> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks reference

> Hook event types, matching rules, execution methods, input and output, and exit codes

Hooks allow you to automatically execute custom logic at specific points in the Qoder CLI lifecycle—for example, validating before a tool call, injecting context at the start of a session, or triggering external processes on file changes. This page is the complete reference for Hooks. For a usage guide, see [Hook](/cli/hooks-reference).

## Event Types

Hooks can be bound to the following events:

| Event                | Trigger                                 |
| -------------------- | --------------------------------------- |
| `PreToolUse`         | Before a tool call.                     |
| `PostToolUse`        | After a successful tool call.           |
| `PostToolUseFailure` | After a failed tool call.               |
| `UserPromptSubmit`   | When the user submits a prompt.         |
| `SessionStart`       | When a session starts.                  |
| `SessionEnd`         | When a session ends.                    |
| `Stop`               | When the main agent stops responding.   |
| `StopFailure`        | When the stop process fails.            |
| `SubagentStart`      | When a subagent starts.                 |
| `SubagentStop`       | When a subagent stops.                  |
| `PreCompact`         | Before context compression.             |
| `PostCompact`        | After context compression.              |
| `Notification`       | When a notification is generated.       |
| `ConfigChange`       | When configuration changes.             |
| `InstructionsLoaded` | After loading project instructions.     |
| `CwdChanged`         | When the working directory changes.     |
| `FileChanged`        | When a file changes.                    |
| `WorktreeCreate`     | When a worktree is created.             |
| `WorktreeRemove`     | When a worktree is removed.             |
| `Elicitation`        | When an elicitation is initiated.       |
| `ElicitationResult`  | When elicitation results are returned.  |
| `TaskCreated`        | When a task is created.                 |
| `TaskCompleted`      | When a task is completed.               |
| `PermissionRequest`  | When a permission request is initiated. |
| `PermissionDenied`   | When permission is denied.              |
| `TeammateIdle`       | When a collaborator is idle.            |
| `Setup`              | During initial installation.            |

For each event's matcher fields, additional stdin input fields, blocking support, and available `hookSpecificOutput` fields, see the "Event Catalog" section in [Hook](/cli/hooks-reference).

## Hook Types

Each Hook specifies its execution method via `type`:

| Type      | Description                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------- |
| `command` | Executes a shell command.                                                                                                   |
| `http`    | Sends an HTTP request.                                                                                                      |
| `prompt`  | Makes an independent single-turn model call for decision-making; the model returns `{ ok, reason }`, and `ok=false` blocks. |
| `agent`   | Starts a subagent for validation, returning `{ ok, reason }` via `StructuredOutput`, and `ok=false` blocks.                 |

For the complete fields of each type (such as `url`/`headers` for `http`, and the return conventions for `prompt` and `agent`), see the "Hook Entry Types" section in [Hook](/cli/hooks-reference).

## Definition Structure

Hooks are configured by event within the `hooks` group in `settings.json`. Each event corresponds to a set of Hook definitions:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./scripts/check.sh" }
        ]
      }
    ]
  }
}
```

Hook definition (group) fields:

| Field     | Description                                                                           |
| --------- | ------------------------------------------------------------------------------------- |
| `matcher` | Matching rules (see below), determining which targets this group of Hooks applies to. |
| `hooks`   | An array of Hooks, each containing `type` and corresponding parameters.               |

In addition to `type` and type-specific parameters, a single Hook entry also supports fields such as `name`, `timeout`, `if`, and `async` (executes in the background without blocking the main process). For the complete list, see the "Hook Entry Types" section in [Hook](/cli/hooks-reference).

## Matching Rules

`matcher` determines which targets (such as tool names) the Hook applies to:

- **Empty or `*`**: Matches all.
- **Exact value**: Such as `Bash`, matches only that target.
- **Pipe `|`**: Multiple values, such as `Bash|Edit|Write`.
- **Regex**: Supports regular expression matching.

More granular `if` conditions can be written as `"ToolName"` or `"ToolName(arg_glob)"`, where `arg_glob` uses glob patterns to match tool parameters.

## Input and Exit Codes

### Input (stdin)

A Hook receives a JSON object via stdin containing the current context (the following are common fields for all events; for event-specific fields, see the "Event Catalog"):

| Field             | Description                                    |
| ----------------- | ---------------------------------------------- |
| `session_id`      | The current session ID.                        |
| `transcript_path` | The path to the session log file.              |
| `cwd`             | The current working directory.                 |
| `hook_event_name` | The name of the triggered event.               |
| `permission_mode` | The current permission mode.                   |
| `agent_id`        | The ID of the triggered Agent (if applicable). |
| `agent_type`      | The Agent type (if applicable).                |

### Exit Codes

`command` type Hooks control the flow via exit codes:

| Exit Code | Meaning                                                                                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`       | Success. stdout can output JSON for the CLI to parse.                                                                                                             |
| `2`       | Block. stderr content is returned as feedback to the Agent (only effective for events that support blocking; see the "Event Catalog" for event-by-event details). |
| Other     | Non-blocking error; logged but does not interrupt the flow.                                                                                                       |

When the exit code is `0`, JSON can be returned via stdout for more granular control. For the complete fields (`continue`, `stopReason`, `suppressOutput`, `systemMessage`, `decision`, `reason`, `hookSpecificOutput`), see the "Writing Hook Scripts" section in [Hook](/cli/hooks-reference).

## Hooks in Plugins

Plugins can include Hooks, configured in `hooks/hooks.json` under the plugin directory, following the same format as the `hooks` group in `settings.json`. See [Plugin Reference](/cli/plugins-reference).

## Next Steps

- Hooks usage guide: [Hook](/cli/hooks-reference).
- Extension troubleshooting: [Hooks, MCP, and plugin issues](/cli/troubleshoot-extensions).
