@zhushanwen/pi-subagent-workflow 9.3.0 → 9.4.1

package/src/interface/command/commands.ts

@@ -24,7 +24,13 @@ import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-wor
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import type { LauncherDeps } from "@zhushanwen/subagent-core";
-import { abortRun, getSubagentService, resumeRun } from "@zhushanwen/subagent-core";
+import {
+  abortRun,
+  assertModelInCatalog,
+  getModelConfigService,
+  getSubagentService,
+  resumeRun,
+} from "@zhushanwen/subagent-core";
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
 import { parseWorkflowRpcCommand, type WorkflowRpcAction } from "./command-actions.ts";
 import { createWorkflowsView, type ViewActions } from "../tui/views/WorkflowsView.ts";
@@ -45,6 +51,13 @@ const STATUS_ORDER: Record<string, number> = {
 /** 未知 status 的默认排序权重（排在已知 status 之后）。 */
 const UNKNOWN_STATUS_WEIGHT = 9;
 
+/** RPC 非 lifecycle 通知 action 词表（abort/resume 之外的三个纯 notify 分支——
+ *  rpcSideNotify 的穷举域；abort/resume 在 handleRpcMode 内 if 早退）。 */
+type WorkflowRpcSideAction = Extract<
+  WorkflowRpcAction,
+  { action: "lifecycle-removed" | "lifecycle-missing-id" | "noop" }
+>;
+
 // ── /workflows command ───────────────────────────────────────
 
 /**
@@ -123,37 +136,7 @@ export function registerWorkflowsCommand(
         return;
       }
 
-      // TUI 动词命令：/workflows resume <runId>——执行断点续跑后 notify，不打开面板
-      // （abort 动词在 TUI 侧无既有通道，不在此顺手扩——resume 是本批接入面）
-      const trimmedArgs = args.trim();
-      const [verb, ...rest] = trimmedArgs.split(/\s+/).filter(Boolean);
-      if (verb === "resume") {
-        const runId = rest[0];
-        if (!runId) {
-          ctx.ui.notify("Usage: /workflows resume <runId>", "warning");
-          return;
-        }
-        try {
-          await resumeRun(runId, deps);
-          ctx.ui.notify(
-            `Workflow ${runId}: resuming — completed calls replay at zero token cost, unfinished calls re-dispatched`,
-            "info",
-          );
-        } catch (err) {
-          ctx.ui.notify(`Failed to resume workflow ${runId}: ${toErrorMessage(err)}`, "warning");
-        }
-        return;
-      }
-
-      // 直接按 runId / 前缀匹配打开
-      const directRunId = trimmedArgs;
-      if (directRunId) {
-        await openByRunId(directRunId, getRuns, ctx, deps);
-        return;
-      }
-
-      // 无参——列表选择
-      await openFromList(getRuns, ctx, deps);
+      await handleTuiCommand(args, ctx, getRuns, deps);
     },
   });
 }
@@ -172,37 +155,36 @@ export function registerWorkflowsCommand(
  *   （F3 定稿——提示语义优先于 missing-id：run 一次性生命周期后不可挂起）
  * - lifecycle-missing-id → Usage 提示
  * - noop → 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+ *
+ * 分派形态：两个 lifecycle 动作 if 早退（控制流收窄，零断言），其余三个纯
+ * notify action 收敛进 rpcSideNotify 的穷举 switch。
  */
 async function handleRpcMode(
   parsed: WorkflowRpcAction,
   ctx: ExtensionCommandContext,
   deps: LauncherDeps,
 ): Promise<void> {
+  if (parsed.action === "abort") {
+    await abortWithNotify(parsed.runId, deps, ctx);
+    return;
+  }
+  if (parsed.action === "resume") {
+    await resumeWithNotify(parsed.runId, parsed.model, deps, ctx);
+    return;
+  }
+  rpcSideNotify(parsed, ctx);
+}
+
+/**
+ * 非 lifecycle RPC action（lifecycle-removed / lifecycle-missing-id / noop）的
+ * 穷举 notify 分派。default 保留 exhaustiveness 断言：未来新增 action verb 忘加
+ * case 时 tsc 报错。
+ */
+function rpcSideNotify(
+  parsed: WorkflowRpcSideAction,
+  ctx: ExtensionCommandContext,
+): void {
   switch (parsed.action) {
-    case "abort": {
-      try {
-        await abortRun(parsed.runId, deps);
-        // abort 单态后 pastTense 固定（原三态拼接随 pause/resume 删除）
-        ctx.ui.notify(`Workflow ${parsed.runId}: aborted`, "info");
-      } catch (err) {
-        const msg = toErrorMessage(err);
-        ctx.ui.notify(`Failed to abort workflow ${parsed.runId}: ${msg}`, "warning");
-      }
-      return;
-    }
-    case "resume": {
-      try {
-        await resumeRun(parsed.runId, deps);
-        ctx.ui.notify(
-          `Workflow ${parsed.runId}: resuming — completed calls replay at zero token cost, unfinished calls re-dispatched`,
-          "info",
-        );
-      } catch (err) {
-        const msg = toErrorMessage(err);
-        ctx.ui.notify(`Failed to resume workflow ${parsed.runId}: ${msg}`, "warning");
-      }
-      return;
-    }
     case "lifecycle-removed":
       ctx.ui.notify(
         `Workflow ${parsed.verb} has been removed — runs are one-shot. To stop a run early: /workflows abort <runId>`,
@@ -210,7 +192,9 @@ async function handleRpcMode(
       );
       return;
     case "lifecycle-missing-id":
-      ctx.ui.notify(`Usage: /workflows ${parsed.verb} <runId>`, "warning");
+      // Usage 按 verb 区分（与 TUI verb 分支同文案——两模式统一）：resume 的可选
+      // [model] 参数要出现在提示里，GUI 侧缺 runId 时得到的指引不指向旧用法。
+      ctx.ui.notify(missingIdUsageText(parsed.verb), "warning");
       return;
     case "noop":
       ctx.ui.notify("View workflows in the composer task tray", "info");
@@ -223,6 +207,122 @@ async function handleRpcMode(
   }
 }
 
+/** lifecycle-missing-id 的 Usage 文案：resume 带可选 [model] 参数，其余 verb 仅 runId。 */
+function missingIdUsageText(verb: "abort" | "resume"): string {
+  return verb === "resume" ? "Usage: /workflows resume <runId> [model]" : `Usage: /workflows ${verb} <runId>`;
+}
+
+/** abort 执行 + 结果通知（成功/失败均 notify，不向上抛——RPC 通道唯一 abort 入口）。 */
+async function abortWithNotify(
+  runId: string,
+  deps: LauncherDeps,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  try {
+    await abortRun(runId, deps);
+    // abort 单态后 pastTense 固定（原三态拼接随 pause/resume 删除）
+    ctx.ui.notify(`Workflow ${runId}: aborted`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Failed to abort workflow ${runId}: ${toErrorMessage(err)}`, "warning");
+  }
+}
+
+/**
+ * resume 执行 + 结果通知（TUI verb / RPC verb 两通道共享——同语义同文案，防
+ * 双处文案漂移）。显式 model 先做目录预检（assertResumeModelInCatalog），成功/
+ * 失败均 notify（不向上抛）。
+ */
+async function resumeWithNotify(
+  runId: string,
+  model: string | undefined,
+  deps: LauncherDeps,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  try {
+    if (model !== undefined) assertResumeModelInCatalog(model);
+    await resumeRun(runId, deps, ...resumeModelArgs(model));
+    ctx.ui.notify(resumeStartedText(runId, model), "info");
+  } catch (err) {
+    ctx.ui.notify(`Failed to resume workflow ${runId}: ${toErrorMessage(err)}`, "warning");
+  }
+}
+
+/** 可选 model → resumeRun 变参（无覆盖 = 空变参，不造覆盖记账）。 */
+function resumeModelArgs(model: string | undefined): [] | [{ model: string }] {
+  return model !== undefined ? [{ model }] : [];
+}
+
+/** resume 启动通知文案（带显式 model 时回显模型，用户可确认覆盖生效）。 */
+function resumeStartedText(runId: string, model: string | undefined): string {
+  return `Workflow ${runId}: resuming${model !== undefined ? ` with model ${model}` : ""} — completed calls replay at zero token cost, unfinished calls re-dispatched`;
+}
+
+/**
+ * TUI 模式命令分派：resume verb → 断点续跑后 notify（不打开面板）；带参 → 按
+ * runId/前缀匹配打开；无参 → 列表选择。（abort 动词在 TUI 侧无既有通道，不在此
+ * 顺手扩——resume 是本批接入面）
+ */
+async function handleTuiCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  getRuns: () => Map<string, WorkflowRun>,
+  deps: LauncherDeps,
+): Promise<void> {
+  const trimmedArgs = args.trim();
+  const [verb, ...rest] = trimmedArgs.split(/\s+/).filter(Boolean);
+  if (verb === "resume") {
+    await resumeTuiVerb(rest, ctx, deps);
+    return;
+  }
+  // 直接按 runId / 前缀匹配打开
+  if (trimmedArgs) {
+    await openByRunId(trimmedArgs, getRuns, ctx, deps);
+    return;
+  }
+  // 无参——列表选择
+  await openFromList(getRuns, ctx, deps);
+}
+
+/**
+ * TUI resume verb：缺 runId 给 Usage 提示。可选第二参数 = 显式模型 canonical ref
+ * （'provider/modelId[:thinkingLevel]'）——落统一覆盖记账（F1-26 后续项：与
+ * setModel 补切同通道，resume 合一步表达）。执行与通知复用 RPC 同款 resumeWithNotify。
+ */
+async function resumeTuiVerb(
+  rest: string[],
+  ctx: ExtensionCommandContext,
+  deps: LauncherDeps,
+): Promise<void> {
+  const runId = rest[0];
+  if (!runId) {
+    ctx.ui.notify("Usage: /workflows resume <runId> [model]", "warning");
+    return;
+  }
+  await resumeWithNotify(runId, rest[1], deps, ctx);
+}
+
+/**
+ * 命令通道显式 model 的目录预检（D8 拒单语义，与 tool 通道 run/resume action 同款
+ * ——isModelRef 语法闸在 core resumeRun，此处补目录存在性：语法合法但目录查无
+ * （如 provider 段拼写错）在写覆盖记账之前同步拒绝，不延迟到派发期，避免「记账已
+ * 落盘 + 命令已 notify 成功」的假成功形态；三通道（TUI verb / RPC verb / tool）对称）。
+ * throw 落调用方 try/catch，分类化错误文案（含可用模型清单 + 修复指引）经 notify
+ * 直达用户。单例缺席（session_start 前不可达）降级跳过 + warn 留痕——派发期
+ * identity 解析仍是权威裁决（与 tool 通道降级语义一致）。
+ */
+function assertResumeModelInCatalog(model: string): void {
+  const modelService = getModelConfigService();
+  if (modelService === null) {
+    getLogger("subagent-workflow").warn(
+      "[commands] model catalog unavailable (model service not initialized) — resume model catalog check skipped; dispatch-time identity resolution remains authoritative",
+    );
+    return;
+  }
+  assertModelInCatalog(model, modelService.getModelRegistry(), {
+    source: "resume model override",
+  });
+}
+
 /**
  * TUI 模式：按 runId 直接打开对应 run 的 view（精确匹配优先，前缀唯一匹配次之）。
  * 均未命中 → error notify。

package/src/interface/command/subagent-model.ts

@@ -0,0 +1,268 @@
+// src/interface/command/subagent-model.ts
+//
+// /subagent-model 命令——subagent/workflow run 执行模型切换的宿主触达通道消费端
+// （subagent-model-switch §7.1.1 通道，U6）。内部 RPC 命令：runtime 网关适配器经
+// client.prompt("/subagent-model <单行JSON>") 短路本 handler（不经主 agent LLM，
+// pi _tryExecuteExtensionCommand 主路径对 / 前缀先行执行）。
+//
+// 通道契约（§7.1.1 四要素）：
+// - 载荷 = 单行 JSON {requestId, recordId?|runId?, provider, modelId, thinkingLevel?}；
+// - 执行 = 本进程直调宿主 setModel 编排（service.setModel，§7.2 单一三步）；
+// - 回执 = 一切结果（SetModelReply 三 scope / 错误 envelope）写结果文件
+//   `<subagent 数据根>/model-switch/<requestId>.json` 后正常返回——**全程不抛**；
+//   runtime 出站点在 handler 返回后读文件一次（写后读，无轮询无监视）。
+// - 结果文件承载 core SetModelReply 形状（scope 判别）——extension 不依赖
+//   @taiji/shared，wire 三形态映射归 runtime 适配器（依赖方向的唯一合法位置）。
+//
+// TUI 分支不存在：本命令是 GUI 通道专用内部命令，非交互入口（照 /subagents RPC
+// verb 的 GUI 屏蔽先例，TUI 手敲仅得指引提示）。
+
+import * as path from "node:path";
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import {
+  ENV_ROOT_CWD,
+  getSubagentModelSwitchResultsDir,
+  getSubagentService,
+  writeAtomicFileSync,
+} from "@zhushanwen/subagent-core";
+import type { ModelSwitchTarget, SetModelReply } from "@zhushanwen/subagent-core";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+
+const logger = getLogger("subagents");
+
+/**
+ * requestId 文件名白名单：`[\w-]{1,128}`（与 core record id 白名单同式——防路径穿越；
+ * 生产源 = runtime randomUUID，字符集 ⊆ 白名单，本式仅防御畸形通道输入）。
+ */
+const REQUEST_ID_PATTERN = /^[\w-]{1,128}$/;
+
+/** 错误 envelope 形状（结果文件内的失败承载；code 值域 = 本文件错误分型常量族）。
+ *  scope: "error" = 网关 mapResultFileToWireReply 的分派判别键（D3-A4 缺陷修复：
+ *  缺 scope 时域内失败被「scope 未知」通道错误吞掉，真实 code/recovery 丢失）。 */
+interface SubagentModelEnvelope { // oe-exempt:20261006:framework:通道结果信封契约形状（单命令单载体，单实现常态）
+  scope: "error";
+  error: { code: string; message: string; recovery: string };
+}
+
+/** /subagent-model 命令的依赖注入面（注册点装配生产实现，单测注入桩）。 */
+export interface SubagentModelCommandDeps { // oe-exempt:20261006:framework:命令 handler 依赖注入面（注册点装配，单实现常态）
+  /** 宿主 setModel 编排单例（session_start 前 null——envelope 分型承接）。 */
+  getService: () => ReturnType<typeof getSubagentService>;
+  /** agentDir 锚（pi SDK 活源，与 session-lifecycle 装配同源）。 */
+  resolveAgentDir: () => string;
+  /** 树根主 cwd（session-baselines rootCwd 同式推导，见 registerSubagentModelCommand）。 */
+  resolveRootCwd: () => string;
+}
+
+/** 载荷解析三态（显式判别：无 requestId = 无法命名结果文件，与字段校验失败分流）。 */
+type ParsedPayload =
+  | { ok: true; requestId: string; payload: SubagentModelPayload }
+  | { ok: false; requestIdMissing: true }
+  | { ok: false; requestIdMissing: false; requestId: string; validationMessage: string };
+
+/** 载荷结构（wire 契约 §7.1.1：recordId/runId 二选一，provider/modelId 必填）。
+ *  字段经逐项 typeof 抽取组装（JSON 边界不落地 unknown 断言）。 */
+interface SubagentModelPayload { // oe-exempt:20261006:framework:通道载荷契约形状（单命令单载体，单实现常态）
+  requestId: string;
+  recordId?: string;
+  runId?: string;
+  provider?: string;
+  modelId?: string;
+  thinkingLevel?: string;
+}
+
+/** 非空字符串字段抽取（undefined = 缺失或类型不符，二者同判缺失）。 */
+function nonEmptyString(v: unknown): string | undefined {
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/**
+ * 解析单行 JSON 载荷（§7.1.1 要素 1）。requestId 缺失/非法 → requestIdMissing（无法
+ * 命名结果文件，本侧零回执——runtime 出站点超时路径承接通道失败，仅日志留痕）；
+ * 其余字段校验失败在 requestId 在场时落 envelope（invalid_payload 分型）。
+ */
+function parsePayload(argsStr: string): ParsedPayload {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(argsStr.trim());
+  } catch {
+    return { ok: false, requestIdMissing: true };
+  }
+  if (typeof raw !== "object" || raw === null) return { ok: false, requestIdMissing: true };
+  const obj = raw as Record<string, unknown>;
+  const requestId = nonEmptyString(obj.requestId);
+  if (requestId === undefined || !REQUEST_ID_PATTERN.test(requestId)) {
+    return { ok: false, requestIdMissing: true };
+  }
+  const payload: SubagentModelPayload = {
+    requestId,
+    recordId: nonEmptyString(obj.recordId),
+    runId: nonEmptyString(obj.runId),
+    provider: nonEmptyString(obj.provider),
+    modelId: nonEmptyString(obj.modelId),
+    thinkingLevel: nonEmptyString(obj.thinkingLevel),
+  };
+  const validationMessage = validatePayload(payload);
+  if (validationMessage !== undefined) {
+    return { ok: false, requestIdMissing: false, requestId, validationMessage };
+  }
+  return { ok: true, requestId, payload };
+}
+
+/** 载荷字段校验（requestId 之外的域内畸形 → envelope invalid_payload 的 message 文案）。 */
+function validatePayload(payload: SubagentModelPayload): string | undefined {
+  if ((payload.recordId !== undefined) === (payload.runId !== undefined)) {
+    return "payload 需要 recordId（chat 域）或 runId（workflow run 级）二选一";
+  }
+  if (payload.provider === undefined) {
+    return "payload 缺 provider（canonical ref 的 provider 段）";
+  }
+  if (payload.modelId === undefined) {
+    return "payload 缺 modelId（canonical ref 的 modelId 段）";
+  }
+  return undefined;
+}
+
+/**
+ * 结果文件写入（唯一出站原语，永不抛）：writeAtomicFileSync（tmp+rename，防 runtime
+ * 读到半文件）+ 目录递归建。写失败 = 通道回执丢失（runtime 超时路径承接），日志留痕。
+ */
+function writeResultFile(resultsFile: string, content: string): void {
+  try {
+    writeAtomicFileSync(resultsFile, content);
+  } catch (err) {
+    logger.warn(`[subagent-model] result file write failed (runtime will report channel timeout): ${toErrorMessage(err)}`, {
+      resultsFile,
+    });
+  }
+}
+
+/** 提取引擎分型错误码（EngineError 载荷 .code——分型值域校验交由 runtime 侧）。 */
+function errorCodeOf(err: unknown): string | undefined {
+  // `in` 收窄（TS 4.9+）：Error & Record<"code", unknown>，零断言读载荷。
+  if (!(err instanceof Error) || !("code" in err)) return undefined;
+  const code: unknown = err.code;
+  return typeof code === "string" && code !== "" ? code : undefined;
+}
+
+/**
+ * RPC 执行体（§7.1.1 要素 2）：payload 校验 → 宿主 setModel → 结果文件。
+ * **全程不抛**——一切异常 catch 后落错误 envelope；校验失败同落 envelope。
+ */
+export async function runSubagentModelRpc(
+  deps: SubagentModelCommandDeps,
+  argsStr: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const parsed = parsePayload(argsStr);
+  if (!parsed.ok) {
+    if (parsed.requestIdMissing) {
+      // requestId 不可用 = 无关联回执面：日志留痕即可，runtime 超时按通道失败应答
+      //（结果文件名 = requestId，载荷缺失时本侧无从落文件）。
+      logger.warn("[subagent-model] payload unparseable or requestId missing — no result file, runtime timeout path will report");
+      ctx.ui.notify("/subagent-model payload requires requestId — request dropped", "warning");
+      return;
+    }
+    // requestId 在场 + 字段校验失败：envelope 落盘（invalid_payload 分型）。
+    const invalidFile = path.join(
+      getSubagentModelSwitchResultsDir(deps.resolveAgentDir(), deps.resolveRootCwd()),
+      `${parsed.requestId}.json`,
+    );
+    writeResultFile(
+      invalidFile,
+      JSON.stringify({
+        scope: "error",
+        error: {
+          code: "invalid_payload",
+          message: parsed.validationMessage,
+          recovery: "修正 subagent.setModel 载荷后重试（runtime 协议面问题，正常使用不可达）",
+        },
+      } satisfies SubagentModelEnvelope),
+    );
+    return;
+  }
+  const { requestId, payload } = parsed;
+  const resultsFile = path.join(
+    getSubagentModelSwitchResultsDir(deps.resolveAgentDir(), deps.resolveRootCwd()),
+    `${requestId}.json`,
+  );
+
+  try {
+    const service = deps.getService();
+    if (!service) {
+      writeResultFile(
+        resultsFile,
+        JSON.stringify({
+          scope: "error",
+          error: {
+            code: "subagent_runtime_not_ready",
+            message: "subagent 执行运行时未就绪（session 未启动或已 dispose）",
+            recovery: "先在该会话派发一条消息启动 subagent 运行时，再重试切换",
+          },
+        } satisfies SubagentModelEnvelope),
+      );
+      return;
+    }
+
+    // 目标组装（§6.1 作用域分流）：recordId → chat 域（getRecordForAction 同 message/close
+    // 的统一入口——含归属校验与冷查）；runId → run 级（终局/成员清单校验在编排步骤①）。
+    let target: ModelSwitchTarget;
+    if (typeof payload.recordId === "string") {
+      target = { domain: "chat", record: service.chatActions.getRecordForAction(payload.recordId) };
+    } else {
+      target = { domain: "workflow-run", runId: payload.runId as string };
+    }
+
+    const thinkingLevel = payload.thinkingLevel as string | undefined;
+    const reply: SetModelReply = await service.setModel(
+      target,
+      { provider: payload.provider as string, modelId: payload.modelId as string },
+      thinkingLevel,
+    );
+    // 应答三 scope 原样落文件（scope 判别由 runtime 适配器消费——core 形状是唯一权威）。
+    writeResultFile(resultsFile, JSON.stringify(reply));
+  } catch (err) {
+    // §7.5 通道行同族语义：handler 域内失败如实落 envelope（生效状态未知不虚构——
+    // 消息携带宿主编排错误原文，恢复动作照通道行）。
+    writeResultFile(
+      resultsFile,
+      JSON.stringify({
+        scope: "error",
+        error: {
+          code: errorCodeOf(err) ?? "subagent_model_switch_failed",
+          message: toErrorMessage(err),
+          recovery: "重试切换（覆盖替换幂等）；当前生效状态以面板与记录链为准",
+        },
+      } satisfies SubagentModelEnvelope),
+    );
+  }
+}
+
+/** 注册 /subagent-model 命令（内部 RPC 通道，taiji GUI 专用）。 */
+export function registerSubagentModelCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("subagent-model", {
+    description: "Internal RPC: switch subagent/workflow-run model (single-line JSON payload)",
+    handler: async (argsStr: string, ctx: ExtensionCommandContext) => {
+      if (ctx.mode !== "rpc") {
+        ctx.ui.notify("/subagent-model is an internal taiji GUI channel — switch models from the subagent panel", "warning");
+        return;
+      }
+      // rootCwd 与 session-baselines 构造推导同式（env PI_SUBAGENT_ROOT_CWD 贯穿 ||
+      // ctx.cwd）——保证结果目录与 records 落同一 enc 段（enc 段不变量，path-encoding
+      // 头注同族约束）。本命令只在主进程执行（子进程无 / 命令通道），env 恒缺省。
+      await runSubagentModelRpc(
+        {
+          getService: getSubagentService,
+          resolveAgentDir: getAgentDir,
+          resolveRootCwd: () => process.env[ENV_ROOT_CWD] || ctx.cwd,
+        },
+        argsStr,
+        ctx,
+      );
+    },
+  });
+}

package/src/interface/tool/__tests__/tool-workflow-resume.test.ts

@@ -130,6 +130,26 @@ describe("actionResume", () => {
     expect(options.budgetTokens).toBe(50_000);
   });
 
+  it("model 形参透传（F1-26 后续项：core 落统一覆盖记账——补切 + 无参 resume 合一步）", async () => {
+    const recordPath = writeRecordStream([runCreatedFrame('{"a":1}')]);
+    await actionResume(
+      { action: "resume", runId: "wf-test", args: { a: 1 }, model: "p2/m2" } as never,
+      makeDeps(recordPath) as never,
+    );
+    const options = vi.mocked(resumeRun).mock.calls[0]![2] as { model?: string };
+    expect(options.model).toBe("p2/m2");
+  });
+
+  it("model 缺省 → options 不带 model 键（无参 resume 不写覆盖记账）", async () => {
+    const recordPath = writeRecordStream([runCreatedFrame('{"a":1}')]);
+    await actionResume(
+      { action: "resume", runId: "wf-test", args: { a: 1 } } as never,
+      makeDeps(recordPath) as never,
+    );
+    const options = vi.mocked(resumeRun).mock.calls[0]![2] as { model?: string };
+    expect("model" in options).toBe(false);
+  });
+
   it("tokens 缺省 → options 不带 budgetTokens 键（core 侧跳过覆盖、走三档回落）", async () => {
     await actionResume(
       { action: "resume", runId: "wf-test" } as never,

package/src/interface/tool/tool-workflow.ts

@@ -114,7 +114,11 @@ const WorkflowParams = Type.Object({
     Type.String({ description: "Error/reason message (optional, used with abort)" }),
   ),
   model: Type.Optional(Type.String({
-    description: "Run-level model override in 'provider/modelId' format. When set, all agents spawned by this run inherit it by default (unless a per-call agent() opts.model is set). Omit to inherit the main agent's model.",
+    description:
+      "Run-level model override in 'provider/modelId' format. When set, all agents spawned by this run inherit it by default (unless a per-call agent() opts.model is set). " +
+      "Also accepted on action:\"resume\" — recorded as the run's user override (same channel as a panel switch) and drives all re-dispatched steps. " +
+      "A user-issued runtime model override (panel model switch / /subagent-model command) takes precedence over this parameter — user override wins over any explicitly scripted model. " +
+      "Omit to inherit the main agent's model.",
   })),
   thinkingLevel: Type.Optional(StringEnum(THINKING_ORDER, {
     description: "Run-level thinkingLevel override (off/minimal/low/medium/high/xhigh/max). All agents in this run inherit it by default. Omit to default each agent to its model's highest available level.",
@@ -232,14 +236,21 @@ export function registerWorkflowTool(
       "completed calls from the record at zero token cost and continues where the run stopped. " +
       "Do NOT resume a settled (done/failed/cancelled) run — start a new run instead.",
       "resume: pass the SAME args as the original run (they are verified field-by-field; a mismatch is rejected " +
-      "with the differing fields listed). Omit args to reuse the original ones. Changed args = different intent = new run.",
+      "with the differing fields listed). Omit args to reuse the original ones. Changed args = different intent = new run. " +
+      "To resume with a specific model: pass model ('provider/modelId') on the resume itself — it is recorded as the " +
+      "run's user override (same channel as a panel switch), drives all re-dispatched steps, and persists for later " +
+      "resumes without the parameter. Alternatively switch the run's model first (panel selector or /subagent-model) " +
+      "then resume without model — both are the same override channel.",
       "Call shapes (JSON): " +
       "- run: {\"action\":\"run\",\"name\":\"<script>\",\"args\":{...},\"tokens\":N,\"time\":N,\"model\":\"<provider/modelId>\",\"thinkingLevel\":\"<level>\"}. " +
       "- status: {\"action\":\"status\"}. " +
       "- abort: {\"action\":\"abort\",\"runId\":\"<id>\"} (optional: {\"error\":\"<reason>\"}). " +
-      "- resume: {\"action\":\"resume\",\"runId\":\"<id>\",\"args\":{...},\"tokens\":N,\"time\":N} — args/tokens/time optional.",
+      "- resume: {\"action\":\"resume\",\"runId\":\"<id>\",\"args\":{...},\"tokens\":N,\"time\":N,\"model\":\"<provider/modelId>\"} — args/tokens/time/model optional.",
       "Budget: Do NOT set tokens/time unless the user explicitly requests a limit. Built-in workflows run unlimited by default.",
-      "Model/thinkingLevel: omit by default (inherit main agent's model). Only set model/thinkingLevel when the user explicitly requests a specific model or thinking depth for this run.",
+      "Model/thinkingLevel: omit by default (inherit main agent's model). Only set model/thinkingLevel when the user explicitly requests a specific model or thinking depth for this run. " +
+      "Note: a user-issued runtime model override (panel switch / /subagent-model) takes precedence over the model parameter — an explicitly scripted thinkingLevel still applies " +
+      "(explicit levels outrank the override's inline level). If a run's explicitly scripted model seems ignored, " +
+      "check for an active user override (run journal model-override frame) before assuming a resolution bug.",
       "Anti-patterns: Flattening args sub-fields (task/items/...) to the top level — they belong inside args. Calling {\"action\":\"run\"} without name.",
       "CRITICAL: For orchestration patterns, ALWAYS use action:run with the <location> absolute " +
       "path of the matching listed workflow — NEVER use workflow-script action:generate to recreate patterns " +
@@ -565,10 +576,28 @@ export async function actionResume(
   assertEntryTimeBudget(params.time);
   assertEntryTokenBudget(params.tokens);
 
+  // 显式 model 参数的目录预检（run action 同款 D8 拒单语义——查无同步 throw 零写，
+  // 单例缺席降级跳过 + warn，派发期 identity 解析仍是权威裁决）。
+  if (params.model !== undefined) {
+    const modelService = getModelConfigService();
+    if (modelService === null) {
+      logger.warn(
+        "[tool-workflow] model catalog unavailable (model service not initialized) — resume model catalog check skipped; dispatch-time identity resolution remains authoritative",
+      );
+    } else {
+      assertModelInCatalog(params.model, modelService.getModelRegistry(), {
+        source: "resume model override",
+      });
+    }
+  }
+
   const options: ResumeRunOptions = {
     ...(params.time !== undefined ? { budgetTimeMs: params.time } : {}),
     // token 预算显式覆盖（与 time 同款通道；三档回落与落盘归 core 单点）
     ...(params.tokens !== undefined ? { budgetTokens: params.tokens } : {}),
+    // [F1-26 后续项] 显式 model 透传（core 落统一覆盖记账——「补切 + 无参 resume」
+    // 的合一步；格式与目录已在本入口预检，记账落盘归 core 锁段单点）
+    ...(params.model !== undefined ? { model: params.model } : {}),
     // [§2.5] args 原样下传由 core 判定（D14 单源）；journalDir 传壳的 store 同源目录，
     // 否则 core 会按模块锚解析 record 路径——多 session 场景会静默读成「无记录」
     //（D14 静默放行 = 安全语义反转；core 锚点与壳 store 锚点必须同源）。