agents-gitflow-guard 0.0.3 → 0.0.5

package/README.md

@@ -2,7 +2,8 @@
 
 > **Are you tired of agents skipping your GitFlow?**
 
-A configurable branch-role guard for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). You define your own branches —
+A configurable branch-role guard for AI coding agents — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, and OpenCode.
+You define your own branches —
 **integration** (features merge in via PR/MR), **preview** (env endpoints), **production**, **archive** — each with its own update rules. Agents can't skip the flow, and sensitive merges stay in your hands.
 
 [中文文档](README.zh.md) · [License](LICENSE)
@@ -308,9 +309,10 @@ 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.
 
-**Claude Code hook** — the same guard inside Claude Code, no DSH required. This repo already ships the config at `.claude/settings.json`; for any other repo, add these hooks:
+**Claude Code / Codex / OpenCode 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) and `.opencode/hook/hooks.yaml` (OpenCode); any other repo adds its own:
 
-```json
+```jsonc
+// Claude Code — .claude/settings.json
 {
   "hooks": {
     "PreToolUse": [
@@ -320,9 +322,30 @@ The package declares `dsh.bundle.patch`, so `dsh plugin add` automatically makes
 }
 ```
 
-- The hook reads the payload on stdin and answers `exit 0` (allow) or `exit 2` (block — stderr is the reason shown to the model, plus a "next step" hint).
-- Only `PreToolUse` is needed: the guard blocks *before* the command runs. There is no permit to consume afterwards, so no `PostToolUse` 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` (after `npm run build`) also works from a checkout.
+```jsonc
+// Codex — .codex/hooks.json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "node bin/gitflow-guard.mjs check --platform codex" }] }
+    ]
+  }
+}
+```
+
+```yaml
+# OpenCode — .opencode/hook/hooks.yaml
+hooks:
+  - id: gitflow-guard
+    event: tool.before.bash
+    actions:
+      - bash: |
+          node "$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs" check --platform opencode
+```
+
+- 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 (Codex also accepts the legacy `{"decision":"block","reason":...}` shape, which `--platform antigravity` uses).
+- 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) also work from a checkout.
 - Fully opt-in: the hook does nothing unless the repo has `gitflow-guard.config.json` with `enabled: true`.
 
 ---
@@ -435,9 +458,12 @@ npm install
 npm test          # unit tests: classify / gate / config / cli / repo / platform
 npm run typecheck     # tsc --noEmit, 0 errors
 npm run build         # tsdown → lib/ (CLI and plugin share the build)
+npm run verify:matrix # continuous cross-agent regression: DSH logic + Claude Code / Codex / antigravity hook wiring
 ```
 
-**Rule**: any logic change must pass a 0-error build + all green tests before done.
+**Rule**: any logic change must pass a 0-error build + all green tests + a green `verify:matrix` before done.
+
+**Adding a new agent client** (e.g. Gemini / OpenCode / Cursor): all of these must change in one commit — `src/platform.ts` (+tests, `HookPlatform` union), a repo hook config beside `.claude/settings.json` / `.codex/hooks.json`, `.agents/hooks/references/<tool>.md`, `scripts/verify-matrix.mjs`, the README hook section and the top tagline, `package.json` description/keywords, and `CHANGELOG`. Done only when `npm run verify:matrix` is green. (Same checklist in [AGENTS.md](AGENTS.md) §8.)
 
 ---
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 > **有没有受够了 agent 跳过你的合入流程?**
 
-一个可自由配置分支角色守卫的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)插件。  
+一个可自由配置分支角色的流程守卫,为 AI 编码 agent 而生——[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)、Claude Code、Codex、OpenCode。  
 你自己定义分支——**集成分支**(feature 经 PR/MR 合入)、**预览分支**(环境终点)、**生产分支**、**归档分支**——每个角色各自配规则。agent 无法跳过流程,敏感合并始终留在你手上。
 
 [English](README.md) · [许可证](LICENSE)
@@ -306,9 +306,10 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 
 包自带 `dsh.bundle.patch` 声明,`dsh plugin add` 自动把它挂为 profile 层,无需手工编辑 profile。
 
-**Claude Code hook**——同一守卫也能在 Claude Code 里跑,不依赖 DSH。本仓库已自带 `.claude/settings.json`;其他仓库加这些 hooks:
+**Claude Code / Codex / OpenCode hook**——同一守卫也能在这些 agent 里跑,不依赖 DSH。本仓库已自带 `.claude/settings.json`(Claude Code)、`.codex/hooks.json`(Codex)和 `.opencode/hook/hooks.yaml`(OpenCode);其他仓库加自己的 hooks:
 
-```json
+```jsonc
+// Claude Code — .claude/settings.json
 {
   "hooks": {
     "PreToolUse": [
@@ -318,9 +319,30 @@ dsh plugin --profile web add file:/path/to/agents-gitflow-guard
 }
 ```
 
-- hook 读 stdin payload,按 `exit 0`(放行)/ `exit 2`(拦截,stderr 展示给模型的原因 + "下一步"提示)作答。
-- 只需要 `PreToolUse`:守卫在命令执行*之前*拦截;没有特许可事后消费,因此无需 `PostToolUse` 钩子。
-- 用**绝对路径**指向二进制——hook 子进程不一定继承你的 shell PATH。`${CLAUDE_PROJECT_DIR}/bin/gitflow-guard.mjs`(`npm run build` 后)也可以。
+```jsonc
+// Codex — .codex/hooks.json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "node bin/gitflow-guard.mjs check --platform codex" }] }
+    ]
+  }
+}
+```
+
+```yaml
+# OpenCode — .opencode/hook/hooks.yaml
+hooks:
+  - id: gitflow-guard
+    event: tool.before.bash
+    actions:
+      - bash: |
+          node "$OPENCODE_PROJECT_DIR/bin/gitflow-guard.mjs" check --platform opencode
+```
+
+- hook 读 stdin payload,按**各平台协议**作答:Claude Code / OpenCode → `exit 2`(stderr 展示原因 + "下一步"提示);Codex → stdout 输出 JSON `{"hookSpecificOutput":{"permissionDecision":"deny",...}}`(Codex 也兼容旧的 `{"decision":"block","reason":...}` 形状,`--platform antigravity` 用的就是它)。
+- 只需要**执行前事件**:守卫在命令执行*之前*拦截;没有特许可事后消费,因此无需执行后钩子。
+- 用**绝对路径**指向二进制——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`(均在项目目录执行)也可以。
 - 完全 opt-in:仓库没有 `gitflow-guard.config.json`(或 `enabled` 非 true)时 hook 什么都不做。
 
 ---

package/lib/cli.mjs

@@ -1,4 +1,4 @@
-import { c as findRepoRoot, d as resolveLocale, f as loadConfig, i as formatDeny, l as gitRunner, m as classify, o as stateDir, p as roleMatches, r as evaluateCommand, s as currentBranch, u as makeT } from "./src-LvZrsHEn.mjs";
+import { c as findRepoRoot, d as resolveLocale, f as loadConfig, i as formatDeny, l as gitRunner, m as classify, o as stateDir, p as roleMatches, r as evaluateCommand, s as currentBranch, u as makeT } from "./src-2TtpUFC9.mjs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts
@@ -30,6 +30,9 @@ function extractHookPayload(raw, platform = "auto") {
 	if (plat === "claude" || plat === "codex") {
 		command = str(j.tool_input?.command);
 		cwd = str(j.cwd);
+	} else if (plat === "opencode") {
+		command = str(j.tool_args?.command) || str(j.tool_args?.cmd);
+		cwd = str(j.cwd);
 	} else if (plat === "copilot") {
 		command = str(j.tool_input?.command) || str(j.toolArgs?.command);
 		cwd = str(j.cwd);
@@ -45,12 +48,13 @@ function extractHookPayload(raw, platform = "auto") {
 		event: eventFrom(j.hook_event_name)
 	};
 }
-/** 按 payload 判别平台: 非空 turn_id→codex, toolCall→antigravity, 其余→claude */
+/** 按 payload 判别平台: 非空 turn_id→codex, toolCall→antigravity, tool_args→opencode, 其余→claude */
 function detectPlatform(raw) {
 	const j = parseRaw(raw);
 	if (!j) return "claude";
 	if (j.turn_id) return "codex";
 	if (j.toolCall) return "antigravity";
+	if (j.tool_args) return "opencode";
 	return "claude";
 }
 /** deny 编码: 各平台的拦截协议(exit 码 + stdout/stderr) */
@@ -60,6 +64,10 @@ function encodeDeny(platform, reason) {
 			exitCode: 2,
 			stderr: reason
 		};
+		case "opencode": return {
+			exitCode: 2,
+			stderr: reason
+		};
 		case "codex": return {
 			exitCode: 0,
 			stdout: JSON.stringify({ hookSpecificOutput: {

package/lib/index.mjs

@@ -1,2 +1,2 @@
-import { a as name, i as formatDeny, n as apply, o as stateDir, r as evaluateCommand, t as appendAudit } from "./src-LvZrsHEn.mjs";
+import { a as name, i as formatDeny, n as apply, o as stateDir, r as evaluateCommand, t as appendAudit } from "./src-2TtpUFC9.mjs";
 export { appendAudit, apply, evaluateCommand, formatDeny, name, stateDir };

package/lib/{src-LvZrsHEn.mjs → src-2TtpUFC9.mjs}

@@ -418,13 +418,13 @@ const en = {
 Usage:
   gitflow-guard status [--repo <path>]
   gitflow-guard audit [--lines <count>] [--repo <path>]
-  gitflow-guard check [--platform <claude|auto>] [--command "<cmd>"] [--repo <path>]
+  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <path>]
   gitflow-guard --help
 
 Notes:
   status/audit are read-only; the agent can self-inspect.
-  check reads the hook payload on stdin (exit 0 = allow / 2 = block) and is meant for
-  pre/post hooks of agents such as Claude Code.`
+  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.`
 };
 const zh = {
 	"role.integration": () => "集成分支",
@@ -488,12 +488,13 @@ const zh = {
 用法:
   gitflow-guard status [--repo <路径>]
   gitflow-guard audit [--lines <数量>] [--repo <路径>]
-  gitflow-guard check [--platform <claude|auto>] [--command "<cmd>"] [--repo <路径>]
+  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <路径>]
   gitflow-guard --help
 
 说明:
   status/audit 只读, agent 可自查。
-  check 读 stdin hook payload 做门禁(exit 0=放行 / 2=拦截), 供 Claude Code 等 agent 的 pre/post hook 调用。`
+  check 读 stdin hook payload 做门禁(平台协议: claude/opencode exit 2, codex/antigravity stdout JSON),
+  供 Claude Code / Codex / OpenCode 等 agent 的 pre/post hook 调用。`
 };
 const MESSAGE_KEYS = Object.keys(en);
 /** key 合法性与 en/zh 双字典完整性检查(开发期一次) */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.3",
-  "description": "DSH plugin: a configurable branch-role guard — integration/preview/production/archive, each with its own update rules",
+  "version": "0.0.5",
+  "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode) — integration/preview/production/archive, each with its own update rules",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.mjs",
@@ -26,7 +26,11 @@
   "keywords": [
     "dsh",
     "deepseek-harness",
+    "claude-code",
+    "codex",
+    "opencode",
     "plugin",
+    "hook",
     "gitflow",
     "git",
     "workflow",
@@ -46,7 +50,8 @@
     "build": "tsdown",
     "prepack": "npm run build",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "verify:matrix": "npm run build && node scripts/verify-matrix.mjs"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",