Subagents

1 · Why subagents essential

Start with the failure you've probably watched happen. You give one agent a big job — "audit this codebase for security issues" — and it dutifully starts reading. File after file streams into its context: the whole auth module, three dead-end configs, a pile of grep output. By the time it's ready to actually reason about the bug on line 12, its memory is stuffed with a thousand details that no longer matter, and the useful signal is drowning in the noise it gathered getting there. The agent didn't get dumber; its workspace got cluttered.

Here's the mental model that fixes this: an agent's context is a desk, not a filing cabinet. It's small, it's where all the thinking happens, and everything you pile on it competes for the same limited surface. A single agent doing everything has to keep every scrap of every subtask on that one desk at once. That's the core problem subagents solve — not "the agent can't do the work," but "the agent can't do the work and keep a clean desk at the same time."

Think of how a good manager delegates. You don't ask your researcher to narrate every article they skimmed — you ask them to go read the pile and come back with a one-paragraph summary. You get the conclusion without inheriting the process. A subagent is exactly that: a colleague with their own desk, who does the messy reading in their own room and hands you back only the answer.

A single agent doing everything fills its context with detail irrelevant to the next step. A subagent is a specialized agent the main session delegates to: its own prompt, tools, model, and — crucially — its own context. It does a job and returns just the conclusion, keeping the main thread clean.

The mistake to name up front, because the rest of this chapter keeps circling back to it: once delegation feels good, the temptation is to delegate everything. But every subagent is a fresh colleague you have to brief from scratch and wait for — it starts with a blank desk and costs you a round trip. Spin one up for a two-line edit and you've hired a contractor to change a lightbulb. The skill isn't "delegate more"; it's knowing which jobs are worth the hand-off and which the main agent should just do itself. Hold that tension as you read on — you'll meet it formally as the over-delegation anti-pattern in §6.

2 · Context isolation, quantified essential

"Keeps the context clean" sounds nice but vague — so let's put a number on it, because the number is genuinely startling. In §1 we argued isolation matters; here you'll feel how much. The claim is simple: whether a subtask costs you 100 tokens or 8,000 tokens of your main agent's precious desk space is entirely a choice about where the work happens.

Recall why this is life-or-death for a long task. A context window is a hard ceiling — a fixed number of tokens the model can hold at once. Do six file-heavy subtasks inline and each one's full material (every file read, every intermediate thought) stacks up in that one window until you hit the wall and the agent starts forgetting the beginning of its own job. Do them as subagents and only the conclusions come home. The subagent burns through 8,000 tokens of reading in its own throwaway window; your main agent receives three lines.

The analogy that makes it click: it's the difference between a colleague forwarding you every email in a 200-message thread versus forwarding you the one-line decision at the end. Same information reaches you either way — but one buries your inbox and the other respects it. Isolation is just deciding the intermediate mess stays in their inbox.

The subagent reads a hundred files and returns three lines; the main agent never sees those files — only the answer. That isolation is what lets long, complex work fit in a context window.

Where people trip: they assume delegation must be slower because it's "more agents" — and forget that the main agent's context is the scarce resource, not the raw compute. The subagent still does all 8,000 tokens of work; you just don't carry it. The lab below runs the arithmetic both ways so the ~10× gap isn't a slogan but a figure you watched compute.

isolation.pydef context_used(main_tokens, subtasks, tokens_per_subtask, inline):
    """inline=True: everything in the main context. inline=False: subagents isolate."""
    if inline:
        return main_tokens + subtasks * tokens_per_subtask       # all piled in
    return main_tokens + subtasks * 100                          # only the conclusions return

print("6 file-heavy subtasks, inline:  ", context_used(2000, 6, 8000, True), "tokens")
print("6 file-heavy subtasks, delegated:", context_used(2000, 6, 8000, False), "tokens")
print("delegation keeps the main thread ~10x leaner")

6 file-heavy subtasks, inline:   50000 tokens
6 file-heavy subtasks, delegated: 2600 tokens
delegation keeps the main thread ~10x leaner

3 · Define a subagent intermediate

Here's the pleasant surprise: a subagent isn't a program you write, it's a job description you write. If you've been picturing threads, queues, and orchestration code, relax — defining a subagent is closer to writing a really good hiring brief than to writing software. You describe who this helper is, when to call them in, what they're allowed to touch, and how you want them to work. The system does the spinning-up.

Concretely, it's a plain Markdown file, and it has exactly two parts. The front-matter — the little block fenced by --- lines at the top — is the metadata: a name, a description of when to use it, the tools it's allowed to use, and optionally which model runs it. Everything below that block is the body, and the body is the subagent's system prompt — its standing instructions, its personality, its rules of engagement. That's the whole anatomy.

The description field earns special attention because it does more than document. It's the part the main agent reads to decide, on its own, when to hand a job to this subagent — so "Reviews a diff for bugs. Use proactively after code changes" isn't a comment, it's the trigger that makes delegation automatic instead of something you have to request every time. A vague description is a subagent that never gets called.

A subagent is a markdown file with front-matter: a name, a description of when to use it, its allowed tools, and optionally a model. The body is its system prompt.

The common mistake here is generosity with tools. It feels helpful to give a new subagent the full toolbox "just in case" — but a reviewer that can edit is a reviewer that might silently rewrite your code while you asked it to look. The safe instinct is the opposite: hand each subagent only the tools its one job actually requires (a reviewer needs Read and Grep, not Edit or git push). A narrow tool list isn't a limitation you're grudgingly accepting; it's a guardrail you're deliberately installing, and it's exactly the least-privilege idea the callout below drives home.

code-reviewer.md---
name: code-reviewer
description: >
  Reviews a diff for bugs and security issues. Use proactively after code
  changes, or when the user asks for a review.
tools: [Read, Grep, Bash]
model: sonnet
---
You are a focused code reviewer. Given a diff:
- Find correctness bugs, edge cases, security issues (injection, secrets, authz).
- Cite file:line. Group by severity. Be terse — no praise, no restating code.
- Return ONLY the findings; the main agent will act on them.

4 · Advanced — delegate and parallelize advanced

So far isolation has been about keeping your desk clean. Now it pays a second dividend — and it's the one people actually get excited about: speed. Because each subagent works in its own sealed context, they don't step on each other. And things that don't step on each other can happen at the same time.

Picture reviewing six modules. Done inline, the one agent grinds through them like a single checkout lane at a supermarket — module one, then two, then three, everyone waiting in a line thirty seconds long apiece. Fan the work out to subagents and you've opened six lanes: the reviews run side by side, and your total wait collapses from "the sum of all of them" to "roughly the slowest one." That shift — from a sum to a max — is the whole prize, and it's why "review these 6 modules" is the textbook case for parallel delegation.

The reason this works cleanly with subagents (and would be a nightmare with one shared context) is precisely the isolation from §2. Six agents writing into one desk would trample each other's notes; six agents each with their own desk simply can't. Independence is what unlocks parallelism — you get the speedup for free because you already paid for isolation.

Because each subagent has its own context, you can run several in parallel — the biggest speedup for wide tasks ("review these 6 modules"). Model the wall-clock win.

Two honest caveats, so the win doesn't turn into a trap. First, "parallel" only helps for genuinely independent work — if step three needs step two's answer, no amount of lanes will let you skip the queue; dependent steps still run in order. Second, you rarely get infinite lanes: there's a workers limit, so ten tasks with four workers run in waves, and your speedup caps at "however many waves you need." The model in the lab below makes both effects visible — watch the parallel time stop improving once every task fits in one wave.

parallel.pydef wall_clock(tasks_secs, parallel, workers=4):
    if not parallel:
        return sum(tasks_secs)                       # one after another
    # parallel: time = ceil(n/workers) * slowest-in-a-wave (approx with equal tasks)
    import math
    waves = math.ceil(len(tasks_secs) / workers)
    return waves * max(tasks_secs)

tasks = [30, 30, 30, 30, 30, 30]                     # 6 module reviews, 30s each
print("serial:  ", wall_clock(tasks, parallel=False), "s")
print("parallel:", wall_clock(tasks, parallel=True, workers=4), "s")

serial:   180 s
parallel: 60 s

5 · Advanced — fan-out / verify / synthesize advanced

Parallel fan-out is fast — but speed without a safety check is how you ship confident nonsense. Six reviewers running at once will happily return six findings, and some of those findings will be wrong: a false positive, a misread, a "bug" that isn't. If you pipe all six straight into your answer, you've just parallelized your mistakes. This section adds the missing step that turns raw breadth into trustworthy breadth.

The pattern has a shape worth memorizing because you'll reuse it everywhere: fan out, verify, synthesize. Fan out to gather cheaply and in parallel; run a separate verifier subagent that tries to refute each finding; then synthesize only the survivors into one answer. It's the difference between a newsroom that prints every tip and one that runs each tip past a fact-checker before it goes to press — the fact-check is what makes the front page worth reading.

The single most important rule — and the one people quietly skip — is that the verifier must be a different agent from the one that gathered. Why? A gatherer checking its own work inherits its own blind spots; it already "believes" its finding and will rationalize it. A fresh subagent with its own context and no stake in the result approaches each claim as a skeptic. Independence isn't a nice-to-have here; it's the entire source of the check's value. Ask someone to grade their own exam and you know what you'll get.

A powerful pattern: split work, run a subagent per unit in parallel, have a verifier subagent adversarially check each finding, then synthesize survivors. Model the flow.

The coordination trap to watch: this pipeline has three stages and a real temptation to add more — a verifier for the verifier, a meta-synthesizer, a committee. Resist it. Each extra stage is another round trip, another hand-off, another chance for the signal to get garbled in translation, and the returns fall off fast. The elegance of fan-out/verify/synthesize is that three roles are usually enough: one to gather, one independent skeptic to filter, one to combine. The lab below models the flow with plain functions so you can see each stage do its job before any real API is involved.

The fan-out workflow

1. Main splits the work into independent units (per module/file/option).
2. A subagent per unit runs in parallel, each returning a structured finding.
3. A verifier subagent adversarially checks each finding ("try to refute this").
4. Main synthesizes the surviving findings into one answer.

fanout.pydef review_module(name):                    # a 'subagent' returning findings
    fake = {"auth": ["hardcoded secret"], "billing": ["float money bug"], "search": []}
    return [{"module": name, "issue": i} for i in fake.get(name, [])]

def verify(finding):                        # a verifier subagent: is it real?
    return "secret" in finding["issue"] or "money" in finding["issue"]

modules = ["auth", "billing", "search"]
raw = [f for m in modules for f in review_module(m)]     # fan-out
confirmed = [f for f in raw if verify(f)]                # verify
print("raw findings:", len(raw), "| confirmed:", len(confirmed))
for f in confirmed: print("  -", f["module"], ":", f["issue"])

raw findings: 2 | confirmed: 2
  - auth : hardcoded secret
  - billing : float money bug

6 · Professional — when NOT to delegate professional

This is the section that separates people who use subagents from people who overuse them. Everything so far has sold you on delegation, and it works — which is exactly why the failure mode is enthusiasm. The engineer who just discovered subagents starts routing every task through one, and their agent gets slower and more expensive while feeling more sophisticated. Knowing when not to delegate is the more valuable half of the skill.

Remember the cost you keep forgetting: a subagent is a new colleague with a blank desk. Every delegation pays a fixed tax — you brief them from nothing, they spin up their own context, and you wait for the round trip. For a big, independent, exploration-heavy job that tax is trivial next to the isolation and parallelism you gain. For a one-line edit, the tax is the whole job — you spent more coordinating the hand-off than the work itself took. It's hiring a contractor, waiting for them to arrive, and briefing them, all to change a lightbulb you were standing next to.

There's also a disqualifier that overrides everything else, and it's the one beginners miss: if the task needs the parent's in-progress working state, you cannot delegate it — full stop, regardless of size. The subagent starts blank; it literally cannot see what the main agent is halfway through. Ask it to "finish the refactor I started" and it has no idea what you started. Shared context isn't a preference here; it's a hard wall.

Subagents add latency and cost (each spins up its own context). Delegate when work is genuinely independent or context-heavy; for a quick edit, the main agent is faster. Over-delegation is a real anti-pattern.

So the rule of thumb worth internalizing: delegate for breadth and isolation (independent work, heavy exploration, things you'd rather keep off the main desk); stay inline for small, sequential, or context-bound work. The little decision function below encodes exactly that priority order — quick-edit bails first, then the genuinely-worth-it cases, then the default "not worth the spin-up." Read it as the checklist you'll run in your head before every hand-off.

delegate_decision.pydef should_delegate(independent, context_heavy, quick_edit):
    if quick_edit: return False, "trivial — main agent is faster"
    if independent and context_heavy: return True, "isolate + parallelize"
    if context_heavy: return True, "isolate to keep main context clean"
    return False, "not worth the spin-up overhead"

for case in [(True,True,False),(False,True,False),(False,False,True),(False,False,False)]:
    print(case, "->", should_delegate(*case))

(True, True, False) -> (True, 'isolate + parallelize')
(False, True, False) -> (True, 'isolate to keep main context clean')
(False, False, True) -> (False, 'trivial — main agent is faster')
(False, False, False) -> (False, 'not worth the spin-up overhead')

7 · Tech-lead — a subagent library + composition tech-lead

Up to now you've been defining subagents one at a time, for yourself. A tech lead thinks one level up: subagents as shared infrastructure. The shift is from "I'll write a reviewer when I need one" to "our team has a reviewer, a researcher, a test-writer, and everyone reaches for the same well-tuned ones." That curated set is a subagent library, and building it is the difference between everyone reinventing a mediocre reviewer and everyone inheriting a great one.

The mental model is a specialist team, not a Swiss-army knife. A hospital doesn't hire one person who does surgery, anesthesia, and billing; it hires narrow experts and an orchestrator who routes each patient to the right one. Your library works the same way: a few sharply-scoped agents (each with least-privilege tools and a right-sized model — a cheap model for search-heavy exploring, a stronger one for verification) plus a selector that picks by task kind. Locate something? Route to the explorer. Confirm a finding? The verifier. Review a diff? The reviewer.

Composition is where it gets powerful, and it ties back to the Skills you met in K4: a subagent can use a Skill to do its job your way. A reviewer subagent that loads your house code-review Skill enforces your standards; a research subagent that loads a "cite sources" Skill always shows its work. The lead who curates both the agents and the Skills they load hands the whole team specialized, house-standard helpers — and that stack is the backbone of the capstone workbench.

A lead builds a library of subagents (reviewer, researcher, test-writer) the team shares, and composes them with Skills (K4): a subagent uses a Skill to do its job your way. This is the backbone of the capstone workbench.

The failure mode at library scale is scope overlap. The moment two agents both plausibly handle "look at this code," your orchestrator's routing becomes a coin flip and the whole system gets unpredictable. A healthy library keeps scopes disjoint — each task kind maps to exactly one agent — and marks the read-only agents as parallel-safe so the fan-out patterns from §4–§5 can lean on them freely. Curating a library is less about adding agents and more about keeping their boundaries clean; an overlapping library is often worse than no library at all.

Without subagent:  main context absorbs 40 files of grep output,
                   3 dead-end reads, and the eventual answer.
                   -> context bloated with search noise.

With subagent:     "Find where auth tokens are validated" runs in a
                   sub-context; it reads 40 files there and returns
                   "validated in src/auth/verify.ts:reviewToken()".
                   -> main context gets the one-line conclusion only.

# .claude/agents/explorer.md
---
name: explorer
description: Read-only code explorer. Use to locate where something is
  implemented across the codebase without editing anything.
tools: Read, Grep, Glob         # no Edit/Write/Bash -> can't change anything
model: claude-haiku-4-5         # cheap model for search-heavy work
---

You locate code. Search broadly, read excerpts, and return the file paths
and symbols that answer the question. Do not modify any file.

tasks = [3, 5, 2, 4]      # seconds each, independent searches

serial   = sum(tasks)                 # 14s — one after another
parallel = max(tasks)                 # 5s  — all at once, wait for slowest
print(f"serial: {serial}s  parallel: {parallel}s  speedup: {serial/parallel:.1f}x")
# serial: 14s  parallel: 5s  speedup: 2.8x

def pipeline(question):
    # 1. FAN-OUT: parallel gatherers, each returns a finding
    findings = [subagent("explorer", q) for q in split(question)]
    # 2. VERIFY: a FRESH subagent that did not gather, checks the findings
    verdict  = subagent("verifier",
                        f"Independently confirm these against the code: {findings}")
    # 3. SYNTHESIZE: the parent combines verified findings into one answer
    return synthesize(findings, verdict)

def should_delegate(independent, exploration_heavy, needs_shared_context):
    if needs_shared_context:
        return "NO — subagent can't see the parent's working state; do it inline"
    if independent and exploration_heavy:
        return "YES — isolate the noise and/or run in parallel"
    return "NO — a single file read or sequential edit is cheaper inline"

print(should_delegate(True, True, False))   # YES (fan-out search)
print(should_delegate(False, False, True))  # NO (needs shared context)
print(should_delegate(False, False, False)) # NO (trivial inline task)

REGISTRY = {
    "explorer":  {"tools": ["Read","Grep","Glob"], "model": "claude-haiku-4-5",
                  "use": "locate code / gather facts, read-only"},
    "verifier":  {"tools": ["Read","Grep"],        "model": "claude-opus-4-8",
                  "use": "independently confirm findings"},
    "reviewer":  {"tools": ["Read"],               "model": "claude-opus-4-8",
                  "use": "review a diff for bugs"},
}

def pick(task_kind):
    return {"locate": "explorer", "confirm": "verifier",
            "review": "reviewer"}.get(task_kind, "explorer")

print(pick("locate"))   # explorer (cheap, read-only, parallel-safe)
print(pick("confirm"))  # verifier (independent, higher model)

Knowledge check check yourself