Subagents: delegating in an isolated context

A subagent runs a task in its own context window, separate from the main conversation. When it finishes, only its conclusion comes back into your thread: the files read, the logs scanned and the dead ends explored stay in its own context. A good delegation gives a complete objective and a named write scope.

A subagent runs a task in its own context window, separate from the main conversation. When it finishes, only its conclusion comes back into the thread you follow: the files read, the logs scanned and the dead ends explored stay in its own context.

What loads at startup, and what does not reach it

A standard subagent receives its own system prompt, the delegation message you wrote, the repository's CLAUDE.md hierarchy and a git status snapshot read when the subagent starts (except the Explore and Plan agents), the content of each skill named in its skills field, and the list of the session's other named agents when it has SendMessage. The main session's output style and automatic memory do not reach it.

Concurrency limits and the safety net

A session does not run an unlimited number of subagents at once: the default limit is twenty simultaneous subagents, adjustable through CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, and a subagent can only spawn another one to three levels of depth by default beneath the main conversation, adjustable through CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH.

Objectif : lister les fichiers de configuration d'un dépôt fictif
et résumer en une ligne le rôle de chacun.
Périmètre d'écriture autorisé : aucun.
Interdiction explicite : aucun commit, aucun push, aucune commande destructive.
Modèle : sonnet.

A good delegation prompt gives a complete objective, a named write scope, explicit prohibitions and a chosen model rather than an inherited one: a subagent cannot come back and ask you a question mid task.

Claude Code scans a subagent's final report before the main model reads it, because a source the subagent read (a file, a web page, a command output) may carry an instruction addressed to the main conversation. No subagent escapes this.

Fork, a variant that isolates nothing

A distinct variant, fork, invoked by /subtask, does not start from an empty context: it inherits the entire ongoing conversation up to the moment of the call. Only its final result then joins the main thread, as with a standard subagent, but everything that came before the call was already known to the fork from the start.

A subagent remains a delegation you decide on when the task calls for it. A hook, covered in the next lesson, follows a different logic: unlike a subagent, it never chooses to call the model, it reacts to a lifecycle event decided by the harness.

What changed in October 2026

The Agent tool accepts an effort parameter: Claude runs the subagent at the level you ask for, low for a simple task. A subagent can declare autoCompactWindow to compact earlier than the main conversation. Forks are on by default in claude -p, the SDK, the desktop app and VS Code, and forks launched together know which launch is their own. A subagent is not always the right tool: Anthropic's article of 22 October 2026 reserves them for saturated context, parallel tasks and tool choice.

A subagent stops only its own processes

Stopping node or python by name, or by a command line filter, also kills the tool servers of the machine's other sessions. When a subagent's brief has it start a server or a browser, it must say three things: note the pid of each process started, stop them by those pids, and never stop a process whose pid was not noted. If a tool vanished anyway, /mcp restores it.

Figure 1

The full cycle of a delegation

Side task identified

A search, a log read, or a file walkthrough that will no longer be needed afterwards in the main conversation.

Autonomous prompt written

A complete goal, a write scope, explicit prohibitions, and a chosen model, with nothing dependent on a later exchange.

Execution in isolated context

The subagent reads, writes, and calls tools within its own window, without the detail reaching the main conversation.

Report scanned

Claude Code examines the final report before the main model reads it, to neutralise any instruction slipped into an external source.

Conclusion alone integrated

Only the summary joins the main thread, the files read and the dead ends explored stay in the subagent's context.

The sequence shows what stays in the subagent's context and what alone reaches the main conversation, the conclusion, after the security check.

Figure 2

What reaches a subagent at startup

What loads at startup	Starting context	Session output style	Context window	Invocation
Standard subagent	Its own system prompt, the CLAUDE.md hierarchy and the git status except for Explore and Plan, the named skills	Does not reach the subagent	Sized by its own model, not the parent's	Agent tool, starts with an empty context
Fork	The entire ongoing conversation, already under way at the time of the call	Also inherits the ongoing conversation	Sized by its own model	/subtask command

The table isolates four elements and compares a standard subagent, which starts empty, with fork, which inherits the entire ongoing conversation up to the call.

Calibrate it yourself

A developer delegates to a subagent the reading of documentation published on a web page, with instructions to summarise its key points. He then receives the summary displayed on screen and reads it.

Write in one sentence what this situation establishes, and in one sentence what it does not establish.

Your answer, before you see the key

What to remember

A subagent isolates its own context from the start, it shares nothing of the main conversation before you request it.
What it inherits is fixed, its own system prompt, the CLAUDE.md hierarchy, the git status, except for the Explore and Plan agents, named skills, but the output style and automatic memory are not part of it.
A subagent should stop only the processes whose pid it noted, never those a name filter catches elsewhere on the machine.
A subagent's final report is scanned before the main model reads it, because an external source consulted by the subagent may carry a hidden instruction.
A fork inherits the entire ongoing conversation instead of starting empty, and only its final result then joins the main thread.

Do this now

Pick a consequence free search in a repository you know, for example counting files longer than three hundred lines, write a complete delegation prompt on the model of the example above, and run it as a subagent to compare its conclusion with what you would have found yourself.

Check the source

Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.

Claude Code, subagents: effort parameter and autoCompactWindow consultée le 2026-10-24
Anthropic, when to fold subagents into your main agent loop consultée le 2026-10-24
Claude Code changelog: forks on by default, forks told their launch consultée le 2026-10-24