[DOCS] Session docs missing nested-Claude launch guard behavior and recovery guidance

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/how-claude-code-works

Section/Topic

Session behavior guidance in:

• "Resume or fork sessions"
• "Run parallel Claude Code sessions with Git worktrees"

Current Documentation

Current docs describe running parallel sessions and same-session behavior, including:

Same session in multiple terminals ... messages from both get interleaved ... use --fork-session.

And a dedicated workflow for:

Run parallel Claude Code sessions with Git worktrees

There is no note that launching Claude Code inside an already running Claude Code session is now guarded/blocked.

What's Wrong or Missing?

Claude Code changelog 2.1.39 says:

Added guard against launching Claude Code inside another Claude Code session

This is a user-visible behavior change for session management, but the session docs do not mention:

• That nested launches are blocked.
• Why the guard exists.
• What users should do instead (new terminal, worktree, --resume, or --fork-session workflows).

The absence of this note can make session startup failures look like bugs rather than expected guard behavior.

Suggested Improvement

1. Add a short warning/note in how-claude-code-works and common-workflows that nested Claude launches are blocked.
2. Add explicit alternatives:

• Start a separate terminal/worktree for parallel work.
• Use claude --resume / claude --continue for existing sessions.
• Use --fork-session when branching from prior context.

1. Add a troubleshooting callout for "I tried to launch Claude from inside Claude" with the expected behavior and workaround.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/how-claude-code-works | Session semantics discuss resume/fork but not nested-launch guard |
| https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees | Parallel-session guidance does not mention nested-launch guard behavior |
| https://code.claude.com/docs/en/best-practices#run-multiple-claude-sessions | Parallel-session recommendations should align with the new guard behavior |

Total scope: 3 pages affected

Source: Claude Code changelog 2.1.39

Entry: "Added guard against launching Claude Code inside another Claude Code session"