[Hook architecture](14) Put the cat-mode-default hook onto the shared hook code

[EdbertChan]

Summary

The hook that turns on the user's working style each turn now has a guide that matches how the shared hook code runs it.

The guide says the shared list of hook modes keeps this hook in warn mode. It also names the one setting that changes that mode on a single machine.

It explains that stop mode blocks a helper agent from starting, instead of adding the working-style note to that agent's instructions.

The checks that feed the hook broken input now write their event records to a throwaway folder, so a check run leaves the real records folder alone.

Review Claim

The working-style hook's guide matches how the shared hook code runs it, and its broken-input checks write event records only to a throwaway folder.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The hook gives the same stop, warn, or silent result on every case in its test folder. Only the README and test setup change, and python3 -m unittest discover -s engine/hooks/cat-mode-default/tests keeps exiting 0.

Slice Rationale

One hook per workflow, so each move to the shared hook code gets its own review. This is part 14 of the hook architecture stack in docs/hook-architecture.md. This slice holds only the guide and check setup for that one hook.

Non-goals

• No change to what the hook detects or to its registry mode (it stays warn).
• No change to the hook's entry scripts, detect.py, or the installer.
• No change to any other hook or to engine/hooks/_sdk/.

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/cat-mode-default/tests → Ran 41 tests in 0.105s / OK
• python3 engine/skills/make-pr/scripts/preflight.py --dry-run --base origin/main → unit engine-runtime: 3 file(s) / ok preflight passed
• python3 scripts/ci/check_hook_test_coverage.py engine/hooks/cat-mode-default → check_hook_test_coverage: OK (1 hook(s) checked)
• bash scripts/pr/scrub-handoff-artifacts.sh → scrub-handoff-artifacts-ok, exit 0

Revert Plan

Revert Plan

• Safe to revert? Yes. It touches only the README and test setup.
• Revert command: git revert -m 1 <merge-sha>
• Post-revert steps: None. The bad-input tests would again write event rows to the default metrics folder.
• Data migration? No

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and test isolation only; no changes to hook detection, entrypoints, or runtime behavior.

Overview
Updates the cat-mode-default README so it matches the shared hook stack: default warn mode in the registry, machine override via CATSTACK_HOOK_MODE_CAT_MODE_DEFAULT, and how stop blocks the Agent PreToolUse path instead of rewriting prompts. The Files section now describes detect(event) → Finding objects, thin entrypoints through engine/hooks/_sdk/runtime.py, and agent output rendered as updatedInput.

Fail-open regression tests (malformed stdin / detect exceptions) in test_hooks.py and test_agent_hook.py now point CATSTACK_HOOK_METRICS_DIR at a temp directory in setUp/tearDown, so those runs do not write hook metrics to the developer’s default folder.

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

[mergify]

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

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-17 09:56 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #766 on main (2a9208f) #771
• ✅ Merged — 2026-09-17 10:03 UTC · at f660fa7a7493cdedb02888aecf9bc68d01f0c325 · squash

This pull request spent 6 minutes 21 seconds in the queue, including 5 minutes 50 seconds running CI.

Required conditions to merge

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