Prompt Hook vs Agent Hook
People think both just ask a model. A prompt hook asks once and sees only the event. An agent hook starts a helper that can open files with tools, for up to 50 turns. Use a prompt hook for a quick judgment, and an agent hook when the answer is in the files.
Prompt Hook
A hook that asks a Claude model a yes or no question.
A prompt hook is a hook whose type is prompt, so it sends a prompt to a Claude model for a single answer. $ARGUMENTS in the prompt is swapped for the event's JSON. The model replies with ok true to allow, or ok false with a reason. It is used where the check needs judgment, not a fixed rule. Its default timeout is 30 seconds.
Agent Hook
A hook that sends a helper to look at files. Then it answers.
An agent hook is a hook whose type is agent, so it starts a subagent that can use tools such as Read, Grep and Glob to check something. After up to 50 turns it returns ok true or ok false with a reason. It suits checks that need to look at files, not just the event. Agent hooks are still experimental, and the default timeout is 60 seconds.
In one line
- Prompt Hook
- A hook that asks a Claude model a yes or no question.
- Agent Hook
- A hook that sends a helper to look at files. Then it answers.