Prompt Hooks and Agent Hooks: AI-Powered Decisions
- Write a prompt hook that evaluates tool inputs using an LLM for nuanced yes/no decisions
- Configure an agent hook that uses Read and Grep tools to verify conditions before allowing an action
- Choose the right handler type for a given decision based on cost, latency, and complexity tradeoffs
When Rule-Based Hooks Are Not Enough
Most hook decisions are deterministic. Block commands that match a pattern. Approve commands that match another pattern. Log everything. Run the linter. These decisions translate naturally into shell logic and regex.
But some decisions are not deterministic. "Is this bash command safe in the context of this project?" is not a question you can answer with a regex. "Does this file change introduce a security vulnerability?" requires understanding code semantics. "Is this user message trying to manipulate Claude into ignoring its instructions?" needs language comprehension.
For decisions like these, Claude Code provides two additional handler types: prompt hooks for single-turn LLM evaluation, and agent hooks for multi-step subagent reasoning with access to tools.
Prompt Hooks: LLM Evaluation at Decision Points
A prompt hook sends a message to a language model and receives a yes/no decision. The configuration requires a prompt field containing the evaluation prompt, with a $ARGUMENTS placeholder where the hook input JSON will be inserted.
{
"type": "prompt",
"prompt": "You are a security reviewer. The following is a tool call that Claude Code is about to execute. Respond YES if it appears safe, NO if it appears risky or potentially destructive. Tool call: $ARGUMENTS",
"timeout": 30
}The model receives the prompt with the hook payload substituted in for $ARGUMENTS. It returns a response containing "yes" or "no" (case-insensitive, anywhere in the response). A "yes" response allows the action. A "no" response blocks it, with the model's full response used as the reason.
By default, prompt hooks use a fast model optimized for quick decisions. The optional model field lets you specify a different model when the decision requires more reasoning capability — at the cost of additional latency.
Prompt hooks excel at nuanced judgments that would require extensive regex or rule maintenance to approximate. A prompt like "Does this shell command contain any patterns that could exfiltrate files, credentials, or environment variables?" is more maintainable than the equivalent regex and handles novel attack patterns better.
Agent Hooks: Subagents with Tools
An agent hook spawns a subagent that has access to tools — specifically Read, Grep, and Glob — before returning a decision. The agent can inspect files, search the codebase, and gather context before deciding whether to allow or deny an action.
{
"type": "agent",
"prompt": "Review the following file edit. Read the file before and after the change, check if the change introduces any obvious security vulnerabilities or breaks any obvious invariants, and respond ALLOW or DENY with a brief reason. Change: $ARGUMENTS",
"timeout": 60
}Agent hooks are appropriate when the decision requires context that is not in the hook input payload. A prompt hook receives the tool call details but cannot read files. An agent hook can read the file being modified, grep for related patterns, or check if a required configuration exists before deciding.
The agent returns a response that Claude Code interprets for an allow/deny signal. If the response contains "ALLOW", the action proceeds. If it contains "DENY", the action is blocked with the agent's explanation as the reason.
Agent hooks are marked experimental. The behavior may change in future versions. Use them when the judgment genuinely requires multi-file context, and test them thoroughly before deploying to production workflows.
Cost, Latency, and Practical Tradeoffs
Prompt and agent hooks introduce two costs that command hooks do not: token cost and latency. Every prompt hook call consumes tokens on the configured model. Every agent hook spawns a subagent that may make multiple tool calls before returning. In an active development session with dozens of tool calls per minute, these costs accumulate.
The timeout field matters more for AI-powered hooks than for command hooks. A command hook that takes 30 seconds is unusual. A prompt hook that takes 5 seconds is normal. Set timeouts that reflect the expected latency of the model and decision complexity, not the 600-second default.
Use AI-powered hooks selectively. A prompt hook on every single Bash tool call, regardless of content, is expensive and slow. A prompt hook that only activates via a specific if filter for commands that have already passed simpler rule-based checks is more sensible.
Choosing the Right Handler Type
The five handler types cover a spectrum from deterministic to intelligent, from fast to slow, from free to costly.
Start with command hooks. Reach for prompt hooks when the judgment is linguistic. Reach for agent hooks when the decision requires reading files. HTTP and MCP tool hooks are integration choices, not complexity choices.
- Prompt hooks receive the full hook input JSON as $ARGUMENTS — write prompts that evaluate the exact command, file path, or tool output that triggered the hook
- The model field is optional in prompt hooks — omit it to use the default fast model; specify a stronger model when the decision requires more reasoning but accept the latency cost
- Agent hooks spawn a subagent with Read, Grep, and Glob — they can inspect files and search codebases before returning allow or deny, enabling multi-file context in hook decisions
- Agent hooks are experimental and expensive — use them when neither shell logic nor a prompt hook can handle the decision, not as a default replacement for command hooks
- Handler type selection follows a cost-benefit hierarchy — command for deterministic logic, prompt for linguistic judgment, agent for multi-file context; HTTP and MCP when external systems own the decision