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
PreToolUse— before a tool runs. The only blocking event: its verdict can stop the tool.PostToolUse— after a tool runs; observe-only.SessionStart— when a session begins.UserPromptSubmit— when you submit a prompt.
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.
Event payloads and the matcher grammar live in Hooks reference.