Hooks Reference - Qoder CN

Hooks let you automatically run custom logic at specific moments in the Qoder CLI CN lifecycle — for example validating before tool calls, injecting context at session start, or triggering external processes on file changes. This page is the complete Hooks reference.

Event types

Hooks can bind to the following events:

Event	When it fires
`PreToolUse`	Before a tool call.
`PostToolUse`	After a tool call succeeds.
`PostToolUseFailure`	After a tool call fails.
`UserPromptSubmit`	When the user submits a prompt.
`SessionStart`	Session start.
`SessionEnd`	Session end.
`Stop`	When the main Agent stops responding.
`StopFailure`	When the stop process fails.
`SubagentStart`	Subagent start.
`SubagentStop`	Subagent stop.
`PreCompact`	Before context compaction.
`PostCompact`	After context compaction.
`Notification`	When a notification is produced.
`ConfigChange`	When configuration changes.
`InstructionsLoaded`	After project instructions load.
`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 information elicitation is initiated.
`ElicitationResult`	When an elicitation result returns.
`TaskCreated`	When a task is created.
`TaskCompleted`	When a task completes.
`PermissionRequest`	When a permission request is raised.
`PermissionDenied`	When a permission is denied.
`TeammateIdle`	When a collaborator goes idle.
`Setup`	At initial installation.

Each event's matcher field, additional stdin input fields, blocking support, and available hookSpecificOutput fields vary by event.

Hook types

Each Hook specifies its execution type via type:

Type	Description
`command`	Run a shell command.
`http`	Send an HTTP request.
`prompt`	An independent single-turn model call for judgment; the model returns `{ ok, reason }`, and `ok=false` blocks.
`agent`	Launch a subagent for validation, returning `{ ok, reason }` via `StructuredOutput`; `ok=false` blocks.

The complete fields of each type (such as http's url/headers, and the return contracts of prompt and agent) vary by type; for configuration, see "Definition structure" below.

Definition structure

Hooks are configured per event in the hooks group of settings.json. Each event maps to a set of Hook definitions:

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

Hook definition (group) fields:

Field	Description
`matcher`	The matching rule (see below), deciding which targets this Hook group applies to.
`hooks`	An array of Hooks, each with a `type` and the corresponding parameters.

Besides type and type-specific parameters, a single Hook entry also supports fields such as name, timeout, if, and async (background execution without blocking the main flow).

Matching rules

matcher decides which targets (such as tool names) a Hook applies to:

Empty or *: matches everything.
Exact value: such as Bash, matching only that target.
Pipe |: multiple values, such as Bash|Edit|Write.
Regex: regular expression matching is supported.

Finer-grained if conditions can be written as "ToolName" or "ToolName(arg_glob)", where arg_glob matches tool arguments with a glob pattern.

Input and exit codes

Input (stdin)

A Hook receives a JSON payload via stdin containing the current context (the fields below are common to all events; each event also has its own fields):

Field	Description
`session_id`	The current session ID.
`transcript_path`	The session transcript file path.
`cwd`	The current working directory.
`hook_event_name`	The triggered event name.
`permission_mode`	The current permission mode.
`agent_id`	The triggering Agent ID (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 may output JSON for the CLI to parse.
`2`	Block. stderr content is returned to the Agent as feedback (only for events that support blocking).
Other	A non-blocking error, recorded without interrupting the flow.

With exit code 0, the Hook can return JSON via stdout for finer control; available fields include continue, stopReason, suppressOutput, systemMessage, decision, reason, and hookSpecificOutput.

Hooks in plugins

Plugins can carry Hooks, configured in hooks/hooks.json under the plugin directory, with the same format as the hooks group in settings.json. See Plugins Reference.

Next steps

Hooks configuration entry points and scopes: Configuration Scopes.
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