Prompt-based hooks

For decisions that require judgment rather than deterministic rules, use type: "prompt" hooks. Instead of running a shell command, Claude Code sends your prompt and the hook's input data to a Claude model, Haiku by default, to make the decision. You can specify a different model with the model field if you need more capability.

The model's only job is to return its decision as JSON:

• "ok": true: the action proceeds
• "ok": false: what happens depends on the event:
  • Stop and SubagentStop: the reason is fed back to Claude so it keeps working, unless the response also sets "impossible": true to mark the condition as one that can never be satisfied, in which case Claude Code allows the stop and the turn ends
  • PreToolUse: the tool call is denied; by default the turn ends and the deny reason appears in the chat as a warning line. Set continueOnBlock: true on the hook to instead return the reason to Claude as the tool error, so it can adjust and continue. Before v2.1.210, the deny reason was returned to Claude as the tool error and the turn continued
  • PostToolUse: by default the turn ends and the reason appears in the chat as a warning line. Set continueOnBlock: true to feed the reason back to Claude and continue the turn instead
  • PostToolBatch, UserPromptSubmit, and UserPromptExpansion: the turn ends and the reason appears in the chat as a warning line

This example uses a Stop hook to ask the model whether all requested tasks are complete. If the model returns "ok": false because the condition isn't met yet, Claude keeps working and uses the reason as its next instruction:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

For full configuration options, see Prompt-based hooks in the reference.