Docs: clarify whether in-place forking (/branch, /btw → f) preserves or tears down the original session's in-flight background subagents/tasks

Open 💬 0 comments Opened Jun 12, 2026 by hjonck

Type: Documentation request

Pages reviewed: interactive-mode, sessions, how-claude-code-works, sub-agents (code.claude.com/docs)

Gap: The docs do not specify what happens to a session's in-flight background subagents / background tasks when the user forks in-place — via /branch, or via the f (fork) option on a /btw answer.

What the docs DO establish:

  • A fork is a transcript copy into a new session ID, "leaving the original unchanged" (how-claude-code-works, sessions).
  • Subagents "work within a single session" (sub-agents); Ctrl+X Ctrl+K kills background subagents "in this session" (interactive-mode).
  • Background tasks are "automatically cleaned up when Claude Code exits" (interactive-mode).

What is NOT documented (the questions):

  1. When /branch (or /btwf) "switches you into" the fork in the same terminal, is the original session's runtime detached-and-kept-alive, or torn down? If torn down, its in-flight background subagents would be cleaned up under the exit rule — i.e., forking would effectively cancel them, despite the fork itself being documented as non-destructive.
  2. Confirm (or correct) the inference that the forked session inherits no live runtime state — no running subagents, no background tasks (and, per sessions, no session-scoped permission grants).
  3. If in-place forking does tear down in-flight work, document the safe pattern for forking from a busy session (e.g., let work complete first, or claude --resume <id> --fork-session from a separate terminal).

Why it matters: For orchestration-heavy workflows (long-running background Agent tasks / workflows), the difference between "fork preserves my running workers" and "fork silently kills them" is load-bearing, and currently has to be inferred from primitives rather than read from the docs.

Suggested fix: One short paragraph on the sessions (Branch a session) and/or interactive-mode (/btw) pages stating the fork-vs-background-task lifecycle explicitly.

View original on GitHub ↗