Claude Code PreToolUse 钩子实战用 block-no-verify 插件拦截 AI Agent 的 git 绕过标志【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents导读AI 编程 Agent 在自动提交代码时可能通过git commit --no-verify、git push --no-verify、git commit --no-gpg-sign等绕过标志跳过 pre-commit 钩子让 lint、格式化、测试与安全检查形同虚设。本指南以开源仓库 GitHub_Trending/agents24/agents 中的 block-no-verify 插件为核心完整讲解 PreToolUse 钩子的配置原理、项目级与全局级安装方式、验证方法以及扩展拦截规则的具体操作帮助你在 Claude Code 项目中建立禁止绕过的提交质量门禁。问题背景AI Agent 正在绕过你的 git 钩子pre-commit 钩子是现代工程团队保障代码质量的最后一道防线通常承载着 lint、格式化、单元测试、安全扫描等检查。然而 AI 编码 AgentClaude Code、Codex 等在执行 shell 命令时完全可能携带绕过标志例如# 以下命令都会完全跳过 pre-commit 钩子 git commit --no-verify -m quick fix git push --no-verify git commit --no-gpg-sign -m unsigned commit git merge --no-verify feature-branch这会导致一系列质量与合规问题未格式化的代码进入仓库lint 错误绕过检查安全扫描被跳过未签名提交绕过签名策略测试套件被规避。block-no-verify 插件的目标就是在这些命令真正执行之前通过 Claude Code 的PreToolUse生命周期钩子将其拦截。该插件在 docs/plugins.md 中被收录于安全Security类别描述为 PreToolUse hook blocking--no-verifyand hook-bypass flags可通过/plugin install block-no-verify安装插件还附带一个独立的block-no-verify-hook技能见 docs/agent-skills.md 的技能目录。PreToolUse 钩子机制在工具调用执行前拦截Claude Code 提供生命周期钩子机制其中PreToolUse钩子会在 Agent 发起某个工具调用如 Bash之前运行。block-no-verify 的核心思路是在钩子脚本中读取待执行的命令文本通过环境变量$TOOL_INPUT用正则检测其中是否包含 git 绕过标志命中即拒绝该工具调用。这一机制符合 Claude Code 的钩子语义仓库中其他插件也采用同类机制例如 review-agent-governance 通过PreToolUse钩子调用 Cedar 策略引擎评估工具调用。可见PreToolUse是 Claude Code 中实现执行前策略控制的标准扩展点。钩子配置完整 JSON 与逐字段解读在项目的.claude/settings.json中添加以下PreToolUse钩子配置{ hooks: { PreToolUse: [ { matcher: Bash, hook: { type: command, command: if printf %s \$TOOL_INPUT\ | grep -qE (^||;|\\|)\\s*git\\s.*--(no-verify|no-gpg-sign); then echo BLOCKED: --no-verify and --no-gpg-sign flags are not allowed. Run the commit without bypass flags so that pre-commit hooks execute properly. 2; exit 2; fi } } ] } }各字段与脚本要点的含义如下配置项作用matcher: Bash钩子只作用于 Bash 工具调用不干扰 Read、Edit、Grep 等其他工具避免误伤hook.type: command声明为命令型钩子由 shell 执行command字段中的脚本$TOOL_INPUT环境变量保存 Agent 即将执行的完整命令文本printf %s安全地将$TOOL_INPUT传给 grep避免echo对特殊字符的转义问题正则(^||;|\|)\s*git\s.*--(no-verify|no-gpg-sign)仅当绕过标志前出现git命令允许命令位于行首或跟随、;、|时命中最大限度降低误报exit 2以退出码 2 终止Claude Code 将整体拒绝该工具调用无命中钩子以退出码 0 返回命令正常执行钩子的执行流程分为四步匹配仅针对 Bash 调用→检查解析$TOOL_INPUT中的命令→拦截命中绕过标志则exit 2并输出错误信息→放行未命中则正常执行。退出码语义钩子脚本的退出码决定工具调用的最终结果需严格区分退出码含义0允许工具调用继续执行1出错工具调用仍会执行仅显示警告2完全阻止工具调用因此 block-no-verify 必须使用exit 2才能真正阻止命令执行exit 1只起警告作用。被拦截的标志与拦截原因默认配置拦截以下两个标志标志用途拦截原因--no-verify跳过 pre-commit 与 commit-msg 钩子绕过 lint、格式化、测试与安全检查--no-gpg-sign跳过 GPG 提交签名绕过提交签名策略安装与配置命令项目级与全局级block-no-verify 插件同时提供命令文档与技能文档分别位于 commands/block-no-verify.md 与 skills/block-no-verify-hook/SKILL.md。命令的工作流包含五步检查现有配置、确定作用域、配置钩子、验证配置、测试钩子。1. 检查现有配置配置前先确认项目根目录是否已存在.claude/settings.jsoncat .claude/settings.json 2/dev/null || echo No existing settings found2. 确定作用域传入--global标志时目标为~/.claude/settings.json全局生效否则目标为项目根目录的.claude/settings.json仅当前项目生效。3. 配置钩子若文件不存在直接写入上文完整配置若文件已存在必须保留全部现有配置将新钩子合并进现有hooks.PreToolUse数组不得覆盖已有的其他钩子若传入--extend标志附带额外标志如--extend force,force-with-lease需将这些标志追加进 grep 模式。项目级per-project安装的完整操作mkdir -p .claude cat .claude/settings.json EOF { hooks: { PreToolUse: [ { matcher: Bash, hook: { type: command, command: if printf %s \$TOOL_INPUT\ | grep -qE (^||;|\\|)\\s*git\\s.*--(no-verify|no-gpg-sign); then echo BLOCKED: --no-verify and --no-gpg-sign flags are not allowed. Run the commit without bypass flags so that pre-commit hooks execute properly. 2; exit 2; fi } } ] } } EOF跨项目强制生效则写入~/.claude/settings.json将上述命令中的路径替换为~/.claude/settings.json即可。4. 验证配置写入后校验 JSON 语法并查看生效配置# 校验 JSON 语法 python3 -c import json; json.load(open(.claude/settings.json)) 21 || echo Invalid JSON # 展示已配置的钩子 cat .claude/settings.json5. 测试钩子向用户说明验证方法尝试执行git commit --no-verify -m test应被钩子拦截并报错而git commit -m test应正常工作。扩展拦截规则拦截更多标志需要拦截--force、--force-with-lease等更多标志时扩展 grep 模式即可{ hooks: { PreToolUse: [ { matcher: Bash, hook: { type: command, command: if printf %s \$TOOL_INPUT\ | grep -qE (^||;|\\|)\\s*git\\s.*--(no-verify|no-gpg-sign|force-with-lease|force); then echo BLOCKED: Bypass flags are not allowed. 2; exit 2; fi } } ] } }注意--extend force,force-with-lease只是命令层面对追加标志到 grep 模式这一操作的描述实际落地时需手动将对应标志写入正则的--(...)分组。与其他 PreToolUse 钩子组合多个PreToolUse钩子可共存于同一数组例如同时拦截 git 绕过标志与危险rm命令{ hooks: { PreToolUse: [ { matcher: Bash, hook: { type: command, command: if printf %s \$TOOL_INPUT\ | grep -qE (^||;|\\|)\\s*git\\s.*--(no-verify|no-gpg-sign); then echo BLOCKED: Bypass flags not allowed. 2; exit 2; fi } }, { matcher: Bash, hook: { type: command, command: if printf %s \$TOOL_INPUT\ | grep -qE rm\\s-rf\\s/; then echo BLOCKED: Dangerous rm command. 2; exit 2; fi } } ] } }适用前提与限制钩子机制是 Claude Code 原生能力。从仓库的跨 harness 能力矩阵docs/harnesses.md可见生命周期钩子在 OpenAI Codex CLI、Cursor 中不受支持OpenCode 需通过 TS 插件、Google Antigravity 通过原生生命周期钩子才具备因此本配置直接面向 Claude Code 场景正则按git命令限定匹配范围以降低误报但无法覆盖所有命令变体如通过 shell 别名、环境变量拼装命令等场景属静态检查的固有边界本钩子负责保证 pre-commit 钩子被执行并不替代钩子本身——仍需在仓库中配置有实际意义的 pre-commit 钩子。最佳实践提交 settings 文件将.claude/settings.json纳入版本控制让所有团队成员共享该钩子在 onboarding 文档中说明在贡献指南中说明为何禁止绕过标志避免开发者困惑与 pre-commit 钩子配套block-no-verify 只保证 pre-commit 钩子会运行请确保已配置真正有价值的 pre-commit 钩子设置后主动测试通过一次刻意触发如测试提交中使用--no-verify验证钩子生效。参考文档插件命令主文档plugins/block-no-verify/commands/block-no-verify.md配套技能文档plugins/block-no-verify/skills/block-no-verify-hook/SKILL.md插件目录与安装方式docs/plugins.md技能目录docs/agent-skills.md跨 harness 能力矩阵docs/harnesses.md【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考