@fitlab-ai/agent-infra 0.9.0 → 0.9.2

package/lib/update.ts

@@ -1,10 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { normalizeAgentClients } from './agent-clients/config.ts';
+import {
+  applyAgentClientReconciliation,
+  planAgentClientReconciliation
+} from './agent-clients/reconcile.ts';
 import { info, ok, err } from './log.ts';
 import { resolveTemplateDir } from './paths.ts';
-import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
-import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from './builtin-tuis.ts';
-import type { BuiltinTUIId } from './builtin-tuis.ts';
+import { renderFile, copySkillDir } from './render.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -24,6 +27,8 @@ type UpdateConfig = {
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
   tuis?: unknown;
+  agentClients?: unknown;
+  customTUIs?: unknown;
 };
 
 type Defaults = {
@@ -40,9 +45,6 @@ const defaults = JSON.parse(
 
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
-const AGENT_INFRA_SANDBOX_TOOL = 'agent-infra';
-const LEGACY_DEFAULT_SANDBOX_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'opencode'];
-const DEFAULT_SANDBOX_TOOLS = [AGENT_INFRA_SANDBOX_TOOL, ...LEGACY_DEFAULT_SANDBOX_TOOLS];
 
 // One-time migration of the legacy project-level PR switch to the three-state
 // `prFlow` preference. `true` (the old default / "PR flow on") maps to the
@@ -63,83 +65,6 @@ function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
   return null;
 }
 
-function isLegacyDefaultSandboxTools(value: unknown): value is string[] {
-  if (!Array.isArray(value) || value.length !== LEGACY_DEFAULT_SANDBOX_TOOLS.length) {
-    return false;
-  }
-  const tools = new Set(value);
-  return LEGACY_DEFAULT_SANDBOX_TOOLS.every((tool) => tools.has(tool));
-}
-
-function migrateSandboxTools(config: UpdateConfig): boolean {
-  const tools = config.sandbox?.tools;
-  if (!isLegacyDefaultSandboxTools(tools)) {
-    return false;
-  }
-  config.sandbox = {
-    ...config.sandbox,
-    tools: [...DEFAULT_SANDBOX_TOOLS]
-  };
-  return true;
-}
-
-function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
-  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
-  if (!top.startsWith('.')) return false;
-
-  const candidate = top.slice(1);
-  if (!KNOWN_PLATFORMS.has(candidate)) return false;
-  return candidate !== platformType;
-}
-
-function syncFileRegistry(config: UpdateConfig, platformType: string, enabledTUIs: Set<BuiltinTUIId>) {
-  config.files ||= {};
-  const before = JSON.stringify({
-    files: {
-      managed: config.files.managed || [],
-      merged: config.files.merged || [],
-      ejected: config.files.ejected || []
-    }
-  });
-  config.files.managed = config.files.managed || [];
-  config.files.merged = config.files.merged || [];
-  config.files.ejected = config.files.ejected || [];
-
-  const allExisting = [
-    ...config.files.managed,
-    ...config.files.merged,
-    ...config.files.ejected
-  ];
-  const added: Pick<FileRegistry, 'managed' | 'merged'> = { managed: [], merged: [] };
-
-  for (const entry of defaults.files.managed) {
-    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
-    if (!allExisting.includes(entry)) {
-      config.files.managed.push(entry);
-      added.managed.push(entry);
-    }
-  }
-  for (const entry of defaults.files.merged) {
-    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
-    if (!allExisting.includes(entry)) {
-      config.files.merged.push(entry);
-      added.merged.push(entry);
-    }
-  }
-
-  const after = JSON.stringify({
-    files: {
-      managed: config.files.managed,
-      merged: config.files.merged,
-      ejected: config.files.ejected
-    }
-  });
-
-  return { added, changed: before !== after };
-}
-
 async function cmdUpdate(): Promise<void> {
   console.log('');
   console.log('  ai update');
@@ -167,24 +92,36 @@ async function cmdUpdate(): Promise<void> {
   const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as UpdateConfig;
   const { project, org, language } = config;
   const platformType = config.platform?.type || defaults.platform.type;
-  const enabledTUIs = resolveEnabledTUIs(config.tuis);
   const replacements = { project, org };
 
+  const normalizedOriginal = normalizeAgentClients(config);
+  const currentRegistry: FileRegistry = {
+    managed: config.files?.managed || [],
+    merged: config.files?.merged || [],
+    ejected: config.files?.ejected || []
+  };
+  const platformAdded = !config.platform;
+  const sandboxAdded = !config.sandbox;
+  const taskAdded = !config.task;
+  const labelsAdded = !config.labels;
+  const prFlowMigrated = migratePrFlow(config);
+  if (platformAdded) config.platform = structuredClone(defaults.platform);
+  if (sandboxAdded) config.sandbox = structuredClone(defaults.sandbox);
+  if (taskAdded) config.task = structuredClone(defaults.task);
+  if (labelsAdded) config.labels = structuredClone(defaults.labels);
+
+  const workflowPlan = planAgentClientReconciliation({
+    config: config as unknown as Record<string, unknown>,
+    mutation: { type: 'replace-state', state: normalizedOriginal.state },
+    projectRoot: process.cwd(),
+    templateRoot: templateDir,
+    platformType,
+    language
+  });
+
   info(`Updating seed files for: ${project}`);
   console.log('');
 
-  // select language-specific template filenames
-  let claudeSrc, geminiSrc, opencodeSrc;
-  if (language === 'zh-CN') {
-    claudeSrc = 'update-agent-infra.zh-CN.md';
-    geminiSrc = 'update-agent-infra.zh-CN.toml';
-    opencodeSrc = 'update-agent-infra.zh-CN.md';
-  } else {
-    claudeSrc = 'update-agent-infra.en.md';
-    geminiSrc = 'update-agent-infra.en.toml';
-    opencodeSrc = 'update-agent-infra.en.md';
-  }
-
   // update skill
   copySkillDir(
     path.join(templateDir, '.agents', 'skills', 'update-agent-infra'),
@@ -206,76 +143,19 @@ async function cmdUpdate(): Promise<void> {
     // Ignore missing legacy script from pre-ESM installs.
   }
 
-  // update Claude command (only if enabled)
-  if (enabledTUIs.has('claude-code')) {
-    renderFile(
-      path.join(templateDir, '.claude', 'commands', claudeSrc),
-      path.join('.claude', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Updated .claude/commands/update-agent-infra.md');
-  }
-
-  // update Gemini command (only if enabled)
-  if (enabledTUIs.has('gemini-cli')) {
-    renderFile(
-      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-      replacements
-    );
-    ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
-  }
-
-  // update OpenCode command (only if enabled)
-  if (enabledTUIs.has('opencode')) {
-    renderFile(
-      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-      path.join('.opencode', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Updated .opencode/commands/update-agent-infra.md');
-  }
-
-  // sync file registry
-  const { added, changed } = syncFileRegistry(config, platformType, enabledTUIs);
+  const added = {
+    managed: workflowPlan.projectAssets.registry.managed.filter(
+      (entry) => !currentRegistry.managed.includes(entry)
+    ),
+    merged: workflowPlan.projectAssets.registry.merged.filter(
+      (entry) => !currentRegistry.merged.includes(entry)
+    )
+  };
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
-  const platformAdded = !config.platform;
-  const sandboxAdded = !config.sandbox;
-  const taskAdded = !config.task;
-  const labelsAdded = !config.labels;
-  const prFlowMigrated = migratePrFlow(config);
-  const sandboxToolsMigrated = !sandboxAdded && migrateSandboxTools(config);
-  let configChanged = changed;
+  const reconcileResult = applyAgentClientReconciliation(workflowPlan);
+  for (const target of reconcileResult.applied) ok(`Updated ${target}`);
 
-  if (platformAdded) {
-    config.platform = structuredClone(defaults.platform);
-    configChanged = true;
-  }
-
-  if (sandboxAdded) {
-    config.sandbox = structuredClone(defaults.sandbox);
-    configChanged = true;
-  }
-
-  if (taskAdded) {
-    config.task = structuredClone(defaults.task);
-    configChanged = true;
-  }
-
-  if (labelsAdded) {
-    config.labels = structuredClone(defaults.labels);
-    configChanged = true;
-  }
-
-  if (prFlowMigrated) {
-    configChanged = true;
-  }
-
-  if (sandboxToolsMigrated) {
-    configChanged = true;
-  }
-
-  if (configChanged) {
+  if (reconcileResult.configUpdated) {
     console.log('');
     if (hasNewEntries) {
       info(`New file entries synced to ${CONFIG_PATH}:`);
@@ -301,9 +181,6 @@ async function cmdUpdate(): Promise<void> {
       if (prFlowMigrated) {
         info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
       }
-      if (sandboxToolsMigrated) {
-        info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} in ${CONFIG_PATH}.`);
-      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -322,10 +199,6 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && prFlowMigrated) {
       info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
     }
-    if (hasNewEntries && sandboxToolsMigrated) {
-      info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} in ${CONFIG_PATH}.`);
-    }
-    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);
   }
 
@@ -333,24 +206,15 @@ async function cmdUpdate(): Promise<void> {
   console.log('');
   ok('Seed files updated successfully!');
   console.log('');
-  if (enabledTUIs.size === 0) {
-    console.log('  No built-in TUI enabled (tuis: []).');
+  if (workflowPlan.nextSteps.length === 0) {
+    console.log('  No Agent Client project integration enabled.');
     console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
     console.log('');
   } else {
     console.log('  Next step: run the full update in your AI TUI:');
     console.log('');
-    const claudeOrOpencode: string[] = [];
-    if (enabledTUIs.has('claude-code')) claudeOrOpencode.push('Claude Code');
-    if (enabledTUIs.has('opencode')) claudeOrOpencode.push('OpenCode');
-    if (claudeOrOpencode.length > 0) {
-      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
-    }
-    if (enabledTUIs.has('gemini-cli')) {
-      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-    }
-    if (enabledTUIs.has('codex')) {
-      console.log('    Codex CLI:               $update-agent-infra');
+    for (const nextStep of workflowPlan.nextSteps) {
+      console.log(`    ${nextStep.displayName}: ${nextStep.command}`);
     }
     console.log('');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -73,7 +73,7 @@
     "typescript": "~7.0"
   },
   "optionalDependencies": {
-    "@lydell/node-pty": "^1.2.0-beta.12"
+    "@lydell/node-pty": "^1.2.0-beta.14"
   },
   "overrides": {
     "axios": "1.18.1"

package/templates/.agents/README.en.md

@@ -218,37 +218,38 @@ Ordinary `managed` files keep their overwrite semantics. A small set of platform
 
 `ejected` entries support literal paths or globs, using the same matching rules as `merged`.
 
-## Built-in TUI Selection
+## Agent Client Configuration
 
-Use the top-level `.agents/.airc.json` `tuis` array to pick which built-in TUIs (`claude-code`, `codex`, `gemini-cli`, `opencode`) agent-infra should install command files for and keep in sync.
+Use the top-level `.agents/.airc.json` `agentClients` array to configure all four built-in clients (`claude-code`, `codex`, `gemini-cli`, `opencode`). Each canonical entry has three fields:
 
-| Value | Meaning |
+| Field | Meaning |
 |-------|---------|
-| `tuis` missing or `null` | All four built-in TUIs are enabled (backward-compatible default for legacy `.airc.json` predating this field). |
-| `tuis: []` | No built-in TUI is managed. Use this when the project only relies on `customTUIs` and does not need any built-in command files installed. |
-| `tuis: [<subset>]` | Only the listed TUIs are managed. Unknown ids are ignored. |
+| `id` | Built-in Agent Client id. The canonical array contains exactly one entry for each built-in client. |
+| `enabled` | Whether agent-infra writes and maintains that client's project integration and seed command. |
+| `installInSandbox` | Whether the sandbox image installs that client's CLI. This is independent from `enabled`. |
 
-`ai init` includes an interactive multi-select for this field:
+Manage these settings without hand-editing JSON:
 
-- Press Enter to accept the default (all built-in TUIs enabled).
-- Type comma-separated numbers or ids (e.g. `1,3` or `claude-code,opencode`) to keep a subset.
-- Type `none` to explicitly disable every built-in TUI (typically combined with a `customTUIs` entry added later).
-- Invalid input (duplicate, out-of-range, unknown id, whitespace-only) aborts init with a non-zero exit code.
+```bash
+ai agent-client list
+ai agent-client status
+ai agent-client enable codex
+ai agent-client disable gemini-cli
+ai agent-client configure
+```
 
-### Side effects of disabling a TUI
+`enable` and `disable` only change `enabled`; `configure` edits both dimensions. `ai init` asks which clients to enable and preserves the displayed defaults when you press Enter. All clients default to `installInSandbox: true`.
 
-When you disable a built-in TUI (either via `ai init` or by hand-editing `.airc.json`), the next `ai update` / `update-agent-infra` will:
+Legacy `tuis` and built-in client ids in `sandbox.tools` are migration inputs only. The next config-writing command converts them into the canonical `agentClients` array and removes the legacy fields. If canonical and legacy values conflict, the command stops without modifying files so the conflict can be resolved explicitly.
 
-- skip seed command writes for that TUI (e.g. `.gemini/commands/<project>/update-agent-infra.toml`);
-- skip the TUI's owned default entries when backfilling `files.managed` / `files.merged`;
-- **clean up existing files** under the TUI's owned path prefix (`.claude/`, `.codex/`, `.gemini/`, `.opencode/`) — these are listed in `report.managed.removed`, mirroring the cleanup behavior when switching `platform`.
+### Side effects of disabling an Agent Client
 
-To opt a specific file out of this cleanup, list it in `files.ejected`; ejected entries owned by disabled TUIs are preserved as-is and are not re-created by sync.
+When you disable a built-in client, reconciliation stops maintaining its seed command and owned registry entries. An unchanged generated seed may be removed; a locally modified seed is protected and reported instead. Files listed in `files.ejected` remain project-owned and are preserved.
 
 ### Relation to other config fields
 
-- `tuis` controls **which TUI command files agent-infra writes and maintains**. It is independent from `sandbox.tools`, which controls **which CLIs the sandbox image installs**. Toggling one does not affect the other; the README for `sandbox.tools` lives in the Sandbox section.
-- `tuis` is independent from `customTUIs` (see below). CustomTUI command files are not removed when you disable a built-in TUI, even if the customTUI's `dir` falls under that TUI's owned prefix (e.g. a customTUI configured with `dir: ".codex/commands"` is preserved when `codex` is disabled).
+- `sandbox.tools` now lists non-client tools such as `agent-infra` and custom tools. Built-in client installation belongs in `agentClients[].installInSandbox`.
+- `agentClients` is independent from `customTUIs` (see below). Custom TUI command files are preserved even when their directory is under a disabled built-in client's path prefix.
 
 ## Custom TUI Configuration
 
@@ -300,7 +301,7 @@ Namespaced custom TUI:
 
 ## Sandbox Custom Tools
 
-`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in sandbox tools (`claude-code`, `codex`, `opencode`, `gemini-cli`, `agent-infra`) keep working unchanged; `agent-infra` only provides the in-sandbox `ai` / `agent-infra` CLI and is not part of `tuis` or `customTUIs`.
+`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in Agent Clients are installed according to `agentClients[].installInSandbox`; `agent-infra` remains a non-client entry in `sandbox.tools` and only provides the in-sandbox `ai` / `agent-infra` CLI.
 
 ### Required fields
 

package/templates/.agents/README.zh-CN.md

@@ -218,37 +218,38 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 
 `ejected` 条目支持字面路径或 glob，匹配规则与 `merged` 相同。
 
-## 内建 TUI 选择
+## Agent Client 配置
 
-`.agents/.airc.json` 顶层 `tuis` 数组用于决定 agent-infra 应当为哪些内建 TUI（`claude-code`、`codex`、`gemini-cli`、`opencode`）安装并维护命令文件。
+`.agents/.airc.json` 顶层 `agentClients` 数组用于配置全部四个内建客户端（`claude-code`、`codex`、`gemini-cli`、`opencode`）。规范化后的每个条目包含三个字段：
 
-| 取值 | 含义 |
+| 字段 | 含义 |
 |------|------|
-| `tuis` 缺失或为 `null` | 启用全部四个内建 TUI（向后兼容默认，适用于本字段引入之前的 `.airc.json`） |
-| `tuis: []` | 不维护任何内建 TUI。适用于只依赖 `customTUIs`、不需要安装任何内建命令文件的项目 |
-| `tuis: [<子集>]` | 仅维护列出的 TUI；未知 id 会被忽略 |
+| `id` | 内建 Agent Client id。规范数组为每个内建客户端保留且仅保留一个条目。 |
+| `enabled` | agent-infra 是否写入并维护该客户端的项目集成与种子命令。 |
+| `installInSandbox` | 沙箱镜像是否安装该客户端 CLI；此字段与 `enabled` 相互独立。 |
 
-`ai init` 会通过交互式多选询问该字段：
+无需手工编辑 JSON，可使用：
 
-- 直接回车 = 接受默认值（全部内建 TUI 启用）。
-- 输入逗号分隔的编号或 id（如 `1,3` 或 `claude-code,opencode`）= 只保留子集。
-- 输入 `none` = 明确不启用任何内建 TUI（通常配合后续在 `customTUIs` 添加条目使用）。
-- 非法输入（重复、超界、未知 id、纯空白）会让 init 以非零退出码终止。
+```bash
+ai agent-client list
+ai agent-client status
+ai agent-client enable codex
+ai agent-client disable gemini-cli
+ai agent-client configure
+```
 
-### 取消某个 TUI 的副作用
+`enable` 和 `disable` 只修改 `enabled`；`configure` 同时编辑两个维度。`ai init` 会询问启用哪些客户端，直接回车会保留界面展示的默认值。所有客户端的 `installInSandbox` 默认均为 `true`。
 
-通过 `ai init` 或手工编辑 `.airc.json` 取消某个内建 TUI 后，下一次 `ai update` / `update-agent-infra` 会：
+旧 `tuis` 字段和 `sandbox.tools` 中的内建客户端 id 仅作为迁移输入。下一次写配置的命令会将其转换为规范 `agentClients` 数组并移除旧字段。若规范配置与旧配置冲突，命令会在修改文件前停止，要求显式解决冲突。
 
-- 跳过该 TUI 的 seed 命令文件写入（例如 `.gemini/commands/<project>/update-agent-infra.toml`）；
-- 在回填 `files.managed` / `files.merged` 时跳过该 TUI owned 的默认条目；
-- **物理清理**该 TUI owned 路径前缀（`.claude/`、`.codex/`、`.gemini/`、`.opencode/`）下的已有文件——清理列表会出现在 `report.managed.removed`，与切换 `platform` 时的清理行为一致。
+### 取消 Agent Client 的副作用
 
-若希望保留某个具体文件，把它加入 `files.ejected`：被 ejected 的、属于已取消 TUI 的条目会保持原状，sync 不会重新创建也不会删除。
+取消某个内建客户端后，协调流程会停止维护其种子命令和 owned 注册项。未修改的生成种子文件可以被删除；本地修改过的种子文件会受到保护并进入报告。`files.ejected` 中的文件仍由项目所有并会被保留。
 
 ### 与其他配置字段的关系
 
-- `tuis` 控制 **agent-infra 写入与维护哪些 TUI 的命令文件**，与 `sandbox.tools`（控制**沙箱镜像里安装哪些 CLI**）相互独立。两者互不影响；`sandbox.tools` 的说明见 Sandbox 一节。
-- `tuis` 与 `customTUIs`（见下）相互独立。取消某个内建 TUI 时 customTUI 命令文件不会被清理，即便 customTUI 的 `dir` 落在该 TUI 的 owned 前缀下（例如 `dir: ".codex/commands"` 的 customTUI 在 `codex` 被取消时仍会保留）。
+- `sandbox.tools` 现在只列出 `agent-infra` 和自定义工具等非客户端工具。内建客户端的安装状态由 `agentClients[].installInSandbox` 表达。
+- `agentClients` 与 `customTUIs`（见下）相互独立。即使自定义 TUI 目录落在已取消的内建客户端路径前缀下，其命令文件也会被保留。
 
 ## 自定义 TUI 配置
 
@@ -300,7 +301,7 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 
 ## 沙箱自定义工具（Sandbox Custom Tools）
 
-`customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 CLI 或工具（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建 sandbox 工具（`claude-code` / `codex` / `opencode` / `gemini-cli` / `agent-infra`）行为保持不变；其中 `agent-infra` 只提供沙箱内 `ai` / `agent-infra` CLI，不属于 `tuis` 或 `customTUIs` 配置。
+`customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 CLI 或工具（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建 Agent Client 按 `agentClients[].installInSandbox` 安装；`agent-infra` 仍是 `sandbox.tools` 中的非客户端条目，只提供沙箱内的 `ai` / `agent-infra` CLI。
 
 ### 必填字段
 

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -0,0 +1,64 @@
+import { execFileSync } from 'node:child_process';
+
+const MAX_INPUT_BYTES = 64 * 1024;
+const clientIndex = process.argv.indexOf('--client');
+const client = clientIndex >= 0 ? process.argv[clientIndex + 1] : '';
+if (client !== 'claude-code') {
+  process.stderr.write('Lifecycle delegation hook requires a supported --client value\n');
+  process.exit(1);
+}
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+  if (Buffer.byteLength(input) > MAX_INPUT_BYTES) {
+    process.stderr.write('Lifecycle delegation hook input exceeds 64 KiB\n');
+    process.exit(1);
+  }
+});
+process.stdin.on('end', () => {
+  let event;
+  try {
+    event = JSON.parse(input || '{}');
+  } catch {
+    process.stderr.write('Lifecycle delegation hook received invalid JSON\n');
+    process.exit(1);
+  }
+  const hook = String(event.hook_event_name || event.event || '').toLowerCase();
+  const nativeAgent = event.agent_name || event.agent_type || event.agent?.name;
+  if (!String(nativeAgent || '').startsWith('agent-infra-lifecycle-')) process.exit(0);
+  const start = hook.includes('start');
+  const stop = hook.includes('stop');
+  if (!start && !stop) {
+    process.stderr.write('Managed lifecycle hook event has an unknown type\n');
+    process.exit(1);
+  }
+  const args = ['task-orchestration', 'auto', start ? 'hook-start' : 'hook-stop', '--client', client];
+  if (start) {
+    args.push(
+      '--native-agent', String(nativeAgent),
+      '--child-id', String(event.child_id || event.agent_id || event.thread_id || ''),
+      '--parent-id', String(event.parent_id || event.parent_session_id || event.session_id || ''),
+      '--spawn-mode', String(event.spawn_mode || 'fresh')
+    );
+    if (event.model) args.push('--actual-model', String(event.model));
+    if (event.model_fallback_reason) args.push('--fallback-reason', String(event.model_fallback_reason));
+  } else {
+    args.push(
+      '--native-agent', String(nativeAgent),
+      '--child-id', String(event.child_id || event.agent_id || event.thread_id || '')
+    );
+  }
+  try {
+    const output = execFileSync('agent-infra-internal', args, {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    process.stdout.write(output);
+  } catch (error) {
+    if (error.stdout) process.stdout.write(String(error.stdout));
+    if (error.stderr) process.stderr.write(String(error.stderr));
+    process.exit(typeof error.status === 'number' ? error.status : 1);
+  }
+});

package/templates/.agents/rules/README.en.md

@@ -25,7 +25,9 @@ so you can quickly find "which ones to read" without opening each file.
 ## Task Workflow
 
 - [`task-management.md`](task-management.md) — Task intent detection and workflow-command mapping.
+- [`lifecycle-orchestration.md`](lifecycle-orchestration.md) — Fresh executor/reviewer, one-use receipt, pause/recovery, and safe endpoint rules for `run-task`.
 - [`review-handshake.md`](review-handshake.md) — Three-stage bidirectional review handshake: four-state disposition, symmetric evidence, disagreement ledger, convergence and post-review commit gate.
+- [`review-method.md`](review-method.md) — Shared three-stage review method: multi-pass review, risk lenses, traceability, and finding evidence.
 - [`human-decision-context.md`](human-decision-context.md) — Self-contained context and canonical structure for new human-decision details.
 - [`task-short-id.md`](task-short-id.md) — Resolution, allocation and lifecycle of bare-number short ids.
 - [`milestone-inference.md`](milestone-inference.md) — Milestone inference for create-task / code-task / create-pr.

package/templates/.agents/rules/README.zh-CN.md

@@ -24,7 +24,9 @@
 ## 任务工作流
 
 - [`task-management.md`](task-management.md) — 任务语义识别与工作流命令映射。
+- [`lifecycle-orchestration.md`](lifecycle-orchestration.md) — `run-task` 的 fresh executor/reviewer、一次性 receipt、暂停恢复与安全终点规则。
 - [`review-handshake.md`](review-handshake.md) — 三阶段双向审查握手协议：四态处置、对称证据、分歧账本、收敛与 post-review commit 门禁。
+- [`review-method.md`](review-method.md) — 三阶段共享检视方法：多遍检视、风险镜头、追踪与 finding 证据契约。
 - [`human-decision-context.md`](human-decision-context.md) — 新建人工裁决详情的自足上下文与规范结构。
 - [`task-short-id.md`](task-short-id.md) — 裸数字任务短号的解析、分配与生命周期。
 - [`milestone-inference.md`](milestone-inference.md) — create-task / code-task / create-pr 的 milestone 推断。

package/templates/.agents/rules/commit-and-pr.en.md

@@ -11,6 +11,7 @@
 
 - Never run `git commit` or `git add` automatically
 - Enter the commit workflow only when the user explicitly requests a commit
+- The only exception is a one-use commit authorization issued by an active `run-task` explicitly started by the user. It authorizes this commit round but does not relax staging, sensitive-file, copyright, test, review-snapshot, HEAD/tree, or push gates.
 - After finishing code changes, remind the user to use the appropriate TUI commit command
 
 ## PR Rules

package/templates/.agents/rules/commit-and-pr.zh-CN.md

@@ -11,6 +11,7 @@
 
 - 绝对不要自动执行 `git commit` 或 `git add`
 - 仅在用户明确发起提交命令时才进入提交流程
+- 唯一例外：用户显式启动的 active `run-task` 可签发一次性 commit authorization；它等价于本轮提交授权，但不得放宽暂存、敏感文件、版权、测试、审查快照、HEAD/tree 或 push 门禁。
 - 完成代码修改后，提醒用户使用对应 TUI 的提交命令
 
 ## PR 提交规则

package/templates/.agents/rules/human-decision-context.en.md

@@ -4,32 +4,34 @@ This rule governs every new `[needs-human-decision]` detail block produced by an
 
 ## Self-contained Context
 
-A maintainer must be able to decide without asking a model to reconstruct context. Every item must state its background, decision objective, impact scope, risks, recommended option, and recommendation rationale. It must provide at least two options, each with both benefits and costs.
+A maintainer must be able to understand the issue and choose without knowing the internal workflow or asking a model to reconstruct context. Start in plain language: explain why a decision is needed now, what must be chosen, which choice is recommended, and why. Then explain what the choice affects and what could go wrong if the wrong choice is made or no action is taken.
+
+Provide at least two options with short names, and state the benefits and trade-offs of each one. Explain internal terms such as stage, severity, and evidence the first time they appear. IDs and evidence are for lookup and troubleshooting; they do not replace the plain-language explanation.
 
 ## Canonical Structure
 
 ```markdown
 ### {AN-N|PL-N|CD-N|HD-N}: {Title} [needs-human-decision]
 
-- **Background**: {facts, constraints, and why a decision is needed}
-- **Decision Objective**: {the single choice that must be made}
-- **Impact Scope**: {affected behavior, files, users, or precedent}
-- **Risks**: {risks of the wrong choice, delay, or no decision}
-- **Recommended Option**: {Option A/B/...}
-- **Recommendation Rationale**: {reason based on benefits, costs, and constraints}
+- **Why a decision is needed now**: {plain-language facts, constraints, and why work cannot simply continue}
+- **What needs a decision**: {the one choice that must be made}
+- **Recommended choice**: {Option A/B/...}
+- **Why this choice**: {reason based on benefits, trade-offs, and current constraints}
+- **What this affects**: {affected behavior, files, users, or future practice}
+- **What could go wrong**: {problems caused by the wrong choice or no action}
 
 #### Option A: {Name}
 
-- **Benefits**: {benefits of this option}
-- **Costs**: {costs and limitations of this option}
+- **Benefits**: {what this option provides}
+- **Trade-offs**: {what this option costs and where it falls short}
 
 #### Option B: {Name}
 
-- **Benefits**: {benefits of this option}
-- **Costs**: {costs and limitations of this option}
+- **Benefits**: {what this option provides}
+- **Trade-offs**: {what this option costs and where it falls short}
 ```
 
-Option C and supporting evidence may be added, but none of the fields above may be omitted or collapsed into an incomparable one-line option list. The heading ID must match the task.md Review Disagreement Ledger row, whose evidence must point to this stable heading anchor.
+Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
 
 ## Decision Closure