钩子参考

钩子参考

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

通信协议

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

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

退出代码行为

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

---

输入架构 (stdin)

每个钩子接收一个基础的 JSON 对象。根据特定事件，会添加额外的字段。

基础字段（所有事件）

字段	类型	描述
会话唯一标识符	占位符	当前 CLI 会话的唯一标识符。
会话 JSON 转录路径	占位符	会话的 JSON 转录路径（如果可用）。
当前工作目录	占位符	当前的工作目录。
触发事件名称	占位符	触发事件的名称（例如，占位符）。
事件 ISO 8601 时间戳	占位符	事件的时间戳（ISO 8601格式）。

事件特定字段

工具事件（占位符, 占位符）

• 工具内部名称: （占位符）工具的内部名称（例如，占位符, 占位符）。
• 传递给工具的参数: （占位符）传递给工具的参数。
• 工具执行原始输出: （占位符，仅限 AfterTool）工具执行的原始输出。
• MCP 工具调用信息: （占位符，可选）仅针对 MCP 工具调用。包含服务器身份信息：
  • 配置的服务器名称: （占位符）MCP 服务器的配置名称。
  • 服务器原始工具名称: （占位符）来自 MCP 服务器的原始工具名称。
  • 启动服务器的命令: （占位符，可选）对于 stdio 传输，启动服务器的命令。
  • 命令参数: （占位符，可选）对于 stdio 传输，命令参数。
  • 工作目录: （占位符，可选）对于 stdio 传输，工作目录。
  • 服务器 URL: （占位符，可选）对于 SSE/HTTP 传输，服务器 URL。
  • TCP 地址: （占位符，可选）对于 WebSocket 传输，TCP 地址。

代理事件（占位符, 占位符）

【翻译文本】

• 用户提交的提示：(prompt) 用户提交的提示内容。
• 模型最终响应文本：(prompt_response, 仅AfterAgent) 模型的最终响应文本。
• 是否已有停止钩子在处理延续：(stop_hook_active, **仅AfterAgent **) 表示是否有停止钩子在处理延续。

模型事件 (BeforeModel, AfterModel, BeforeToolSelection)

• 出站请求的稳定表示：(llm_request) 出站请求的稳定表示。请参阅稳定模型API。
• 进站响应的稳定表示：(llm_response, **仅AfterModel **) 进站响应的稳定表示。

会话与通知事件

• 触发源：(source, **仅SessionStart **) 触发源。
• 会话结束原因：(reason, **仅SessionEnd **) 会话结束的原因。
• 触发压缩事件的原因：(trigger, **仅PreCompress **) 触发压缩事件的原因。
• 触发的通知类型：(notification_type, **仅Notification **) 触发的通知类型。
• 通知消息：(message, **仅Notification **) 通知消息。
• 通知的有效负载详情：(details, **仅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
  }
}