Sub-Agents: The Context-Isolation Primitive
The first move of the coordination axis — a sub-agent is isolation, not capability. A fresh window that inherits nothing and returns only the relevant result; the fresh-in / result-only-out contract that makes it composable; separation of concerns; roles as description plus system prompt plus scoped tools; and when the isolation earns its keep versus when it is pure overhead.
On this page
The spine’s second axis was coordination, and its reframing was sharp: a new unit of work is not a new skill, it is a fresh window. This chapter develops the primitive that embodies that — the sub-agent. Everything here follows from one claim the rest of the chapter unpacks: a sub-agent’s value is the separate context window, not any capability the model otherwise lacks. Get that backwards and you reach for a sub-agent to “make the model smarter”; get it right and you reach for one to quarantine context.
Isolation, not capability
Start from what a sub-agent is, because the common mental model — “a helper that can do something the main agent can’t” — is wrong and leads to misuse. Across Anthropic’s own descriptions the sub-agent is defined by its isolation, not by any new ability. It is, plainly, “an isolated Claude instance with its own context window.” [Official] How and when to use subagents in Claude Code · Anthropic (2026)T1-official original When a side task would otherwise flood the main conversation, “the subagent does that work in its own context and returns only the summary.” [Official] Create custom subagents · AnthropicT1-official original And from the caller’s side the isolation is total: “The subagent works in its own separate context window. None of its file reads touch yours.” [Official] Explore the context window · AnthropicT1-official original
So the value is the window, not the worker. A sub-agent runs the same model you already have; what it adds is a clean, separate place for that model to do focused work whose verbose middle never lands in your conversation.
The contract: fresh in, relevant result only out
Isolation is only composable if the boundary is well-defined in both directions, and it is. On the way in, a sub-agent inherits nothing: “Each subagent starts fresh, unburdened by the history of the conversation or invoked skills.” [Official] How and when to use subagents in Claude Code · Anthropic (2026)T1-official original The SDK is precise about how fresh: a sub-agent “runs in its own fresh conversation” [Official] Subagents in the SDK · AnthropicT1-official original and does not receive the parent’s conversation history, tool results, or system prompt — the only channel from parent to sub-agent is the prompt string you pass it. On the way out, the return is equally narrow: “only its final message returns to the parent” [Official] Subagents in the SDK · AnthropicT1-official original — every intermediate tool call and result stays inside the sub-agent.
There is one deliberate exception, and naming it sharpens the rule. Fork mode (fork_session) inverts the input side: it carries the parent’s context into the sub-agent, for cases where the side task genuinely needs the conversation so far. The return contract is unchanged — still only the final message comes back. The configuration mechanics of fork mode belong to the SDK reference, not here; what matters for design is that the default is fresh, and fork is the explicit opt-out when isolation-on-input would cost you more than it saves.
Isolation buys separation of concerns
Why is a separate window worth the trouble? Because it makes each unit of work independent and non-interfering. Anthropic’s multi-agent write-up names the payoff directly: a sub-agent “provides separation of concerns—distinct tools, prompts, and exploration trajectories—which reduces path dependency and enables thorough, independent investigations.” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original Sub-agents “facilitate compression by operating in parallel with their own context windows,” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original each compressing its slice of the work rather than sharing one crowded window.
The separate window is not just hygiene, then — it is the property that makes the next move (assigning roles) possible. Two investigations in one window contaminate each other’s reasoning; the same two in separate windows stay clean.
Roles: description + system prompt + scoped tools
If isolation gives you independent units, a role is how you specialize one. A role is not a new mechanism — it is three ordinary knobs set deliberately: a description, a system prompt, and a scoped tool set. The docs make the tool-scoping explicit (“limiting which tools a subagent can use” [Official] Create custom subagents · AnthropicT1-official original ) and the design principle blunt: “each subagent should excel at one specific task.” [Official] Create custom subagents · AnthropicT1-official original
The most productive role decomposition the sources demonstrate is generate-then-verify — focused generators plus a separate reviewer. Claude Code’s code review runs it concretely: “Each agent looks for a different class of issue,” [Official] Code Review · AnthropicT1-official original and then “a verification step checks candidates against actual code behavior to filter out false positives.” [Official] Code Review · AnthropicT1-official original The product announcement says the same in plainer words — the agents “look for bugs in parallel” [Official] Bringing Code Review to Claude Code · Anthropic (2026)T1-official original and then “verify bugs to filter out false positives.” [Official] Bringing Code Review to Claude Code · Anthropic (2026)T1-official original
When a sub-agent earns its keep
Isolation is not free, and the honest rule is a tradeoff, not a default-on. The benefit side: delegating verbose work (running tests, fetching docs, processing logs) keeps that output in the sub-agent so “only the relevant summary returns to your main conversation,” [Official] Create custom subagents · AnthropicT1-official original and the multi-agent architecture “distributes work across agents with separate context windows to add more capacity for parallel reasoning.” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original The cost side, stated just as plainly: “Subagents start fresh and may need time to gather context” [Official] Create custom subagents · AnthropicT1-official original — a latency hit — and the task’s value “must be high enough to pay for the increased performance.” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original
The quantified side of that cost — how many more tokens, how much more latency — is the Operations volume’s subject; this chapter asserts the tradeoff qualitatively and leaves the numbers to where they can be measured.
Patterns
Quarantine verbose work. Sketch: delegate high-volume, low-relevance work (tests, doc fetches, log scans) to a sub-agent; keep only the summary. When to use: any side task whose output would crowd the main window. Create custom subagents · AnthropicT1-official original Mechanics: pass a focused prompt; the sub-agent’s verbose middle stays in its window, only the final message returns. Remember: the win is the quarantine, not the work — the main agent could do it, just not without the noise.
Clean-room verify. Sketch: generate with one (or several) focused sub-agents, then review with a separate verifier. When to use: anything where self-evaluation would inherit the generator’s blind spots. Code Review · AnthropicT1-official original Mechanics: focused generators look for distinct issue classes; a verifier checks candidates against actual behavior to filter false positives. Remember: the verifier is separate on purpose — a fresh window has no stake in the path it reviews.
Scope the role, not just the prompt. Sketch: define a role by description + system prompt + a deliberately limited tool set. When to use: whenever a sub-agent should excel at one task and not wander. Create custom subagents · AnthropicT1-official original Mechanics: allowlist/denylist its tools; one task per sub-agent. Remember: the tool scope is part of the role — an unscoped sub-agent is an unfocused one.
Default fresh, fork on purpose. Sketch: let sub-agents start fresh; use fork_session only when the task genuinely needs the parent’s context. When to use: fork when re-gathering context would cost more than carrying it in. Subagents in the SDK · AnthropicT1-official original Mechanics: fresh is the default (one prompt string in); fork inverts the input side, return unchanged. Remember: fork trades isolation-on-input for context — reach for it deliberately, not by habit.
Quick reference
- What it is: an isolated instance with its own context window — isolation, not capability. How and when to use subagents in Claude Code · Anthropic (2026)T1-official original
- The contract: fresh in (one prompt string; no inherited history/tools/system prompt), relevant-result-only out (final message only). Subagents in the SDK · AnthropicT1-official original
fork_session: the deliberate inversion of the fresh-start default (carries parent context in; return unchanged).- Why isolate: separation of concerns — distinct tools/prompts/trajectories, non-interfering. How we built our multi-agent research system · Anthropic (2025)T1-official original
- Roles: description + system prompt + scoped tools; the productive split is generate-then-verify with a clean-room reviewer. Code Review · AnthropicT1-official original
- When: quarantine context / parallelize / clean-room review. When not: latency dominates, or task value doesn’t clear the cost. How we built our multi-agent research system · Anthropic (2025)T1-official original (Quantified cost → the Operations volume.)
Practice
Exercise solutions
The error is treating a sub-agent as added capability — it is the same model with no extra ability, so it will get the hard math wrong in its own window just as the main agent does. What a sub-agent actually adds is context isolation: a fresh, separate window. A sub-agent could legitimately help the math task only under an isolation framing, not a capability one — e.g. a clean-room verifier that checks the main agent’s answer against actual computation (running code, not re-deriving by hand), where the value is the independent check in a window with no stake in the original derivation, or quarantining a verbose symbolic-computation step so its output doesn’t flood the main thread. The reframing is the whole lesson: “make it smarter” is the wrong reason; “isolate or independently check” is the right one.
A representative pass. Should be a sub-agent: “summarize the 2,000-line dependency-audit log.” It quarantines a large, low-relevance output — the sub-agent reads the log in its own window and returns only the few findings that matter, so the main conversation never carries the 2,000 lines. It should run fresh (fork_session off): the task needs only the log, not the conversation so far, so carrying parent context in would cost window for no benefit. Should not be a sub-agent: “fix the typo in the function we’re editing.” It needs context the main agent already holds, the output is trivial, and a fresh sub-agent would pay startup latency to re-gather what’s already in hand — pure overhead. The decision turned on context to isolate (lots, in the first; none, in the second), exactly as the contract predicts — never on whether a sub-agent could do it.