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

[EdbertChan]

Summary

This guard stops Claude from changing only some items when the user asked for all of them.

For example, it blocks a change that skips done tasks after the user said "all tasks."

The problem: each guard decided on its own whether to block or just warn. Changing that choice meant editing the guard's code.

The fix: this guard now only reports what it found. Shared code decides whether to block or warn, and logs one record per finding.

It still blocks by default, same as before. A local setting can now soften it to a warning.

Cursor and Codex now get their own entry scripts for this guard too.

Review Claim

This guard now reports what it found to the shared hook code, which picks block or warn from the shared settings and logs each finding. The default is still to block.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The hook gives the same stop, warn, or silent result on every case in its current test folder, except the mode change named in this claim, and its test folder keeps exiting 0.

Slice Rationale

One hook per workflow, as the user asked, so each migration is reviewed on its own. This is part 15 of the hook architecture stack described in docs/hook-architecture.md, stacked on the cat-mode-default migration (part 14).

Non-goals

• No change to what the hook detects: decide(), decide_payload(), and the transcript reader are untouched.
• No other hook moves onto the shared code in this PR.
• No change to install_claude_hook.py or claude.hook.json; Claude still runs the same entry script.
• The only _sdk edit is the wording of the bad-JSON error line in runtime.py.

Architecture

Before

graph TD
    A["claude_pretooluse.py"] --> B["parse stdin JSON"]
    B --> C["decide_payload()"]
    C -->|"HIT or UNCHECKED"| D["stderr message, exit 2"]
    C -->|"CLEAN"| E["exit 0"]

Loading

After

graph TD
    A["claude / cursor / codex entry script"] --> R["_sdk runtime.run_hook()"]
    R --> F["detect(event) returns Finding list"]
    F --> C["decide_payload()"]
    R --> M["registry mode, default stop, env override"]
    R --> L["one event row per finding, with rule_id"]
    M -->|"stop"| D["block, exit 2"]
    M -->|"warn"| W["additionalContext warning, exit 0"]

Loading

Rule ids: categorical-scope-guard.partial-status-filter for a HIT, and categorical-scope-guard.unchecked for UNCHECKED or a detector crash. Under the default stop mode, both still block the command.

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/categorical-scope-guard/tests → Ran 45 tests in 0.637s / OK
• Fail-before: the new tests/test_hooks_sdk_mode.py copied onto the base branch (part 14) → FAIL: test_each_finding_writes_one_event_row_with_rule_id, FAIL: test_mode_override_warn_changes_block_to_warning, FAILED (failures=2)
• Default mode still blocks: the update_tasks_status_in_pending_queued.txt fixture sent to claude_pretooluse.py with CATSTACK_HOOK_MODE_CATEGORICAL_SCOPE_GUARD unset, after a turn that said "all tasks" → default exit=2, stderr starts categorical-scope-guard: you said "can you make all tasks use claude and local executor". "all tasks" names every task, and this command narrows tasks by a status filter
• python3 -m unittest discover -s engine/hooks/_sdk/tests → Ran 31 tests in 0.036s / OK
• python3 scripts/ci/check_hook_test_coverage.py engine/hooks/categorical-scope-guard → check_hook_test_coverage: OK (1 hook(s) checked)
• python3 scripts/ci/check_hook_test_coverage.py engine/hooks/_sdk → check_hook_test_coverage: OK (1 hook(s) checked)
• python3 engine/skills/make-pr/scripts/preflight.py --base origin/plan/hook-architecture-14-put-the-cat-mode-default-hook-onto-the-shared-hook-code --body-file <this body> → declare Review Unit: engine-runtime, ruff gate All checks passed!, description clean, ok preflight passed
• node engine/skills/draft-pr/scripts/validate-pr-body.mjs --body-file <this body> --changed-files-file <diff vs base> → PR body validation passed.
• bash scripts/scrub-handoff-artifacts.sh → completed (workflow gate)

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <merge-sha>
• Post-revert steps: None. The hook goes back to blocking from its own entry script, and the Cursor and Codex entry scripts are removed.
• Data migration? No

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes PreToolUse enforcement plumbing (centralized block/warn and metrics) for a guard that intercepts shell commands, though core decide() logic is unchanged and default remains block.

Overview
Migrates categorical-scope-guard onto the shared hook SDK so detection returns structured Findings instead of the entry script choosing exit codes directly.

detect.py now exposes detect(event) with rule ids categorical-scope-guard.partial-status-filter (HIT) and categorical-scope-guard.unchecked (UNCHECKED / detector failure), keyed by a hashed command subject. claude_pretooluse.py is reduced to run_hook(..., detect, "PreToolUse"), and matching cursor_pretooluse.py / codex_pretooluse.py entrypoints are added. Block vs warn and per-finding metrics/event rows are handled by _sdk (effective_mode, render, write_events); CATSTACK_HOOK_MODE_CATEGORICAL_SCOPE_GUARD=warn can soften a hit to stdout context while still logging the finding.

Docs now describe outcomes in terms of findings and registry default stop. Shared runtime’s bad-JSON stderr line is slightly clarified. New test_hooks_sdk_mode.py covers warn override and one event row per finding with rule_id.

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

[cursor]

Stale Bugbot comment from a previous run.

[mergify]

Queued — the merge queue status continues in this comment ↓.

[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 5bcd8b5. Configure here.}

[cursor]

Detector prints crash line with finding

Low Severity

When decide_payload raises, detect writes a catstack-hook-error line to stderr and still returns an unchecked finding. Shared runtime already records and renders that finding, so the extra line prefixes the Claude block reason and makes the runner treat a warn-mode result as caught_error.

 

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

[EdbertChan]

@Mergifyio queue admin-bypass

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-17 06:13 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #730 on main (e6ec812), stacked on #740 #765
• ✅ Merged — 2026-09-17 06:21 UTC · at 4c4fcd58d6f744f5d7c07fc2cd7631d5717f191c · squash

This pull request spent 7 minutes 16 seconds in the queue, including 6 minutes 44 seconds running CI.

Required conditions to merge

• check-success = lint
• check-success = test
• check-success = validate

[EdbertChan]

Mergify repair stopped: unresolved human review thread PRRT_kwDOT3uYWs6jOw4J