Hook metrics (3) a per-hook report and a crash notice

[EdbertChan]

Summary

Each saved hook run can now be seen in one table.

The table shows how often each hook ran, what happened, how long it took, and its last error.

A short prompt message points out new hook failures in Claude, Cursor, and Codex, without stopping the prompt.

Review Claim

Review that hook failures become visible on demand and automatically on the next prompt.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

A registered hook with no rows is reported as no record, never healthy; the notice never blocks prompt submission; an unreadable metrics log is reported as unchecked, not clean.

Slice Rationale

This slice reads metrics produced by the earlier runner work and exposes them to users and agents, while keeping metric production unchanged.

Non-goals

No changes to run.py, outcome.py, or wrap_installed.py behavior, and no dashboard or remote metrics upload.

Architecture

The table reader compares registered hook configuration with the metrics log on demand. Prompt entrypoints read new rows from a per-session offset, emit harness-specific context, and advance that offset.

Before

graph TD
    A["runner metrics log"] --> B["no reader"]
    C["prompt event"] --> D["no failure context"]

Loading

After

graph TD
    A["runner metrics log"] --> B["per-hook table"]
    A --> C["prompt health reader"]
    D["registered hook configs"] --> B
    E["prompt event"] --> C
    C --> F["Claude/Cursor/Codex context notice"]

Loading

Test Plan

Test Plan

• bash scripts/run_all_tests.sh && python3 scripts/check_hook_test_coverage.py
• bash scripts/scrub-handoff-artifacts.sh

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <sha>
• Post-revert steps: None
• Data migration? No

---

Note

Low Risk
Read-only reporting plus non-blocking advisory context on prompt submit; install merges new hook entries without changing runner metric production.

Overview
This PR surfaces hook-runner metrics that were previously only written to runs.jsonl: a on-demand per-hook report and an advisory prompt notice when wrapped hooks fail.

engine/hooks/_runner/report.py joins installed catstack hook commands (Claude/Cursor/Codex configs via wrap_installed) with metrics rows in a --since window. It prints outcome counts, p95 duration, and last error; registered hooks with no rows show no record (not “healthy”); stray log rows appear under unregistered:. Missing or bad logs exit 2 with unchecked messages. --json mirrors the same structure.

hook-health is a new advisory hook on prompt submit (UserPromptSubmit / beforeSubmitPrompt). Per session it tails the metrics log from a saved byte offset, and on new crashed / timed_out / caught_error rows for the current harness it injects a short summary (up to five failures, points at report.py). It never blocks prompts; unreadable logs get an unchecked notice. Install links the hook for all three harnesses; docs and tests cover report CLI, detect/runtime, and install wiring.

^{Reviewed by Cursor Bugbot for commit 605ba6a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e44aeb0b-4c7e-4ab6-9ff3-315d6b9e1ff8)