What it does
Everything an agent does passes through a small number of observable moments: a prompt is submitted, a tool is about to run, a file has just been edited, a session ends. Hooks let you attach your own executable to those moments so the behaviour you care about happens every time rather than when someone remembers.
Two categories matter in practice. Observational hooks record what happened, feeding audit logs, usage telemetry, or a compliance trail. Gating hooks sit in front of an action and can block it, which is how teams stop agents from touching production configuration, committing secrets, or running a command outside an allowlist.
Because a hook is a normal executable receiving structured input, it can be written in whatever language your repo already uses, and it is reviewable in version control alongside the rules and skills it enforces.
Worth knowing
- A slow hook slows every agent action it is attached to, so keep gating hooks fast and push expensive analysis into observational hooks that do not block.
- Hooks run with your local permissions. Treat a hook script from an untrusted source the same way you would treat any other code you are about to execute.
Checked against Hooks documentation on 25 September 2026.