Debug hooks as small integrations

Understand the approach

A hook that produces no visible result may never have been discovered, may need trust review, may not match, may fail to launch, or may return output that the event ignores. Debug these stages separately. Repeatedly changing all configuration at once destroys the evidence. Start with the current source inventory and one fictional input that has a clear expected result.

In Codex CLI, /hooks exposes configured sources, review status, and controls for non-managed hooks. This is different from the source course's Claude debug flag and shortcut. Managed hooks can be enforced by policy and may not be disableable from the user browser. Reading their status does not authorize changing organization controls. Record the exact client and execution host before deciding a hook is absent.

Run a proposed handler independently with fictional stdin before connecting it. Check the interpreter, path quoting, cwd assumptions, stdout, stderr, exit status, and timeout. Then inspect event selection and trust separately. Concurrent handlers and background delivery can make observed order misleading; tag local test output with a fictional case identifier rather than inferring a sequential lifecycle from timestamps alone.

Retain a minimal incident record

Keep the client version, redacted configuration excerpt, fixture identifier, expected result, observed result, and one next experiment. Avoid copying a whole transcript when a single event explains the defect. The transcript format is not a stable hook interface and can include sensitive material. A compact incident record makes it easier to reproduce a bug after a runtime update and to tell a new configuration defect from a changed product contract.

Try it step by step

1. Run the unchanged policy suite and combined depth suite to isolate a code regression before touching client configuration.
2. Replay one exact failing input and inspect stdout, stderr and exit status; distinguish an intentional deny from a launch failure.
3. Inspect the generated absolute interpreter path and cwd assumptions on the actual execution host.
4. In /hooks inspect source, enabled state, current trust and event/matcher. Change only the failing stage, then repeat the same covered operation.
5. Restore any deliberately broken scratch copy, disable the practice definition and retain a concise before/after report with version and observed event.

A useful starting example

Illustration · adapt before use.

node labs/hook-policy/demo.cjs

Diagnose this draft hook without activating it.
Inspect its source location, event, matcher, interpreter, script path, and expected output contract.
Use fictional input only. Distinguish not discovered, awaiting trust, not matched, launch failure, and invalid output.
Return one smallest next test for each unresolved stage. Do not weaken policy or trust hooks.

Check your result

• The report distinguishes policy denial, input validation, no-match coverage, and process launch failure.
• Every conclusion names a reproducible fixture and observed channel or status.
• The final baseline passes and client discovery/trust remain unrun unless actually observed.

Common mistakes

• Using another product's debug switches and interpreting their absence as missing hook support.
• Fixing a launch error by turning off trust review or assuming all handler failures block the tool.