Emit session-lifecycle events via harness hooks

[williamthorsen]

Problem

The event channel carries no session-lifecycle signal. An ended session persists in the lane view as "idle" indefinitely, a session is invisible until its first instrumented skill emits, and the waiting-on-user state rides the least reliable skill emission point (end of turn). Session end has no skill emission point at all — ending is not a skill moment — and activity-based inference is ruled out: sessions legitimately sit idle for days.

Context

• Both harnesses expose event hooks whose payloads carry session_id and cwd. Confirmed inventory: Claude Code SessionStart, SessionEnd, UserPromptSubmit, Stop; Rovo Dev on_session_start, on_session_end, on_user_prompt, on_complete (configured under eventHooks in ~/.rovodev/config.yml; config is read at startup, so changes require a session restart; a failing hook never blocks the agent).
• Rovo Dev executes hook commands via the shell (/bin/sh -c) and delivers the event payload as JSON on stdin; hook exit codes are semantic (a hook can block the agent). Verified against the CLI itself — the vendor docs' map-keyed eventHooks.events shape is wrong and is rejected as corrupt config; real configs use a list of {name, commands: [{command}]} items. See the codeassembly KB: "Rovo Dev event-hooks config schema and execution semantics".
• The harness configs are user-curated files that must not be clobbered. Add a managed hook-entry utility for Claude Code settings.json #1007 (Claude settings.json) and Add a managed event-hook utility for Rovo Dev config.yml #1008 (Rovo config.yml) provide sentinel-based ensure/check/remove utilities; this ticket supplies the actual entries and wiring, and reworks Add a managed event-hook utility for Rovo Dev config.yml #1008's utility to the verified list schema (it shipped modeling the map shape Rovo rejects).
• Claude Code interprets some non-zero hook exits as control signals (a Stop hook exiting 2 blocks the agent from stopping), so the relay's never-block contract means unconditionally exiting 0.

Proposed solution

One relay helper serving both harnesses, installed into each harness's scripts directory: read the hook payload from stdin, map {harness, hook name} to an event type via a static table, resolve repo and branch attribution against the payload's cwd, and append the event with the payload's session id.

Event	Claude Code	Rovo Dev
session.started	SessionStart	on_session_start
session.ended	SessionEnd	on_session_end
turn.started	UserPromptSubmit	on_user_prompt
turn.completed	Stop	on_complete

Waiting-on-user is derived state (latest event is turn.completed), not an event type. Start/end payload discriminators (Claude's source/reason, Rovo's switch/fork/exit) pass through in event payloads rather than minting distinct types.

Only these four hooks are relayed — not Notification or the tool-level hooks: tool events flood the log with detail the lane view does not render, and Notification overlaps the waiting signal Stop already provides. Distribution is CLI-based config injection, not a Claude Code plugin — a plugin cannot cover Rovo Dev.

Hook configuration is a discrete CLI step (configure-hooks) that install invokes by default — decoupling it later is a one-line removal. It injects the entries via the #1007/#1008 utilities, supports --skip-hooks on install, and offers configure-hooks --print emitting snippets for externally managed configs; touching the Rovo config prints its restart reminder. status reports each harness's hook entries as present, drifted, or absent via the same catalog, giving the check utilities their consumer. Ownership rides an inert --sentinel argument the relay accepts and ignores — not a shell comment, so it survives any execution semantics. Hooks carry the session-lifecycle family; skills keep the work-narration family (skill.*, artifact.written, pr.created) — two complementary channels, not a replacement.

Acceptance criteria

Must have

• A session is visible in the lane view from session start, and ending it (exit or session switch) marks it ended, on both harnesses.
• Turn boundaries are relayed on both harnesses: prompt submission emits turn.started; response completion emits turn.completed.
• Relayed envelopes carry correct session, repo, and branch attribution.
• A hook-relay failure never blocks or degrades the session it observes; the relay always exits 0.
• Hook configuration is installed and removed via the CLI as a discrete step invoked by install, with an opt-out and a print mode, touching only sentinel-marked entries (via Add a managed hook-entry utility for Claude Code settings.json #1007/Add a managed event-hook utility for Rovo Dev config.yml #1008).
• status reports each harness's hook entries as present, drifted, or absent.
• session.started, session.ended, turn.started, turn.completed join the declared vocabulary (no warnings on emit).
• Hook configuration for both harnesses is documented: manual-adoption snippets matching the print mode's output, Rovo's restart requirement, and the new CLI surface.
• New behavior is covered by tests.

Should have

• Session-start/-end payload discriminators (source/reason, including fork and switch) pass through in event payloads.

[williamthorsen]

Docs findings from #1007's design phase, verified against the official Claude Code hooks documentation — relevant here when authoring the actual hook entries:

• Matcher support varies by event. SessionStart supports matcher (values: startup|resume|clear|compact) and SessionEnd supports it (clear|resume|logout|prompt_input_exit|bypass_permissions_disabled|other). UserPromptSubmit and Stop do not — a matcher on them is silently ignored.
• Command execution has two forms. Shell form (no args field) runs via sh -c (PowerShell on Windows) and tolerates pipes, env-var expansion, and trailing # comments — a natural place to embed the ownership sentinel. Exec form (with args) spawns directly with no shell interpretation: no comments, no expansion.
• Multiple entries per event are supported and all fire; one hook's outcome doesn't suppress siblings, and identical hook commands are deduplicated by Claude Code.
• Unknown keys are rejected, not ignored. The published settings schema (schemastore) sets additionalProperties: false on hook objects, and a user/project settings file that fails validation is rejected as a whole — this is why Add a managed hook-entry utility for Claude Code settings.json #1007's sentinel rides the command string rather than a metadata key.

Sources: https://code.claude.com/docs/en/hooks.md, https://code.claude.com/docs/en/hooks-guide.md, https://code.claude.com/docs/en/settings.md, https://www.schemastore.org/claude-code-settings.json

[williamthorsen]

Does hook config appear in status?

Raising this from #1007, which landed the Claude utility this ticket consumes.

The acceptance criteria here cover installing hook config, removing it, and a print mode, but no status surface. That leaves two things worth deciding while this ticket is planned:

1. checkClaudeHookEntries has no consumer. Add a managed hook-entry utility for Claude Code settings.json #1007 built and justified check as being "for status-style reporting", and nothing calls it. If hook config never appears in status, that function is speculative surface and should arguably not exist.
2. status would be inconsistent. status (packages/agents/src/commands/status.ts) reports current/modified/missing drift for everything else install writes to disk. If install starts writing hook entries that status cannot see, a user gets "everything current" with no way to ask whether their hooks are actually installed.

Either answer is fine, but it should be deliberate rather than defaulted:

• Add a status surface — then Decide whether managed-entry check should report unsupplied owned entries #1013 becomes live (it decides whether check needs to report owned entries the caller no longer supplies, which is what makes a stale hook from an earlier version visible), and this ticket likely wants an acceptance criterion for it.
• Deliberately omit one — then Decide whether managed-entry check should report unsupplied owned entries #1013 resolves to "keep entry-scoped reporting" immediately, and check's existence is worth revisiting.

#1013 is blocked by this ticket for that reason: this is where the requirement gets settled.

[williamthorsen]

Status-surface question: resolved. Hook configuration gets a status surface in this ticket — status reports each harness's hook entries as present, drifted, or absent, consuming checkHookEntries on both sides through the shared entry catalog. That gives check its consumer, and #1013 is now live: it decides whether check should also report owned entries the caller no longer supplies (a stale entry from an earlier version).

Two implementation notes recorded during the work:

• Add a managed event-hook utility for Rovo Dev config.yml #1008's utility shipped against a schema Rovo Dev rejects (eventHooks.events as a map keyed by event name, commands as bare strings). Verified against the CLI and a live config: events is a list of {name, commands: [{command}]} items, and the map shape is treated as corrupt config — the vendor docs are wrong. The utility is reworked to the list schema on this branch. Full findings in the codeassembly KB: "Rovo Dev event-hooks config schema and execution semantics".
• The ownership sentinel rides as an inert --sentinel argument the relay accepts and ignores, on both harnesses — not a trailing shell comment. Rovo turns out to execute hooks via sh -c (so a comment would also have worked), but the argument form holds under any execution semantics and keeps one encoding across harnesses, docs, and tests.