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?
answer
- exit codes only block
- four outcomes, not one
- nested under hookSpecificOutput
- replaces the whole input
basics
~20 sExit 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.
solid answer
~40 sUse JSON whenever the hook needs more than a yes/no block. Printed on stdout with exit 0, `hookSpecificOutput` with `hookEventName: "PreToolUse"` supports `permissionDecision`: `"allow"` skips the permission prompt, `"ask"` forces one and shows `permissionDecisionReason` to the user, `"deny"` blocks and shows the reason to Claude, and `"defer"` pauses the call, honoured only in `-p` runs. `updatedInput` **replaces the tool's whole input object**, so it must carry unchanged fields too, and permission rules are checked against the rewritten input; pair it with `allow` to auto-approve or `ask` to show the user the change. `additionalContext` adds a note next to the tool result. The fields must sit inside `hookSpecificOutput`: a top-level `permissionDecision` is silently ignored. An `allow` still can't override a deny or ask rule.
code
json · 11 lines{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"permissionDecisionReason": "Rewritten as a dry run; confirm before syncing",
"updatedInput": {
"command": "rsync -av --dry-run ./dist/ [email protected]:/srv/app/",
"description": "Preview the deploy sync"
}
}
}go deeper
Recall that exit 2 can only block, while JSON can also allow, ask or deny, and that the decision goes inside hookSpecificOutput.
Explain where each decision's reason goes, that updatedInput replaces the whole input object, and that the JSON must be the only thing on stdout.
Show judgment on when to rewrite rather than block, why permission rules see the rewritten input, why only one hook should rewrite a tool, and the silent failures of misplaced fields.
Weigh hooks as policy middleware against permission rules: hooks can tighten and redirect but not loosen past the rules, so decide which controls live in rules and which need a hook's logic.
## Why JSON exists alongside exit codes An exit code gives a hook two answers: **stay silent** (`exit 0`) or **block** (`exit 2`). Many real hooks need more. They want to wave a known-safe call through without a prompt, insist that a human confirm a risky one, rewrite an argument before it runs, or tell Claude something useful. For that, the hook exits 0 and prints **one JSON object** on stdout. On `PreToolUse` the decision lives in a nested **`hookSpecificOutput`** object, which must include `hookEventName: "PreToolUse"`. ## The four decisions | `permissionDecision` | Effect | Where `permissionDecisionReason` goes | |---|---|---| | `"allow"` | Skips the permission prompt | Debug log only | | `"ask"` | Forces a permission prompt, even in auto mode | Shown to the user in the prompt | | `"deny"` | Blocks the tool call | Shown to Claude, so it can change course | | `"defer"` | Pauses the call so a calling process can resume it later | Debug log only | Some boundaries matter: - **`allow` is not a master key.** Deny and ask rules from settings are still evaluated, so a matching deny rule blocks the call anyway. A few protected actions that no mode auto-approves still prompt, and `AskUserQuestion` and `ExitPlanMode` need `updatedInput` paired with `allow`. - **`ask` labels its source.** The prompt shows where the hook came from, such as `[settings]`, `[plugin:<name>]` or `[skill]`, so the user knows which configuration asked. - **`defer` is for integrations.** It is honoured only in non-interactive `-p` runs, and only when Claude made a single tool call in the turn; interactive sessions log a warning and ignore it. - **Exit 2 routes like `deny`.** A hook that exits 2 is treated as a denial, with stderr as the reason Claude sees. ## Rewriting the call with `updatedInput` `updatedInput` sits directly under `hookSpecificOutput` and **replaces the entire input object** of the tool call. It is not merged, so a hook that sends back only a changed `command` drops the call's other fields. Copy the original `tool_input`, change what you need and return the whole object. Claude Code evaluates permission rules against the **input your hook returns**, not the input Claude sent. Combine `updatedInput` with: 1. **`allow`** to run the rewritten call without a prompt, or 2. **`ask`** to show the user the modified call and let them confirm it. With `defer`, `updatedInput` is ignored. When more than one hook returns `updatedInput` for the same call, the last to finish wins, and since hooks run in parallel that order is non-deterministic, so let only one hook rewrite a given tool. ## Adding context and stopping entirely - **`additionalContext`** inside `hookSpecificOutput` is wrapped in a system reminder and placed next to the tool result. Use factual statements ("this directory is generated from `schema.ts`") rather than imperative system-style commands, which can trip Claude's prompt-injection defences. - **`continue: false`** at the top level stops Claude's processing entirely after the hook runs, with `stopReason` shown to the user. It takes precedence over the event-specific decision. - **`systemMessage`** shows a warning to the user without changing the decision. ## Getting the JSON read at all 1. Print **only** the JSON object on stdout. Anything before the `{`, such as a banner from a shell profile, turns the output into ignored plain text. 2. Nest the decision fields inside `hookSpecificOutput`. A top-level `permissionDecision` parses but is ignored with no error, and the debug log lists it under `Hook JSON output had unrecognized keys`. 3. Don't use the old top-level `decision` and `reason` on this event. They are deprecated for `PreToolUse`, with `"approve"` and `"block"` mapped to `allow` and `deny`. Other events, such as `PostToolUse` and `Stop`, still use top-level `decision`. 4. Build the object with an encoder such as `jq -n`, so quotes inside a reason don't break parsing. ## When to choose which | Need | Use | |---|---| | A plain yes/no block with a message | `exit 2` and stderr | | Approve known-safe calls without a prompt | JSON `allow` | | Make a human confirm a risky call | JSON `ask` with a reason | | Change the call's arguments | `updatedInput` with `allow` or `ask` | | Give Claude a hint without deciding | `additionalContext`, no decision |
- Why does a hook's `ask` matter in auto mode?A hook's `ask` forces a permission prompt in auto mode as well. The auto-mode classifier can still deny the call, but it can't approve it silently. That lets a hook mark specific calls as needing a human even in sessions where most calls are approved without prompting.
- Can `updatedInput` sneak a call past a deny rule?No. Claude Code evaluates permission rules against the input the hook returns, so a rewritten command that matches a deny rule is still blocked, and an `allow` paired with it doesn't override that rule. Rewriting changes what is checked, not whether the check happens.
- A hook's allow overrides any deny rule in settings
- updatedInput is merged into the original tool input field by field
- permissionDecision works at the top level of the JSON object
- PreToolUse still uses top-level decision: block as its current format
- A deny reason is shown only to the user, not to Claude