@brawnen/agent-harness-cli 0.1.0 → 0.1.1

package/README.md

@@ -37,6 +37,8 @@ The current implementation also covers:
 - host rule injection
 - base project config generation
 - minimal `.codex/hooks.json` integration
+- `.claude/settings.json` hook integration
+- `.gemini/settings.json` hook integration
 
 ## Current Boundaries
 
@@ -144,7 +146,7 @@ Current responsibilities:
 - `docs scaffold --type design-note|adr`
 - generate minimal Markdown skeletons from task context
 
-## Codex Support
+## Host Support
 
 The current repository has the most complete host integration for `Codex`.
 
@@ -152,16 +154,44 @@ Current Codex coverage includes:
 
 - `SessionStart`
 - `UserPromptSubmit`
+
+Currently disabled by default:
+
 - `PreToolUse`
 - `PostToolUse`
 
 Highlights:
 
 - automatic intake / continue / clarify
-- pre-tool gating
-- automatic evidence capture
 - active task restore
 
+Current Codex boundary:
+
+- tool-level hooks remain implemented but are not enabled by default because of host visibility noise
+
+Current Gemini CLI coverage includes:
+
+- `SessionStart`
+- `BeforeAgent`
+- `BeforeTool`
+- `AfterTool`
+- `AfterAgent`
+
+Highlights:
+
+- automatic intake / continue / clarify
+- before-tool gating for supported Gemini tools
+- shell evidence capture through `AfterTool`
+- completion gating through `AfterAgent`
+
+Current Claude Code coverage includes:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `Stop`
+
 ### Current `PreToolUse` Coverage For `Bash`
 
 `Bash` currently supports high-confidence path inference for common write commands such as:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brawnen/agent-harness-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI for task convergence, verification, reporting, and delivery in agent-harness projects.",
   "license": "MIT",
   "bin": {
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@brawnen/agent-harness-protocol": "^0.1.0"
+    "@brawnen/agent-harness-protocol": "^0.1.1"
   },
   "scripts": {
     "start": "node ./bin/agent-harness.js --help"

package/src/commands/gate.js

@@ -67,7 +67,7 @@ function parseBeforeToolArgs(argv) {
   return { ok: true, options };
 }
 
-function beforeTool(cwd, options) {
+export function beforeTool(cwd, options) {
   const taskId = options.taskId ?? resolveActiveTaskId(cwd);
   const taskState = taskId ? getTaskState(cwd, taskId) : null;
   const config = loadProjectConfig(cwd);

package/src/commands/hook.js

@@ -0,0 +1,43 @@
+import { runClaudeHook, readHookPayload } from "../lib/claude-hooks.js";
+import { runCodexHook } from "../lib/codex-hooks.js";
+import { runGeminiHook } from "../lib/gemini-hooks.js";
+
+export function runHook(argv) {
+  const [host, event] = argv;
+
+  if (!host || !event) {
+    console.error("用法: hook <claude|codex|gemini> <event>");
+    return 1;
+  }
+
+  if (!["claude", "claude-code", "codex", "gemini", "gemini-cli"].includes(host)) {
+    console.error(`未知 hook 宿主: ${host}`);
+    return 1;
+  }
+
+  try {
+    const payload = readHookPayload();
+    const result = runHostHook(host, event, payload);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function runHostHook(host, event, payload) {
+  if (host === "claude" || host === "claude-code") {
+    return runClaudeHook(event, payload);
+  }
+
+  if (host === "codex") {
+    return runCodexHook(event, payload);
+  }
+
+  if (host === "gemini" || host === "gemini-cli") {
+    return runGeminiHook(event, payload);
+  }
+
+  throw new Error(`未知 hook 宿主: ${host}`);
+}

package/src/commands/init.js

@@ -295,6 +295,9 @@ function queueInitActions(context) {
     if (hosts.includes("claude-code")) {
       queueClaudeSettingsMerge(actions, cwd);
     }
+    if (hosts.includes("gemini-cli")) {
+      queueGeminiSettingsMerge(actions, cwd);
+    }
   }
 }
 
@@ -361,6 +364,25 @@ function queueClaudeSettingsMerge(actions, cwd) {
   });
 }
 
+function queueGeminiSettingsMerge(actions, cwd) {
+  const targetPath = path.join(cwd, ".gemini", "settings.json");
+  const templatePath = path.join(PROTOCOL_ROOT, "adapters", "gemini-cli", "hooks.json");
+  const template = JSON.parse(readText(templatePath));
+  const existing = fs.existsSync(targetPath) ? readJson(targetPath) : {};
+  const merged = mergeClaudeSettings(existing, template);
+  const content = `${JSON.stringify(merged, null, 2)}\n`;
+
+  actions.push({
+    description: fs.existsSync(targetPath) ? "合并 Gemini CLI hooks" : "创建 Gemini CLI hooks 配置",
+    relativePath: path.relative(cwd, targetPath),
+    run: () => {
+      ensureDirectory(path.dirname(targetPath));
+      fs.writeFileSync(targetPath, content, "utf8");
+    },
+    skip: false
+  });
+}
+
 function queueRuntimeFiles(actions, cwd) {
   const runtimeReadme = path.join(cwd, DEFAULT_RUNTIME_DIR, "README.md");
   queueWriteAction({

package/src/commands/state.js

@@ -110,7 +110,9 @@ function runStateUpdate(argv) {
     }
 
     const result = updateTaskState(process.cwd(), taskId, changes);
-    printJson(result);
+    if (parsed.options.verbose) {
+      printJson(result);
+    }
     return 0;
   } catch (error) {
     console.error(error.message);
@@ -208,7 +210,8 @@ function parseStateUpdateArgs(argv) {
     phase: null,
     state: null,
     taskId: null,
-    tool: null
+    tool: null,
+    verbose: false
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -251,6 +254,11 @@ function parseStateUpdateArgs(argv) {
       continue;
     }
 
+    if (arg === "--verbose") {
+      options.verbose = true;
+      continue;
+    }
+
     return { ok: false, error: `未知参数: ${arg}` };
   }
 

package/src/commands/status.js

@@ -72,6 +72,10 @@ export function runStatus(argv) {
   pushCheck(checks, claudeHooksCheck);
   exitCode = maxExitCode(exitCode, claudeHooksCheck.severity);
 
+  const geminiAdapterCheck = inspectGeminiAdapter(cwd, runtimeMode, hosts.includes("gemini-cli"));
+  pushCheck(checks, geminiAdapterCheck);
+  exitCode = maxExitCode(exitCode, geminiAdapterCheck.severity);
+
   const runtimeDirsCheck = inspectRuntimeDirectories(cwd, runtimeMode);
   pushCheck(checks, runtimeDirsCheck);
   exitCode = maxExitCode(exitCode, runtimeDirsCheck.severity);
@@ -307,14 +311,21 @@ function inspectCodexHooks(cwd, hasCodexHost) {
     return warn(".codex/hooks", "hooks.json 存在，但 JSON 解析失败");
   }
 
-  const checks = [
-    hasCodexHookCommand(parsedHooks, "UserPromptSubmit", "user_prompt_submit_intake.js"),
-    hasCodexHookCommand(parsedHooks, "SessionStart", "session_start_restore.js"),
-    hasCodexHookCommand(parsedHooks, "PostToolUse", "post_tool_use_record_evidence.js")
-  ];
+  const hasUserPromptSubmit = hasCodexHookCommand(parsedHooks, "UserPromptSubmit", "user_prompt_submit_intake.js");
+  const hasSessionStart = hasCodexHookCommand(parsedHooks, "SessionStart", "session_start_restore.js");
+  const hasPreToolUse = hasCodexHookCommand(parsedHooks, "PreToolUse", "pre_tool_use_gate.js");
+  const hasPostToolUse = hasCodexHookCommand(parsedHooks, "PostToolUse", "post_tool_use_record_evidence.js");
+
+  if (!hasUserPromptSubmit || !hasSessionStart) {
+    return warn(".codex/hooks", "hooks.json 存在，但缺少最小 Codex hooks：SessionStart / UserPromptSubmit");
+  }
 
-  if (checks.some((item) => item === false)) {
-    return warn(".codex/hooks", "hooks.json 存在，但 agent-harness Codex hooks 不完整");
+  if (!hasPreToolUse && !hasPostToolUse) {
+    return ok(".codex/hooks", "Codex hooks 已配置；已启用 SessionStart / UserPromptSubmit，工具级 hooks 当前关闭");
+  }
+
+  if (hasPreToolUse !== hasPostToolUse) {
+    return warn(".codex/hooks", "hooks.json 存在，但工具级 hooks 仅部分启用");
   }
 
   return ok(".codex/hooks", "Codex hooks 已配置；trusted project 默认启用，untrusted 请显式使用 codex --enable codex_hooks");
@@ -348,14 +359,120 @@ function inspectClaudeHooks(cwd, runtimeMode, hasClaudeHost) {
     .map((hook) => hook.command)
     .filter(Boolean);
 
-  const hasPreTool = commands.some((command) => command.includes("agent-harness gate before-tool"));
-  const hasPostTool = commands.some((command) => command.includes("agent-harness state update"));
+  const hasPreTool = commands.some((command) =>
+    command.includes("agent-harness gate before-tool") ||
+    command.includes("@brawnen/agent-harness-cli gate before-tool") ||
+    command.includes("packages/cli/bin/agent-harness.js\" gate before-tool") ||
+    command.includes("packages/cli/bin/agent-harness.js gate before-tool")
+  );
+  const hasPostTool = commands.some((command) =>
+    command.includes("agent-harness state update") ||
+    command.includes("@brawnen/agent-harness-cli state update") ||
+    command.includes("packages/cli/bin/agent-harness.js\" state update") ||
+    command.includes("packages/cli/bin/agent-harness.js state update")
+  );
+  const hasSessionStart = commands.some((command) =>
+    command.includes("agent-harness hook claude session-start") ||
+    command.includes("@brawnen/agent-harness-cli hook claude session-start") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook claude session-start") ||
+    command.includes("packages/cli/bin/agent-harness.js hook claude session-start")
+  );
+  const hasUserPromptSubmit = commands.some((command) =>
+    command.includes("agent-harness hook claude user-prompt-submit") ||
+    command.includes("@brawnen/agent-harness-cli hook claude user-prompt-submit") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook claude user-prompt-submit") ||
+    command.includes("packages/cli/bin/agent-harness.js hook claude user-prompt-submit")
+  );
+  const hasStop = commands.some((command) =>
+    command.includes("agent-harness hook claude stop") ||
+    command.includes("@brawnen/agent-harness-cli hook claude stop") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook claude stop") ||
+    command.includes("packages/cli/bin/agent-harness.js hook claude stop")
+  );
+
+  if (hasSessionStart && hasUserPromptSubmit && hasPreTool && hasPostTool && hasStop) {
+    return ok(".claude/settings.json", "Claude Code hooks 已配置（SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop）");
+  }
 
   if (hasPreTool && hasPostTool) {
-    return ok(".claude/settings.json", "Claude Code hooks 已配置");
+    return warn(".claude/settings.json", "检测到旧版 Claude Code 最小 hooks，缺少 SessionStart / UserPromptSubmit / Stop");
+  }
+
+  return warn(".claude/settings.json", "hooks 存在，但 Claude Code adapter 命令不完整");
+}
+
+function inspectGeminiAdapter(cwd, runtimeMode, hasGeminiHost) {
+  if (!hasGeminiHost) {
+    return skip("Gemini adapter", "当前项目未检测到 Gemini CLI 宿主");
+  }
+
+  const hostPath = path.join(cwd, "GEMINI.md");
+  const settingsPath = path.join(cwd, ".gemini", "settings.json");
+  if (!fs.existsSync(hostPath)) {
+    return warn("Gemini adapter", "缺少 GEMINI.md，无法注入 Gemini CLI 宿主规则");
   }
 
-  return warn(".claude/settings.json", "hooks 存在，但 agent-harness 命令不完整");
+  if (!fs.existsSync(settingsPath)) {
+    if (runtimeMode === "protocol-only") {
+      return skip("Gemini adapter", "protocol-only 模式，仅依赖 GEMINI.md 规则注入");
+    }
+
+    return warn("Gemini adapter", "未发现 .gemini/settings.json，Gemini CLI hooks 尚未配置");
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  } catch {
+    return warn("Gemini adapter", ".gemini/settings.json 存在，但 JSON 解析失败");
+  }
+
+  const commands = Object.values(parsed.hooks ?? {})
+    .flatMap((entries) => entries ?? [])
+    .flatMap((entry) => entry.hooks ?? [])
+    .map((hook) => hook.command)
+    .filter(Boolean);
+
+  const hasSessionStart = commands.some((command) =>
+    command.includes("agent-harness hook gemini session-start") ||
+    command.includes("@brawnen/agent-harness-cli hook gemini session-start") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook gemini session-start") ||
+    command.includes("packages/cli/bin/agent-harness.js hook gemini session-start")
+  );
+  const hasBeforeAgent = commands.some((command) =>
+    command.includes("agent-harness hook gemini before-agent") ||
+    command.includes("@brawnen/agent-harness-cli hook gemini before-agent") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook gemini before-agent") ||
+    command.includes("packages/cli/bin/agent-harness.js hook gemini before-agent")
+  );
+  const hasBeforeTool = commands.some((command) =>
+    command.includes("agent-harness hook gemini before-tool") ||
+    command.includes("@brawnen/agent-harness-cli hook gemini before-tool") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook gemini before-tool") ||
+    command.includes("packages/cli/bin/agent-harness.js hook gemini before-tool")
+  );
+  const hasAfterTool = commands.some((command) =>
+    command.includes("agent-harness hook gemini after-tool") ||
+    command.includes("@brawnen/agent-harness-cli hook gemini after-tool") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook gemini after-tool") ||
+    command.includes("packages/cli/bin/agent-harness.js hook gemini after-tool")
+  );
+  const hasAfterAgent = commands.some((command) =>
+    command.includes("agent-harness hook gemini after-agent") ||
+    command.includes("@brawnen/agent-harness-cli hook gemini after-agent") ||
+    command.includes("packages/cli/bin/agent-harness.js\" hook gemini after-agent") ||
+    command.includes("packages/cli/bin/agent-harness.js hook gemini after-agent")
+  );
+
+  const modeSummary = runtimeMode === "protocol-only"
+    ? "当前为 protocol-only，但 hooks 已可用"
+    : "已检测到 .harness 运行时目录，可配合 hooks 与 CLI 做 state / verify / report";
+
+  if (hasSessionStart && hasBeforeAgent && hasBeforeTool && hasAfterTool && hasAfterAgent) {
+    return ok("Gemini adapter", `Gemini CLI hooks 已配置（SessionStart / BeforeAgent / BeforeTool / AfterTool / AfterAgent）；${modeSummary}`);
+  }
+
+  return warn("Gemini adapter", "Gemini CLI hooks 已部分配置，但命令集合不完整");
 }
 
 function hasCodexHookCommand(parsedHooks, eventName, commandFragment) {

package/src/index.js

@@ -2,6 +2,7 @@ import { runAudit } from "./commands/audit.js";
 import { runDelivery } from "./commands/delivery.js";
 import { runDocs } from "./commands/docs.js";
 import { runGate } from "./commands/gate.js";
+import { runHook } from "./commands/hook.js";
 import { runInit } from "./commands/init.js";
 import { runReport } from "./commands/report.js";
 import { runState } from "./commands/state.js";
@@ -21,6 +22,7 @@ Usage:
   agent-harness delivery <ready|request|commit>
   agent-harness docs scaffold --type <design-note|adr>
   agent-harness gate before-tool --tool <tool>
+  agent-harness hook <claude|codex|gemini> <event>
   agent-harness status
   agent-harness task intake "<任务描述>"
   agent-harness task confirm [--task-id <task-id>]
@@ -75,6 +77,10 @@ export function run(argv) {
     return runGate(argv.slice(1));
   }
 
+  if (command === "hook") {
+    return runHook(argv.slice(1));
+  }
+
   if (command === "status") {
     return runStatus(argv.slice(1));
   }

package/src/lib/claude-hooks.js

@@ -0,0 +1,49 @@
+import {
+  handleCompletionGate,
+  handlePromptSubmit,
+  handleSessionStart
+} from "./hook-core.js";
+import { buildClaudeHookOutput, resolveClaudeCompletionMessage } from "./hook-io/claude.js";
+import { readHookPayload, resolvePayloadCwd, resolvePayloadPrompt } from "./hook-io/shared.js";
+
+const MANUAL_FALLBACK_COMMANDS = [
+  "npx @brawnen/agent-harness-cli state active",
+  "npx @brawnen/agent-harness-cli task intake \"任务描述\"",
+  "npx @brawnen/agent-harness-cli task suspend-active --reason \"切换任务\""
+];
+
+export { readHookPayload };
+
+export function runClaudeHook(event, payload) {
+  const cwd = resolvePayloadCwd(payload);
+
+  if (event === "session-start") {
+    return buildClaudeHookOutput("SessionStart", handleSessionStart({
+      cwd,
+      fallbackCommands: [
+        "npx @brawnen/agent-harness-cli state active",
+        "npx @brawnen/agent-harness-cli task intake \"任务描述\""
+      ],
+      hostDisplayName: "Claude Code",
+      source: payload?.source ?? ""
+    }));
+  }
+
+  if (event === "user-prompt-submit") {
+    return buildClaudeHookOutput("UserPromptSubmit", handlePromptSubmit({
+      cwd,
+      fallbackCommands: MANUAL_FALLBACK_COMMANDS,
+      hostDisplayName: "Claude Code",
+      prompt: resolvePayloadPrompt(payload)
+    }));
+  }
+
+  if (event === "stop") {
+    return buildClaudeHookOutput("Stop", handleCompletionGate({
+      cwd,
+      lastAssistantMessage: resolveClaudeCompletionMessage(payload)
+    }));
+  }
+
+  throw new Error(`未知 Claude hook 事件: ${event}`);
+}

package/src/lib/codex-hooks.js

@@ -0,0 +1,48 @@
+import {
+  handleCompletionGate,
+  handlePromptSubmit,
+  handleSessionStart
+} from "./hook-core.js";
+import { buildCodexHookOutput, resolveCodexCompletionMessage } from "./hook-io/codex.js";
+import { resolvePayloadCwd, resolvePayloadPrompt } from "./hook-io/shared.js";
+
+const MANUAL_FALLBACK_COMMANDS = [
+  "node packages/cli/bin/agent-harness.js state active",
+  "node packages/cli/bin/agent-harness.js task intake \"任务描述\"",
+  "node packages/cli/bin/agent-harness.js task suspend-active --reason \"切换任务\""
+];
+
+export function runCodexHook(event, payload) {
+  if (event === "session-start") {
+    const decision = handleSessionStart({
+      cwd: resolvePayloadCwd(payload),
+      fallbackCommands: [
+        "node packages/cli/bin/agent-harness.js state active",
+        "node packages/cli/bin/agent-harness.js task intake \"任务描述\""
+      ],
+      hostDisplayName: "Codex",
+      source: payload?.source ?? ""
+    });
+    return buildCodexHookOutput("SessionStart", decision);
+  }
+
+  if (event === "user-prompt-submit") {
+    const decision = handlePromptSubmit({
+      cwd: resolvePayloadCwd(payload),
+      fallbackCommands: MANUAL_FALLBACK_COMMANDS,
+      hostDisplayName: "Codex",
+      prompt: resolvePayloadPrompt(payload)
+    });
+    return buildCodexHookOutput("UserPromptSubmit", decision);
+  }
+
+  if (event === "stop") {
+    const decision = handleCompletionGate({
+      cwd: resolvePayloadCwd(payload),
+      lastAssistantMessage: resolveCodexCompletionMessage(payload)
+    });
+    return buildCodexHookOutput("Stop", decision);
+  }
+
+  throw new Error(`未知 Codex hook 事件: ${event}`);
+}

package/src/lib/gemini-hooks.js

@@ -0,0 +1,76 @@
+import {
+  handleAfterTool,
+  handleBeforeTool,
+  handleCompletionGate,
+  handlePromptSubmit,
+  handleSessionStart
+} from "./hook-core.js";
+import {
+  buildGeminiHookOutput,
+  resolveGeminiCompletionMessage,
+  resolveGeminiToolCommand,
+  resolveGeminiToolExitCode,
+  resolveGeminiToolName,
+  resolveGeminiToolOutput,
+  resolveGeminiToolPath
+} from "./hook-io/gemini.js";
+import { resolvePayloadCwd, resolvePayloadPrompt } from "./hook-io/shared.js";
+
+const MANUAL_FALLBACK_COMMANDS = [
+  "node packages/cli/bin/agent-harness.js state active",
+  "node packages/cli/bin/agent-harness.js task intake \"任务描述\"",
+  "node packages/cli/bin/agent-harness.js task suspend-active --reason \"切换任务\""
+];
+
+export function runGeminiHook(event, payload) {
+  const cwd = resolvePayloadCwd(payload);
+
+  if (event === "session-start") {
+    return buildGeminiHookOutput(handleSessionStart({
+      cwd,
+      fallbackCommands: [
+        "node packages/cli/bin/agent-harness.js state active",
+        "node packages/cli/bin/agent-harness.js task intake \"任务描述\""
+      ],
+      hostDisplayName: "Gemini CLI",
+      source: payload?.source ?? ""
+    }));
+  }
+
+  if (event === "before-agent") {
+    return buildGeminiHookOutput(handlePromptSubmit({
+      cwd,
+      fallbackCommands: MANUAL_FALLBACK_COMMANDS,
+      hostDisplayName: "Gemini CLI",
+      prompt: resolvePayloadPrompt(payload)
+    }));
+  }
+
+  if (event === "before-tool") {
+    return buildGeminiHookOutput(handleBeforeTool({
+      command: resolveGeminiToolCommand(payload),
+      cwd,
+      filePath: resolveGeminiToolPath(payload),
+      toolName: resolveGeminiToolName(payload)
+    }));
+  }
+
+  if (event === "after-tool") {
+    return buildGeminiHookOutput(handleAfterTool({
+      command: resolveGeminiToolCommand(payload),
+      cwd,
+      exitCode: resolveGeminiToolExitCode(payload),
+      output: resolveGeminiToolOutput(payload),
+      toolName: resolveGeminiToolName(payload)
+    }));
+  }
+
+  if (event === "after-agent") {
+    return buildGeminiHookOutput(handleCompletionGate({
+      cwd,
+      lastAssistantMessage: resolveGeminiCompletionMessage(payload)
+    }));
+  }
+
+  throw new Error(`未知 Gemini hook 事件: ${event}`);
+}