[maxthomas95]

Summary

Once a hook has been seen, a hook-driven session ignores output cadence entirely, so any turn ending Claude does not report left the session "running" until something else corrected it. This PR closes the endings hooks can report and adds two bounded fallbacks for the ones they cannot. Part 1 of 2 for the status-detection findings in the 2026-11-09 review.

New Claude hooks observed

• StopFailure — Claude runs it instead of Stop when a turn ends on an API error (rate limit, overload, auth). It completes the turn like Stop. Only the error type is forwarded, never error_details or the message text.
• SessionEnd / SessionStart, installed with a clear|resume matcher, so the helper is not spawned on ordinary startup, compaction or exit.
• elicitation_url_dialog notifications, reported as an elicitation dialog.

Following /clear and in-pane /resume

• When the pane's own conversation ends with reason clear or resume, a session start with a different session id and the matching source is adopted if it arrives within 30 s.
• Adoption moves the native session id, usage tracking (local tracker, or the remote usage reader), subagent rows, and the id used by restart and workspace restore. It also clears the old conversation's subagent and permission state.
• Without that pending end, a mismatched session id is dropped exactly as before. That is what keeps a nested claude -p or claude --resume (which inherits the pane's Tether env) from taking over the pane. Adopted ids must be UUID-shaped.

Ghost subagents

• A parent idle_prompt is now authoritative. Claude only sends it once no background agent is running, so it clears subagents whose SubagentStop never arrived instead of deferring to them forever.

Fallbacks for a stuck "running" (Claude only; Codex is unchanged)

• Silence watchdog: a hook-confirmed running turn with no PTY output and no hook event for 2 minutes drops to cadence mode and shows waiting. It does not fire while hooks report a running subagent.
• Interrupt hint: a lone Esc or Ctrl+C typed into a running hook-driven pane drops it to cadence mode until the next hook, because Claude sends no hook on interrupt. Escape sequences (arrows, focus reports, bracketed paste) do not count.
• A session in either fallback rests at waiting instead of decaying to idle, so the hook that later confirms the pause does not notify a second time.

Overlay

• Install and scrub cover the new event keys, locally and on SSH hosts (same code path).
• Scrub now also removes Tether-managed entries from event keys this version does not install, and leaves keys without one untouched.

Boundaries

• Nothing reads or alters PTY output. The interrupt hint looks at a single input byte and never changes or delays it.
• The helper prints nothing for the new events (a SessionStart hook's stdout is added to Claude's context); the helper tests assert this.
• No IPC, schema, dependency or lockfile changes.

Behaviour change to be aware of

• A confirmed Claude turn no longer stays "running" through unlimited total silence; the test that asserted that now covers Codex, and a new one covers a 30-minute Claude turn that keeps redrawing.

In-app docs updated: src/docs/sessions.md (session states, resume), src/docs/settings.md (CLI hooks).

Test plan

• npx tsc --noEmit
• npx eslint on the touched source and test files
• npx vitest run — 2334 passed, 1 failed: src/main/usage/remote-command.test.ts (real POSIX shell), which fails the same way on the untouched base on this Windows host
• Rate-limited or otherwise API-failed turn: the session leaves "running" as soon as Claude shows the error
• Press Esc mid-turn: the session shows waiting a few seconds after output stops, and one notification fires, not two
• Press Esc while Claude keeps working (for example to close a menu): the session stays running
• /clear in a hooked pane, then send a prompt: status follows the turn, usage shows the new conversation, and restart reopens it
• /resume to another conversation in a hooked pane: same checks; then quit and relaunch to confirm restore reopens the conversation you switched to
• Run a claude -p from a pane's Bash tool: the pane's status and id are unaffected
• Interrupt a running subagent: the parent leaves "running", and the child row stops showing running within about a minute
• Long foreground tool run (several minutes, spinner visible): the session stays running throughout
• SSH environment with remote hooks: /clear moves remote usage collection to the new conversation

Out of scope

• PermissionRequest (instant permission state) and an input-side "permission resolved" hint
• agent_needs_input and the quota_auto_resume_* notification types
• Helper timeout changes
• A status inspector
• /branch and other fork session starts: no SessionEnd reason identifies them, so the pane is not followed there

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud