Skip to content
Docs menu

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.

View .md

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: bell

macOS 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: section

Payload types are VenomHookPayload and PayloadOf<"MainAgentDone">. A listener that throws is reported as a diagnostic and never reaches the agent.

Limitations

  • venom serve and venom acp fire events to onHook listeners and Claude-settings hooks but do not load the hooks: section or play sounds.
  • In venom -p, whose approver denies without asking, PermissionNeeded fires before the denial.