Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Forked subagent docs still say interactive-only for SDK and `claude -p` [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#54163•Fetched 2026-04-29 06:34:36
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3
RAW_BUFFERClick to expand / collapse

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:

PageContext
https://code.claude.com/docs/en/sub-agentsForked subagent section currently says non-interactive mode is unsupported
https://code.claude.com/docs/en/env-varsCLAUDE_CODE_FORK_SUBAGENT entry still says "Interactive mode only"
https://code.claude.com/docs/en/headlessCanonical claude -p / non-interactive page does not mention the new support
https://code.claude.com/docs/en/agent-sdk/subagentsSDK 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

extent analysis

TL;DR

Update the documentation for forked subagents and CLAUDE_CODE_FORK_SUBAGENT environment variable to reflect the new support for non-interactive sessions.

Guidance

  • Remove the "interactive mode only" limitation from the forked subagent documentation and CLAUDE_CODE_FORK_SUBAGENT environment variable reference.
  • Add a note to the claude -p / Agent SDK documentation explaining that CLAUDE_CODE_FORK_SUBAGENT=1 now works in non-interactive sessions.
  • Review and update the documentation for non-interactive-specific behavior and remaining limitations of fork mode.
  • Verify the changes by checking the affected pages, including the sub-agents, environment variables, headless, and Agent SDK documentation.

Example

No code snippet is necessary for this issue, as it is related to documentation updates.

Notes

The updates should be made to the following pages: https://code.claude.com/docs/en/sub-agents, https://code.claude.com/docs/en/env-vars, https://code.claude.com/docs/en/headless, and https://code.claude.com/docs/en/agent-sdk/subagents.

Recommendation

Apply the suggested improvements to update the documentation and reflect the new support for non-interactive sessions, as this will help resolve the inconsistency and provide accurate guidance for users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#environment variable#network issue#logging issue#authentication issue#prompt issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Forked subagent docs still say interactive-only for SDK and `claude -p` [1 participants]