Git Safety Guardrails 是一款针对自主 AI 智能体的 Git 安全防护工具，核心目标是在智能体执行 Git 命令之前进行确定性拦截，阻止破坏性、不可逆或重写历史的操作。
用途 该工具用于为运行自主智能体的开发环境提供预执行防护，避免智能体自动执行可能导致代码丢失或分支历史被覆盖的 Git 命令。
主要能力
- 确定性拦截：自动阻止 git push --force、git reset --hard、git clean -f/-fd、git branch -D、git checkout .、git restore . 等破坏性命令。
- 显式权限门：被拦截的命令返回非零退出码（文档中测试步骤要求退出码为 2），并向智能体输出说明性信息，表明其无权执行该操作。
- 范围选择：安装前需询问用户是仅在项目级配置（.claude/settings.json）还是全局配置（~/.claude/settings.json）中启用防护，默认使用项目级。
- 设置合并安全：将防护钩子合并进已有的 PreToolUse 配置，不覆盖其他工具或设置。
- 强制拦截测试：安装结束前必须用模拟禁用命令验证钩子能正确触发。
组成结构
- scripts/block-dangerous-git.sh：分类钩子脚本，检查并阻止禁用的 Git 命令模式。
- scripts/classify_git_command.py：Python 命令解析器，用于解析复杂的 shell 命令链。
- .claude/settings.json 或 ~/.claude/settings.json：钩子注册所在的配置。
使用方式
- 确认防护范围：询问用户是项目级还是全局，默认项目级。
- 复制钩子脚本：将 scripts/block-dangerous-git.sh 复制到 .claude/hooks/block-dangerous-git.sh，并执行 chmod +x 赋予可执行权限，确保父目录已创建。
- 注册钩子：在 .claude/settings.json 中添加 PreToolUse 钩子条目，合并进已有数组，使用 "$CLAUDE_PROJECT_DIR"/.claude/hooks/block-dangerous-git.sh 路径展开。
- 验证拦截：执行模拟测试，例如： echo '{"tool_input":{"command":"git push origin main --force"}}' | .claude/hooks/block-dangerous-git.sh 确认命令以退出码 2 结束并输出拦截提示。
约束规则 工具明确反对若干常见放宽理由：不得因工作区存在未提交问题而允许 git reset --hard，必须改用显式的 stash 或 revert；默认拦截所有强制推送，包括功能分支；不得跳过模拟测试，因为钩子脚本的语法错误会导致其失效放行，使仓库失去保护。
适用场景 适用于使用自主编码智能体、且需要防止智能体误执行破坏性 Git 操作的仓库开发环境。
限制 具体支持的 Git 命令范围以脚本内容为准；文档未说明对其他版本控制操作或非 Git 命令的防护能力。