How Subagents Get Their Own Context and Tools
A subagent is not a smaller version of the main Claude Code session.
//
Search across all documentation pages
A subagent is not a smaller version of the main Claude Code session.
It is a separate instance, with a context window that starts nearly empty and a tool list that can be narrower than the parent's.
Understanding why that isolation exists, rather than treating it as an implementation detail, is what makes it possible to use subagents well instead of just spawning them reflexively.
Every Claude Code session has a context window, the running record of everything said and done in that conversation so far.
A subagent gets a context window of its own, not a shared slice of the parent's.
When the parent spawns a subagent, it writes a task prompt describing exactly what the subagent should do, and that task prompt is effectively the entire starting point of the subagent's context.
The subagent does not inherit the parent's prior turns, its earlier file reads, or its running train of thought, unless the parent explicitly restates that information in the task prompt.
A simple analogy: handing work to a subagent is like handing a sealed folder of instructions to a contractor, not like looping in a coworker who was already sitting in the room for the whole meeting.
The contractor does the job described in the folder, then hands back a written report. They do not walk back into the room and start narrating everything they saw along the way.
Isolation solves two separate problems, and it helps to name them separately.
The first is context budget. A context window is finite. If a research task takes forty tool calls to explore a codebase, running that research directly in the main session means forty tool calls' worth of file contents, search results, and dead ends all sit in the main conversation's history, whether or not any of it turns out to matter. Delegating that research to a subagent means only the subagent's final summary, not its forty intermediate steps, lands in the parent's context.
The second is tool scope. A subagent can be configured with a tool list narrower than the parent's own permissions.
---
name: codebase-researcher
description: Read-only research into how a specific feature is implemented
tools: Read, Grep, Glob
---
You investigate how a named feature is implemented across the codebase and
report back file paths and a short description of each, in under 300 words.That tools line is a real constraint, not a suggestion. A subagent defined this way cannot call Edit or Write no matter how its task prompt is worded, because those tools are simply not in its available set for that invocation. This is what turns "isolation" from a convenience into an actual security boundary.
When the parent spawns multiple subagents at once, each gets its own independent context, which is exactly what makes running them in parallel safe. Two subagents researching different subsystems cannot accidentally read or build on each other's intermediate findings, because neither one has access to the other's context in the first place.
The isolation model has real trade-offs, and treating it as free would lead to over-using subagents.
Spawning a subagent has latency cost: standing up a new context, running the task, and reporting back is slower than just continuing in the main session for a small, well-scoped task. A one-line lookup does not need a subagent; a forty-step exploration usually does.
Isolation also means a subagent can lose access to nuance the parent session has built up over a long conversation. If the parent has been debugging a subtle issue for twenty turns and spawns a subagent to check one hypothesis, the subagent only knows what the parent's task prompt tells it, not the twenty turns of accumulated context. Writing a task prompt that includes just enough of that context, without pasting the entire conversation, is a real skill, and under-specifying it is one of the most common ways a subagent's report comes back less useful than expected.
There is also a governance angle worth naming explicitly. Because tool scope is enforced per subagent, a project can define specialized subagent roles, a strictly read-only researcher, a test-runner with access to test commands but not source edits, a documentation writer scoped to markdown files only, each with permissions matched to its actual job. That is a meaningfully different security posture than one session with uniformly broad access performing every kind of task.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Work directly in the main session | No latency overhead, full running context available | Every exploratory step consumes the shared context budget | Small, quick tasks tightly coupled to ongoing conversation |
| Spawn one subagent | Keeps exploration out of the main context, can scope tools down | Adds latency, subagent starts with minimal context | A bounded research or isolated task with a clear deliverable |
| Spawn several subagents in parallel | Independent work happens concurrently, no cross-contamination | Coordination overhead, parent must synthesize multiple reports | Multiple genuinely independent subtasks (e.g. auditing separate subsystems) |
Edit in its tool list genuinely cannot edit files, regardless of what its prompt says or how it is asked.Not necessarily. A subagent's tool list can be configured narrower than the parent's, and any tool not in that list is simply unavailable to it, regardless of what the task asks for.
No. The parent only receives the summary the subagent reports back at the end; the subagent's individual file reads, searches, and intermediate reasoning steps are not surfaced to the parent.
Because each subagent's context is independent, their research cannot cross-contaminate. Two subagents investigating separate subsystems will not accidentally influence each other's findings, since neither has visibility into the other's work.
Both, but the security aspect is real, not cosmetic. A subagent scoped to read-only tools cannot make an edit even if its prompt is worded to try to talk it into one, because the tool is not available to call.
Yes, primarily latency. Standing up a new context and waiting for the subagent to complete its task and report back takes longer than continuing directly in the main session, which matters for small tasks.
The subagent has nothing else to fall back on, so a vague or under-specified task prompt tends to produce a vague or incomplete report, since the subagent cannot infer missing context from a conversation it never saw.
The mechanism exists in the underlying architecture, but in practice most workflows keep subagent spawning to one level, delegated from the main session, to avoid compounding latency and coordination complexity.
The mechanism is the same kind of context window, but because it starts nearly empty, a subagent typically has much more headroom available for its specific task than the main session does partway through a long conversation.
No. A subagent with Edit or Write in its tool list can still modify files; isolation is about context and permission scope, not about whether it can act on the same codebase the parent is working in.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.
Reviewed by Chris St. John·Last updated Jul 16, 2026