[DOCS] Forked subagent docs still say interactive-only for SDK and `claude -p`

[coygeek]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

The "Fork the current conversation" section, plus the CLAUDE_CODE_FORK_SUBAGENT environment variable reference for non-interactive usage.

Current Documentation

The docs currently say:

Fork mode works only in interactive sessions. It is disabled in non-interactive mode, which includes the Agent SDK. A fork cannot spawn further forks.

And the environment variable reference says:

CLAUDE_CODE_FORK_SUBAGENT | Set to 1 to enable forked subagents. A forked subagent inherits the full conversation context from the main session instead of starting fresh. When enabled, /fork spawns a forked subagent rather than acting as an alias for /branch, and all subagent spawns run in the background. Interactive mode only

The claude -p / Agent SDK page is the canonical non-interactive entry point:

This page covers using the Agent SDK via the CLI (claude -p).

but it does not currently mention CLAUDE_CODE_FORK_SUBAGENT or that forked subagents now work in non-interactive sessions.

What's Wrong or Missing?

Changelog v2.1.121 says:

SDK and claude -p: CLAUDE_CODE_FORK_SUBAGENT=1 now works in non-interactive sessions

The current docs still explicitly say fork mode is interactive-only and disabled in non-interactive mode, which now contradicts current behavior.

That leaves automation users with the opposite guidance of what the product now supports. Someone reading the docs would reasonably conclude that forked subagents cannot be used from the Agent SDK or claude -p, even though v2.1.121 added exactly that support.

Suggested Improvement

Update the forked subagent documentation to reflect v2.1.121:

1. Remove the "interactive mode only" limitation from the forked subagent docs and CLAUDE_CODE_FORK_SUBAGENT env var reference.
2. Add a short note in the claude -p / Agent SDK docs explaining that CLAUDE_CODE_FORK_SUBAGENT=1 now works in non-interactive sessions.
3. Clarify any non-interactive-specific behavior or remaining limitations, especially which parts of fork mode apply to SDK / claude -p sessions versus interactive-only UI features like /fork.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Context
https://code.claude.com/docs/en/sub-agents	Forked subagent section currently says non-interactive mode is unsupported
https://code.claude.com/docs/en/env-vars	CLAUDE_CODE_FORK_SUBAGENT entry still says "Interactive mode only"
https://code.claude.com/docs/en/headless	Canonical claude -p / non-interactive page does not mention the new support
https://code.claude.com/docs/en/agent-sdk/subagents	SDK subagents page documents fresh-context subagents but does not cross-reference the new forked-subagent path for non-interactive sessions

Total scope: 4 pages affected

Source: Changelog v2.1.121

Exact changelog entry: SDK and claude -p: CLAUDE_CODE_FORK_SUBAGENT=1 now works in non-interactive sessions

[coygeek]

Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.

[coygeek]

Verified against the latest docs; this still appears unresolved.

[coygeek]

Verified against the latest docs; this still appears unresolved.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.