加载中

钩子(Hooks)作为审批关卡

第 11 课7 分钟

构建阶段使用钩子(hooks)作为护栏,在没有人工介入的情况下允许或阻止操作(阶段 3:构建)。钩子也可以发出询问(ask),暂停操作,直到运行该会话的人确认为止。当审批者是其他人(例如发布经理)时,钩子会查找其已记录的批准,并在批准存在之前保持阻止状态。

该实践位于阶段 5:部署,因为发布关卡是最清晰的案例,但钩子并非部署专用:它们会在 Claude 执行操作的任何地方运行。例如,在阶段 3:构建期间,钩子可以阻止在没有变更工单的情况下对迁移脚本和基础设施进行编辑;在阶段 4:测试期间,钩子可以阻止代理在修复任务中编辑测试文件。

入门指南

  • 前提条件:无。
  • 基础设施:一份书面列表,列出变更流程所需的审批。

如何执行

  1. 工程领导层与变更管理和合规团队一起,列出必须保留的人工审批关卡,例如变更管理签核、发布授权以及对受保护路径的编辑。
  2. 平台工程师将每个关卡表达为一个钩子——一个在 Claude 执行操作之前运行的脚本,可以允许(allow)、询问(ask)或阻止(block)。
  3. 团队钩子放在 Git 中的 .claude/settings.json 里,而不可协商的钩子则放在由平台或 IT 管理员拥有的托管设置(managed settings)中,个别工程师无法将其关闭。
  4. 阻止操作应当自我解释,因此当钩子阻止某个操作时,原因和获取批准的途径会出现在 Claude 的输出中。

实际效果

此示例是一家保险公司的客户门户,发布到开发(dev)、预发布(staging)和生产(production)环境。部署通过 MCP 工具运行,每个环境对应一个服务器,每个服务器都有一个 release 工具。

下面的条目是项目 .claude/settings.json 中的一个独立示例。其匹配器(matcher)会捕获每个服务器上的 release。空的 args 列表使 Claude Code 直接运行脚本,而不是通过 shell 运行:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__deploy-.*__release",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/release-gate.sh",
            "args": [] }
        ]
      }
    ]
  }
}

关卡本身,即 .claude/hooks/release-gate.sh:

bash
#!/bin/bash
# 发布关卡。dev:允许。staging:询问。production:需要此版本的已批准变更工单,否则阻止。
input=$(cat)
tool=$(jq -r '.tool_name' <<<"$input")
version=$(jq -r '.tool_input.version' <<<"$input")
ticket=$(jq -r '.tool_input.ticket // empty' <<<"$input")

decide() {   # decide <allow|ask|deny> <reason>
  jq -n --arg decision "$1" --arg reason "$2" '{hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: $decision,
    permissionDecisionReason: $reason}}'
  exit 0
}

case "$tool" in
  mcp__deploy-dev__release)
    decide allow "dev needs no approval" ;;
  mcp__deploy-staging__release)
    [ "$GITHUB_REF" = "refs/heads/main" ] && decide allow "pipeline release from main"
    decide ask "This ships $version to staging. Approve only if you own this release." ;;
  mcp__deploy-prod__release)
    route="Open a change ticket at https://change.example.com/new for version $version, \
wait for the release manager to approve it, then call release again with that ticket number."
    [[ "$ticket" =~ ^CHG-[0-9]+$ && "$version" =~ ^[0-9a-f]{7,40}$ ]] ||
      decide deny "Production needs an approved change ticket. $route"
    if approver=$(/usr/local/bin/change-ticket show --ticket "$ticket" --format json |
        jq -er --arg v "$version" 'select(.state == "approved" and .version == $v) | .approver' 2>/dev/null); then
      decide allow "$ticket approved by $approver"
    fi
    decide deny "$ticket is not approved for version $version. $route" ;;
  *)
    decide deny "No release rule for $tool. Add one to release-gate.sh first." ;;
esac

在脚本中,version 和 ticket 是 Claude 传递给 release 工具的输入。change-ticket 代表您的变更系统自身的命令行工具。该关卡依赖于代理无法写入其所读取的记录这一前提。

在非交互式运行中,没有人可以回答 ask,因此 Claude Code 会拒绝该调用。这就是为什么该关卡允许从 main 上的流水线发布到预发布环境——在这种情况下,已批准的合并(merge)本身就是批准。

该关卡存在一个限制。工程师可以在自己的会话中手动设置 GITHUB_REF,不过这样做只会跳过他们本来需要自己回答的提示。

ask 上的原因会展示给人看。deny 上的原因会展示给 Claude,因此阻止消息会指明获取批准的途径,以便 Claude 转达。预发布结果在前,随后是没有工单的生产环境结果:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "This ships 4f2c9e1 to staging. Approve only if you own this release."
  }
}
json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Production needs an approved change ticket. Open a change ticket at https://change.example.com/new for version 4f2c9e1, wait for the release manager to approve it, then call release again with that ticket number."
  }
}

治理考量

钩子就是审批关卡。关卡条件每次都会被强制执行,对所有人一视同仁。允许和阻止的决定都会带时间戳记录下来。关卡还定义了什么算作批准,无论是已批准的变更工单,还是发布经理的签核。

面向受监管企业的托管设置

面向受监管企业的托管设置,由平台团队通过移动设备管理(MDM)或管理控制台部署。工程师无法编辑或覆盖其中的任何设置。请参见下文:

json
{
  "permissions": {
    "deny": [
      "Read(.env*)", "Read(./secrets/**)",
      "WebFetch", "Bash(curl *)", "Bash(wget *)"
    ],
    "allow": [
      "Bash(git *)", "Bash(make build)",
      "Bash(make test)", "Bash(make lint)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": { "allowedDomains": ["git.internal.example.com", "registry.npmjs.org"] },
    "credentials": {
      "files": [
        { "path": "~/.ssh", "mode": "deny" },
        { "path": "~/.aws/credentials", "mode": "deny" }
      ],
      "envVars": [ { "name": "GITHUB_TOKEN", "mode": "deny" } ]
    }
  },
  "allowManagedHooksOnly": true,
  "disableSideloadFlags": true,
  "allowManagedMcpServersOnly": true,
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "example-corp/approved-plugins" }
  ],
  "requiredMinimumVersion": "2.1.193"
}

从控制角度看,这些设置的作用:

  • permissions.deny 使密钥不会进入代理的上下文,并阻止工具进行任意的网络出站访问。permissions.allow 预先批准安全的内部循环,使拒绝列表不会演变成提示疲劳。
  • disableBypassPermissionsMode 加上 allowManagedPermissionRulesOnly 意味着没有任何工程师、项目文件或命令行标志可以放宽这些规则。
  • sandbox 覆盖了权限无法覆盖的部分。对 WebFetch 的工具级拒绝并不能阻止 shell 命令访问网络,而操作系统级的域名允许列表则会直接阻止出站访问,因此这两者在不同层面上共同实现同一个目标。failIfUnavailable 和 allowUnsandboxedCommands 将沙箱变成一个前提条件,这意味着当沙箱无法初始化时,Claude Code 会拒绝启动,并且在沙箱内失败的命令无法在沙箱外重试。
  • credentials 处理了拒绝规则未能覆盖的情况。permissions.deny 管理的是 Claude 的文件工具,但默认情况下,沙箱化的 shell 命令仍可能读取 ~/.ssh 或 ~/.aws/credentials。此配置块拒绝这些读取操作,并从沙箱化命令的环境中剥离所列出的密钥。
  • allowManagedHooksOnly 意味着只有在托管设置中定义的钩子才会运行;用户、项目和本地设置中的钩子都会被阻止,包括上文中独立的 .claude/settings.json 示例。为了让本实践中的审批关卡持续生效,应将其定义在托管文件自身的 hooks 配置块中。
  • disableSideloadFlags 和 strictKnownMarketplaces 意味着工程师机器上的任何技能(skill)、代理(agent)、钩子或 MCP 服务器都必须来自组织批准的插件市场,而不是来自主目录。市场允许列表控制可以安装的内容,而那些会为单次运行侧载(sideload)插件、代理或 MCP 配置的标志会在启动时被拒绝。
  • allowManagedMcpServersOnly 使代理的工具范围成为由平台团队拥有的一份允许列表。
  • requiredMinimumVersion 会拒绝在低于已批准最低版本的版本上启动,因此这些控制措施是由组织实际评估过的构建版本来强制执行的。

请将此示例视为一个起点,根据您自己的环境进行定制。每条拒绝规则都会移除某些能力,而正确的平衡取决于代码仓库的数据分类。设置参考文档记录了所有键,包括仅限托管设置使用的键。

如何衡量

对于钩子本身:

  • 领先指标:在每个审批关卡上等待所花费的时间。每个钩子决策都会带时间戳以及允许或阻止的判定写入 OpenTelemetry 导出数据,因此每个关卡的等待时间都是可见的。
  • 滞后指标:根据事件跟踪系统记录的,在引入钩子前后到达生产环境的关卡违规次数。