[Hook architecture](15) Put the categorical-scope-guard hook onto the shared hook code

[EdbertChan]

Summary

The guard that checks "all" requests now runs on the shared hook code. It still stops a command that changes only some items after the user asked for all.

Before this, the hook chose its own response and printed its own output. A mode change meant editing the hook itself.

Now the hook only reports what it found. The shared code picks stop, warn, or silent from the registry and writes one event row per finding.

One behavior did change. If the checker itself crashes, the hook now lets the command through and logs the error. Before, it blocked the command.

Review Claim

The guard that checks "all" requests reports findings to the shared hook code, which applies its registry mode and writes event rows. It keeps mode stop.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

Every case in the hook's current test folder gets the same stop, warn, or silent result as before, and the folder still exits 0. The new mode-override test is the only intended change.

Known gap: when the checker crashes, the hook used to block the command. The removed code in claude_pretooluse.py caught the error and called sys.exit(2). Now the shared runtime's crash handler in engine/hooks/_sdk/runtime.py logs catstack-hook-error categorical-scope-guard: <error> and calls sys.exit(0), so the command goes through. A deliberate crash probe (see Test Plan) exited 0. The current test folder has no case for this path. A reviewer should decide whether this needs a follow-up.

Slice Rationale

One hook per workflow, so each move to the shared code is reviewed on its own. This is part 15 of the stack in docs/hook-architecture.md.

Non-goals

• No change to what the hook detects.
• No other hook changes.
• install_claude_hook.py was listed in the plan but is not changed here.
• Does not restore blocking when the checker crashes.

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/categorical-scope-guard/tests → Ran 45 tests in 0.290s / OK
• New test test_mode_override_warn_changes_block_to_warning: with CATSTACK_HOOK_MODE_CATEGORICAL_SCOPE_GUARD=warn, a case that stops today exits 0 and returns a warning instead.
• New test test_each_finding_writes_one_event_row_with_rule_id: one stopped event row with rule id categorical-scope-guard.narrowed-mutation.
• python3 engine/skills/make-pr/scripts/preflight.py --dry-run --base origin/plan/hook-architecture-14-put-the-cat-mode-default-hook-onto-the-shared-hook-code → unit engine-runtime: 4 file(s) / ok preflight passed
• python3 scripts/ci/check_hook_test_coverage.py engine/hooks/categorical-scope-guard → check_hook_test_coverage: OK (1 hook(s) checked)
• bash scripts/scrub-handoff-artifacts.sh → scrub-handoff-artifacts-ok
• Deliberate crash probe (checker patched to raise RuntimeError("probe")). The expected error log printed: catstack-hook-error categorical-scope-guard: RuntimeError: probe. The probe then printed crash-path exit 0.
• ruff check --select E9,F on the four changed files: not run, because ruff is not installed on this machine (command not found: ruff).

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <merge-sha>
• Post-revert steps: None. The hook goes back to choosing its own response and blocking when the checker crashes.
• Data migration? No

🤖 Generated with Claude Code

---

Note

High Risk
categorical-scope-guard is security-sensitive; shared-runtime detector crashes now fail open (exit 0) instead of blocking, which can let status-narrowed mutations through if classification breaks.

Overview
categorical-scope-guard now reports Finding objects through engine/hooks/_sdk/runtime.py instead of choosing exit codes in the Claude entrypoint. Thin PreToolUse wrappers exist for Claude, Cursor, and Codex; detect(event) maps HIT/UNCHECKED to rule ids partial-status-filter and unchecked. Registry default stop still blocks, but CATSTACK_HOOK_MODE_CATEGORICAL_SCOPE_GUARD=warn turns blocks into additionalContext warnings and writes per-finding metrics rows (new SDK mode tests).

Documented behavior change: if detect() throws past its own handler, the shared runtime logs catstack-hook-error, records a crash event, and exits 0 (allows the tool). The old entrypoint exited 2 on detector failure.

The same diff also moves demo-freeze and diu-stop (Claude Stop/UserPromptSubmit, Codex notify) onto run_hook, adds CATSTACK_HOOK_METRICS_DIR setup in cat-mode fail-open tests, clarifies invalid JSON stderr in runtime.py, and adds a working-style rule plus test_check_memory_first_rule.py to pin “search saved memory (both ways) before a deep dive.”

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

[cursor]

Stale Bugbot comment from a previous run.

[EdbertChan]

Mergify repair stopped: unresolved human review thread PRRT_kwDOT3uYWs6jPLm9

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f1c98a1. Configure here.}

[cursor]

Reminder findings always record as stopped

Medium Severity

The prompt reminder detect always returns a finding, and diu-stop stays in registry stop mode. UserPromptSubmit still only injects context, but every turn is stored as a stopped event. That drowns out the hook's real stop counts used for mode review.

 

^{Reviewed by Cursor Bugbot for commit f1c98a1. Configure here.}