setup-git-guardrails

设置 Git 防护措施

在破坏性 Git 命令前加入人工决策，让人类逐一批准，而不是由 Agent 未经检查就执行。常规操作（提交、推送到功能分支、试运行）不受影响。此设置与 Agent 无关：分为两层，不假设使用任何特定运行环境。

• 可移植层：Git pre-push 钩子。适用于任何 Agent 和任何人，但 Git 没有针对 reset --hard 等本地命令的钩子，因此它只保护推送操作。
• Agent 层：scripts/guard-git.py，一个命令防护工具，接入各运行环境自身的命令拦截方式。它会读取命令文本，因此能够识别命令链（&&、;、|、&）、sudo、xargs、command、bash -c、$(...) 和 git -C。

防护级别

每个级别都包含其上方级别的内容。

级别	防护内容
1. 共享历史记录	推送到受保护分支（main、master、远程的默认分支，以及用户添加的任何分支）、普通强制推送（-f、--force、+ refspec）、删除或镜像推送（--delete、:branch、--mirror、--all、--prune）、推送时使用 --no-verify。--force-with-lease 和 --dry-run 不受拦截
2. 本地工作	reset --hard、clean -f（非试运行）、branch -D、会丢弃更改的 checkout 或 switch（.、-- <paths>、-f、--discard-changes）、针对工作区的 restore（单独使用 --staged 不受拦截）、stash drop 和 clear、worktree remove --force、reflog expire 和 delete、gc --prune、prune
3. 严格	所有推送，以及 rebase、任何形式的 reset、commit --amend、任何分支或标签删除、filter-branch、filter-repo、update-ref

步骤

1. 询问要设置哪些内容

一次性询问，并为每项提供推荐答案（运行环境有提问工具时使用该工具，否则使用普通聊天）：

• 级别：1、2 或 3。推荐 2。
• 范围：仅限此项目，还是所有项目。
• 运行环境：用户使用哪些 Agent 运行环境。运行 python3 -I scripts/detect-harnesses.py --project .，获取磁盘上的候选项（目录、路径中的命令、引导文件；只有已安装技能的目录会作为一行 skills-only 返回），若当前使用的运行环境不在列表中，则将其添加进去，并提出该列表。
• 受保护分支：保留 main 和 master；添加 develop 等其他分支。

完成条件：已确定级别、范围、运行环境和受保护分支。

2. 安装可移植层

将 scripts/pre-push 复制到仓库的钩子目录（git rev-parse --git-path hooks，该命令会遵循 core.hooksPath），设置为可执行文件，并在文件顶部设置 PROTECTED_BRANCHES 和 LEVEL。如果已有 pre-push 钩子，则从现有钩子中调用新钩子，并确保现有钩子继续正常工作。钩子仅属于单个仓库，因此若要设置全局范围，请询问要在哪些仓库中安装。

完成条件：钩子可执行，且会拒绝模拟的删除操作；运行 printf 'refs/heads/x 0000000000000000000000000000000000000000 refs/heads/feat abc\n' | <hook> 时会以 1 退出。

3. 按各个 Agent 框架接入 Agent 层

将 scripts/guard-git.py 复制到适用于该范围的稳定路径（项目中为 .agents/hooks/，全局为 ~/.agents/hooks/）。它需要 Python 3 和 git。先运行 python3 --version；如果没有 Python 3，此钩子会默认放行，因此请跳过此步骤并说明原因。

对于每个 Agent 框架，请查阅其当前关于命令拦截的文档，因为架构和文件位置会随版本发布而变化。使用文档中最强的机制：

1. 可询问或拦截的命令前钩子。 将其指向 python3 -I <path>/guard-git.py --level <N> --protected <branches>，并通过标准输入传入钩子负载。默认的 text 格式会以退出码 2 结束，并将原因写入标准错误，这是拦截钩子的常见约定；--format ask-json 会输出 Claude Code 风格钩子所接受的权限提示决策。
2. 带命令模式的权限规则。 将防护表转换为询问规则。模式无法识别分支或命令链，因此会对每次非演练推送都进行询问。
3. 两者都没有。 仅使用可移植层。告知用户哪些级别 2 和 3 的命令未受防护。

EXAMPLES.md 展示了前两种机制各自的一种接入方式。合并到 Agent 框架现有的设置中，并保留已有的每一项。

完成标准：记录每个 Agent 框架所用的机制（1、2 或 3），并确保其设置文件仍能解析。

4. 验证

在所选级别下，对三个命令运行防护，并确认第一个受到防护（退出码为 2），其余命令正常通过（退出码为 0）：

printf 'git push origin main' | python3 -I <path>/guard-git.py --level <N>
printf 'git push --force-with-lease origin feature' | python3 -I <path>/guard-git.py --level <N>
printf 'echo "git push origin main"' | python3 -I <path>/guard-git.py --level <N>

然后，在 Agent 框架允许的情况下，通过该框架本身检查各自的接入情况（在全新会话中执行受防护的命令，应出现提示或拦截）。

5. 报告

每层和每个 Agent 框架各用一行说明：级别、机制、已验证和仅已写入的内容，以及仍未受防护的内容。

更改或移除此功能

根据新的答案重新执行这些步骤：文件会原地覆盖，设置项会被替换，而不会重复添加。若要移除，请列出钩子、复制的脚本和每个设置项，并在征得用户同意后将它们删除。

告知用户的限制

• 防护会读取命令文本。它不会跟踪 git 别名、运行 git 的脚本和 eval，因此它能捕捉错误，但无法阻止有意绕过。远程仓库上的分支保护才是唯一的硬性阻止措施。
• 确认操作需要由人来完成。无人可以确认时，受防护的命令会被拒绝。
• git push --no-verify 会跳过钩子；在级别 1 下，命令防护会在执行前询问，而用户可以有意使用此命令来批准推送。