Subagent Context Isolation in Claude Multi-Agent Systems

What subagent context isolation is

Subagent context isolation is the principle that each subagent thinks in its own private context window, sealed off from the coordinator and from other subagents. It is the single most commonly misunderstood idea in multi-agent design, and the exam tests it deliberately because getting it wrong produces agents that fail in confusing ways. The Anthropic Agent SDK documentation states it plainly: a subagent's context "starts fresh (no parent conversation)," and "the only channel from parent to subagent is the Agent tool's prompt string."

Two consequences follow, and you need both. First, a subagent does not see the coordinator's conversation history or earlier tool results. Second, a subagent does not remember what happened in a previous invocation of itself. Fresh every time, isolated every time. Anything it must know has to be handed to it in the prompt that starts it.

Why isolation follows from the topology

This is not an arbitrary constraint; it is the direct consequence of hub and spoke architecture. Because subagents have no direct channel to each other or to the coordinator's internal state, the only way information reaches a spoke is through the hub's invocation. Isolation is what the star topology looks like from inside a single spoke.

The SDK documentation spells out the boundary precisely. A subagent does receive its own system prompt and the prompt the coordinator sends it, and it can load project-level configuration. It does not receive the parent's conversation history, the parent's tool results, or the parent's system prompt. The clean separation is deliberate: it is what lets a subagent explore freely without polluting the coordinator's context, and what keeps each spoke independently reasoned.

The cost of forgetting isolation

When developers assume a subagent can "just see" what the coordinator knows, they build prompts that omit critical context. The subagent then operates on a partial picture, missing a customer id, an earlier finding, or a constraint that lived only in the coordinator's history, and produces work that looks plausible but is subtly wrong. Because nothing crashes, the bug can hide until it causes a visible failure downstream.

The same trap appears with memory across invocations. A developer might invoke a subagent, get a result, then invoke it again expecting it to "remember" the first round. It will not. The second call is as blank as the first unless the coordinator re-supplies what matters. Internalising this prevents a whole family of multi-agent bugs that are otherwise maddening to track down.

Isolation is a feature, not a limitation

It is easy to read context isolation as an inconvenience to work around, but it is one of the main reasons multi-agent systems are worth building. Because a subagent's intermediate tool calls and reasoning stay inside its own window and never flow back to the coordinator, a subagent can explore dozens of files or run a long investigation without bloating the coordinator's context. The Agent SDK documentation gives the example directly: a research subagent "can explore dozens of files without any of that content accumulating in the main conversation," and "the parent receives a concise summary, not every file the subagent read."

That containment is what lets a coordinator orchestrate large work while staying lean. If every subagent's raw exploration were dumped back into the coordinator, the hub would quickly drown in detail and lose the overview that makes it useful. Isolation is the mechanism that keeps the coordinator's context focused on decisions and distilled results. So the same property that forces you to pass context explicitly is the property that gives multi-agent systems their context efficiency, the constraint and the benefit are inseparable.

What does and does not cross the boundary

It helps to be precise about the boundary rather than treating it as a vague "subagents are separate." A subagent does receive its own system prompt and the invoking prompt string, and it can load project-level configuration such as a shared conventions file. It does not receive the parent's conversation history, the parent's earlier tool results, the parent's system prompt, or any preloaded skill content that was not explicitly granted. Knowing exactly which side of the line each item sits on is what lets you predict a subagent's behaviour.

The practical takeaway is that the invoking prompt string is the entire bridge. Anything that must influence the subagent has to be expressed there, because nothing else from the parent crosses. When you design a subagent invocation, treat that prompt as a self-contained briefing document: it is not a hint that supplements hidden shared knowledge, it is the only knowledge the subagent will have about the task at hand.

How to pass context correctly

The fix is straightforward once the principle is clear: the coordinator must include, in each subagent's prompt, every fact that subagent needs to do its job. That means embedding the relevant findings from prior agents, the specific question to answer, and any constraints or identifiers, directly in the prompt string, because that string is the only channel. The next knowledge points build on this: coordinator responsibilities include assembling these prompts, and structured context passing refines how to format them so attribution survives.

A useful discipline is to write each subagent prompt as if the subagent knows nothing about the wider task, because it does not. List the inputs, state the goal, and supply the constraints explicitly. If you find yourself thinking "the subagent will already know X," stop: it will not, unless X is in the prompt.

How you structure that context matters too, not just whether it is present. When you pass findings from an earlier agent, keep them organised, separate the actual content from its metadata, such as which source a fact came from or which document a quote sits in. Dumping a wall of unlabelled text into the prompt technically delivers the information, but it makes the subagent's job harder and risks losing attribution as the work moves down the pipeline. A clean, structured briefing, clearly delineated inputs, an explicit goal, and labelled sources, is both easier for the subagent to use and more faithful to where each piece of information originated. This is the seam where context isolation connects to structured context passing: isolation says you must pass everything, and structure says pass it in a form that survives the journey.

Worked example: a research subagent that loses the thread

Misconceptions the exam targets

Resumption is the exception that proves the rule

There is one nuance worth knowing so it does not trip you up: a subagent can sometimes be resumed, and a resumed subagent does retain its own earlier conversation. Its previous tool calls, results, and reasoning. That might sound like a contradiction of isolation, but it is not. Resumption restores a subagent's own prior context within the same session; it never grants the subagent the coordinator's history or another subagent's context. The boundary between agents stays intact; only a single agent's continuity across a pause is preserved.

The distinction to hold is between isolation across agents and continuity within one agent. Context isolation is about what crosses the wall between the coordinator and a subagent, or between two subagents, and nothing does, except the invoking prompt. Resumption is about whether one agent picks up where it left off, which is a separate axis entirely. For the foundations exam, the headline remains unchanged: never assume one agent can see another's context. Resumption is a same-agent feature, not a hole in the wall between agents.

Subagents versus agent teams

Isolation also explains when a subagent is the wrong tool for the job. A subagent is an isolated worker: it runs as part of a single session and reports a result back to the main agent only, sharing none of its working context with peers. That is ideal when the coordinator just needs a focused answer with minimal coordination overhead. But it means subagents cannot compare findings with each other or message one another while they work, because the only channel any of them has is the return path to the hub.

When a task genuinely needs that peer-to-peer collaboration, Claude Code offers a different primitive: agent teams. In an agent team each teammate gets its own context window, and teammates can communicate directly with one another rather than only reporting upward. The distinction is worth holding for the exam: if a scenario calls for agents to collaborate, cross-check, or talk to each other, isolated subagents are the wrong fit and agent teams are the intended pattern. For everything else, the headline for this knowledge point stands unchanged: a subagent is isolated, and the invoking prompt is its only window onto the task.

How this is tested on the exam

Task 1.2 questions frequently hinge on this principle. A scenario will show a subagent producing wrong or empty output, and the correct diagnosis is that the coordinator failed to pass the needed context into the subagent's prompt. Other questions test the memory boundary, asking whether a second invocation retains the first's findings. It does not. Because subagent context isolation is rated understand but underpins the more advanced apply and evaluate knowledge points in this task statement, mastering it early pays dividends across the whole multi-agent section. When in doubt, assume the subagent knows nothing it was not explicitly told.

Watch and learn

Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.

Official · Anthropic AcademyOpen full lesson in Academy

What are subagents?

Why watch: Explains that a subagent starts fresh without the coordinator's history, the context-isolation fact this KP stresses.

More videos for this concept

What are subagents?

Introduction to Subagents

Designing effective subagents

Introduction to Subagents

Building Reliable AI Agents with Sub-Agent Context Isolation in Claude Code

TheOTNerd

#12 Context Isolation | DevCompass | Claude Certified Architect Prep Cohort

DevCompass

Subagents: Parallel Execution and Context Isolation

Visual Studio Code

Using Subagents in Claude Code (Save that precious context window!)

Sundog Education with Frank Kane