dsh-session-conductor 1.3.11 → 1.3.16

package/lib/features/member-model/switch.js

@@ -5,6 +5,7 @@
 
 import { readFileSync, copyFileSync, mkdirSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { createZstdDecompress } from "node:zlib";
 import { replaceFileSync } from "../../shared/atomic-file.js";
 import path from "node:path";
 import { log } from "../../shared/log.js";
@@ -84,36 +85,232 @@ function backupSwitchLog(filePath, sessionId) {
   const backupDir = path.join(path.dirname(filePath), ".model-switch-backup");
   try {
     mkdirSync(backupDir, { recursive: true });
-    copyFileSync(filePath, path.join(backupDir, `${Date.now()}-${sessionId}.zstd`));
-    return { ok: true };
+    const file = path.join(backupDir, `${Date.now()}-${sessionId}.zstd`);
+    copyFileSync(filePath, file);
+    return { ok: true, file };
   } catch (error) {
     return { error: `备份失败（未写入）：${String(error?.message ?? error)}` };
   }
 }
 
+/** 写后自检不合格时把日志还原回备份（宁可不动日志，也不能留下 corrupt 的会话）。 */
+function restoreSwitchLog(backup, filePath) {
+  if (!backup?.file) return { error: "没有可用备份，无法回滚" };
+  try {
+    copyFileSync(backup.file, filePath);
+    return { ok: true };
+  } catch (error) {
+    return { error: `回滚失败：${String(error?.message ?? error)}` };
+  }
+}
+
+/**
+ * 该会话是否带「委派策略快照」，带则返回一条排查提示。
+ *
+ * 【为什么需要】本机实测：子代理会话开头会有 `approval/policy`（source=delegation，
+ * 创建时从父级快照）。若部署侧关掉「自动审查」，宿主恢复这条快照会失败，失败被
+ * `manager.coldResume` 统一包成 `subagent/not-resumable` —— 界面只看到
+ * 「subagent cannot be resumed」，极具误导性（会让人去查模型/描述符/文件）。
+ * 因此切换时若发现该会话带这种快照，就主动提示先去查自动审查开关。
+ *
+ * 只读首帧（header + 开头几条策略事件），失败一律返回空字符串，绝不影响切换本身。
+ *
+ * @param {string} filePath 会话日志路径
+ * @returns {Promise<string>} 提示文案；不适用或读不到时为空串
+ */
+export async function delegationPolicyHint(filePath) {
+  try {
+    const { readFile } = await import("node:fs/promises");
+    const { scanZstdFrames, decodeFrame } = await import("../../zstd-frames.js");
+    const buf = await readFile(filePath);
+    const { frames } = scanZstdFrames(buf);
+    if (frames.length === 0) return "";
+    // 策略事件在会话最开头（header 之后几条），解首帧通常就够
+    let text = (await decodeFrame(buf.subarray(frames[0].start, frames[0].end))).toString("utf8");
+    if (frames.length > 1) {
+      text += (await decodeFrame(buf.subarray(frames[1].start, frames[1].end))).toString("utf8").slice(0, 20000);
+    }
+    if (text.includes('"type":"approval/policy"') && text.includes('"source":"delegation"')) {
+      return '该成员带委派策略快照（approval/policy, source=delegation）；若它之后唤不醒并报 subagent/not-resumable，先检查部署侧「自动审查」开关是否被关掉——本机实测这才是真因，与模型/描述符/文件无关';
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * 切换模型时同步修正「失效的 descriptor 路由」。
+ *
+ * 【为什么必须做】宿主 cold resume 子代理时，provider/model 取自会话日志里的
+ * `subagent/descriptor`（manager.coldResume → materialize 的 agentOptions），
+ * `model/selection` 不参与该路径。若 descriptor 仍指向一个已被删除的 provider
+ * （例如配置里移除了某个渠道），materialize 必然失败并被统一包成
+ * `subagent/not-resumable` —— 表现为「这个成员永远唤不醒，怎么切模型都没用」。
+ * 因此这里在写入 selection 之后顺带校验 descriptor 的路由是否仍存在，失效就同步改掉。
+ *
+ * 保守原则：拿不到模型目录（服务不可用）或 descriptor 本就有效时，一律不动日志。
+ *
+ * @returns {Promise<{repaired?: boolean, skipped?: string, error?: string}>}
+ */
+async function repairDescriptorIfStale(ctx, filePath, sessionId, provider, model) {
+  const { readDescriptorEvent } = await import("../../sessions/tail-io.js");
+  const { readFile } = await import("node:fs/promises");
+  let buf;
+  try {
+    buf = await readFile(filePath);
+  } catch (error) {
+    return { error: `读取会话日志失败：${String(error?.message ?? error)}` };
+  }
+  let found;
+  try {
+    found = await readDescriptorEvent(buf);
+  } catch (error) {
+    return { error: `读取 descriptor 失败：${String(error?.message ?? error)}` };
+  }
+  const descriptor = found.descriptor;
+  if (!descriptor || typeof descriptor !== "object") return { skipped: "不是子代理会话（无 descriptor）" };
+
+  // 取当前可用 provider 列表；拿不到就不猜、不动日志
+  const sc = ctx.get("sessionController");
+  if (typeof sc?.modelCatalog !== "function") return { skipped: "modelCatalog 不可用，跳过 descriptor 校验" };
+  let groups;
+  try {
+    const catalog = await sc.modelCatalog();
+    groups = catalog?.groups ?? [];
+  } catch (error) {
+    return { skipped: `modelCatalog 调用失败，跳过：${String(error?.message ?? error)}` };
+  }
+  if (groups.length === 0) return { skipped: "模型目录为空，跳过 descriptor 校验" };
+
+  const providerIds = new Set(groups.map((g) => g.id));
+  const staleProvider = descriptor.agentProvider !== undefined && !providerIds.has(descriptor.agentProvider);
+  const staleModel = (() => {
+    if (descriptor.agentProvider === undefined || descriptor.agentModel === undefined) return false;
+    const group = groups.find((g) => g.id === descriptor.agentProvider);
+    if (!group) return false;
+    return !(group.models ?? []).some((m) => m.id === descriptor.agentModel);
+  })();
+  if (!staleProvider && !staleModel) return { skipped: "descriptor 路由有效" };
+
+  // 整份重写（descriptor 在文件头部，追加帧改不了它）；这条路径只在路由失效时走一次，代价可接受
+  const { encodeSessionText } = await lazyRepair();
+  const { decodeAllFrames } = await import("../../zstd-frames.js");
+  const fullText = buf.length > 0 ? await decodeAllFrames(buf) : "";
+  const lines = fullText.split("\n").filter((l) => l.trim() !== "");
+  if (lines.length === 0) return { error: "会话日志为空，无法修正 descriptor" };
+  let patched = 0;
+  for (let i = 1; i < lines.length; i += 1) {
+    let e;
+    try { e = JSON.parse(lines[i]); } catch { continue; }
+    if (e.type !== "subagent/descriptor") continue;
+    e.data.agentProvider = provider;
+    e.data.agentModel = model;
+    lines[i] = JSON.stringify(e);
+    patched += 1;
+    break;
+  }
+  if (patched === 0) return { skipped: "未找到可改写的 descriptor" };
+
+  // 写前校验 seq 严格连续，避免把会话写成 corrupt
+  let prev = -1, gaps = 0;
+  for (let i = 1; i < lines.length; i += 1) {
+    let e;
+    try { e = JSON.parse(lines[i]); } catch { return { error: "改写后存在坏行，放弃写盘" }; }
+    if (typeof e.seq !== "number") continue;
+    if (prev >= 0 && e.seq !== prev + 1) gaps += 1;
+    prev = e.seq;
+  }
+  if (gaps > 0) return { error: `改写后 seq 不连续（${gaps} 处），放弃写盘` };
+
+  const backup = backupSwitchLog(filePath, sessionId);
+  if (backup.error) return { error: backup.error };
+  replaceFileSync(filePath, await encodeSessionText(lines.join("\n") + "\n"), { tmpSuffix: ".descfixtmp" });
+  log(ctx, `切换写日志：descriptor 路由失效（${staleProvider ? "provider 已不存在" : "model 不在目录"}），已改为 ${provider}/${model}`);
+  return { repaired: true };
+}
+
 export async function appendSelectionEventToLog(ctx, sessionId, provider, model) {
   const startedAt = Date.now();
-  const logInfo = await readSwitchLog(sessionId);
+  // 这条路径会整份解码会话日志再整份写回，而宿主在同一会话上会并发追加事件
+  // （turn/start、agent/inbox/spliced…）。若直接用「读到的 maxSeq+1」写回，就会写入过期序号，
+  // 表现为 released v2 row N has seq gap（序号回退），整份会话随即被判 corrupt。
+  // 因此这里做三件事：① 写前 CAS（对比快照是否已过期）② 过期就重读重试 ③ 写后自检 + 失败回滚。
+  //
+  // 【为什么改成「尾部读 + 追加帧」】原实现每次都整份解码（30MB 日志要 1~3s CPU 与数百 MB 内存），
+  // 而追加一条事件只需要知道「尾部 seq」。这里只解码最后几帧拿尾部事件，写入也是「把新事件压缩成一个
+  // 新帧追加到文件尾」——开销与日志总大小无关，且不回写已有帧（失败不会破坏历史）。
+  const { readTailEvents, appendEventFrame } = await import("../../sessions/tail-io.js");
+  let logInfo = await readSwitchLog(sessionId);
   if (logInfo.error) return { error: logInfo.error };
-  const { filePath, lines, events } = logInfo;
-  // 这条路径要整份解码会话日志（几十 MB 时会明显耗时），把耗时单独记出来才能和「卡住」区分
-  log(ctx, `切换写日志：定位+解码 ${Date.now() - startedAt}ms（行数 ${lines.length}）`);
-  const last = foldLastModelSelection(events);
-  if (last && last.provider === provider && last.model === model) {
-    return { ok: true, note: "日志里已是该模型，无需重复写入" };
+  const filePath = logInfo.filePath;
+  log(ctx, `切换写日志：定位+首读 ${Date.now() - startedAt}ms（行数 ${logInfo.lines.length}）`);
+
+  const tailOf = (events) => ({
+    maxSeq: events.reduce((max, e) => (typeof e?.seq === "number" && e.seq > max ? e.seq : max), -1),
+    count: events.length,
+  });
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const { events } = logInfo;
+    const last = foldLastModelSelection(events);
+    if (last && last.provider === provider && last.model === model) {
+      return { ok: true, note: "日志里已是该模型，无需重复写入" };
+    }
+    const { maxSeq } = tailOf(events);
+    const event = { type: "model/selection", seq: maxSeq + 1, time: Date.now(), data: { provider, model } };
+
+    // ① CAS：写前再读一次尾部，确认快照期间宿主没有追加新事件（尾部 seq 未变才敢写）
+    const { readFile } = await import("node:fs/promises");
+    let freshTail;
+    try {
+      freshTail = await readTailEvents(await readFile(filePath), { tailFrames: 3 });
+    } catch (error) {
+      return { error: `写前重读失败：${String(error?.message ?? error)}` };
+    }
+    if (tailOf(freshTail.events).maxSeq !== maxSeq) {
+      log(ctx, `切换写日志：快照已过期（第 ${attempt + 1} 次，尾部 seq ${maxSeq} → ${tailOf(freshTail.events).maxSeq}），重读重试`);
+      logInfo = { ...logInfo, events: freshTail.events };
+      continue;
+    }
+
+    // ② 追加帧（appendEventFrame 内部自证首帧契约 + 长度 CAS + fsync）
+    const writeStartedAt = Date.now();
+    const written = await appendEventFrame(filePath, event);
+    log(ctx, `切换写日志：追加帧 ${Date.now() - writeStartedAt}ms（seq ${event.seq}）`);
+    if (!written.ok) return { error: `写入会话日志失败：${written.error}` };
+    // descriptor 路由失效会让成员永久唤不醒（宿主报 subagent/not-resumable），这里顺带修
+    const descFix = await repairDescriptorIfStale(ctx, filePath, sessionId, provider, model);
+    if (descFix.error) log(ctx, `切换写日志：descriptor 校验失败（不影响本次切换）：${descFix.error}`);
+
+    // 附带排查提示：本机实测「成员唤不醒」的真凶是部署侧的「自动审查」开关被关掉，
+    // 与 descriptor / 帧校验和 / 写锁全都无关（详见 docs/VERSIONS.md 1.3.15）。
+    // 判据：该会话日志开头存在 `approval/policy` 且 source 为 delegation（创建时从父级快照），
+    // 此时若自动审查被关掉，宿主恢复这条委派快照会失败，且失败被 coldResume 统一包成
+    // `subagent/not-resumable` —— 表现就是「切什么模型都唤不醒、重启也没用」。
+    const policyHint = await delegationPolicyHint(filePath);
+    if (policyHint) log(ctx, `切换写日志：${policyHint}`);
+
+    // ③ 写后自检：只读尾部，确认新事件确实落在尾部且 seq 严格 +1 衔接
+    try {
+      const after = await readTailEvents(await readFile(filePath), { tailFrames: 3 });
+      const seqs = after.events.map((e) => e?.seq).filter((n) => typeof n === "number");
+      const tailOk = seqs.length > 0 && seqs.at(-1) === event.seq
+        && seqs.every((n, i) => i === 0 || n === seqs[i - 1] + 1);
+      if (tailOk) return { ok: true, note: "已直接写入会话日志" };
+      log(ctx, `切换写日志：写后自检失败（尾部 ${JSON.stringify(seqs.slice(-3))}），回滚`);
+    } catch (error) {
+      log(ctx, `切换写日志：写后自检读取失败：${String(error?.message ?? error)}`);
+    }
+    // 追加帧写坏时只能整份回退：用备份整份恢复
+    const backup = backupSwitchLog(filePath, sessionId);
+    if (backup.error) return { error: `写后自检失败且无备份可回滚：${backup.error}` };
+    restoreSwitchLog(backup, filePath);
+    return { error: "写入后 seq 不连续，已回滚（不改日志，改用选择意图生效）" };
   }
-  const maxSeq = events.reduce((max, e) => (typeof e?.seq === "number" && e.seq > max ? e.seq : max), -1);
-  const event = { type: "model/selection", seq: maxSeq + 1, time: Date.now(), data: { provider, model } };
-  const newText = [...lines, JSON.stringify(event)].join("\n") + "\n";
-  const { validateSessionText, encodeSessionText } = await lazyRepair();
-  const check = validateSessionText(newText);
-  if (!check.ok) return { error: `写入后校验失败：${check.problems?.[0] ?? "未知"}` };
-  const backup = backupSwitchLog(filePath, sessionId);
-  if (backup.error) return backup;
-  const encodeStartedAt = Date.now();
-  replaceFileSync(filePath, await encodeSessionText(newText), { tmpSuffix: ".modelswitchtmp" });
-  log(ctx, `切换写日志：重编码+原子写回 ${Date.now() - encodeStartedAt}ms`);
-  return { ok: true, note: "已直接写入会话日志" };
+  // 一直有并发写入：放弃写日志（不算失败，选择意图仍会生效）
+  log(ctx, "切换写日志：并发写入持续存在，放弃写日志（不影响切换）");
+  return { ok: true, note: "会话正在被并发写入，跳过日志写入（选择意图仍生效）" };
 }
 
 /**
@@ -337,6 +534,11 @@ function modelEventOf(event) {
  *   · `model/selection` 的 `data.{provider,model}` —— 切换意图（有则一并返回，便于对照）。
  * 用按 zstd 帧流式读（常量内存），大日志也不会把整份文本读进内存。
  *
+ * 【内存纪律】① `pending` 加上限：只在「遇到换行才切走」的缓冲区，若某帧内长时间没有换行
+ * （单行超大事件，例如几 MB 的工具结果）会无限增长；超过上限直接抛错，不再硬撑。
+ * ② `readFile` 换成只读**最后若干帧**：查证只关心「最近一次请求」，没必要把整份文件读进内存
+ * （30MB 日志时这一项就省掉一份整文件 Buffer）。
+ *
  * @returns {Promise<{lastRequest: {provider,model,time}|null, lastSelection: {provider,model,time}|null, scanned: number}>}
  */
 export async function readLastRequestModel(sessionId, root = null) {
@@ -346,11 +548,23 @@ export async function readLastRequestModel(sessionId, root = null) {
   const { streamDecodedFrames } = await import("../../zstd-frames.js");
   const { StringDecoder } = await import("node:string_decoder");
   const buf = await readFile(file); // 日志最大可达数十 MB，异步读避免阻塞事件循环
+  const { scanZstdFrames } = await import("../../zstd-frames.js");
+  // 只流式解码最后若干帧：请求头/选择意图判定只关心最近一次，够用且省内存
+  const TAIL_FRAMES = 8;
+  let tailFrames;
+  try {
+    const { frames } = scanZstdFrames(buf);
+    tailFrames = frames.slice(Math.max(0, frames.length - TAIL_FRAMES));
+  } catch {
+    // 帧扫描失败（文件损坏）：退回整份流式解码，让上层按损坏处理，不在这里静默丢数据
+    tailFrames = null;
+  }
   const decoder = new StringDecoder("utf8");
   let pending = "";
   let scanned = 0;
   let lastRequest = null;
   let lastSelection = null;
+  const PENDING_LIMIT = 8 * 1024 * 1024; // 单行缓冲上限：超过即视为异常，避免无上限增长
   const consume = (line) => {
     if (!line) return;
     let event;
@@ -364,15 +578,32 @@ export async function readLastRequestModel(sessionId, root = null) {
       lastSelection = hit.value;
     }
   };
-  await streamDecodedFrames(buf, (chunk) => {
+  const onChunk = (chunk) => {
     pending += decoder.write(chunk);
+    if (pending.length > PENDING_LIMIT) {
+      throw new Error(`readLastRequestModel 单行缓冲超过 ${PENDING_LIMIT} 字节仍无换行（疑似异常大事件）`);
+    }
     let idx;
     while ((idx = pending.indexOf("\n")) >= 0) {
       const line = pending.slice(0, idx);
       pending = pending.slice(idx + 1);
       consume(line);
     }
-  });
+  };
+  if (tailFrames === null) {
+    await streamDecodedFrames(buf, onChunk);
+  } else {
+    for (const fr of tailFrames) {
+      await new Promise((resolve, reject) => {
+        const d = createZstdDecompress();
+        d.on("data", (c) => { try { onChunk(c); } catch (error) { reject(error); } });
+        d.on("end", resolve);
+        d.on("error", reject);
+        d.write(buf.subarray(fr.start, fr.end));
+        d.end();
+      });
+    }
+  }
   pending += decoder.end();
   consume(pending);
   return { lastRequest, lastSelection, scanned };

package/lib/features/member-model/tools.js

@@ -0,0 +1,324 @@
+// dsh-session-conductor — 成员模型/权限相关的 AI 工具与聊天指令注册
+//
+// 【为什么单独成文件】原先这 293 行全部内联在 lib/apply.js 的 `ctx.inject(["tools"])` 回调里，
+// 使该回调变成一个巨型函数（审计 readability/max-function-length 拦截），
+// 而它内部其实只有两类内容：① 5 个工具的注册（list_models / set_member_model /
+// list_permission_presets / set_member_permission / create_teammate_with_model）
+// ② 两条聊天指令的注册（/model-switch、/perm-switch）。两者都属于「成员模型/权限」这一域，
+// 整体搬出来即可，handler 体与错误隔离策略逐字保留。
+//
+// 【错误隔离约定（必须保留）】每个工具单独包 try/catch：defineTool 抛错会让整个
+// inject 回调中止，历史上因此导致四个工具一起消失（宿主侧表现为「tool 不存在」）。
+import { log } from "../../shared/log.js";
+import { findTargetAgent, resolveTargets, validateModelPair } from "./locate.js";
+import { switchAgentModel, registerSwitchWatch, readLastRequestModel } from "./switch.js";
+import { createTeammateWithModel, renderCreateTeammateResult } from "./create-teammate.js";
+import { switchMemberPermission, describeMemberPermission, readPresetCatalog } from "./permission.js";
+import { readLeaderRoute } from "./lead.js";
+import { applyModelToMany, applyPermissionToMany, renderBatchReport } from "./batch.js";
+import { registerModelSwitchCommand } from "./command.js";
+import { registerContextUsageTool } from "../context-usage/index.js";
+import { registerMemoryRecallTool } from "../memory-recall/index.js";
+import { registerSessionMessagingTools } from "../session-messaging/index.js";
+import { registerPermSwitchCommand } from "./permission-command.js";
+
+/**
+ * 注册成员模型/权限相关的全部 AI 工具与聊天指令。
+ *
+ * @param {object} deps
+ * @param {object} deps.ctx 插件 context
+ * @param {object} deps.tools 宿主 tools 服务（提供 register）
+ * @param {Function} deps.defineTool 宿主 defineTool（工作区自测环境可能为 undefined，调用方已判空）
+ * @returns {void}
+ */
+export function registerMemberModelTools({ ctx, tools, defineTool }) {
+    tools.register(defineTool({
+      name: "list_models",
+      description: "列出当前可用模型（provider → models[]）。切模型前先用它拿到确切 model id，不要凭记忆猜模型名。",
+      parameters: {},
+      output: {
+        schema: { type: "string" },
+        render(args, value) {
+          return [{ type: "text", text: String(value) }];
+        }
+      },
+      async execute() {
+        try {
+          const sc = ctx.get("sessionController");
+          if (!sc?.modelCatalog) return "modelCatalog 服务不可用（无法列出模型）";
+          const catalog = await sc.modelCatalog();
+          const groups = catalog?.groups ?? [];
+          if (groups.length === 0) return "模型目录为空（检查 provider 配置）";
+          return groups.map((g) => {
+            const models = (g.models ?? [])
+              .map((m) => `  - ${m.id}${m.name && m.name !== m.id ? `（${m.name}）` : ""}`)
+              .join("\n");
+            return `${g.id}${g.name && g.name !== g.id ? `（${g.name}）` : ""}:\n${models}`;
+          }).join("\n\n");
+        } catch (error) {
+          return `列出模型失败：${String(error?.message ?? error)}`;
+        }
+      }
+    }));
+/**
+ * 切换后的「查证快照」：最近一次实际请求 + 最近一次切换意图 + 一行判定。
+ * 抽出来是因为这段有 4 个分支，塞在工具 execute 里把圈复杂度顶到 18；
+ * 判定只认「请求时真实使用的模型」（request/header），不信注入的提示语。
+ * @returns {Promise<{snap: string, verdict: string}>}
+ */
+async function describeSwitchSnapshot(ctx, sessionId, provider, model) {
+  const startedAt = Date.now();
+  const { lastRequest, lastSelection, scanned } = await readLastRequestModel(sessionId);
+  // 读整份日志取「最近一次请求」，大日志上这一步本身就要时间
+  log(ctx, `切换查证快照耗时 ${Date.now() - startedAt}ms（命中请求记录 ${scanned ?? 0} 条）`);
+  if (!lastRequest) {
+    return {
+      snap: "【查证·最近一次实际请求】会话日志里还没有 request/header 记录（该成员可能从未运行过）",
+      verdict: "【查证·判定】⏳ 待该成员首次运行后生效",
+    };
+  }
+  const when = lastRequest.time ? `（${new Date(lastRequest.time).toLocaleString("zh-CN")}）` : "";
+  const snap = `【查证·最近一次实际请求】${lastRequest.provider}/${lastRequest.model}${when}`
+    + (lastSelection ? `\n【查证·最近一次切换意图】${lastSelection.provider}/${lastSelection.model}` : "");
+  const alreadyNew = lastRequest.provider === provider && lastRequest.model === model;
+  return {
+    snap,
+    verdict: alreadyNew
+      ? "【查证·判定】✅ 该成员最近的请求已经是新模型"
+      : "【查证·判定】⏳ 待下一回合生效：最近一次请求是切换前发出的（属正常，不代表失败）",
+  };
+}
+
+    tools.register(defineTool({
+      name: "set_member_model",
+      description: "给成员/子代理切换模型。三个参数都可空：target 留空 = 作用于全部成员（慎用，会改所有子代理）；provider/model 留空 = 跟随主代理（Team Lead）当前实际使用的模型。target 传成员名/sessionId/标题关键字。切换前会校验 provider/model 组合是否存在。批量时逐条执行、回执带完整名单。",
+      parameters: {
+        target: { type: "string", description: "目标成员：成员名、sessionId 或标题关键字。留空 = 全部成员（排除 Lead）" },
+        provider: { type: "string", description: "provider 分组名（list_models 的顶层分组）。留空 = 跟随主代理的 provider" },
+        model: { type: "string", description: "该 provider 下的模型 id（含前缀）。留空 = 跟随主代理的 model" }
+      },
+      output: {
+        schema: { type: "string" },
+        render(args, value) {
+          return [{ type: "text", text: String(value) }];
+        }
+      },
+      async execute(args, exec) {
+        const caller = exec?.agent ?? null;
+        let provider = String(args?.provider ?? "").trim();
+        let model = String(args?.model ?? "").trim();
+        // provider/model 留空 = 跟随主代理（Team Lead）当前实际使用的模型。
+        // 取值只认「请求级权威记录」，读不到就如实报错，绝不用名册里的静态字段冒充。
+        let followedLead = null;
+        if (!provider || !model) {
+          const lead = await readLeaderRoute(ctx, { caller });
+          if (lead.error) return `切换失败：${lead.error}`;
+          provider = lead.provider;
+          model = lead.model;
+          followedLead = lead;
+        }
+        // 先校验组合有效性——无效组合会让后续回合的模型请求被拒（表现为「切换生效但回合失败」）
+        const pair = await validateModelPair(ctx, provider, model);
+        if (pair.error) return `切换失败：${pair.error}`;
+        // target 留空 = 作用于全部成员；与聊天指令 /model-switch 走同一套目标解析
+        const resolved = resolveTargets(ctx, args?.target, { caller });
+        if (resolved.error) return `切换失败：${resolved.error}`;
+        if (resolved.all) {
+          const report = await applyModelToMany(ctx, resolved.targets, { provider, model });
+          const extra = [];
+          if (followedLead) {
+            extra.push(`模型来源：跟随主代理 ${followedLead.sessionId}（${followedLead.modelSource}）`);
+            for (const w of followedLead.warnings ?? []) extra.push(`提示：${w}`);
+          }
+          if (pair.note) extra.push(`【校验】${pair.note}`);
+          return renderBatchReport(`批量切换模型 → ${provider}/${model}`, report, extra);
+        }
+        const found = resolved.targets[0];
+        const switchResult = await switchAgentModel(ctx, found.sessionId, provider, model, found.agent);
+        if (switchResult.error) return `切换失败：${switchResult.error}`;
+        const memberLabel = found.member?.name ? `${found.member.name}(${found.sessionId})` : found.sessionId;
+        // 查证（注册 job，不阻塞）：登记待查证项 → 该成员下次发起请求时由 agent/request 事件判定
+        // → 结果注入回本次调用方。同时立刻附一份快照：最近一次实际请求 + 最近一次切换意图。
+        // 判定只认「请求时真实使用的模型」（request/header），不信注入的提示语。
+        try {
+          registerSwitchWatch(found.sessionId, provider, model, exec?.agent?.session?.id ?? null);
+        } catch (error) {
+          log(ctx, `切换查证登记失败（不影响本次切换）: ${String(error?.message ?? error)}`);
+        }
+        let snap = "";
+        let verdict = "";
+        try {
+          ({ snap, verdict } = await describeSwitchSnapshot(ctx, found.sessionId, provider, model));
+        } catch (error) {
+          snap = `【查证·快照】读取会话日志失败：${String(error?.message ?? error)}`;
+        }
+        // 复核命令按**当前插件安装位置**生成（不写死本机路径），可直接复制执行
+        const scriptUrl = new URL("../scripts/check-member-model.mjs", import.meta.url);
+        const cmd = `node ${decodeURIComponent(scriptUrl.pathname)} ${found.sessionId}`;
+        return [
+          `已把成员 ${memberLabel}（${found.matched} 匹配）切到 ${provider}/${model}；生效方式：${switchResult.via}`,
+          // 组合校验默认关闭（避免 @Remote 卡顿）；跳过时如实告知，别让人以为「拼错也会被拦住」
+          pair.note ? `【校验】${pair.note}` : "",
+          snap,
+          verdict,
+          "【查证·任务】已登记（不阻塞）：该成员下次发起请求时按事件判定，结果会在下一次 step 注入给你",
+          `复核命令（可直接复制）：\n${cmd}`,
+        ].filter(Boolean).join("\n");
+      }
+    }));
+    // 列出宿主当前可选的权限预设。存在的意义是让 set_member_permission 的 preset 参数
+    // 有可查来源，避免凭记忆猜名字（不可用的预设名写进会话会让成员加载失败）。
+    try {
+      tools.register(defineTool({
+        name: "list_permission_presets",
+        description: "列出宿主当前可选的权限预设（permission preset）名称与默认值。给成员切换权限前先用它确认确切名字。",
+        parameters: {},
+        output: {
+          schema: { type: "string" },
+          render(args, value) {
+            return [{ type: "text", text: String(value) }];
+          }
+        },
+        async execute() {
+          const catalog = await readPresetCatalog(ctx);
+          if (catalog.error) return `读取失败：${catalog.error}`;
+          const lines = [`可选权限预设（共 ${catalog.names.length} 个）`, ""];
+          for (const name of catalog.names) lines.push(`  - ${name}`);
+          if (catalog.defaultPreset) lines.push("", `新会话默认预设：${catalog.defaultPreset}`);
+          if (catalog.names.includes("auto")) {
+            lines.push("", "注意：auto 依赖「自动审查」集成；该功能一旦关闭，带 auto 的会话会无法恢复（宿主报 subagent/not-resumable）。");
+          }
+          return lines.join("\n");
+        }
+      }));
+    } catch (error) {
+      log(ctx, `list_permission_presets 工具注册失败（不影响其它工具）: ${String(error?.message ?? error)}`);
+    }
+    // 查看/切换成员（子代理）的权限预设。
+    // 子代理会话在界面上无法手动切权限预设（界面只对主会话开放），而 preset 一旦指向
+    // 当前不可用的值（典型：auto 在「自动审查」关闭后悬空），该成员就永久唤不醒——
+    // 宿主 permission-presets 在会话发布前抛错，再被 subagent 的 coldResume 统一包成
+    // `subagent/not-resumable`，报错文本完全指不到权限层。此工具提供不改界面的修正通道。
+    // 与其它工具一致：render 必须放在 output 里；单独包 try/catch，避免一个工具抛错
+    // 让整个 inject("tools") 中止（历史上四个工具一起消失过）。
+    try {
+      tools.register(defineTool({
+        name: "set_member_permission",
+        description: "给成员/子代理切换权限预设（写在该成员会话日志里，下次加载生效）。子代理无法在界面上手动切换权限预设，只能用这个工具。两个参数都可空：target 留空 = 作用于全部成员（慎用）；preset 留空 = 跟随主代理（Team Lead）当前预设。preset 必须在宿主当前可选列表里，可用 list_permission_presets 查。批量时逐条执行、回执带完整名单。",
+        parameters: {
+          target: { type: "string", description: "目标成员：成员名、sessionId 或标题关键字。留空 = 全部成员（排除 Lead）" },
+          preset: { type: "string", description: "目标权限预设名（如 danger-full-access）。留空 = 跟随主代理的预设" }
+        },
+        output: {
+          schema: { type: "string" },
+          render(args, value) {
+            return [{ type: "text", text: String(value) }];
+          }
+        },
+        async execute(args, exec) {
+          const caller = exec?.agent ?? null;
+          let preset = String(args?.preset ?? "").trim();
+          // preset 留空 = 跟随主代理（Team Lead）当前预设；主代理自己没记录预设时如实报错，
+          // 不猜一个默认值塞进去（写错预设会让成员加载失败）。
+          let followedLead = null;
+          if (!preset) {
+            const lead = await readLeaderRoute(ctx, { caller });
+            if (lead.error) return `切换失败：${lead.error}`;
+            if (!lead.preset) return `切换失败：主代理（${lead.sessionId}）没有记录权限预设，无法跟随；请显式指定 preset（可用 list_permission_presets 查）`;
+            preset = lead.preset;
+            followedLead = lead;
+          }
+          // target 留空 = 作用于全部成员
+          const resolved = resolveTargets(ctx, args?.target, { caller });
+          if (resolved.error) return `切换失败：${resolved.error}`;
+          if (resolved.all) {
+            const report = await applyPermissionToMany(ctx, resolved.targets, preset);
+            const extra = [];
+            if (followedLead) {
+              extra.push(`预设来源：跟随主代理 ${followedLead.sessionId}（${followedLead.preset}）`);
+              for (const w of followedLead.warnings ?? []) extra.push(`提示：${w}`);
+            }
+            return renderBatchReport(`批量切换权限预设 → ${preset}`, report, extra);
+          }
+          const found = resolved.targets[0];
+          const label = found.member?.name ? `${found.member.name}(${found.sessionId})` : found.sessionId;
+          const result = await switchMemberPermission(ctx, found.sessionId, preset);
+          if (result.error) return `切换失败：${result.error}`;
+          const lines = [
+            `已把成员 ${label} 的权限预设切成 ${result.to}`,
+            `原预设：${result.from ?? "(未记录)"} ｜ 新事件 seq：${result.seq}`,
+          ];
+          if (followedLead) lines.push(`预设来源：跟随主代理 ${followedLead.sessionId}`);
+          if (result.note) lines.push(`说明：${result.note}`);
+          lines.push(`当前旋钮：sandbox=${result.knobs?.sandbox ?? "(未记录)"} ｜ approval=${result.knobs?.approval ?? "(未记录)"}`);
+          lines.push("改动写在会话日志里，成员下次加载/唤醒时按折叠语义生效（最后一条 preset 事件为准）。");
+          return lines.join("\n");
+        }
+      }));
+    } catch (error) {
+      log(ctx, `set_member_permission 工具注册失败（不影响其它工具）: ${String(error?.message ?? error)}`);
+    }
+    // 创建成员并同时指定模型：宿主 spawn_teammate 没有 provider/model 参数，这里补齐。
+    // 形状必须与其它工具一致（render 放在 output 里）；且单独包 try/catch——
+    // 这个回调里任何一个 defineTool 抛错都会让整个 inject("tools") 中止，四个工具一起消失。
+    try {
+      tools.register(defineTool({
+        name: "create_teammate_with_model",
+        description: "创建团队成员，并让第一轮真实任务就用指定模型（宿主 spawn_teammate 没有 provider/model 参数，此工具补齐）。内部流程：占位任务创建 → 立刻中断（避免用默认模型把首轮跑掉）→ 写 model/selection → 投递真实任务。只能由 Team Lead 调用。",
+        parameters: {
+          name: { type: "string", required: true, description: "成员名（lower-kebab-case，唯一）" },
+          description: { type: "string", required: true, description: "职责简述" },
+          prompt: { type: "string", required: true, description: "该成员的初始任务全文" },
+          provider: { type: "string", required: true, description: "模型 provider 分组名（agnes / wb / d …；先用 list_models 查确切值）" },
+          model: { type: "string", required: true, description: "模型 id（先用 list_models 查确切值）" },
+          subagentProvider: { type: "string", description: "子代理 provider（与模型 provider 不是一回事；默认取 ctx.subagents.list() 第一个，通常就是 spawn）。一般不用填" },
+          context: { type: "string", description: "上下文来源：fresh（默认，不继承）或 fork（继承调用方已有回合）" },
+        },
+        output: {
+          schema: { type: "string" },
+          render(args, value) {
+            return [{ type: "text", text: String(value) }];
+          },
+        },
+        async execute(args, exec) {
+          const result = await createTeammateWithModel(ctx, exec, args);
+          return renderCreateTeammateResult(args, result);
+        },
+      }));
+    } catch (error) {
+      log(ctx, `create_teammate_with_model 注册失败（不影响其它工具）: ${String(error?.message ?? error)}`);
+    }
+
+    // 上下文用量自查工具：让 AI 自己按需查占用与构成，而不是每轮把数值注入系统提示词
+    // （每轮注入会让系统提示词前缀每轮变化 → prompt cache 失效 → 成本上升）。
+    if (registerContextUsageTool(ctx, defineTool, tools)) {
+      log(ctx, "上下文用量工具已注册 (context_usage)");
+    }
+    // 跨会话消息 + 指定模型新建会话（三个工具一次注册）。
+    // 整体包 try/catch：注册期抛错会连累同批其它工具（本项目历史事故），失败只留痕、不阻断。
+    try {
+      if (registerSessionMessagingTools(ctx, defineTool, tools)) {
+        log(ctx, "跨会话工具已注册 (list_sessions / send_to_session / create_session)");
+      }
+    } catch (error) {
+      log(ctx, `跨会话工具注册失败（不影响其它工具）: ${String(error?.message ?? error)}`);
+    }
+    try {
+      // 记忆取回的手动通道：让 AI 自己按需回溯（自动注入之外的补充）
+      if (registerMemoryRecallTool(ctx, defineTool, tools)) {
+        log(ctx, "记忆取回工具已注册 (recall_memory)");
+      }
+    } catch (error) {
+      log(ctx, `记忆取回工具注册失败（不影响其它工具）: ${String(error?.message ?? error)}`);
+    }
+    log(ctx, "成员模型工具已注册 (list_models / set_member_model)");
+    // 聊天框指令 `/model-switch`：用户自己就能看/切成员模型的入口（与 AI 工具同一套切换 + 查证路径）。
+    // 异步注册 + 独立兜底：宿主 commands 服务或 brand 包不可用时只留痕，绝不影响其它功能（同既有约定）。
+    registerModelSwitchCommand(ctx)
+      .then((ok) => { if (ok) log(ctx, "聊天框指令已注册 (/model-switch)"); })
+      .catch((error) => log(ctx, `聊天框指令注册失败（不影响其它功能）: ${String(error?.message ?? error)}`));
+    // 聊天框指令 `/perm-switch`：子代理在界面上切不了权限预设，只能靠这条写会话日志的通道。
+    registerPermSwitchCommand(ctx)
+      .then((ok) => { if (ok) log(ctx, "聊天框指令已注册 (/perm-switch)"); })
+      .catch((error) => log(ctx, `权限指令注册失败（不影响其它功能）: ${String(error?.message ?? error)}`));
+}