watchlight-claude-agent — Claude Agent SDK 治理钩子：每次工具调用 + 子 Agent 启动前授权，fail-closed

技能简介

watchlight-claude-agent 是为 Python Claude Agent SDK 写的治理插件，给无人值守的 Agent 加上 PreToolUse 闸门 + 子 Agent 受控衍生。Python SDK 没有官方 plugin loader，插件通过 hook map 把治理逻辑注入到 ClaudeAgentOptions：每次工具调用前都走授权决策，授权变量只传参数名 + 值类型（不传值，避免泄露敏感数据），任何 deny / 超时 / 后端不可达都 fail-closed（拒绝执行）；每次 Task / Agent 子 Agent 启动也在同一闸门内治理，子 Agent 拿到范围被父凭证收窄的子凭证，spawn 失败时子 Agent 不会启动也不会拿到 model turn。配合 Watchlight 编译策略引擎（in-process Developer Edition 或云端控制平面），让 Claude Agent SDK 满足企业级安全合规要求。

核心能力

• PreToolUse 全量拦截：每个工具调用都在执行前过授权决策，子 Agent 调用使用其自身 handle 的授权范围
• 子 Agent 受控衍生：Task / Agent 工具调用前先做 governed spawn，子凭证范围是父凭证的子集
• fail-closed 拒绝：deny / needs-approval / 后端不可达 / 任何错误一律返回 deny
• 数据脱敏授权：PreToolUse 只传参数名 + 值类型，参数值永远不会离开本机
• 二阶段 spawn 绑定：子 Agent 启动通过 tool-use id 绑定到 governed spawn，120 秒未启动自动关闭
• 双决策后端：Developer Edition 用 in-process 编译策略引擎（本地无基础设施），生产用云端控制平面
• egress 管控：可选 wl-proxy CONNECT 代理 + 进程级 HTTPS_PROXY / HTTP_PROXY，防止敏感数据外联
• 运行启动 fail-closed：未注册 agent / 后端无法建连 / 缺少 constraint manifest 一律 raise GovernanceUnavailable
• 计划验证（可选）：handle.submit_plan 仅在你主动调用时运行，可与工具授权分层
• 45 秒决策 deadline：超过 45 秒未出决策视为 deny，避免挂死

安装配置

# 基础 + Developer Edition（本地策略引擎）
pip install watchlight-claude-agent watchlight-engine

# 或仅装插件（用云端控制平面）
pip install watchlight-claude-agent

环境变量：WATCHLIGHT_PLAN_GOVERNANCE_MODE（fail-closed / degrade）、WATCHLIGHT_PROXY_URL（wl-proxy URL）、WATCHLIGHT_API_KEY（云端模式）。Python 3.10+。

使用步骤

1. 编写 Cedar 策略（policy.json），用 permit(principal, action, resource) 定义允许矩阵
2. 创建 plugin 实例：plugin = WatchlightClaudeAgentSDKPlugin(governance=InProcessClient(POLICIES))
3. 用 async with await plugin.start_run("agent-name") as handle 启动受控运行
4. 调用 plugin.governed_options(handle, ClaudeAgentOptions()) 拿到带治理钩子的 options
5. 把 options 传给 query(prompt=..., options=options)，每个工具调用自动过闸门
6. 启动子 Agent 时用同一 handle，让 Task 工具也走 governed spawn
7. 用 handle.submit_plan(plan_text) 在执行大动作前先过计划验证

适用场景

• 企业部署 Claude Agent SDK：满足 SOC2 / HIPAA 等合规要求的关键工具必须显式授权
• 金融 / 医疗高风险领域：所有 Bash / Write / 数据库工具调用前必须过策略引擎
• 多租户 SaaS：不同租户的 Agent 凭证范围严格收窄，避免越权访问
• 外包团队协作：临时凭证只能调用白名单工具，超出范围一律 deny
• CI 中的 AI Agent：PR 检查、自动化部署，敏感路径必须人工 / 策略批准
• egress 管控场景：wl-proxy 确保所有 HTTP 出站都经审计代理

适用人群

• 平台 / 安全工程师：在企业内推广 Claude Agent SDK 需满足合规要求
• 金融 / 医疗 / 政府开发者：高敏感行业的 AI Agent 必须有 fail-closed 闸门
• Claude Agent SDK 应用开发者：让自己的 agent 在生产环境跑得更安全
• 独立开发者：跑夜间 / 无人值守 agent 时不想半夜被危险操作惊醒
• 多 Agent 协同架构师：父 / 子 agent 凭证层级收窄的最佳实践

工作原理

plugin 把治理逻辑注入到 ClaudeAgentOptions 的 hook map：PreToolUse 在每次工具调用前同步执行授权决策，决策后端调用 Watchlight 编译策略引擎（in-process 或云端）；SubagentStart 处理 Task / Agent 工具的 governed spawn，给子 Agent 颁发被父凭证收窄的子凭证；PostToolUse / PostToolUseFailure 关闭未启动的 spawn 槽位。授权请求只包含参数名和值类型（schema 级别），参数值永远不离开本机。egress 管控通过 HTTPS_PROXY / HTTP_PROXY 环境变量把进程级 HTTP 流量导入本地 wl-proxy，proxy 用 backend 颁发的 token 鉴权。Run 启动时 start_run 必须从 backend 拿到约束清单，否则 raise GovernanceUnavailable，整个 run 不会开始（fail-closed）。整个插件独立于 Anthropic，与 Claude Agent SDK 同名商标仅用于描述兼容性。

官方链接

• PyPI：https://pypi.org/project/watchlight-claude-agent/
• GitHub：https://github.com/watchlight-ai/watchlight-claude-agent
• 官方文档：https://docs.watchlight.ai/de
• 官网：https://watchlight.ai
• 独立第三方插件，与 Anthropic 无关