CONCEPT Input arrives as JSON on stdin
When an event fires, Claude Code runs your command and pipes event data as JSON to stdin.
Your script reads it (typically with jq or a language JSON parser), does its work, and replies
through its exit code and/or stdout.
Every event includes common fields; each event adds its own:
| Field | Meaning | Present on |
|---|---|---|
session_id | Unique ID for this session | All events |
cwd | Working directory when the event fired | All events |
hook_event_name | Which event triggered the hook | All events |
transcript_path | Path to the conversation transcript | All events |
tool_name | The tool involved (e.g. Bash) | Tool events |
tool_input | The arguments Claude passed to the tool | PreToolUse / PostToolUse |
tool_response | The tool's result | PostToolUse |
prompt | The submitted prompt text | UserPromptSubmit |
source | startup / resume / clear / compact | SessionStart |
stop_hook_active | true if a Stop hook already forced a continuation | Stop / SubagentStop |
CONCEPT Output: exit codes, or structured JSON
A hook answers Claude Code in one of two ways:
- Exit codes (simple) —
0= success/no objection;2= block the action and feed stderr back to Claude; any other code = non-blocking error (stderr goes to the debug log, action proceeds). Onexit 0, stdout is added to Claude's context forUserPromptSubmitandSessionStart; for other events plain stdout just goes to the debug log. - Structured JSON (rich) —
exit 0and print a JSON object to stdout for fine control:continue,decision,hookSpecificOutput, etc. (covered in 6.4).
exit 2, Claude Code ignores any JSON —
exit 2 wins. Use exit 2 with a stderr message, or exit 0 with JSON, never both.DIAGRAM The stdin → work → reply loop
event JSON to stdin"] IN --> HK["Your command reads it
(jq / parser)"] HK --> DEC{"How to reply?"} DEC -->|"exit 0"| OK["✅ Proceed
(stdout may add context)"] DEC -->|"exit 2 + stderr"| BLK["🔴 Block
stderr → Claude"] DEC -->|"exit 0 + JSON stdout"| JSON["🟠 Structured control
decision / permissionDecision"] DEC -->|"other code"| ERR["Non-blocking error
stderr → debug log"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class OK ok; class JSON gate; class BLK bad;
CODE Read stdin, act on it
A PreToolUse hook that inspects the Bash command and blocks table drops via exit 2.
Everything on stderr becomes Claude's feedback; exit 0 means "no objection."
#!/bin/bash INPUT=$(cat) # read the JSON from stdin COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command') if echo "$COMMAND" | grep -q "drop table"; then echo "Blocked: dropping tables is not allowed" >&2 # stderr → Claude exit 2 # 2 = block the action fi exit 0 # 0 = no decision; normal permission flow applies
PreToolUse hook, exit 0 does not auto-approve
the tool — the normal permission flow still runs. It only means "this
hook has no objection."TRADE-OFFS Exit codes vs. structured JSON
✅ Exit codes
- Dead simple:
0,2, other - stderr on exit 2 is the feedback channel
- Perfect for block / format / log hooks
⚠️ Structured JSON
- More expressive: allow / deny / ask, rewrite input, inject context
- Must be valid JSON on stdout with
exit 0 - Ignored if you exit 2 — pick one channel
EXAM TRAPS
$1 $2." → No. Input is a JSON object
on stdin. Read it with cat / jq, not positional args.PreToolUse, exit 0 just means "no
objection"; the normal permission prompt still applies. To skip it you need JSON "allow".UserPromptSubmit and SessionStart; elsewhere it goes to the debug
log unless you emit structured JSON.PRACTICE
Q1 · How does a hook receive the tool's arguments?
As a JSON object on stdin. For a tool event, .tool_input holds the
arguments — e.g. jq -r '.tool_input.command' for a Bash call.
Q2 · Your PreToolUse hook exits 2 and writes to stderr. What happens?
The tool call is blocked and the stderr text is fed back to Claude as feedback so it can adjust. Any JSON you also printed is ignored.
Q3 · You want a SessionStart hook to add notes to context. Which channel?
Write the notes to stdout and exit 0. For SessionStart (and
UserPromptSubmit), stdout on exit 0 is injected into Claude's context.