Hook metrics (1) a runner records every hook run

[EdbertChan]

Summary

This change adds a dormant wrapper that records every automated check while preserving its output and exit status.

Today, direct starts provide no record of which automated checks speak, stay silent, block, or fail.

The wrapper starts each check separately, forwards its standard streams, classifies the result, and appends one JSONL metrics row.

Installation wiring is intentionally deferred to the next step.

Review Claim

Approve a wrapper that records each check result without changing its visible output or exit status.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

A wrapped hook produces byte-identical stdout and the same exit code as a direct run; a failed metrics write leaves both unchanged and adds one stderr line.

Slice Rationale

The runner and its outcome rules form one behavior claim. Documentation describes the same contract, while installation wiring remains a later slice.

Non-goals

• No install.sh, settings, or hook fragment changes.
• No report CLI or metrics reader.
• No changes to existing hooks.

Architecture

Before

graph TD
    A["Harness"] --> B["Hook script"]
    B --> C["stdout, stderr, exit code"]

Loading

After

graph TD
    A["Harness"] --> B["Hook runner"]
    B --> C["Hook subprocess"]
    C --> D["stdout, stderr, exit code"]
    B --> E["Outcome classifier"]
    B --> F["JSONL metrics row"]

Loading

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/_runner/tests -v
• bash scripts/run_all_tests.sh
• python3 scripts/check_hook_test_coverage.py
• python3 engine/skills/make-pr/scripts/preflight.py --base main
• python3 scripts/check_no_new_comments.py
• bash scripts/scrub-handoff-artifacts.sh

Revert Plan

Revert Plan

• Safe to revert? Yes. The runner is dormant until installation wiring lands.
• Revert command: git revert <merge-commit-sha>
• Post-revert steps: None.
• Data migration? No.

---

Note

Low Risk
New isolated runtime code with no install wiring; behavior is test-guarded to preserve hook stdout and exit codes when eventually enabled.

Overview
Adds a dormant hook runner under engine/hooks/_runner/ that wraps hook scripts in a subprocess, forwards stdout/stderr and the exit code unchanged, and appends one JSONL metrics row per run (default ~/.cache/catstack-hook-metrics/runs.jsonl, overridable via CATSTACK_HOOK_METRICS_DIR).

Each row records harness (inferred from path), hook/script, stdin-derived event and session_id (with conversation_id fallback), timing, stdout size, stderr tail, and an outcome from outcome.classify (timeout, exit 2 / JSON deny signals → blocked, crashes, catstack-hook-error lines, spoke vs silent). Optional --timeout kills slow hooks and records timed_out. Metrics or classification failures add a single catstack-hook-metrics: stderr line without altering hook stdout/exit code.

README documents the CLI and outcome precedence; unit tests lock the passthrough invariant and classification rules. Install wiring is explicitly deferred—nothing in the repo invokes the runner yet.

^{Reviewed by Cursor Bugbot for commit 6a83264. 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_0722b5cf-6ea5-4d3a-a405-f2859b23a7a4)

[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_82413a95-721c-4568-9c8f-05d5c7157784)