Skip to content

10.1 Subagents: Delegation Within Delegation

Your agent can hire help. A subagent is an agent your main agent spawns for a piece of work — running in its own context window, doing its task, and returning only its conclusions. If that sounds like a context-engineering move wearing a teamwork costume, congratulations: you've internalized Chapter 5. This lesson makes delegation-within-delegation a daily tool.

What you will learn

  • Explain what a subagent is and the one property that makes it valuable: context isolation.
  • Know the three tasks that beg for subagents — and the ones that don't.
  • Define specialized subagents with their own instructions and toolsets.

Builder principle

Send the errand out; keep the decision home. A subagent that returns a two-page conclusion just saved your main session from fifty files of noise.

The mechanics, and the point

When your agent faces a chunky sub-task — "investigate how auth works across this codebase" — it can spawn a subagent: a fresh agent instance with its own clean context window, a brief, and (optionally) its own restricted tools. The subagent runs its own gather-act-verify loop, finishes, and hands back a report. Only the report enters your main session's context.

Read that last sentence again, because it's the entire value proposition. Remember 5.5's exploration/build separation — investigations flood the window, so quarantine them? Subagents are that pattern with the plumbing built in:

WITHOUT:  main session reads 60 files → window sludged → build
          quality sags for the rest of the session  (5.5's disease)

WITH:     subagent reads 60 files in ITS window → returns 2 pages
          of conclusions → main window stays curated  (the cure)

The subagent's context is disposable by design. It burns its window on the messy work so yours stays clean for the decisions.

Where subagents shine

1. Research and reconnaissance. The unfamiliar codebase (5.6), the "which library should we use" comparison, the log archaeology of a 6.3 debug. Any task whose output is knowledge, not changes — the report-back shape fits perfectly, and the exploration debris stays in the disposable window.

2. Review with fresh eyes. A subagent reviewing your main agent's diff has a property you can't fake in-session: it doesn't know the intentions — it only sees the code. Your main session's context is full of what the code is supposed to do; the reviewer's blankness is the feature. (The skeptical-reviewer question from 4.3, upgraded from a prompt to an institution.)

3. Parallel independent chunks. Three product descriptions, four data files to validate, five pages to rude-test — homogeneous work with no shared state. Fan out, collect reports, integrate. (This foreshadows 10.3's teams, where the chunks get heterogeneous and the coordination gets real.)

Where they don't: tasks needing the full session's accumulated context (the subagent starts blank — that's the tradeoff), tiny errands (spawn overhead exceeds the work), and judgment calls that are yours (6.5's constitution, unamended). The blank start is the tell: if briefing the subagent would take longer than doing the thing, keep it home.

Specialized subagents: roles, not just errands

Beyond ad-hoc spawns, Claude Code lets you define subagents — named roles with standing instructions and scoped tools, saved in your project (.claude/agents/, shipping with the repo like every other piece of your stack). The starter roster:

reviewer   — reviews diffs against CLAUDE.md standards + the harness.
             Tools: read-only. Cannot edit; its whole job is opinions.
researcher — investigates and reports with sources; UNVERIFIED flags
             welcome (6.4 rules baked in). Tools: read + web.
tester     — runs the rude-test pass (4.4) against a live preview.
             Tools: read + browser (8.3's Playwright).

Notice what defining a role really is: a Skill-shaped object whose trigger is delegation. Instructions, standards, boundaries, scoped tools — you've written this document four times by now (CLAUDE.md, Skills, hooks policy, and now agents). Same craft, new address. And notice the tool scoping: the reviewer can't edit. Least privilege (8.5) applies to your own crew — not because agents scheme, but because a reviewer that can't touch code can't accidentally "fix" what it was supposed to critique.

Frame it as staffing: you've had one brilliant assistant; now it can call departments. Your first spawn should be the reviewer — next real build, before you commit: "Have a subagent review this diff with fresh eyes against our CLAUDE.md — report issues by severity." The report comes back written to your main agent, argued about in front of you, and you referee. Watching your agents disagree about your code is the most instructive ten minutes in this track.

The pattern to steal for work: context budgeting as architecture. Main session = the trunk (decisions, integration); subagents = branches (exploration, review, validation), each with a defined report format back. Concretely this week: define the reviewer with read-only tools + your team's standards, and make it a pre-PR institution — cheap, immediate, and it makes the 4.3 review-quality problem structural instead of habitual. Then notice how role definitions + settings policy (9.4) + harness (9.3) are converging into one object... that's 10.4, and it has a name.

Try it now

  1. Ad-hoc spawn: on your main project — "Spawn a subagent to investigate [something real: how your CSS is organized, what's stale in docs/]. I want conclusions and recommendations, not the tour." Watch the report come back; check what did not enter your window.
  2. Define the reviewer role (.claude/agents/), read-only tools, standards pointed at your CLAUDE.md.
  3. Use it for real: next diff, reviewer first, then commit. Referee any disagreement.
  4. Journal: where did the reviewer's blankness catch something your context-soaked main session had blessed?

Check your understanding

  • What crosses back from a subagent to the main session — and what deliberately doesn't?
  • Which 5.5 pattern do subagents mechanize, and what does "disposable window" mean?
  • Why is the reviewer's ignorance of intentions a feature? Which Chapter 4 practice does it upgrade?
  • Why scope the reviewer's tools read-only — what principle, from where?