Agent-based hooks spawn a subagent to handle the hook, giving you full tool access and multi-step reasoning inside a hook.

What it does

When the event fires, Claude Code hands off to a subagent with its own tools, context, and system prompt. The subagent can read files, run commands, consult external APIs, and return a decision. This is overkill for logging but perfect for rich policy - "review this diff for security issues before allowing the write".

When to use it

Policies that need to read multiple files before deciding.
Advisory reviewers that post comments rather than block.
Complex approval flows that can't fit in a single prompt.
Integrating an auditor role into the hook pipeline.

Gotchas

Agents in hooks are slow relative to command or prompt hooks. Use sparingly.
Each hook fire costs a subagent spawn. Cache where possible.
Circular dependencies (hook agent triggers same hook) are easy to write and hard to debug.

Official docs: https://code.claude.com/docs/en/hooks.md#agent-based-hooks