HowToCodePage

Subagents and context isolation

Delegate a search or a review to an agent with its own context window and a restricted tool set, and get a summary back instead of a transcript.

The point is the separate window

A subagent runs in its own conversation with its own context window. It reads files, greps, and explores, and returns only a final message to the parent. Everything it read in between stays out of your main session - which is exactly the value when the task is 'find where this is handled' across a large repository.

---
name: code-reviewer
description: Reviews a diff for correctness, security and missing tests. Use after writing or changing code.
tools: Read, Grep, Glob, Bash(git diff:*)
model: sonnet
---

You are a strict reviewer. You do not edit files.

Given a diff or a file list:
1. Read the changed files and enough surrounding code to judge them.
2. Report findings as a list, most severe first.
3. For each finding give file:line, what is wrong, and the smallest fix.
4. If a change has no test covering it, say so explicitly.

End with a one-line verdict: SHIP, FIX FIRST, or REWORK.
  • tools restricts what the subagent can do - a reviewer with no Edit or Write cannot quietly change the code it is judging.
  • description is how the parent decides to delegate, so write it as a trigger, not a job title.
  • Subagents are stored in .claude/agents (project) or ~/.claude/agents (personal).
  • A subagent cannot spawn further subagents, which keeps delegation one level deep and predictable.

Invoking and designing them

# list and manage definitions
/agents

# delegate explicitly
> use the code-reviewer subagent on the staged diff

# fan out deliberately: several independent searches in parallel
> use three subagents to locate the rate limiter, the retry policy and the timeout config
Task shapeGood subagent?Why
Broad search across an unfamiliar repoYesHuge read volume, tiny answer
Independent parallel researchYesWall-clock time drops
Focused review of a diffYesIsolated judgement, restricted tools
Tiny edit in one known fileNoDelegation costs more than doing it
Anything needing your whole conversationNoThe subagent cannot see it
⚠️
A subagent starts with none of your conversation. Anything it needs - the failing output, the constraint, the file list - has to be in the delegation prompt. Vague delegation produces a vague summary that you then have to redo yourself.

Concurrency and cost

---
name: migration-auditor
description: Audit a directory for patterns that block a framework migration.
tools: Read, Grep, Glob
model: haiku
---

Audit the path given in the task. Report only files that need manual changes,
each as: path, line, pattern found, suggested replacement.
Do not explain the migration. Do not read test fixtures.
  • Parallel subagents multiply token spend - each has its own system prompt and tool definitions.
  • A cheap model is often enough for search and audit work; reserve the strong model for judgement.
  • Keep the return contract short and structured: a table or a list you can act on, not prose.
  • Because the parent only stores the summary, a subagent-heavy session stays healthy far longer than one that reads everything inline.

The practical rule: delegate when the work is high-volume, self-contained and produces a small answer. Do it inline when the work needs the context you already have.

FAQ

Do subagents share my permissions?
They run within the same permission mode and settings, further narrowed by their tools list. A subagent cannot grant itself more than the session already has, but a permissive session plus a permissive tool list is still a permissive subagent - restrict tools explicitly.
Why did my subagent return almost nothing?
Usually the delegation prompt was too thin or its description did not match the request, so it did not know what to look for. Restate the task with the specific path, the exact question and the output format you want.

Scoped instructions: memory, rules and path-specific context Skills, plugins and marketplaces

Last refreshed 2026-09-18.