Playbooks · Coding tasks
Stop fork subagents inheriting your context
Written November 2, 2026
Fork subagents now run by default in headless, SDK, desktop, and VS Code. A fork inherits your history and model — and skips cheap-model routing.
What changed
On 16 October 2026, Claude Code 2.1.302 changed fork subagents — started with subagent_type: "fork" — to be on by default in claude -p, the Agent SDK, the desktop app, and VS Code, as they already were in the terminal. Fork mode is on by default from 2.1.302, and in an interactive terminal session from 2.1.232. The same release made the desktop app and VS Code always run the main conversation's subagents in the background, and made a subagent's own Agent calls run in the foreground by default in headless, SDK, desktop, and VS Code sessions. One surface never offers forks: claude mcp serve. Everywhere else on the list, Claude can now start a fork on its own, without anything configured, and you may never notice. A fork appears in a panel below the prompt, runs in the background while you keep working, and only its final result comes back into your conversation.
What a fork carries
A fork is a subagent that inherits the entire conversation so far instead of starting fresh. That drops the input isolation subagents otherwise provide. The difference, as Claude Code's own docs draw it:
- Context: a fork gets the full conversation history; any other subagent starts fresh, with only the prompt passed to it.
- System prompt and tools: a fork gets the same ones as the main session; any other subagent gets them from its definition file.
- Model: a fork runs the main session's model; any other subagent runs the model named in its definition.
- Prompt cache: a fork shares the main session's cache; any other subagent has a separate cache.
That is the whole trade in one list. A fork needs no re-explanation: hand it a side task and it already knows the situation. But a reviewer fork is not an independent reviewer — it has read the same conversation that produced the code, including the reasoning that led to the mistake. And a fork cannot be routed to a cheaper model: cheap-model routing lives in a subagent definition's model field, and a fork has no definition. It runs the main session's model, at the main session's price, with the main session's history attached. The one genuine saving is cache reuse: because a fork's system prompt and tool definitions are identical to the parent's, its first request reuses the parent's prompt cache. A fork therefore costs less than a fresh subagent for tasks that need the same context. That saving is real and unquantified — no figure for it is published — and it does not offset the model-routing difference on its own. Measure both on your own sessions rather than assuming either direction. A fork also cannot spawn further forks.
Steps
- Check the version you run. This default applies from 2.1.302 (2.1.232 in an interactive terminal session). On an older install the default does not apply. On a newer one it may have moved again: the changelog entry dated 16 October 2026 is the record of this change, and the version on your machine is the one that decides.
- Decide what you actually want to stop. There are three different controls, and they stop different things. Pick the narrowest one that fits:
- To stop forks only, and keep everything else as it is, add
"Agent(fork)"topermissions.denyin your settings. - To turn fork mode off entirely, set
CLAUDE_CODE_FORK_SUBAGENTto0, for example insettings.json. While fork mode is on, Claude also cannot wait for a subagent in interactive terminal, VS Code, or desktop sessions on your machine; turning it off restores waiting. - To keep forks for side tasks but give review work a genuinely fresh reviewer, define a custom subagent for review. A custom subagent starts fresh from its definition, with its own system prompt and its own
modelfield — set it to a cheaper model and the review runs there, without the conversation that produced the code. This is the reviewer-isolation route: it fixes the review problem without touching the fork default.
- To stop forks only, and keep everything else as it is, add
- Set the effort control separately. Claude Code 2.1.316, on 31 October 2026, added
CLAUDE_CODE_SUBAGENT_EFFORT, which sets the effort level subagents run at when nothing else names one, instead of inheriting the session's. Effort is not the model: this variable does not change which model a fork runs — a fork still runs the main session's model — it changes how much effort subagents spend. Set it if subagents are inheriting a session effort level you would not choose for background work. - Remember the manual fork. You can start a fork yourself with
/subtaskfollowed by a task, whether or not fork mode is on. Turning fork mode off stops Claude starting forks on its own; it does not remove your own ability to fork, and a/subtaskfork still inherits everything. - Check the first fork you see. When a fork runs, open its panel row and confirm it is the kind of agent you intended: a side task that genuinely needs the history, not a review that needed fresh eyes. If it is the wrong kind, stop it and re-dispatch as a defined subagent.
A note on the docs
Write-ups published shortly after the change reported that the subagent docs still described fork mode as off in headless and SDK sessions in one passage, while the changelog said on. The subagent docs page carries the same on-by-default wording as the changelog, dated to 2.1.302. Follow the changelog version — the dated change record — and check the version you run. The stale passage was a docs lag, not a second behaviour.
What can go wrong
- Reviewing with a fork and calling it independent. A fork has read the reasoning behind the code. An independent review needs a fresh subagent from a definition, not a fork.
- Assuming the cheap model applies. A
model: haikudefinition routes a defined subagent, not a fork. A fork runs the main session's model whatever the definitions say. - Turning fork mode off to fix one review. The global switch also restores waiting behaviour in interactive sessions. The deny rule, or a defined reviewer subagent, fixes the review problem without changing the rest.
- Forgetting
/subtaskstill forks. The opt-out stops Claude starting forks. Your own/subtaskcommand forks regardless, with full inheritance. - Assuming forks run everywhere.
claude mcp servenever offers them. A setup that depends on forks through that surface is depending on something that does not exist there. - Reading a cost direction as a cost figure. Cache reuse makes a fork cheaper than a fresh subagent needing the same context, and main-model routing makes it dearer than a cheap defined subagent. Neither direction is a number. Measure your own sessions.
Limits
- No cost-impact figure is published for this change, because the changelog quantifies none. Any figure quoted for it is someone's measurement on their own sessions, not a published property of the default.
- The behaviour described is for the versions named. Fork defaults have already moved once — terminal first, then everywhere else — and can move again. The version on your machine and the dated changelog entry are the authorities, in that order.
- SDK behaviour follows the changelog entry, which names the Agent SDK, and the SDK subagent docs. Check the SDK release notes for your installed SDK version before assuming parity beyond that.
Related playbooks
- Claude Code 2.1.318: sign-in expiry and fork effort
- Mistral Vibe 3.1.0: see what fills the context
- OpenCode 2.3.0: subagents move to the background
- Claude Code 2.1.319: unattended runs stop stalling
Sources
- https://code.claude.com/docs/en/changelog
- https://code.claude.com/docs/en/sub-agents
- https://code.claude.com/docs/en/agent-sdk/subagents
Back to: Coding playbooks hub · Also: Run subagents in parallel in Claude Code · What Claude Code hooks cost in tokens · Measure what a background agent summary costs