Hooks
Declarative shell commands that run on Venna Code engine events to observe — or block — tool calls.
A hook is a declarative shell command that runs on a Venna Code engine event. Drop a
~/.venna/hooks/<name>.toml with one or more [[hook]] entries:
[[hook]]
event = "PreToolUse"
matcher = "bash" # tool-name glob, for the *ToolUse events
command = "./guard.sh"
timeout_secs = 30 # default 30
enabled = true # default trueEvents
Prop
Type
The contract
A hook reads the event as JSON on stdin and returns its verdict — allow or block — on
stdout. Toggle hooks per session; a per-session override beats the file's enabled default
(last write wins).
PreToolUse fails closed
Hooks are fail-safe — a timeout or error never wedges the turn. The exception is the blocking
PreToolUse event: if it times out, the tool does not run. Other events log the failure and
continue.
Next steps
- Hooks reference — event payload shapes, the matcher grammar, and the stdin/stdout verdict contract.
- Plugins — bundle hooks with skills, MCP servers, and commands into one installable unit.