[FEATURE] Add Fork and Backtrack hook event types for session lifecycle tracking

Resolved 💬 4 comments Opened Mar 23, 2026 by mr-lee Closed Apr 21, 2026

Problem

When a user forks a session (/fork or --fork-session) or backtracks to a prior turn, there are no hook events emitted for these state transitions. The only way to detect them is by reading the internal project JSONL files and looking for forkedFrom metadata — which is an unstated dependency on an internal file format.

Hooks are the official integration surface for extending Claude Code, but these two lifecycle events have no hook signals. Every other session lifecycle transition (start, end, compaction) fires a hook — fork and backtrack are the gaps.

Proposed Solution

1. Fork hook event

Fired on the new (child) session when created via /fork or --fork-session.

Stdin JSON should include:

{
  "type": "Fork",
  "session_id": "<new session id>",
  "forked_from_session_id": "<parent session id>",
  "fork_point_message_uuid": "<message uuid where the fork branched>",
  "fork_name": "<user-provided name, if any>"
}

2. Backtrack hook event

Fired when the user rewinds to a prior turn in the conversation.

Stdin JSON should include:

{
  "type": "Backtrack",
  "session_id": "<session id>",
  "backtrack_to_message_uuid": "<message uuid rewound to>",
  "messages_discarded": "<count of messages removed>"
}

3. Enrich SessionStart on forked sessions

When SessionStart fires on a forked session, include forked_from_session_id in the stdin JSON (alongside existing fields). This is the minimal change — even without a dedicated Fork event, this would let hook consumers detect forks from SessionStart alone.

Why This Matters

  • Hook completeness: Every other session lifecycle event (start, end, compaction) fires a hook. Fork and backtrack are state transitions with no hook signal — this is a gap in the integration surface.
  • Backtrack means discarded work: When a user backtracks, anything after the branch point is abandoned. Without a signal, hook consumers can't distinguish completed work from abandoned work.
  • Avoids internal file parsing: The forkedFrom metadata exists in session JSONL, but hooks should be the API. Consumers shouldn't need to read internal file formats to detect basic session lifecycle events.

Related Issues

  • #32631 — Conversation branching spec (fork/merge/tree nav) — hook events would enable automation for that work
  • #37228 — /session-tree visualization — currently reads internal JSONL; would benefit from hook signals
  • #37339 — Pass session_id to all hook types — same theme of enriching hook payloads
  • #12629 — Session branching UI request

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗