Sub-Agents

A sub-agent is a model instance your main session spawns to handle a piece of work in its own separate context window, returning only its result. In Claude Code this is the Task tool — the agent dispatches a described job to a helper; you can also define named agents in .claude/agents/ with their own system prompts, tool restrictions, and model choice. The buttons matter less than the concept: sub-agents are how you escape the one-desk limit of lesson 2, and they're the atom from which every orchestration pattern in this course (19, 22, 29, 30) is built. This lesson: the real reason to split, the honest cost, the craft of the delegation brief, and the granularity judgement that decides whether a fan-out helps or thrashes.

The real reason to split (it isn't speed)

The naive pitch is parallelism. The deeper win — the one that pays even when nothing runs concurrently — is context isolation, three ways:

Exploration without pollution. The dirtiest context work is search: finding where something lives means reading eight files that turn out irrelevant. Done in your main session, all eight stay on your desk forever, crowding out real work and diluting attention (lesson 2). Done by a sub-agent, the junk dies with the sub-agent — only the two-line answer returns ("retry logic: src/net/backoff.ts; config: config/http.ts; note it's duplicated in the worker"). This alone makes research-via-sub-agent the correct default in any session you expect to be long, and it's why Claude Code itself reaches for the Task tool when asked open-ended search questions.

Headroom that doesn't shrink with the job. One context reviewing thirty files degrades as it fills. Thirty contexts reviewing one file each never degrade. Splitting makes per-item quality independent of job size — the property that lets pipelines scale past what any single window can hold, and the reason lesson 22 exists.

Independent judgement. A sub-agent doesn't inherit your session's accumulated assumptions, half-decisions, and anchoring. For "second opinion on this design," adversarial review of freshly written code, or grading work against a rubric (lesson 21 leans on this), the blank slate is the feature — you're buying an opinion uncontaminated by the conversation that produced the artifact.

The honest cost

Every sub-agent re-pays the fixed overhead — system prompt, tool definitions, its briefing — from token zero. Fan out to N workers and you buy that overhead N times. The chart on this page shows the shape: total tokens climb well above the single-context cost, and what you get in exchange is that no individual context ever nears its ceiling. That's the trade in one sentence: fan-out spends total tokens to buy per-context headroom — worth it when the job outgrows one window or isolation improves the answer; pure waste when the task would fit comfortably where you already are. "Could this just be one prompt here?" is a question to actually ask; the answer is yes more often than enthusiasm suggests.

Latency and steering are the other costs: a sub-agent is a round trip whose middle you can't interrupt (lesson 6's interrupt-early habit doesn't reach inside it), and its result arrives as a report, not a collaboration. Don't delegate what you need to steer — exploratory design conversations, tasks where you expect to redirect midway, anything where your judgement is part of the loop.

The delegation brief: prompt craft, squared

A sub-agent brief is a prompt (all of lesson 1 applies) with two extra obligations, both consequences of the blank slate:

Complete context, stated. It knows nothing your session knows — not the files you've discussed, not the conventions you've established, not the constraint from an hour ago. The lesson-1 stranger test stops being a metaphor: which files, which patterns, which boundaries, or it guesses. (Named agents in .claude/agents/ help here: their system prompt carries the standing part of the brief so each dispatch only supplies the variable part — lesson 9's command logic, applied to delegation.)

A return contract. You will consume the result in a context that pays per token (lesson 3), so specify shape and size: "return a list of file:line findings, one line each, severity-tagged, no prose preamble." The difference between that and an unshaped ask is a 200-token result versus a 3,000-token essay burying the finding — and skipping the contract is the classic sub-agent mistake, because thirty workers each returning their full working transcript hand your main session the exact context explosion the fan-out existed to prevent. Lesson 22 promotes this from craft tip to design rule (return modes: full, summary, handle), because at orchestration scale it decides whether the pattern works at all.

Add lesson 10's routing lever: sub-agents can run different models. Strong orchestrator, cheap workers is the canonical pipeline shape — priced per role rather than per default.

Granularity: the weekly judgement call

• Deep task, one agent; wide task, many. Wide = decomposes into similar, independent pieces (audit every endpoint). Deep = each step needs the previous step's full reasoning (debug this race). Fan out the wide; keep the deep in one context where the reasoning chain stays intact. Splitting a deep task destroys exactly the accumulated understanding that was making progress possible.
• Batch by what must be understood together. One worker per file is right when files are independent; when a change spans five coupled files, the worker's unit is the change — otherwise each worker sees a fifth of a refactor and none can complete it. Coupling defines the atom; the count follows (lesson 13 handles their write-conflicts; lesson 19 their coordination hazards).
• Composite briefs waste the isolation you paid for. "Check auth AND update deps AND fix the flaky test" in one sub-agent is three agents in a trench coat: no headroom gained, attribution lost. One brief, one concern — the same one-command-one-job rule as lesson 9, for the same debuggability reasons.

Held together: sub-agents are context economics (lesson 2) with a dispatch mechanism. Keep every window doing one thing well, pay the overhead knowingly, brief like a stranger, demand terse returns — and the orchestration lessons ahead will read less like new machinery and more like this idea, compounding.