Separate context, shared quota

The documentation describes each subagent as running "in its own context window with a custom system prompt, specific tool access, and independent permissions."1 Claude hands it a task. It works on its own and returns its results.

A custom subagent is a Markdown file with YAML frontmatter, and "only name and description are required."1 The body of the file becomes the subagent's system prompt. Claude reads the description to decide when to delegate, so descriptions are meant to stay short: past 15,000 tokens of combined descriptions, Claude Code shows a warning at startup.1

Definitions load from five places, highest priority first: managed settings, the --agents flag for a single session, the project's .claude/agents/ folder, the user's ~/.claude/agents/ folder, and installed plugins. When two definitions share a name, the higher one wins.1

Three main ones come built in, alongside smaller helper agents such as statusline-setup and claude-code-guide. Explore is read-only and searches code. Plan is read-only and gathers context in plan mode. General-purpose gets every tool available to subagents, for work that needs both reading and changing files.1

A subagent starts empty. "It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read."1 Its first context is its own system prompt, the task message Claude writes when it delegates, the CLAUDE.md files the main conversation loads, a git status snapshot, and any skills its file preloads.1 The one exception is a fork, a subagent that copies the whole conversation instead.

Two of the built-ins see less. "Explore and Plan skip your CLAUDE.md files and the git status snapshot."1 Auto memory and the output style never reach a subagent that isn't a fork. For a rule that has to reach the subagent anyway, the documentation's answer is to "restate it in the prompt you give Claude when delegating."1

Tools narrow the same way. A tools list is an allowlist and disallowedTools is a denylist. No subagent gets AskUserQuestion, and one running in the background keeps a smaller set of built-in tools.1

Hooks cross the boundary. "A PreToolUse hook in settings.json also runs before every tool a subagent uses."1 That holds only where the settings file loads at all, which is its own story: the folder where a write guard never ran.

The context window is separate. The quota is not. A subagent "sends its own requests, which count toward the same usage limits as your main conversation."1 The cost documentation says the same: every subagent "sends its own requests on top of the main conversation's," and on Pro, Max, Team and Enterprise plans /usage shows the share of recent usage that went to subagents.2

The main conversation's context isn't sealed off either. Results come back into it, and "running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs."1

Two limits are written down, and both are defaults. A subagent can start subagents of its own "up to three layers below the main conversation," and once 20 are running in a session, the next one fails with Concurrent subagent limit reached; the 20 can be changed with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.1 Neither is a usage limit.

Claude Code picks a subagent's model in a fixed order: the model Claude passes on that call, then the model field in the subagent's file, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model.1 The cost documentation's advice for spending less on subagents is a smaller model, and it states that Sonnet "costs less than Opus."2

My one custom subagent shows the order at work. It looks up documentation, and it sits in my user folder, so every project has it (description shortened):

---
name: docs
description: Look up external documentation — library, API, framework,
  CLI or vendor docs — and return quoted lines with their URLs. Read-only. …
tools: Read, Grep, Glob, WebFetch, WebSearch
model: opus
effort: medium
---

The file says Opus. On 2 October the call that used it asked for Sonnet, and the call comes first in the order. The tools are the part the call can't change. There's no Edit, Write or Bash in the list, so it can't change a file, whatever the task says.

In my setup, subagents that build in parallel are called lanes. The rule in my global instructions is to "split implementation into lanes that own disjoint files, each on the model and effort its job needs." A lane's work is accepted "when its diff stays inside its files and its named checks ran green where you can see the command and exit code."

For a round of work on this site, a rules file tells every lane what it owns: its own pages, and the CSS, JavaScript and images that only those pages load. The files every page shares belong to the main session. A lane that needs a change there describes it in its report, and the main session makes it.

Reading goes to cheaper agents. The rule is to "send cheap agents for recon and act on their quoted file:line evidence." Recon runs on Explore, which skips CLAUDE.md, so that rule can't arrive through the file. The task message carries it instead. One recon prompt from 2 October asked for each claim "VERIFIED or REFUTED … with quoted evidence (file path + line number + the quoted line)."

That day, one session on this site started 26 subagents from the main conversation: nine Explore recon runs on Sonnet, one documentation lookup, and 16 general-purpose subagents for page builds, audits and reviews. The build lanes started 11 more Explore subagents of their own, one layer down.

By the afternoon of 2 October, five or six lanes on Opus had been running in parallel for about three and a half hours. Four Blender sessions were also running on Opus on the same plan. Those are separate Claude Code sessions, not subagents. The usage meter read 99%, and the lanes were stopped mid-work at about 14:40. Five page lanes left unfinished edits in the site's source, and the next session went through them page by page.

I can't say how much of the 99% the lanes used and how much the Blender sessions did. /usage breaks recent usage down by subagent,2 and that breakdown wasn't recorded that day.

The rule now is two lanes at most, each with a time box and a model that fits its job, and the main session does the integration.

Owning separate files keeps two lanes from writing the same file. It doesn't stop a lane from writing after the main session has moved on. Earlier on 2 October, the main session copied the site's source into its deploy mirror while a lane was still editing a page. The check that compares the two failed. The preview was built from the consistent copy, not from the moving one.

The lanes all worked in one checkout. The documentation offers a separate copy per subagent: isolation: worktree runs it "in a temporary git worktree, giving it an isolated copy of the repository."1 These lanes didn't use it. Their edits landed in the shared source.

• How much of the 99% the subagents used. The breakdown exists and wasn't recorded.
• Whether the lanes made the work better or faster than one session would have. Nothing was compared.
• That the documented behaviour holds on other versions. It was read at Claude Code 2.1.288, and the page itself lists defaults that changed between versions.
• Anything about how other people run subagents. This is one setup.