Hooks 配置、开关与环境

配置分两层：事件中的分组定义 matcher 和 sequential，组内 hooks 数组定义每个命令。当前执行引擎只支持 command。

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "sequential": true,
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000,
            "description": "Check proposed file changes"
          }
        ]
      }
    ]
  }
}

示例脚本需要自行创建。组内 sequential 为 true 时依次运行，false 时并行；本页显式配置，不从省略值推断执行顺序。timeout 单位毫秒，单个 Hook 默认 60000。

匹配规则

BeforeTool/AfterTool 的 matcher 是工具名称正则；生命周期事件使用精确触发字符串，例如 startup。* 或空字符串匹配全部，不能把生命周期 matcher 当成通用正则。

配置可能来自项目、用户、系统和扩展。Hooks 概览的层级列表与通用 settings 合并说明方向不同；多来源同事件时应在面板核对真实加载结果，不用这一列表推导企业设置可被项目绕过。

开关

当前配置参考的 hooksConfig.enabled 默认 true，改变后需重启；hooksConfig.disabled 默认空数组，用于禁用指定 Hook；hooksConfig.notifications 默认 true。

最佳实践页仍有旧 hooks.disabled 示例，与当前生成配置不一致。新设置采用 hooksConfig.disabled，并通过面板检查。

交互管理

脚本环境

GEMINI_PROJECT_DIR 为项目根绝对路径，GEMINI_PLANS_DIR 为计划目录，GEMINI_SESSION_ID 为会话 ID，GEMINI_CWD 为当前目录；CLAUDE_PROJECT_DIR 作为兼容别名提供。不要在普通终端检查不到这些变量时就认定 Hook 环境也没有，它们由 CLI 调用时提供。