钩子系统 (Hooks)

钩子（Hooks）允许您在 Antigravity 执行循环的特定节点运行自定义脚本或 Shell 命令。这在强制执行自定义规范、运行 Linter（代码检查工具）或自动捕获诊断信息时非常强大。

配置方式 (Configuration)

钩子在您自定义目录中的 hooks.json 文件中进行配置（例如工作空间中的 .agents/ 或 ~/.gemini/config/）。

模式与文件格式 (Schema and File Format)

hooks.json 文件将钩子名称映射到其事件配置。

json

{
  "my-linter-hook": {
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint.sh",
            "timeout": 10
          }
        ]
      }
    ]
  },
  "safety-gate": {
    "enabled": false,
    "PreToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "command": "./scripts/safety-check.sh"
          }
        ]
      }
    ]
  },
  "reminder": {
    "PreInvocation": [
      {
        "type": "command",
        "command": "./scripts/reminder.sh"
      }
    ]
  }
}

钩子定义字段 (Hook Definition Fields)

字段	类型	描述
enabled	boolean	可选。设为 `false` 以禁用此钩子而不将其删除。默认为 `true`。
PreToolUse	array	在工具执行前运行的处理程序。
PostToolUse	array	在工具执行完毕后运行的处理程序。
PreInvocation	array	在 Antigravity 调用大模型前运行的处理程序。
PostInvocation	array	在工具调用流程结束后运行的处理程序。
Stop	array	在执行循环终止时运行的处理程序。

支持的事件 (Supported Events)

事件 (Event)	描述	匹配器目标 (Matcher Target)
PreToolUse	在工具执行前触发。	工具名称（如 `run_command`）
PostToolUse	在工具完成后触发。	工具名称
PreInvocation	在调用大模型前触发。	无（忽略匹配器）
PostInvocation	在工具调用流程结束后触发。	无（忽略匹配器）
Stop	在执行终止时触发。	无（忽略匹配器）

匹配器 (Matcher)

对于 PreToolUse 和 PostToolUse，您可以在 matcher 字段中使用正则表达式来指定触发钩子的工具：

"" 或 "*"：匹配所有工具。
"run_command"：精确匹配 run_command。
"run_command|view_file"：匹配这两个工具之一。
"browser_.*"：匹配任何以 browser_ 开头的工具。

[!NOTE] 对于 PreInvocation、PostInvocation 和 Stop，其结构更简单（直接在事件键下的处理程序列表），且匹配器会被忽略。

支持的工具 (Supported Tools)

对于 PreToolUse 和 PostToolUse 匹配器，您可以针对以下按类别分组的工具名称进行匹配：

文件与目录操作

view_file：查看文件内容。
write_to_file：创建新文件。
replace_file_content：编辑文件中单个连续的文本块。
multi_replace_file_content：对同一文件进行多次非连续的编辑。
list_dir：列出目录内容。
find_by_name：使用 Glob 模式搜索文件和目录。

搜索与研究

grep_search：在特定路径中进行快速文本搜索。
search_web：执行常规网页搜索。
read_url_content：获取公开 URL 的文本内容。

系统与执行

run_command：提议运行 Bash 命令。
manage_task：与后台任务交互。
schedule：设置定时器或循环 Cron 任务。
list_permissions：查看当前资源访问授权。
ask_permission：请求额外的细粒度作用域权限。

Agent 协同

invoke_subagent：派生出专门的子 Agent。
define_subagent：创建自定义子 Agent。
send_message：与其他 Agent 进行通信。
manage_subagents：列出或终止活动的子 Agent。

交互与媒体

ask_question：提出多项选择题。
generate_image：创建或编辑图像。

钩子处理程序配置 (Hook Handler Configuration)

hooks 数组中的每个项目支持以下字段：

字段	类型	描述
type	string	可选。目前仅支持 `"command"`。默认为 `"command"`。
command	string	必填。要执行的 Shell 命令。
timeout	integer	可选。超时时间（以秒为单位）。默认为 `30`。

输入/输出协定 (Input/Output Contract)

钩子通过 stdin 接收 JSON 输入，并应通过 stdout 返回 JSON 输出。字段名使用驼峰命名法（camelCase）。

通用输入字段 (Common Input Fields)

所有钩子在通过 stdin 传入的输入 Payload 中都会收到以下系统元数据字段：

字段	类型	描述
conversationId	string	当前活动 Agent 对话的唯一 UUID。
workspacePaths	array of strings	代表用户挂载的工作空间的绝对目录路径。
transcriptPath	string	对话日志文件 `transcript.jsonl` 的绝对路径。
artifactDirectoryPath	string	包含所有对话 Artifacts 产物和屏幕截图的目录绝对路径。

PreToolUse

在工具执行前触发。

模式 (Schema)

输入字段 (stdin)：

字段	类型	描述
toolCall	object	提议执行的工具调用的详细信息。
toolCall.name	string	正在执行的工具名称（例如 `run_command`）。
toolCall.args	object	传递给该工具的参数。
stepIdx	integer	当前步骤在轨迹中以 0 为起点的索引。
(通用字段)	-	包含 `conversationId`、`workspacePaths`、`transcriptPath`、`artifactDirectoryPath`。

输出字段 (stdout)：

字段	类型	描述
decision	string	必填。控制如何拦截或准入该工具调用： - `"allow"`：自动允许工具执行。 - `"deny"`：立即硬性拦截执行。 - `"ask"`：提示用户，但遵守“总是允许”的配置。 - `"force_ask"`：总是提示用户，忽略已缓存的权限。
reason	string	可选。向 Agent 或用户展示该决策的解释。
permissionOverrides	array of strings	可选。覆盖默认工具权限的资源字符串列表（如 `["read_file(/path)", "command(args)"]`）。

示例

输入 (stdin)：

json

{
  "toolCall": {
    "name": "run_command",
    "args": {
      "CommandLine": "npm test",
      "Cwd": "/workspace/project",
      "WaitMsBeforeAsync": 5000
    }
  },
  "stepIdx": 19,
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": [
    "/workspace/project"
  ],
  "transcriptPath": "/workspace/project/.gemini/jetski/transcript.jsonl",
  "artifactDirectoryPath": "/workspace/project/.gemini/jetski/artifacts"
}

输出 (stdout)：

json

{
  "decision": "ask",
  "reason": "Requires confirmation for test execution.",
  "permissionOverrides": [
    "command(npm test)"
  ]
}

PostToolUse

在工具完成运行后触发。

模式 (Schema)

输入字段 (stdin)：

字段	类型	描述
stepIdx	integer	已完成步骤的 0 起点索引。
error	string	可选。如果工具调用失败，则为详细的运行时错误消息；如果成功，则为空。
(通用字段)	-	包含 `conversationId`、`workspacePaths`、`transcriptPath`、`artifactDirectoryPath`。

输出字段 (stdout)：返回一个空的 JSON 对象 {}。

示例

输入 (stdin)：

json

{
  "stepIdx": 5,
  "error": "exit status 1",
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": [
    "/workspace/project"
  ],
  "transcriptPath": "/workspace/project/.gemini/jetski/transcript.jsonl",
  "artifactDirectoryPath": "/workspace/project/.gemini/jetski/artifacts"
}

输出 (stdout)：{}

PreInvocation

在调用大模型前触发。

模式 (Schema)

输入字段 (stdin)：

字段	类型	描述
invocationNum	integer	当前模型调用的序列号。
initialNumSteps	integer	目前在轨迹中的步数。
(通用字段)	-	包含 `conversationId`、`workspacePaths`、`transcriptPath`、`artifactDirectoryPath`。

输出字段 (stdout)：

字段	类型	描述
injectSteps	array of objects	可选。在大模型被调用之前，要注入到对话轨迹中的步骤列表。

注入的步骤模式 (Injected Step Schema)：injectSteps 数组中的每个对象可以包含以下字段之一：

toolCall (object)：要执行的工具调用。
userMessage (string)：来自用户的消息。
ephemeralMessage (string)：临时的系统消息。

示例

输入 (stdin)：

json

{
  "invocationNum": 3,
  "initialNumSteps": 10,
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": [
    "/workspace/project"
  ],
  "transcriptPath": "/workspace/project/.gemini/jetski/transcript.jsonl",
  "artifactDirectoryPath": "/workspace/project/.gemini/jetski/artifacts"
}

输出 (stdout)：

json

{
  "injectSteps": [
    {
      "ephemeralMessage": "Remember to lint"
    }
  ]
}

PostInvocation

在工具调用流程结束后触发。

模式 (Schema)

输入字段 (stdin)：与 PreInvocation 输入字段相同。

输出字段 (stdout)：

字段	类型	描述
injectSteps	array of objects	可选。在模型调用完成后注入的步骤列表（模式与 `PreInvocation` 注入步骤相同）。
terminationBehavior	string	可选。控制注入后的执行流程： - `"force_continue"`：强制循环继续。 - `"terminate"`：强制循环终止。 - `""`（或省略）：默认行为。

示例

输入 (stdin)：与 PreInvocation 相同。输出 (stdout)：

json

{
  "injectSteps": [],
  "terminationBehavior": ""
}

Stop

在执行循环终止时触发。

模式 (Schema)

输入字段 (stdin)：

字段	类型	描述
executionNum	integer	执行尝试的序列号。
terminationReason	string	执行停止的原因（例如 `"model_stop"`, `"max_steps_exceeded"`, `"error"`）。
error	string	可选。如果停止是由系统错误引起的，则为错误消息。
fullyIdle	boolean	必填。如果 Agent 完全运行结束，且所有后台命令或异步任务都已完成，则为 `true`。如果有活跃的后台任务仍在运行，则为 `false`。
(通用字段)	-	包含 `conversationId`、`workspacePaths`、`transcriptPath`、`artifactDirectoryPath`。

输出字段 (stdout)：

字段	类型	描述
decision	string	必填。设置为 `"continue"` 以阻止 Agent 停止，并重新进入执行循环。任何其他值都将允许停止。
reason	string	可选。如果 `decision` 是 `"continue"`，该消息将被作为系统消息注入到对话中。

示例

输入 (stdin)：

json

{
  "executionNum": 1,
  "terminationReason": "model_stop",
  "error": "",
  "fullyIdle": true,
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": [
    "/workspace/project"
  ],
  "transcriptPath": "/workspace/project/.gemini/jetski/transcript.jsonl",
  "artifactDirectoryPath": "/workspace/project/.gemini/jetski/artifacts"
}

输出 (stdout)：

json

{
  "decision": "continue",
  "reason": "Not done yet"
}

钩子系统 (Hooks) ​

配置方式 (Configuration) ​

模式与文件格式 (Schema and File Format) ​

钩子定义字段 (Hook Definition Fields) ​

支持的事件 (Supported Events) ​

匹配器 (Matcher) ​

支持的工具 (Supported Tools) ​

文件与目录操作 ​

搜索与研究 ​

系统与执行 ​

Agent 协同 ​

交互与媒体 ​

钩子处理程序配置 (Hook Handler Configuration) ​

输入/输出协定 (Input/Output Contract) ​

通用输入字段 (Common Input Fields) ​

PreToolUse ​

模式 (Schema) ​

示例 ​

PostToolUse ​

模式 (Schema) ​

示例 ​

PreInvocation ​

模式 (Schema) ​

示例 ​

PostInvocation ​

模式 (Schema) ​

示例 ​

Stop ​

模式 (Schema) ​

示例 ​

钩子系统 (Hooks)

配置方式 (Configuration)

模式与文件格式 (Schema and File Format)

钩子定义字段 (Hook Definition Fields)

支持的事件 (Supported Events)

匹配器 (Matcher)

支持的工具 (Supported Tools)

文件与目录操作

搜索与研究

系统与执行

Agent 协同

交互与媒体

钩子处理程序配置 (Hook Handler Configuration)

输入/输出协定 (Input/Output Contract)

通用输入字段 (Common Input Fields)

PreToolUse

模式 (Schema)

示例

PostToolUse

模式 (Schema)

示例

PreInvocation

模式 (Schema)

示例

PostInvocation

模式 (Schema)

示例

Stop

模式 (Schema)

示例