How Claude Code's Subagent Forking Works

A subagent that doesn't start from zero

Every subagent Claude Code spawns has always faced the same trade-off: isolation costs context. A fresh subagent starts clean, with its own system prompt and the prompt you hand it, which keeps it focused but means it can't see anything from the conversation that spawned it. Forking removes that trade-off for the cases where you want the opposite: a subagent that picks up exactly where the main session left off.

A fork is a subagent that inherits the entire parent conversation instead of starting fresh. It sees the same system prompt, the same tools, the same model, and the same message history as the main session. You lose the input isolation an ordinary subagent gives you, but you gain something concrete in return: because a fork's system prompt and tool definitions are identical to the parent's, its first request reuses the parent's prompt cache. Anthropic's own documentation is direct about the effect: forking is cheaper than spawning a fresh subagent for tasks that need the same context, because the cache is already warm.

As of Claude Code v2.1.232, released 13 August 2026, fork mode is on by default in every interactive session. That single change reshapes how subagent spawning behaves day to day, not just for forks but for ordinary subagents too, so it's worth walking through exactly what changed and what didn't.

Starting a fork yourself

The direct way to start one is /subtask, available since v2.1.212:

/subtask draft unit tests for the parser changes so far

The fork appears in a panel below your prompt and runs in the background while you keep working. When it finishes, its result arrives as a message in your main conversation, the same conversation it forked from, carrying full context of everything discussed up to that point.

Claude can also start a fork on its own, by requesting subagent_type: 'fork' through the Agent tool, whenever fork mode is enabled for the session. You control whether it can with fork mode itself, which is on by default in an interactive session. To stop Claude from spawning forks while leaving other subagent behaviour untouched, deny the fork subagent type specifically:

{
  "permissions": {
    "deny": ["Agent(fork)"]
  }
}

What "on by default" changed about background execution

Before v2.1.232, whether a subagent ran in the foreground or background was a judgement call Claude made per task: foreground when it needed the result before continuing, background when it didn't. That judgement call still applies when fork mode is off, which is the default in non-interactive mode (-p) and in the Agent SDK unless you turn it on.

With fork mode on, that judgement call disappears for non-teammate spawns. Anthropic's documentation states it plainly: where fork mode is on, Claude Code runs the subagent in the background, forks and non-fork subagents alike, and Claude can't ask for the foreground. In practice, that means the classic pattern of "spawn a subagent, wait for it, use the result in this same turn" no longer happens automatically inside an interactive session. Results come back asynchronously, as a message in the conversation once the subagent finishes.

Two escape hatches exist if you need different behaviour:

• Per-subagent, keep it in the background regardless of fork mode. Set background: true in the subagent's own definition file. The one restriction: Claude Code refuses, with an error, to spawn a teammate's subagent whose definition sets background: true, since a teammate in agent teams is expected to report back directly.
• Session-wide, force everything to the foreground. Set the environment variable:

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

This runs every subagent in the foreground, in every kind of session, whether or not fork mode is on, overriding the default entirely.

How deep subagents can nest

Subagents can spawn their own subagents, up to a configurable depth below the main conversation. That default has moved twice this year: v2.1.217 through v2.1.218 defaulted the limit to one layer, meaning a subagent couldn't spawn its own subagent unless you raised it by hand. v2.1.219 raised the default to three layers, where it stands as of this writing.

To change it, set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH in settings.json. This example caps nesting at two layers below the main conversation:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

At the depth limit, Claude Code withholds the Agent tool from every subagent except a fork, so a subagent at the limit does its delegated work itself and returns one summary rather than delegating further. A fork at the limit is treated slightly differently: it keeps Agent in its inherited tool list (because it inherited the parent's full tool set), but calling it returns an error instead of actually spawning anything. Either way, a fork can't spawn further forks, and forks can't request worktree isolation for themselves; only the parent session can pass that parameter when it starts a fork.

Where skills fit into fork mode

A skill's frontmatter can set context: fork, which runs that skill's work as a fork subagent rather than inline in the main conversation. This has its own default-behaviour history worth knowing:

• v2.1.221 (4 August 2026): skills with context: fork began running in the background by default too, with a per-skill opt-out via background: false in the skill's own frontmatter.
• Same release: skill and plugin frontmatter booleans started accepting yes/no/on/off/1/0, case-insensitive, alongside the existing true/false.
• v2.1.222 (4 August 2026): the refusal message Claude gets when it tries to invoke a skill marked disable-model-invocation was improved, so Claude now asks you to run the skill directly instead of quietly trying to replicate its workflow from memory.

If you're writing a skill that does meaningful multi-step work and don't want it silently backgrounded, set background: false in its frontmatter explicitly, since the default changed under it without any action required on your part.

A quick reference

Why this matters if you run skills across a team

None of this changes how Agent Skills are discovered or activated; a skill Claude is already permitted to call still fires the same way during a fork as it would in the main conversation. What changes is invisible until you go looking for it: a task that used to block your prompt while a subagent worked now returns control to you immediately, with the subagent's result landing later as a message. For teams running long, cache-heavy subagent workflows, that's a meaningful throughput change, and for anyone who wrote automation assuming a subagent call blocks until it resolves, it's worth testing against the new default rather than assuming the old behaviour still holds.

If your workflow genuinely needs a subagent's result before the current turn continues, don't fight fork mode session-wide. Set background: true deliberately where you want backgrounding guaranteed, or reach for CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 only as a blunt, session-wide override when you need the old blocking behaviour back everywhere.

Why prompt cache reuse is the real payoff

The background-execution change gets the headline, but the cache reuse is the part worth understanding if you're deciding whether to reach for a fork over an ordinary subagent in the first place. A fresh subagent has to process its own system prompt and tool definitions from scratch on its first turn, the same way any new conversation does. A fork skips that: because its system prompt and tools are identical to the parent's, the underlying model can reuse the parent's already-computed prompt cache for that shared portion, rather than reprocessing it. The saving applies to the fixed overhead every request in that session carries, not to the actual task-specific work the fork goes on to do, so the benefit scales with how much shared context (a large CLAUDE.md, a long-running investigation, many tool definitions) the parent session was already carrying before you forked.

That's also why forking isn't automatically the right call for every delegated task. A fork carries the parent's entire history into a new subagent, including anything irrelevant to the specific job you're delegating. For a narrowly scoped task that doesn't need the conversation so far, an ordinary subagent with a tight, purpose-built prompt is often both cheaper and more focused, since it isn't paying to carry (and isn't distracted by) context the task doesn't need. Reach for a fork when the task genuinely benefits from everything discussed so far; reach for an ordinary subagent when it would only need a clean slate and one clear instruction anyway.

Troubleshooting

A subagent result never seems to arrive. With fork mode on, results return asynchronously as a message in the conversation once the subagent finishes, not inline in the turn that spawned it. If you're watching the terminal expecting a blocking response, check for a completion message instead, or ask Claude directly whether the background subagent has finished.

Claude Code refuses to spawn a teammate's subagent. This happens specifically when that subagent's definition sets background: true; teammates in agent teams are expected to report back directly, and the two settings conflict by design. Remove background: true from the subagent definition if it needs to run as a teammate.

A fork's Agent tool call errors out instead of spawning anything. Check whether the fork is at the configured spawn depth limit. A fork at the limit keeps Agent in its inherited tool list, since it inherited the parent's full tool set, but the call itself returns an error rather than actually spawning a nested subagent. Raise CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH if you genuinely need deeper nesting.

Boolean frontmatter fields aren't being read the way you expect. As of v2.1.221, skill and plugin frontmatter accepts yes/no/on/off/1/0 case-insensitively alongside true/false. If you're on an older Claude Code version, only true/false are recognised, so confirm your version before assuming a frontmatter typo.

A skill you expected to run inline instead runs as a background fork. Check its frontmatter for context: fork. Since v2.1.221, that setting defaults to background execution; add background: false to the skill's own frontmatter if you specifically want it to run inline and block until it completes.

Where to go next

For coordinating several independent sessions rather than forking within one, see what Claude Code's agent teams feature does. For messaging between separate Claude Code sessions on the same machine or beyond it, see how Claude Code sessions message each other. For the broader distinction between a subagent and an Agent Skill, see Agent Skills vs subagents. Browse the current install paths and catalogue at getclaudeskills.com/platforms/claude-code.