Prompt-Based Hooks - Claude Code

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