HTTP Hooks 与网络边界

HTTP Hook 把事件输入作为 JSON POST 到已有服务，服务必须返回相应 Hook 协议。配置 URL 不会自动创建接收服务。

最小请求配置

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^run_shell_command$",
        "hooks": [
          {
            "type": "http",
            "url": "http://127.0.0.1:8080/hooks/pre-tool-use",
            "headers": {"Authorization": "Bearer ${HOOK_API_KEY}"},
            "allowedEnvVars": ["HOOK_API_KEY"],
            "timeout": 10,
            "name": "shell-review"
          }
        ]
      }
    ]
  }
}

type、url 必填，其他可选字段包括 headers、allowedEnvVars、timeout、name、statusMessage、once。HTTP 默认超时 600 秒；${VAR} 插值只允许 allowedEnvVars 列出的变量。once 是每会话每事件执行一次，仅用于 HTTP Hook。

接收端返回

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "This operation is outside the approved scope."
  }
}

只有响应 Content-Type 为 application/json 时才作为 JSON 解析。其他非空响应体变成 systemMessage，不会像部分 command 事件的 stdout 那样自动进入上下文。要添加上下文，应返回 JSON 的 hookSpecificOutput.additionalContext。

非 2xx 是非阻止 Hook 失败。HTTP 从不跟随重定向，3xx 不会请求新的目标；不要以为服务返回错误状态就等于 deny。执行前拒绝必须使用有效的协议输出，并验证网络故障和超时下的行为。

网络限制

默认拒绝私有和链路本地地址，但允许回环地址 127.0.0.1、::1；请求前还验证 DNS 解析。允许列表设置使用 security.allowedHttpHookUrls。

项目允许列表仅在 User、System、SystemDefaults 都没有设置时生效；上层已有列表时项目值被忽略并警告，不能替换管理员列表。空列表表示允许全部，不是拒绝全部。

受管内部端点需要放宽私有网络范围时，可在用户或系统范围设置 security.allowPrivateNetworkHooks: true。项目范围无效并警告；该设置只放宽一般私有、CGNAT、链路本地范围，允许列表仍独立执行。

云元数据主机名与 169.254.169.254、100.100.100.200 始终阻止，包括其他序列化形式、IPv4-mapped IPv6 和 DNS 解析结果。放宽私网不等于允许元数据服务。两项网络设置更改都需重启。

数据与服务依赖

matcher 命中哪些调用，就会把对应输入发给端点。工具参数可能带文件正文、路径或凭据，* 会覆盖所有匹配事件；先缩小事件范围，再决定接收方如何保存与转发。

官方展示的外部判断服务适配器是示例，并非使用 HTTP Hook 的必要产品依赖。本页只说明通用协议；选择已有内部接收服务时应验证其允许、拒绝、异常响应及超时契约。