@fitlab-ai/agent-infra 0.6.4 → 0.7.0

package/lib/sandbox/tools.ts

@@ -1,10 +1,14 @@
 import { safeNameCandidates, sanitizeBranchName } from './constants.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
 
+export type SandboxToolInstall =
+  | { type: 'npm'; cmd: string }
+  | { type: 'shell'; cmd: string };
+
 export type SandboxTool = {
   id: string;
   name: string;
-  npmPackage: string;
+  install: SandboxToolInstall;
   sandboxBase: string;
   containerMount: string;
   versionCmd: string;
@@ -21,14 +25,17 @@ type ToolsConfig = {
   home: string;
   project: string;
   tools: string[];
+  customTools?: SandboxTool[];
 };
 
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
 function createBuiltinTools(home: string, project: string): Record<string, SandboxTool> {
   return {
     'claude-code': {
       id: 'claude-code',
       name: 'Claude Code',
-      npmPackage: '@anthropic-ai/claude-code@stable',
+      install: { type: 'npm', cmd: '@anthropic-ai/claude-code@stable' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
       containerMount: '/home/devuser/.claude',
       versionCmd: 'claude --version',
@@ -58,7 +65,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     codex: {
       id: 'codex',
       name: 'Codex',
-      npmPackage: '@openai/codex',
+      install: { type: 'npm', cmd: '@openai/codex' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'codex'),
       containerMount: '/home/devuser/.codex',
       versionCmd: 'codex --version',
@@ -73,7 +80,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     opencode: {
       id: 'opencode',
       name: 'OpenCode',
-      npmPackage: 'opencode-ai',
+      install: { type: 'npm', cmd: 'opencode-ai' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'opencode'),
       containerMount: '/home/devuser/.local/share/opencode',
       versionCmd: 'opencode version',
@@ -92,7 +99,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     'gemini-cli': {
       id: 'gemini-cli',
       name: 'Gemini CLI',
-      npmPackage: '@google/gemini-cli',
+      install: { type: 'npm', cmd: '@google/gemini-cli' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
       containerMount: '/home/devuser/.gemini',
       versionCmd: 'gemini --version',
@@ -108,16 +115,224 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
   };
 }
 
+export function builtinToolIds(): string[] {
+  return Object.keys(createBuiltinTools('', ''));
+}
+
 function validateTool(tool: SandboxTool): void {
-  if (!tool.npmPackage || !tool.containerMount.startsWith('/')) {
-    throw new Error(`Invalid sandbox tool descriptor: ${tool.id}`);
+  if (!tool.id || !TOOL_ID_PATTERN.test(tool.id)) {
+    throw new Error(`Invalid sandbox tool id: ${String(tool.id)}`);
+  }
+  if (!tool.install || (tool.install.type !== 'npm' && tool.install.type !== 'shell')) {
+    throw new Error(`Sandbox tool ${tool.id} has invalid install.type`);
+  }
+  if (!tool.install.cmd) {
+    throw new Error(`Sandbox tool ${tool.id} has empty install.cmd`);
+  }
+  if (!tool.containerMount || !tool.containerMount.startsWith('/')) {
+    throw new Error(`Sandbox tool ${tool.id} containerMount must be an absolute path`);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown, field: string, context: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`${context}: field "${field}" must be a string`);
+  }
+  return value;
+}
+
+function asOptionalNonEmptyString(value: unknown, field: string, context: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== 'string') {
+    throw new Error(`${context}: field "${field}" must be a string when provided`);
+  }
+  if (value.length === 0) {
+    throw new Error(`${context}: field "${field}" must be non-empty when provided`);
+  }
+  return value;
+}
+
+function asStringRecord(value: unknown, field: string, context: string): Record<string, string> | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(value)) {
+    throw new Error(`${context}: field "${field}" must be an object when provided`);
+  }
+  const out: Record<string, string> = {};
+  for (const [key, val] of Object.entries(value)) {
+    if (typeof val !== 'string') {
+      throw new Error(`${context}: field "${field}.${key}" must be a string`);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+function asStringArray(value: unknown, field: string, context: string): string[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "${field}" must be an array when provided`);
+  }
+  return value.map((item, index) => {
+    if (typeof item !== 'string') {
+      throw new Error(`${context}: field "${field}[${index}]" must be a string`);
+    }
+    return item;
+  });
+}
+
+function parseInstall(value: unknown, context: string): SandboxToolInstall {
+  if (!isPlainObject(value)) {
+    throw new Error(`${context}: field "install" must be an object`);
+  }
+  const type = value.type;
+  if (type !== 'npm' && type !== 'shell') {
+    throw new Error(`${context}: field "install.type" must be "npm" or "shell"`);
+  }
+  const cmd = asString(value.cmd, 'install.cmd', context);
+  if (!cmd) {
+    throw new Error(`${context}: field "install.cmd" must be non-empty`);
+  }
+  return { type, cmd };
+}
+
+function parseHostPreSeedFiles(value: unknown, context: string): SandboxTool['hostPreSeedFiles'] {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "hostPreSeedFiles" must be an array when provided`);
+  }
+  return value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new Error(`${context}: field "hostPreSeedFiles[${index}]" must be an object`);
+    }
+    return {
+      hostPath: asString(item.hostPath, `hostPreSeedFiles[${index}].hostPath`, context),
+      sandboxName: asString(item.sandboxName, `hostPreSeedFiles[${index}].sandboxName`, context)
+    };
+  });
+}
+
+function parseHostPreSeedDirs(value: unknown, context: string): SandboxTool['hostPreSeedDirs'] {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "hostPreSeedDirs" must be an array when provided`);
   }
+  return value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new Error(`${context}: field "hostPreSeedDirs[${index}]" must be an object`);
+    }
+    return {
+      hostDir: asString(item.hostDir, `hostPreSeedDirs[${index}].hostDir`, context),
+      sandboxSubdir: asString(item.sandboxSubdir, `hostPreSeedDirs[${index}].sandboxSubdir`, context)
+    };
+  });
+}
+
+function parseHostLiveMounts(value: unknown, context: string): SandboxTool['hostLiveMounts'] {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "hostLiveMounts" must be an array when provided`);
+  }
+  return value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new Error(`${context}: field "hostLiveMounts[${index}]" must be an object`);
+    }
+    return {
+      hostPath: asString(item.hostPath, `hostLiveMounts[${index}].hostPath`, context),
+      containerSubpath: asString(item.containerSubpath, `hostLiveMounts[${index}].containerSubpath`, context)
+    };
+  });
+}
+
+export function parseCustomTool(
+  entry: unknown,
+  index: number,
+  options: { home: string }
+): SandboxTool {
+  const context = `customTools[${index}]`;
+  if (!isPlainObject(entry)) {
+    throw new Error(`${context} must be an object`);
+  }
+
+  const id = asString(entry.id, 'id', context);
+  if (!TOOL_ID_PATTERN.test(id)) {
+    throw new Error(`${context}: field "id" must match ${TOOL_ID_PATTERN.source}`);
+  }
+
+  const containerMount = asOptionalNonEmptyString(entry.containerMount, 'containerMount', context)
+    ?? `/home/devuser/.${id}`;
+  if (!containerMount.startsWith('/')) {
+    throw new Error(`${context}: field "containerMount" must be an absolute path`);
+  }
+
+  const tool: SandboxTool = {
+    id,
+    name: asOptionalNonEmptyString(entry.name, 'name', context) ?? id,
+    install: parseInstall(entry.install, context),
+    sandboxBase: hostJoin(options.home, '.agent-infra', 'sandboxes', id),
+    containerMount,
+    versionCmd: asOptionalNonEmptyString(entry.versionCmd, 'versionCmd', context) ?? `which ${id}`,
+    setupHint: asOptionalNonEmptyString(entry.setupHint, 'setupHint', context)
+      ?? `Run \`${id}\` inside the container to set up.`,
+    envVars: asStringRecord(entry.envVars, 'envVars', context),
+    hostPreSeedFiles: parseHostPreSeedFiles(entry.hostPreSeedFiles, context),
+    hostPreSeedDirs: parseHostPreSeedDirs(entry.hostPreSeedDirs, context),
+    pathRewriteFiles: asStringArray(entry.pathRewriteFiles, 'pathRewriteFiles', context),
+    hostLiveMounts: parseHostLiveMounts(entry.hostLiveMounts, context),
+    postSetupCmds: asStringArray(entry.postSetupCmds, 'postSetupCmds', context)
+  };
+
+  validateTool(tool);
+  return tool;
+}
+
+export function parseCustomTools(value: unknown, options: { home: string }): SandboxTool[] {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error('sandbox: "customTools" must be an array');
+  }
+  return value.map((entry, index) => parseCustomTool(entry, index, options));
 }
 
 export function resolveTools(config: ToolsConfig): SandboxTool[] {
   const builtins = createBuiltinTools(config.home, config.project);
+  const customs = config.customTools ?? [];
+
+  const seen = new Set<string>();
+  for (const tool of customs) {
+    if (builtins[tool.id]) {
+      throw new Error(`Custom sandbox tool id "${tool.id}" collides with a built-in tool`);
+    }
+    if (seen.has(tool.id)) {
+      throw new Error(`Duplicate sandbox tool id "${tool.id}" in customTools`);
+    }
+    seen.add(tool.id);
+  }
+
+  const merged: Record<string, SandboxTool> = { ...builtins };
+  for (const tool of customs) {
+    merged[tool.id] = tool;
+  }
+
   return config.tools.map((id) => {
-    const tool = builtins[id];
+    const tool = merged[id];
     if (!tool) {
       throw new Error(`Unknown sandbox tool: ${id}`);
     }
@@ -139,5 +354,29 @@ export function toolProjectDirCandidates(tool: SandboxTool, project: string): st
 }
 
 export function toolNpmPackagesArg(tools: SandboxTool[]): string {
-  return tools.map((tool) => tool.npmPackage).join(' ');
+  return tools
+    .filter((tool) => tool.install.type === 'npm')
+    .map((tool) => tool.install.cmd)
+    .join(' ');
+}
+
+export function toolShellInstallScript(tools: SandboxTool[]): string {
+  const blocks = tools
+    .filter((tool) => tool.install.type === 'shell')
+    .map((tool) => `# install: ${tool.id}\n${tool.install.cmd}`);
+
+  if (blocks.length === 0) {
+    return '';
+  }
+
+  return ['#!/bin/bash', 'set -e', '', ...blocks, ''].join('\n');
+}
+
+export function toolShellInstallScriptBase64(tools: SandboxTool[]): string {
+  const script = toolShellInstallScript(tools);
+  return script ? Buffer.from(script, 'utf8').toString('base64') : '';
+}
+
+export function imageSignatureFields(tools: SandboxTool[]): Array<{ id: string; install: SandboxToolInstall }> {
+  return tools.map((tool) => ({ id: tool.id, install: tool.install }));
 }

package/lib/update.ts

@@ -15,6 +15,7 @@ type UpdateConfig = {
   org: string;
   language: string;
   platform?: { type?: string };
+  requiresPullRequest?: boolean;
   sandbox?: Record<string, unknown>;
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
@@ -22,6 +23,7 @@ type UpdateConfig = {
 
 type Defaults = {
   platform: { type: string };
+  requiresPullRequest: boolean;
   sandbox: Record<string, unknown>;
   labels: Record<string, unknown>;
   files: FileRegistry;
@@ -178,6 +180,7 @@ async function cmdUpdate(): Promise<void> {
   const platformAdded = !config.platform;
   const sandboxAdded = !config.sandbox;
   const labelsAdded = !config.labels;
+  const requiresPullRequestAdded = config.requiresPullRequest === undefined;
   let configChanged = changed;
 
   if (platformAdded) {
@@ -195,6 +198,11 @@ async function cmdUpdate(): Promise<void> {
     configChanged = true;
   }
 
+  if (requiresPullRequestAdded) {
+    config.requiresPullRequest = defaults.requiresPullRequest;
+    configChanged = true;
+  }
+
   if (configChanged) {
     console.log('');
     if (hasNewEntries) {
@@ -205,7 +213,7 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || labelsAdded) {
+    } else if (platformAdded || sandboxAdded || labelsAdded || requiresPullRequestAdded) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
@@ -215,6 +223,9 @@ async function cmdUpdate(): Promise<void> {
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
+      if (requiresPullRequestAdded) {
+        info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -227,6 +238,9 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && platformAdded) {
       info(`Default platform config added to ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && requiresPullRequestAdded) {
+      info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+    }
     fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/QUICKSTART.en.md

@@ -164,7 +164,7 @@ The receiving AI should read this document first to get up to speed.
 
 ### 1. One AI Per Phase
 
-Don't have multiple AIs working on the same files simultaneously. Follow the sequential workflow: analyze, design, implement, review, fix, commit.
+Don't have multiple AIs working on the same files simultaneously. Follow the sequential workflow: analysis → analysis-review → design → design-review → code → code-review → commit (when any review finds issues, re-run the matching upstream stage).
 
 ### 2. Always Create Handoff Documents
 

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

@@ -164,7 +164,7 @@ cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2
 
 ### 1. 每个阶段一个 AI
 
-不要让多个 AI 同时处理相同的文件。遵循顺序工作流：分析、设计、实现、审查、修复、提交。
+不要让多个 AI 同时处理相同的文件。遵循顺序工作流：分析 → 分析审查 → 设计 → 设计审查 → 编码 → 代码审查 → 提交（任一审查发现问题时，回到同名上游阶段重跑）。
 
 ### 2. 始终创建交接文档
 

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

@@ -224,8 +224,8 @@ Supported `invoke` placeholders:
 
 | Placeholder | Replaced with | Example |
 |-------------|---------------|---------|
-| `${skillName}` | The skill command name, such as `review-task` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-task` |
-| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+| `${skillName}` | The skill command name, such as `review-code` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
+| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
 
 Non-namespaced custom TUI:
 
@@ -258,6 +258,83 @@ Namespaced custom TUI:
 
 `customTUIs` should contain one entry per custom TUI. To let `update-agent-infra` generate command files for custom skills, keep at least one existing command file in `dir` that references a built-in skill path such as `.agents/skills/analyze-task/SKILL.md`; agent-infra uses that file as the format reference.
 
+## Sandbox Custom Tools
+
+`customTUIs` (above) generates slash-command files but does not change the sandbox image. To install a non-npm TUI (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 tools (`claude-code`, `codex`, `opencode`, `gemini-cli`) keep working unchanged.
+
+### Required fields
+
+| Field | Meaning |
+|-------|---------|
+| `id` | Lowercase id matching `^[a-z0-9][a-z0-9-]*$`. Referenced from `sandbox.tools`. Must not collide with a built-in id. |
+| `install` | Install descriptor. `{ "type": "npm", "cmd": "<npm package spec>" }` runs `npm install -g <cmd>`. `{ "type": "shell", "cmd": "<shell>" }` runs the shell command(s) as `devuser` during image build. `cmd` must be non-empty. |
+
+Minimal entry — the contract for getting a tool into the image is just these two fields:
+
+```json
+{
+  "sandbox": {
+    "tools": ["my-shell-tool"],
+    "customTools": [
+      {
+        "id": "my-shell-tool",
+        "install": { "type": "shell", "cmd": "curl -fsSL https://example.com/install.sh | bash" }
+      }
+    ]
+  }
+}
+```
+
+### Optional integration fields
+
+Add only the fields your tool actually needs. Omit them and the loader fills sensible defaults; provide them and the loader uses your value. Provide an explicit empty string and the loader rejects it (preventing silent install-verification bypass).
+
+| Field | Default when omitted | When to provide |
+|-------|---------------------|-----------------|
+| `name` | `id` | A friendlier display name in sandbox reports / hints. |
+| `containerMount` | `/home/devuser/.<id>` | Your tool stores its config / state somewhere other than `~/.<id>`. Must be an absolute path. |
+| `versionCmd` | `which <id>` | The installed binary name differs from `id` (e.g. id `anthropic-claude`, binary `claude`); set `"claude --version"` so sandbox-create can verify the install. |
+| `setupHint` | `Run \`<id>\` inside the container to set up.` | The setup story is non-obvious and worth a one-liner. |
+| `envVars` | (none) | Your tool reads config from a path the env points to (e.g. `XDG_CONFIG_HOME`-style or a custom `*_CONFIG` env). Shape: `Record<string, string>`. |
+| `hostPreSeedFiles` / `hostPreSeedDirs` | (none) | Seed the tool's sandbox dir from host files / directories on first launch. |
+| `pathRewriteFiles` | (none) | Seeded files contain absolute host paths that need rewriting to container paths. |
+| `hostLiveMounts` | (none) | Share host credentials live (e.g. OAuth tokens) with the container. Read-write. |
+| `postSetupCmds` | (none) | Run commands inside the container after first setup (e.g. symlinks). |
+
+> **`sandboxBase` is not user-configurable.** The loader always assigns `~/.agent-infra/sandboxes/<id>` so `ai sandbox rm` / `prune` can find tool state. Any `sandboxBase` value in `customTools` entries is silently ignored.
+
+Real-world example — `anthropic-claude` as a user-defined id with binary name `claude` and host credential live-mount:
+
+```json
+{
+  "sandbox": {
+    "tools": ["claude-code", "anthropic-claude"],
+    "customTools": [
+      {
+        "id": "anthropic-claude",
+        "install": { "type": "npm", "cmd": "@anthropic-ai/claude-code@stable" },
+        "versionCmd": "claude --version",
+        "hostLiveMounts": [
+          { "hostPath": "~/.claude/.credentials.json", "containerSubpath": ".credentials.json" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Trust boundary and execution context
+
+- `install.cmd` runs as user `devuser` (non-root) during `docker build`. It can write to the container's filesystem but cannot escape to the host. The trust model is the same as for the `sandbox.dockerfile` escape hatch — you own the `.airc.json` in your repo, so you own what runs at build time.
+- Because the build runs as `devuser`, shell installs cannot `sudo` / `apt-get`. Available options for non-npm distributions:
+  - User-scope installers landing in `~/.local/bin`, `~/.cargo/bin`, `~/.npm-global/bin` (e.g. `pipx`, `cargo install`, `curl … | bash` with `INSTALL_DIR=$HOME/.local/bin`).
+  - When you genuinely need root or system packages, fall back to the existing `sandbox.dockerfile` field and own the full Dockerfile.
+- Changing `install.cmd` (or any field that participates in the image signature) triggers exactly one image rebuild on the next `ai sandbox` invocation.
+
+### Interaction with `sandbox.dockerfile`
+
+When you set `sandbox.dockerfile` to point at your own Dockerfile, agent-infra still passes both `AI_TOOL_PACKAGES` (space-separated npm package specs) and `AI_TOOLS_SHELL_INSTALL_B64` (base64-encoded shell install script) as `--build-arg`. Your custom Dockerfile decides whether to consume them; if it does not declare the matching `ARG`, the shell installs for `customTools` are silently skipped — taking over the Dockerfile means taking over the install path.
+
 ## Skill Authoring Conventions
 
 When writing or updating `.agents/skills/*/SKILL.md` files and their templates, keep step numbering consistent:

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

@@ -224,8 +224,8 @@ args: "<task-id>"   # 可选
 
 | 占位符 | 替换为 | 示例 |
 |--------|--------|------|
-| `${skillName}` | skill 命令名，例如 `review-task` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-task` |
-| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+| `${skillName}` | skill 命令名，例如 `review-code` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
 
 不带命名空间的自定义 TUI：
 
@@ -258,6 +258,83 @@ args: "<task-id>"   # 可选
 
 `customTUIs` 每个条目对应一个自定义 TUI。若希望 `update-agent-infra` 为自定义 skill 生成命令文件，请在 `dir` 中保留至少一个引用内置 skill 路径的既有命令文件，例如 `.agents/skills/analyze-task/SKILL.md`；agent-infra 会以该文件作为格式参考。
 
+## 沙箱自定义工具（Sandbox Custom Tools）
+
+上文 `customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 TUI（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建的四个工具（`claude-code` / `codex` / `opencode` / `gemini-cli`）行为保持不变。
+
+### 必填字段
+
+| 字段 | 含义 |
+|------|------|
+| `id` | 小写 id，匹配 `^[a-z0-9][a-z0-9-]*$`；由 `sandbox.tools` 引用；不可与内建 id 冲突。 |
+| `install` | 安装描述符。`{ "type": "npm", "cmd": "<npm 包规范>" }` 执行 `npm install -g <cmd>`；`{ "type": "shell", "cmd": "<shell>" }` 在镜像构建阶段以 `devuser` 执行 shell。`cmd` 必须非空。 |
+
+最小入口——把一个工具装进镜像所需的契约只有这两个字段：
+
+```json
+{
+  "sandbox": {
+    "tools": ["my-shell-tool"],
+    "customTools": [
+      {
+        "id": "my-shell-tool",
+        "install": { "type": "shell", "cmd": "curl -fsSL https://example.com/install.sh | bash" }
+      }
+    ]
+  }
+}
+```
+
+### 可选集成字段
+
+只在你的工具真正需要时才加。**省略**则 loader 用合理默认值；**显式提供**则用你给的值；**显式给空串**会被拒绝（防止安装验证被绕过）。
+
+| 字段 | 省略时的默认值 | 什么时候应该提供 |
+|------|---------------|----------------|
+| `name` | `id` | 想在沙箱报告 / 提示里显示更友好的名称。 |
+| `containerMount` | `/home/devuser/.<id>` | 工具的配置 / 状态目录不在 `~/.<id>` 而在别处。必须是绝对路径。 |
+| `versionCmd` | `which <id>` | 安装后的可执行文件名与 `id` 不同（例如 id 是 `anthropic-claude`，二进制名是 `claude`）；填 `"claude --version"` 让 sandbox-create 能验证安装。 |
+| `setupHint` | `Run \`<id>\` inside the container to set up.` | setup 流程不一目了然，值得用一行说明。 |
+| `envVars` | （无） | 工具通过环境变量找配置（如 `XDG_CONFIG_HOME` 风格或自定义 `*_CONFIG` 变量）。形状：`Record<string, string>`。 |
+| `hostPreSeedFiles` / `hostPreSeedDirs` | （无） | 首次启动时从宿主复制文件 / 目录到工具沙箱配置目录。 |
+| `pathRewriteFiles` | （无） | seed 进来的文件里有宿主绝对路径，需要改写为容器路径。 |
+| `hostLiveMounts` | （无） | 把宿主凭证（如 OAuth token）实时挂进容器，读写共享。 |
+| `postSetupCmds` | （无） | 首次安装完成后在容器内执行命令（如建符号链接）。 |
+
+> **`sandboxBase` 不由用户配置。** loader 永远使用 `~/.agent-infra/sandboxes/<id>`，这样 `ai sandbox rm` / `prune` 才能找到工具状态目录。`customTools` 条目里写的任何 `sandboxBase` 都会被静默忽略。
+
+实际场景示例——`anthropic-claude` 作为用户自定义 id，二进制名是 `claude`，并把宿主凭证 live-mount 进来：
+
+```json
+{
+  "sandbox": {
+    "tools": ["claude-code", "anthropic-claude"],
+    "customTools": [
+      {
+        "id": "anthropic-claude",
+        "install": { "type": "npm", "cmd": "@anthropic-ai/claude-code@stable" },
+        "versionCmd": "claude --version",
+        "hostLiveMounts": [
+          { "hostPath": "~/.claude/.credentials.json", "containerSubpath": ".credentials.json" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 信任边界与执行身份
+
+- `install.cmd` 在 `docker build` 阶段以 `devuser`（非 root）身份执行，只能写容器内文件系统，不能逃逸到宿主。信任模型与现有 `sandbox.dockerfile` 一致：你是 `.airc.json` 的作者，本次构建做什么由你负责。
+- 因为不是 root，shell 安装无法 `sudo` / `apt-get`。非 npm 分发的几条可用路径：
+  - 用户态安装器，落到 `~/.local/bin`、`~/.cargo/bin`、`~/.npm-global/bin`（如 `pipx`、`cargo install`、`curl … | bash` 配合 `INSTALL_DIR=$HOME/.local/bin`）。
+  - 确实需要 root / 系统包时，仍走原有 `sandbox.dockerfile` 字段，接管整个 Dockerfile。
+- 修改 `install.cmd` 或任何参与镜像签名的字段，下次 `ai sandbox` 命令会触发一次镜像重建。
+
+### 与 `sandbox.dockerfile` 的交互
+
+当 `sandbox.dockerfile` 指向自定义 Dockerfile 时，agent-infra 仍会把 `AI_TOOL_PACKAGES`（空格分隔的 npm 包规范）和 `AI_TOOLS_SHELL_INSTALL_B64`（base64 编码的 shell 安装脚本）作为 `--build-arg` 传入。你的自定义 Dockerfile 若未声明对应 `ARG`，shell 安装路径会被 docker build 静默忽略——这是接管 Dockerfile 后的应有代价。
+
 ## Skill 编写规范
 
 编写或维护 `.agents/skills/*/SKILL.md` 及其模板时，步骤编号遵循以下规则：

package/templates/.agents/rules/create-issue.en.md

@@ -2,4 +2,4 @@
 
 This code platform does not provide an Issue creation rule.
 
-`create-task` skips the cascade Issue creation step on this platform; the local `task.md` remains a valid artifact. If you later want to bind the task to an Issue, manually write `issue_number` into `task.md` and the subsequent skills (`commit` / `refine-task` / `complete-task`, etc.) will pick up Issue metadata syncing through the existing cascade rules.
+`create-task` skips the cascade Issue creation step on this platform; the local `task.md` remains a valid artifact. If you later want to bind the task to an Issue, manually write `issue_number` into `task.md` and the subsequent skills (`commit` / `code-task` / `complete-task`, etc.) will pick up Issue metadata syncing through the existing cascade rules.

package/templates/.agents/rules/create-issue.github.en.md

@@ -5,7 +5,7 @@ After `create-task` writes the local `task.md`, follow this rule to cascade Issu
 ## Boundary
 
 - Issue title and body must come from `task.md` only
-- Do not read `analysis.md`, `plan.md`, `implementation.md`, or any review artifact
+- Do not read `analysis.md`, `review-analysis.md`, `plan.md`, `review-plan.md`, `code.md`, or any review-code artifact
 - Persistent outputs are limited to the remote Issue and the `issue_number` written back to `task.md`
 - If Issue creation fails, do not roll back `task.md`; the current task remains valid for the workflow, and the user can later manually fill `issue_number` so other skills' cascade sync takes over
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -5,7 +5,7 @@
 ## 行为边界
 
 - Issue 标题和正文只能来自 `task.md`
-- 不读取 `analysis.md`、`plan.md`、`implementation.md` 或审查产物
+- 不读取 `analysis.md`、`review-analysis.md`、`plan.md`、`review-plan.md`、`code.md` 或代码审查产物
 - 持久产物只有：远端 Issue + `task.md` 中回写的 `issue_number`
 - Issue 创建失败时不回滚 `task.md`；当前 task 仍可继续后续工作流，未来可由用户手动写入 `issue_number`，让其它技能的级联同步接管
 

package/templates/.agents/rules/create-issue.zh-CN.md

@@ -2,4 +2,4 @@
 
 当前代码平台未提供 Issue 创建规则。
 
-`create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `refine-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。
+`create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `code-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。