# Agent Hook

> A hook that sends a helper to look at files. Then it answers.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** type: agent

## Think of it like

It is like you send a helper to go and look. Then they say yes or no.

## Definition

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.

## Example code

```json
{
  "type": "agent",
  "prompt": "Check that every changed file has a matching test file."
}
```

Let a helper look before Claude stops.

## Why it matters

A prompt hook only sees the event. An agent hook can open files and check.

## Common mistake

Using it on an event that fires a lot. Each run can take many turns and many tokens.

## Three principles

- **Starts a helper.** With tools.
- **Up to 50 turns.** Then ok or not.
- **Experimental.** May change.

## Related terms

- [Prompt Hook](https://learn.benibix.com/term/ai/prompt-hook)
- [Subagent](https://learn.benibix.com/term/ai/subagent)
- [Stop Hook](https://learn.benibix.com/term/ai/stop-hook)

## Told apart from

- [Prompt Hook vs Agent Hook](https://learn.benibix.com/compare/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.

---

Source: https://learn.benibix.com/term/ai/agent-hook
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
