Static reading edition · s06-06

Build a bounded Stop review instead of an unsupported prompt hook

Hooks24 min estimatedCodex app · CLI; surface-specific notes below

Implement and activate a deterministic completion check while keeping unsupported model-evaluated hook types explicit.

Understand the approach

The source uses a model-evaluated prompt hook with an ok/reason answer. Current Codex parses prompt and agent handler types but skips them. A type:prompt file therefore cannot be this course’s active quality gate. Use a supported command handler for a criterion that can actually be checked, and use ordinary model review for judgments the script cannot establish.

The bundled Stop checker reads candidate.md and review-evidence.json in a generated project. It checks two literal headings, the current candidate SHA-256, and two named observations. Missing headings, absent evidence or stale hashes request a focused continuation using decision:block and a reason. Success returns an empty object. A malformed event is diagnosed separately rather than certified as a successful review.

Continuation can repeat agent work, so the checker uses stop_hook_active to bound the classroom retry. If another Stop attempt is already active it reports the unresolved condition and returns without asking for another turn. This is not a built-in model evaluator, and the narrow check does not establish general writing quality. Native activation still requires loaded configuration and reviewed trust.

Review criteria are matched to current evidence. A demonstrated failed criterion needs repair and a new check. Missing evidence is reported as not verified, with the smallest required handoff; retry only when new evidence or access arrives. A structural pass alone does not establish the quality judgment.
Open the full diagram

Make judgment auditable without asking for hidden reasoning

Ask for conclusions, assumptions, the specific evidence used, and short explanations for failed criteria. Do not ask a model to expose private chain-of-thought as a quality signal. A reviewer can be wrong even when its explanation sounds confident, so keep the underlying command result, file excerpt, or interaction trace available. The review improves accountability; it does not replace the user's acceptance of the delivered behavior.

About your environment

Verified October 21, 2026. Prompt and agent handlers are skipped in current local Codex hook documentation. No evaluator service, API call, hook, or recurring task is created here.

Try it step by step

Run stop-demo.cjs and inspect the newly created candidate and evidence files, not just the printed statuses.
Compare the missing-heading and stale-hash continuations with the fresh complete candidate that returns {}.
Read stop-review.cjs and explain why setting passed:true alone cannot conceal a missing heading.
Generate the --with-stop project and follow NATIVE-CLIENT.md to load/trust the command hook and observe actual continuation if supported.
Verify the retry guard, then disable only the scratch definition. Keep unavailable native steps explicit.

A useful starting example

Illustration · adapt before use.

Run the real artifact-based Stop checker without a model text

node labs/hook-policy/stop-demo.cjs
node --test labs/hook-policy/depth.test.cjs

From input to result

Four real artifact states

A generated guide starts without Verification; editing it makes previous hash evidence stale.

Worked input text

node labs/hook-policy/stop-demo.cjs

Expected result · compare with your run

missing verification: continue once
stale evidence: continue once
fresh matching evidence: no continuation
already continued: no continuation

These are excerpts of the actual demo labels. The full output includes each reason and scratch path. Actual saved files are checked; no native model turn is claimed.

Hands-on exercise

Your turn

Repair the generated candidate, compute its actual hash and provide the two actual heading observations. Show the checker requesting continuation before the repair and returning {} after a fresh repair. Then demonstrate that a later edit invalidates the evidence and that stop_hook_active prevents a loop. Native-track learners additionally retain the actual client hook activity.

Try the exercise before opening its reference answer. Use a disposable practice folder.

Run the practice

Inspect and activate an actual Stop contract

Extract into a new practice folder and keep the included labs folder. Run these commands from that extraction root, or from the course folder, using an existing Node.js installation.

Download this lab ↓

Command 1 text
```
node labs/hook-policy/stop-demo.cjs
```
Check: Prints the generated root and missing, stale, fresh and already-continuing outcomes.
Command 2 text
```
node --test labs/hook-policy/test.cjs labs/hook-policy/depth.test.cjs
```
Check: 18 checks pass, including stale evidence, forged passed flags and bounded retry.

Inspect the actual filesDeterministic Stop handler ↗Actual file-state demo ↗Artifact regression checks ↗Native activation, observation and disabling ↗

This is executable completion checking with a bounded native track, not a prompt-hook imitation.

Check your result

Missing or forged evidence never becomes a successful classroom quality result.
Fresh complete artifacts pass, later edits become stale, and the retry stops after the bounded continuation.
The lesson distinguishes supported command Stop behavior from skipped prompt/agent hooks and from a native activation not yet observed.

Reference answer & rubric Try the exercise before opening

Repair the real candidate and link fresh evidence to its exact bytes; use the complete handler as the reference.

Inspect the missing Verification heading in the generated candidate; keep its current failed observation rather than changing only the JSON flag.
Add the required section, hash the saved file, and record the exact two heading observations in review-evidence.json.
Replay evaluateStop against that generated root. Expect {} only after both the artifact and matching evidence pass.
Edit the candidate again and verify the hash becomes stale. Send stop_hook_active:true and verify no second continuation is requested.
Compare actual native activity separately; the offline replay never claims a model turn ran.

Think it through

Check your understanding

What is the correct description of this lesson's explicit review?

A practical alternative to unsupported prompt-hook execution.
Proof that type prompt runs automatically in Codex.
A replacement for all sandbox and approval controls.

Reveal the answer and explanation

Answer 1: A practical alternative to unsupported prompt-hook execution.

The source goal is preserved, but the alternative's capabilities and limits must remain explicit.

Take this quiz in the interactive lesson to save your answer in the browser.

When it does not work

A valid-looking all-passed record still requests continuation.

Likely cause: The actual heading or current artifact hash does not satisfy the contract.

What to try: Inspect and repair candidate.md, then derive a new hash from saved bytes and record actual observations.

The native Stop hook never runs.

Likely cause: The source may not be loaded or the current definition is untrusted; prompt/agent types are skipped.

What to try: Use the generated command configuration and inspect /hooks in a supported client. Keep handler replay and client activation separate.

Common mistakes

Claiming a parsed-but-skipped prompt handler provides automatic protection.
Using an unbounded Stop continuation that keeps working without a testable stopping condition.

Source mapping & differences · alternative

Codex skips native prompt/agent handlers today. Use explicit evidence-based review, or a separately verified command/MCP evaluation integration, to retain the source's quality-check purpose.

Source topic: Prompt-based hooks ↗

Go to the source

Official documentation, checked 21 October 2026. Product names, controls and availability may vary with your version, platform or account.

Continue in the interactive lesson →

Completion and quiz progress are saved
only in the interactive course.