chainlesschain 0.162.159 → 0.162.160

package/src/commands/agent.js

@@ -16,7 +16,10 @@ import {
 } from "../runtime/fallback-model.js";
 import { resolveImages, resolveVisionLlm } from "../lib/image-input.js";
 import { loadConfig } from "../lib/config-manager.js";
-import { normalizeAgentSandbox } from "../lib/agent-sandbox.js";
+import {
+  normalizeAgentSandbox,
+  assertSandboxAvailable,
+} from "../lib/agent-sandbox.js";
 
 /**
  * Resolve + validate `--add-dir` values into absolute, existing, de-duped
@@ -172,6 +175,14 @@ export function registerAgentCommand(program) {
       "--bare",
       "Everything --safe-mode disables PLUS skills, plugins and MCP/IDE auto-connect — minimal fast surface for scripted calls (explicit --mcp-config still loads; permission rules STAY active)",
     )
+    .option(
+      "--ephemeral",
+      "No session persistence: nothing is written to the session store (headless; a --resume id still replays history read-only)",
+    )
+    .option(
+      "--capabilities",
+      "Print a machine-readable capability manifest (JSON: protocol version, tools, permission modes, exit codes) and exit",
+    )
     .option(
       "--disable-slash-commands",
       "Interactive REPL: don't dispatch '/' input as slash commands — it reaches the model verbatim (/exit and /quit stay live)",
@@ -367,12 +378,31 @@ export function registerAgentCommand(program) {
       false,
     )
     .action(async (task, options, command) => {
+      // --capabilities: print the machine-readable manifest and exit — no
+      // config, no bootstrap, no network (gap-analysis 2026-07-11 快速收益 #6).
+      if (options.capabilities) {
+        const { buildAgentCapabilities } =
+          await import("../lib/headless-manifest.js");
+        console.log(JSON.stringify(buildAgentCapabilities(), null, 2));
+        return;
+      }
       // CC_API_KEY env fallback for --api-key: lets callers (IDE plugins,
       // scripts) pass the key via the environment instead of argv, where it
       // is visible to every local process (/proc/<pid>/cmdline, Win32_Process).
       // An explicit --api-key still wins.
       if (!options.apiKey && process.env.CC_API_KEY) {
         options.apiKey = process.env.CC_API_KEY;
+      } else if (
+        options.apiKey &&
+        process.argv.includes("--api-key") &&
+        !process.env.VITEST &&
+        !process.env.VITEST_WORKER_ID
+      ) {
+        // gap-analysis 2026-07-11: argv keys leak into shell history, process
+        // lists and logs — steer callers to the env/helper paths.
+        process.stderr.write(
+          "⚠️  --api-key on the command line is visible to every local process (shell history, ps). Prefer CC_API_KEY env or config llm.apiKeyHelper.\n",
+        );
       }
       const bypassPermissions = !!(
         options.allowDangerousBypass ||
@@ -830,6 +860,7 @@ export function registerAgentCommand(program) {
             outputStyle: options.outputStyle || null,
             strictMcpConfig: options.strictMcpConfig === true,
             replayUserMessages: options.replayUserMessages === true,
+            ephemeral: options.ephemeral === true,
             maxCostUsd,
             priceTable,
             chatFn: fallbackChatFn,
@@ -937,6 +968,15 @@ export function registerAgentCommand(program) {
           network: options.sandboxNetwork === true,
           settings: settingsSandbox,
         });
+        // Strict sandbox mode: failIfUnavailable refuses to START when the
+        // configured engine can't run — no silent per-command degradation.
+        try {
+          assertSandboxAvailable(agentSandbox);
+        } catch (err) {
+          process.stderr.write(`Error: ${err.message}\n`);
+          await _finishWorktree();
+          process.exit(6); // config error (see lib/exit-codes.cjs)
+        }
         // Resume requested onto a session with no headless (JSONL) transcript?
         // Warn instead of silently starting empty 鈥?headless resume rebuilds
         // from the JSONL store only (DB-only sessions are not replayable here).
@@ -1025,6 +1065,8 @@ export function registerAgentCommand(program) {
           // --settings: extra .claude/settings.json permission rules
           settingsFile: options.settings || null,
           outputStyle: options.outputStyle || null,
+          // --ephemeral: no session persistence (resume replay stays read-only)
+          ephemeral: options.ephemeral === true,
           // --max-budget-usd: hard spend cap (+ price table from config llm.pricing)
           maxCostUsd,
           priceTable,
@@ -1074,6 +1116,13 @@ export function registerAgentCommand(program) {
         return;
       }
 
+      // --ephemeral is a headless contract (the interactive REPL owns its own
+      // session lifecycle) — warn instead of silently dropping the flag.
+      if (options.ephemeral) {
+        process.stderr.write(
+          "--ephemeral is only used in headless mode (-p / a task / piped stdin); ignoring for the interactive session.\n",
+        );
+      }
       // Reached only for an interactive session, where --image has no turn to
       // attach to 鈥?warn instead of silently dropping the attachment.
       if (images.length) {
@@ -1082,6 +1131,20 @@ export function registerAgentCommand(program) {
         );
       }
 
+      // Strict sandbox mode also guards the interactive session: refuse to
+      // start when failIfUnavailable is set and the engine can't run.
+      const interactiveSandbox = normalizeAgentSandbox(options.sandbox, {
+        cwd: process.cwd(),
+        network: options.sandboxNetwork === true,
+        settings: settingsSandbox,
+      });
+      try {
+        assertSandboxAvailable(interactiveSandbox);
+      } catch (err) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(6); // config error (see lib/exit-codes.cjs)
+      }
+
       const runtime = createAgentRuntimeFactory().createAgentRuntime({
         model: options.model,
         thinking,
@@ -1103,11 +1166,7 @@ export function registerAgentCommand(program) {
         parkOnExit: options.parkOnExit, // false when --no-park-on-exit
         bundlePath: options.bundle || null,
         additionalDirectories,
-        sandbox: normalizeAgentSandbox(options.sandbox, {
-          cwd: process.cwd(),
-          network: options.sandboxNetwork === true,
-          settings: settingsSandbox,
-        }),
+        sandbox: interactiveSandbox,
         autoCheckpoint,
         // --vim: start the REPL in vim-mode editing (also CC_VIM=1 or /vim).
         vimMode: options.vim === true,

package/src/commands/background-session.js

@@ -597,6 +597,36 @@ export function registerBackgroundSessionCommands(program) {
       }
     });
 
+  // daemon rm — record cleanup (gap-analysis 2026-07-11 P0 后台 Supervisor).
+  daemon
+    .command("rm <id>")
+    .description(
+      "Remove a finished background agent's record + log (running agents need --force; the conversation session itself is untouched)",
+    )
+    .option("--force", "Stop a still-running agent first, then remove")
+    .option("--keep-log", "Keep the log file, remove only the state record")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      try {
+        const { removeBackgroundAgent } = await loadSupervisor();
+        const result = removeBackgroundAgent(id, {
+          force: options.force === true,
+          keepLog: options.keepLog === true,
+        });
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        logger.log(
+          chalk.green(`Removed background agent ${result.id}`) +
+            chalk.gray(` (was ${result.status})`),
+        );
+      } catch (error) {
+        logger.error(chalk.red(error.message));
+        process.exitCode = 1;
+      }
+    });
+
   daemon
     .command("stop [id]")
     .description("Stop one background agent, or all running agents with --any")

package/src/commands/mcp.js

@@ -999,6 +999,52 @@ export function registerMcpCommand(program) {
     });
 
   // mcp scaffold — generate a boilerplate MCP server project
+  mcp
+    .command("trust-project")
+    .description(
+      "Re-trust the project .mcp.json after reviewing a content change (records its fingerprint for --project-mcp runs)",
+    )
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      try {
+        const fsMod = await import("node:fs");
+        const { projectRootBase } = await import("../lib/project-root.cjs");
+        const { recordProjectMcpTrust, projectMcpFingerprint } =
+          await import("../lib/project-mcp-trust.js");
+        const cwd = process.cwd();
+        const candidates = [path.join(cwd, ".mcp.json")];
+        const root = projectRootBase(cwd, { fs: fsMod.default, path });
+        if (root) candidates.push(path.join(root, ".mcp.json"));
+        const results = [];
+        for (const file of [...new Set(candidates)]) {
+          if (!fsMod.existsSync(file)) continue;
+          const content = fsMod.readFileSync(file, "utf-8");
+          const ok = recordProjectMcpTrust(file, content);
+          results.push({
+            file,
+            trusted: ok,
+            fingerprint: projectMcpFingerprint(content).slice(0, 16),
+          });
+        }
+        if (options.json) {
+          console.log(JSON.stringify(results, null, 2));
+          return;
+        }
+        if (results.length === 0) {
+          console.log("No .mcp.json found in this project.");
+          return;
+        }
+        for (const r of results) {
+          console.log(
+            `${r.trusted ? "Trusted" : "FAILED to record"} ${r.file} (${r.fingerprint})`,
+          );
+        }
+      } catch (err) {
+        console.error(`Failed: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
   mcp
     .command("scaffold <name>")
     .description("Scaffold a new MCP server project (stdio or http+sse)")

package/src/commands/session.js

@@ -534,6 +534,76 @@ export function registerSessionCommand(program) {
       }
     });
 
+  // session rename — named sessions (gap-analysis 2026-07-11 快速收益 #5).
+  // Appends a session_rename event (hash chain stays intact); last one wins.
+  session
+    .command("rename")
+    .description("Rename a headless (JSONL) session — shows up in session list")
+    .argument("<id>", "Session ID")
+    .argument("<title...>", "New title")
+    .option("--json", "Output as JSON")
+    .action(async (id, title, options) => {
+      try {
+        const { renameSession } =
+          await import("../harness/jsonl-session-store.js");
+        const result = renameSession(
+          id,
+          Array.isArray(title) ? title.join(" ") : title,
+        );
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        logger.success(`Renamed session ${result.id}`);
+        logger.info(`  ${result.title}`);
+      } catch (err) {
+        logger.error(`Failed: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  // session prune — retention sweep (gap-analysis 2026-07-11 P1 "保留期限").
+  session
+    .command("prune")
+    .description(
+      "Delete JSONL sessions whose last activity is older than a cutoff (newest N always kept)",
+    )
+    .requiredOption(
+      "--older-than <days>",
+      "Delete sessions idle for more than this many days",
+    )
+    .option("--keep <n>", "Always keep the newest N sessions (default 10)")
+    .option("--dry-run", "List what would be deleted without deleting")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      try {
+        const { pruneJsonlSessions } =
+          await import("../harness/jsonl-session-store.js");
+        const result = pruneJsonlSessions({
+          olderThanDays: Number(options.olderThan),
+          keep: options.keep != null ? Number(options.keep) : undefined,
+          dryRun: options.dryRun === true,
+        });
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        const verb = result.dryRun ? "Would delete" : "Deleted";
+        logger.info(
+          `${verb} ${result.deleted.length} of ${result.scanned} session(s).`,
+        );
+        for (const id of result.deleted.slice(0, 50)) {
+          logger.info(`  - ${id}`);
+        }
+        if (result.deleted.length > 50) {
+          logger.info(`  … and ${result.deleted.length - 50} more`);
+        }
+      } catch (err) {
+        logger.error(`Failed: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
   session
     .command("migrate")
     .description("Migrate legacy JSON session files to JSONL")

package/src/data/changelog.json

@@ -3,7 +3,7 @@
   "releases": [
     {
       "productVersion": "Unreleased",
-      "cliVersion": "0.162.159",
+      "cliVersion": "0.162.160",
       "cliVersions": [
         "0.4.46",
         "0.4.51",
@@ -17,11 +17,16 @@
         "0.162.156",
         "0.162.157",
         "0.162.158",
-        "0.162.159"
+        "0.162.159",
+        "0.162.160"
       ],
       "date": null,
       "title": "",
       "sections": [
+        {
+          "heading": "Added — cc CLI 0.162.160：运行时安全与确定性 8 批（沙箱严格模式 + 依赖/凭据安全 + 确定性 Headless + Subagent 契约 + MCP 生命周期 + Hooks 硬化）（CLI-only npm 发版）",
+          "body": "> `chainlesschain` 0.162.159 → **0.162.160** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。命令面**只加子命令**（`cc session rename/prune`、`cc daemon rm`、`cc mcp trust-project`），**顶层命令数 175 不变**（manifest 无需重生）。对照 `docs/CLAUDE_CODE_CLI_GAP_ANALYSIS.md`（docs 根）审计确认仍缺的 8 项全落地（commit 链 `c4533ad848..4c2e297754`）。\n>\n> ⚠️ **行为变更（升级前须知）**：① `run_code` 的 pip 依赖**默认不再自动安装**（改 opt-in，见下）；② agent 脚本默认写 OS 临时目录、不再落项目根（`persist:true` 才进项目）；③ headless/agent **退出码细化**——最大轮次→3、预算超限→4、模型错误→5、配置错误→6（成功仍 0、通用失败仍 1、hook block 仍 2、SIGINT/SIGTERM 仍 130/143）。依赖固定 exit≠0 判失败的脚本不受影响；依赖\"失败必为 1\"的脚本需放宽。\n\n- **确定性 Headless（A）**：新增 `--ephemeral`（resume 只读回放、零落盘）；init 事件补 `protocol_version`/`session_persistence`/`loaded_sources`/`policy_digest`/`tools_hash`/`isolation_level`（消费者可判定回放确定性与工具/策略指纹）；退出码分类（`lib/exit-codes.cjs`）；`cc agent --capabilities` 打印机读能力清单（协议版本、agent 工具集、权限模式、退出码、特性开关）后退出。\n- **依赖安装安全（B）**：`run_code` 的 pip 自动安装**默认关闭**——经 settings `runCode.autoInstall` 或 `CC_RUN_CODE_AUTO_INSTALL` 显式开启，且受 `runCode.installAllowlist`（PEP 503 归一化包名）约束，每次安装写审计 JSONL（`~/.chainlesschain/audit/`，`CC_AUDIT_DIR` 可覆盖）；agent 脚本默认写 OS 临时目录（`persist:true` 才进项目根）。系统提示词/工具契约文案已同步。\n- **凭据卫生（C）**：config `llm.apiKeyHelper`——从外部命令（→ OS 凭据库）解析 API Key，5 分钟缓存，helper 失败 **fail-closed 并告警一次**（返回 null，绝不静默替换成别的凭据）；argv `--api-key` 明文传参现给出告警（进程表/shell 历史泄露面）。\n- **沙箱严格模式（D）**：`failIfUnavailable` 此前只是声明、从不执行——现在启动期探测沙箱引擎（docker `version` / bwrap `--version`），不可用即拒绝启动（退出码 6），headless 与交互双路均生效；`isolation_level`（os-sandbox / container / policy-only）透出到 init 事件与 `sandboxSummary`，不再静默降级为\"只有工具规则\"。\n- **Subagent 契约（E）**：`spawn_sub_agent` 与 `.claude/agents/*.md` frontmatter 双入口新增 `disallowedTools`（从 allowedTools 减去）、`maxTurns`、`isolation:worktree`。**顺手修出一个真 bug**：`SubAgentContext._runCore` 早已算出工具白名单却从未传给 agentLoop——子代理在 LLM 面一直看到全量工具，白名单形同虚设（修=`enabledToolNames` 透传）。\n- **会话运营（F）**：`cc session rename <id> <title>`（append `session_rename` 事件，哈希链不破）+ `cc session prune --older-than <days> [--keep N] [--dry-run]`（按最后活动保留期清理，默认保最新 10）+ `cc daemon rm <id> [--force] [--keep-log]`（终态直接移除、运行中需 `--force`）。\n- **MCP 生命周期（G）**：mcp-client 处理 `notifications/tools/list_changed` + `notifications/resources/list_changed`——合并式重拉服务器工具/资源清单（刻意**不动 in-flight LLM 工具数组**，保 tool-search 缓存稳定性，追加式更新）；项目 `.mcp.json` 首用记 sha256 指纹，文件变更后 **fail-closed 拒绝加载**，需 `CC_PROJECT_MCP_TRUST=1` 或 `cc mcp trust-project` 显式重信任（防被换过的项目配置静默拉起新 MCP server）。\n- **Hooks 硬化（H）**：每个 hook 的 stdin payload 打 `schema_version`（=1，additive 变更保号、破坏性 reshape 才 bump）；连续失败熔断——同一 hook 命令连续 3 次非阻塞失败（spawn error / 超时 / 非 2 非零退出）开闸，60s 冷却后半开试跑一次，成功或真 block/ask 决策关闸（`CC_HOOK_BREAKER_THRESHOLD=0` 关闭、`CC_HOOK_BREAKER_COOLDOWN_MS` 可调）；坏 hook 不再每轮拖慢 agent。"
+        },
         {
           "heading": "Added — cc CLI 0.162.159：Claude-Code 平价 gap-analysis 14 项收口（cloud handoff + /tui + /voice + /fast + plugin 治理 + session SQLite 索引）（CLI-only npm 发版）",
           "body": "> `chainlesschain` 0.162.158 → **0.162.159** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。顶层命令数 **173 → 175**（新增 `cc cloud` + `cc routine`；`cc session index` 是 `session` 子命令、`/tui` `/voice` `/fast` 为 REPL-only 均不计数）。对照 `docs/internal/cli-claude-code-gap-analysis-2026-07-11.md` 14 项全落地。\n\n- **`cc cloud`（P1#7）自托管 cloud handoff**：`cc cloud run/status/attach/list`——`git bundle`（base64）当前分支上传到配置的私有 runner（`cloud.baseUrl`/`cloud.token` 或 `CC_CLOUD_URL`/`CC_CLOUD_TOKEN`），runner 完成后 `cc cloud attach` 轮询到终态并 `git apply --3way` 回流 patch、落 plan/artifacts、显示 PR——无 Anthropic 云依赖。本地 job 台账 `~/.chainlesschain/cloud-jobs/`（穿越守卫），不落地的 patch 存旁不失败。\n- **`/tui`（P1#10）全屏无闪烁视图**：`/tui fullscreen` 进备用屏缓冲（`?1049h`，保滚动历史）+ 尾锚定视口窗口化 + diff 重绘（仅改动行光标寻址重写，无整屏清屏→无闪烁）；`/tui default` 退回流式滚动；`CC_NO_FLICKER=1` 启动即全屏；屏幕阅读器模式强制 default。持久化 `cli.tuiMode`。\n- **`/voice`（P2#11）语音听写**：`/voice hold|tap|off`（hold=按住说话，tap=切换）；严格 local-first STT 优先级（本地 Whisper > 系统 STT > 云，云需 `voice.allowCloud` 显式开）；SSH/无 TTY/CI/`CC_NO_VOICE` 环境清晰降级不假装监听；真实采集是主机绑定 DI seam。\n- **`/fast`（P2#12）延迟档**：`/fast on|off|status`——下一轮最小化推理（thinking off）+ 除非用户 `/model` 钉过模型否则换到 provider 的低延迟模型（anthropic→haiku-4-5、openai→4o-mini、deepseek/dashscope/mistral/gemini），始终显示成本/质量权衡。持久化 `cli.fastMode`。\n- **插件治理（P2#13）三项**：manifest `dependencies`（插件名→semver 区间 + 保留 `host`/`cc` 约束 CLI 版本）经 `cc plugin validate` 校验缺失/越界依赖；LSP 注册表改**每 languageId 有序候选表**——一个插件 LSP server 二进制缺失不再遮蔽 builtin（回退到下一候选/内建，扩展名不再\"变黑\"）；`isPluginInUse` 把 LSP/MCP/hooks/monitors 被动组件视为 in-use，不再被\"未调用即弃用\"误判。\n- **`cc session index`（P2#14）外部 session 存储**：JSONL 仍是权威源，新增 SQLite 索引（`~/.chainlesschain/session-index.db`）——增量按 mtime+size 同步 + 内容/标题搜索（LIKE 转义通配符）+ stats + `--rebuild`，取代逐文件解析（1072 真 session 验过）；可插拔 off-box mirror（`fs`/`http` 驱动，S3/WebDAV/Redis 同接口待配），`session.mirror.{kind,dir|baseUrl,token}` 配置，加密/访问控制由驱动独立负责。\n- **P0/P1 早前提交同随本版发出**：`cc bg view` 交互式 agent 面板（P0#1）+ background supervisor 稳定性加固（P0#2）+ `/doctor` 可修复 checkup + `/checkup` 别名（P0#3）+ transcript hash-chain 防篡改 `cc session verify`（P0#4）+ Inbound Channels（webhook/telegram allowlist，P0#5）+ computer-use MCP 显式开启（P1#6）+ Routines（cron/once/webhook/github，P1#8）+ PR/session linking（P1#9）。"

package/src/harness/jsonl-session-store.js

@@ -271,10 +271,17 @@ export function listJsonlSessions(options = {}) {
       const messageCount = events.filter(
         (e) => e.type === "user_message" || e.type === "assistant_message",
       ).length;
+      // cc session rename appends session_rename events; the LAST one wins.
+      let renamedTitle = null;
+      for (const e of events) {
+        if (e.type === "session_rename" && e.data?.title) {
+          renamedTitle = e.data.title;
+        }
+      }
 
       return {
         id,
-        title: startEvent?.data?.title || "Untitled",
+        title: renamedTitle || startEvent?.data?.title || "Untitled",
         provider: startEvent?.data?.provider || "",
         model: startEvent?.data?.model || "",
         message_count: messageCount,
@@ -296,6 +303,68 @@ export function listJsonlSessions(options = {}) {
   return files;
 }
 
+/**
+ * Rename a session (gap-analysis 2026-07-11 P1 "命名会话"): appends a
+ * `session_rename` event so the hash chain stays intact (no rewrite). The
+ * LAST rename wins when listing/showing.
+ */
+export function renameSession(sessionId, title) {
+  if (!sessionExists(sessionId)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  const normalized = String(title || "").trim();
+  if (!normalized) throw new Error("A non-empty title is required");
+  appendEvent(sessionId, "session_rename", { title: normalized.slice(0, 200) });
+  return { id: sessionId, title: normalized.slice(0, 200) };
+}
+
+/**
+ * Prune old sessions (gap-analysis 2026-07-11 P1 "保留期限"): delete session
+ * transcripts whose LAST activity is older than `olderThanDays`, always
+ * keeping the newest `keep` (default 10) regardless of age. Dry-run returns
+ * the same shape without deleting.
+ */
+export function pruneJsonlSessions(options = {}) {
+  const olderThanDays = Number(options.olderThanDays);
+  if (!Number.isFinite(olderThanDays) || olderThanDays < 0) {
+    throw new Error(
+      "prune requires --older-than <days> (a non-negative number)",
+    );
+  }
+  const keep = Number.isFinite(Number(options.keep))
+    ? Math.max(0, Math.floor(Number(options.keep)))
+    : 10;
+  const now = typeof options.now === "number" ? options.now : Date.now();
+  const cutoff = now - olderThanDays * 24 * 60 * 60 * 1000;
+  // listJsonlSessions sorts by last activity DESC — the first `keep` entries
+  // survive unconditionally.
+  const all = listJsonlSessions({ limit: 100000 });
+  const candidates = all.slice(keep).filter((s) => {
+    const last = Date.parse(s.updated_at || s.created_at || "");
+    return Number.isFinite(last) && last < cutoff;
+  });
+  const deleted = [];
+  for (const s of candidates) {
+    if (options.dryRun === true) {
+      deleted.push(s.id);
+      continue;
+    }
+    try {
+      rmSync(sessionPath(s.id), { force: true });
+      _chainTailCache.delete(s.id);
+      deleted.push(s.id);
+    } catch {
+      /* per-file failures never abort the sweep */
+    }
+  }
+  return {
+    scanned: all.length,
+    kept: all.length - deleted.length,
+    deleted,
+    dryRun: options.dryRun === true,
+  };
+}
+
 export function forkSession(sourceId) {
   const events = readEvents(sourceId);
   if (events.length === 0) return null;

package/src/harness/mcp-client.js

@@ -1051,6 +1051,17 @@ export class MCPClient extends EventEmitter {
 
     // Server notification
     if (msg.method) {
+      // tools/resources list_changed (gap 2026-07-11 MCP 生命周期): refetch
+      // the changed list so entry.tools/entry.resources stay live —
+      // `listTools()`, `/mcp` status and callTool routing all see the update.
+      // (The LLM tool array of an in-flight turn is deliberately NOT mutated:
+      // tool-search's prompt-cache stability depends on an append-only,
+      // stable-prefix tool list.)
+      if (msg.method === "notifications/tools/list_changed") {
+        this._refreshServerList(serverName, "tools");
+      } else if (msg.method === "notifications/resources/list_changed") {
+        this._refreshServerList(serverName, "resources");
+      }
       this.emit("notification", {
         server: serverName,
         method: msg.method,
@@ -1059,6 +1070,45 @@ export class MCPClient extends EventEmitter {
     }
   }
 
+  /**
+   * Re-fetch a server's tools / resources list after a `*_list_changed`
+   * notification. Coalesced per server+kind: a burst of notifications folds
+   * into the in-flight refetch plus at most one trailing pass. Best-effort —
+   * a failed refetch keeps the previous list and waits for the next
+   * notification. Emits "tools-changed" / "resources-changed" on update.
+   */
+  async _refreshServerList(serverName, kind) {
+    const entry = this.servers.get(serverName);
+    if (!entry) return;
+    const flags = (entry._listRefresh = entry._listRefresh || {});
+    if (flags[`${kind}Running`]) {
+      flags[`${kind}Dirty`] = true;
+      return;
+    }
+    flags[`${kind}Running`] = true;
+    try {
+      do {
+        flags[`${kind}Dirty`] = false;
+        try {
+          const method = kind === "tools" ? "tools/list" : "resources/list";
+          const result = await this._sendRequest(serverName, method, {});
+          const list =
+            (kind === "tools" ? result?.tools : result?.resources) || [];
+          entry[kind] = list;
+          if (kind === "tools") entry.toolsError = null;
+          this.emit(`${kind}-changed`, {
+            server: serverName,
+            count: list.length,
+          });
+        } catch {
+          break; // keep the previous list; the next notification retries
+        }
+      } while (flags[`${kind}Dirty`]);
+    } finally {
+      flags[`${kind}Running`] = false;
+    }
+  }
+
   /**
    * Answer a server-initiated JSON-RPC request. `roots/list` returns the
    * session's workspace roots (we advertise the roots capability); `ping`

package/src/lib/agent-sandbox.js

@@ -215,11 +215,79 @@ function executeBubblewrapShell(command, sandbox, options, hostCwd, policy) {
   };
 }
 
+/**
+ * The run's TRUE isolation level (gap-analysis 2026-07-11 P0 "OS 级沙箱"):
+ *  - "os-sandbox"  : bubblewrap — kernel namespaces confine the child
+ *  - "container"   : docker — container boundary confines the child
+ *  - "policy-only" : no sandbox — permission rules/shell policy are advisory
+ *                    for already-spawned subprocesses
+ * Surfaced in the headless init event and sandboxSummary so a caller can see
+ * what actually confines tool subprocesses instead of assuming.
+ */
+export function isolationLevel(sandbox) {
+  if (!sandbox) return "policy-only";
+  if (sandbox.engine === "bubblewrap") return "os-sandbox";
+  if (sandbox.engine === "docker") return "container";
+  return "policy-only";
+}
+
+/**
+ * Probe whether the configured sandbox ENGINE is actually runnable on this
+ * host (binary present + responds to a version query). Cheap: one spawnSync
+ * with a short timeout; no container is started.
+ * @returns {{available:boolean, reason:string|null}}
+ */
+export function probeSandboxAvailability(sandbox, deps = _deps) {
+  if (!sandbox) return { available: true, reason: null };
+  const probeArgs =
+    sandbox.engine === "bubblewrap"
+      ? ["bwrap", ["--version"]]
+      : ["docker", ["version", "--format", "{{.Server.Version}}"]];
+  const result = deps.spawnSync(probeArgs[0], probeArgs[1], {
+    encoding: "utf8",
+    timeout: 10000,
+    windowsHide: true,
+  });
+  if (result.error) {
+    return {
+      available: false,
+      reason:
+        result.error.code === "ENOENT"
+          ? `${probeArgs[0]} is not installed`
+          : result.error.message,
+    };
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    return {
+      available: false,
+      reason: `${probeArgs[0]} probe exited ${result.status}: ${(result.stderr || "").trim().slice(0, 200)}`,
+    };
+  }
+  return { available: true, reason: null };
+}
+
+/**
+ * Strict mode (`sandbox.failIfUnavailable: true` in settings): refuse to
+ * START the agent when the configured sandbox engine is unavailable, instead
+ * of silently degrading per command. Throws with an actionable message; a
+ * no-op when the flag is unset or the sandbox is fine.
+ */
+export function assertSandboxAvailable(sandbox, deps = _deps) {
+  if (!sandbox || sandbox.policy?.failIfUnavailable !== true) return;
+  const probe = probeSandboxAvailability(sandbox, deps);
+  if (!probe.available) {
+    throw new Error(
+      `sandbox.failIfUnavailable: ${sandbox.engine} sandbox is unavailable (${probe.reason}) — refusing to start. Install/start ${sandbox.engine === "bubblewrap" ? "bubblewrap" : "Docker"}, or unset failIfUnavailable to allow per-command degradation.`,
+    );
+  }
+}
+
 export function sandboxSummary(sandbox) {
   if (!sandbox) return null;
   return {
     engine: sandbox.engine,
     image: sandbox.image,
+    isolationLevel: isolationLevel(sandbox),
     network: sandbox.network ? "enabled" : "disabled",
     workspace: "read-write",
     policy: {

package/src/lib/agents.js

@@ -8,10 +8,13 @@
  * `review/security.md` is the agent `review:security`.
  *
  * Frontmatter (all optional):
- *   name          override the filename-derived name
- *   description   one-line summary (when to use this agent)
- *   tools         allow-list — comma string or YAML array; omit = inherit all
- *   model         model override for runs of this agent
+ *   name             override the filename-derived name
+ *   description      one-line summary (when to use this agent)
+ *   tools            allow-list — comma string or YAML array; omit = inherit all
+ *   disallowedTools  deny-list — removed from whatever the allow-list resolves to
+ *   model            model override for runs of this agent
+ *   maxTurns         per-run iteration cap for this agent (positive integer)
+ *   isolation        "worktree" → run in a fresh git worktree (gap 2026-07-11)
  *
  * Project scope shadows personal on a name clash. Discovery + parse are pure
  * (inject fs/path/home) so the whole thing is unit-testable.
@@ -132,13 +135,18 @@ export function parseAgentFile(file, scope, opts = {}) {
     return null;
   }
   const { data, body } = parseFrontmatter(content);
+  const maxTurns = Number(data.maxTurns);
   return {
     file,
     scope,
     name: data.name || null, // resolved against the path in discoverAgents
     description: data.description || "",
     tools: normalizeTools(data.tools),
+    disallowedTools: normalizeTools(data.disallowedTools),
     model: data.model || null,
+    maxTurns:
+      Number.isFinite(maxTurns) && maxTurns > 0 ? Math.floor(maxTurns) : null,
+    isolation: data.isolation === "worktree" ? "worktree" : null,
     systemPrompt: body || "",
   };
 }