[FEATURE] Add Fork and Backtrack hook event types for session lifecycle tracking
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
forkedFrommetadata 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-treevisualization — currently reads internal JSONL; would benefit from hook signals - #37339 — Pass
session_idto all hook types — same theme of enriching hook payloads - #12629 — Session branching UI request
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗