What a Claude Code subagent can and can't see (including why MCP tools can sink it before it starts)

A subagent is a separate Claude instance that Claude starts for a side task. It gets its own context window, system prompt, tool list, and permission settings. It does the work and returns a summary, which keeps a pile of search results or logs out of your main window. The isolation is the feature. It is also why the subagent asks questions you already answered. A fork, which inherits the whole conversation instead of starting fresh, is the exception; it has its own section below.

The context window is the working text the model can see at once: the system prompt, instruction files, the task message, files it has read, and its own replies. A subagent's window is sized by its own model, not by the parent's. That one detail explains a class of failures that look like bad reasoning but are really a budget problem.

Checked against each tool's documentation on 26 October 2026.

Status, 26 October 2026: the docs now describe what loads at startup, but two reported gaps matter. User-level allow rules from settings are reported not to reach skills or subagents (#18950, open). MCP tool schemas can still exhaust a subagent's window. The acute built-in failure was closed as completed on 18 October 2026 (#37793); the budget still applies whenever definitions load upfront. The checks below work either way.

What starts in a subagent#

A non-fork subagent starts with a fresh, isolated context. It does not see your conversation history, the skills you have already invoked, or the files the main conversation has already read. Claude writes a delegation message that summarizes the task, and the subagent works from that.

The system prompt is the agent's own prompt plus environment details, not the Claude Code system prompt. The task message is the delegation prompt. Those two, plus whichever instruction files load, are the whole brief. Everything else the subagent needs must be in the prompt or in a file it reads.

CLAUDE.md is the exception people trip on#

CLAUDE.md is the instruction file that gives Claude standing rules for a project. A custom subagent loads the same hierarchy the main conversation does: user, project, local, managed, and any AGENTS.md loaded as project instructions. The built-in Explore and Plan agents start without it to keep research cheap and fast, and a custom agent with omitClaudeMd: true starts without the user, project, and local files. Managed policy still loads, except for managed subagents.

A subdirectory's CLAUDE.md and matching path-scoped rules can still load on demand if the subagent works with files there. But a rule that must reach the subagent should be restated in the delegation prompt. The docs recommend that for rules like "ignore the vendor/ directory", because the subagent may never trigger the file that contains it.

Its own memory is separate#

If a subagent definition sets memory: user, project, or local, the subagent gets a persistent directory of its own. It can read and write notes there across runs. That is not the main conversation's auto memory; the main store is not loaded into subagents. Subagent memory is part of the auto memory feature, so it has no effect if auto memory is turned off.

Permissions: the mode follows, the rules may not#

Each subagent runs with independent permissions. A custom agent can set permissionMode in its frontmatter; if it does not, it inherits the main conversation's permission mode. The main mode can override the frontmatter: in bypass permissions, accept edits, or auto mode, the subagent runs in that same mode. In plan mode, the subagent stays in plan mode.

A permission rule is a setting that allows, asks about, or denies a tool or command; Claude Code enforces it rather than the model. Built-in subagents inherit the parent conversation's permission rules. Permission rules still apply to a custom subagent's tool calls; the reported gap is user-level allow rules, below.

There is a reported gap. In #18950, measured on Claude Code 2.1.12, allow rules from a user-level ~/.claude/settings.json were not applied inside skills or subagents: commands that ran without a prompt in the main conversation prompted every time inside the subagent. The issue is open. If you rely on a user-level allow rule inside a subagent, test one command before trusting it. The report's workaround is a workspace-level permission, which applies to the whole project rather than your whole machine. Do not assume "allowed in the main session" means "allowed in the subagent".

MCP tools and the window#

MCP, the Model Context Protocol, is a way to connect Claude to external tools and data. A server exposes tools, and each tool comes with a name, a description, and a JSON schema that describes its arguments. The model needs that schema before it can call the tool.

Tool search changes when the schema is paid for. It is on by default: only MCP tool names and server instructions load at session start, and a tool's full definition loads when Claude searches for it. If tool search is off, an older model does not support it, or a server marks its tools to load upfront, the definitions are charged to the context window immediately.

A subagent inherits the built-in tools and MCP tools available in the main conversation, narrowed by its tools and disallowedTools fields and by the smaller tool set used for background subagents, which run while you keep working. Its window is sized by its own model. A parent running on a 1M-token model can hold a tool set that a child on a 200K model cannot.

That is the mechanism behind the failure in #37793: 34 MCP servers, about 566 tools, and roughly 208,000 tokens of tool definitions against a 200,000-token subagent window. The subagent failed with prompt is too long before its first tool call, and the terminal showed 0 tool uses · 0 tokens. The issue was closed as completed. The closure says Explore now runs on the main session's model and built-in subagents defer MCP schemas through tool search from v2.1.198. The arithmetic still applies whenever definitions load upfront. The closing note names built-in subagents; the docs do not spell out a separate deferral rule for every custom agent, so measure a custom agent's startup cost rather than assuming it behaves like Explore.

How to audit the budget#

• Run /context in the main session. It shows what is using the window, including tool definitions and loaded instruction files.
• Run /mcp to see which servers are connected and what they expose.
• Run /tasks while a subagent is running. It names the model and effort level for that subagent.
• Open the subagent transcript, the saved JSON of its conversation, at ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl. The error is recorded there even when the terminal only shows a short failure.

How to shrink the bill#

• Use tools as an allowlist. A reviewer that needs Read, Grep, and Glob does not need every MCP tool.
• Use disallowedTools: mcp__github or mcp__* to withhold a server or every MCP tool. A specifier such as Bash(git push *) removes the whole Bash tool, so use a permission deny rule for individual commands.
• Define a server inline in the agent's mcpServers field when only that subagent needs it. The parent conversation does not pay for the tool definitions.
• Give the subagent a model with a larger window, or set model: inherit so it uses the main model. The window is per model, not a global setting.
• Remove servers you do not use. Tool search keeps names cheap, but it does not make an unbounded set free.

Resume, fork, and the two ways to get context back#

Each subagent invocation is a new instance. If the work needs to continue, Claude can resume the subagent with the SendMessage tool, using the agent ID or name it received. A resumed subagent keeps its full conversation history, including earlier tool calls and results. Explore and Plan are one-shot and return no agent ID, so they cannot be resumed. Transcripts persist within the session and are deleted after cleanupPeriodDays, 30 days by default.

A fork is the exception to isolation. It is a subagent that inherits the entire conversation so far: the same system prompt, tools, model, and message history as the main session. Its own tool calls stay out of your conversation, and only the final result comes back. Start one with /subtask followed by the task. A fork shares the parent's prompt cache, the reused part of a request that keeps repeated context cheap, so it costs less than a fresh subagent for work that needs the same context. A fork cannot spawn another fork.

Use a fresh subagent when you want the side task to stay out of your context. Use a fork when the task needs the context you already have. If neither fits, restate the missing facts in the delegation prompt; there is no hidden channel into the subagent's window.

What to check when a subagent fails#

• It did nothing and reported 0 tokens. Look for prompt is too long in the subagent transcript. That is the tool-definition budget, not a bad task.
• It ignored a project rule. Check whether it is Explore or Plan, whether the definition sets omitClaudeMd, and whether the rule lives in a subdirectory that never loaded. Restate the rule in the prompt.
• It asked for permission you already allowed. Check whether the rule is user-level or project-level. The user-level gap is #18950.
• It lost earlier work. Each invocation starts fresh. Ask Claude to resume the same subagent rather than spawning a new one.
• It returned a partial answer. A subagent that hits maxTurns returns output marked partial, and Claude can resume it.

Where to go next#

For the rest of the set, see the Claude Code guides hub.

• Claude Code auto memory explains the store a subagent does not inherit.
• Why your nested CLAUDE.md or path-scoped rule never loaded covers the instruction files that may or may not reach a subagent.
• Why Claude Code keeps asking for permission goes deeper on allow rules and compound commands.
• Context compaction covers what happens when a window, including a subagent's, fills up.
• Persistent memory for Claude Code and Codex compares the wider set of memory mechanisms.