Hooks 参考

Hooks 让你在 Qoder CLI 生命周期的特定时机自动执行自定义逻辑——例如在工具调用前校验、在会话开始时注入上下文、在文件变更时触发外部流程。本页是 Hooks 的完整参考。使用指南见钩子。

事件类型

Hooks 可绑定到以下事件：

事件	触发时机
`PreToolUse`	工具调用前。
`PostToolUse`	工具调用成功后。
`PostToolUseFailure`	工具调用失败后。
`UserPromptSubmit`	用户提交提示时。
`SessionStart`	会话开始。
`SessionEnd`	会话结束。
`Stop`	主 Agent 停止响应时。
`StopFailure`	停止流程失败时。
`SubagentStart`	子 Agent 启动。
`SubagentStop`	子 Agent 停止。
`PreCompact`	上下文压缩前。
`PostCompact`	上下文压缩后。
`Notification`	产生通知时。
`ConfigChange`	配置变更时。
`InstructionsLoaded`	加载项目说明后。
`CwdChanged`	工作目录变更时。
`FileChanged`	文件变更时。
`WorktreeCreate`	创建 Worktree 时。
`WorktreeRemove`	移除 Worktree 时。
`Elicitation`	发起信息征询时。
`ElicitationResult`	征询结果返回时。
`TaskCreated`	创建任务时。
`TaskCompleted`	任务完成时。
`PermissionRequest`	发起权限请求时。
`PermissionDenied`	权限被拒绝时。
`TeammateIdle`	协作者空闲时。
`Setup`	初始化安装时。

每个事件的 matcher 匹配字段、stdin 的额外输入字段、是否支持阻塞，以及可用的 hookSpecificOutput 字段，见钩子的「事件清单」小节。

Hook 类型

每个 Hook 通过 type 指定执行方式：

类型	说明
`command`	执行一条 Shell 命令。
`http`	发送 HTTP 请求。
`prompt`	独立的单轮模型调用做判定，模型返回 `{ ok, reason }`，`ok=false` 阻塞。
`agent`	启动子 Agent 校验，经 `StructuredOutput` 返回 `{ ok, reason }`，`ok=false` 阻塞。

各类型的完整字段（如 http 的 url/headers、prompt 与 agent 的返回约定）见钩子的「Hook 条目类型」小节。

定义结构

Hooks 在 settings.json 的 hooks 分组中按事件配置。每个事件对应一组 Hook 定义：

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

Hook 定义（分组）字段：

字段	说明
`matcher`	匹配规则（见下文），决定该组 Hook 对哪些目标生效。
`hooks`	Hook 数组，每项含 `type` 及对应参数。

单个 Hook 条目除 type 及类型专属参数外，还支持 name、timeout、if、async（后台执行，不阻塞主流程）等字段，完整清单见钩子的「Hook 条目类型」小节。

匹配规则

matcher 决定 Hook 对哪些目标（如工具名）生效：

空或 *：匹配全部。
精确值：如 Bash，仅匹配该目标。
管道符 |：多值，如 Bash|Edit|Write。
正则：支持正则表达式匹配。

更细粒度的 if 条件可写作 "ToolName" 或 "ToolName(arg_glob)"，其中 arg_glob 用 glob 模式匹配工具参数。

输入与退出码

输入（stdin）

Hook 通过 stdin 接收一段 JSON，包含当前上下文（以下为各事件通用字段，事件专属字段另见「事件清单」）：

字段	说明
`session_id`	当前会话 ID。
`transcript_path`	会话记录文件路径。
`cwd`	当前工作目录。
`hook_event_name`	触发的事件名。
`permission_mode`	当前权限模式。
`agent_id`	触发的 Agent ID（如适用）。
`agent_type`	Agent 类型（如适用）。

退出码

command 类型 Hook 通过退出码控制流程：

退出码	含义
`0`	成功。stdout 可输出 JSON 供 CLI 解析。
`2`	阻塞。stderr 内容作为反馈返回给 Agent（仅对支持阻塞的事件生效，逐事件说明见「事件清单」）。
其他	非阻塞错误，记录但不中断流程。

退出码为 0 时可通过 stdout 返回 JSON 做更精细的控制，完整字段（continue、stopReason、suppressOutput、systemMessage、decision、reason、hookSpecificOutput）见钩子的「Hook 脚本编写」小节。

插件中的 Hooks

插件可携带 Hooks，配置于插件目录下的 hooks/hooks.json，格式与 settings.json 的 hooks 分组一致。见插件参考。

下一步

Hooks 使用指南：钩子。
扩展问题排查：Hooks、MCP 和插件问题。

​事件类型

​Hook 类型

​定义结构

​匹配规则

​输入与退出码

​输入（stdin）

​退出码

​插件中的 Hooks

​下一步