D3 · Claude Code › Cluster 6 · Hooks

6.3 · Hook Input & Output

stdin JSON → exit codes / JSON

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:

FieldMeaningPresent on
session_idUnique ID for this sessionAll events
cwdWorking directory when the event firedAll events
hook_event_nameWhich event triggered the hookAll events
transcript_pathPath to the conversation transcriptAll events
tool_nameThe tool involved (e.g. Bash)Tool events
tool_inputThe arguments Claude passed to the toolPreToolUse / PostToolUse
tool_responseThe tool's resultPostToolUse
promptThe submitted prompt textUserPromptSubmit
sourcestartup / resume / clear / compactSessionStart
stop_hook_activetrue if a Stop hook already forced a continuationStop / SubagentStop

CONCEPT Output: exit codes, or structured JSON

A hook answers Claude Code in one of two ways:

⚠️ Don't mix the two. If you 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

flowchart TD EV["Event fires"] --> IN["Claude Code pipes
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
🔑 For a 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

Trap: "The hook gets arguments as $1 $2." → No. Input is a JSON object on stdin. Read it with cat / jq, not positional args.
Trap: "Exit 0 approves the tool." → For PreToolUse, exit 0 just means "no objection"; the normal permission prompt still applies. To skip it you need JSON "allow".
Trap: Printing JSON and exiting 2. → Exit 2 makes Claude Code ignore the JSON. Use stderr+exit 2, or JSON+exit 0 — not both.
Trap: Expecting stdout to reach Claude on every event. → On exit 0, stdout is added to context only for 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.