Hooks¶
Hooks execute configured shell commands or plugin handlers on agent events.
Events you can hook¶
| Event | Timing | Effect of a block |
|---|---|---|
pre_tool_use |
After permission allows a tool, before execution | Refuse the tool |
post_tool_use |
After tool completion | Log the block |
on_message |
When a user or assistant message is persisted | Log the block |
on_compact |
After context compaction | Log the block |
A timeout blocks a pre_tool_use operation. For observational events it is
logged and execution continues. Malformed handler responses are treated as
continue; a timeout and an invalid response have different behavior.
Shell command¶
[hooks]
enabled = true
default_timeout_secs = 5
[[hooks.entries]]
event = "pre_tool_use"
command = "/usr/local/bin/audit.sh"
timeout_secs = 2
[hooks.entries.matcher]
tool = "Bash"
The program receives event JSON on stdin. Empty stdout permits execution;
valid outcome JSON can return a decision. A nonzero pre_tool_use exit
blocks the tool and uses the stderr tail as the reason.
Plugin¶
A plugin declares subscribed events in its manifest:
See Plugins.
Matching specific tools¶
matcher.tool limits a shell hook to a tool name. Without a matcher, the
hook receives every applicable event.
Inspecting what's active¶
Lists configuration without invoking handlers. Permissions are evaluated before hooks; a hook does not replace a permission denial.