Skip to content
BENIBIX Learn

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.

AI⌨️ Claude Code

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.

Example
Lucy cannot write a script that knows if a task is finished. A prompt hook on Stop asks a model to judge it.
Why it matters
Some checks are about meaning. A model can judge them where a script cannot.
Full entry
AI⌨️ Claude Code

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.

Example
Emma wants Claude to stop only when every new file has a test. Her agent hook looks through the folder before it says yes.
Why it matters
A prompt hook only sees the event. An agent hook can open files and check.
Full entry

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.