skip to content

Claude Code hooks offer command, http, mcp_tool, prompt and agent handlers; how do you choose between them for a given check?

level: seniorimportance: should knowfreq 12%

answer

  1. deterministic script versus model judgement
  2. one model call versus a tool-using verifier
  3. same JSON contract over a POST
  4. a connected server's tool as the handler
  5. not every event takes every type

basics

~20 s

Command suits deterministic checks, http hands the event to a shared service, mcp_tool calls a connected MCP server's tool, prompt makes one model judgement on the hook input, and the experimental agent type verifies by reading files or running tools.

solid answer

~50 s

A `command` handler runs a shell command with the event JSON on stdin and answers through exit codes and stdout; it is the default for formatters, guards and anything deterministic. `http` POSTs the same JSON to a URL and reads the same JSON contract from a 2xx response body, which suits a team-wide audit or policy service; status codes alone never block. `mcp_tool` calls a tool on a configured MCP server, with `input` values such as `"${tool_input.file_path}"` filled from the event. `prompt` sends the hook input to a Claude model for one evaluation that returns `{"ok": ..., "reason": ...}` (30-second default timeout), so it judges only what the input shows. `agent`, which is experimental, spawns a subagent that can use Read, Grep and Glob for up to 50 turns (60-second default timeout) when the answer depends on the codebase. Event support differs: `SessionStart` takes only `command` and `mcp_tool`, and `PermissionRequest` skips `agent` hooks.

go deeper

for a junior

Recall that command is the default type, that prompt and agent use a Claude model, and that http posts the event to a URL.

for a middle

Explain how each type answers: exit codes and stdout, a 2xx JSON body, a tool's text, or the ok and reason JSON. Know the default timeouts of 600, 30 and 60 seconds.

for a senior

Choose by what the check needs: determinism, a shared service, an existing tool, judgement, or judgement plus evidence. Mention event support limits, agent hooks being experimental, and how ok:false lands on PreToolUse.

for a principal

Weigh cost and reliability across a team: model-backed hooks add latency and tokens on every firing, so reserve them for decisions a script cannot make and keep hard gates deterministic.

## Five handler types Every hook has three levels: an **event**, a **matcher group**, and one or more **handlers**. The handler's `type` field decides what actually runs. | Type | What runs | How it answers | Default timeout | |---|---|---|---| | `command` | a shell command (or an executable with `args`) | exit code, stdout JSON, stderr | 600 s | | `http` | a POST of the event JSON to `url` | JSON in a 2xx response body | 600 s | | `mcp_tool` | a tool on a configured MCP server | the tool's text, read like stdout | 600 s | | `prompt` | one evaluation by a Claude model | `{"ok": true}` or `{"ok": false, "reason": "..."}` | 30 s | | `agent` | a subagent with tool access (experimental) | the same `ok` / `reason` shape | 60 s | Some events lower the default for the first three types; `UserPromptSubmit`, for example, uses 30 seconds. ## Deterministic handlers - **`command`** is the workhorse. Anything a script can decide by inspecting the input or the disk belongs here: format-on-edit, protected-file guards, logging, notifications. It is also the only type that accepts `async` and `asyncRewake` for background work. - **`http`** moves the logic into a service: one audit endpoint for every developer, a policy server, a cloud function. Headers can carry secrets via `$VAR` interpolation, but only for variables listed in the hook's `allowedEnvVars`. A non-2xx status, a connection failure or a plain-text body is a **non-blocking error**; to deny, return a 2xx with the decision fields in JSON. - **`mcp_tool`** reuses a tool you already have connected, such as a scanner exposed by an MCP server, with `server`, `tool` and an `input` object whose string values take `${path}` substitutions from the hook input. If the tool returns `isError: true` or the server is not connected, the result is a non-blocking error. ## Judgement handlers - **`prompt`** suits decisions that need judgement but no new facts: "does this final message claim work it did not show?", "does this prompt leak a customer name?". Use `$ARGUMENTS` in the prompt to place the hook input; the `model` field overrides the default, which is the model Claude Code uses for background work. On a `PreToolUse` hook, `ok: false` denies the call and **ends the turn by default** since v2.1.210; `continueOnBlock: true` instead returns the reason to Claude so it can adjust. On `Stop`, the reason becomes Claude's next instruction unless the model also sets `impossible: true`. - **`agent`** suits checks that need evidence: run the tests, grep for leftover debug calls, read the changed files. It costs a multi-turn model run per firing, is **experimental**, and the docs recommend command hooks for production workflows. On `ok: false` it behaves like a prompt hook with `continueOnBlock: true`; it has neither that field nor `impossible`. ## Which events accept which type - All five types: tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `PermissionDenied`), `Stop`, `SubagentStop`, `UserPromptSubmit`, `UserPromptExpansion` and the task and teammate events. - `PermissionRequest`: everything except `agent`, which is skipped. A prompt hook's `ok: false` has no effect there; deny with a command or HTTP hook's decision object. - `SessionStart` and `Setup`: `command` and `mcp_tool` only. - Most other events, such as `Notification`, `PreCompact`, `ConfigChange` and `SessionEnd`: `command`, `http` and `mcp_tool`. ## Choosing 1. Can a script decide it from the input or the files? Use **`command`**. 2. Does the logic belong in a shared service, or must results be centralised? Use **`http`**. 3. Is the capability already a tool on a connected server? Use **`mcp_tool`**. 4. Does it need judgement over the input alone? Use **`prompt`**, and accept latency and token cost on every firing. 5. Does it need judgement plus evidence from the repository? Use **`agent`**, knowing it is experimental and slower. ## Cost and observability - Every `prompt` or `agent` firing is a model request, so a hook on a busy event such as `PostToolUse` multiplies latency and token use; scope it with a matcher. - The common `statusMessage` field sets a custom spinner message while any handler runs, which helps users understand a pause caused by a slow check. - Timeouts can be overridden per handler with `timeout`, in seconds. One more handler field matters when choosing where to declare a hook: `once: true` removes a hook after its first successful run, and it is honoured only in skill frontmatter.

  • Why does an mcp_tool hook on SessionStart do nothing at launch, yet run after a compaction?
    `SessionStart` at launch, including `--continue` and `--resume`, fires before the session's MCP servers are available, so Claude Code skips `mcp_tool` hooks and logs that no MCP client context exists. When `SessionStart` fires again after `/clear` or a compaction, the servers are up and the hook runs. Anything needed at launch, such as re-adding conventions, belongs in a `command` hook.
  • Your HTTP hook service answers 403 to block a Bash call, but the call runs. Why?
    HTTP status codes cannot block. A non-2xx response is a non-blocking error and execution continues. To deny, return a 2xx response whose JSON body carries `hookSpecificOutput` with `hookEventName: "PreToolUse"` and `permissionDecision: "deny"` plus a reason, exactly as a command hook would print it.
  • On a PreToolUse hook, how does an agent hook's ok:false differ from a prompt hook's by default?
    A prompt hook's `ok: false` denies the call and ends the turn, showing the reason as a warning line, unless `continueOnBlock: true` is set. An agent hook is always handled as if `continueOnBlock` were true: the call is denied, the reason goes back to Claude as the tool error, and the turn continues.

  • A prompt hook can run the test suite itself before deciding whether to allow.
  • An HTTP hook blocks a tool call by returning a 4xx status code.
  • Agent hooks are the stable, recommended handler for production gates.
  • Every hook event accepts all five handler types.
  • Setting async: true on a prompt hook keeps its judgement off the critical path.

Assumes Claude Code 2.1.286; since 2.1.210 a prompt hook's ok:false on PreToolUse ends the turn unless continueOnBlock is true.