agents-gitflow-guard 0.0.20 → 0.0.22

package/README.md

@@ -40,17 +40,17 @@ You define your own branches —
 
 ```bash
 # DSH — in-process plugin; restart DSH afterwards (plugins load at startup)
-dsh plugin --profile web add agents-gitflow-guard@0.0.20
+dsh plugin --profile web add agents-gitflow-guard@0.0.22
 ```
 
 ```bash
 # Claude Code · Codex · OpenCode · Antigravity — standalone hooks, no DSH needed
-npm i -g agents-gitflow-guard@0.0.20
+npm i -g agents-gitflow-guard@0.0.22
 ```
 
 ```bash
 # Pi — in-process extension
-npm i -D agents-gitflow-guard@0.0.20
+npm i -D agents-gitflow-guard@0.0.22
 ```
 
 > **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.)
@@ -68,7 +68,7 @@ gitflow-guard wire --client claude --project --yes
 # Codex / OpenCode / Antigravity (each its own config file; --yes skips the y/N prompt)
 gitflow-guard wire --client codex --project --yes
 gitflow-guard wire --client opencode --project --yes
-gitflow-guard wire --client antigravity --project --yes     # experimental
+gitflow-guard wire --client antigravity --project --yes
 ```
 
 ```bash
@@ -82,14 +82,14 @@ gitflow-guard setup
 
 > ⚠️ **main is protected by default.** Trunk / single-branch users (everyone pushes straight to one branch) will get blocked on direct `main` pushes until they opt out — create `gitflow-guard.config.json` with `{ "enabled": false }`, or map your own branches (see [Configuration Reference](#configuration-reference)). `gitflow-guard status` repeats this notice whenever the built-in defaults are in effect.
 
-**Step 3 — verify.** Ask the agent (or run in a DSH session) to `git push origin develop`. Expect the tool call to be denied:
+**Step 3 — verify.** Ask the agent to `git push origin develop`. Expect the tool call to be denied:
 
 ```text
 Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
 Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
 ```
 
-Messages are English by default; create a config with `"locale": "zh"` to switch to Chinese (see [Configuration Reference](#configuration-reference)).
+Messages are English by default; create a config with `"locale": "zh"` to switch to Chinese — messages then read like: *已拦截:受保护分支「develop」禁止直推 / 下一步:集成分支(develop)由 PR/MR 合入 feature……* (see [Configuration Reference](#configuration-reference)).
 
 **Done.** The guard is live for this repo with the built-in defaults. Want more stages (`preview` / `production`) or different branch names? Write a `gitflow-guard.config.json` and only the fields you care about — everything else keeps the built-in defaults. For the full decision table, see the [Gate Matrix](#gate-matrix--what-gets-blocked-what-passes).
 
@@ -356,14 +356,14 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 
 | Agent | Install command | After that |
 |---|---|---|
-| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.20` | restart DSH — the plugin auto-mounts as a profile layer |
-| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.20` | `gitflow-guard wire --client <name>` — one command per client (below) |
-| Pi | `npm i -D agents-gitflow-guard@0.0.20` | copy `pi/gitflow-guard.ts` into `.pi/extensions/` (below) |
+| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.22` | restart DSH — the plugin auto-mounts as a profile layer |
+| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.22` | `gitflow-guard wire --client <name>` — one command per client (below) |
+| Pi | `npm i -D agents-gitflow-guard@0.0.22` | 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.20    # pin recommended, see note above
+dsh plugin --profile web add agents-gitflow-guard@0.0.22    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -380,11 +380,11 @@ The package declares `dsh.bundle.patch`, so `dsh plugin add` automatically makes
 **Standalone agent hooks** — Claude Code / Codex / OpenCode / Antigravity, no DSH required. Install the CLI once, then wire one client per command (the guard is on by default via its built-in config, so wiring is all that remains):
 
 ```bash
-npm i -g agents-gitflow-guard@0.0.20   # provides the `gitflow-guard` binary
+npm i -g agents-gitflow-guard@0.0.22   # provides the `gitflow-guard` binary
 gitflow-guard wire --client claude --project --yes
 gitflow-guard wire --client codex --project --yes
 gitflow-guard wire --client opencode --project --yes
-gitflow-guard wire --client antigravity --project --yes   # experimental
+gitflow-guard wire --client antigravity --project --yes
 ```
 
 `wire` reads the existing config file (if any), merges the hook entry in without touching anything else, is idempotent (already wired → skipped), supports `--dry-run` to preview and `--unwire` to remove, and asks before touching `--global` files. The exact files it writes (for reference, and for hand-writing instead of `wire`) are:
@@ -411,18 +411,18 @@ gitflow-guard wire --client antigravity --project --yes   # experimental
 }
 ```
 
-```yaml
-# OpenCode — .opencode/hook/hooks.yaml
-hooks:
-  - id: gitflow-guard
-    event: tool.before.bash
-    actions:
-      - bash: |
-          gitflow-guard check --platform opencode
+```ts
+// OpenCode — `.opencode/plugins/gitflow-guard.ts` (copy of the shipped `opencode/gitflow-guard.ts`;
+// OpenCode 1.18+ dropped hooks.yaml, the extension point is now plugins — `tool.execute.before`,
+// deny = throwing; `wire --client opencode` copies the file for you)
 ```
+`gitflow-guard wire --client opencode` writes this file from the package; hand-write only if you know what you are doing.
 
 ```json
 // Antigravity (Google) — .agents/hooks.json
+// (Antigravity hook processes run with cwd = the config file's directory, so a relative
+// bin/… path breaks; `wire` writes an absolute path for project scope, `gitflow-guard`
+// from PATH for global scope. Shown here: globally-installed form.)
 {
   "gitflow-guard": {
     "PreToolUse": [
@@ -440,7 +440,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@0.0.20
+npm i -D agents-gitflow-guard@0.0.22
 mkdir -p .pi/extensions
 cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-guard.ts
 ```
@@ -535,7 +535,7 @@ If it saves your team from a shortcut gone wrong, the coffee button at the top o
 | **integration** | the core role (built-in default: `develop`); features merge in via PR/MR; protected |
 | **preview** | optional env-endpoint branches (`branches.preview`, array); updates via PR/MR only |
 | **production** | optional production branches (`branches.production`, array); PR/MR + merge by user only |
-| **archive** | optional post-release archive branch (`branches.archive`); user-hand only |
+| **archive** | optional post-release archive branch (`branches.archive`, array); agents may create PR/MRs into it, but the merge stays user-hand only |
 | **feature branch** | your working branch, matched by `featurePattern`; free zone |
 | **gate matrix** | the decision table mapping each classified command to allow/deny |
 | **pre-execute** | the tool-pipeline hook where denial happens — before the command runs |
@@ -545,10 +545,18 @@ If it saves your team from a shortcut gone wrong, the coffee button at the top o
 
 ## Roadmap
 
-- **i18n — localized block messages** ✅ (0.0.3): English by default, `"locale": "zh"` for Chinese.
-- **v2 — audit sync**: sync the user-level audit log across machines (audit is local-only today).
-- **v2 — more pre-built templates**: ready-made config templates for common flows (solo `develop`, multi-env enterprise) as community-contributed presets.
-- **v2 — CI hard-gating research**: whether `pr checks` could become a real gate without hurting the platform-agnostic core.
+**Shipped**:
+
+- ✅ **i18n — localized block messages** (0.0.3): English by default, `"locale": "zh"` for Chinese; custom locales via `registerLocale` since 0.0.12.
+- ✅ **Zero-config onboarding** (0.0.20): built-in `develop` + `main` defaults, deep-merge override, guard on by default with no config file.
+- ✅ **One-command wiring** (0.0.20): `gitflow-guard wire` / `setup` writes each stdin-hook client's hook entry (Claude Code / Codex / OpenCode / Antigravity).
+- ✅ **Six platforms** (0.0.2–0.0.17): DSH (in-process), Claude Code, Codex, OpenCode, Antigravity, Pi (in-process).
+
+**v2 (open)**:
+
+- **audit sync**: sync the user-level audit log across machines (audit is local-only today; since 0.0.14 it lives outside the repository).
+- **more pre-built templates**: extend the built-in defaults with ready-made presets for common flows (solo `develop`, multi-env enterprise) as community-contributed configs.
+- **CI hard-gating research**: whether `pr checks` could become a real gate without hurting the platform-agnostic core.
 
 Contributions welcome — see [Development](#development).
 
@@ -566,9 +574,10 @@ The plugin is free and open source (MIT). If it saves you and your team from a s
 
 ```bash
 npm install
-npm test          # unit tests: classify / gate / config / cli / repo / platform / i18n / index / accuracy-audit
+npm test          # unit tests: classify / gate / config / cli / repo / platform / i18n / index / accuracy-audit / pi
 npm run typecheck     # tsc --noEmit, 0 errors
 npm run build         # tsdown → lib/ (CLI and plugin share the build)
+npm run check:pins    # assert package.json version matches every README lock-version pin and the CHANGELOG heading
 npm run verify:matrix # continuous cross-agent regression: DSH logic + zh-locale regression + Claude Code / Codex / OpenCode / Antigravity hook wiring + Pi extension
 ```
 

package/README.zh.md

@@ -39,17 +39,17 @@
 
 ```bash
 # DSH —— 进程内插件(装完重启 DSH; 插件在进程启动时加载)
-dsh plugin --profile web add agents-gitflow-guard@0.0.20
+dsh plugin --profile web add agents-gitflow-guard@0.0.22
 ```
 
 ```bash
 # Claude Code · Codex · OpenCode · Antigravity —— 独立 hook,不需要 DSH
-npm i -g agents-gitflow-guard@0.0.20
+npm i -g agents-gitflow-guard@0.0.22
 ```
 
 ```bash
 # Pi —— 进程内扩展
-npm i -D agents-gitflow-guard@0.0.20
+npm i -D agents-gitflow-guard@0.0.22
 ```
 
 > **版本坑**: 裸 `add` 或不带版本的 `npm i` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。(DSH 用户: pnpm 打印的 peer 依赖 *警告* 属预期——DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`,插件正常工作。)
@@ -67,7 +67,7 @@ gitflow-guard wire --client claude --project --yes
 # Codex / OpenCode / Antigravity(各写各的配置文件; --yes 跳过 y/N 确认)
 gitflow-guard wire --client codex --project --yes
 gitflow-guard wire --client opencode --project --yes
-gitflow-guard wire --client antigravity --project --yes     # 实验支持
+gitflow-guard wire --client antigravity --project --yes
 ```
 
 ```bash
@@ -115,7 +115,9 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 
 **这是软规则。** Agent 会跳过、重排、干脆"忘记"它——不是因为恶意,而是因为软指令对模型来说本来就是可选的。
 
-这个插件把软规则变成**硬机制**。agent 每次尝试的 git 操作都会对照*本地仓库的真实状态*检查;违规在命令执行前就被拦截,并给出原因和下一步。没人需要记得规则——规则被强制执行。
+这个插件把软规则变成**硬机制**。agent 每次尝试的 git 操作都会对照*本地仓库的真实状态*检查;违规在命令执行前就被拦截,并给出原因和下一步。
+
+没人需要记得规则——规则被强制执行。
 
 ---
 
@@ -352,14 +354,14 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 
 | 客户端 | 安装命令 | 装完再做什么 |
 |---|---|---|
-| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.20` | 重启 DSH——插件自动挂为 profile 层 |
-| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.20` | `gitflow-guard wire --client <名>`——每个客户端一条命令(见下) |
-| Pi | `npm i -D agents-gitflow-guard@0.0.20` | 把 `pi/gitflow-guard.ts` 拷进 `.pi/extensions/`(见下) |
+| DSH | `dsh plugin --profile web add agents-gitflow-guard@0.0.22` | 重启 DSH——插件自动挂为 profile 层 |
+| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard@0.0.22` | `gitflow-guard wire --client <名>`——每个客户端一条命令(见下) |
+| Pi | `npm i -D agents-gitflow-guard@0.0.22` | 把 `pi/gitflow-guard.ts` 拷进 `.pi/extensions/`(见下) |
 
 **DSH —— 进程内插件**(标准路径,已在[快速开始](#快速开始30-秒用上)覆盖):
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.20    # 建议锁版本, 见上文提示
+dsh plugin --profile web add agents-gitflow-guard@0.0.22    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -376,11 +378,11 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 **各 agent 独立 hook**——Claude Code / Codex / OpenCode / Antigravity,不依赖 DSH。全局装一次 CLI,然后**每客户端一条命令接线**(守卫凭内置默认配置已默认开启,接线是唯一剩下的事):
 
 ```bash
-npm i -g agents-gitflow-guard@0.0.20   # 提供 `gitflow-guard` 二进制
+npm i -g agents-gitflow-guard@0.0.22   # 提供 `gitflow-guard` 二进制
 gitflow-guard wire --client claude --project --yes
 gitflow-guard wire --client codex --project --yes
 gitflow-guard wire --client opencode --project --yes
-gitflow-guard wire --client antigravity --project --yes   # 实验支持
+gitflow-guard wire --client antigravity --project --yes
 ```
 
 `wire` 读取已有配置文件(如有)并把 hook 条目合入——不碰其他内容、幂等(已接则跳过)、支持 `--dry-run` 预览与 `--unwire` 移除、写 `--global` 前必先询问。它写入的准确文件(供参考,也可代替 `wire` 手写)是:
@@ -407,18 +409,17 @@ gitflow-guard wire --client antigravity --project --yes   # 实验支持
 }
 ```
 
-```yaml
-# OpenCode — .opencode/hook/hooks.yaml
-hooks:
-  - id: gitflow-guard
-    event: tool.before.bash
-    actions:
-      - bash: |
-          gitflow-guard check --platform opencode
+```ts
+// OpenCode — `.opencode/plugins/gitflow-guard.ts`(随包 `opencode/gitflow-guard.ts` 的副本;
+// OpenCode 1.18+ 已移除 hooks.yaml,扩展点改为 plugins —— `tool.execute.before` 事件,
+// 拒绝语义 = 抛错; `wire --client opencode` 自动复制该文件)
 ```
+`gitflow-guard wire --client opencode` 会从包内写入此文件;非必要不建议手写。
 
 ```json
 // Antigravity (Google) — .agents/hooks.json
+// (agy hook 进程 cwd = hook 配置文件所在目录,相对 bin/… 会解析失败; `wire` 项目级写绝对路径、
+// 全局写 PATH 上的 gitflow-guard。此处展示全局安装形态。)
 {
   "gitflow-guard": {
     "PreToolUse": [
@@ -436,7 +437,7 @@ hooks:
 Pi 以进程内扩展装载(没有 stdin payload,也没有子进程 hook)。把随包发布的入口装进项目、包留在 devDependencies:
 
 ```bash
-npm i -D agents-gitflow-guard@0.0.20
+npm i -D agents-gitflow-guard@0.0.22
 mkdir -p .pi/extensions
 cp node_modules/agents-gitflow-guard/pi/gitflow-guard.ts .pi/extensions/gitflow-guard.ts
 ```
@@ -541,10 +542,18 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 
 ## 路线图
 
-- **i18n——拦截文案本地化** ✅(0.0.3):默认英文,`"locale": "zh"` 切中文。
-- **v2——审计同步**:跨机器同步用户级审计日志(现仅本地)。
-- **v2——更多预制模板**:常用流程(solo `develop`、多环境企业)的现成配置模板,由社区贡献。
-- **v2——CI 硬门槛研究**:`pr checks` 能否在不伤平台无关核心的前提下变成真实门槛。
+**已落地**:
+
+- ✅ **i18n——拦截文案本地化**(0.0.3):默认英文,`"locale": "zh"` 切中文;0.0.12 起支持 `registerLocale` 自定义语言。
+- ✅ **零配置开箱**(0.0.20):内置 `develop` + `main` 默认配置、深度合并覆盖,无配置文件也默认开启守卫。
+- ✅ **一键接线**(0.0.20):`gitflow-guard wire` / `setup` 一条命令写入各 stdin-hook 客户端(Claude Code / Codex / OpenCode / Antigravity)的 hook 条目。
+- ✅ **六个平台**(0.0.2–0.0.17):DSH(进程内)、Claude Code、Codex、OpenCode、Antigravity、Pi(进程内)。
+
+**v2 规划中**:
+
+- **审计同步**:跨机器同步用户级审计日志(现仍仅本地;0.0.14 起已存于仓库外)。
+- **更多预制模板**:在内置默认之上延伸,为常用流程(solo `develop`、多环境企业)提供社区贡献的现成配置预设。
+- **CI 硬门槛研究**:`pr checks` 能否在不伤平台无关核心的前提下变成真实门槛。
 
 欢迎贡献——见[开发](#开发)。
 
@@ -562,9 +571,10 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 
 ```bash
 npm install
-npm test          # 单测: classify / gate / config / cli / repo / platform / i18n / index / accuracy-audit
+npm test          # 单测: classify / gate / config / cli / repo / platform / i18n / index / accuracy-audit / pi
 npm run typecheck     # tsc --noEmit, 0 Error
 npm run build         # tsdown → lib/(CLI 与插件共用)
+npm run check:pins    # 校验 package.json 版本与双语 README 锁版本示例及 CHANGELOG 标题一致
 npm run verify:matrix # 连续复测矩阵: DSH 逻辑 + zh 文案回归 + Claude Code / Codex / OpenCode / Antigravity hook 编码 + Pi 扩展
 ```
 

package/lib/cli.mjs

@@ -1,8 +1,9 @@
-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-DPJRoEJq.mjs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+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-DMlNMtXn.mjs";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 //#region src/platform.ts
 function str(v) {
 	return typeof v === "string" ? v : "";
@@ -37,7 +38,7 @@ function extractHookPayload(raw, platform = "auto") {
 		cwd = str(j.cwd);
 	} else if (plat === "antigravity") {
 		command = str(j.toolCall?.args?.CommandLine);
-		cwd = str(j.cwd);
+		cwd = str(j.toolCall?.args?.Cwd);
 	}
 	if (!command) return null;
 	return {
@@ -98,7 +99,9 @@ const CLIENTS = [
 function isWireClient(v) {
 	return CLIENTS.includes(v);
 }
-/** 各客户端的 hook 落位规格(dsh/pi 无 hook 文件, 仅输出接入引导) */
+/** 各客户端的 hook 落位规格(dsh/pi 无 hook 文件, 仅输出接入引导)
+*  opencode: OpenCode 1.18+ 已废弃 hooks.yaml(实机零调用, 见 docs/e2e/TestResult/opencode.md),
+*  官方扩展点为 plugins 目录 —— wire 把随包插件 opencode/gitflow-guard.ts 复制到插件目录。 */
 const WIRE_CLIENTS = [
 	{
 		client: "claude",
@@ -112,14 +115,13 @@ const WIRE_CLIENTS = [
 	},
 	{
 		client: "opencode",
-		projectPath: ".opencode/hook/hooks.yaml",
-		globalPath: () => join(homedir(), ".config", "opencode", "hook", "hooks.yaml")
+		projectPath: ".opencode/plugins/gitflow-guard.ts",
+		globalPath: () => join(homedir(), ".config", "opencode", "plugins", "gitflow-guard.ts")
 	},
 	{
 		client: "antigravity",
 		projectPath: ".agents/hooks.json",
-		globalPath: () => join(homedir(), ".gemini", "config", "hooks.json"),
-		experimental: true
+		globalPath: () => join(homedir(), ".gemini", "config", "hooks.json")
 	},
 	{
 		client: "dsh",
@@ -132,24 +134,18 @@ const WIRE_CLIENTS = [
 		globalPath: () => ""
 	}
 ];
-/** 各 stdin-hook 客户端的 hook 命令(与 references/*.md 逐一对应; codex/antigravity 用相对 bin/...) */
-const COMMANDS = {
-	claude: "node ${CLAUDE_PROJECT_DIR}/bin/gitflow-guard.mjs check --platform claude",
-	codex: "node bin/gitflow-guard.mjs check --platform codex",
-	opencode: "node \"$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs\" check --platform opencode",
-	antigravity: "node bin/gitflow-guard.mjs check --platform antigravity"
-};
-/** OpenCode YAML 模板(顶层 hooks: + 语义 id gitflow-guard) */
-const OPENCODE_TEMPLATE = [
-	"hooks:",
-	"  - id: gitflow-guard",
-	"    event: tool.before.bash",
-	"    actions:",
-	"      - bash: |",
-	`          ${COMMANDS.opencode}`
-].join("\n");
-const YAML_ID_GUARD = /^\s*- id: gitflow-guard\s*$/m;
-const YAML_ID_ANY = /^\s*- id:/m;
+/** 随包发布的 OpenCode 插件源文件(wire --client opencode 复制到插件目录; dev 下即仓库 opencode/) */
+const OPENCODE_PLUGIN_SOURCE = fileURLToPath(new URL("../opencode/gitflow-guard.ts", import.meta.url));
+/** 各 JSON 客户端的 hook 命令(与 references/*.md 逐一对应)。
+*  antigravity 必须绝对路径: agy hook 进程 cwd = hook 配置文件所在目录(TestResult/antigravity.md AGY-D2),
+*  相对 bin/... 会解析为 .agents/bin/... → MODULE_NOT_FOUND; 全局落位无仓库根, 用 PATH 上的 gitflow-guard。 */
+function commandFor(client, repoRoot) {
+	switch (client) {
+		case "claude": return "node ${CLAUDE_PROJECT_DIR}/bin/gitflow-guard.mjs check --platform claude";
+		case "codex": return "node bin/gitflow-guard.mjs check --platform codex";
+		case "antigravity": return repoRoot ? `node ${join(repoRoot, "bin", "gitflow-guard.mjs")} check --platform antigravity` : "gitflow-guard check --platform antigravity";
+	}
+}
 /** 读取文本文件; 缺失返回 null(其余异常也视为缺失, 决策保守) */
 async function readText(path) {
 	try {
@@ -169,6 +165,20 @@ function jsonContains(obj, needle) {
 	if (obj !== null && typeof obj === "object") return Object.values(obj).some((x) => jsonContains(x, needle));
 	return false;
 }
+/** JSON 递归搜索(谓词版): 用于旧格式条目的柔性识别 */
+function jsonContainsBy(obj, pred) {
+	if (pred(obj)) return true;
+	if (Array.isArray(obj)) return obj.some((x) => jsonContainsBy(x, pred));
+	if (obj !== null && typeof obj === "object") return Object.values(obj).some((x) => jsonContainsBy(x, pred));
+	return false;
+}
+/** 判断命令是否为本插件 antigravity 条目: 新格式绝对路径 node <root>/bin/gitflow-guard.mjs … 或
+*  AGY-D2 之前的旧相对格式 node bin/gitflow-guard.mjs …, 或全局 PATH 形态(无 .mjs);
+*  格式演进后旧条目仍能被识别/替换/移除, 避免新旧双条并存。 */
+function antigravityCommandish(cmd) {
+	if (typeof cmd !== "string") return false;
+	return cmd.includes("gitflow-guard.mjs check --platform antigravity") || cmd === "gitflow-guard check --platform antigravity";
+}
 function parseJsonOrThrow(path, raw) {
 	try {
 		const parsed = JSON.parse(raw);
@@ -182,8 +192,8 @@ async function writeJson(path, obj) {
 	await writeText(path, `${JSON.stringify(obj, null, 2)}\n`);
 }
 /** JSON 客户端(claude/codex/antigravity)新增 hook 条目; 非破坏性合并, 同命令已存在则跳过 */
-async function addJsonEntry(path, client, dryRun) {
-	const cmd = COMMANDS[client];
+async function addJsonEntry(path, client, dryRun, repoRoot) {
+	const cmd = commandFor(client, repoRoot);
 	const raw = await readText(path);
 	const obj = raw === null ? {} : parseJsonOrThrow(path, raw);
 	if (jsonContains(obj, cmd)) return "exists";
@@ -203,7 +213,11 @@ async function addJsonEntry(path, client, dryRun) {
 	if (client === "antigravity") {
 		const block = obj["gitflow-guard"] ??= { PreToolUse: [] };
 		if (!Array.isArray(block.PreToolUse)) throw new Error(`invalid ${path}: gitflow-guard.PreToolUse must be an array`);
-		block.PreToolUse.push(entry);
+		const entries = block.PreToolUse;
+		if (entries.some((e) => jsonContainsBy(e, (v) => v === cmd))) return "exists";
+		const next = entries.filter((e) => !jsonContainsBy(e, antigravityCommandish));
+		next.push(entry);
+		block.PreToolUse = next;
 	} else {
 		const hooksObj = obj["hooks"] ??= {};
 		const arr = hooksObj["PreToolUse"] ??= [];
@@ -214,14 +228,17 @@ async function addJsonEntry(path, client, dryRun) {
 	return "added";
 }
 /** JSON 客户端移除本插件条目; 不动其他内容 */
-async function removeJsonEntry(path, client, dryRun) {
-	const cmd = COMMANDS[client];
+async function removeJsonEntry(path, client, dryRun, repoRoot) {
+	const cmd = commandFor(client, repoRoot);
 	const raw = await readText(path);
 	if (raw === null) return "absent";
 	const obj = parseJsonOrThrow(path, raw);
-	if (!jsonContains(obj, cmd)) return "absent";
-	if (client === "antigravity") delete obj["gitflow-guard"];
-	else {
+	if (client === "antigravity") {
+		const block = obj["gitflow-guard"];
+		if (!block || !jsonContainsBy(block, antigravityCommandish)) return "absent";
+		delete obj["gitflow-guard"];
+	} else {
+		if (!jsonContains(obj, cmd)) return "absent";
 		const hooksObj = obj["hooks"];
 		const arr = hooksObj?.["PreToolUse"];
 		if (Array.isArray(arr)) {
@@ -234,60 +251,36 @@ async function removeJsonEntry(path, client, dryRun) {
 	if (!dryRun) await writeJson(path, obj);
 	return "removed";
 }
-/** OpenCode YAML: hooks: 列表按语义 id gitflow-guard 判重/落位 */
-async function addYamlEntry(path, dryRun) {
-	const raw = await readText(path);
-	if (raw !== null) {
-		if (YAML_ID_GUARD.test(raw)) return "exists";
-		const lines = raw.split("\n");
-		const hooksIdx = lines.findIndex((l) => /^hooks:\s*$/.test(l));
-		const block = OPENCODE_TEMPLATE.split("\n").slice(1);
-		if (hooksIdx === -1) {
-			const joined = [
-				...lines,
-				"",
-				...block
-			].join("\n");
-			if (!dryRun) await writeText(path, joined);
-			return "added";
-		}
-		lines.splice(hooksIdx + 1, 0, ...block);
-		if (!dryRun) await writeText(path, lines.join("\n"));
-		return "added";
+/** OpenCode 插件: 复制随包插件文件; 已存在同文件视为已接线(幂等) */
+async function addPluginFile(path, dryRun) {
+	if (await readText(path) !== null) return "exists";
+	let source;
+	try {
+		source = await readFile(OPENCODE_PLUGIN_SOURCE, "utf8");
+	} catch {
+		throw new Error(`cannot read bundled opencode plugin source at ${OPENCODE_PLUGIN_SOURCE} — install the package (npm i -g agents-gitflow-guard) or copy opencode/gitflow-guard.ts into the project's .opencode/plugins/ manually`);
 	}
-	if (!dryRun) await writeText(path, OPENCODE_TEMPLATE);
+	if (!dryRun) await writeText(path, source);
 	return "added";
 }
-/** OpenCode YAML: 移除 gitflow-guard 块; 若列表清空则连顶层 hooks: 一并清理 */
-async function removeYamlEntry(path, dryRun) {
-	const raw = await readText(path);
-	if (raw === null) return "absent";
-	if (!YAML_ID_GUARD.test(raw)) return "absent";
-	const lines = raw.split("\n");
-	const start = lines.findIndex((l) => YAML_ID_GUARD.test(l));
-	let end = lines.length;
-	for (let i = start + 1; i < lines.length; i++) if (YAML_ID_ANY.test(lines[i])) {
-		end = i;
-		break;
-	}
-	let rest = [...lines.slice(0, start), ...lines.slice(end)];
-	if (!rest.some((l) => YAML_ID_ANY.test(l))) rest = rest.filter((l) => !/^hooks:\s*$/.test(l));
-	const text = rest.join("\n");
-	if (!dryRun) await writeText(path, text);
+/** OpenCode 插件: 删除插件文件; 不动其他插件 */
+async function removePluginFile(path, dryRun) {
+	if (await readText(path) === null) return "absent";
+	if (!dryRun) await unlink(path);
 	return "removed";
 }
 /** 执行一次 wire 落位/移除/预览; dsh/pi 由上层直接短路, 不进这里 */
-async function applyWire(client, path, unwire, dryRun) {
-	if (client === "opencode") return unwire ? removeYamlEntry(path, dryRun) : addYamlEntry(path, dryRun);
-	return unwire ? removeJsonEntry(path, client, dryRun) : addJsonEntry(path, client, dryRun);
+async function applyWire(client, path, unwire, dryRun, repoRoot = null) {
+	if (client === "opencode") return unwire ? removePluginFile(path, dryRun) : addPluginFile(path, dryRun);
+	return unwire ? removeJsonEntry(path, client, dryRun, repoRoot) : addJsonEntry(path, client, dryRun, repoRoot);
 }
-/** 只读探测: 该配置文件是否已含本插件 hook(status 的接线提示用) */
-async function isWired(client, path) {
+/** 只读探测: 该客户端是否已接线(opencode 判插件文件存在; JSON 客户端按命令精确匹配) */
+async function isWired(client, path, repoRoot = null) {
 	const raw = await readText(path);
 	if (raw === null) return false;
-	if (client === "opencode") return YAML_ID_GUARD.test(raw);
+	if (client === "opencode") return true;
 	try {
-		return jsonContains(JSON.parse(raw), COMMANDS[client]);
+		return jsonContains(JSON.parse(raw), commandFor(client, repoRoot));
 	} catch {
 		return false;
 	}
@@ -416,7 +409,7 @@ async function status(flags, runner) {
 	const hints = [];
 	for (const spec of WIRE_CLIENTS) {
 		if (spec.client === "dsh" || spec.client === "pi") continue;
-		if (!await isWired(spec.client, join(repoRoot, spec.projectPath))) hints.push(spec.client);
+		if (!await isWired(spec.client, join(repoRoot, spec.projectPath), repoRoot)) hints.push(spec.client);
 	}
 	if (hints.length > 0) {
 		console.log(t("cli.statusWireHints"));
@@ -490,7 +483,7 @@ async function wireCore(client, scope, opts, t) {
 		path
 	}));
 	if (opts.dryRun) {
-		const res = await applyWire(client, path, !!opts.unwire, true);
+		const res = await applyWire(client, path, !!opts.unwire, true, opts.repoRoot);
 		if (res === "added") console.log(t("cli.wireDryRunAdd", {
 			client,
 			path
@@ -515,7 +508,7 @@ async function wireCore(client, scope, opts, t) {
 			if (ans !== "y" && ans !== "yes") return 1;
 		}
 	}
-	const res = await applyWire(client, path, !!opts.unwire, false);
+	const res = await applyWire(client, path, !!opts.unwire, false, opts.repoRoot);
 	if (res === "added") console.log(t("cli.wireCreated", {
 		client,
 		path

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-DPJRoEJq.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-DMlNMtXn.mjs";
 export { MESSAGE_KEYS, appendAudit, apply, createPiExtension, evaluateCommand, formatDeny, name, registerLocale, stateDir, userStateRoot };

package/lib/{src-DPJRoEJq.mjs → src-DMlNMtXn.mjs}

@@ -732,9 +732,10 @@ Notes:
   --locale overrides the message language for this invocation (flag > project config > English).
   check reads the hook payload on stdin (platform-specific protocol: claude/opencode exit 2,
   codex/antigravity JSON on stdout) and is meant for pre/post hooks of AI agents.
-  wire writes each client's hook config into the project (default) or global scope; dsh/pi are
-  in-process and only print guidance. No config file needed — built-in defaults (develop+main)
-  apply out of the box; create gitflow-guard.config.json to override, or set "enabled": false to turn off.`
+  wire writes each client's hook config (or the OpenCode plugin file) into the project
+  (default) or global scope; dsh/pi are in-process and only print guidance. No config file
+  needed — built-in defaults (develop+main) apply out of the box; create
+  gitflow-guard.config.json to override, or set "enabled": false to turn off.`
 };
 const zh = {
 	"role.integration": () => "集成分支",
@@ -839,7 +840,7 @@ const zh = {
   --locale 可临时覆盖本次调用的文案语言(旗标 > 项目配置 > 英文)。
   check 读 stdin hook payload 做门禁(平台协议: claude/opencode exit 2, codex/antigravity stdout JSON),
   供 Claude Code / Codex / OpenCode 等 agent 的 pre/post hook 调用。
-  wire 把各客户端默认 hook 写入工程(默认)或全局作用域; dsh/pi 为进程内接入, 仅打印引导。
+  wire 把各客户端默认 hook 写入工程(默认)或全局作用域(opencode 为复制插件文件); dsh/pi 为进程内接入, 仅打印引导。
   无需配置文件 — 内置默认(develop+main)开箱即用; 建 gitflow-guard.config.json 可覆盖, 或写 "enabled": false 关闭。`
 };
 /** 内置文案注册表: en 为兜底语言; 下游可经 registerLocale 追加 */

package/opencode/gitflow-guard.ts

@@ -0,0 +1,98 @@
+// OpenCode 插件(随包发布; `wire --client opencode` 会复制本文件到 .opencode/plugins/):
+// 在 tool.execute.before 事件拦截 bash/powershell 工具, 经守卫 CLI 门禁(check --platform opencode),
+// 拒绝(exit 2)时抛错阻断工具执行; 守卫不可用时 fail-open 放行, 不破坏工具管道。
+//
+// 背景: OpenCode 1.18+ 已移除 hooks.yaml 机制(实机测试零调用, 见 docs/e2e/TestResult/opencode.md),
+// 官方扩展点为 plugins 目录 + 事件订阅, 阻断语义 = handler 抛错(官方 env-protection 示例同款)。
+// 插件导出必须是**函数**(工厂), 返回事件处理器对象 —— 直接导出对象会报 "Plugin export is not a function"。
+// 协议参考: .agents/hooks/references/opencode.md。
+//
+// 用法: 项目内执行 `gitflow-guard wire --client opencode --project --yes`, wire 会把本文件
+// 复制到 <project>/.opencode/plugins/gitflow-guard.ts(全局落位到 ~/.config/opencode/plugins/);
+// 也可手工复制。零外部依赖: 不 import @opencode-ai/plugin, 客户端原生加载本文件即可。
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 插件自身所在目录: 项目级 = <项目>/.opencode/plugins, 全局 = ~/.config/opencode/plugins */
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url))
+
+interface GuardTarget {
+  bin: string
+  args: string[]
+}
+
+/** 组装 spawn 目标: opencode 插件在 opencode 进程内执行, process.execPath 是 opencode 自身而非 node,
+ *  不能拿它当解释器 —— Unix 直跑脚本(#!/usr/bin/env node shebang), Windows 用 PATH 上的 node。 */
+function makeTarget(bin: string): GuardTarget {
+  return process.platform === 'win32' ? { bin: 'node', args: [bin] } : { bin, args: [] }
+}
+
+/** 定位守卫 CLI(按可用性取第一个):
+ *  1. 插件上两级(项目根)的 bin/gitflow-guard.mjs —— 项目级落位时插件在 <项目>/.opencode/plugins/;
+ *  2. $OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs —— 客户端展开的项目目录兜底;
+ *  3. GITFLOW_GUARD_BIN 显式指定;
+ *  4. PATH 上的 gitflow-guard —— 全局安装场景。 */
+function guardTarget(): GuardTarget | null {
+  const projectRoot = resolve(dirname(dirname(PLUGIN_DIR)))
+  const local = join(projectRoot, 'bin', 'gitflow-guard.mjs')
+  if (existsSync(local)) return makeTarget(local)
+  const envProject = process.env.OPENCODE_PROJECT_DIR
+  if (envProject) {
+    const viaEnv = join(envProject, 'bin', 'gitflow-guard.mjs')
+    if (existsSync(viaEnv)) return makeTarget(viaEnv)
+  }
+  if (process.env.GITFLOW_GUARD_BIN) return makeTarget(process.env.GITFLOW_GUARD_BIN)
+  return makeTarget('gitflow-guard')
+}
+
+/** 运行守卫 check; exit 2 = 拒绝(抛错阻断工具), 其余一律放行(fail-open) */
+async function runGuard(command: string): Promise<void> {
+  const target = guardTarget()
+  if (!target) {
+    console.error('[gitflow-guard] guard CLI not found — allowing tool call (fail-open)')
+    return
+  }
+  const args = [...target.args, 'check', '--platform', 'opencode', '--command', command]
+  let stderr = ''
+  // 对象属性承载 spawn 错误: TS 对回调内赋值的局部变量不做跨闭包窄化(会推断为 never)
+  const outcome: { spawnError?: Error } = {}
+  const code = await new Promise<number>((resolvePromise) => {
+    const child = spawn(target.bin, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    let settled = false
+    child.stderr.on('data', (d: Buffer) => (stderr += d.toString()))
+    child.on('error', (e) => {
+      // spawn 失败等内部故障: fail-open, 不阻断工具管道; 告警统一在尾部输出(避免双打)
+      if (settled) return
+      settled = true
+      outcome.spawnError = e
+      resolvePromise(-1)
+    })
+    child.on('close', (code) => {
+      if (settled) return
+      settled = true
+      resolvePromise(code ?? -1)
+    })
+  })
+  if (code === 2) throw new Error(stderr.trim() || `[gitflow-guard] blocked: ${command}`)
+  if (code !== 0) {
+    const spawnMsg = outcome.spawnError?.message
+    if (spawnMsg) console.error(`[gitflow-guard] cannot spawn guard: ${spawnMsg} — allowing tool call (fail-open)`)
+    else console.error(`[gitflow-guard] check exited ${code} — allowing tool call (fail-open): ${stderr.trim()}`)
+  }
+}
+
+/** OpenCode 插件工厂(官方要求导出函数): 订阅 tool.execute.before, 仅拦 bash/powershell */
+export default async function gitflowGuardPlugin() {
+  return {
+    'tool.execute.before': async (input: { tool?: string; args?: Record<string, unknown> }, output: { args?: Record<string, unknown> }) => {
+      // 只拦截命令执行面(bash/powershell); 其余工具(read/edit 等)不经过守卫
+      if (input.tool !== 'bash' && input.tool !== 'powershell') return
+      const command = typeof output.args?.command === 'string' ? output.args.command : ''
+      if (!command) return
+      await runGuard(command)
+    },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity / Pi) — zero-config defaults (develop+main) out of the box, deep-merge override, and per-client native hooks via gitflow-guard wire/setup; integration/preview/production/archive, each with its own update rules",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
     "bin",
     "patch.yml",
     "pi",
+    "opencode",
     "README.md",
     "README.zh.md"
   ],