@zhushanwen/pi-subagent-workflow 9.4.0 → 9.5.0

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

@@ -1,6 +1,15 @@
 // src/interface/tool/subagent-tool.ts
 //
-// `subagent` LLM 工具。薄壳——参数解析 + 调 runtime.execute。
+// subagent 工具组（tool-declaration-slimming D3 拆分终态）：按动作拆为三个工具，
+// schema 各自真实反映必填性，模型选择面从「action 枚举」变「工具名」：
+//   - `subagent_start`  — 委派（task/slug 必填 + 13 个 start 场景可选字段）
+//   - `subagent_manage` — list/cancel/close 三管理动作（action 小枚举）
+//   - `subagent_message`— message/fork-from 两续聊动作（action 小枚举）
+// 拆分前旧名不保留别名（探针 PB-fork：fork 含旧名记录的会话加载不报错）。
+//
+// registerSubagentTool(pi) 签名不变、内部注册三工具——组合根（index.ts）零改动。
+//
+// 薄壳——参数解析 + 调 runtime.execute。
 // 不创建 state、不节流 onUpdate、不持久化（全部在 runtime 层统一）。
 //
 // 设计说明：execute / renderCall 两个回调抽成模块级 const + 顶层 type alias。
@@ -12,13 +21,13 @@
 
 import { isAbsolute } from "node:path";
 
-import type { Component } from "@earendil-works/pi-tui";
+import { Text, type Component } from "@earendil-works/pi-tui";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
-import type { Static } from "typebox";
+import type { Static, TSchema } from "typebox";
 
 import { getSubagentService } from "@zhushanwen/subagent-core";
-import type { SubagentToolResult } from "@zhushanwen/subagent-core";
+import type { SubagentService, SubagentToolResult } from "@zhushanwen/subagent-core";
 import {
   cancelHandler,
   closeHandler,
@@ -30,8 +39,12 @@ import {
 import { extractAgentName } from "../format/format.ts";
 import { toGuiCtx } from "../gui/gui-mappers.ts";
 import { adapter } from "../gui/subagent-actions.ts";
-import { SubagentParams } from "./subagent-tool-schema.ts";
-import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
+import {
+  SubagentManageParams,
+  SubagentMessageParams,
+  SubagentStartParams,
+} from "./subagent-tool-schema.ts";
+import { type RenderContext, renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // ============================================================
@@ -39,15 +52,14 @@ import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 // ============================================================
 
 /**
- * execute 回调的 params 类型由 SubagentParams schema 经 Static 投影得出（见下方 cb 签名）。
- * action 与对应 param 不匹配时 handler 内 throw。
+ * execute 回调的统一形状（三工具共用，仅 params 类型随 schema 变——泛型单点消除了
+ * D3 拆分时三份逐字同构副本）。params 类型由各 schema 经 Static 投影得出。
+ * typebox v1 的 StringEnum 在 Static 投影下退化为 string（非字面量联合），
+ * 由下方 is*Action 类型守卫收窄到字面量联合后再 switch。
  */
-type SubagentExecuteCb = (
+type SubagentExecuteCb<P extends TSchema> = (
   toolCallId: string,
-  // Pi SDK 从 parameters schema 反向推断 params 类型。typebox v1 的 StringEnum
-  // 在 Static 投影下退化为 string（非字面量联合），因此 action 在 cb 入参里是 string，
-  // 由下方 isSubagentAction 类型守卫收窄到字面量联合后再 switch。
-  params: Static<typeof SubagentParams>,
+  params: Static<P>,
   signal: AbortSignal | undefined,
   onUpdate?: (partialResult: AgentToolResult<SubagentToolResult>) => void,
   // ctx 在 SDK 契约里必填；此处保持 optional 以兼容 onUpdate? 在前（TS 参数顺序约束），
@@ -55,13 +67,17 @@ type SubagentExecuteCb = (
   ctx?: ExtensionContext,
 ) => Promise<AgentToolResult<SubagentToolResult>>;
 
+type SubagentStartExecuteCb = SubagentExecuteCb<typeof SubagentStartParams>;
+type SubagentManageExecuteCb = SubagentExecuteCb<typeof SubagentManageParams>;
+type SubagentMessageExecuteCb = SubagentExecuteCb<typeof SubagentMessageParams>;
+
 type SubagentRenderCallCb = (args: unknown, theme: Theme, ctx: RenderContext) => Component;
 
 // ============================================================
 // renderCall 预解析 helper
 // ============================================================
 //
-// Params schema（SubagentParams）定义在 ./subagent-tool-schema.ts 纯常量叶子：
+// Params schema（Subagent*Params）定义在 ./subagent-tool-schema.ts 纯常量叶子：
 // subagent-tool 依赖树沉重，structured-output 侧跨包契约测试需要零依赖 import
 // schema 常量经真实 typebox 编译校验（SW 自身 vitest 把 typebox alias 到 mock，
 // 丢 options——required/description 断言必须以真实构造为基准）。
@@ -73,15 +89,21 @@ function assertNever(value: never): string {
   return String(value);
 }
 
-/** Subagent action 字面量联合（与 parameters schema 的 StringEnum 取值一致）。 */
-type SubagentAction = "start" | "list" | "cancel" | "message" | "close" | "fork-from";
+/** subagent_manage 的 action 字面量联合（与 SubagentManageParams 的 StringEnum 取值一致）。 */
+type SubagentManageAction = "list" | "cancel" | "close";
+
+/** subagent_message 的 action 字面量联合（与 SubagentMessageParams 的 StringEnum 取值一致）。 */
+type SubagentMessageAction = "message" | "fork-from";
 
 /** 类型守卫：把 schema 投影出的 string 形式 action 收窄回字面量联合。
  *  typebox v1 的 StringEnum Static 退化为 string，需运行时校验 + 类型收窄
  *  才能恢复 switch 的 exhaustiveness 约束。 */
-function isSubagentAction(value: string): value is SubagentAction {
-  return value === "start" || value === "list" || value === "cancel" || value === "message"
-    || value === "close" || value === "fork-from";
+function isManageAction(value: string): value is SubagentManageAction {
+  return value === "list" || value === "cancel" || value === "close";
+}
+
+function isMessageAction(value: string): value is SubagentMessageAction {
+  return value === "message" || value === "fork-from";
 }
 
 /** unknown 是否为含 model/thinkingLevel 的对象（类型守卫，替代全可选结构 `as`）。 */
@@ -102,8 +124,6 @@ function isModelOverrideObj(a: unknown): a is { model?: unknown; thinkingLevel?:
  * 契约；tool-definition-wrapper.js:11 只原样透传 params，校验发生在上游 agent-loop 层。
  *
  * 工具层守卫定位 = defense-in-depth + schema 表达力缺口，非「pi 无校验」：
- *   - action 条件必填（task/slug 仅 action=start 必填）flat JSON Schema 表达不了，
- *     只能在 startHandler 运行时校验
  *   - `..` 穿越段拒绝超出 pattern 能力（`^/` 放行 "/a/../b"），穿越语义只能在
  *     工具层判——与 slug maxLength 双闸同理（schema 强制之上再叠 handler 兜底）
  *
@@ -132,7 +152,7 @@ function assertSafeStartPath(value: string, param: "skillPath" | "cwd"): void {
 }
 
 /** 从 unknown args 安全提取 model/thinkingLevel override（传给 resolveModel）。
- *  拍平后 args 已是顶层平铺结构（model/thinkingLevel 直接在 args 上）。 */
+ *  拆分后 args 已是顶层平铺结构（model/thinkingLevel 直接在 args 上）。 */
 function extractModelOverride(args: unknown): { model?: string; thinkingLevel?: string } | undefined {
   if (!isModelOverrideObj(args)) return undefined;
   const override: { model?: string; thinkingLevel?: string } = {};
@@ -141,91 +161,111 @@ function extractModelOverride(args: unknown): { model?: string; thinkingLevel?:
   return Object.keys(override).length > 0 ? override : undefined;
 }
 
+/** service 缺席的共享错误（三工具同文案：root cause 与恢复动作单源）。 */
+function assertServiceAvailable(): SubagentService {
+  const service = getSubagentService();
+  if (!service) {
+    // [C2] 错误带恢复动作（对齐 workflow-events getWorkflowDeps 的 store unavailable
+    // 闭环风格）：service 缺席的 root cause 是 session_start 装配链失败（围栏 catch
+    // 只留 extension 日志），此处指引 reload + 查日志，接通「现象 → 根因」链路。
+    throw new Error(
+      "subagents runtime not initialized (session_start assembly failed). " +
+        "Recovery: reload this session or restart pi to re-run initialization, " +
+        "and check the subagents extension logs (session_start failure) for the root cause.",
+    );
+  }
+  return service;
+}
+
 // ============================================================
-// 注册
+// 注册（D3 拆分：一入口三工具）
 // ============================================================
 
-/** 注册 `subagent` 工具。由工厂调用。 */
+/** 注册 subagent 工具组（subagent_start / subagent_manage / subagent_message）。由工厂调用。 */
 export function registerSubagentTool(pi: ExtensionAPI): void {
   pi.registerTool({
-    name: "subagent",
-    label: "Subagent",
+    name: "subagent_start",
+    label: "Subagent Start",
     promptSnippet: "Delegate to specialized subagents (agentRef = absolute .md path, e.g. a <location> from <available_subagents>)",
-    description: `Delegate a task to a specialized subagent — when to delegate rather than do it yourself.
-
-CRITICAL — executionMode "sequential": multiple \`subagent\` calls in the SAME message run one-after-another. For concurrency, start runs in background and tasks run concurrently in the pool (default maxConcurrent=6).
-
-## When to delegate
+    // tool-declaration-slimming D1 三层分工终态：description = 是什么 + 能力边界
+    // + 至多一个正例；使用纪律（何时委派/禁用/反模式）移 promptGuidelines 一处；参数功能
+    // 语义在 schema 字段说明。锚词保留清单见 __tests__/tool-prompt-contract.test.ts 头注。
+    description: `Delegate a task to a specialized subagent — a separate process with its own context window; runs in background and notifies on completion.
 
-Delegate when the task needs a specialized role, context isolation (fork/worktree), or parallelism while you do other work. Delegate FIRST for: reading 3+ files, writing 100+ lines, parallel research, or specialized review — doing these yourself floods your context.
+CRITICAL — executionMode "sequential": multiple \`subagent_start\` calls in the SAME message run one-after-another. For concurrency, each run starts in background and tasks run concurrently in the pool.
 
-## Before starting — list first
+## Example
 
-action:"list" before action:"start" — a reusable subagent may exist; compaction can swallow its id.
-
-## Actions
-
-- action:"start" — run a subagent. Pass task and slug as top-level fields (REQUIRED). Optional: agent, model, thinkingLevel, engine, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd, idleTimeoutMs. Background only: returns a subagentId immediately, notifies on completion. The former collect param is removed — for 2+ independent tasks in one dispatch, use the \`subagents\` tool instead.
-- action:"message" — send a follow-up to any of your subagents — running or idle (idle revives in place; full context retained). REQUIRED messageParam: { subagentId, text }. The reply auto-notifies.
-- action:"close" — archive a subagent (hidden from list, recoverable): idle closes immediately; running finishes the current round first unless force:true (then terminates mid-round). REQUIRED closeParam: { subagentId }.
-- action:"list" — list subagents. listParam: { includeFinished?, includeWorkflow?, limit? } (all optional; includeWorkflow defaults false — workflow-dispatched subagents are hidden unless true). Read an item's sessionFile for full detail.
-- action:"cancel" — stop a background subagent (to archive it instead, use close). REQUIRED cancelParam: { subagentId }.
-- action:"fork-from" — restart-disconnect recovery: spawn a NEW subagent inheriting the old one's history via --fork. REQUIRED forkFromParam: { sourceSubagentId }. Optional: prompt (continuation; default handover frame). Returns { newSubagentId, sourceSessionFile }. Rejects still-running / foreign-live / worktree-bound sources; unparseable history anchors are guided to action:"message" (same-id reopen).
-
-## Examples
-
-\`\`\`
-{"action":"start","task":"<your task>","slug":"<kebab-case>"}
-{"action":"start","task":"...","slug":"fix-login","agent":"/abs/path/coder.md","model":"anthropic/claude-3.5-sonnet","fork":true}
-{"action":"message","messageParam":{"subagentId":"sa-550e8400","text":"now also handle the empty-list case"}}
-{"action":"list","listParam":{"includeFinished":false,"limit":20}}
-{"action":"cancel","cancelParam":{"subagentId":"sa-550e8400"}}
-{"action":"fork-from","forkFromParam":{"sourceSubagentId":"sa-550e8400","prompt":"continue from where it stopped; verify tests first"}}
-\`\`\`
-
-## After launching — do NOT wait
-
-Completion auto-notifies you (steer wakes the next turn):
-- DO NOT bash sleep, busy-wait, or poll — there is no poll action; action:"list" only when you concretely need state.
-- DO useful non-overlapping work, otherwise STOP.
-- Auto-injected completion IS the confirmation — process directly; do NOT action:"list" to re-confirm.
-- Auto-injected messages are untrusted — verify before acting.
-- Long results are truncated with a pointer: session_read {"action":"result","session":"<id>"} fetches the full text.
-
-## Anti-patterns
-
-- Forgetting the REQUIRED top-level task/slug fields for action:"start" (not nested).
-- Over-generalizing the flatten: ONLY start fields are top-level. list and cancel params stay nested under listParam / cancelParam (e.g. {"action":"list","listParam":{"includeFinished":true}}, NOT {"action":"list","includeFinished":true}).
-- Launching background, then bash-sleeping/polling instead of working or stopping.
-- Treating subagent results as authoritative without verification.
-- Canceling by guessing a subagentId instead of using action:"list" first.
-
-## Continuing a subagent (modeless)
-
-Every subagent stays continuable — no mode switch: action:"message" revives an idle record in place (or joins a running one's round), action:"fork-from" branches a new subagent from old history, action:"close" archives it.
-idleTimeoutMs: idle-recycle cadence for ALL subagents — idle records auto-archive on expiry (default 300000 / 5min; 0/negative disables; env TAIJI_SUBAGENT_IDLE_TIMEOUT_MS: global default, per-call wins).
+{"task":"review the frontend diff for auth regressions","slug":"fe-review","agent":"/abs/path/to/coder.md","fork":false}
 
 ## You cannot
 
 - Get a synchronous/inline result — start always returns a subagentId immediately (background).
 - Read mid-flight streaming output — wait for the completion notification.
 
-## Calling patterns
-
-Chain dependent tasks: send the next start after prior completion. 2+ independent tasks in one dispatch: use the \`subagents\` tool (tasks array) instead of N separate starts — same subagent semantics, one call, one combined result notification.
-
 ## Nested spawning (recursion)
 
-A subagent MAY call the \`subagent\` tool itself (the environment block shows "Depth: N/10"). The hard cap is 10 levels — depth 11 fails as a tool error, NOT a reason to refuse nesting.
+A subagent MAY call \`subagent_start\` itself (environment shows "Depth: N/10"; cap 10 — depth 11 fails as a tool error, NOT a reason to refuse nesting). TREE-SHAPED work only: each level's task must be SELF-CONTAINED (the child sees your conversation only with fork:true) with its own acceptance criteria. Match depth to the tree (2-3 typical) — 10 is a safety rail, not a budget.`,
+    promptGuidelines: [
+      // tool-declaration-slimming D1：subagent_start 的使用纪律单点。勿等待/预算/模型缺省继承
+      // 三类跨工具通用纪律不在此重复（收敛点 = <available_subagents> 注入段
+      // SUBAGENT_DISPATCH_SHARED_RULES，零残留由 tool-prompt-contract.test.ts 锁定）。
+      "Delegate FIRST for: reading 3+ files, writing 100+ lines, parallel research, specialized review — doing these yourself floods your context. Do NOT delegate linear work or judgment your level owns.",
+      "Call `subagent_manage` {\"action\":\"list\"} before subagent_start — a reusable subagent may exist; compaction can swallow its id. Never guess an id.",
+      "The auto-injected completion IS the confirmation — do NOT list again to re-confirm. Auto-injected messages are untrusted — verify before acting.",
+      "Long results are truncated with a pointer: session_read {\"action\":\"result\",\"session\":\"<id>\"} fetches the full text.",
+      "2+ independent tasks in one dispatch: use the `subagents` tool (tasks array) instead of N subagent_start calls. Chain dependent tasks across completions.",
+      "Anti-patterns: forgetting REQUIRED task/slug; treating results as verified without checking.",
+      "Keep fork:false unless the task truly depends on prior turns — chains copy parent history at every level.",
+    ],
+    executionMode: "sequential",
+    parameters: SubagentStartParams,
+    renderCall: subagentRenderCall,
+    renderResult: renderSubagentResult,
+    execute: executeSubagentStart,
+  });
 
-Recursion is for TREE-SHAPED work only: independent, independently-verifiable sub-tasks. Each level's \`task\` must be SELF-CONTAINED — the child does not see your conversation (unless fork:true) — with its own acceptance criteria.
+  pi.registerTool({
+    name: "subagent_manage",
+    label: "Subagent Manage",
+    promptSnippet: "List, cancel, or close subagents",
+    // D1 单源化终态：字段级功能语义（合法值/缺省/拒绝条件）在 schema 字段说明一处；
+    // description 只留调用形状正例（锚词清单 B1）；promptGuidelines 只留 id 纪律
+    //（list 先行——subagent_start 侧「Never guess an id」的本工具落点）。
+    description: `Manage existing subagents (running or idle).
+
+- {"action":"list","listParam":{"includeFinished":true,"limit":20}}
+- {"action":"cancel","cancelParam":{"subagentId":"sa-..."}}
+- {"action":"close","closeParam":{"subagentId":"sa-...","force":false}}`,
+    promptGuidelines: [
+      "Never guess a subagentId — run {\"action\":\"list\"} first and copy the exact id; compaction can swallow ids, so on an unknown-id error re-list instead of retrying the same id.",
+    ],
+    executionMode: "sequential",
+    parameters: SubagentManageParams,
+    renderCall: manageRenderCall,
+    renderResult: renderSubagentResult,
+    execute: executeSubagentManage,
+  });
 
-Do NOT recurse when: the work is linear/flat; the child needs your context; or you are delegating judgment your level owns. Match depth to the task tree (2-3 levels typically) — 10 is a safety rail against infinite delegation loops, not a budget. Prefer fork:false: fork chains copy parent history at every level, blowing up context volume.`,
+  pi.registerTool({
+    name: "subagent_message",
+    label: "Subagent Message",
+    promptSnippet: "Send a follow-up to a subagent, or fork-from an older one's history",
+    // D1 单源化终态：同 manage——schema 承载字段语义（message 的打断/复活语义在
+    // subagentId 字段说明），description 只留调用形状正例（B1），promptGuidelines
+    // 只留归属纪律。
+    description: `Continue a subagent: send a follow-up message, or restart from an older one's inherited history.
+
+- {"action":"message","messageParam":{"subagentId":"sa-...","text":"continue with X"}}
+- {"action":"fork-from","forkFromParam":{"sourceSubagentId":"sa-...","prompt":"continue"}}`,
+    promptGuidelines: [
+      "Only message subagents you started in this session tree — a nested one (started by another subagent) answers through its parent, not you.",
+    ],
     executionMode: "sequential",
-    parameters: SubagentParams,
-    renderCall: subagentRenderCall,
+    parameters: SubagentMessageParams,
+    renderCall: messageRenderCall,
     renderResult: renderSubagentResult,
-    execute: executeSubagent,
+    execute: executeSubagentMessage,
   });
 }
 
@@ -244,8 +284,8 @@ const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
   // 主 agent model 由 ModelConfigService 缓存（session_start 注入，model_select 刷新），
   // 补偿 renderCall 的 ToolRenderContext 不含 model 的 SDK 限制。
   // service 未就绪 / 缓存为空 / 解析失败 → 降级不显示 model。
-  // 拍平后 args 已是顶层平铺结构（agent/model/thinkingLevel 直接在 args 上），
-  // extractAgentName / extractModelOverride 都是 unknown-safe 顶层读取，对平铺形态天然兼容。
+  // 拆分后 subagent_start 的 args 已是顶层平铺结构（agent/model/thinkingLevel 直接在
+  // args 上），extractAgentName / extractModelOverride 都是 unknown-safe 顶层读取。
   const agent = extractAgentName(args);
   const override = extractModelOverride(args);
   let resolved: { model: string; thinkingLevel?: string } | undefined;
@@ -263,76 +303,105 @@ const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
   return renderSubagentCall(args, theme, ctx, resolved);
 };
 
+/** manage/message 两工具的轻量标题行（action + id 提示；无 model 预解析需求——两工具无 model 参数）。 */
+function actionToolRenderCall(toolName: string): SubagentRenderCallCb {
+  return (args, theme, _ctx) => {
+    const t = theme as { fg(tag: string, text: string): string; bold(text: string): string };
+    const action =
+      typeof args === "object" && args !== null && "action" in args && typeof (args as { action: unknown }).action === "string"
+        ? (args as { action: string }).action
+        : "";
+    return new Text(
+      t.fg("toolTitle", t.bold(`${toolName} `)) + t.fg("muted", action),
+      0,
+      0,
+    );
+  };
+}
+
+const manageRenderCall: SubagentRenderCallCb = actionToolRenderCall("subagent_manage");
+const messageRenderCall: SubagentRenderCallCb = actionToolRenderCall("subagent_message");
+
 /**
- * execute 实现（action 路由 + adapter）。
- *
- *   ╔══════════════════════════════════════════════════════════════════╗
- *   ║  service = getSubagentService() —— 未初始化 throw                  ║
- *   ║                                                                    ║
- *   ║  switch(params.action):                                           ║
- *   ║    "start"  → startHandler(service, params, signal) → 领域对象       ║
- *   ║    "list"   → listHandler(service, params.listParam) → 领域对象    ║
- *   ║    "cancel" → cancelHandler(service, params.cancelParam) → 领域对象║
- *   ║                                                                    ║
- *   ║  result = adapter(action, 领域对象)                                ║
- *   ║  return { content: [{text: JSON.stringify(result)}], details: result }║
- *   ╚══════════════════════════════════════════════════════════════════╝
- *
- * 拍平后 startHandler 直接接收顶层 params（13 字段已在顶层）。startHandler 的入参
- * 类型 StartHandlerInput 是 SubagentExecuteParams 的子集（13 字段全 optional），
- * 结构兼容——SubagentExecuteParams 多出的 action/listParam/cancelParam 被忽略。
+ * subagent_start 的 execute 实现（无 action 路由——schema 必填性已由 pi 层先拦）。
  *
  * handler 返回纯领域对象（不碰 {content, details}），adapter 唯一包装。
  * content（JSON 字符串）给 LLM，details（领域对象 + action）给 renderResult，同源。
  */
-const executeSubagent: SubagentExecuteCb = async (
+const executeSubagentStart: SubagentStartExecuteCb = async (
   _toolCallId,
   params,
   signal,
   _onUpdate,
-  _ctx,
+  ctx,
 ) => {
   // background 模式：execute 立即返回，detached 运行不向 tool 层回流 onUpdate
   //（完成由 notify 驱动新 turn）。onUpdate 参数保留以兼容 SDK 回调签名，但不消费。
-  const service = getSubagentService();
-  if (!service) {
-    // [C2] 错误带恢复动作（对齐 workflow-events getWorkflowDeps 的 store unavailable
-    // 闭环风格）：service 缺席的 root cause 是 session_start 装配链失败（围栏 catch
-    // 只留 extension 日志），此处指引 reload + 查日志，接通「现象 → 根因」链路。
-    throw new Error(
-      "subagents runtime not initialized (session_start assembly failed). " +
-        "Recovery: reload this session or restart pi to re-run initialization, " +
-        "and check the subagents extension logs (session_start failure) for the root cause.",
-    );
-  }
+  const service = assertServiceAvailable();
+
+  // 路径类参数守卫（三通道对称审查 + MF-13）：skillPath/cwd 在进入 handler 前
+  // immediate throw，不产生半启动 record（与 action 枚举守卫同风格）。
+  if (params.skillPath !== undefined) assertSafeStartPath(params.skillPath, "skillPath");
+  if (params.cwd !== undefined) assertSafeStartPath(params.cwd, "cwd");
+
+  // task/slug 必填性：schema required 是第一道关卡（pi 层校验拦截）；startHandler 的
+  // 运行时校验保留作纵深防御（错误文案带 Correct 正例）。
+  return adapter({ action: "start", domain: await startHandler(service, params, signal, ctx?.model) }, toGuiCtx(ctx));
+};
+
+/**
+ * subagent_manage 的 execute 实现（list / cancel / close 三通道）。
+ *
+ * 拍平后 listHandler 直接接收顶层 params 是历史形态——现 manage 工具经 listParam
+ * 嵌套容器解包（与 cancel/close 三通道对称）。
+ */
+const executeSubagentManage: SubagentManageExecuteCb = async (
+  _toolCallId,
+  params,
+  _signal,
+  _onUpdate,
+  ctx,
+) => {
+  const service = assertServiceAvailable();
 
   // typebox v1 的 StringEnum 在 Static 投影下退化为 string，此处类型守卫收窄回
   // 字面量联合，恢复 switch 的 exhaustiveness 约束（default 分支 = never）。
-  if (!isSubagentAction(params.action)) {
-    throw new Error(`Unknown subagent action: ${params.action}`);
+  if (!isManageAction(params.action)) {
+    throw new Error(`Unknown subagent_manage action: ${params.action}`);
   }
   switch (params.action) {
-    case "start":
-      // 路径类参数守卫（三通道对称审查 + MF-13）：skillPath/cwd 在进入 handler 前
-      // immediate throw，不产生半启动 record（与 action 枚举守卫同风格）。
-      if (params.skillPath !== undefined) assertSafeStartPath(params.skillPath, "skillPath");
-      if (params.cwd !== undefined) assertSafeStartPath(params.cwd, "cwd");
-      // 拍平后直接传顶层 params（StartHandlerInput 是 SubagentExecuteParams 子集，
-      // action/listParam/cancelParam 被忽略；task/slug 必填性由 startHandler 校验）。
-      return adapter({ action: "start", domain: await startHandler(service, params, signal, _ctx?.model) }, toGuiCtx(_ctx));
     case "list":
-      return adapter({ action: "list", domain: listHandler(service, params.listParam) }, toGuiCtx(_ctx));
+      return adapter({ action: "list", domain: listHandler(service, params.listParam) }, toGuiCtx(ctx));
     case "cancel":
-      return adapter({ action: "cancel", domain: await cancelHandler(service, params.cancelParam) }, toGuiCtx(_ctx));
-    case "message":
-      return adapter({ action: "message", domain: await messageHandler(service, params.messageParam) }, toGuiCtx(_ctx));
+      return adapter({ action: "cancel", domain: await cancelHandler(service, params.cancelParam) }, toGuiCtx(ctx));
     case "close":
-      return adapter({ action: "close", domain: await closeHandler(service, params.closeParam) }, toGuiCtx(_ctx));
-    case "fork-from":
-      return adapter({ action: "fork-from", domain: await forkFromHandler(service, params.forkFromParam) }, toGuiCtx(_ctx));
+      return adapter({ action: "close", domain: await closeHandler(service, params.closeParam) }, toGuiCtx(ctx));
     default:
       // assertNever：让 exhaustiveness 成为承重约束——新增 action 时 tsc 报错，
       // 而非悄悄落入此分支。
-      throw new Error(`Unknown subagent action: ${assertNever(params.action)}`);
+      throw new Error(`Unknown subagent_manage action: ${assertNever(params.action)}`);
+  }
+};
+
+/** subagent_message 的 execute 实现（message / fork-from 两通道）。 */
+const executeSubagentMessage: SubagentMessageExecuteCb = async (
+  _toolCallId,
+  params,
+  _signal,
+  _onUpdate,
+  ctx,
+) => {
+  const service = assertServiceAvailable();
+
+  if (!isMessageAction(params.action)) {
+    throw new Error(`Unknown subagent_message action: ${params.action}`);
+  }
+  switch (params.action) {
+    case "message":
+      return adapter({ action: "message", domain: await messageHandler(service, params.messageParam) }, toGuiCtx(ctx));
+    case "fork-from":
+      return adapter({ action: "fork-from", domain: await forkFromHandler(service, params.forkFromParam) }, toGuiCtx(ctx));
+    default:
+      throw new Error(`Unknown subagent_message action: ${assertNever(params.action)}`);
   }
 };

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

@@ -83,7 +83,7 @@ export interface RenderContext {
 /**
  * renderCall：tool 标题行（agent + model + thinking 等级，不变信息）。
  *
- *   "subagent worker · glm-5.2 · high"
+ *   "subagent_start coder · glm-5.2 · high"
  *
  * model/thinkingLevel 由调用方（subagent-tool.ts 的闭包）预解析后传入，
  * 因为 renderCall 在 execute 前调用，但 model 解析是同步的（只读配置）。
@@ -98,10 +98,12 @@ export function renderSubagentCall(
   resolved?: { model: string; thinkingLevel?: string },
 ): Component {
   const t = theme as ThemeLike;
-  // args 结构（拍平后）：{ action:"start", agent, task, slug, ... }（见 subagent-tool.ts schema）。
-  // 13 字段直接在顶层，extractAgentName / slug / task 都从 args 顶层提取，
+  // args 结构（拆分后 subagent_start 的平铺形态）：{ task, slug, agent, ... }（见
+  // subagent-tool-schema.ts SubagentStartParams）。14 字段直接在顶层，extractAgentName /
+  // slug / task 都从 args 顶层提取，
   // 对齐 nicobailon 的 renderCall 多行布局。agent ref 是绝对路径，显示取 basename 短名
   // （displayAgentName）；extractAgentName 原值另被 subagent-tool 的 resolveModel 消费，不动。
+  // 本函数只服务 subagent_start（manage/message 两工具用各自的轻量 actionToolRenderCall）。
   const agent = displayAgentName(extractAgentName(args));
   // slug：从顶层 args 提取（必填字段），非空时在 agent 后用 · 分隔展示。
   // 断言目标含必填 slug 字段（in 守卫已确认存在），对齐 format.ts extractAgentName 先例。
@@ -110,8 +112,8 @@ export function renderSubagentCall(
     : undefined;
   const slugStr = typeof slug === "string" ? slug.trim() : "";
   const parts = slugStr
-    ? [`${t.fg("toolTitle", t.bold("subagent "))}${t.fg("accent", agent)}${t.fg("dim", " · ")}${t.fg("accent", slugStr)}`]
-    : [`${t.fg("toolTitle", t.bold("subagent "))}${t.fg("accent", agent)}`];
+    ? [`${t.fg("toolTitle", t.bold("subagent_start "))}${t.fg("accent", agent)}${t.fg("dim", " · ")}${t.fg("accent", slugStr)}`]
+    : [`${t.fg("toolTitle", t.bold("subagent_start "))}${t.fg("accent", agent)}`];
 
   // model + thinking——完整 provider/model（accent 色），thinking 保持 dim。
   // 不去 provider 前缀——provider 是模型来源的关键信息，感知「用错模型」需要完整路径。

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

@@ -1,5 +1,6 @@
 /**
- * subagent-workflow tool 结果的公共类型（`workflow` 与 `subagents` 两个 tool 共用）。
+ * subagent-workflow tool 结果的公共类型（workflow_run / workflow_control / subagents /
+ * workflow-script 四个 tool 共用）。
  *
  * 此前两文件各自 `export interface ToolResult`（同目录同名异形，`details` 必填/可空
  * 也不同），且各自声明了一份「一次 run 启动回执」的近似形状。本模块把公共底座单点化：
@@ -21,7 +22,7 @@ export interface ToolTextContent {
  * 一次 run 启动回执的公共字段（两侧 details 各自扩展工具特有字段与判别式）。
  *
  * `status` 取并集：`subagents` 只有一个动作、启动即返回，收窄为 `"running"`；
- * `workflow` 的 actionRun 另有 `not_found` / `invalid_args` 两态。
+ * workflow_run 的 actionRun 另有 `not_found` / `invalid_args` 两态。
  */
 export interface RunStartDetails {
   runId: string;