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

[yacb2]

Preflight Checklist

• I have searched existing requests; this consolidates rather than duplicates them
• 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:

• Add /restart command to restart session from within chat #34320 "Add /restart command to restart session from within chat"
• [Feature Request] Add /restart command to reload Claude Code session without exiting #46948 "Add /restart command to reload Claude Code session without exiting"
• /reload-plugins does not reload hook scripts — stale hooks persist until session restart #55008 "/reload-plugins does not reload hook scripts — stale hooks persist until session restart"
• [FEATURE] Add /reload-skills command to refresh skill discovery mid-session #58733 "/reload-skills command to refresh skill discovery mid-session"
• /reload-plugins breaks inbound channel notifications #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:

• Feature Request: Session Handoff / Continuity Support #11455 "Session Handoff / Continuity Support"
• Feature request: Expose context usage to hooks for autonomous session handoff #54580 "Expose context usage to hooks for autonomous session handoff"
• [Feature] Context-aware session relay: hook events, CLI flags, and env vars for context utilization #50978 "Context-aware session relay"
• [BUG] /compact 95% forever #58996 "/compact 95% forever" — handoff is a bypass when compaction wedges
• [FEATURE] UserIdle hook event for proactive state persistence after N minutes of inactivity #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.

2. /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 [FEATURE] UserIdle hook event for proactive state persistence after N minutes of inactivity #58895) — fires once after N minutes of operator inactivity.
• PreCompact (already requested in Feature request: Expose context usage to hooks for autonomous session handoff #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.

2. 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.

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

4. 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)

[github-actions]

Found 3 possible duplicate issues:

1. MCP servers, hooks, and plugins should auto-reload when config changes — no restart needed #24057
2. Hook subsystem: session metrics in payloads + warm-reset primitive #57306
3. [FEATURE] /handover — user-curated session hand-off with fresh context #54254

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[yacb2]

👎 to the auto-close — this is an intentional consolidation, not a duplicate.

The three issues the duplicate-detector flagged are themselves evidence of the fragmentation this RFC exists to resolve:

• [FEATURE] /handover — user-curated session hand-off with fresh context #54254 /handover — user-curated session hand-off with fresh context is a genuine sibling of the /handoff cluster and was missed in the original write-up. It should be folded into the consolidated list:

  /handoff cluster — Feature Request: Session Handoff / Continuity Support #11455, Feature request: Expose context usage to hooks for autonomous session handoff #54580, [Feature] Context-aware session relay: hook events, CLI flags, and env vars for context utilization #50978, [BUG] /compact 95% forever #58996, [FEATURE] UserIdle hook event for proactive state persistence after N minutes of inactivity #58895, [FEATURE] /handover — user-curated session hand-off with fresh context #54254

• MCP servers, hooks, and plugins should auto-reload when config changes — no restart needed #24057 (auto-reload MCP/hooks/plugins without restart) is adjacent and narrower — covered by the motivation behind the /restart cluster (pick up fresh hooks/skills/MCP in the same terminal without exiting). Relevant prior art for the reload semantics.
• Hook subsystem: session metrics in payloads + warm-reset primitive #57306 (hook subsystem: session metrics + warm-reset primitive) overlaps the "hook-event primitives" half of the proposed design (context-pressure / warm-reset).

None of these supersede the RFC. Its entire purpose is to stop restart/handoff/reload asks from being filed and discussed in isolation — auto-closing it as a duplicate would re-fragment 12+ requests back into separate threads. The preflight checklist already states this consolidates rather than duplicates.

Adding #54254 to the consolidated list above; #24057 and #57306 noted as adjacent prior art.

[kcarriedo]

Strongly in favor of the consolidation. The fragmentation across nine separate threads has been a real source of duplicated effort for anyone trying to build session-spanning workflows on top of Claude Code — we've ended up writing three different prototypes for what is essentially the same primitive.

A few additions that may help shape the design:

Why the process-boundary matters for out-of-process orchestrators. Even with --continue / --resume, the current model is "one human's terminal, one machine." For anyone wrapping Claude Code as a subprocess in a longer scheduler (cron, polling service, CI runner), the missing primitive isn't really "restart in place" — it's "hand off enough state to a fresh subprocess invocation that the new run is functionally continuous." /handoff as you've defined it covers this if the handoff manifest is stable, machine-readable, and writeable by the agent without operator approval steps.

One subtle requirement: deterministic handoff filenames + manifest schema. If /handoff writes to .claude/handoffs/<timestamp>-<hash>.md, an external scheduler can latch onto "latest handoff file" and resume from it on the next invocation without operator action. Conversely, if the path is operator-prompted or non-deterministic, the loop has to involve a human, which defeats the use case. A small concession in the spec (fixed path or argv-overridable path) would unlock the orchestrator class entirely.

/restart vs /handoff should diverge on what carries over.

• /restart: hooks, skills, MCP servers reload from disk; conversation state is preserved (this is the "same operator, same session, fresher harness" case)
• /handoff: conversation state is distilled and reset; hooks/skills/MCP reload as a side effect (this is the "process boundary on purpose" case)

If they merge into one verb, operators will keep getting one when they wanted the other.

Idle-trigger should be optional, not the only path. The UserIdle hook (#58895) is one good trigger, but a manual /handoff invocation and a context-pressure-driven auto-trigger should both be supported as first-class. The idle-only case misses long-running autonomous runs where there is no operator idleness to detect.

Happy to share traces from our wrapper-prototype if useful for the spec.

[csmarshall]

+1 to the consolidation framing. The discipline-based substitute pattern yacb2 describes from the read side has a direct twin on the write side in maury — both ship glue that runs around the trigger gap, not on top of a missing receive surface.

Of the three primitives proposed:

• UserIdle — already canonicalized in [FEATURE] UserIdle hook event for proactive state persistence after N minutes of inactivity #58895; maury's reasoning there still applies.
• PreCompact (Feature request: Expose context usage to hooks for autonomous session handoff #54580) — maury would consume this directly. Compaction is the moment maury's working session-state.md is most likely to be lost; a hook that fires before compaction is the structural answer to "save before context disappears" that today's aggressive-discipline rule can only approximate.
• $CLAUDE_CONTEXT_PERCENT in hook stdin — maury would consume this for proactive persistence: when context crosses a threshold (say 80%), trigger a state-save without waiting for idle. Cheap, always-on, composable with existing hooks.

No opinion on /restart and /handoff themselves — different problem domain for maury (process lifecycle isn't our concern; state persistence across the process boundary is). But the three primitives are the load-bearing piece — without them, every downstream tool reinvents the same brittle wrapper.