D3 · Claude Code › Cluster 7 · Subagents

7.3 · Context Isolation & Delegation

Separate context windows

CONCEPT Each subagent gets its OWN context window

This is the whole point. Each subagent starts with a fresh, isolated context window with its own system prompt. It does not see your conversation history, the skills you've already invoked, or the files Claude has already read. Claude composes a short delegation message that summarises the task, and the subagent works from there. When it finishes, only its result returns to the main conversation — the verbose intermediate work (search hits, logs, file dumps) stays behind in the subagent's context.

🔑 The key benefit for context management: high-volume work happens in a separate window, so it never pollutes the main conversation. You pay the tokens once, over there, and get a clean summary back.

CONCEPT What a subagent starts with

A non-fork subagent's initial context is deliberately minimal:

Included at startupNotes
System promptThe agent's own prompt (Markdown body) plus environment details — not the full Claude Code system prompt.
Task messageThe delegation prompt Claude writes when handing off the work.
CLAUDE.md & memoryThe memory hierarchy the main conversation loads. (Built-in Explore and Plan skip this to stay fast.)
Preloaded skillsFull content of any skill named in the agent's skills field.

Because a subagent starts fresh, if a rule must reach it (for example "ignore the vendor/ directory"), restate it in the prompt you give Claude when delegating — the subagent won't infer it from your earlier conversation.

⚠️ Isolation cuts both ways: when subagents complete, their results return to the main conversation. Running many subagents that each return long detailed results can itself consume significant context. Ask them to return summaries, not transcripts.

DIAGRAM Verbose work stays isolated; only a summary returns

flowchart TD MAIN["🗨️ Main conversation
(context you care about)"] -->|"delegation message
(task summary)"| SUB subgraph ISO["Subagent — separate context window"] SUB["Fresh system prompt
+ task message"] --> WORK["Reads files, runs tests,
fetches docs → huge output"] WORK --> SUM["Distils to a short result"] end SUM -->|"only the summary"| MAIN NOTE["❌ Search hits · logs · file dumps
never reach the main window"] -.-> WORK classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef iso fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class MAIN ok; class SUB iso; class WORK iso; class SUM iso; class NOTE bad;

CODE Delegating a high-volume task

The classic isolation pattern: let the subagent absorb the noisy test output and hand back only what you need.

# In the main conversation, you ask:
Use a subagent to run the test suite and report only the
failing tests with their error messages.

# What happens:
#  - The subagent runs the full suite in ITS OWN context
#  - Thousands of lines of pass/fail output stay in that window
#  - Only the short list of failures + errors returns to you
This is why subagents "preserve context": the expensive, verbose part is isolated, and the main thread receives a compact answer it can act on.

TRADE-OFFS Isolated context vs. shared context

✅ Isolated subagent context

  • Verbose exploration never bloats the main window
  • Independent tool access & permissions per agent
  • Parallel subagents each explore without cross-talk

⚠️ Cost of isolation

  • Subagent can't see prior conversation — must be told what it needs
  • It starts fresh, so it may need time to gather context (latency)
  • Many detailed returns can still add up in the main context

EXAM TRAPS

Trap: "A subagent shares the main conversation's context." → It does not. It starts in a fresh, isolated context window and doesn't see your history, invoked skills, or files Claude already read. (The one exception is a fork, which inherits the conversation.)
Trap: "The subagent returns its full working transcript." → Only its result / summary returns to the main conversation. The intermediate output stays in the subagent's window.
Trap: "Subagents don't help with context because their output comes back anyway." → The verbose work stays isolated; just the distilled summary returns. That's the context saving — though many long returns can still accumulate, so ask for summaries.
Trap: "A subagent automatically knows my project rules from the chat." → It only knows what its system prompt, CLAUDE.md, and the delegation message contain. Restate any conversation-specific rule in the delegation prompt.

PRACTICE

Q1 · What is the single biggest benefit of running a subagent in a separate context window?

Context management: the verbose side-work happens in the subagent's own window and never pollutes the main conversation — only a compact summary returns.

Q2 · Does a subagent see your earlier conversation and the files Claude already read?

No. It starts with a fresh, isolated context — its own system prompt, the delegation task message, CLAUDE.md/memory, and any preloaded skills. Not your chat history or previously read files. (A fork is the exception.)

Q3 · What comes back to the main conversation when a subagent finishes?

Only its result/summary. The high-volume intermediate output (search results, logs, file contents) stays in the subagent's context.