Hooks reference

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.

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.

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.

Definition Structure

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

{
  "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.

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.

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.

Next Steps

Hooks usage guide: Hook.
Extension troubleshooting: Hooks, MCP, and plugin issues.

​Event Types

​Hook Types

​Definition Structure

​Matching Rules

​Input and Exit Codes

​Input (stdin)

​Exit Codes

​Hooks in Plugins

​Next Steps