@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/types.ts

@@ -88,6 +88,15 @@ export type ExecutionMode = "background";
  *
  * 设计：AgentEvent 携带 updateFromEvent 收口进 record 所需的**全部数据**——
  * tool_end 带 result（供 turn.toolCalls 存完整 ToolCall），无需翻译层旁路累积。
+ *
+ * ACP 词汇对照（D11 注记级校准，零行为变更；新引擎实现者按本表对齐语义，
+ * 详见 docs/architecture/subagent-engine-gui-visibility.md §3.3 D11）：
+ *   text_delta / thinking_delta ↔ ACP content blocks（text / thinking）
+ *   tool_start / tool_end      ↔ ACP tool_call / tool_call_update
+ *   turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
+ *   compaction                 ↔ ACP session/compaction
+ * 本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
+ * 与跨引擎 trace 映射的翻译成本最低。
  */
 export type AgentEvent =
   | { type: "tool_start"; toolName: string; args?: unknown }
@@ -384,6 +393,23 @@ export interface ExecutionRecord {
    * 向后兼容：旧 record 无此字段，按默认值处理。
    */
   readonly idleTimeoutMs?: number;
+  /**
+   * 实际执行引擎 id（P4 路由留痕，D9①）。创建时确定不可变；缺省（存量 record）
+   * = pi 投影（消费方零迁移）。持久化经 subagent-record entry。
+   */
+  readonly engine?: string;
+  /**
+   * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源；
+   * 缺省 = 无 fallback。持久化经 subagent-record entry。
+   */
+  readonly engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U2：非 pi run resolve 后回填、终态迁移落 entry 前——run 前
+   * 缺省不可用）。sessionRef 整体透传（失败终态 sessionId 缺失时仍回填已有部分，
+   * 读侧①级降②级的防御形态）；journalPath 为 retarget 后实际落盘路径。pi 分支不
+   * 回填（sessionFile 即定位符）。持久化经 subagent-record entry。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 
   // ── 状态（实时更新）──
   status: ExecutionStatus;
@@ -563,6 +589,16 @@ export interface ExecuteOptions {
    * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
    */
   idleTimeoutMs?: number;
+  /**
+   * 实际执行引擎 id（P4 路由留痕）：pi 引擎由 PiEngine.run 在还原 opts 时写入；
+   * 缺省（历史调用方不设）= pi 投影。createRecordForMode 读入 record identity。
+   */
+  engine?: string;
+  /**
+   * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎时由路由层写入）。
+   * from = 请求引擎 id，reason 恒 'engine_probe_failed'（GUI 警告条数据源）。
+   */
+  engineFallback?: { from: string; reason: string };
   // 注：fork 深度不从外部传入（曾暴露 parentForkDepth，改用 ALS 后 execute 内部从调用链派生，
   // 公开字段成为死字段误导调用方，已移除）。深度限制检查见 session-runner.ts 内部 RunOptions.parentForkDepth
   // （与历史残留的 types.ts RunOptions 同名不同 interface——后者已删除）。
@@ -731,6 +767,19 @@ export interface SubagentRecord {
   externalInstance?: AliveMarker;
   /** fork 模式下的 worktree handle。 */
   worktreeHandle?: WorktreeHandle;
+  /**
+   * 实际执行引擎 id（P4 路由留痕）。缺省 = pi 投影（存量 record 零迁移）；
+   * GUI 警告条/引擎标记的数据源之一。
+   */
+  engine?: string;
+  /** 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+  engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U1：EngineHandleData 的持久化消费面子集，引擎无关——
+   * sessionRef 整体透传不枚举内部键）。read 降级链①②级的数据源（runtime
+   * subagent-engine-history）；缺省 = pi（走 JSONL 直读链）。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 }
 
 // ============================================================
@@ -747,6 +796,13 @@ export interface SubagentRecord {
 export interface SubagentsGlobalConfig {
   version: number;
   maxConcurrent: number;
+  /**
+   * 全局默认执行引擎（D9 三层优先级的最底层：调用参数 > agent frontmatter > 本值）。
+   * 缺省 'pi'（P4 路由层 DEFAULT_ENGINE_ID）。加载期只做类型校验，注册表校验归路由层。
+   */
+  defaultEngine?: string;
+  /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
+  engineRouting?: { strict: boolean };
 }
 
 // ============================================================

package/src/index.ts

@@ -16,7 +16,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
+import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
@@ -24,6 +24,15 @@ import { bestEffort } from "./execution/best-effort.ts";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
 import { getOrCreateChannelRegistry } from "./execution/channel-registry-access.ts";
 import { DialogGlobalQueue } from "./execution/dialog-queue.ts";
+// [U7] 引擎列表状态文件（registry → engines.json，GUI 引擎选择器数据源）
+import { syncEnginesFile } from "./execution/engine/engine-discovery.ts";
+// [U7] 引擎模型段注入（defaultEngine 非 pi 时 system prompt 补 <available_<engine>_models>）
+import { buildEngineModelsPromptAppend } from "./execution/engine/model-prompt.ts";
+// [P1 引擎接线] 组合根登记 'pi' 引擎进 registry（引擎获取统一经 getEngine，缺省 id 'pi'）
+import { registerPiEngine } from "./execution/engine/engines/pi/registration.ts";
+// [P3 引擎接线] 组合根登记 'zcode' 引擎（spawn 单轮模式；engineDataDir 默认走
+// common/data-dir SSOT，见 engines/zcode/registration.ts）
+import { registerZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
 import { createUiRequestHandlerForMode } from "./execution/ui-request-handler-factory.ts";
 import {
   getModelConfigService,
@@ -160,6 +169,22 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // 的 getLogger("subagents") 也能走 appendEntry。
   setPiHandle(pi);
 
+  // [P1 引擎接线] 组合根登记缺省引擎：进程级 SubagentService 单例（session_start 注入）
+  // 经 registry 以 'pi' 暴露——引擎获取从此统一走 getEngine(DEFAULT_ENGINE_ID)，上层
+  // 不再硬编码「spawn pi」。幂等（registerEngine 覆盖语义），工厂惰性解析服务单例。
+  // P4 配置路由（agent frontmatter engine 字段 + 三层优先级）在本登记之上消费。
+  registerPiEngine();
+
+  // [P3 引擎接线] 登记 'zcode'（幂等同上）。惰性工厂：不触发 CLI/凭据探测，引擎被
+  // 实际选用（P4 路由或显式 getEngine('zcode')）才解析 deps。
+  registerZcodeEngine();
+
+  // [U7b] 引擎列表在 extension 模块加载时即同步 engines.json（不等 session_start——
+  // 用户体验拍板 2026-08-25：xyz-agent 打开后激活任意 session 的第一时间（含 TUI 等价
+  // 场景）GUI 引擎选择器就该有数据；session_start 处保留幂等重写兜底 jiti 双路径/
+  // 模块重载场景的刷新）。
+  syncEnginesFile(getAgentDir());
+
   // ════════════════════════════════════════════════════════════
   //  subagents 域：tool + command + messageRenderer
   // ════════════════════════════════════════════════════════════
@@ -332,6 +357,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     const sessionId = ctx.sessionManager.getSessionId();
     lsRef.lastSessionId = sessionId;
 
+    // [U7] 引擎列表同步 engines.json（幂等零写 + fail-safe；组合根注册已在
+    // extension 工厂体完成，此处 registry 已含全部引擎）
+    syncEnginesFile(agentDir);
+
     // skill 路径两级缓存 session 级失效：pi 同进程可能有多个 session（TUI /new、/fork），
     // 运行中安装的 skill 需对新 session 可见（含曾 miss 缓存的 undefined 条目与 npm 新装
     // 包的候选目录）。session 内复用收益不变（IF8/DM3 消重发生在同 session 的重复调用）。
@@ -559,6 +588,22 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     });
   });
 
+  // ════════════════════════════════════════════════════════════
+  //  [U7] before_agent_start：引擎模型段注入（defaultEngine 非 pi 且引擎实现
+  //  listModels 时追加 <available_<engine>_models>——每 turn 重判 config，改配置
+  //  后下一 turn 即生效；fail-safe 任何异常不注入不阻塞 agent loop）
+  // ════════════════════════════════════════════════════════════
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
+    try {
+      const service = getModelConfigService();
+      const append = service === null ? "" : buildEngineModelsPromptAppend(service.getGlobalConfig().defaultEngine);
+      if (append === "" || typeof event.systemPrompt !== "string") return undefined;
+      return { systemPrompt: `${event.systemPrompt}\n\n${append}` };
+    } catch {
+      return undefined;
+    }
+  });
+
   // ════════════════════════════════════════════════════════════
   //  model_select：用户切换 model 时刷新缓存
   // ════════════════════════════════════════════════════════════

package/src/interface/command-actions.ts

@@ -8,10 +8,15 @@
  * 设计为纯函数（无 ctx / service 依赖），便于独立单测，handler 只做薄分发。
  */
 
-/** /subagents RPC action 判别联合。 */
+/** /subagents RPC action 判别联合。message/start 为 GUI 定向消息通道（设计 §3.3.3，
+ *  仅 RPC 分支消费；missing-args 携带 missing 字段供 handler 输出指明缺什么的 usage）。 */
 export type SubagentRpcAction =
   | { action: "cancel"; recordId: string }
   | { action: "cancel-missing-id" }
+  | { action: "message"; recordId: string; text: string }
+  | { action: "message-missing-args"; missing: "recordId" | "text" }
+  | { action: "start"; slug: string; task: string }
+  | { action: "start-missing-args"; missing: "slug" | "task" }
   | { action: "noop" };
 
 /** /workflows RPC action 判别联合。 */
@@ -46,25 +51,84 @@ function isRemovedLifecycleVerb(verb: string): verb is "pause" | "resume" {
   return REMOVED_LIFECYCLE_VERBS.has(verb as "pause" | "resume");
 }
 
+/**
+ * 还原转义协议（设计 §3.3.3 / 探针 P3）：字面 `\n`（反斜杠 + n 两字符）→ 真实换行、
+ * 字面 `\\`（两反斜杠）→ 单反斜杠。
+ *
+ * 与 runtime encodeDirectiveText（session-service.ts）互逆：composer 多行输入在
+ * client.prompt 传输前把真实换行编码为字面 \n、原生反斜杠编码为 \\（命令保持单行），
+ * extension 解析侧在此还原。反斜杠转义必须与换行转义在**单次遍历**里成对处理
+ * （交替分支 `\\\\|\\n`，两反斜杠优先匹配）——若只处理 \n，原文里的字面反斜杠+n
+ * （如路径 `C:\new`）会被误解码为换行，往返歧义。
+ */
+function decodeNewlineEscapes(s: string): string {
+  return s.replace(/\\\\|\\n/g, (m) => (m === "\\\\" ? "\\" : "\n"));
+}
+
+/**
+ * 提取首个非空白 token 与其后剩余原文。
+ *
+ * 与 split(/\s+/) 不同：rest 保留 token 之后的全部原文（含空格/引号/换行转义），
+ * 供 message text / start task 的「剩余全量到字符串末尾」语义使用（设计 §3.3.3——
+ * pi 以首个空格拆命令名后 args 为其后全文，文本内的空格/引号必须原样保留）。
+ * rest 跳过 token 后的分隔空白（分隔符不属文本），但保留其后全部内容原样。
+ */
+function splitFirstToken(s: string): { token: string; rest: string } | null {
+  const head = s.trimStart();
+  if (!head) return null;
+  const idx = head.search(/\s/);
+  if (idx === -1) return { token: head, rest: "" };
+  return { token: head.slice(0, idx), rest: head.slice(idx + 1).trimStart() };
+}
+
 /**
  * 解析 /subagents RPC 命令字符串。
  *
  * 支持格式：
  * - `cancel <id>` → { action: "cancel", recordId }
  * - `cancel`（无 id）→ { action: "cancel-missing-id" }
+ * - `message <recordId> <text...>` → { action: "message", recordId, text }
+ *   text 为第二 token 后的剩余全量（含空格/引号原样；字面 \n 还原为换行、字面 \\ 还原为
+ *   反斜杠——composer 定向消息经此协议编码，与 runtime encodeDirectiveText 互逆，设计 §3.3.3）
+ * - `message`（缺 recordId 或 text 为空白）→ { action: "message-missing-args", missing }
+ * - `start <slug> <task...>` → { action: "start", slug, task }（task 同 text 转义协议）
+ * - `start`（缺 slug 或 task 为空白）→ { action: "start-missing-args", missing }
  * - 其他（空 / 未知 action / 无参）→ { action: "noop" }
  *
- * noop 表示 GUI 端无对应程序化操作（GUI 已在 CommandPopover 屏蔽 /subagents 入口，
- * 此分支仅兜底手动 prompt）。
+ * missing-args 携带 missing 字段（缺哪个参数），handler 据此输出可操作的 usage
+ * 错误（全局规则：错误信息指向恢复动作）。noop 表示 GUI 端无对应程序化操作（GUI
+ * 已在 CommandPopover 屏蔽 /subagents 入口，此分支仅兜底手动 prompt）。
  */
 export function parseSubagentRpcCommand(argsStr: string): SubagentRpcAction {
-  const args = argsStr.trim().split(/\s+/).filter(Boolean);
-  if (args.length === 0) return { action: "noop" };
+  const first = splitFirstToken(argsStr);
+  if (!first) return { action: "noop" };
 
-  const [verb, recordId] = args;
+  const { token: verb, rest } = first;
   if (verb === "cancel") {
-    if (!recordId) return { action: "cancel-missing-id" };
-    return { action: "cancel", recordId };
+    const idToken = splitFirstToken(rest);
+    if (!idToken) return { action: "cancel-missing-id" };
+    return { action: "cancel", recordId: idToken.token };
+  }
+  if (verb === "message" || verb === "start") {
+    // message 与 start 共用解析骨架，仅结果字段名不同（recordId/text vs slug/task）
+    const isMessage = verb === "message";
+    // 第二 token：message→recordId / start→slug；其后剩余全量（还原换行转义）为 text/task
+    const second = splitFirstToken(rest);
+    if (!second) {
+      return isMessage
+        ? { action: "message-missing-args", missing: "recordId" }
+        : { action: "start-missing-args", missing: "slug" };
+    }
+    // 先还原再判空：纯字面 \n 还原后是真实换行（whitespace），应在解析层拦截为缺参
+    const payload = decodeNewlineEscapes(second.rest);
+    if (!payload.trim()) {
+      return isMessage
+        ? { action: "message-missing-args", missing: "text" }
+        : { action: "start-missing-args", missing: "task" };
+    }
+    return isMessage
+      ? { action: "message", recordId: second.token, text: payload }
+      : { action: "start", slug: second.token, task: payload };
   }
   return { action: "noop" };
 }

package/src/interface/subagent-actions.ts

@@ -81,6 +81,8 @@ export interface StartHandlerInput {
   conversation?: boolean;
   /** 空闲超时毫秒数（仅 conversation 模式有意义，覆盖默认 5min）。 */
   idleTimeoutMs?: number;
+  /** 执行引擎（D4 三层路由第一层：本参数 > agent frontmatter engine > config defaultEngine）。 */
+  engine?: string;
 }
 
 /** start 领域对象（adapter 包成 bgResponse）。 */
@@ -219,6 +221,7 @@ export async function startHandler(
     cwd: input.cwd,
     conversation: input.conversation,
     idleTimeoutMs: input.idleTimeoutMs,
+    engine: input.engine,
     ctxModel,
     signal,
     // background detached 运行，完成由 notify 驱动新 turn。
@@ -329,10 +332,13 @@ export interface MessageHandlerInput {
   interrupt?: boolean;
 }
 
-/** message 领域对象（adapter 包成 messageResponse）。 */
+/** message 领域对象（adapter 包成 messageResponse）。
+ *  slug 来自 record（GUI /subagents message 通道的留痕 details 需要，设计 §3.3.3），
+ *  避免调用方二次 getRecordForAction 查询。 */
 export type MessageHandlerResult = {
   kind: "message";
   subagentId: string;
+  slug: string;
   response: MessageResponse;
 };
 
@@ -393,7 +399,7 @@ export async function messageHandler(
       `Recovery: use action:'close' to clean up, then action:'start' a new subagent.`,
     );
   }
-  return { kind: "message", subagentId: id, response: { delivered: true } };
+  return { kind: "message", subagentId: id, slug: record.slug, response: { delivered: true } };
 }
 
 // ============================================================

package/src/interface/subagent-tool.ts

@@ -127,6 +127,12 @@ const SubagentParams = Type.Object({
       "Default: 300000 (5min). Override for long-interval collaboration where each round is spaced >5min apart. " +
       "Only meaningful with conversation:true; ignored for one-shot subagents.",
   })),
+  engine: Type.Optional(StringEnum(["pi", "zcode"], {
+    description:
+      "Execution engine for this subagent. Omit to inherit the global config. " +
+      "Three-layer priority: this parameter > agent .md frontmatter engine > config.json defaultEngine. " +
+      "Non-pi engines do not support conversation/fork/worktree (rejected before the subagent is created).",
+  })),
   // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
   listParam: Type.Optional(Type.Object({
     includeFinished: Type.Optional(Type.Boolean({

package/src/interface/subagents.ts

@@ -3,16 +3,211 @@
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
 //
 // 解析：args[0] 直接作可选 <id>（聚焦该 record）。
-// RPC 模式（xyz-agent GUI）：解析 cancel action 直接执行，不打开 TUI。
+// RPC 模式（xyz-agent GUI）：解析 cancel/message/start action 直接执行，不打开 TUI。
+// message/start 为 GUI 定向消息通道（设计 §3.3.3）：GUI 经 client.prompt 短路
+// extension 命令（不经主 agent LLM），TUI 分支不消费这两个 verb（行为零变化）。
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 import { getSubagentService } from "../execution/subagent-service.ts";
+import type { SubagentService } from "../execution/subagent-service.ts";
 import { displayAgentName } from "../shared/agent-ref.ts";
+import { messageHandler, startHandler } from "./subagent-actions.ts";
 import { parseSubagentRpcCommand } from "./command-actions.ts";
+import type { SubagentRpcAction } from "./command-actions.ts";
 import { LIST_LIMIT } from "./list-shared.ts";
 import { createSubagentsView } from "./list-view.ts";
 
+/**
+ * subagent-directive custom_message 的 customType。
+ *
+ * 定向消息留痕载体（设计 §3.3.3）：message/start 成功派发后落主 session 的
+ * custom_message entry，一 entry 双消费——
+ * 1. 主 agent 上下文（custom_message 进 context，主 agent 下次 turn 可见定向对话）
+ * 2. renderer 定向气泡渲染源（§3.3.3a live/reload 双链路，后续 wave 消费）
+ * 字段形状是 GUI 契约，改动需与 renderer 侧同步。
+ */
+export const SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
+
+/** subagent-directive entry 的 details 形状（GUI 定向气泡渲染契约）。 */
+export interface SubagentDirectiveDetails {
+  subagentId: string;
+  slug: string;
+  /** 消息方向：'user' = 用户 → subagent 定向（当前唯一方向，命名预留双向扩展）。 */
+  direction: "user";
+}
+
+/**
+ * 定向消息留痕：向主 session 落 subagent-directive custom_message entry。
+ *
+ * 按主 agent streaming 状态分流 sendMessage options。pi 0.84.1 sendCustomMessage
+ * 实装（agent-session.js）：isStreaming 且无 deliverAs 时默认 agent.steer()——会把
+ * 定向消息注入正在运行的主 agent LLM turn，违反「不经主 agent LLM 直达 subagent」。
+ * 故按调用时刻的权威 streaming 状态（ctx.isIdle()，与 sendCustomMessage 内部
+ * isStreaming 判据精确互补，含 agent_end 后 retry/continuation 窗口）分流：
+ * - streaming（isMainAgentIdle=false）：传 { deliverAs: "nextTurn" }——消息入
+ *   pi 内存 _pendingNextTurnMessages 队列，下个 turn 注入主 agent 上下文；不打断、
+ *   不 steer 当前 turn。注意：该队列不落 entry，留痕延迟到下个 turn
+ * - 非 streaming（isMainAgentIdle=true）：不传 options——立即 append entry 留痕
+ *   + message_start/end 双发（renderer live 链路即时可见，现状行为）
+ * 两者都不传 triggerTurn——不产生新 turn（§3.3.8「留痕 ≠ 处理」的结构性保证）；
+ * display:false 使 pi TUI 不渲染该 entry（GUI 侧由 §3.3.3a 定向气泡通路渲染）。
+ */
+function emitSubagentDirective(
+  pi: Pick<ExtensionAPI, "sendMessage">,
+  details: SubagentDirectiveDetails,
+  text: string,
+  isMainAgentIdle: boolean,
+): void {
+  pi.sendMessage(
+    {
+      customType: SUBAGENT_DIRECTIVE_CUSTOM_TYPE,
+      content: text,
+      display: false,
+      details,
+    },
+    isMainAgentIdle ? undefined : { deliverAs: "nextTurn" },
+  );
+}
+
+/** RPC cancel 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcCancel(
+  service: SubagentService,
+  recordId: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  try {
+    const ok = service.cancel(recordId);
+    ctx.ui.notify(
+      ok ? `Cancelled subagent ${recordId}` : `Subagent ${recordId} not found or already finished`,
+      ok ? "info" : "warning",
+    );
+  } catch (err) {
+    // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to cancel subagent ${recordId}: ${msg}`, "warning");
+  }
+}
+
+/** RPC message 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcMessage(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  recordId: string,
+  text: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  // GUI 定向消息（设计 §3.3.3）：不经主 agent LLM 直达 subagent。
+  // one-shot 首条 message 自动升级 chatMode 的机制在 messageHandler 内（勿在此重复）。
+  try {
+    const result = await messageHandler(service, {
+      subagentId: recordId,
+      text,
+    });
+    // 留痕（§3.3.3）：成功派发后才留痕——失败时不留痕，GUI 按 toast 错误重发。
+    // ctx.isIdle() 按调用时刻分流（streaming → nextTurn 队列延迟留痕，见
+    // emitSubagentDirective JSDoc），保证任何时刻都不 steer 主 agent 当前 turn
+    emitSubagentDirective(
+      pi,
+      { subagentId: result.subagentId, slug: result.slug, direction: "user" },
+      text,
+      ctx.isIdle(),
+    );
+    ctx.ui.notify(`Message delivered to subagent ${result.slug} (${result.subagentId})`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to message subagent ${recordId}: ${msg}`, "warning");
+  }
+}
+
+/** RPC start 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcStart(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  slug: string,
+  task: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  // GUI 定向新建（设计 §3.3.3）：conversation 固定 true（GUI 定向对话场景需要可续聊）
+  try {
+    const result = await startHandler(
+      service,
+      {
+        slug,
+        task,
+        conversation: true,
+      },
+      // RPC 命令无外层 AbortSignal（GUI 请求生命周期不映射到 subagent 取消——
+      // start 是 detached 后台语义，取消走 /subagents cancel）
+      undefined,
+    );
+    emitSubagentDirective(
+      pi,
+      { subagentId: result.subagentId, slug: result.slug, direction: "user" },
+      task,
+      ctx.isIdle(),
+    );
+    ctx.ui.notify(`Started subagent ${result.slug} (${result.subagentId})`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to start subagent ${slug}: ${msg}`, "warning");
+  }
+}
+
+/**
+ * RPC 模式（xyz-agent GUI）：解析后的 action 分发执行，不打开 TUI。
+ * 行为等价拆分自 handler（fallow 圈复杂度 21 > 15）：三个执行体
+ * （cancel/message/start）各自成函数，本函数只做 switch 分发 +
+ * usage notify + exhaustiveness 断言。
+ */
+async function executeRpcAction(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  parsed: SubagentRpcAction,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  switch (parsed.action) {
+    case "cancel":
+      await rpcCancel(service, parsed.recordId, ctx);
+      return;
+    case "cancel-missing-id":
+      ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
+      return;
+    case "message":
+      await rpcMessage(pi, service, parsed.recordId, parsed.text, ctx);
+      return;
+    case "message-missing-args":
+      // 错误可操作：指明缺什么 + 完整 usage（全局规则 16）
+      ctx.ui.notify(
+        parsed.missing === "recordId"
+          ? "Usage: /subagents message <recordId> <text> — recordId is missing"
+          : "Usage: /subagents message <recordId> <text> — text is missing",
+        "warning",
+      );
+      return;
+    case "start":
+      await rpcStart(pi, service, parsed.slug, parsed.task, ctx);
+      return;
+    case "start-missing-args":
+      ctx.ui.notify(
+        parsed.missing === "slug"
+          ? "Usage: /subagents start <slug> <task> — slug is missing"
+          : "Usage: /subagents start <slug> <task> — task is missing",
+        "warning",
+      );
+      return;
+    case "noop":
+      // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+      ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
+      return;
+    default: {
+      // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
+      const _exhaustive: never = parsed;
+      throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
+    }
+  }
+}
+
 /** 注册 /subagents 命令（= list overlay）。 */
 export function registerSubagentsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("subagents", {
@@ -59,35 +254,8 @@ export function registerSubagentsCommand(pi: ExtensionAPI): void {
       // ── RPC 模式（xyz-agent GUI）：解析 action 直接执行，不打开 TUI ──
       // hasUI 在 TUI 和 RPC 都为 true，不能用于区分；用 ctx.mode === "rpc" 判定 GUI 通道。
       if (ctx.mode === "rpc") {
-        const parsed = parseSubagentRpcCommand(argsStr);
-        switch (parsed.action) {
-          case "cancel": {
-            try {
-              const ok = service.cancel(parsed.recordId);
-              ctx.ui.notify(
-                ok ? `Cancelled subagent ${parsed.recordId}` : `Subagent ${parsed.recordId} not found or already finished`,
-                ok ? "info" : "warning",
-              );
-            } catch (err) {
-              // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
-              const msg = err instanceof Error ? err.message : String(err);
-              ctx.ui.notify(`Failed to cancel subagent ${parsed.recordId}: ${msg}`, "warning");
-            }
-            return;
-          }
-          case "cancel-missing-id":
-            ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
-            return;
-          case "noop":
-            // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
-            ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
-            return;
-          default: {
-            // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
-            const _exhaustive: never = parsed;
-            throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
-          }
-        }
+        await executeRpcAction(pi, service, parseSubagentRpcCommand(argsStr), ctx);
+        return;
       }
 
       // ── print/json 模式（headless）：不可交互 ──

package/src/orchestration/__tests__/__fixtures__/worker-template.snapshot.txt

@@ -12,7 +12,7 @@ const { parentPort: _parentPort, workerData: _workerData } = require("node:worke
 const _workerLogs = [];
 // IF6(#12): known agent() fields — hoisted to module scope, built once per worker
 // (was rebuilt inside agent() on every call; field set is call-invariant).
-const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);
+const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);
 function _pushWorkerLog(level, args) {
   try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }
 }
@@ -153,6 +153,8 @@ function _safePost(msg, context) {
         scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,
         phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,
         thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || $THINKING_LEVEL,
+        // P4 D9③：step 级 engine 显式指定（仅限必须某引擎独有能力的场景）
+        engine: (secondArg && typeof secondArg === "object" && secondArg.engine) || undefined,
       };
     } else if (typeof firstArg === "object" && firstArg !== null) {
       if (firstArg.prompt) {
@@ -174,6 +176,7 @@ function _safePost(msg, context) {
           worktree: firstArg.worktree,
           returnMeta: firstArg.returnMeta,
           thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL,
+          engine: firstArg.engine,
         };
       } else {
         opts = firstArg;
@@ -190,7 +193,7 @@ function _safePost(msg, context) {
     // Validate known agent() fields to catch API misuse early (_KNOWN_FIELDS at module scope)
     const _unknownFields = Object.keys(opts).filter((k) => !_KNOWN_FIELDS.has(k));
     if (_unknownFields.length > 0) {
-      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);
+      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel, engine"]);
     }
 
     const callId = _callIdCounter;

package/src/orchestration/__tests__/worker-script-template-snapshot.test.ts

@@ -100,11 +100,11 @@ describe("buildWorkerScript — _KNOWN_FIELDS module scope 提升（IF6）", ()
     expect(agentBody).toContain("_KNOWN_FIELDS.has(k)");
   });
 
-  it("字段集合内容逐字段一致（16 known fields 不丢失）", () => {
+  it("字段集合内容逐字段一致（17 known fields 不丢失——P4 增 engine）", () => {
     expect(script).toContain(
-      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
+      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);',
     );
     // unknown-fields 警告文案不变（known 列表仍全量）
-    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel/);
+    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel.*engine/);
   });
 });

package/src/orchestration/models/types.ts

@@ -143,6 +143,13 @@ export interface AgentCallOpts {
   cwd?: string;
   /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
   fork?: boolean;
+  /**
+   * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
+   * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
+   * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
+   * agent() → execute-agent-call → SAR 路由层。
+   */
+  engine?: string;
   /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
   worktree?: boolean;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.