Coordinator and subagent architecture

The single most-tested idea in the heaviest domain: subagents do not inherit context.

6 min read · Lesson 6 of 12 in this domain

This is the heaviest-weighted idea in the heaviest-weighted domain, and almost every mistake traces back to one wrong assumption: that a subagent can see what the coordinator saw. It cannot. A subagent gets a fresh context window containing only the prompt you hand it. It has no access to the coordinator's conversation, its tool results, or its earlier findings, and there is no session id or handle that grants that access. Once you internalise this, the rest follows — every architectural rule in this lesson is a consequence of context not being inherited.

• Subagents start with a fresh context window. They inherit nothing — not the coordinator's history, not its findings, not its tool results. There is no mechanism for one agent to read another's session.
• Therefore the coordinator must inject all prior output explicitly, in a structured form that preserves attribution (claim, evidence, source, date) rather than prose that destroys it.
• Use hub-and-spoke: a coordinator mediates between subagents. Flat all-to-all topology is a named anti-pattern — unpredictable state, duplicated work, nowhere to observe or enforce policy.
• If the coordinator already holds the information, do the work in place. Spawning a subagent to restate what you are already holding is pure overhead.
• Delegate only when the payoff exceeds the fixed cost: fresh context establishment, re-exploration, a report, and the coordinator re-reading it.
• Emit independent Task calls in a single turn so they run concurrently. Wall-clock then equals the slowest task rather than the sum.

Source: Claude Docs — Agent SDK subagents · Independent study aid, not affiliated with or endorsed by Anthropic.