Hooks: a lifecycle, not a reminder

Understand the approach

A hook attaches a small operation to a point in Codex's lifecycle. Instead of asking the agent to remember a check in every prompt, you define when a script or an existing MCP tool should run. Useful examples include adding short repository context at session start or inspecting a pending tool operation. The trigger, handler, and interpretation of its result form one contract; a script alone is not a working hook.

The source course introduces several Claude hook mechanisms. Codex provides the same broad event-driven capability, but its supported handlers, events, and response fields differ. Current documentation supports command and mcp_tool handlers. Hooks from multiple active sources can match the same event, and matching command hooks can start concurrently. Do not rely on one hook running before another or preventing another handler from starting.

Start with the fictional fixture suite, then connect the same handler in a disposable project. The generated native track writes a complete project-local configuration with the actual host interpreter path. It lets you observe discovery, definition trust, a covered allowed edit, a protected edit denial, and disabling. These are separate from a program merely printing correct JSON. Keep personal configuration out of this first experiment.

Observe the policy before trusting it

The lab begins with an offline policy precisely so its outcomes can be observed without preventing a real operation. Compare a no-objection response, explicit denial, irrelevant tool, handled-invalid input, and a process that never launched. A production credential filter would need a stronger threat model and broader coverage. Keep this small guard's lexical path and tool limits visible; completing its classroom exercise does not make it universal protection.

What this first hook actually establishes

The guard inventories paths in canonical apply_patch input before the operation. It is a deliberately small lexical rule, not a filesystem sandbox: other tools and symlinks remain outside its coverage. Native success means the particular covered tool event was observed and handled in that client, not that every possible file write is prevented.

Try it step by step

1. Run the fixture demo and original suite; distinguish a running program returning a denial from a missing handler that never ran.
2. Generate a new project with create-workspace.cjs --path-only. Inspect the actual .codex/hooks.json, executable path and two scratch files.
3. Open that project in the app, or launch the CLI in it and inspect /hooks. Review project trust and the current hook-definition trust separately.
4. Use the two covered apply_patch prompts in NATIVE-CLIENT.md. Compare allowed/protected file content and tool activity; do not test by asking the model whether it would obey.
5. Disable the scratch hook, verify its loaded state, and retain the observed client/version separately from offline fixture results.

A useful starting example

Illustration · adapt before use.

node labs/hook-policy/demo.cjs

Inspect labs/hook-policy/guard.cjs and its fictional fixtures.
Explain the event, canonical input, path policy, output contract, and coverage limits.
Run the offline demo and tests; cite the observed cases.
Do not place configuration, trust hooks, or apply a patch.

Check your result

• The allow fixture returns no-objection context; protected paths return the documented PreToolUse denial.
• The report separates invalid input handled by a running program from failure to launch that program.
• The 13 local checks pass and the remaining client acceptance states are labeled unrun.

Common mistakes

• Treating a reminder in AGENTS.md as proof that an executable check always runs.
• Assuming all matching hooks run in a dependable sequence or that installation automatically trusts them.