docs: document forking and handing off agent sessions

Merged
AV
2mo ago
+99-11

Summary

  • New Agent Sessions & Forking docs page (/agent-sessions): resume interrupted sessions, the fork-icon menu (Continue with another agent, Fork session), which agents fork natively, how to find session and terminal IDs, the CLI forms, and superset agents read.
  • superset agents create reference gains --fork-session, --from-terminal, and --context-chars, and --prompt is no longer described as required unless --resume-session is set.
  • AI Agents now points to the new page instead of carrying the resume section; adds the Fork Args setting to its settings list.

Why / Context

Session fork and handoff shipped in #6962, but only the blog post and changelog described it. The CLI reference was also wrong: --prompt is optional with any of --resume-session, --fork-session, or --from-terminal, and rejected with --from-terminal.

Every claim comes from the code, not the marketing copy:

  • Flags, mutual exclusion, prompt rules, and the 1-36000 range: packages/cli/src/commands/agents/create/command.ts
  • Handoff prompt and 36,000-character budget: packages/shared/src/terminal-session-handoff.ts
  • Native fork commands (Claude Code, Codex, OpenCode, Pi, Grok, Droid): packages/shared/src/builtin-terminal-agents.ts
  • Fork refused for agents without fork args or when the source session is gone: packages/host-service/src/trpc/router/agents/agents.ts
  • Menu, placement, the disabled Fork state, and the copy-IDs menu: TerminalSessionHandoffMenu.tsx, TerminalIdCopyMenu.tsx
  • The agent's own transcript is read first for Claude Code and Codex, otherwise the recorded terminal stream: transcriptSession in packages/host-service/src/terminal/terminal.ts

Where the blog post and the code disagree (the docs follow the code)

  • "Continue with another agent" does not require a different agent: the picker lists every agent, including the source one.
  • The blog says the handoff prefers the agent's own conversation store. That only applies to Claude Code and Codex, and only while the agent's session is still live in that terminal.
  • The blog calls Droid's fork flag unverified, but the code ships it as a built-in fork command.

Testing

  • bun run typecheck in apps/docs (compiles the MDX)
  • bun run build in apps/docs, on the first commit
  • Dev server: /agent-sessions, /agent-integration, /terminal-integration, and /cli/cli-reference return 200, and the moved anchors (#resume-interrupted-sessions, #fork-and-hand-off-sessions) resolve
  • Not checked in a browser. No prose lint was run: biome does not cover MDX and the repo has no vale config.

Notes

  • The screenshot is copied from the changelog (/changelog/2026-08-30-session-handoff.png).
  • The page URL is /agent-sessions. The title is "Agent Sessions & Forking".

Summary by cubic

Documents session forking and handoff in a new Agent Sessions & Forking docs page, and corrects the agents create CLI reference.

  • Adds the /agent-sessions page covering resume, the fork-icon menu, finding session and terminal IDs, and superset agents read (noting it needs a saved transcript).
  • Moves session recovery out of AI Agents, adds the Fork Args setting, and keeps the old resume anchor pointing to the new page.
  • Documents --fork-session, --from-terminal, and --context-chars on agents create; --prompt is optional with any session flag and rejected with --from-terminal.
  • Clarifies that the fork-command table omits launch flags while Superset actually passes them, and that fork refusal applies only to agents whose transcripts Superset can read.

Summary by CodeRabbit

  • Documentation
    • Added guidance for resuming interrupted sessions, forking sessions within an agent, and handing recent terminal context to another agent.
    • Documented the {sessionId} placeholder and Fork Args configuration, along with supported CLI options, mode constraints, and the terminal-context limit.
    • Added the agent sessions guide to the documentation navigation and updated Agent Settings and terminal integration links to point to it.