---
title: Hooks and venom's events
description: 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.
section: plugins
order: 40
audience: [user, operator, builder]
sources: [docs/hooks.md, packages/harness/src/notify/config-hooks.ts, packages/harness/src/notify/events.ts, packages/harness/src/compat/hooks.ts]
features: [plugins.hooks]
---

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

```yaml
# ~/.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:

```yaml
hooks:
  - event: MainAgentDone
    command: >
      jq -r '"\(.reason): \(.summary)"' |
      xargs -0 -I{} osascript -e 'display notification "{}" with title "venom"'
```

## The `hooks:` section {#config}

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](/docs/plugins/sounds.md)) |
| `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 {#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:

```json
{ "hooks": { "MainAgentDone": [{ "hooks": [{ "type": "command", "command": "say done" }] }] } }
```

## Claude Code hooks {#claude-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:

```ts
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.

## Related

- [Sounds](/docs/plugins/sounds.md)
- [Claude Code plugins](/docs/plugins/claude-code-plugins.md)
