Understand hook input and output

Understand the approach

Command hooks receive a JSON object on standard input. Shared fields identify the session, current directory, event, and optional transcript location; event-specific fields carry tool inputs, tool results, or stop state. Read only the fields your handler needs and validate their types. A transcript path is a convenience, not a stable parsing interface, and the transcript may contain sensitive material.

Output must match the event. For example, a PreToolUse denial uses hookSpecificOutput with hookEventName, permissionDecision, and its reason. A Stop continuation uses decision block and a reason instead. The same-looking word block therefore has different effects at different lifecycle points. Several fields are parsed but unsupported for particular events, so a syntactically valid JSON response can still be operationally wrong.

Keep diagnostic logs on standard error and machine-readable response data on standard output. In this lab, malformed input handled by the running guard deliberately becomes a supported denial response at exit zero; successful process exit means the response was emitted, not that the proposed patch was allowed. A missing executable or crash is different because it may produce no usable policy response. Oversized model-visible context can spill to a temporary file, so never return secrets on the assumption that truncation removes them. A compact, typed result is easier to inspect and maintain.

A useful failure is distinguishable

For the same input, distinguish policy denial from missing runtime, unreadable fixture, malformed JSON, and timeout. If all five produce the same vague message, an operator cannot know whether a safeguard worked. Record these outcomes explicitly in your test table. For prevention-sensitive workflows, also verify the documented runtime failure behavior; a crashing validator should never be assumed to have denied an operation.

Evidence must describe the latest artifact

The Stop example links a SHA-256 hash to the actual candidate and independently inspects both required headings. A copied all-passed record cannot conceal a missing heading, and editing the candidate makes the old hash stale. This protects the narrow classroom contract; it does not evaluate arbitrary prose or guarantee that every claimed external test actually ran.

Try it step by step

1. Inspect the exact fictional event and read tool_input.command rather than a Claude-specific patch field.
2. Replay allowed, denied, irrelevant and malformed cases; retain stdout, stderr and process status separately.
3. Inspect the missing-handler test: no running program means no JSON policy denial was produced.
4. Run stop-demo.cjs and compare its fresh/stale artifact observations with the different Stop response fields.
5. Keep responses compact and typed; attach actual native event observations only if the client track was run.

A useful starting example

Illustration · adapt before use.

node labs/hook-policy/replay.cjs deny-protected

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "The fixture operation targets a protected practice file."
  }
}

Check your result

• The expected JSON uses supported fields for the correct event and stays separate from stderr diagnostics.
• Exit zero is not confused with an allow decision, and irrelevant {} is not treated as universal protection.
• The report identifies the untested client effect rather than claiming a live blocked edit.

Common mistakes

• Printing debug messages before JSON on stdout and breaking the response contract.
• Returning a source product's accepted field and assuming Codex honors it identically.