Prompt-based hooks let Claude evaluate the event with a short prompt, making allow/deny decisions that are too nuanced for pure shell scripts.

What it does

Instead of a shell command, you provide a prompt. Claude Code sends the event context to a lightweight model call, and the response shapes the hook's decision. The model can reason about the content of a prompt or tool call, not just regex-match it. This opens up semantic policies - "block this if it looks like a destructive production action".

When to use it

Policies that require judgment ("is this prompt about the production DB?").
Content classification that a regex can't do reliably.
Advisory hooks that suggest improvements rather than block.
Cases where the event context is too complex for simple checks.

Gotchas

Prompt-based hooks add model latency to every fire. Pick a cheap, fast model.
Non-determinism is a feature and a bug - the same event might decide differently twice.
For safety-critical policy, pair with a deterministic shell hook for defense in depth.

Official docs: https://code.claude.com/docs/en/hooks.md#prompt-based-hooks