skip to content

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%

answer

  1. exit codes only block
  2. four outcomes, not one
  3. nested under hookSpecificOutput
  4. replaces the whole input

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.

solid answer

~40 s

Use 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
json
{
  "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

for a junior

Recall that exit 2 can only block, while JSON can also allow, ask or deny, and that the decision goes inside hookSpecificOutput.

for a middle

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.

for a senior

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.

for a principal

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