How Subagents Get Their Own Context and Tools
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.
Summary
- Core Idea: a subagent runs in its own context window and with its own scoped tool permissions, separate from the session that spawned it.
- Why It Matters: without isolation, every exploratory step a subagent takes would consume the main session's context budget, and every subagent would have full access to everything the parent could touch.
- Key Concepts: context window, isolated context, tool scoping, task prompt, summary report, parent session.
- When to Use: research that would otherwise flood the main session with intermediate detail, work that should not be able to touch certain tools, or independent tasks that can run in parallel.
- Limitations / Trade-offs: isolation means a subagent cannot see the parent's prior conversation unless it is explicitly included, and spawning one adds real latency for small tasks.
- Related Topics: parallel subagent research, the Claude Agent SDK, custom slash commands, hooks.
Foundations
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.
Mechanics & Interactions
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.
Advanced Considerations & Applications
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) |
Common Misconceptions
- "A subagent has access to the whole conversation so far, just in a separate window." It does not. Its context starts essentially empty, seeded only with the task prompt the parent writes; anything the parent doesn't explicitly include is invisible to the subagent.
- "Scoping a subagent's tools is just an organizational nicety." It is an enforced constraint. A subagent without
Editin its tool list genuinely cannot edit files, regardless of what its prompt says or how it is asked. - "Subagents share the same context budget, just split up." Each subagent gets its own independent context window; spawning three subagents does not divide one shared budget three ways, it creates three separate ones.
- "Using a subagent is always more efficient than doing the work directly." For a small task, the setup and report-back overhead of a subagent can cost more than just doing the work in the main session; isolation pays off once the task is large or independent enough to justify it.
- "A subagent can freely go back and ask the parent for more context mid-task." A subagent generally operates on the task prompt it was given upfront and reports back once; it does not have an open channel to interactively query the parent session while working.
FAQs
What does a subagent actually start with in its context window?
- Just the task prompt the parent session wrote when spawning it.
- No prior conversation history from the parent, unless explicitly included in that task prompt.
- No memory of any other subagent that may be running in parallel.
Can a subagent use any tool the parent session can use?
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.
Does the parent session see everything the subagent did while working?
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.
Why does isolation matter for running several subagents in parallel?
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.
Is scoping a subagent's tools mainly about convenience or about security?
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.
Does spawning a subagent cost anything besides the isolation benefit?
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.
What happens if a task prompt to a subagent is too vague?
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.
Can a subagent spawn its own subagents?
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.
Is a subagent's isolated context window the same size as the main session's?
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.
How does the parent session decide when to spawn a subagent instead of doing work directly?
- The task is exploratory and would generate a lot of intermediate detail not worth keeping in the main context.
- The task should run with narrower tool access than the current session has.
- The task is independent enough to run in parallel with other work.
Does isolation mean a subagent can never affect the main session's actual files?
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.
Related
- Custom Commands, Hooks, and Subagents: What Each One Is For - how subagents differ from commands and hooks.
- Custom Commands & Subagents Basics - a first hands-on subagent spawn.
- Spawning Parallel Subagents for Isolated Research Tasks - putting isolation to work across several subagents at once.
- Subagents vs the Agent SDK: How Claude Code Is Built - the underlying primitives this isolation model is built on.
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.