---
name: subagents-reference
description: CC subagents — how the Task tool spawns isolated agent instances with scoped tools and context.
layer: reference
cc_feature: subagents
source: https://docs.claude.com/en/docs/claude-code/sub-agents
concept: task-tool-delegation
last_verified: 2026-04-18
ngram_overlap_score: null
review_status: approved
---

# Subagents — Reference

Subagents are fresh Claude instances spawned via the Task tool. Each
receives a task prompt, a tool subset, and no memory of the parent
conversation except what the parent explicitly passes. They return a
single final message to the parent.

## Anatomy

A subagent has:

- **A name** — either a built-in type (`general-purpose`, `Explore`,
  `Plan`) or a plugin-defined type (`code-reviewer`, `test-runner`,
  ...).
- **A system prompt** — defined by the agent type. The parent cannot
  override it.
- **A tool set** — subset of the parent's tools, as declared in the
  agent definition's frontmatter `tools:` field.
- **A task prompt** — what the parent asks it to do. Self-contained;
  the subagent has no access to prior messages.
- **A model** — either explicit in the agent definition (`model: opus |
  sonnet | haiku`) or inherited from the parent.

## How to define a subagent

A plugin agent is a markdown file in `agents/` with frontmatter:

```yaml
---
name: code-reviewer
description: <when to invoke, include examples>
model: sonnet
tools: ["Read", "Grep", "Glob"]
---

<system prompt content>
```

The `description` field is how Claude decides when to spawn this
subagent. Include concrete trigger examples.

## How to invoke

Parent calls the `Task` / `Agent` tool with:

- `subagent_type` — the agent's name
- `description` — short label for logs
- `prompt` — the self-contained task

Optional:

- `run_in_background: true` — agent runs in the background; parent
  is notified on completion.
- `isolation: "worktree"` — agent runs in a temporary git worktree
  (isolated copy of the repo).

## Return protocol

- Foreground agent: parent blocks until the agent returns. Return value
  is a single text message.
- Background agent: parent continues. On completion, the harness
  injects a notification into the parent's next turn.

## Isolation guarantees

- No conversation history sharing. Each subagent starts cold.
- Separate context window. A subagent can read large files without
  polluting the parent's context.
- Separate tool permissions. A subagent with only `Read` tools cannot
  write files, even if the parent can.

## Cost and latency

- Every subagent call is a full model call with its own token budget.
- Model choice matters: Sonnet is ~5× cheaper than Opus; Haiku is
  cheaper still but cannot be used (per project policy).
- Parallel subagents: the parent can launch multiple in one message;
  the harness runs them concurrently. Total latency ≈ slowest agent.

## Failure modes

- Subagent hits context limit → partial or missing return.
- Subagent runs in background and the parent conversation ends → result
  may be orphaned.
- Subagent's return message hallucinates file paths → caller must
  verify.