skip to content

Input, Output & Exit Status

The hook contract: JSON arrives on stdin, exit 2 blocks, exit 1 does not, and JSON on stdout can allow, deny, rewrite input or add context. Asked because a gate that exits 1 lets everything through.

part ofClaude Coderead it →
on this pageshow

explore

questions

5

How does a Claude Code command hook receive the event's data, and how does it report its result back?

level: juniorimportance: must knowfreq 22%

answer

  1. one object per event
  2. read from stdin, not arguments
  3. exit code plus stdout
  4. two is the special code

basics

~20 s

Claude Code pipes one JSON object describing the event to the hook's stdin. The hook answers with its exit code (0 success, 2 block where the event allows it, others a non-blocking error) and, optionally, a JSON object on stdout.

solid answer

~50 s

A command hook reads the event as one JSON object on stdin: common fields such as `session_id`, `transcript_path`, `cwd`, `permission_mode` and `hook_event_name`, plus event-specific ones, which on tool events are `tool_name`, `tool_input` and `tool_use_id`. It answers through three channels. The **exit code**: `0` is success, `2` is a blocking error on events that can block, and any other code is a non-blocking error unless valid JSON decides. **Stdout**: a JSON object is read for fields such as `permissionDecision`, `decision`, `additionalContext` or `continue`; plain text reaches Claude only on a few events such as `UserPromptSubmit` and `SessionStart`, and otherwise goes to the debug log. **Stderr**: becomes the reason on an exit-2 block, a short notice on other failures, and only the debug log on exit 0. An HTTP hook gets the same JSON as its POST body and answers with a JSON response body.

go deeper

for a junior

Remember the shape: one JSON object on stdin, an exit code back, and optional JSON on stdout. Know that 2 is the blocking code and that tool events carry tool_name and tool_input.

for a middle

Explain each channel: which stdin fields are common versus event-specific, how stdout is parsed as JSON or plain text, and where stderr ends up on exit 0, exit 2 and other codes.

for a senior

Show you design hooks around the contract: clean stdout, absolute file paths in tool_input, last_assistant_message instead of the lagging transcript, and per-event differences in what a block means.

for a principal

Discuss the contract as an interface teams build on: one shared parsing helper, fixtures of real stdin payloads for tests, and the risk that a silent stdout or exit-code mistake leaves a policy unenforced.

## The contract in one sentence A Claude Code **command hook** is a program that Claude Code starts when a lifecycle event fires and a matcher matches. Claude Code writes **one JSON object** describing the event to the program's **stdin**, then reads back three things: the **exit code**, **stdout** and **stderr**. The event data never arrives as command-line arguments, and the hook cannot call tools or slash commands itself; it can only answer. ## What arrives on stdin Every event carries a set of **common input fields**, and each event adds its own: | Field | What it holds | |---|---| | `session_id` | The current session's identifier | | `transcript_path` | Path to the conversation file on disk (written asynchronously, so it can lag) | | `cwd` | The working directory when the hook runs | | `permission_mode` | The current mode, such as `default`, `plan`, `acceptEdits`, `auto`, `dontAsk` or `bypassPermissions` (not every event receives it) | | `hook_event_name` | Which event fired, such as `PreToolUse` | | `tool_name`, `tool_input`, `tool_use_id` | Tool events only: which tool, its arguments, and the call's id | For a Bash call, `tool_input` carries `command`, `description` and the call's other arguments, so a guard reads `.tool_input.command`. For the file tools `Write`, `Edit` and `Read`, `tool_input.file_path` is always **absolute**: Claude Code expands `~` and relative paths before the hook runs, so a path check can't be dodged by spelling the path differently. Stop hooks also get `last_assistant_message`, which is the reliable way to read the turn's final reply. ## The three return channels - **Exit code** decides the coarse outcome. `0` means success. `2` means a **blocking error**: on events that can block, the action is stopped. Any other code, including the Unix-conventional `1`, is a **non-blocking error** on most events: the action proceeds and the transcript shows a `<hook name> hook error` notice. - **Stdout** carries structured decisions. If it starts with `{` and ends with `}`, Claude Code parses it as **JSON output** and honours the fields the event supports. It reads that JSON on every exit code, and an exit-2 block still holds whatever the JSON says. - **Stderr** is the human-readable message. On an exit-2 block it becomes the reason, shown to Claude on events such as `PreToolUse`. On exit 0 it goes only to the debug log, and Claude never sees it. ## Exit codes at a glance | Exit code | Meaning | Typical effect on `PreToolUse` | |---|---|---| | `0`, no output | Success, no decision | Normal permission flow continues | | `0`, JSON on stdout | Success with structured control | JSON fields decide (allow, deny, ask, context) | | `2` | Blocking error | Tool call blocked; stderr is the reason Claude sees | | Any other | Non-blocking error | Call proceeds; a hook error notice appears, unless valid JSON decides | The effect of a block **depends on the event**. Exit 2 blocks a tool call on `PreToolUse`, rejects the prompt on `UserPromptSubmit` and keeps Claude working on `Stop`, but on `PostToolUse` the tool already ran, so it only feeds stderr to Claude. On `PermissionRequest` exit 2 isn't honoured at all. ## Where plain stdout goes On most events, a successful hook's plain-text stdout is written to the **debug log only**. The exceptions are `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` and `PostModelSwitch`, where plain stdout is added as context Claude can read. Elsewhere, to put text in front of Claude, return `additionalContext` inside `hookSpecificOutput`. Keep stdout clean: a shell profile that echoes a banner breaks the leading `{` and turns your JSON into ignored plain text. ## A minimal hook ```bash #!/bin/bash input=$(cat) # the whole event, once event=$(jq -r '.hook_event_name' <<<"$input") tool=$(jq -r '.tool_name // empty' <<<"$input") echo "$(date -u +%FT%TZ) $event $tool" >> "$HOME/.claude-hook-audit.log" exit 0 # no decision ``` The script reads stdin once, extracts fields with `jq`, does its side effect and exits 0, so it never changes what Claude Code does. ## HTTP hooks use the same data An `http` hook receives the identical JSON as the **POST request body** and answers with the same JSON output format in a 2xx response body. Status codes alone can't block: a non-2xx response, a connection failure or plain text is a non-blocking error, so an HTTP guard must return a JSON decision to stop anything.

  • On which events does a hook's plain-text stdout reach Claude on exit 0?
    On `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` and `PostModelSwitch`, Claude Code adds plain stdout to Claude's context. On every other event a successful hook's stdout goes only to the debug log. To show Claude something from, say, a `PostToolUse` hook, return `additionalContext` inside `hookSpecificOutput`.
  • Why can a Stop hook that parses `transcript_path` miss the reply it wants?
    The transcript file is written asynchronously and may lag the in-memory conversation, so the turn's last assistant message may not be in it yet. Stop and SubagentStop hooks receive `last_assistant_message` with that text directly; read it instead of the file.

  • The event data is passed to the hook script as command-line arguments
  • Any non-zero exit code tells Claude Code to block the action
  • Whatever a hook prints to stdout is always shown to Claude
  • Stderr from a hook that exits 0 is fed back to Claude as a warning
  • An HTTP hook blocks a tool call by returning a 403 status
open as a page

A Claude Code PreToolUse guard prints an error and exits 1 on terraform destroy, yet the command still runs. Why, and what do you change?

level: middleimportance: must knowfreq 18%

basics

~20 s

Claude Code treats exit 1 as a non-blocking error, so the call proceeds with only a hook-error notice. Exit 2 with the reason on stderr, or exit 0 and print JSON with permissionDecision set to deny.

open as a page

When should a Claude Code PreToolUse hook return JSON with permissionDecision instead of exiting 2, and what do allow, ask, deny and updatedInput each do?

level: seniorimportance: should knowfreq 10%

basics

~20 s

Exit 2 can only block. JSON in hookSpecificOutput can allow (skip the prompt), ask (force one), deny (block with a reason Claude sees) or rewrite the call with updatedInput, which replaces the entire input object.

open as a page

A Claude Code Stop hook blocks until a condition holds, and Claude keeps working long after it should stop. Why does it loop, and how do you guard it?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Each decision: block or exit 2 sends Claude back to work, and the next finish fires the hook again. Check stop_hook_active in the stdin JSON and exit 0 when it is true; Claude Code also ends the turn after eight consecutive blocks.

open as a page

In Claude Code, how is a tool call decided when several PreToolUse hooks return different decisions and a permissions deny rule also matches?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

All matching PreToolUse hooks run in parallel, and their decisions combine as deny over defer over ask over allow. A hook's allow never overrides a deny or ask rule, while a hook's deny or exit 2 blocks even when an allow rule matches.

open as a page