Hooks and venom's events
Run a command or play a sound when the agent finishes, fails, needs approval or completes a step, and use Claude Code's hooks as they are.
venom has two kinds of hook:
- Claude Code's hooks (
PreToolUse,PostToolUse,PostToolUseFailure,UserPromptSubmit,Stop,SubagentStart,SubagentStop,SessionStart,SessionEnd,PreCompact,Notification,StopFailure) from your Claude settings files. They work as in Claude Code: they can block a tool call, keep the agent working or add context. - venom's events (
MainAgentDone,SubagentDone,StepDone,PermissionNeeded,AgentFailed,ScheduleDone). These are notifications: they fire after something happened, cannot block or steer the agent, and say what kind of agent it was and how it ended. Use them for a sound, a desktop notification, a chat message or a log line.
The repository's reference for both is docs/hooks.md.
Quick start
# ~/.venom/config.yaml
hooks:
- event: MainAgentDone
command: 'jq -r .summary | xargs -0 notify-send venom' # Linux; payload JSON on stdin
- event: AgentFailed
command: 'jq -r .error >> ~/.venom/failures.log'
- event: SubagentDone
matcher: "reviewer|security-reviewer"
sound: bellmacOS notification with the start of the answer:
hooks:
- event: MainAgentDone
command: >
jq -r '"\(.reason): \(.summary)"' |
xargs -0 -I{} osascript -e 'display notification "{}" with title "venom"'The hooks: section
In ~/.venom/config.yaml or a project's venom.yaml / .venom/config.yaml. Lists from every file run, home first: a project's list adds to yours.
| Key | Type | Default | What |
|---|---|---|---|
hooks |
list | [] |
the hook entries |
hooks[].event |
string | required | one of venom's six events; Claude events belong in .claude/settings.json |
hooks[].command |
string | none | a shell command run with /bin/sh -c in the workspace; the payload JSON is on stdin |
hooks[].sound |
string | none | a built-in sound name or an absolute path to an audio file (Sounds) |
hooks[].matcher |
string | all | an anchored regex. For SubagentDone, MainAgentDone, AgentFailed: the agent name or role. For StepDone and PermissionNeeded: the tool name. For ScheduleDone: the job name. Empty or * matches all |
hooks[].timeout |
number (seconds) | 30 (max 600) |
the command is killed after this |
hooks[].async |
boolean | true |
false makes venom wait for the command (up to timeout) before the next listener; the agent never waits |
An entry needs a command, a sound or both. The command gets VENOM_HOOK_EVENT, VENOM_PROJECT_DIR and CLAUDE_PROJECT_DIR in its environment; venom's own credentials are never passed on. Output is ignored.
Trust. Commands from ~/.venom/config.yaml always run. Commands from a project file run only while the project is trusted; each one is a trust item, so a new or changed command asks again. An untrusted project's command is skipped with one notice. sound: entries need no trust.
venom's events
Every payload has hook_event_name, session_id, cwd, timestamp (ISO) and agent: { id, name, role, depth, parent_id?, description? }. The main agent is name: "main", role: "main", depth: 0.
| Event | Fires when | Event-specific fields |
|---|---|---|
MainAgentDone |
the top-level run settled and venom is waiting for you | reason (completed, error, aborted), waiting_for_input: true, duration_ms, tokens (input, output, cached), cost_usd (subagents included, at list price), requests, tool_calls, subagents, summary (the answer, up to 300 characters), error? |
SubagentDone |
a child agent exited | reason, status (done, turn-limit, terminated, killed, crashed, budget, orphaned, truncated), ok, partial, duration_ms, tokens, cost_usd, turns, tool_calls, summary, error? |
StepDone |
a main-agent tool call finished (rate-limited) | tool, tool_call_id, ok, duration_ms, steps, failed |
PermissionNeeded |
venom is waiting on an approval, a subagent's included | reason: "waiting-for-input", tool, summary, why, permission_mode |
AgentFailed |
the main run ended in a model or provider error, or a child crashed or ran out of budget | reason: "error", status (error, crashed, budget), error, duration_ms, summary |
ScheduleDone |
a scheduled job's run ended in venom serve or venom schedule run |
reason, schedule, run_id, trigger (cron, catch-up, manual), workspace?, duration_ms, cost_usd, budget_exceeded, summary, error? |
Order in a run: StepDone events (and SubagentDone as each child exits), then AgentFailed if the run failed, then MainAgentDone. Claude's Stop hook runs before all of these.
StepDone is rate-limited: the first step after 2 quiet seconds fires at once; steps in the next 2 seconds fold into one event at the end of the window, with steps and failed counting them. Pending steps fire before MainAgentDone.
Not fired: MainAgentDone for a subagent, and PermissionNeeded when nobody would be asked. aborted means you pressed Esc.
Compared with Claude Code's events
| venom | Closest Claude Code event | Difference |
|---|---|---|
MainAgentDone |
Stop |
fires once after the run settled, also on errors and aborts; cannot block; carries outcome, duration, tokens and cost |
SubagentDone |
SubagentStop |
every child, with its exit status and role; cannot block |
StepDone |
PostToolUse |
rate-limited; cannot change the result |
PermissionNeeded |
Notification (permission_prompt) |
both fire; venom's names the tool, the call and why |
AgentFailed |
StopFailure |
also fires for a crashed subagent |
A Claude settings file may name a venom event with Claude's hook shape. It runs fire-and-forget; exit codes and output are ignored:
{ "hooks": { "MainAgentDone": [{ "hooks": [{ "type": "command", "command": "say done" }] }] } }Claude Code hooks
Hooks in .claude/settings.json, .claude/settings.local.json, ~/.claude/settings.json and plugins' hooks.json run as in Claude Code: JSON on stdin, CLAUDE_PROJECT_DIR, regex matchers on Claude tool names, exit code 2 blocks where Claude blocks. type: "prompt" hooks run one completion on venom-fast. type: "agent", "http" and "mcp_tool" hooks, and events venom does not fire, are ignored with a diagnostic.
PostToolUseFailure runs after PostToolUse for a failed tool call (is_error: true, error). SubagentStart runs once per task child before its first turn (agent_id, agent_type, description). StopFailure fires when the main run ends in an error, with Claude's error values (rate_limit, overloaded, authentication_failed, billing_error, model_not_found, max_output_tokens, invalid_request, server_error, unknown).
The JSON a command hook prints is checked per event. All events take continue, stopReason, suppressOutput, systemMessage, decision, reason and hookSpecificOutput (with hookEventName); an unknown key or wrong type shows a diagnostic to you (never the model), and valid fields are still applied.
| Event | hookSpecificOutput keys |
|---|---|
PreToolUse |
permissionDecision (allow, deny, ask, defer), permissionDecisionReason, updatedInput, additionalContext |
PostToolUse |
additionalContext, updatedToolOutput, updatedMCPToolOutput |
UserPromptSubmit |
additionalContext, sessionTitle |
PostToolUseFailure, SessionStart, SubagentStart, Stop, SubagentStop |
additionalContext |
SessionEnd, Notification, PreCompact, StopFailure and venom's events |
none |
A hook's allow skips the approval prompt but never overrides a deny rule.
For apps on the harness
The events are a harness API:
const off = harness.onHook("MainAgentDone", (e) => console.log(e.reason, e.duration_ms, e.summary));
harness.onHook("*", (e) => log(e.hook_event_name, e)); // every venom event
harness.setConfigHooks(notify.loadConfigHooks({ cwd, venomHome }).hooks); // the hooks: sectionPayload types are VenomHookPayload and PayloadOf<"MainAgentDone">. A listener that throws is reported as a diagnostic and never reaches the agent.
Limitations
venom serveandvenom acpfire events toonHooklisteners and Claude-settings hooks but do not load thehooks:section or play sounds.- In
venom -p, whose approver denies without asking,PermissionNeededfires before the denial.