Subagents

Read these first

• The extensibility landscape
• Sub-agent context isolation

What you will know

• Delegate a bounded task to a subagent with a restricted tool set

  A narrow permission surface limits destructive actions and makes failures attributable to one delegated unit.

• Decide what the subagent returns and how much

  An explicit output contract prevents verbose transcripts from consuming the parent context and makes downstream handling deterministic.

• Compare a bounded task with and without a fresh context and measure the effect

  Isolation can remove distracting history and tool affordances, but it also discards useful state and adds setup overhead.

• Show a subagent succeeding where the main loop was drowning

  A useful demonstration isolates a task whose competing history or intermediate work would otherwise crowd out the parent objective.

• Decide against a subagent when the handoff costs more than it saves

  Serialization, scheduling, extra model calls, and result validation can outweigh any reduction in context pressure.

Chapters

1. 1

   Delegation buys a context boundary, not extra intelligence

   A subagent is the same model with a fresh transcript and a narrower job, so the only thing it reliably buys is that the bulk it reads never enters the parent. That framing changes the comparison: reading a 4,000-line OpenAPI spec to find endpoints taking a cursor parameter is a delegation candidate, but grep answers it with no model call at all. Justify a subagent against the cheapest alternative, never against doing nothing.

   Read chapter
2. 2

   The output contract decides whether isolation survives

   Ask a child to find every place a Stripe client is constructed and it reads twelve files and hands back its whole working transcript, leaving the parent larger than if it had searched itself. The delegation must state what comes back and in what shape — file and line references with one line of context each. Without a contract the child returns its process rather than its conclusion, and the isolation you paid for is undone at the handoff.

   Read chapter
3. 3

   A narrow tool set bounds what a delegated unit can do

   For "identify which Terraform modules reference the retiring subnet" the child needs file read and nothing else, even though the parent holds plan, apply and a shell. The argument that restriction is pointless because a read-only task would never call apply misses that a delegated unit is the component you have least visibility into while it runs. One line of configuration against an unattended apply is not a close trade. When the restriction bites — the child wants `plan` to resolve module variables — widening the grant is the reflex to resist: `plan` needs credentials and touches state and lock files, so resolve the variables in the parent and pass the values, or grant only the narrower capability the child was actually blocked on.

   Read chapter
4. 4

   A fresh context discards established state along with noise

   A parent spends twenty turns proving that a flake in checkout.spec.ts is a race in fixture setup; the child, asked to "fix the flaky test", deletes the assertion. Everything the parent established is gone unless the brief carries it. The opposite mistake is worse: pasting the full conversation history into the brief so the child "has full context" builds a second model call rather than a boundary, paying setup cost and receiving none of the benefit.

   Read chapter
5. 5

   A brief carries conclusions, not the transcript that produced them

   Between the two failures of the previous chapter sits the rule neither of them states. A brief carries what the parent established and the constraints that follow from it — the flake is a race in the fixture setup, do not touch the assertions — plus pointers the child can expand for itself, and it deliberately omits the process that produced those conclusions. That is what lets the child start from twenty turns of work without inheriting their token cost, and it is the same discipline the output contract imposes in the outbound direction.

   Read chapter
6. 6

   Showing a rescue means replaying the same context pressure

   Claiming a subagent succeeds where the main loop drowned is a claim about a specific moment, so a fresh run of the delegated version proves nothing. Take a session that failed with a long transcript, replay the conversation up to that point, and branch the delegation from there. Run the inline arm from that same point too, recording tokens arriving in the parent, wall-clock and whether the answer was right, and the demonstration doubles as the with-and-without comparison. This chapter also covers how to read the honest version of that result, such as forty billing turns answered correctly at 35% more tokens and twelve seconds more latency.

   Read chapter
7. 7

   Turn count is a proxy for nothing in particular

   A rule that delegates every task longer than ten turns will still delegate the wrong ones after you raise the threshold to twenty: a long conversation with small tool outputs has no context problem, and a five-turn task that reads a huge file has a severe one. Learn where the handoff loses — when the parent must re-check everything the child returns — and what replaces the rule once you can see which delegations earn their keep.

   Read chapter