03 / 20Agents7 MIN READ

Subagents

A subagent is a second Claude instance that runs a delegated task in its own context window with its own system prompt and tool list, and returns a single text result to the conversation that spawned it.

What it is

When Claude calls the Agent tool, Claude Code starts a fresh conversation with its own context window, its own system prompt, and its own tool set. That subagent works the task through on its own and returns one text result. The parent never sees the intermediate tool calls or their output, only the final answer. This is the whole point: forty file reads happen somewhere your conversation does not pay for them.

Claude Code ships several built-in subagents. Explore is read-only and optimised for search; Write and Edit are denied and it skips your CLAUDE.md files to stay fast. Plan does the same job during plan mode. general-purpose gets every tool available to subagents and handles multi-step work that both explores and modifies. You add your own as markdown files with YAML frontmatter in .claude/agents/ or ~/.claude/agents/.

As of v2.1.198, subagents run in the background by default; Claude runs one in the foreground when it needs the result before continuing. A background subagent keeps every MCP tool but a reduced set of built-in tools, so the same definition can resolve to different tools depending on where it runs.

What it does for you

It stops research from evicting your work. A "find every call site of this function" task can read fifty files; in the main conversation that is fifty files of context you never reference again.
It enforces a boundary a prompt cannot. A reviewer subagent with tools: Read, Grep, Glob physically cannot edit your code, whatever it decides it should do.
It runs independent work at the same time. Three reviewers looking at security, performance, and accessibility are three separate context windows filling in parallel rather than three sequential passes through one.

How it works

01Claude matches a task against subagent descriptions
The description field is what Claude reads when deciding to delegate, the same way a skill description works. You can also name one explicitly: "use the code-reviewer agent on this diff".
02Claude Code resolves the subagent’s tools
With neither tools nor disallowedTools set, the subagent inherits every tool available to subagents. With tools set it gets only those. disallowedTools wins over tools when both list the same entry.
03Two filters narrow that set further
Every subagent loses AskUserQuestion, EnterPlanMode, EndConversation, ScheduleWakeup, TaskOutput, WaitForMcpServers, and Workflow. A subagent running in the background additionally keeps only the file, shell, web, and skill tools.
04The subagent starts with its own system prompt
The markdown body of the definition becomes the system prompt, plus basic environment details. It does not receive the full Claude Code system prompt, the parent conversation, or the parent’s auto memory.
05Permissions are checked per tool call, not at spawn
Launching a subagent does not prompt. Each tool call the subagent makes is checked against your rules as it happens. Background subagents surface those prompts in your main session, naming which subagent is asking.
06One text result returns to the parent
The parent sees the final answer and nothing else, which is why a subagent instruction should end by stating exactly what to report back. The subagent also builds its own prompt cache rather than reading the parent’s, so its first call has no cache hits.

How to implement it

01Create the definition file
Write .claude/agents/<name>.md for a project subagent teammates share, or ~/.claude/agents/<name>.md for a personal one. Only name and description are required.
02Write the description as a delegation trigger
State when Claude should hand work to this subagent, not what the subagent is. "Use after code changes to review a diff for security issues" beats "Security expert".
03Restrict the tool list to the job
A reviewer gets tools: Read, Grep, Glob. Leaving Bash off a subagent is a stronger guarantee than telling it not to run commands.
04Pick a model deliberately
Set model: haiku for cheap mechanical scans, model: sonnet for review, or omit it to inherit the main conversation’s model. A blocked value falls back rather than failing.
05Isolate it if it writes files in parallel
Add isolation: worktree so the subagent gets its own git worktree, branched from your default branch. Claude Code removes the worktree automatically when the subagent makes no changes.

Examples

.claude/agents/security-reviewer.mdmarkdown

---
name: security-reviewer
description: Reviews a diff for injection, authentication, authorization, and data-exposure defects. Use after code changes that touch request handling, auth, or persistence.
tools: Read, Grep, Glob, Bash
model: sonnet
color: red
maxTurns: 30
---

You review code for security defects. You never edit files.

Run `git diff origin/main...HEAD` to get the change under review, then read the
surrounding code for every file it touches. A diff alone does not show whether
an input was already validated upstream.

Check, in this order:

1. Untrusted input reaching a query, a shell command, a path, or a template
2. Authorization checks that are missing, or present but after the side effect
3. Secrets, tokens, and personal data entering logs, error messages, or responses
4. Session, cookie, and CORS configuration changes
5. New dependencies, and any change to how one is invoked

Report only defects you can point at. For each one give the file and line, the
concrete input that triggers it, what an attacker gets, and the smallest fix.
Rank them most severe first. If the diff is clean, say so in one line and stop —
do not pad the report with observations.

One of three read-only reviewers. Copy the shape for the performance and accessibility variants, changing only the description, the checklist, and the colour.

Running the three reviewersbash

# In an interactive session, ask for all three at once:
#   "Review this branch with the security-reviewer, performance-reviewer,
#    and accessibility-reviewer agents."
#
# Watch them and stop one that is going nowhere:
/tasks

# Or define them for a single scripted run, without files on disk:
claude -p "Review the staged diff for security issues" --agents '{
  "security-reviewer": {
    "description": "Reviews a diff for security defects.",
    "prompt": "You review code for security defects. You never edit files.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

Each reviewer fills its own context window; your conversation receives three summaries.

Use it when

Searching a large codebase for every call site or usage pattern, where the reads are worthless once summarised.
Running several review passes over the same diff at once, each with its own lens and its own context window.
Applying a mechanical refactor across many files with isolation: worktree, so parallel edits cannot collide.
Routing cheap classification work to model: haiku while the main conversation stays on a larger model.
Reading a large log or test output to extract the three lines that matter, keeping the rest out of your session.

Avoid it when

The task needs the conversation so far. A subagent starts fresh: it gets its system prompt and your task description, not your history, so re-explaining costs more than doing the work inline.
You need to iterate on the result. Each round trip is a fresh context window that re-reads everything, which is slower and more expensive than staying in one conversation.
The task is small. A single file read returns faster inline than the spawn, run, and summarise cycle of a subagent.
Two subagents would edit the same files. Without isolation: worktree their writes interleave and the last one wins.

Common mistakes

SYMPTOMThe subagent returns a vague summary and you have to ask follow-up questions you cannot direct at it.
FIXEnd the system prompt with the exact output contract: which fields, in what order, and what to do when there is nothing to report. The parent only ever sees that final text.
SYMPTOMA subagent edits files you expected it to leave alone, despite the prompt saying not to.
FIXSet tools: Read, Grep, Glob in the frontmatter. Tool lists are enforced by Claude Code; instructions in the body are not.
SYMPTOMRewinding with /rewind does not undo a subagent’s edits.
FIXCheckpointing does not capture subagent edits except for a foreground forked skill. Use git to revert them, and commit before delegating write work.
SYMPTOMA subagent that works in the foreground loses tools when Claude runs it in the background.
FIXBackground subagents keep only a reduced built-in tool set. Set background: false in the frontmatter if the definition depends on a tool outside that set.
SYMPTOMTwo parallel subagents refactor the same files and the result is a mess.
FIXAdd isolation: worktree to each definition so every subagent gets an isolated checkout, then merge the branches yourself.

Best practices

Delegate work whose output you will not reference again, and keep work you will iterate on in the main conversation.
Give every subagent the narrowest tool list that lets it finish, and leave Bash off read-only agents.
State the return format explicitly at the end of the system prompt, since the single text result is all the parent gets.
Set maxTurns on any subagent that could loop, so a stuck agent stops instead of burning the session.
Use isolation: worktree whenever more than one subagent writes files.
Watch long-running delegations with /tasks and stop the ones that are not converging.

Try it in five minutes

Create a read-only reviewer subagent and confirm its tool restriction is real.

1.Create .claude/agents/doc-reviewer.md with name, a description like Reviews markdown docs for broken links and stale commands. Use when the user asks to check documentation., and tools: Read, Grep, Glob.
2.Start claude and ask: "Use the doc-reviewer agent to check README.md."
3.Watch the transcript: you get one summary row, not the file reads.
4.Now ask: "Have the doc-reviewer agent fix the problems it found." It cannot — Edit is not in its tool list.
5.Run /context before and after and compare: the review cost you a summary, not the files.

Verified against code.claude.com/docs/en/sub-agents on 2026-08-09. See content/SOURCES.md for the full table.

← / → MOVE BETWEEN CONCEPTS