Subagents: delegating in an isolated context

A subagent handles a task in an isolated context window and returns only its conclusion, which keeps the main conversation clean and allows several to run in parallel.

A subagent runs a task in its own context window, separate from the main conversation. When it finishes, only its conclusion returns to the thread you are following: the files it read, the logs it went through, and the dead ends it explored stay in its own context, never in yours. This is what lets you delegate a large search without flooding the main conversation with results you will never look at again.

What loads at startup, and what does not reach it

A standard subagent does not start from nothing: it receives its own system prompt, distinct from that of Claude Code, the delegation message you wrote, the full CLAUDE.md hierarchy of the repository and a snapshot of the git status taken at the start of the main session, except for the Explore and Plan agents which are deprived of it, the full content of each skill named in its skills field, and the list of sibling agents launched in the same batch. Three things, on the other hand, do not reach it: the output style chosen for the main session, automatic memory, and the context window size of the conversation that launched it, since its own is sized by its own model.

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. Beyond that, a new delegation fails with a limit reached message rather than silently degrading the session.

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 well built delegation prompt looks like this example: a complete goal, a named write scope, explicit prohibitions, and a model chosen rather than inherited by default. Nothing should depend on a later exchange, since a subagent cannot come back and ask you a question mid task.

A subagent's final report is not read as is by the main model: Claude Code scans it first, because a subagent may have read a file, a web page, or a command output that you yourself never reviewed, and the text of that source may carry an instruction addressed to the main conversation rather than to you. This check applies to every report, with no declared exception for a trusted subagent.

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. The choice between the two depends on what the task needs to know: an autonomous search needs no history at all, a continuation of reasoning already under way needs all of it.

Explicitly declaring the model is not a cosmetic detail: a hook, unlike a subagent, never chooses to call the model, it reacts to a lifecycle event decided by the harness.

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.
Twenty subagents by default can run at the same time in a session, and a chain of delegations does not go beyond three levels by default beneath the main conversation, two caps adjustable through environment variables.
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, what is inherited, Explore and Plan exceptions, concurrency and depth limits consultée le 2026-09-02