Chapter 04 · Section I · 12 min read
What subagents are, and why
A subagent is a fresh instance of Claude with its own context and its own toolset, spawned by the main session to do a bounded task. Getting the mental model right — think "delegate a sub-task to a new hire" — is what separates using them well from using them poorly.
Every session of Claude Code has a main conversation — the one you are typing into. That conversation has a memory of everything you have discussed, and a context window that fills up as you keep going. A subagent is a second, temporary conversation that the main session can spawn to handle a specific task. When it finishes, only its final summary comes back into the main thread. Nothing else.
The core insight
You can think of the main session as your desk and a subagent as a scratch pad someone else works on. The person doing the scratch work does not need your entire day’s history to be useful — they need the specific task, the relevant background, and a clear format for what to bring back. When they hand you the result, your desk is unchanged except for one more piece of paper.
Two properties fall out of this:
- Isolation. A subagent’s exploration does not clutter the main context. If your Explore agent grepped fifty files, you never see those fifty file bodies — you see the paragraph summarising what it found.
- Delegation cost. Spawning a subagent starts a fresh model with no memory of your session. Whatever it needs to know has to be in the briefing prompt.
When they earn their keep
Subagents shine when the task is broad, the raw output is voluminous, and the main conversation only needs the conclusion.
Good candidates:
- “Where in the codebase is X handled?” — Explore agent greps and reports.
- “Read these five long PDFs and summarise their positions on Y.” — a general-purpose agent reads and returns bullets.
- “Given this design goal, sketch a migration plan.” — a Plan agent thinks; you get the plan back.
When they are the wrong tool
Not everything wants a subagent. If the task is small and known, the round-trip cost outweighs the benefit.
Bad candidates:
- “Read
src/foo.tsand tell me what it does.” — you can Read that file yourself in the main session in one call. - “Change the return type of this one function.” — same.
- Anything you can do in one Grep and one Edit should stay in the main session.
The nature of the summary
Subagents return one message. That message is the agent’s summary of what it did and what it found. Two things follow:
- The main conversation trusts the summary, but should verify claims that matter. If the agent said “there are no other callers of
parseInvoice”, and you are about to delete the function based on that, run a Grep in the main session too. - You should ask for the summary format you want. “Return a punch list of file paths and one-line notes” produces a very different reply from “explain what you learned.”
Check your understanding
Quick check
—