What you will be able to do
- Check that each subagent gets the facts it needs in its delegation prompt, given what a fresh subagent does and doesn't receive
- Spot task boundaries that will collide on shared files or depend on each other, and fix them with single ownership or sequencing
- Pick runtime controls that cap fan-out, depth and spend no matter how the orchestrator decides to delegate
- Judge whether a decomposition meets observability and error-recovery requirements, comparing subagent threads with workflow runs
- Find where result synthesis can report success that the subagents' work doesn't support
Key concept
Context isolation at the delegation boundary — A subagent works in its own conversation. It learns only what the delegation hands it, and the orchestrator gets back only the subagent's final message. Every boundary, recovery path and synthesis step in a decomposition depends on what crosses that line in each direction.
1.What a decomposition buys and what it costs
An orchestrator/subagent decomposition splits a multi-step workload so that a lead agent plans the work and hands slices of it to subagents, each running in its own context. The main thing it buys is isolation. A research subagent can read dozens of files, and the parent gets a short summary back instead of every file. Several subagents can also run at the same time, so independent subtasks finish in the time of the slowest one rather than the sum of all of them. Whether a workload should be split at all is a pattern-selection question, covered in choosing between workflow patterns and agents. This page assumes someone has already proposed a split and asks whether it will hold up.
The same isolation makes a decomposition fragile. Anything the subagent needs and isn't given, it doesn't have. Anything it learns and leaves out of its final message, the orchestrator never sees. Teams that built separate agents for planning, execution, review and iteration found they lost context at every handoff and spent more tokens coordinating than executing. Multi-agent setups typically use 3–10x more tokens than a single agent doing the same task. The extra comes from duplicated context, coordination messages, and summaries written for each handoff.
Reviewing a proposal comes down to four questions. Does each boundary give the subagent everything it needs while keeping it out of its siblings' way? Is the control flow bounded by the runtime, or only by what the prompt asks for? Can an operator see each subagent's work and recover when one fails? And does the synthesis step check what comes back before reporting it?
Checkpoint 1 of 9· Check yourself
An orchestrator sends a research subagent to survey a codebase. The subagent reads 40 files and spots a deprecated API in one of them, but its final message does not mention it. What does the orchestrator learn about the deprecated API?
Context isolation works in both directions. The subagent's intermediate tool calls and results stay in its own conversation, and the parent receives only its final message. Anything the subagent leaves out of that message never reaches the orchestrator.
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”Source: code.claude.com
2.Task boundaries: what crosses into a subagent
In the Agent SDK, a regular subagent starts fresh. It doesn't see the conversation that produced its task, so any decision made in that conversation has to be written into the delegation prompt. A thirty-turn agreement on a target schema, a list of excluded tables and a rollback rule is lost if the delegation says only "Write the migration scripts." There are two fixes. Put those decisions directly in the Agent tool prompt, or start the worker as a fork. A fork is the one kind of subagent whose conversation doesn't start fresh, so it gets the history. The cost is that the fork then carries the parent's whole history in its own context, which gives up some of the isolation.
| The subagent receives | The subagent doesn’t receive |
|---|---|
| Its own system prompt (AgentDefinition.prompt) and the Agent tool’s prompt | The parent’s conversation history or tool results |
| Project CLAUDE.md (loaded via settingSources), unless the agent sets omitClaudeMd | Preloaded skill content, unless listed in AgentDefinition.skills |
| Tool definitions, inherited from the parent or the subset in tools | The parent’s system prompt |
Use the table to rule out the tempting non-fixes. Listing items in AgentDefinition.skills preloads skill content. It does not load the parent's conversation. Changing the parent's system prompt doesn't help either, because the subagent never receives it. A subagent can't infer decisions it was never shown, however much effort it spends.
A good delegation is more than a list of facts. Anthropic's research system found that each subagent needs an objective, an output format, guidance on which tools and sources to use, and clear task boundaries. With vague instructions like "research the semiconductor shortage," subagents misread the task or ran the same searches as their siblings. Without clear boundaries, agents duplicate work, leave gaps, or miss information they needed.
Boundaries also have to divide the shared state, not just the topics. Suppose a logging-library migration is split into three write-capable subagents, one per service. All three services import a shared utils/ package. The boundaries look clean, but each subagent will edit utils/, and parallel edits to the same files conflict at random. Workloads with many dependencies between agents are a poor fit for parallel decomposition. Two changes remove the dependency itself:
- Single ownership. One subagent owns
utils/. The others report the shared changes they need instead of making them. - Sequencing. A first step updates
utils/, and the three service subagents then run in parallel against the finished package.
Neither of the obvious patches fixes the boundary. Telling each subagent to re-read a file just before editing it only narrows the window in which a conflict can happen. Giving every subagent the orchestrator's history tells it what was planned, but nothing stops two subagents from writing the same file at once.
Checkpoint 2 of 9· Check yourself
A logging-library migration is split across three write-capable subagents running in parallel, one per service. All three services import the shared utils/ package. Which change to the decomposition removes the conflict?
The conflict comes from a dependency between agents that all write to utils/. Re-reading only makes the conflict window smaller. Forking tells each agent the plan but still lets two of them write the same file. Giving utils/ a single owner removes the dependency. Updating utils/ in a step before the parallel fan-out would also work.
“involve many dependencies between agents are not a good fit for multi-agent systems today”Source: www.anthropic.com
Checkpoint 3 of 9· Check yourself
After thirty turns, an Agent SDK orchestrator and the user agree on a target schema, a list of excluded tables and a rollback rule. The orchestrator then delegates "Write the migration scripts" to a regular (non-fork) subagent. Which fix gets those decisions to the subagent?
A regular subagent starts with a fresh conversation. It gets its own system prompt and the Agent tool's prompt, not the parent's history or the parent's system prompt. Writing the decisions into the delegation prompt works, and so does starting the worker as a fork. Listing a skill preloads skill content, not the conversation.
“each subagent runs in its own conversation, which starts fresh unless the subagent is a fork.”Source: code.claude.com
Checkpoint 4 of 9· Exam question
An orchestrator in the Agent SDK has spent thirty turns with a user agreeing on a migration plan covering the target schema, the tables to exclude and a rollback rule. It then spawns a regular migration-writer subagent with the prompt "Write the migration scripts." The scripts ignore the exclusions and the rollback rule. Which two changes fix the handoff? Choose two.(Select 2)
Correct answers: A, E — Place the agreed schema, excluded tables and rollback rule directly in the Agent tool prompt string, the only content a fresh subagent receives from its parent; Start the writer as a fork that copies the conversation so far, accepting that it then carries the parent's whole history in its own context
- A. A non-fork subagent starts fresh, and the Agent tool prompt is the only channel from parent to subagent. Writing the decisions into that prompt gives it what it needs.
- B. Reasoning effort cannot reconstruct decisions that were made in conversation and never recorded in the repository. The exclusions would still be guesses.
- C. A subagent does not receive the parent's system prompt, and the plan lived in the conversation anyway. Nothing carries the agreement across.
- D. The
skillslist preloads named skills, not conversation history. It does not transfer the agreement. - E. A fork copies the conversation so far, so the agreed plan is already in its context. The cost is a larger context carried into the subagent.
Checkpoint 5 of 9· Exam question
An orchestrator built on the Claude Agent SDK splits a logging-library migration into three write-capable subagents, one per service team. All three services import a shared utils/ package. Runs intermittently end with conflicting edits to the same shared files, and the orchestrator's synthesized summary still reports success. Which two changes to the decomposition most directly fix this task-boundary problem? Choose two.(Select 2)
Correct answers: B, D — Make one subagent the owner of utils/, and have the other two report needed shared changes back rather than editing the package themselves; Run a first step that updates utils/, then start the three per-service subagents in parallel against the already-updated package
- A. The subagents start together and edit concurrently, so none has settled its changes when it begins. The conversation history shows nothing about what siblings will do, and three subagents still hold write access to the same
utils/files. - B. Giving
utils/one owner leaves a single writer for the shared files. The other two subagents' write sets stay inside their own services, and the shared changes they need are routed to the owner instead of being made in parallel. - C.
maxTurnsonly caps how many turns one subagent may take. It does not order subagents relative to each other, and the conflicts come from parallel runs holding overlapping write access, not from edits that were cut short. - D. Updating
utils/in a sequential first step turns the hidden shared dependency into an explicit stage. The parallel phase then touches only per-service files, so the subagents' write sets no longer overlap. - E. A re-read narrows the race window, but checking and writing are not one atomic step, and the subagent has no reliable way to merge a sibling's edit. Three subagents still write to
utils/, which is a decomposition flaw that an instruction cannot fix.
3.Control flow: bounding fan-out, depth and spend
When Claude decides how many subagents to spawn, the system prompt steers that decision but the runtime is what limits it. Early versions of Anthropic's research system spawned 50 subagents for simple queries. The fix there was explicit scaling rules in the prompt: one agent with 3–10 tool calls for simple fact-finding, and 2–4 subagents for direct comparisons. Rules like these lower how often over-spawning happens. If the requirement is a hard ceiling no matter how Claude delegates, you need a limit the runtime enforces. A delegation rule in the prompt is not one.
| Limit | Set it with | Default | At the limit |
|---|---|---|---|
| Depth | CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH | 3 layers below the main agent; 1 stops subagents spawning their own | A bottom-layer subagent can't spawn and does its delegated work itself |
| Concurrency | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | 20 subagents running at once | Refuses to spawn, returning Concurrent subagent limit reached, until the running count drops |
| Spend | maxBudgetUsd (TypeScript), max_budget_usd (Python) | No limit; subagent requests count | Refuses further spawns with Budget limit reached, stops background subagents, ends the query with error_max_budget_usd |
Each control fixes a different failure. Deep chains of nested subagents call for a lower depth limit, and a value of 1 makes delegation flat. Wide bursts of spawning call for a lower concurrency limit. A bill far above forecast calls for a spend cap, because that is the only one of the three that stops the run. Depth, concurrency and spend are the three documented controls on spawning. A setting that limits something else, such as how many turns one subagent may take, does not cap how many subagents the parent creates.
Claude Managed Agents enforces stricter limits by design. Delegation is one level deep, so an agent that references another agent with multiagent set fails validation. A session can have at most 25 child threads at a time, including idle ones. Spend there is governed by a session budget: a single cap shared by all of a session's threads, including workflow runs. When the cap is reached, threads pause independently.
Checkpoint 6 of 9· Check yourself
Finance requires a hard ceiling on what one Claude Managed Agents session can spend, including any workflow runs, however the lead agent decides to delegate. Which design meets that requirement?
Prompt rules steer how Claude delegates but enforce nothing, and the requirement is a ceiling that holds whatever Claude decides. In Managed Agents, the session budget is the runtime spend cap, and it covers every thread, workflow runs included. The thread limit caps how many threads exist at once, not spend. A per-subagent turn limit does not cap how many subagents get created.
“Every agent in a run uses tokens, so set a session budget to cap the session’s spend, runs included.”Source: platform.claude.com
Checkpoint 7 of 9· Exam question
A code-audit agent built on the Agent SDK lets Claude decide how many subagents to spawn. A run against a monorepo produced deep chains of nested subagents and a bill several times the forecast, even though the prompt already tells it to delegate sparingly. Finance now wants fan-out and spend bounded no matter how Claude chooses to delegate. Which two controls meet this? Choose two.(Select 2)
Correct answers: A, D — Set a maximum dollar budget in the SDK options for the run, so the runtime stops spawning subagents and ends the query once the budget is hit; Lower the nesting-depth and concurrent-subagent limits through the environment settings passed to the SDK, so the runtime enforces them on each spawn request
- A. Correct. A run-level budget is enforced by the runtime and counts subagent usage. Once it is reached, further spawns are refused and the query ends, so cost stays bounded whatever delegation choices Claude makes.
- B. Wrong. A policy in the system prompt, even with a numeric ceiling, only steers Claude's judgment and nothing enforces the number. The existing instruction to delegate sparingly already failed, so more prompt text cannot give guaranteed bounds.
- C. Wrong. A turn limit restricts how many turns one subagent may take, not how many subagents exist or how many levels they nest. A single turn can launch several children, each with its own turns, so fan-out and spend remain unbounded.
- D. Correct. Nesting-depth and concurrent-subagent limits are runtime settings supplied through the environment. They cap how deep and how wide subagents can go, independent of Claude's delegation decisions.
- E. Wrong. A cheaper model lowers the price of each subagent but places no limit on how many are spawned, how deeply they nest, or what the run costs in total. Fan-out stays unbounded, so spend can still balloon and finance gets no guaranteed ceiling.
4.Observability and error recovery across threads
In Managed Agents, the session-level stream gives an operator a summary of each subagent's work, not the full detail. That primary thread shows a condensed view of activity across all threads: the start and end of each subagent's work, plus blocking events such as tool permission requests. To inspect a specific agent's reasoning and tool calls, open that thread's own stream at /v1/sessions/{session_id}/threads/{thread_id}/stream. A child's live previews never appear on the session-level stream. In the Console session viewer, the Threads tab lists every thread with its status, context size and cost, and the timeline gives each thread its own lane. If a requirement says that every subagent's tool calls must be auditable, the design has to read per-thread streams. Watching the primary stream won't meet it. Which signals to collect in the first place is covered in instrumentation and monitoring gaps.
| Event | What it tells an operator |
|---|---|
| session.thread_created | A thread was created; includes session_thread_id and agent_name |
| session.thread_status_idle | The thread's agent is awaiting input; includes a stop_reason |
| session.thread_status_terminated | The thread accepts no further input, e.g. archived or hit an unrecoverable error |
| agent.thread_message_received | A subagent sent the primary agent a report or question |
The two Managed Agents delegation modes differ most in how you recover from errors. With subagents, a thread persists until you archive it. The orchestrator can send a follow-up to a subagent it called earlier, and that subagent keeps everything from its previous turns, so a bad result can be corrected inside the context that produced it. With dynamic workflows, a program that Claude writes runs the agents in the background. The orchestrator can't send follow-ups to a run's threads, and the server archives each one by the end of the run. On a run's threads, a session.thread_status_terminated event tells you a thread is done, but no event records the result it returned to the workflow. A requirement like "retry or correct a failed step in place, and audit what each step returned" favours subagents. A long, parallel audit where per-step correction isn't needed suits a workflow run.
The interrupt closes the child's pending tool calls with an error result asking for a retry, and the thread goes idle without sampling the model. The interrupted child sends no end-of-turn report to the orchestrator. If the orchestrator was waiting on that child, it won't start another turn until something else reaches it, such as a user message or a report from another thread. A recovery plan built on interrupts has to send that next message itself.
Interrupts also behave differently inside workflow runs. An interrupt doesn't end a run, and an interrupt that names one of the run's threads stops nothing. A design whose error-recovery plan says "interrupt the failing worker" therefore needs to say which mode that worker runs in. For retry and backoff policy beyond this, see production reliability controls.
Checkpoint 8 of 9· Match them up
You are reviewing a Claude Managed Agents design. Match each requirement to the design choice that meets it.
Tap a term, then the definition that fits it.
The primary stream shows only a condensed view of each subagent's work, so a full audit means reading the per-thread streams. Only subagent threads persist and accept follow-ups, so in-place correction requires subagents. A workflow run's threads accept no follow-ups and are archived by the end of the run, which is acceptable only when per-step correction isn't needed.
“A subagent’s thread stays available until you archive it, so the agent can send it follow-up messages.”Source: platform.claude.com
5.Result synthesis: where success gets misreported
Synthesis works only from what the subagents chose to return. Each subagent's intermediate tool calls stay inside it, and only its final message reaches the parent. In the research pattern below, the lead agent breaks the query into facets, waits for every subagent, then synthesizes whatever came back. Nothing in that loop checks that two results agree, or that a reported change actually landed. In the logging migration, three subagents can each report success while their edits to utils/ overwrite one another. If the synthesis step just combines those reports, the summary says the migration succeeded.
async def research_topic(query: str) -> dict:
# Lead agent breaks query into research facets
facets = await lead_agent.decompose_query(query)
# Spawn subagents to research each facet in parallel
tasks = [
research_subagent(facet)
for facet in facets
]
results = await asyncio.gather(*tasks)
# Lead agent synthesizes findings
return await lead_agent.synthesize(results)Synthesis holds up when the decomposition plans for it. First, the delegation prompt fixes an output format, so returned results can be compared instead of just read. Second, the lead agent treats synthesis as a decision point. In Anthropic's research system, the lead synthesizes results and then decides whether more research is needed. It can spawn more subagents or change its strategy before it answers. Third, a dedicated final stage can check the combined output. That system passes every finding to a separate CitationAgent, which attributes each claim to a source before the report goes to the user. Where results come from a workflow run, no event preserves what each thread returned. If you need to audit a summary, the workflow has to persist its intermediate results itself.
Checkpoint 9 of 9· Fill the gap
In this fan-out-and-synthesis loop, what does the lead agent pass to its synthesis step? Pick the token that completes the sample.
async def research_topic(query: str) -> dict:
# Lead agent breaks query into research facets
facets = await lead_agent.decompose_query(query)
# Spawn subagents to research each facet in parallel
tasks = [
research_subagent(facet)
for facet in facets
]
results = await asyncio.gather(*tasks)
# Lead agent synthesizes findings
return await lead_agent.synthesize( ? )Synthesis works only from what the subagents returned (the gathered results). It never sees their tool calls, and nothing in the loop checks that two results agree or that a reported change actually landed. To catch a misreported success, the design needs a fixed output format, a decision point after synthesis, or a separate verification stage.
Source: claude.comSources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent”
↩︎ What a decomposition buys and what it costs“Its own system prompt (AgentDefinition.prompt) and the Agent tool’s prompt”
↩︎ Task boundaries: what crosses into a subagent“each subagent runs in its own conversation, which starts fresh unless the subagent is a fork”
↩︎ Task boundaries: what crosses into a subagent“Leaves a subagent at the bottom layer unable to spawn, so it does its delegated work itself.”
↩︎ Control flow: bounding fan-out, depth and spend“ends the query with the error_max_budget_usd result subtype”
↩︎ Control flow: bounding fan-out, depth and spend“The parent receives a concise summary, not every file the subagent read.”
↩︎ Result synthesis: where success gets misreported“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent”
↩︎ Key concept“each subagent runs in its own conversation, which starts fresh unless the subagent is a fork”
↩︎ Exam trap 1“Refuses to spawn another subagent, returning Concurrent subagent limit reached, until the running count drops below the limit.”
↩︎ Exam trap 2“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
↩︎ Checkpoint“each subagent runs in its own conversation, which starts fresh unless the subagent is a fork.”
↩︎ Checkpoint - 2.
“multi-agent implementations typically use 3-10x more tokens than single-agent approaches for equivalent tasks”
↩︎ What a decomposition buys and what it costs“they suffered from lost context at each handoff and spent more tokens coordinating than executing”
↩︎ What a decomposition buys and what it costs - 3.
“Each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries.”
↩︎ Task boundaries: what crosses into a subagent“Without detailed task descriptions, agents duplicate work, leave gaps, or fail to find necessary information.”
↩︎ Task boundaries: what crosses into a subagent“involve many dependencies between agents are not a good fit for multi-agent systems today”
↩︎ Task boundaries: what crosses into a subagent“spawning 50 subagents for simple queries”
↩︎ Control flow: bounding fan-out, depth and spend“Simple fact-finding requires just 1 agent with 3-10 tool calls, direct comparisons might need 2-4 subagents with 10-15 calls each”
↩︎ Control flow: bounding fan-out, depth and spend“The LeadResearcher synthesizes these results and decides whether more research is needed”
↩︎ Result synthesis: where success gets misreported“involve many dependencies between agents are not a good fit for multi-agent systems today”
↩︎ Exam trap 4 - 4.
“Delegation is one level deep, and a session can have at most 25 child threads at a time, idle ones included.”
↩︎ Control flow: bounding fan-out, depth and spend“The agent can send a follow-up to a subagent it called earlier, and that subagent retains everything from its previous turns.”
↩︎ Observability and error recovery across threads“The agent can’t send follow-up messages to a run’s threads, and the server archives each one by the end of its run.”
↩︎ Exam trap 3“Every agent in a run uses tokens, so set a session budget to cap the session’s spend, runs included.”
↩︎ Checkpoint“A subagent’s thread stays available until you archive it, so the agent can send it follow-up messages.”
↩︎ Checkpoint - 5.
“A session budget is a single shared cap across all of a session’s threads.”
↩︎ Control flow: bounding fan-out, depth and spend“You don’t see the full activity from subagents, but you do see the start and end of their work”
↩︎ Observability and error recovery across threads“No event records the result it returned to the workflow.”
↩︎ Observability and error recovery across threads“An interrupted child doesn’t send the primary thread’s agent the report it sends when a turn ends.”
↩︎ Observability and error recovery across threads“No event records the result it returned to the workflow.”
↩︎ Result synthesis: where success gets misreported - 6.
“Every thread with its status, context size, and cost.”
↩︎ Observability and error recovery across threads