[Hook architecture](17) Put the diu-stop hook onto the shared hook code

[EdbertChan]

Summary

The hook that checks reply length and proof now runs through the shared hook code. It still stops the same replies: too long, or claims with no proof.

Before this change, each of its scripts read its input, picked its own response, and printed it. The stop-or-warn choice was fixed inside the hook.

Now each check returns a list of findings. The shared runner picks stop, warn, or off from the hook registry and writes one event row per finding.

A setting can now turn its stop into a warning. No hook code has to change for that.

Review Claim

The reply-length hook sends its findings to the shared hook code, which applies the registry mode and writes event rows, while the hook still stops replies by default.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

Every case in engine/hooks/diu-stop/tests gives the same stop, warn, or silent result as before. The only new result is the mode override, and the test folder still exits 0.

Slice Rationale

This is part 17 of the hook architecture stack. It moves one hook, so each move can be reviewed alone. The shared runner already landed lower in the stack.

Non-goals

• No change to what diu-stop looks for: word limit, unproven claims, marker tags, plain words.
• No change to its default mode, which stays stop.
• No other hook is changed.
• Codex has no way to block a reply, so its notify script still only prints a note. It now skips the note when the mode is off and writes event rows.

Architecture

Before

graph TD
    A["Claude Stop event"] --> B["claude_stop_check.main()"]
    B --> C["checks inside main()"]
    C --> D["stderr text + exit 2"]

Loading

After

graph TD
    A["Claude Stop event"] --> B["run_hook('diu-stop', 'claude', detect, 'Stop')"]
    B --> C["detect(event) returns Finding list"]
    C --> D["registry mode: stop, warn, or off"]
    D --> E["stop: stderr + exit 2"]
    D --> F["warn: additionalContext + exit 0"]
    D --> G["events-*.jsonl row per rule_id"]

Loading

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/diu-stop/tests → Ran 111 tests in 0.367s / OK
• python3 scripts/ci/check_hook_test_coverage.py engine/hooks/diu-stop → check_hook_test_coverage: OK (1 hook(s) checked)
• bash scripts/pr/scrub-handoff-artifacts.sh → scrub-handoff-artifacts-ok
• New tests in tests/test_hooks_sdk_mode.py:
  • test_mode_override_warn_changes_block_to_warning: with CATSTACK_HOOK_MODE_DIU_STOP=warn, a 200-word reply exits 0 and warns.
  • test_mode_stop_still_blocks_by_default: with no override, the same reply still exits 2.
  • test_each_finding_writes_one_event_row_with_rule_id: one row with rule id diu-stop.word-limit, mode warn, action warned.
• Test-only change in tests/test_hooks.py: the old main() calls now allow SystemExit, because run_hook exits on its own.

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <merge-sha>
• Post-revert steps: None. diu-stop goes back to its own stop logic and ignores the registry mode.
• Data migration? No. Event rows already written stay on disk and nothing reads them back.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes how assistant replies are blocked or warned at turn end (core agent behavior), though detection rules are unchanged and existing tests assert parity except the new mode override.

Overview
diu-stop now routes Claude hooks through the shared run_hook SDK instead of hand-rolled JSON stdin/stdout and sys.exit(2).

claude_stop_check.py and claude_prompt_reminder.py expose a detect(event) that returns Finding objects with stable **rule_id**s (word limit, unverified claims, markers, plain words, prompt reminder). The shared runner applies registry stop / warn / off via CATSTACK_HOOK_MODE_DIU_STOP, renders Claude hook output, and writes one events-*.jsonl row per finding. Default behavior stays block on violation; warn surfaces the same text as additionalContext with exit 0.

Codex codex_notify.py adopts the same finding shape and effective_mode / write_events (still advisory-only on stderr); it skips output when mode is off.

Tests tolerate SystemExit from run_hook, and test_hooks_sdk_mode.py covers warn override, default block, and metrics rows with rule_id.

^{Reviewed by Cursor Bugbot for commit 281e4f2. 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 281e4f2. Configure here.}

[cursor]

Installed hooks cannot import shared SDK

High Severity

The new scripts import finding and runtime from a sibling _sdk directory, but install.sh never links _sdk into ~/.claude/hooks or ~/.codex/hooks. After install, each entrypoint looks next to those hook roots, misses the package, and fails on import. The Stop check, prompt reminder, and Codex notify then never run, so long or unproven replies are no longer blocked.

Additional Locations (2)

• engine/hooks/diu-stop/claude_prompt_reminder.py#L23-L28
• engine/hooks/diu-stop/codex_notify.py#L23-L29

 

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

[EdbertChan]

@Mergifyio queue admin-bypass

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-17 06:42 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #732 on main (4432e10) #769
• ✅ Merged — 2026-09-17 06:49 UTC · at 2a9208f8af8f8d9921b9fd1a28d0d742482e7247 · squash

This pull request spent 6 minutes 42 seconds in the queue, including 6 minutes 18 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_kwDOT3uYWs6jPQ8G