What a Claude Code subagent can and cannot see

You asked Claude Code to delegate something — use a subagent to find every place we call the payments API — and watched it open three files the main conversation had already read, in full. The summary came back and the detail you actually cared about was not in it.

Nothing failed. Both are documented behaviour of a boundary the docs describe field by field and never state as a rule. The subagent page tells you how to define one: the frontmatter, the tool list, the model, the directory. What it never says in one place is what a subagent inherits from you and what it loses — and that, not any frontmatter field, decides whether delegating a task will work.

Here is the boundary, in both directions.

A subagent is a second conversation, not a second reader

The fact that explains most surprises: a subagent does not read over your shoulder. It is a separate conversation with a separate context window, and it begins with nothing of yours in it.

Anthropic states it without hedging: "Each subagent starts with a fresh, isolated context window. It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read."

Each item retires a different assumption. Not the conversation — so the constraint you agreed on twenty messages ago is gone. Not the skills — so a workflow you invoked in the main thread is not running in there. Not the files — so anything Claude read for you, the subagent must read again for itself.

The re-reading is not waste and not a cache miss. It is the only way the subagent can know the file exists.

The delegation prompt is the entire crossing

If the context window starts empty, something has to carry the task across, and exactly one thing does: "The only content you pass from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt."

That is the whole channel. One string.

Two consequences follow. The first is that you do not write it — Claude does. @-mentioning a subagent chooses which one runs, not what it is told; your message goes to Claude, and Claude composes the handoff. The delegation prompt is a summary of your request, written by something that may not know which part of it mattered.

The second is the fix, and the highest-value habit in this subject. Anything the subagent must know has to be said in the turn where you delegate: the file path, the exact error text, the branch, the decision you do not want revisited. "Check the thing we discussed" crosses the boundary as nothing at all.

Some things load anyway, and you did not pass them

The context is fresh, not bare. A non-fork subagent starts with its own system prompt — its definition body plus environment details, not Claude Code's full main-session prompt — plus a short list of things Claude Code loads on its behalf.

Your CLAUDE.md hierarchy is one: every level the main conversation loads, including the user-level file, project rules, CLAUDE.local.md and managed policy files. A git status snapshot from the start of the parent session is another. So is the full content of any skill named in the subagent's skills field.

One documented exception bites hardest: the built-in Explore and Plan agents skip both CLAUDE.md and git status, deliberately, to keep research cheap, and no frontmatter field changes that. If a project rule has to reach a research subagent — never touch `vendor/` — restate it in the delegation.

Where an instruction belongs in the first place is its own question; here it matters only that project instructions do cross, and that two built-ins are the exception.

What never crosses, whatever you do

A shorter list, worth memorising because nothing in the frontmatter overrides it.

The parent's conversation history and tool results do not cross. Neither does the parent's system prompt. Your output style does not apply, because the subagent runs its own system prompt instead. Your auto memory does not load — and a subagent that wants memory gets its own: "A subagent's own auto memory, enabled with the subagent memory field, is a separate directory."

And one that catches people out on long tasks: the context window size is the subagent's own, set by its model rather than the parent's. Delegate to a smaller model and you have delegated into a smaller window, which is not the same as delegating to a cheaper one.

Only the final message comes back, and the working is discarded

The return path is as narrow as the outbound one. "Only the subagent's final text response comes back to your context, plus a small metadata trailer with token counts and duration."

Everything else — every file it read, every command it ran, every intermediate conclusion — stays in its context and disappears with it. There is no way to ask afterwards what it saw at step four.

It is also why a delegation feels like it "dropped" something. The subagent did not; the summary did, and a summary preserves only what it was asked to preserve. It can narrow twice, too, because the parent receives that final message as a tool result and may summarise it again in its own reply.

So specify the return value the way you would a function's. Report the path and line of every call site, and the exact error string returns something usable. Have a look and let me know returns prose.

The tool list is narrowed, not handed over

A subagent starts from the tools available in the main conversation, then loses some. Two filters run.

The first removes a fixed handful from every subagent regardless of its tools field — things that only make sense in a main session, such as asking you a question directly. The second applies to background subagents, the default in interactive sessions: they keep their MCP tools but only a reduced set of built-ins.

The consequence is easy to miss: the same definition can resolve to different tools depending on where it runs. A subagent that behaved in the foreground and looks inert in the background has not been misconfigured, it has been filtered.

Whether it then actually uses the tools it kept is a separate mechanism with its own failure modes, covered here.

A fork is the one subagent that inherits everything

There is one deliberate exception to every paragraph above.

A fork inherits the entire conversation so far — the same system prompt, tools, model and message history as the main session. It drops the input isolation on purpose, so you can hand it a side task without re-explaining anything. What it keeps is the output isolation: the fork's own tool calls stay out of your window and only its final result comes back.

That is the trade stated cleanly. Ordinary subagent: nothing in, summary out. Fork: everything in, summary out. When writing the delegation prompt would take longer than doing the work, the fork is the shape you want.

Isolation is the product, not a limitation

It is tempting to read all of this as a list of things subagents cannot do. Invert it. The isolation is the feature, and the summary is what you are buying: you delegate a log trawl precisely so that ten thousand tokens of output never land in your window. If a subagent could see your conversation and you could see its working, you would have spent the context you were trying to protect.

So the boundary cannot be partially switched off. No setting lets a subagent peek at the parent thread while keeping the savings, because those are the same mechanism seen from two sides. When you want the parent's context in there, you are asking for a fork.

When delegating is cheaper, and when it is strictly more expensive

Delegation has a floor cost, and prompt caching is where it shows. A subagent's prefix differs from the parent's, so: "Its first request doesn't read the parent's cache, because the two prefixes differ, and it warms a cache of its own across its turns."

Every delegation therefore builds context from cold — its own system prompt, its own CLAUDE.md, its own file reads — before doing useful work. A fork does not: its prefix matches the parent's.

That gives a usable test. Delegating is cheaper when the task produces far more output than it needs input: verbose, self-contained, summarisable. It is strictly more expensive when the task needs most of your conversation to make sense, because you pay to rebuild that context and pay again for the summary. Small, chatty, iterative work belongs in the main thread; how any of it lands on your usage meter is its own subject.

Each invocation is a new instance, unless it is resumed

Delegating the same subagent twice continues nothing. Each invocation creates a new instance on a new empty window, and two runs with the same prompt are two independent conversations that can differ for all the ordinary reasons.

Continuation exists, but as a distinct act: Claude can resume a subagent by ID or name, and it keeps its full history — previous tool calls, results and reasoning. The built-in Explore and Plan agents are one-shot and return no ID, so they cannot be continued.

One asymmetry worth holding on to: subagent transcripts live in separate files, so when your main conversation compacts they are unaffected. The parent forgetting does not make the subagent forget.

When a subagent is the wrong shape entirely

The boundary has an outer edge. A subagent reports to its caller and nothing else: it cannot compare notes with a peer. Where the value is in the arguing rather than the answering, that is the wrong topology, and Anthropic draws the line: "Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own."

If your instinct is to spawn four subagents and have them reconcile, note that they cannot. Only their four summaries can, in your window, in sequence.

Four questions that predict a case this page never mentioned

Given any delegation, in any version, answer these before you run it.

1. Does the task make sense on its own? The subagent gets one string plus whatever loads at startup. If it is only intelligible in light of your last thirty messages, say the relevant part in the delegation or use a fork.
2. Have you named the inputs? Paths, error text, branch, decisions already settled. A reference to something "we discussed" resolves to nothing on the other side.
3. Have you named the output? Only the final message survives. Ask for the shape you want — paths, line numbers, verbatim strings — not a verdict.
4. Is the output much larger than the input? That ratio is the whole economic case for delegating. When it is close to one, do the work inline.

Run the payments-API example through them: intelligible on its own, so no fork; name the directory and the symbol; ask for path, line and surrounding call rather than "a list"; and a repository-wide sweep is the high-output, low-input shape delegation exists for. The same four questions place a delegation this article never described — which is why the boundary is worth learning and the fields are not.