git-guardrails

用途

git-guardrails 用于为 Codex 或 Claude Code 安装 Git 防护栏（hooks），在危险 Git 命令执行前将其拦截，防止智能体误执行破坏性操作。仅安装该技能本身不会改动任何宿主设置。

主要能力

会被拦截的命令包括：

• git push（所有变体，包括 --force）
• git reset --hard
• git clean -f / git clean -fd
• git branch -D
• git checkout . / git restore .

被拦截时，智能体会看到一条消息，告知其没有权限访问这些命令。

检测器会检查普通字面量的 Git shell 命令，涵盖常见 Git 选项与 shell 分隔符。

使用方式

1. 确定用户指定的宿主（Codex 或 Claude Code）、项目级或全局作用域，以及要拦截的操作，并询问是否增删拦截列表中的模式。在编辑前检查现有设置与实际钩子能力。当目标与策略明确且获得授权后，此步骤完成。
2. 将 Python 检测器复制到约定的钩子位置，并确认可用的 Python 3。如有增删模式，编辑复制后的检测器。当检测器通过其测试用例且限制说明与所需策略一致时完成。
3. 阅读对应的宿主参考文档，在现有设置中合并一个命令钩子，且不替换无关钩子。解析绝对脚本路径，或使用宿主文档中规定的项目钩子目录形式；切勿使用不可信的 issue 文本构建命令。当保存的 matcher 与命令符合该宿主的文档化 schema 时完成。
4. 使用 stdin 测试数据测试无害的允许与拒绝事件；例如被拒绝的 git push origin main 应以退出码 2 结束，并向 stderr 输出 BLOCKED 消息。随后在不运行破坏性命令的情况下，验证宿主确实调用了钩子。Codex 钩子需要原生 review/trust，应如实报告待信任步骤，绝不绕过。当观察到的宿主行为符合策略，或激活仍是明确的缺口时完成。

宿主适配器

• Codex：阅读 Codex 适配器。
• Claude Code：阅读 Claude Code 适配器。

可选的 scripts/block-dangerous-git.sh 包装脚本会为现有的 shell 钩子启动器调用 Python 检测器。两个适配器使用同一检测器和相同的 JSON 拒绝响应。

可在该技能目录下运行以下命令来检验其有限范围内的命令覆盖：

python3 -m unittest discover -s scripts/tests -v

限制

该检测器是误操作防护栏，并非完整的 shell 沙箱：别名、不透明脚本、间接的语言运行时或不受支持的宿主路径都可能绕过它。强制执法应使用宿主权限机制。