[FEATURE] Native /restart and /handoff: consolidating 9 open requests + 2 working prototypes

Preflight Checklist

• [x] I have searched existing requests; this consolidates rather than duplicates them
• [x] This is a single coherent design proposal (restart + handoff are intentionally bundled because they share the same underlying primitives)

Problem

Nine open issues request some combination of "restart the Claude Code process from inside the session" or "open a fresh session that knows what the previous one was doing". They are fragmented across two verbs (/restart, /handoff) and several adjacent asks (/reload-plugins, /reload-skills, idle state persistence, context-pressure events). The common need is a way to bridge a process boundary without losing operator state, which today requires either:

• killing the terminal and rerunning claude (loses argv, loses any unwritten context, no continuity),
• claude --continue / --resume <id> (works for transcript replay but reloads tens of thousands of tokens and is local to one machine), or
• third-party shell wrappers and hooks (works, but every operator reinvents it).

Open issues this consolidates:

/restart cluster — CLI process is fine; user just wants fresh hooks/skills/MCP servers in the same terminal:

• #34320 "Add /restart command to restart session from within chat"
• #46948 "Add /restart command to reload Claude Code session without exiting"
• #55008 "/reload-plugins does not reload hook scripts — stale hooks persist until session restart"
• #58733 "/reload-skills command to refresh skill discovery mid-session"
• #46728 "/reload-plugins breaks inbound channel notifications — full restart fixes it"

/handoff cluster — CLI process should end; new one should be seeded with curated state:

• #11455 "Session Handoff / Continuity Support"
• #54580 "Expose context usage to hooks for autonomous session handoff"
• #50978 "Context-aware session relay"
• #58996 "/compact 95% forever" — handoff is a bypass when compaction wedges
• #58895 "UserIdle hook event for proactive state persistence" — handoff is the receive side of the loop

Existing surface (what already works and what's missing)

| Need | Today | Gap |
|---|---|---|
| Same-session continuation | claude --continue | Reloads full transcript, costs context, local to host |
| Resume by id | claude --resume <id> | Same costs; transcripts pruned at 30d on commercial plans |
| Reload plugins | /reload-plugins | Doesn't pick up hook script edits, new skills, MCP changes (#55008, #58733, #46728) |
| Restart in same terminal | (none) | Operators reinvent shell wrappers |
| Fresh session seeded with state | (none) | Operators reinvent handoff files |
| Hook-driven proactive snapshot | (none) | No idle / pre-compact / context-pressure event (#54580, #58895) |

Proposed design (minimum native primitives)

Two built-in slash commands:

1. /restart — re-exec the current claude process with the same argv, preserving terminal, session id (resumable), and any subscribed channels. Picks up fresh hooks, skills, plugins, MCP servers, and binary updates. Does NOT preserve transcript-in-flight unless paired with --continue semantics.

1. /handoff [prompt] — terminate the current session, spawn a fresh one (new session id), inject the operator-provided prompt (or one synthesized by the assistant from current context) into the SessionStart hook's additionalContext, and surface a systemMessage banner so the user can see they're in a handoff session. Does NOT carry the transcript.

Three hook-event primitives that the slash commands and downstream tools both benefit from:

• UserIdle (already requested in #58895) — fires once after N minutes of operator inactivity.
• PreCompact (already requested in #54580) — fires before /compact runs, with a payload describing why compaction was triggered.
• \$CLAUDE_CONTEXT_PERCENT in hook stdin payloads — exposes current context usage so hooks can decide whether to trigger a handoff proactively.

Prior-art prototypes

To validate the design is implementable from outside the binary today, I built two working tools that operators are using in production:

• claude-restart — POSIX shell wrapper plus a UserPromptSubmit hook. Typing restart (zero tokens) or /restart sends SIGTERM, the wrapper re-execs claude with the same argv. Works in zsh/bash/fish.

• claude-session-handoff — same wrapper + SessionStart hook with two output fields (additionalContext for Claude, systemMessage banner for the user). Triggered via /handoff slash command, handoff: prefix (zero tokens), or a natural-language skill.

What the prototypes prove:

• The two-command design is coherent and operators can reason about it.
• The SessionStart hook's additionalContext + systemMessage fields are sufficient for the handoff receive side (no native change needed there).
• The shell wrapper trick works for triggering the re-exec.

What the prototypes can't fake (and is the reason for this proposal):

• Re-exec from inside the TUI without a wrapper — operators have to install one.
• UserIdle / PreCompact / context-percent — these can't be polyfilled from a hook.
• A consistent banner / sessionId story that survives the boundary cleanly.

Open questions

1. Should /restart preserve the transcript? Two reasonable defaults: (a) no, behave like claude fresh; (b) yes, behave like claude --continue. Prototype evidence: most use cases for restart are "I want fresh hooks" — option (a) is simpler and works in practice.

1. Should /handoff synthesize its own prompt when invoked without one? Yes — operator-typed prompts are noisy; the assistant has the synthesized model of "where we are" already.

1. What's the relationship to /clear and /branch? PR #59275 adds /new as /clear + label. /restart and /handoff are different process-lifecycle operations, not session-clearing variants. They should coexist.

1. Should hook events be opt-in via setting? Probably yes for UserIdle (avoid noise) and PreCompact (allow operators to veto). \$CLAUDE_CONTEXT_PERCENT is cheap and could be always-on.

What I'm asking for

• Maintainer signal on whether this design direction is acceptable.
• If yes, I'm happy to draft a PR for the plugins/ scaffolding (slash command markdown + plugin.json) alongside whatever upstream change is needed for the re-exec entrypoint.
• If no, a "won't fix / out of scope" reply is also useful so the nine open issues can be closed with a pointer to community solutions.

Acknowledgements

Prior community efforts that informed this proposal (none of them replace the native primitives, but they prove the demand):

• forty4420/cc-restart — /restart plugin with Desktop / Windows handling
• guvencem/handoff-md — markdown handoff CLI
• @neoacar/claude-handoff — cross-machine session bundling via git
• RecallWorks/Recall — MCP memory server for cross-session state
• 199-biotechnologies work — plan-aware handoff slash commands
• Sourcegraph Amp's built-in handoff (different product, same concept)