# Hooks

> Run your own commands, HTTP calls, prompts or agents at fixed points of a KazoCode agent session, to block tool calls, add context, format code or send notifications.

Hooks run your own logic at fixed points in a session, every time, without relying on the model to remember. Use them to block risky commands, format files after each edit, add context to every prompt, or notify you when a task finishes.

## Where hooks live

| File | Scope |
| --- | --- |
| `~/.kazocode/hooks.json` | You, in every project |
| `.kazo/hooks.json` | This project. KazoCode asks you to trust a project's hooks before running them |
| A plugin's `hooks/hooks.json` | Wherever the plugin is on |

`/hooks` lists every hook that runs in the current workspace.

## Example

Block force pushes, and format TypeScript after every edit:

```json title=".kazo/hooks.json"
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [{ "type": "command", "command": "node .kazo/check-push.js" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "edit_file|write_file",
        "hooks": [{ "type": "command", "command": "pnpm prettier --write ." }]
      }
    ]
  }
}
```

This is the same layout Claude Code uses, and Claude Code tool names in a `matcher` also match KazoCode's tools.

## Events

| Event | Runs |
| --- | --- |
| `SessionStart` | When a conversation starts |
| `UserPromptSubmit` | When you send a message, before the agent sees it |
| `PreToolUse` | Before a tool runs; can block it or change its input |
| `PermissionRequest` | When the agent asks for approval; can allow or deny |
| `PostToolUse` | After a tool succeeds |
| `PostToolUseFailure` | After a tool fails |
| `Notification` | When KazoCode would notify you |
| `SubagentStart`, `SubagentStop` | When a sub-agent starts or finishes |
| `Stop` | When the agent finishes its reply |
| `TaskCompleted`, `TeammateIdle` | When a task in a team finishes or a teammate is idle |
| `PreCompact` | Before a conversation is summarized |
| `WorktreeCreate`, `WorktreeRemove` | When an agent worktree is made or removed |
| `ConfigChange` | When settings, rules or servers change |

`matcher` is a tool name, a `|`-separated list, or a regular expression. Leave it out to match everything.

## Hook types

| `type` | Runs |
| --- | --- |
| `command` | A shell command. The event arrives as JSON on standard input |
| `http` | A POST of the event to a `url`, with optional `headers` |
| `prompt` | A prompt for a model, which judges the event |
| `agent` | A sub-agent that checks the event with tools |

## What a hook can do

A command hook answers with its exit code and output:

- **Exit 0**: carry on. For `UserPromptSubmit` and `SessionStart`, plain output is added as context for the agent.
- **Exit 2**: block. The action is stopped and the hook's error output tells the agent why; for `PreToolUse` the tool call is denied.
- **Other exit codes**: the hook failed. The session carries on and the failure is noted.

For finer control, print JSON: `{"continue": false, "stopReason": "…"}` stops the turn, and `systemMessage` adds a message for the agent.
