钩子挂钩允许您在 Antigravity 执行循环期间的特定点运行自定义脚本或 shell 命令。这对于执行自定义规则、运行 linter 或自动捕获诊断信息非常有用。

配置挂钩在位于自定义目录中的 hooks.json 文件中进行配置（例如，工作区中的 .agents/ 或 ~/.gemini/config/ ）。

架构和文件格式

hooks.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"
      }
    ]
  }
}

钩子定义字段

支持的活动

匹配器对于 PreToolUse 和 PostToolUse ，您可以在 matcher 字段中使用正则表达式来指定哪些工具触发挂钩：

• "" 或 "*" ：匹配所有工具。
• "run_command" ：完全匹配 run_command 。
• "run_command|view_file" ：匹配任一工具。
• "browser_.*" ：匹配以 browser_ 开头的任何工具。

<公告> 图标：信息 iconColor: var(--主题-primary) 颜色：var(--主题-表面-表面-容器) 文本： 注意：对于 PreInvocation 、 PostInvocation 和 Stop ，结构更简单（直接位于事件键下的处理程序列表）并且匹配器被忽略。 </公告>

支持的工具对于 PreToolUse 和 PostToolUse 匹配器，您可以匹配以下工具名称（按类别分组）：

文件和目录操作

• ** view_file **：查看文件的内容。
• 参数： AbsolutePath 、 StartLine （可选）、 EndLine （可选）、 IsSkillFile （可选）
• ** write_to_file **：创建新文件。
• 参数： TargetFile 、 Overwrite 、 CodeContent 、 Description 、 IsArtifact （可选）、 ArtifactMetadata （可选）
• ** replace_file_content **：编辑文件中的单个连续文本块。
• 参数： TargetFile 、 Instruction 、 Description 、 AllowMultiple 、 TargetContent 、 ReplacementContent 、 StartLine 、 EndLine 、 TargetLintErrorIds （可选）
• ** multi_replace_file_content **：对同一文件进行多次、不连续的编辑。
• 参数： TargetFile 、 Instruction 、 Description 、 ReplacementChunks （块数组）、 TargetLintErrorIds （可选）、 ArtifactMetadata （可选）
• ** list_dir **：列出目录的内容。
• 参数： DirectoryPath
• ** find_by_name **：使用 glob 模式搜索文件和目录。
• 参数： SearchDirectory 、 Pattern 、 Type （可选）、 Excludes （可选）、 Extensions （可选）、 FullPath （可选）、 MaxDepth （可选）

搜索与研究

• ** grep_search **：在特定路径内快速文本搜索。
• 参数： SearchPath 、 Query 、 IsRegex （可选）、 CaseInsensitive （可选）、 Includes （可选）、 MatchPerLine （可选）
• ** search_web **：执行一般网络搜索。
• 参数： query 、 domain （可选）
• ** read_url_content **：获取公共 URL 的文本内容。
• 参数： Url

系统与执行

• ** run_command **：建议运行 bash 命令。
• 参数： CommandLine 、 Cwd 、 WaitMsBeforeAsync 、 RunPersistent （可选）、 RequestedTerminalID （可选）
• ** manage_task **：与后台任务交互。
• 参数： Action （ 'list' 、 'kill' 、 'status' 、 'send_input' ）、 TaskId （可选）、 Input （可选）
• ** schedule **：设置计时器或重复的 cron 作业。
• 参数： DurationSeconds （可选）、 CronExpression （可选）、 MaxIterations （可选）、 Prompt
• ** list_permissions **：查看当前资源访问授权。
• 参数：无
• ** ask_permission **：请求额外的范围权限。
• 参数： Action 、 Target 、 Reason

代理协作

• ** invoke_subagent **：生成专门的子代理。
• 参数： Subagents （包含 Prompt 、 Role 、 TypeName 、 Workspace 的规范数组（可选））
• ** define_subagent **：创建自定义子代理。
• 参数： name 、 description 、 system_prompt 、 enable_mcp_tools （可选）、 enable_write_tools （可选）、 enable_subagent_tools （可选）
• ** send_message **：与其他代理通信。
• 参数： Recipient 、 Message
• ** manage_subagents **：列出或终止活动子代理。
• 参数： Action （ 'list' 、 'kill' 、 'kill_all' ）、 ConversationIds （可选）

互动与媒体

• ** ask_question **：提出多项选择题。
• 参数： questions （包含 question 、 options 、 is_multi_select 的问题数组）
• ** generate_image **：创建或编辑图像。
• 参数： Prompt 、 ImageName 、 ImagePaths （可选）

钩子处理程序配置

hooks 数组中的每一项都支持：

输入/输出合同挂钩通过 stdin 作为 JSON 接收输入，并应通过 stdout 作为 JSON 返回输出。字段名称使用驼峰命名法。

通用输入字段所有挂钩在 stdin 上的输入负载中接收以下系统元数据字段：

预工具使用在执行工具之前触发。

模式

输入字段（标准输入）：

输出字段（标准输出）：

例子

• 输入（标准输入）：

{
  "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"
}

• 输出（标准输出）：

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

后期工具使用工具完成后触发。

模式

输入字段（标准输入）：

输出字段（stdout）：返回空 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"
}

• 输出（标准输出）： {}

预调用在调用模型之前触发。

模式

输入字段（标准输入）：

输出字段（标准输出）：

注入的步骤架构： injectSteps 数组中的每个对象都可以具有以下字段之一：

• toolCall （对象）：要执行的工具调用。
• userMessage （字符串）：来自用户的消息。
• ephemeralMessage （字符串）：瞬态系统消息。

例子

• 输入（标准输入）：

{
  "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"
}

• 输出（标准输出）：

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

调用后工具调用完成后触发。

模式

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

输出字段（标准输出）：

例子

• 输入（标准输入）：与 PreInvocation 相同
• 输出（标准输出）：

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

停止当执行循环终止时触发。

模式

输入字段（标准输入）：

输出字段（标准输出）：

例子

• 输入（标准输入）：

{
  "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"
}

• 输出（标准输出）：

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