@brawnen/agent-harness-cli 0.1.0 → 0.1.2

package/README.md

@@ -2,11 +2,14 @@
 
 [中文](README.zh-CN.md)
 
-`@brawnen/agent-harness-cli` is the Node.js CLI for `agent-harness`.
+`@brawnen/agent-harness-cli` is the compatibility CLI for `agent-harness`.
 
-It is the runtime layer that turns protocol rules into a working task loop with:
+Its focus is no longer to be the long-term product center. It is the compatibility layer for:
 
 - initialization
+- host/runtime bootstrap
+- status inspection
+- manual fallback commands
 - task state
 - verification
 - reports
@@ -15,6 +18,10 @@ It is the runtime layer that turns protocol rules into a working task loop with:
 - delivery
 - documentation scaffolding
 
+The repo-local host runtime is becoming the primary execution surface. The CLI remains for initialization, diagnostics, and explicit manual operations.
+
+This package is now in maintenance mode. It remains publishable and usable, but it is no longer intended to grow into the long-term product center.
+
 ## Current Coverage
 
 The CLI currently includes these commands:
@@ -37,10 +44,12 @@ 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
 
-The CLI is already usable, but it is still an evolving implementation.
+The CLI is already usable, but it should now be treated as a bounded compatibility layer rather than an expanding surface.
 
 It currently does not try to provide:
 
@@ -49,6 +58,12 @@ It currently does not try to provide:
 - automatic `git push`
 - a deep upgrader / migration system
 
+Maintenance-mode interpretation:
+
+- keep it usable for bootstrap, diagnostics, and manual fallback
+- accept bug fixes, compatibility fixes, and documentation clarification
+- do not keep expanding host-specific wrapper behavior
+
 ## What The CLI Does Today
 
 ### `init`
@@ -144,7 +159,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 +167,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:
@@ -196,6 +239,8 @@ Useful local checks:
 ```bash
 npm --prefix packages/cli run verify:task-core
 npm --prefix packages/cli run verify:codex-e2e
+npm --prefix packages/cli run verify:host-hooks
+npm --prefix packages/cli run verify:init-status
 ```
 
 From the repository root:
@@ -203,8 +248,14 @@ From the repository root:
 ```bash
 npm run codex:hooks:check
 npm run codex:e2e
+npm run runtime:host-hooks
+npm run runtime:init-status
+npm run runtime:p1:check
+node packages/cli/bin/agent-harness.js sync --check
 ```
 
+`codex:hooks:check` validates the source-of-truth hook files under `.harness/hosts/codex/hooks/`, not the generated root `.codex/` shell.
+
 ## Local Invocation Note
 
 If your current working directory is not the repository root, prefer calling the CLI with an absolute path, for example:
@@ -221,4 +272,5 @@ Do not assume `node packages/cli/bin/agent-harness.js ...` will work from an arb
 - installing `@brawnen/agent-harness-cli` from npm should automatically pull `@brawnen/agent-harness-protocol`
 - the protocol must not depend on the CLI
 - the default npm entrypoint is `npx @brawnen/agent-harness-cli init`
-- this repository currently treats the Node.js CLI as the only mainline implementation
+- this repository now treats the Node.js CLI as the compatibility layer of `Agent Harness Runtime`
+- repo-local hooks should now consume the stable runtime entry `@brawnen/agent-harness-cli/runtime-host`

package/README.zh-CN.md

@@ -2,7 +2,10 @@
 
 [English](README.md)
 
-这是 `agent-harness` 的 Node.js CLI。
+这是 `agent-harness` 的兼容 CLI。
+
+当前产品方向已经明确：宿主运行时逐步前移到 repo-local hooks，`CLI` 主要负责初始化、状态检查、人工 fallback 和显式交付动作。
+这个包现在已经进入维护态：保持可用、可发布、可诊断，但不再继续向长期主产品方向扩张。
 
 当前已完成：
 
@@ -22,9 +25,11 @@
 - 基础项目配置生成
 - `.codex/hooks.json` 最小方案
 
-还未完成：
+当前边界：
 
-- 更深的宿主集成
+- 继续支持初始化、状态检查、验证、报告和人工 fallback
+- 接受必要的 bug fix、兼容修复和文档澄清
+- 不再继续扩大宿主专属 wrapper 行为
 
 `init` MVP 当前负责：
 
@@ -218,7 +223,13 @@ node /abs/path/to/agent-harness/packages/cli/bin/agent-harness.js audit read --t
 Codex E2E 回归：
 
 - 可执行 `npm --prefix packages/cli run verify:codex-e2e`
+- 可执行 `npm --prefix packages/cli run verify:host-hooks`
+- 可执行 `npm --prefix packages/cli run verify:init-status`
+- 可执行 `npm --prefix packages/cli run verify:status-compat`
 - 或在仓库根目录执行 `npm run codex:e2e`
+- 或在仓库根目录执行 `npm run runtime:host-hooks`
+- 或在仓库根目录执行 `npm run runtime:init-status`
+- 或在仓库根目录执行 `npm run runtime:p1:check`
 - 当前最小回归覆盖：新任务自动 intake、follow-up 不误切、高风险确认链路、hook 降级提示
 - 当前回归采用“真实 `codex exec` smoke + hook 主链路回归”混合方式，优先验证我们自己的接入链路
 - 当前脚本会在**当前 trusted 仓库**里执行真实 Codex 回归，并清理自己创建的 task/audit/report 文件
@@ -229,4 +240,5 @@ Codex E2E 回归：
 - CLI 依赖 `@brawnen/agent-harness-protocol`
 - 从 npm 安装 `@brawnen/agent-harness-cli` 时，应自动带上 `@brawnen/agent-harness-protocol`
 - 默认 npm 入口是 `npx @brawnen/agent-harness-cli init`
-- 当前仓库以 Node.js CLI 作为唯一主线实现
+- 当前仓库将 Node.js CLI 视为 `Agent Harness Runtime` 的 compatibility layer
+- repo-local hooks 当前应通过 `@brawnen/agent-harness-cli/runtime-host` 这一稳定入口接入 runtime

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@brawnen/agent-harness-cli",
-  "version": "0.1.0",
-  "description": "CLI for task convergence, verification, reporting, and delivery in agent-harness projects.",
+  "version": "0.1.2",
+  "description": "Compatibility CLI for bootstrap, status, and manual fallback in agent-harness projects.",
   "license": "MIT",
   "bin": {
     "agent-harness": "./bin/agent-harness.js"
   },
+  "exports": {
+    "./runtime-host": "./src/runtime-host/index.js"
+  },
   "type": "module",
   "files": [
     "bin",
@@ -35,10 +38,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@brawnen/agent-harness-protocol": "^0.1.0"
+    "@brawnen/agent-harness-protocol": "^0.1.2"
   },
   "scripts": {
-    "start": "node ./bin/agent-harness.js --help"
+    "start": "node ./bin/agent-harness.js --help",
+    "verify:codex-e2e": "node ./scripts/verify-codex-e2e.js",
+    "verify:host-hooks": "node ./scripts/verify-host-hooks-smoke.js",
+    "verify:init-status": "node ./scripts/verify-host-init-status.js",
+    "verify:status-compat": "node ./scripts/verify-sync-status-compat.js",
+    "verify:task-core": "node ./scripts/verify-task-core-classification.js"
   },
   "engines": {
     "node": ">=18"

package/src/commands/docs.js

@@ -154,31 +154,33 @@ function buildDesignNoteTemplate(title, context) {
   return [
     `# ${title}`,
     "",
-    "## 背景",
+    "## 决策摘要",
     "",
     `- task_id: \`${context.task_id}\``,
     `- intent: \`${context.intent}\``,
     `- risk_level: \`${context.risk_level}\``,
+    context.goal ? `- goal: ${context.goal}` : "- goal: 待补充",
     "",
-    "## 目标",
+    "## 要解决的问题",
     "",
-    context.goal ? `- ${context.goal}` : "- 待补充",
+    "- 问题：待补充",
     "",
-    "## 作用范围",
+    "## 采用方案",
     "",
-    ...toBulletLines(context.scope),
+    "- 方案：待补充",
     "",
-    "## 方案",
+    "## 为什么选这个方案",
     "",
-    "- 待补充",
+    "- 原因：待补充",
     "",
-    "## 风险与权衡",
+    "## 边界与风险",
     "",
-    "- 待补充",
+    ...toBulletLines(context.scope),
+    "- 风险与权衡：待补充",
     "",
-    "## 验证计划",
+    "## 验证",
     "",
-    "- 待补充",
+    "- 验证方式：待补充",
     ""
   ].join("\n");
 }
@@ -200,9 +202,13 @@ function buildAdrTemplate(title, context) {
     "",
     "## 决策",
     "",
-    "- 待补充",
+    "- 决策内容：待补充",
+    "",
+    "## 备选方案",
+    "",
+    "- 备选方案及放弃原因：待补充",
     "",
-    "## 后果",
+    "## 代价与后果",
     "",
     "- 正面影响：待补充",
     "- 代价与风险：待补充",

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

@@ -3,9 +3,10 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { collectHostLayoutWrites } from "../lib/host-layout.js";
 import { DEFAULT_RUNTIME_DIR, defaultRuntimeRelativePath } from "../lib/runtime-paths.js";
 
-const CLI_VERSION = "0.1.0";
+const CLI_VERSION = "0.1.2";
 const RULE_MODES = new Set(["base", "full"]);
 const HOSTS = new Set(["auto", "claude-code", "codex", "gemini-cli"]);
 const MODES = new Set(["delivery", "explore", "poc"]);
@@ -36,16 +37,19 @@ export function runInit(argv) {
   const project = detectProject(cwd);
   const hosts = resolveHosts(cwd, parsed.options.host);
   const actions = [];
+  const warnings = [];
 
   queueInitActions({
     cwd,
     project,
     hosts,
     options: parsed.options,
-    actions
+    actions,
+    warnings
   });
 
   printPlan(actions, parsed.options.dryRun, cwd, project, hosts);
+  printWarnings(warnings);
 
   if (parsed.options.dryRun) {
     return 0;
@@ -277,8 +281,7 @@ function resolveHosts(cwd, explicitHost) {
 }
 
 function queueInitActions(context) {
-  const { actions, cwd, hosts, options, project } = context;
-  const ruleText = readText(path.join(PROTOCOL_ROOT, "rules", `${options.rules}.md`));
+  const { actions, cwd, hosts, options, project, warnings } = context;
 
   queueWriteAction({
     actions,
@@ -288,13 +291,34 @@ function queueInitActions(context) {
   });
 
   queueProtocolTemplates(actions, cwd, options.force);
-  queueRulesInjection(actions, cwd, hosts, options, ruleText);
+  queueHostLayoutActions(actions, warnings, cwd, hosts, options);
 
   if (!options.protocolOnly) {
     queueRuntimeFiles(actions, cwd);
-    if (hosts.includes("claude-code")) {
-      queueClaudeSettingsMerge(actions, cwd);
-    }
+  }
+}
+
+function queueHostLayoutActions(actions, warnings, cwd, hosts, options) {
+  const layout = collectHostLayoutWrites(cwd, {
+    hosts,
+    includeConfigs: !options.protocolOnly,
+    includeRules: true,
+    rewrite: options.force,
+    seedMissing: true
+  });
+
+  warnings.push(...layout.warnings);
+
+  for (const write of layout.writes) {
+    actions.push({
+      description: describeHostLayoutWrite(write),
+      relativePath: path.relative(cwd, write.targetPath),
+      run: () => {
+        ensureDirectory(path.dirname(write.targetPath));
+        fs.writeFileSync(write.targetPath, write.content, "utf8");
+      },
+      skip: false
+    });
   }
 }
 
@@ -361,6 +385,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({
@@ -666,6 +709,38 @@ function printPlan(actions, dryRun, cwd, project, hosts) {
   }
 }
 
+function printWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) {
+    return;
+  }
+
+  console.log("");
+  console.log("提示：");
+  for (const warning of warnings) {
+    console.log(`  - ${warning}`);
+  }
+}
+
+function describeHostLayoutWrite(write) {
+  if (write.type === "source") {
+    return "写入收敛布局源文件";
+  }
+
+  if (write.type === "host") {
+    return "生成宿主薄壳配置";
+  }
+
+  if (write.type === "rule") {
+    return "生成宿主规则文件";
+  }
+
+  if (write.type === "generated") {
+    return "生成布局清单";
+  }
+
+  return "写入布局文件";
+}
+
 function readText(filePath) {
   return fs.readFileSync(filePath, "utf8");
 }

package/src/commands/report.js

@@ -256,15 +256,15 @@ function buildMissingArtifactsMessage(taskId, error, outputPolicy) {
 
     if (artifact === "design_note") {
       const suggestedPath = path.posix.join(outputPolicy.design_note.directory, `${taskId}-design-note.md`);
-      lines.push(`- design_note: 可先执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type design-note --task-id ${taskId} --path ${suggestedPath}\``);
-      lines.push(`  然后在 report 中补上 \`--design-note ${suggestedPath}\``);
+      lines.push(`- design_note: 当前任务命中 design note 条件。若尚未沉淀设计决策，可执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type design-note --task-id ${taskId} --path ${suggestedPath}\``);
+      lines.push(`  完成后在 report 中补上 \`--design-note ${suggestedPath}\``);
       continue;
     }
 
     if (artifact === "adr") {
       const suggestedPath = path.posix.join(outputPolicy.adr.directory, `${taskId}-adr.md`);
-      lines.push(`- adr: 可先执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type adr --task-id ${taskId} --path ${suggestedPath}\``);
-      lines.push(`  然后在 report 中补上 \`--adr ${suggestedPath}\``);
+      lines.push(`- adr: 当前任务命中 ADR 条件。若尚未记录正式决策，可执行 \`node packages/cli/bin/agent-harness.js docs scaffold --type adr --task-id ${taskId} --path ${suggestedPath}\``);
+      lines.push(`  完成后在 report 中补上 \`--adr ${suggestedPath}\``);
     }
   }
 

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}` };
   }