Claude Code Fork Subagents: A Headless Migration Runbook

Claude Code fork subagents change what an unattended worker can receive before it makes its first tool call. Anthropic’s v2.1.302 release, published October 16, 2026, enables forks by default in print mode, the Agent SDK, Desktop and VS Code. A fork inherits conversation history rather than starting with a fresh delegation prompt. That makes an upgrade a context-distribution decision as well as a scheduling change.

The operating lesson is concrete: approve the delegation boundary before promoting the version. Establish what a child receives, which conversation can continue while it works, and what evidence closes every outstanding descendant. A successful parent response cannot substitute for those checks. This guide proposes a migration procedure; it does not report tests performed on a running installation.

Separate the shipped change from older documentation

Start with a version-specific reading of the release. It names three changes relevant to delegation: fork availability expands to the listed surfaces; Desktop and VS Code always background the main conversation’s subagents; and a subagent’s own Agent calls become foreground by default in print mode, the SDK, Desktop and VS Code. Those are separate decisions. Availability of the fork type does not mean every delegation becomes a fork.

The fetched subagent documentation still says fork mode is off by default in print mode and the SDK. Its scheduling sections also describe earlier defaults. Treat that discrepancy as documentation lag against the explicit v2.1.302 release, and record it in the migration ticket. Use the documentation for mechanisms such as inheritance and permission handling, while testing scheduling against the new release’s stated behavior.

1. Record the exact Claude Code version and SDK package version independently.
2. Save the release reference and the documentation read date with the migration decision.
3. Mark conflicting default descriptions as unresolved documentation, rather than silently combining them.
4. Establish observed behavior on the intended runtime before expanding deployment.

Source capture requested from Anthropic’s GitHub release page. It identifies the release; the delegation changes appear within its longer notes and may require scrolling on the original page.

This is a focused delegation migration. The broader CLI upgrade canary procedure remains the place for general default drift. Here, the unit of acceptance is a parent, its child and any nested child, with their context and completion relationships recorded separately.

Inventory lanes by context and delegation depth

Build the inventory around actual entry points. A nightly print-mode job and an SDK application can use the same model while differing in approval handling, stream consumption and process lifetime. Desktop and VS Code introduce another distinction: a visible main conversation can continue while delegated work remains active. Name each runtime instead of writing one organization-wide row called Claude.

For each lane, identify its accountable owner, current version, delegation types, maximum permitted depth, sensitive inputs and completion consumer. Include installed agent definitions and effective settings sources. A project definition can differ from a user definition with the same name, and the documentation describes precedence among managed, session, project, user and plugin definitions. Record the resolved definition, not merely the file someone expected to load.

Inventory field	Decision it supports
Entry point and exact versions	Which shipped defaults apply
Fork permitted or explicitly disabled	Whether conversation inheritance is authorized
Parent context classes	Which information could reach a fork
Child types and permitted depth	Which delegation paths need probes
Effective permission mode	Which approval mechanism must work
Approval destination and owner	Who can resolve a blocked child
Completion consumer	What prevents early downstream acceptance
Rollback owner and configuration	How the lane returns to its approved posture

Give every row a decision: accept forks after evidence, retain a tested non-fork configuration, or hold promotion. An unknown context class is a reason to hold that row. It is not a reason to assume that a child receives less information than its parent.

Keep the scope distinct from general subagent orchestration. That guide helps choose a collaboration pattern. This inventory asks whether an existing lane remains acceptable when a new delegation option inherits its conversation. The owner should be able to explain that choice without relying on a model’s promise to use the option sparingly.

Probe inheritance with synthetic context

A fork inherits the parent’s system prompt, tools, model and message history, according to the subagent documentation. A non-fork starts from its definition and delegation message, although other startup material can still load. Conversation inheritance therefore removes the input isolation operators may associate with a fresh subagent. A separate context window does not make inherited information disappear.

Use invented markers rather than real confidential content. Put a distinctive phrase early in the parent conversation, introduce a different phrase in the delegation request, and place a third marker in an allowlisted fixture file. Give each marker a different purpose so that the resulting transcript can distinguish inherited history, explicit handoff and a later file read. Do not ask the model to guess where information came from. Inspect the recorded messages and tool activity.

1. Prepare a synthetic parent conversation with a historical marker and a harmless constraint.
2. Request a fork for a small task that needs the historical marker.
3. Record the requested agent type and the child’s observed inputs and output.
4. Repeat with an explicitly selected non-fork definition and a minimal delegation prompt.
5. Compare what the child received with what it subsequently fetched through tools.
6. Repeat after the lane’s normal setup steps, including any declared instruction loading.

The acceptance condition is a documented match between intended and observed information flow. A non-fork might learn a marker because the parent copied it into the handoff; that does not demonstrate history inheritance. Conversely, a fork that can repeat a historical phrase has shown a meaningful exposure even if it never opens a file.

Keep credentials out of both experiments. Anthropic’s secure-deployment guidance recommends placing sensitive resources outside the agent’s security boundary and limiting filesystem and network access. Apply that principle before adding real data. Read-only access can still expose secrets, and a worktree separates repository edits without creating an independent credential boundary.

Measure parent and nested-child waits separately

Test scheduling as an event order. At minimum, distinguish the main conversation, its delegated child and that child’s nested worker. The release changes behavior at different depths, so a single observation that delegation ran in the background is insufficient. Name the immediate parent for every launch and capture when each level starts, continues and finishes.

Use a harmless fixture with two independently recognizable milestones. The child must produce its first milestone before the nested worker completes; its final milestone should require the nested result. The main conversation has a separate small task it can perform while the child runs. Arrange a controlled delay in the fixture environment, rather than relying on a naturally slow model response to establish ordering.

Original explanatory timing diagram. It illustrates the distinction to test, based on v2.1.302’s Desktop and VS Code main-conversation behavior and listed nested-call default. It is not a measured trace or a guarantee for every override.

Probe	Required observation	Hold condition
Main delegates to child	Launch and main continuation order	Order cannot be established
Child delegates to nested worker	Immediate parent’s wait and nested completion	Child reports final success without required nested result
Nested worker fails	Failure reaches its consumer	Parent substitutes an unsupported success summary
Operator interrupts	Remaining descendants are accounted for	A worker’s state becomes unknown

Run these probes separately in print mode, the SDK and each interactive surface you actually deploy. Do not infer print-mode main-parent scheduling solely from the release’s Desktop and VS Code sentence. Record that runtime’s result directly. Likewise, foreground by default is not a promise that every possible explicit configuration produces the same schedule.

The documentation describes special handling for background descendants in interactive versus non-interactive sessions. Because those descriptions coexist with older fork defaults, include a deliberate background-nested case if your lane permits one. Establish where its result arrives when its launcher ends. That exception deserves its own recorded outcome rather than being hidden behind the ordinary foreground probe.

Verify permissions at the child’s actual tool call

Permission inheritance needs an execution-level check. The SDK permission reference says subagents generally inherit the parent mode, with defined exceptions when the parent uses default, dontAsk or plan and the child definition specifies a mode. Parent auto, acceptEdits or bypassPermissions cannot be treated as a restrictive child definition merely because that definition contains a more cautious-looking field.

Test the effective mode with a harmless operation whose outcome you control. Use an isolated fixture destination and a narrow rule. Record the tool request, the decision mechanism, the result and the resulting state. Permission testing should establish that an operation was blocked or approved at execution, not that the assistant described the intended policy correctly.

1. Make the parent mode explicit in the test configuration.
2. Record the child definition’s requested mode, if any.
3. Trigger one operation that should proceed and one that must be denied.
4. Confirm both outcomes from tool evidence and fixture state.
5. Repeat the denied operation at the nested depth the lane allows.
6. Check that a child message claiming approval cannot replace the real permission decision.

Be precise about allow rules. The SDK reference says allowedTools pre-approves listed tools; it is not a complete tool-availability allowlist. Unlisted tools can remain available, and calls requiring no approval can still run. A callback also does not see every call: earlier approvals can resolve it first. If a check must cover every tool invocation, the documentation directs operators to PreToolUse hooks.

That distinction matters during migration because a fork inherits the parent’s tool pool. A callback log with no entries does not prove that the child made no calls. It may prove only that its calls were resolved earlier. Compare attempted tool activity with callback activity before declaring coverage. Use the existing fleet permission guide for the house policy; this probe verifies its effective behavior across delegation depth.

Make approval waits observable and bounded

The SDK user-input guide states that canUseTool can remain pending indefinitely. Execution stays paused until the callback returns. An application that records only process liveness can therefore mistake a permission wait for useful work, especially when the waiting request belongs to a child rather than the main conversation.

Give the approval destination a named owner and a finite operating procedure. The timeout you choose is an application policy, not a new vendor default. On expiry, record a denied, cancelled or deferred outcome according to your implementation; do not manufacture approval to keep the run moving. If using the documented defer mechanism, verify persistence and resumption in the same fixture before depending on it.

Situation	Operator policy to implement and test
Child needs approval	Show the requesting worker and exact proposed operation
Nobody is attending	Deny or use a tested persisted deferral path
User declines	Preserve denial and verify no prohibited side effect
Request is cancelled	Close the pending request and reconcile worker state
Approval is granted once	Verify the executed input matches that decision

Do not assume every child can ask clarifying questions through the same tool surface. The user-input documentation lists AskUserQuestion as unavailable in Agent-tool subagents, while fork documentation describes broader inherited tools. That tension is another reason to probe the exact fork and non-fork paths. Route unresolved requirements back to the parent through an explicit contract instead of designing unattended success around an unverified question path.

For interactive background work, the subagent documentation says permission prompts surface in the main session. Test that the prompt identifies the requester and that denial affects the intended operation. Avoid a session-wide grant during the probe: the documentation warns that choices lasting beyond one call can apply across the whole session.

Reconcile every child before accepting the run

Build a small acceptance record outside the parent’s prose answer. It should associate each observed worker with its immediate parent, requested type, start, terminal state and output evidence. These are proposed operator fields, not a claimed built-in SDK receipt schema. Populate them from the events and transcripts your application actually receives, and leave unsupported fields unknown rather than inferring success.

The SDK hooks guide documents SubagentStart and SubagentStop, agent identifiers and transcript references. It also documents important limits: hooks may not fire at a turn limit, and a timed-out SubagentStop callback can leave the subagent stopping without that callback’s decision. A lifecycle hook is useful evidence, but it cannot be the only mechanism determining completeness.

Original editorial coverage chart. Filled cells identify proposed required checks; they represent no measured pass rate or completed test run.

1. Register each observed delegation before consuming its result as accepted work.
2. Attach terminal outcomes and transcript evidence to the correct worker.
3. Reject completion when a required child remains running, partial or unknown.
4. Inspect partial output separately from success, including API-error cases.
5. Reconcile fixture state against every claimed side effect.
6. Retain the evidence after the interactive task row disappears.

For interruption testing, stop the parent while a child is active, then repeat while a nested worker is active. Determine whether workers stop, remain active or become unreachable through your application. Record the observed behavior without assuming cancellation cascades. Exercise the lane’s documented stop controls and verify that its downstream consumer withholds acceptance until outstanding work is resolved.

This extends the evidence discipline in fleet replay: preserve what happened outside a short-lived status display. The nearby Qwen completion guide addresses another product’s background tasks; its existence does not establish Claude behavior. Here, the practical requirement is a delegation tree whose unresolved nodes prevent acceptance.

Promote one lane with an explicit fallback

Choose a canary with synthetic inputs, a real owner and the same approval and output-consumption paths as production. Changing those paths for the test defeats the purpose. First establish a baseline under the lane’s approved configuration, then introduce v2.1.302 with the intended fork setting. Compare inheritance, scheduling, denied operations and completion reconciliation before judging task quality.

Anthropic documents CLAUDE_CODE_FORK_SUBAGENT=0 as the fork opt-out. Use it where conversation inheritance has not been accepted, but test the resulting lane again: turning fork mode off does not disable all delegation or necessarily restore every scheduling behavior changed in this release. An opt-out is a specific control, not a complete version rollback.

1. Hold deployment while any context or approval boundary remains unknown.
2. Accept only the tested runtime, settings and delegation depths.
3. Record the owner’s decision and links to the probe evidence.
4. Keep the prior approved version and configuration available through the normal release process.
5. Re-run the focused probes after changing agent definitions, permission settings or result consumers.

A lane earns promotion when its owner can show what each worker received, why each consequential tool call proceeded, and how every required descendant ended. Preserve unknown as an operational state. The durable control is the acceptance contract around delegation, even as future versions change which worker starts fresh, which inherits history and which parent waits.

Sources

1. Anthropic: Claude Code v2.1.302 release.
2. Anthropic: Create custom subagents.
3. Anthropic: Configure SDK permissions.
4. Anthropic: Intercept and control behavior with SDK hooks.
5. Anthropic: Handle approvals and user input.
6. Anthropic: Securely deploying AI agents.