Place checks at the right event

Understand the approach

An event name tells you when a hook runs, which inputs it receives, and how its result is interpreted. PreToolUse runs before supported tool operations; PostToolUse sees their output after execution. SessionStart can supply context, while Stop can request continued work at the end of a turn. Selecting an event because its name sounds suitable is insufficient: timing determines what the hook can still influence.

Codex documents twelve lifecycle events across session start/end, subagent start/stop, prompt submission, tools, permission requests, compaction, stopping, and interruption. Do not import the source course's larger event matrix as a Codex promise. Matchers also have event-specific meaning. A SessionStart matcher filters the start source; PreToolUse filters tool names; Stop and UserPromptSubmit currently ignore matcher settings.

PostToolUse cannot undo a completed side effect. For Bash it also runs after a non-zero command exit, so seeing the event does not mean the command succeeded. PermissionRequest only runs when an approval would be requested; it is not a check on every ordinary operation. Stop's blocking decision asks Codex to continue, which differs from denying a pending tool. Record these distinctions in the event map.

Compare prevention with later information

The deny-move fixture inventories a protected destination before any patch executes. Separately, workflow-plugin/hooks/demo.cjs replays SessionStart, successful PostToolUse, and failed PostToolUse input. The informational handler supports both those event kinds; other events return an empty object. Its PostToolUse message cannot undo an operation. Optional actual-client observations should record event, source or tool name, output, and effect on the supported host rather than claiming coverage of every tool.

One event, one interpretation

The same handler output cannot be reused blindly across events. Stop continuation creates another agent turn; it does not roll back a patch or certify correctness. The classroom Stop checker ends the retry when stop_hook_active is true, leaving the user a specific unresolved state instead of an endless loop.

Try it step by step

1. Map the desired outcome to the last point where it can still affect execution: before a patch, after an outcome, or before a turn stops.
2. Replay deny-move and verify the destination is inventoried before returning PreToolUse deny.
3. Inspect the plugin’s successful and failed PostToolUse fixtures; informational output does not reverse either operation.
4. Run the Stop demo and compare decision:block with a PreToolUse permissionDecision:deny. Inspect the bounded retry state.
5. In the generated --with-stop project, inspect the actual event bindings and run the covered native prompts if supported.

A useful starting example

Illustration · adapt before use.

node labs/hook-policy/replay.cjs deny-move
node labs/hook-policy/stop-demo.cjs

For each requirement, choose a documented Codex event and explain its limits:
1. Add short repository context when a session resumes.
2. Deny a supported tool before it writes a protected fixture.
3. Summarize a failed command after it exits.
4. Ask for one more verification pass before a turn ends.
Return a timeline; do not configure hooks.

Check your result

• The pending protected move is denied by PreToolUse in the offline fixture.
• The PostToolUse error example remains a failed operation rather than a successful policy check.
• The map names documented events and matcher meanings without importing the source course's event count.

Common mistakes

• Using PostToolUse as though it could reverse an external write.
• Adding a matcher to an event that ignores it, then assuming the hook is narrowly scoped.