agents-gitflow-guard 0.0.17 → 0.0.19

package/README.md

@@ -36,16 +36,26 @@ You define your own branches —
 
 ## Quick Start — 30 seconds to a guarded repo
 
-**Step 1 — install**, then restart DSH (plugins load at process startup):
+**Step 1 — install.** All six clients consume the same npm package `agents-gitflow-guard` — pick yours:
 
 ```bash
-# installs the latest release
-dsh plugin --profile web add agents-gitflow-guard
-# ...or pin an exact known-good version (recommended; also bypasses stale registry caches)
-dsh plugin --profile web add agents-gitflow-guard@0.0.17
+# DSH — in-process plugin; restart DSH afterwards (plugins load at startup)
+dsh plugin --profile web add agents-gitflow-guard@0.0.19
 ```
 
-> **Version gotcha**: a bare `add` resolves whatever `latest` is at install time — on machines behind a stale npm/pnpm registry cache or mirror it may install an old version. If the installed version looks wrong, pin it explicitly. The peer-dependency *warning* pnpm may print is expected: DSH supplies `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` through its shared profile module fallback at startup (the plugin works normally).
+```bash
+# Claude Code · Codex · OpenCode · Antigravity — standalone hooks, no DSH needed
+npm i -g agents-gitflow-guard@0.0.19
+```
+
+```bash
+# Pi — in-process extension
+npm i -D agents-gitflow-guard@0.0.19
+```
+
+> **Version gotcha**: a bare `add` or unpinned `npm i` resolves whatever `latest` is at install time — on machines behind a stale npm/pnpm registry cache or mirror it may install an old version. If the installed version looks wrong, pin it explicitly. (DSH users: the pnpm peer-dependency *warning* is expected — DSH supplies `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` through its shared profile module fallback at startup; the plugin works normally.)
+>
+> The hook clients (Claude Code · Codex · OpenCode · Antigravity) and Pi need one wiring step after install — walk the per-agent table in [Installation in detail](#installation-in-detail).
 
 **Step 2 — configure**, create `gitflow-guard.config.json` in your **project root**:
 
@@ -294,6 +304,12 @@ archive (optional; you archive after release)
 | PR/MR into archive | ✅ create allowed; 🚫 merge blocked (you merge in UI) |
 | local `git merge feature/x` while on integration / preview | 🚫 block (PR/MR required); `update: flexible` allows |
 | chained commands (`checkout develop && merge feature/x`) | 🚫 blocked — branch switches are simulated per segment, no bypass |
+| force-recreate a protected branch (`git checkout -B/-C <branch>` / `git switch -C`) | 🚫 block (direct ref-update gate) |
+| retarget/delete a protected branch via `git symbolic-ref` | 🚫 block (direct ref-update gate) |
+| `git cherry-pick` / `git revert` while on integration / preview / production / archive | 🚫 block (history rewrite on a protected branch); `-n` / `--no-commit` and `--abort`/`--continue`/`--skip`/`--quit` pass |
+| `sudo`-wrapped git commands (privilege wrapper) | 🚫 wrapper peeled (`sudo -u …` included), underlying command gated |
+
+> Two deliberate non-gates, so they don't get "closed" by accident later: `git tag -f` (moving a tag, even pointing at a protected branch) stays exempt — tags are outside the branch-role scope, same as `push --tags`; and a plain `git commit` on a protected branch stays allowed — the guard governs branch roles and merge paths, not content, and the following `git push` is still blocked (remote stays clean).
 
 The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab). Without a platform CLI, the plugin is conservative.
 
@@ -307,12 +323,18 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 ---
 ## Installation in detail
 
-**Prerequisite**: a working [DSH](https://github.com/deepseek-ai/deepseek-harness) installation and **Node.js ≥ 22** on your `PATH` (matches the package `engines` floor and the lowest CI matrix tier — standalone hook users bypass npm but still need the runtime).
+**Prerequisite**: **Node.js ≥ 22** on your `PATH` (the package `engines` floor and the lowest CI matrix tier). Every client consumes the **same npm package** `agents-gitflow-guard` — only the mounting step differs.
 
-**From the npm registry** — the standard path, already covered in [Quick Start](#quick-start--30-seconds-to-a-guarded-repo):
+| Agent | Install command | After that |
+|---|---|---|
+| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.19` | restart DSH — the plugin auto-mounts as a profile layer |
+| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.19` | wire a hook to the `gitflow-guard` binary (below) |
+| Pi | `npm i -D agents-gitflow-guard@0.0.19` | copy `pi/gitflow-guard.ts` into `.pi/extensions/` (below) |
+
+**DSH — in-process plugin** (the standard path, already covered in [Quick Start](#quick-start--30-seconds-to-a-guarded-repo)):
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.17    # pin recommended, see note above
+dsh plugin --profile web add agents-gitflow-guard@0.0.19    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -326,14 +348,20 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 
 The package declares `dsh.bundle.patch`, so `dsh plugin add` automatically makes it a profile layer — no manual profile editing.
 
-**Standalone agent hooks** — the same guard inside those agents, no DSH required. This repo ships project configs at `.claude/settings.json` (Claude Code), `.codex/hooks.json` (Codex), `.opencode/hook/hooks.yaml` (OpenCode), `.agents/hooks.json` (Antigravity / Google) and `.pi/settings.json` + `.pi/extensions/gitflow-guard.ts` (Pi); any other repo adds its own:
+**Standalone agent hooks** — Claude Code / Codex / OpenCode / Antigravity, no DSH required. Install the CLI once, then reference the `gitflow-guard` binary in each hook config:
+
+```bash
+npm i -g agents-gitflow-guard@0.0.19   # provides the `gitflow-guard` binary
+```
+
+This repo ships project configs at `.claude/settings.json` (Claude Code), `.codex/hooks.json` (Codex), `.opencode/hook/hooks.yaml` (OpenCode) and `.agents/hooks.json` (Antigravity / Google); any other repo adds its own:
 
 ```jsonc
 // Claude Code — .claude/settings.json
 {
   "hooks": {
     "PreToolUse": [
-      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "/abs/path/gitflow-guard check --platform claude" }] }
+      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "gitflow-guard check --platform claude" }] }
     ]
   }
 }
@@ -344,7 +372,7 @@ The package declares `dsh.bundle.patch`, so `dsh plugin add` automatically makes
 {
   "hooks": {
     "PreToolUse": [
-      { "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "node bin/gitflow-guard.mjs check --platform codex" }] }
+      { "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "gitflow-guard check --platform codex" }] }
     ]
   }
 }
@@ -357,7 +385,7 @@ hooks:
     event: tool.before.bash
     actions:
       - bash: |
-          node "$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs" check --platform opencode
+          gitflow-guard check --platform opencode
 ```
 
 ```json
@@ -365,7 +393,7 @@ hooks:
 {
   "gitflow-guard": {
     "PreToolUse": [
-      { "matcher": "run_command", "hooks": [ { "type": "command", "command": "node bin/gitflow-guard.mjs check --platform antigravity" } ] }
+      { "matcher": "run_command", "hooks": [ { "type": "command", "command": "gitflow-guard check --platform antigravity" } ] }
     ]
   }
 }
@@ -379,7 +407,7 @@ hooks:
 Pi loads extensions in-process (no stdin payload, no subprocess hook). Install the shipped entry point into the project and keep the package in devDependencies:
 
 ```bash
-npm i -D agents-gitflow-guard
+npm i -D agents-gitflow-guard@0.0.19
 mkdir -p .pi/extensions
 cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-guard.ts
 ```
@@ -392,7 +420,7 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 
 - The hook reads the payload on stdin and answers with that platform's protocol: Claude Code / OpenCode → `exit 2` (stderr is the reason + "next step" hint); Codex → JSON `{"hookSpecificOutput":{"permissionDecision":"deny",...}}` on stdout; Antigravity → JSON `{"decision":"deny","reason":...}` on stdout with `exit 0` (Antigravity requires exit 0 and rejects `hookSpecificOutput` / non-allow values). Pi has no stdin protocol: the in-process extension listens to the official `tool_call` event and denies via its return value `{ block: true, reason }` (the CLI subprocess only speaks the internal exit-2 contract).
 - Only the pre-tool event is needed: the guard blocks *before* the command runs. There is no permit to consume afterwards, so no post-tool hooks are required.
-- Use an **absolute path** to the binary — hook subprocesses may not inherit your shell `PATH`. `${CLAUDE_PROJECT_DIR}/bin/gitflow-guard.mjs` (Claude Code), `node bin/gitflow-guard.mjs` (Codex, runs from the project working directory), or `$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs` (OpenCode) or `node bin/gitflow-guard.mjs` (Antigravity, relative to the workspace `.agents/` dir) also work from a checkout.
+- The examples above call the globally-installed `gitflow-guard` (`npm i -g`). If a hook subprocess can't see it on its `PATH`, point at the full binary path from `npm bin -g` — hook subprocesses may not inherit your interactive shell `PATH`. The `bin/gitflow-guard.mjs` paths in this repo's shipped configs only work from a checkout.
 - Fully opt-in: the hook does nothing unless the repo has `gitflow-guard.config.json` with `enabled: true`.
 
 ---
@@ -417,7 +445,7 @@ No. Add only the roles your flow actually has. A solo repo with just `develop` c
 
 No, and it is important that you don't treat it as one. It is a workflow guard: it makes an agreed process mechanically enforceable. Text-based command recognition is inherently best-effort — an agent determined to obfuscate a command can slip past the parser.
 
-Within its supported command forms, the role boundary is enforced locally: merging into a protected role branch (integration / preview / production / archive) requires the configured path (PR/MR, or a human merge for production/archive). Standard obfuscation wrappers are classified and blocked — shell wrappers (`sh -c` / `bash -lc`), subshells and backtick/`$()` nesting, `env`/`command`/`nohup`/`xargs` prefixes and `VAR=x` assignments, absolute paths, pipelines and `||` tails, git global options (`-C .`, `--git-dir=…`), wildcard refspecs (`refs/heads/*:refs/heads/*`), `git pull` used as fetch+merge, and the `send-pack`/`update-ref` plumbing. The executable adversarial corpus lives in `tests/accuracy-audit.spec.ts`.
+Within its supported command forms, the role boundary is enforced locally: merging into a protected role branch (integration / preview / production / archive) requires the configured path (PR/MR, or a human merge for production/archive). Standard obfuscation wrappers are classified and blocked — shell wrappers (`sh -c` / `bash -lc`), subshells and backtick/`$()` nesting, `env`/`command`/`nohup`/`xargs`/`sudo` prefixes and `VAR=x` assignments, absolute paths, pipelines and `||` tails, git global options (`-C .`, `--git-dir=…`), wildcard refspecs (`refs/heads/*:refs/heads/*`), `git pull` used as fetch+merge, and the `send-pack`/`update-ref`/`symbolic-ref` plumbing; force-recreating a protected branch (`checkout -B`/`switch -C`) and cherry-pick/revert on a protected branch are blocked by the ref-update / ref-move gates. The executable adversarial corpus lives in `tests/accuracy-audit.spec.ts`.
 
 What remains **locally non-defensible**: direct forge-API calls (`gh api repos/…/pulls/N/merge`, `curl`) and commands inside interpreter subprocesses (`node -e "child_process.exec('git push …')"`); arbitrarily deep quoting or encoding stays best-effort by nature. The real, non-bypassable boundary lives in branch-protection rules on your hosting service. Use both — treat this guard as instant feedback and audit trail, not as a security boundary.
 

package/README.zh.md

@@ -35,16 +35,26 @@
 
 ## 快速开始——30 秒用上
 
-**第 1 步——安装**,然后重启 DSH(插件在进程启动时加载):
+**第 1 步——安装**。六个客户端吃同一个 npm 包 `agents-gitflow-guard`,按你的 agent 选一条:
 
 ```bash
-# 安装最新版
-dsh plugin --profile web add agents-gitflow-guard
-# ...或锁定已知良好版本(推荐; 同时绕开 registry 陈旧缓存)
-dsh plugin --profile web add agents-gitflow-guard@0.0.17
+# DSH —— 进程内插件(装完重启 DSH; 插件在进程启动时加载)
+dsh plugin --profile web add agents-gitflow-guard@0.0.19
 ```
 
-> **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
+```bash
+# Claude Code · Codex · OpenCode · Antigravity —— 独立 hook,不需要 DSH
+npm i -g agents-gitflow-guard@0.0.19
+```
+
+```bash
+# Pi —— 进程内扩展
+npm i -D agents-gitflow-guard@0.0.19
+```
+
+> **版本坑**: 裸 `add` 或不带版本的 `npm i` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。(DSH 用户: pnpm 打印的 peer 依赖 *警告* 属预期——DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`,插件正常工作。)
+>
+> hook 客户端(Claude Code · Codex · OpenCode · Antigravity)和 Pi 装完还要各做一步接线——见[安装详解](#安装详解)的逐客户端表。
 
 **第 2 步——配置**,在**项目根目录**创建 `gitflow-guard.config.json`:
 
@@ -290,6 +300,12 @@ archive(可选, 发布后你亲手归档)
 | 指向 archive 的 PR/MR | ✅ 可创建;🚫 合并被拦(你在 UI 合并) |
 | 在 integration / preview 上 `git merge feature/x`(本地) | 🚫 拦(须 PR/MR);`update: flexible` 则放行 |
 | 串联命令(`checkout develop && merge feature/x`) | 🚫 拦——逐段模拟分支切换,无法绕序 |
+| 强制重建受保护分支(`git checkout -B/-C <分支>` / `git switch -C`) | 🚫 拦(直改 ref-update 门禁) |
+| 用 `git symbolic-ref` 重定向/删除受保护分支 | 🚫 拦(直改 ref-update 门禁) |
+| 在 integration / preview / production / archive 上 `git cherry-pick` / `git revert` | 🚫 拦(受保护分支上改写历史);`-n`/`--no-commit` 与 `--abort`/`--continue`/`--skip`/`--quit` 放行 |
+| `sudo` 包装的 git 命令(特权外壳) | 🚫 剥壳(含 `sudo -u …`)后按内层命令判定 |
+
+> 两处**刻意不拦**的边界,防止后来者「顺手堵上」造成语义回归:`git tag -f` 移动 tag(即使指向受保护分支)维持豁免——tag 不在分支角色守卫范围,与 `push --tags` 同型;受保护分支上的普通 `git commit` 维持放行——守卫只管分支角色与合入路径、不管内容,后续 `git push` 仍被拦(远端零污染)。
 
 PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有平台 CLI 时插件走保守路径。
 
@@ -303,12 +319,18 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 ---
 ## 安装详解
 
-**前置**:一个可用的 [DSH](https://github.com/deepseek-ai/deepseek-harness) 安装,且 `PATH` 上有 **Node.js ≥ 22**(与包 `engines` 及 CI 矩阵最低档一致——独立 hook 用户不经 npm 安装,同样需要运行时)。
+**前置**:`PATH` 上有 **Node.js ≥ 22**(与包 `engines` 及 CI 矩阵最低档一致)。所有客户端都吃**同一个 npm 包** `agents-gitflow-guard`——只有挂载步骤不同。
 
-**从 npm registry**——标准路径,已在[快速开始](#快速开始30-秒用上)覆盖:
+| 客户端 | 安装命令 | 装完再做什么 |
+|---|---|---|
+| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.19` | 重启 DSH——插件自动挂为 profile 层 |
+| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.19` | 在各自 hook 配置里指向 `gitflow-guard` 二进制(见下) |
+| Pi | `npm i -D agents-gitflow-guard@0.0.19` | 把 `pi/gitflow-guard.ts` 拷进 `.pi/extensions/`(见下) |
+
+**DSH —— 进程内插件**(标准路径,已在[快速开始](#快速开始30-秒用上)覆盖):
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.17    # 建议锁版本, 见上文提示
+dsh plugin --profile web add agents-gitflow-guard@0.0.19    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -322,14 +344,20 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 
 包自带 `dsh.bundle.patch` 声明,`dsh plugin add` 自动把它挂为 profile 层,无需手工编辑 profile。
 
-**各 agent 独立 hook**——同一守卫也能在这些 agent 里跑,不依赖 DSH。本仓库已自带 `.claude/settings.json`(Claude Code)、`.codex/hooks.json`(Codex)、`.opencode/hook/hooks.yaml`(OpenCode)、`.agents/hooks.json`(Antigravity / Google)和 `.pi/settings.json` + `.pi/extensions/gitflow-guard.ts`(Pi);其他仓库加自己的 hooks:
+**各 agent 独立 hook**——Claude Code / Codex / OpenCode / Antigravity,不依赖 DSH。全局装一次 CLI,然后引用 `gitflow-guard` 二进制:
+
+```bash
+npm i -g agents-gitflow-guard@0.0.19   # 提供 `gitflow-guard` 二进制
+```
+
+本仓库已自带 `.claude/settings.json`(Claude Code)、`.codex/hooks.json`(Codex)、`.opencode/hook/hooks.yaml`(OpenCode)和 `.agents/hooks.json`(Antigravity / Google);其他仓库加自己的 hooks:
 
 ```jsonc
 // Claude Code — .claude/settings.json
 {
   "hooks": {
     "PreToolUse": [
-      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "/abs/path/gitflow-guard check --platform claude" }] }
+      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "gitflow-guard check --platform claude" }] }
     ]
   }
 }
@@ -340,7 +368,7 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 {
   "hooks": {
     "PreToolUse": [
-      { "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "node bin/gitflow-guard.mjs check --platform codex" }] }
+      { "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "gitflow-guard check --platform codex" }] }
     ]
   }
 }
@@ -353,7 +381,7 @@ hooks:
     event: tool.before.bash
     actions:
       - bash: |
-          node "$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs" check --platform opencode
+          gitflow-guard check --platform opencode
 ```
 
 ```json
@@ -361,7 +389,7 @@ hooks:
 {
   "gitflow-guard": {
     "PreToolUse": [
-      { "matcher": "run_command", "hooks": [ { "type": "command", "command": "node bin/gitflow-guard.mjs check --platform antigravity" } ] }
+      { "matcher": "run_command", "hooks": [ { "type": "command", "command": "gitflow-guard check --platform antigravity" } ] }
     ]
   }
 }
@@ -375,7 +403,7 @@ hooks:
 Pi 以进程内扩展装载(没有 stdin payload,也没有子进程 hook)。把随包发布的入口装进项目、包留在 devDependencies:
 
 ```bash
-npm i -D agents-gitflow-guard
+npm i -D agents-gitflow-guard@0.0.19
 mkdir -p .pi/extensions
 cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-guard.ts
 ```
@@ -388,7 +416,7 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 
 - hook 读 stdin payload,按**各平台协议**作答:Claude Code / OpenCode → `exit 2`(stderr 展示原因 + "下一步"提示);Codex → stdout 输出 JSON `{"hookSpecificOutput":{"permissionDecision":"deny",...}}`;Antigravity → stdout 输出 `{"decision":"deny","reason":...}` 且 **exit 0**(Antigravity 要求 exit 0,拒绝 hookSpecificOutput/非 allow 值)。Pi 没有 stdin 协议:进程内扩展监听官方 `tool_call` 事件,经返回值 `{ block: true, reason }` 拒绝(守卫 CLI 子进程只承载内部 exit-2 契约)。
 - 只需要**执行前事件**:守卫在命令执行*之前*拦截;没有特许可事后消费,因此无需执行后钩子。
-- 用**绝对路径**指向二进制——hook 子进程不一定继承你的 shell PATH。Claude Code 用 `${CLAUDE_PROJECT_DIR}/bin/gitflow-guard.mjs`,Codex 用 `node bin/gitflow-guard.mjs`,OpenCode 用 `$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs`、Antigravity 用 `node bin/gitflow-guard.mjs`(相对 workspace `.agents/` 目录)也可以。
+- 上面示例调的是全局安装的 `gitflow-guard`(`npm i -g`)。若 hook 子进程在它的 `PATH` 里找不到,就指向 `npm bin -g` 给出的完整二进制路径——hook 子进程不一定继承你交互 shell 的 PATH。本仓库自带配置里的 `bin/gitflow-guard.mjs` 路径只对 checkout 贡献者有效。
 - 完全 opt-in:仓库没有 `gitflow-guard.config.json`(或 `enabled` 非 true)时 hook 什么都不做。
 
 ---
@@ -413,7 +441,7 @@ cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-
 
 不是,请注意别把它当安全工具。它是工作流守卫:把既定流程变成可机制执行的东西。基于文本的命令识别天然是尽力而为——铁心混淆命令的 agent 可以绕过解析器。
 
-在其支持的命令形态内,角色边界在本地强制生效:合入受保护角色分支(integration / preview / production / archive)必须走配置好的路径(PR/MR,或生产/归档的人工合并)。常见混淆包装已纳入分类与拦截——shell 包装(`sh -c` / `bash -lc`)、子 shell 与反引号/`$()` 内嵌、`env`/`command`/`nohup`/`xargs` 前缀与 `VAR=x` 赋值、绝对路径、管道与 `||` 后半段、git 全局选项(`-C .`、`--git-dir=…`)、通配 refspec(`refs/heads/*:refs/heads/*`)、当 fetch+merge 用的 `git pull`,以及 `send-pack`/`update-ref` 等 plumbing。可执行对抗语料见 `tests/accuracy-audit.spec.ts`。
+在其支持的命令形态内,角色边界在本地强制生效:合入受保护角色分支(integration / preview / production / archive)必须走配置好的路径(PR/MR,或生产/归档的人工合并)。常见混淆包装已纳入分类与拦截——shell 包装(`sh -c` / `bash -lc`)、子 shell 与反引号/`$()` 内嵌、`env`/`command`/`nohup`/`xargs`/`sudo` 前缀与 `VAR=x` 赋值、绝对路径、管道与 `||` 后半段、git 全局选项(`-C .`、`--git-dir=…`)、通配 refspec(`refs/heads/*:refs/heads/*`)、当 fetch+merge 用的 `git pull`,以及 `send-pack`/`update-ref`/`symbolic-ref` 等 plumbing;强制重建受保护分支(`checkout -B`/`switch -C`)与受保护分支上的 cherry-pick/revert 由 ref-update / ref-move 门禁拦截。可执行对抗语料见 `tests/accuracy-audit.spec.ts`。
 
 已知**本地不可防**的通道:直连 forge API(`gh api repos/…/pulls/N/merge`、`curl`)与解释器子进程内嵌(`node -e "child_process.exec('git push …')"`);任意深度的引号/编码变换天然只能尽力而为。真正不可绕过的边界在你托管服务的分支保护设置。两边都用——把本守卫当作即时反馈与审计留痕,而不是安全边界。
 

package/lib/cli.mjs

@@ -1,4 +1,4 @@
-import { _ as resolveLocale, d as gitRunner, f as loadConfig, h as makeT, i as formatDeny, l as currentBranch, o as stateDir, p as roleMatches, r as evaluateCommand, u as findRepoRoot, v as classify } from "./src-BQYC4N6b.mjs";
+import { _ as resolveLocale, d as gitRunner, f as loadConfig, h as makeT, i as formatDeny, l as currentBranch, o as stateDir, p as roleMatches, r as evaluateCommand, u as findRepoRoot, v as classify } from "./src-CL6uB3oo.mjs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts

package/lib/index.mjs

@@ -1,2 +1,2 @@
-import { a as name, c as createPiExtension, g as registerLocale, i as formatDeny, m as MESSAGE_KEYS, n as apply, o as stateDir, r as evaluateCommand, s as userStateRoot, t as appendAudit } from "./src-BQYC4N6b.mjs";
+import { a as name, c as createPiExtension, g as registerLocale, i as formatDeny, m as MESSAGE_KEYS, n as apply, o as stateDir, r as evaluateCommand, s as userStateRoot, t as appendAudit } from "./src-CL6uB3oo.mjs";
 export { MESSAGE_KEYS, appendAudit, apply, createPiExtension, evaluateCommand, formatDeny, name, registerLocale, stateDir, userStateRoot };

package/lib/{src-BQYC4N6b.mjs → src-CL6uB3oo.mjs}

@@ -119,10 +119,12 @@ function classifySegment(segment, ctx) {
 }
 /** 分派: 已知命令直接解析; 包装器剥壳后递归(token 只减不增, 必然终止) */
 function classifyTokens(tokens, ctx) {
+	if (tokens.length === 0) return [{ kind: "other" }];
 	const rawCmd = tokens[0];
 	const cmd = rawCmd.includes("/") ? rawCmd.slice(rawCmd.lastIndexOf("/") + 1) : rawCmd;
 	if (SHELLS.has(cmd)) return classifyShellWrapped(tokens, ctx);
 	if (cmd === "env") return classifyTokens(stripEnvArgs(tokens.slice(1)), ctx);
+	if (cmd === "sudo") return classifyTokens(stripSudoArgs(tokens.slice(1)), ctx);
 	if (WRAPPERS.has(cmd)) return classifyTokens(stripWrapperArgs(tokens.slice(1)), ctx);
 	if (/^[\w-][\w.-]*=/.test(rawCmd)) return classifyTokens(tokens.slice(1), ctx);
 	if (cmd === "git") return classifyGit(tokens.slice(1), ctx);
@@ -168,6 +170,35 @@ function stripWrapperArgs(args) {
 	while (i < args.length && (args[i].startsWith("-") || /^\d+$/.test(args[i]) || /^[\w-]+=/.test(args[i]))) i++;
 	return args.slice(i);
 }
+/**
+* sudo 参数剥离: 旗标与 VAR=x 赋值逐个消费; -u/-g/-p(及长旗标)消费下一个参数;
+* `--` 之后即命令本体。仅剥壳不出新语义, 递归分类必然终止。
+*/
+function stripSudoArgs(args) {
+	const WITH_VALUE = /* @__PURE__ */ new Set([
+		"-u",
+		"--user",
+		"-g",
+		"--group",
+		"-p",
+		"--prompt"
+	]);
+	let i = 0;
+	while (i < args.length) {
+		const a = args[i];
+		if (a === "--") return args.slice(i + 1);
+		if (WITH_VALUE.has(a)) {
+			i += args[i + 1] != null ? 2 : 1;
+			continue;
+		}
+		if (a.startsWith("-") || /^[\w-]+=/.test(a)) {
+			i++;
+			continue;
+		}
+		break;
+	}
+	return args.slice(i);
+}
 /** 分词: 引号内的空格不拆分 */
 function tokenize(segment) {
 	return segment.match(/"[^"]*"|'[^']*'|\S+/g)?.map((t) => t.replace(/^['"]|['"]$/g, "")) ?? [];
@@ -181,6 +212,8 @@ function classifyGit(args, ctx) {
 	if (sub === "checkout" || sub === "switch") return parseCheckout(rest);
 	if (sub === "send-pack") return parseSendPack(rest);
 	if (sub === "update-ref") return parseUpdateRef(rest);
+	if (sub === "symbolic-ref") return parseSymbolicRef(rest);
+	if (sub === "cherry-pick" || sub === "revert") return parseCherryPickLike(rest);
 	if (sub === "reset" || sub === "filter-branch") return [{ kind: "ref-move" }];
 	if (sub === "rebase") return parseRebase(rest);
 	if (sub === "commit") return parseCommit(rest);
@@ -203,6 +236,21 @@ function parseCommit(args) {
 	if (args.some((a) => a === "--amend")) return [{ kind: "ref-move" }];
 	return [{ kind: "other" }];
 }
+/**
+* cherry-pick/revert 会在当前分支上新提交 → 改写当前 tip, 收编为 ref-move
+* (受保护分支上拒绝, 与 reset/rebase 同型);
+* -n/--no-commit 只改工作树与索引(不移动 tip)与恢复类旗标(abort/continue 等)放行。
+*/
+function parseCherryPickLike(args) {
+	const RESUME = /* @__PURE__ */ new Set([
+		"--abort",
+		"--continue",
+		"--skip",
+		"--quit"
+	]);
+	if (args.some((a) => a === "-n" || a === "--no-commit" || RESUME.has(a))) return [{ kind: "other" }];
+	return [{ kind: "ref-move" }];
+}
 /** 剥离子命令前的全局选项(-C <path> / -c <k=v> / --git-dir 等), 否则 git -C . push 会被判 other */
 function stripGlobalOptions(args) {
 	const WITH_VALUE = /* @__PURE__ */ new Set([
@@ -238,20 +286,44 @@ function stripGlobalOptions(args) {
 	}
 	return args.slice(i);
 }
-/** 分支切换: 门禁放行, 分支状态由 evaluateCommand 按段模拟 */
+/**
+* 分支切换: 普通切换/-b/-c(switch -c)新建 → checkout(放行, 分支状态由 evaluateCommand 模拟);
+* -B/-C 强制重建会静默移动/重建既有 ref(可波及受保护分支), 目标名单独送 ref-update 门禁,
+* 门禁放行后仍按 checkout 模拟切换(两段任一 deny 即整体拦截, 与 push 歧义双解释同机制)。
+* 短旗标簇(-Bf/-bt 等)扫描 b/B/c/C 视同对应形态。
+*/
 function parseCheckout(args) {
 	const first = args[0];
 	if (first === "--") return [{
 		kind: "checkout",
 		branch: null
 	}];
+	const name = args[1];
+	const validName = name != null && !name.startsWith("-");
 	if (first === "-b" || first === "-B" || first === "-c" || first === "-C") {
-		const name = args[1];
+		if (!validName) return [{
+			kind: "checkout",
+			branch: null
+		}];
+		if (first === "-B" || first === "-C") return forceRecreateOut(name);
 		return [{
 			kind: "checkout",
-			branch: name && !name.startsWith("-") ? name : null
+			branch: name
 		}];
 	}
+	if (first != null && first.startsWith("-") && !first.startsWith("--") && first.length > 1) {
+		const clusterForce = first.includes("B") || first.includes("C");
+		if (clusterForce || first.includes("b") || first.includes("c")) {
+			if (!validName) return [{
+				kind: "checkout",
+				branch: null
+			}];
+			return clusterForce ? forceRecreateOut(name) : [{
+				kind: "checkout",
+				branch: name
+			}];
+		}
+	}
 	if (first && !first.startsWith("-")) return [{
 		kind: "checkout",
 		branch: first
@@ -261,6 +333,17 @@ function parseCheckout(args) {
 		branch: null
 	}];
 }
+/** -B/-C(及含 B/C 的旗标簇)的产出: 目标 ref 送 ref-update, 再按 checkout 模拟切换 */
+function forceRecreateOut(name) {
+	return [{
+		kind: "ref-update",
+		branch: stripRefPrefix(name),
+		delete: false
+	}, {
+		kind: "checkout",
+		branch: name
+	}];
+}
 function parsePush(args, ctx) {
 	let force = false;
 	let isDelete = false;
@@ -404,6 +487,36 @@ function parseUpdateRef(args) {
 	}
 	return [{ kind: "other" }];
 }
+/**
+* git symbolic-ref 直改 symbolic refs(plumbing 绕行面):
+* - 查询形态(symbolic-ref <name> / --short 等单参)不改变任何 ref → other;
+* - 双参重定向(symbolic-ref <name> <ref>)把 name 指向别处, 目标名送 ref-update;
+* - -d/--delete 删除该 ref, 同样送 ref-update。
+*/
+function parseSymbolicRef(args) {
+	let isDelete = false;
+	const nonFlag = [];
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (a === "-d" || a === "--delete") {
+			isDelete = true;
+			continue;
+		}
+		if (a === "-m" || a === "--message") {
+			i++;
+			continue;
+		}
+		if (a.startsWith("-")) continue;
+		nonFlag.push(a);
+	}
+	if (!isDelete && nonFlag.length < 2) return [{ kind: "other" }];
+	if (isDelete && nonFlag.length === 0) return [{ kind: "other" }];
+	return [{
+		kind: "ref-update",
+		branch: stripRefPrefix(nonFlag[0]),
+		delete: isDelete
+	}];
+}
 function parseMerge(args) {
 	if (args.some((a) => a === "--abort")) return [{ kind: "other" }];
 	return [{
@@ -526,9 +639,9 @@ const en = {
 	"head.unknown": () => "current branch",
 	"denyDeleteOrForce.why": (v) => `Protected branch "${v.branch}" may not be deleted or force-pushed`,
 	"denyDeleteOrForce.next": () => "Delete/force-push on a feature branch outside the protected branches; protected branches are managed by you.",
-	"refUpdateProtected.why": (v) => `Protected branch "${v.branch}" forbids direct ref updates (update-ref)`,
+	"refUpdateProtected.why": (v) => `Protected branch "${v.branch}" forbids direct ref updates (update-ref / symbolic-ref / branch -m|-f / checkout -B)`,
 	"refUpdateProtected.next": () => "Update protected branches via PR/MR; they are managed by you.",
-	"refMoveProtected.why": () => "Rewriting history on a protected branch (reset / rebase / commit --amend / filter-branch) is not allowed",
+	"refMoveProtected.why": () => "Rewriting history on a protected branch (reset / rebase / commit --amend / filter-branch / cherry-pick / revert) is not allowed",
 	"refMoveProtected.next": () => "Do history rewrites on a feature branch; protected branches advance via PR/MR and are managed by you.",
 	"pushAll.why": () => "--all/--mirror push would include protected branches",
 	"pushAll.next": () => "Push branch by branch with an explicit refspec.",
@@ -603,9 +716,9 @@ const zh = {
 	"head.unknown": () => "当前分支",
 	"denyDeleteOrForce.why": (v) => `受保护分支「${v.branch}」禁止删除或强推`,
 	"denyDeleteOrForce.next": () => "删除/强推请到受保护分支外的 feature 分支上操作; 受保护分支由用户亲手管理",
-	"refUpdateProtected.why": (v) => `受保护分支「${v.branch}」禁止直接改写 refs(update-ref)`,
+	"refUpdateProtected.why": (v) => `受保护分支「${v.branch}」禁止直接改写 refs(update-ref / symbolic-ref / branch -m|-f / checkout -B)`,
 	"refUpdateProtected.next": () => "请通过 PR/MR 更新受保护分支; 受保护分支由用户亲手管理",
-	"refMoveProtected.why": () => "受保护分支禁止本地改写历史(reset / rebase / commit --amend / filter-branch)",
+	"refMoveProtected.why": () => "受保护分支禁止本地改写历史(reset / rebase / commit --amend / filter-branch / cherry-pick / revert)",
 	"refMoveProtected.next": () => "历史改写请在 feature 分支上进行; 受保护分支仅经 PR/MR 推进, 由用户亲手管理",
 	"pushAll.why": () => "--all/--mirror 推送会包含受保护分支",
 	"pushAll.next": () => "请逐分支推送并显式指定 refspec",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity / Pi) — integration/preview/production/archive, each with its own update rules",
   "license": "MIT",
   "type": "module",