Agent-Based Hooks - Claude Code

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