Hooks
Deterministic handlers that run at defined points in an agent lifecycle to validate, block, transform, log, or trigger work.
Use it when
- A formatter, validator, audit log, or policy check must run consistently.
- Tool calls need inspection before or after execution.
- The environment or context must be refreshed at a known lifecycle event.
Choose another layer when
- Open-ended reasoning that benefits from the main agent's full context.
- Unreviewed third-party scripts with broad local or network access.
Production path
Build it in this order
- 01
Choose the narrowest event
Trigger only at the lifecycle point and tool pattern that require control; avoid global handlers when a scoped matcher works.
Quality check: The hook does not slow or alter unrelated operations.
- 02
Fail clearly and safely
Set timeouts, validate input, use meaningful exit behavior, and return guidance the agent or user can act on.
Quality check: Failure cannot silently bypass a required policy or trap the session in a loop.
- 03
Review it as executable code
Inspect commands, URLs, permissions, logging, and secret handling before enabling shared or downloaded hooks.
Quality check: Every side effect and external destination is documented and owned.
Artifacts you may see
- .claude/settings.json
- hooks/hooks.json
- Skill or agent frontmatter
- policy scripts
Connected layers
Evidence ledger
Primary documentation behind this guide
Provider-specific behavior is sourced to that provider. Open standards are sourced to their specifications and official maintainers.