钩子参考

本文档提供 Gemini CLI 钩子的技术规范，包括输入和输出的 JSON 模式、退出码行为和稳定的模型 API。

通信协议

钩子通过标准流和退出码与 Gemini CLI 通信：

• 输入：Gemini CLI 向钩子的 stdin 发送 JSON 对象。
• 输出：钩子向 stdout 发送 JSON 对象（或纯文本）。
• 退出码：用于表示成功或阻塞错误。

退出码行为

退出码	含义	行为
0	成功	stdout 被解析为 JSON。如果解析失败，则被视为 systemMessage。
2	阻塞错误	中断当前操作。stderr 显示给代理（对于工具事件）或用户。
其他	警告	继续执行。stderr 作为非阻塞警告记录。

---

输入模式（stdin）

每个钩子都会收到一个基本 JSON 对象。根据特定事件添加额外字段。

基本字段（所有事件）

字段	类型	描述
session_id	string	当前 CLI 会话的唯一标识符。
transcript_path	string	会话 JSON 转录的路径（如果可用）。
cwd	string	当前工作目录。
hook_event_name	string	触发事件的名称（如 BeforeTool）。
timestamp	string	事件的 ISO 8601 时间戳。

事件特定字段

工具事件（BeforeTool、AfterTool）

• tool_name：（string）工具的内部名称（如 write_file、run_shell_command）。
• tool_input：（object）传递给工具的参数。
• tool_response：（object，仅 AfterTool）工具执行的原始输出。

代理事件（BeforeAgent、AfterAgent）

• prompt：（string）用户提交的提示。
• prompt_response：（string，仅 AfterAgent）模型的最终响应文本。
• stop_hook_active：（boolean，仅 AfterAgent）指示停止钩子是否已在处理继续。

模型事件（BeforeModel、AfterModel、BeforeToolSelection）

• llm_request：（LLMRequest）传出请求的稳定表示。参见稳定模型 API。
• llm_response：（LLMResponse，仅 AfterModel）传入响应的稳定表示。

会话和通知事件

• source：（startup | resume | clear，仅 SessionStart）触发源。
• reason：（exit | clear | logout | prompt_input_exit | other，仅 SessionEnd）会话结束的原因。
• trigger：（manual | auto，仅 PreCompress）触发压缩事件的原因。
• notification_type：（ToolPermission，仅 Notification）正在触发的通知类型。
• message：（string，仅 Notification）通知消息。
• details：（object，仅 Notification）通知的特定负载详情。

---

输出模式（stdout）

如果钩子以 0 退出，CLI 会尝试将 stdout 解析为 JSON。

通用输出字段

字段	类型	描述
decision	string	以下之一：allow、deny、block、ask、approve。
reason	string	当决策为 deny 或 block 时显示给代理的解释。
systemMessage	string	在 CLI 终端中显示给用户的消息。
continue	boolean	如果为 false，立即终止此轮的代理循环。
stopReason	string	当 continue 为 false 时显示给用户的消息。
suppressOutput	boolean	如果为 true，钩子执行将从 CLI 转录中隐藏。
hookSpecificOutput	object	事件特定数据的容器（见下文）。

hookSpecificOutput 参考

字段	支持的事件	描述
additionalContext	SessionStart、BeforeAgent、AfterTool	直接附加文本到代理的上下文。
llm_request	BeforeModel	Partial<LLMRequest> 用于覆盖传出调用的参数。
llm_response	BeforeModel	完整的 LLMResponse 用于绕过模型并提供合成结果。
llm_response	AfterModel	Partial<LLMResponse> 用于在代理看到之前修改模型的响应。
toolConfig	BeforeToolSelection	包含 mode（AUTO/ANY/NONE）和 allowedFunctionNames 的对象。

---

稳定模型 API

Gemini CLI 使用解耦格式进行模型交互，以确保即使底层 Gemini SDK 更改，钩子也保持稳定。

LLMRequest 对象

用于 BeforeModel 和 BeforeToolSelection。

💡 注意：在 v1 中，模型钩子主要关注文本。content 数组中提供的非文本部分（如图像或函数调用）将被翻译器简化为其字符串表示。

{
  "model": string,
  "messages": Array<{
    "role": "user" | "model" | "system",
    "content": string | Array<{ "type": string, [key: string]: any }>
  }>,
  "config"?: {
    "temperature"?: number,
    "maxOutputTokens"?: number,
    "topP"?: number,
    "topK"?: number
  },
  "toolConfig"?: {
    "mode"?: "AUTO" | "ANY" | "NONE",
    "allowedFunctionNames"?: string[]
  }
}

LLMResponse 对象

用于 AfterModel 和作为 BeforeModel 中的合成响应。

{
  "text"?: string,
  "candidates": Array<{
    "content": {
      "role": "model",
      "parts": string[]
    },
    "finishReason"?: "STOP" | "MAX_TOKENS" | "SAFETY" | "RECITATION" | "OTHER",
    "index"?: number,
    "safetyRatings"?: Array<{
      "category": string,
      "probability": string,
      "blocked"?: boolean
    }>
  }>,
  "usageMetadata"?: {
    "promptTokenCount"?: number,
    "candidatesTokenCount"?: number,
    "totalTokenCount"?: number
  }
}