agent-guard-hooks Claude Code 行为护栏 Skill 技能

技能简介

agent-guard-hooks（包名 agent-guard-hooks）是一套为 Claude Code 量身定制的"行为护栏"Hook 集合，全部用 Python 标准库实现，零三方依赖。安装一条命令即可在 Claude Code 的 SessionStart、PreToolUse、PostToolUse、Stop 等生命周期事件上注入六类防护：阻止"改测试让代码看起来绿"的作弊、阻止推送到保护分支 / 包发布 / 生产部署 / 云资源花费等高风险外发动作、对声明已生效的命令做执行后回读验证、并提供 mutation test-honesty 自检 CLI。它把"AI 编程助手不该犯的错"在 Hook 层硬性拦截，而不是依赖模型自觉。

核心能力

• Test tampering guard：会话开始时给所有测试与源码做哈希快照，会话结束时如果测试文件被改/被删而源码没动，强制 Stop 时拦下，要求证明改动后的测试在无 fix 时确实失败
• Outbound action guard：PreToolUse(Bash) 上的黑名单 hook，覆盖 push 到保护分支、force push、npm publish/twine upload 等包发布、生产部署、云资源消耗、Slack webhook 群发等模式
• 脚本内容扫描：v0.2 起会扫描被执行的脚本文件（如 bash evil.sh）的实际内容，关闭"先把脚本写出来再执行"的绕路
• Post-exec read-back verifier：声明外发生效的命令（git push、npm publish 等）执行后做世界状态回读，未生效则告警但永不阻断
• Mutation test honesty checker：对"我自己写测试自己跑"的区分
• 审计日志与白名单：每条匹配结果写入审计日志；用户白名单可在 config.json 中覆盖默认拦截

安装配置

pip install agent-guard-hooks
agent-guard init    # 生成 config.json 与 .agent-guard/ 目录

零依赖意味着即便在一个非常受限的 Python 环境里也能直接拉起；Hook 入口由 agent-guard CLI 注册到 ~/.claude/settings.json 的 hooks 段，SessionStart、PreToolUse、PostToolUse、Stop 四个事件全覆盖。denylist 模式默认保守，可通过 config.json 增加自定义规则或白名单。

使用步骤

1. pip install agent-guard-hooks 后执行 agent-guard init，初始化配置与目录。
2. 在 ~/.claude/settings.json 的 hooks 字段里挂上 agent-guard 对应生命周期命令（脚本会写入）。
3. 在 config.json 中按需调整黑名单（默认已覆盖推送、发布、生产部署、云资源消耗、群发 webhook）与白名单。
4. 启动一次 Claude Code 会话，SessionStart hook 自动为所有测试与源码建立哈希基线。
5. 助手在执行 Bash 时，外发动作先经 PreToolUse 拦截；声明已生效的命令执行后会由 PostToolUse 回读。
6. 会话结束时，Stop hook 对比测试文件 vs 源码文件的变化，发现"只动测试不动源码"则强制要求重新证明每个被改的测试在无 fix 时确实失败。

适用场景

• AI 编程助手安全护栏：让 Claude Code / Codex 类的 Agent 在不告知用户地推送到保护分支、包发布、生产部署前被拦截
• 测试诚实性治理：杜绝"让测试看起来绿"的作弊，要求每个被改测试都要给出"无 fix 时确实失败"的证据
• 外发动作可观测：把所有被拦截/被允许的外发动作写入可审计的日志，便于事后复盘
• 本地化部署：零三方依赖，适合在受限/隔离的开发机、内网或 CI 容器中直接拉起
• 多人协作/合规团队：通过白名单与可审计日志，让 AI 编程的破坏面处于可解释状态

适用人群

适合所有重度使用 Claude Code / 类似 AI 编程助手的研发团队，尤其是金融、政企、医疗、关键基础设施等对代码改动与外发动作有合规审计要求的场景；对个人重度用户而言，也是降低"AI 误推"风险的最低成本护栏。

工作原理

agent-guard 通过 Claude Code 提供的 hooks 机制把 Python 脚本注入到 SessionStart、PreToolUse、PostToolUse、Stop 四个生命周期：SessionStart 收集测试/源码的 SHA256 哈希作为基线；PreToolUse 在 Bash 调用前用 denylist 模式匹配 git push/npm publish/twine upload/云 CLI 等动作，匹配即阻断并写入审计；脚本被执行的"二次绕路"通过读取脚本内容再做匹配关掉；PostToolUse 在命令声明已生效时（如 git push）再读一次世界状态校验；Stop 时则要求"测试改了但源码没动"必须有证人在前面继续证明每个被改的测试在无 fix 时确实失败。

官方链接

• GitHub 仓库：https://github.com/hahahahahahahahah6/agent-guard
• PyPI 包：https://pypi.org/project/agent-guard-hooks/
• 适用宿主：Claude Code（依赖其官方 Hooks 机制）
• 许可证：MIT