@zhushanwen/pi-subagent-workflow 8.14.3 → 8.14.4

package/src/interface/tool-subagents.ts

@@ -0,0 +1,310 @@
+/**
+ * Subagent Workflow Extension — subagents tool（批量派发入口，一跳扁平 schema）。
+ *
+ * ⚠️ 命名同名不同命名空间，互指防混淆：本文件是 **tool**（模型调用的批量派发面，
+ * 名为 `subagents`），`interface/subagents.ts` 是 **slash 命令**壳（`/subagents`：
+ * TUI list overlay + GUI 定向消息通道）。两者无共享状态、无调用关系——改本文件
+ * 不影响命令壳，反之亦然。
+ *
+ * 行为契约（设计 §3.1 终态 / §3.3 D1-D3、D8、D9）：
+ * - 唯一批量入口：N 个已知独立任务一次派发；handler 确定性转译
+ *   runWorkflow("fan-out")（执行管道唯一——collect 时代的批协调状态已退役，
+ *   不存在第二套批机制）。
+ * - 无 action 分发：status/abort 不复制，直接指路 workflow tool（runId 同体系）。
+ * - 无 args 嵌套：tasks/agents/aggregate/... 全在顶层（弱模型信任 schema 结构信号，
+ *   两跳转译是事故高发区——对照 workflow tool 的 name+args 形态）。
+ * - 批量成员是一次性成员：不可 message/续聊（workflow-origin record 由 messageHandler
+ *   拒绝），结果在 run 收口时以一条通知（notifyDone）到达。
+ * - 不构造 `details.__gui__`：GUI 挂载按 WORKFLOW_TOOL_NAMES 集合分流，批量块走
+ *   workflow 块分支（恒折叠单行 + openWorkflowDrawer）；`__gui__` 的渲染点在普通
+ *   tool 分支（v-else）的展开区内，isWorkflow 分支无展开路径不消费——构造即死代码
+ *   （D8 裁决；workflow tool 现状构造 `__gui__` 但块面同样不消费，本工具不复制该漂移）。
+ *
+ * 层归属：Interface。依赖 Pi SDK + core lifecycle/registry + reentry-guard。
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
+
+import { MAX_TIMER_DELAY_MS, SLUG_MAX_LENGTH, THINKING_ORDER } from "@zhushanwen/subagent-core";
+import type { LauncherDeps } from "@zhushanwen/subagent-core";
+import { assertEntryTimeBudget, assertSlugWithinLimit, runWorkflow } from "@zhushanwen/subagent-core";
+import {
+  acquireReentryGuard,
+  REENTRY_BUSY_MESSAGE,
+  type ReentryGuardRef,
+  releaseReentryGuard,
+} from "./reentry-guard.ts";
+import {
+  assertNotAborted,
+  buildRunSpecFromScript,
+  formatAvailableWorkflowList,
+  optionSlugSuffix,
+  renderTextResult,
+} from "./tool-shared.ts";
+import type { RunStartDetails, WorkflowToolResult } from "./tool-result.ts";
+
+// ── Constants ────────────────────────────────────────────────
+
+/**
+ * 本工具的固定执行体（内置模板）脚本名。
+ *
+ * 常量而非参数：subagents tool 的契约就是「转译到 fan-out 模板」——参数化会让
+ * 工具的语义随脚本漂移（对照 D3「执行管道唯一」）。脚本按名经 registry 解析
+ * （内置名优先链与 workflow tool actionRun 同一条，见 plan U2「复刻既有加载路径」）。
+ */
+export const FAN_OUT_SCRIPT_NAME = "fan-out";
+
+/** 批量标签时间短码基数（Date.now() 的 36 进制形态：8 字符覆盖到 2059 年）。 */
+const SLUG_TIME_RADIX = 36;
+
+// ── Parameter schema（D2：一跳扁平，无 action、无嵌套 args）──
+
+const SubagentsParams = Type.Object({
+  tasks: Type.Array(Type.String(), {
+    description:
+      "N complete, self-contained task descriptions — one array element = one dispatchable task prompt. " +
+      "Members run as independent one-shot subagents (they do NOT see your conversation), so each element must carry its own context and acceptance criteria. " +
+      "All tasks are dispatched in parallel; results arrive together.",
+  }),
+  agents: Type.Optional(Type.String({
+    description:
+      "Comma-separated absolute paths to agent .md files (use <location> from <available_subagents>). " +
+      "One path applies to every member; N paths map one-to-one onto tasks in the same order. " +
+      "When more than one path is given it MUST equal the number of tasks — a mismatch fails the run fast (never a silent persona swap). " +
+      "Omit for the default (general-purpose) executor.",
+  })),
+  aggregate: Type.Optional(Type.Boolean({
+    description:
+      "Default false. When true, one extra agent is appended at the end to reduce all results into a single conclusion (results are still returned in full).",
+  })),
+  slug: Type.Optional(Type.String({
+    description:
+      "Batch label (max 35 chars, kebab-case) shown on the conversation block and run list — provide a short label for multi-batch scenarios. " +
+      "If omitted, one is generated for the run state face only.",
+    maxLength: SLUG_MAX_LENGTH,
+  })),
+  model: Type.Optional(Type.String({
+    description:
+      "Run-level model override in 'provider/modelId' format; every member of the batch inherits it. " +
+      "Omit to inherit the main agent's model.",
+  })),
+  thinkingLevel: Type.Optional(StringEnum(THINKING_ORDER, {
+    description:
+      "Run-level thinking depth for every member. Omit to default each agent to its model's highest available level.",
+  })),
+  tokens: Type.Optional(Type.Number({ description: "Max token budget for the whole batch — ONLY set when the user explicitly requests a limit; omit = unlimited (default)" })),
+  time: Type.Optional(Type.Number({ description: `Max time budget in ms for the whole batch — ONLY set when the user explicitly requests a limit; omit = unlimited (default; hard ceiling ${MAX_TIMER_DELAY_MS} ms — larger values fail fast at entry)` })),
+});
+
+export type SubagentsToolParams = Static<typeof SubagentsParams>;
+
+// ── Tool result types ────────────────────────────────────────
+
+/**
+ * `subagents` tool 的 details。
+ *
+ * 单形态（无 action 判别式——本工具只有一个动作）。刻意不含 `__gui__`（D8）：
+ * 批量块由集合分流走 workflow 块分支，不消费 GUI 描述符。
+ */
+export interface SubagentsToolDetails extends RunStartDetails {
+  /** 启动即返回（后台运行），恒 "running"。 */
+  status: "running";
+  /** 执行体模板名（恒 FAN_OUT_SCRIPT_NAME，供程序化消费方核对）。 */
+  scriptName: string;
+  /** 生效标签（模型提供的 slug，或 handler 生成的 fan-out-<时间短码>）。 */
+  slug: string;
+  taskCount: number;
+}
+
+/** Result returned by the `subagents` tool's execute（公共骨架见 tool-result.ts）。 */
+type SubagentsExecuteResult = WorkflowToolResult<SubagentsToolDetails>;
+
+// ── helpers ──────────────────────────────────────────────────
+
+/**
+ * 生成缺省批量标签 `fan-out-<时间短码>`（时间短码 = Date.now() 的 36 进制）。
+ *
+ * 长度：`fan-out-` (8) + 8 = 16 ≤ SLUG_MAX_LENGTH (35)，数十年内形态稳定
+ * （36^8 = 2.8e12 ms ≈ 2059 年）——测试锁定该不变量。
+ * 空串与空白串按「未提供」处理（避免状态面出现空标签）。
+ */
+export function generateBatchSlug(now: number = Date.now()): string {
+  return `${FAN_OUT_SCRIPT_NAME}-${now.toString(SLUG_TIME_RADIX)}`;
+}
+
+/** 启动返回文案（设计 §3.1 成功路径原文：一条通知 + 单次 status 恢复出口 + abort 指引）。 */
+function subagentsStartupText(
+  slug: string,
+  runId: string,
+  taskCount: number,
+  scriptName: string,
+): string {
+  return [
+    `Started batch '${slug}' (${runId}) as workflow run '${scriptName}' — ${taskCount} subagents dispatched in parallel (allSettled).`,
+    "Results arrive as ONE notification when the run settles. Do NOT poll.",
+    `If no notification arrives well past the expected duration, make a SINGLE status check: workflow tool with runId ${runId} (recovery exit, not a poll loop).`,
+    `To abort: workflow tool, action abort, runId ${runId}`,
+  ].join("\n");
+}
+
+/**
+ * 批量运行体（execute 主体；导出供契约测试直接调用）。
+ *
+ * 失败形态与恢复动作见设计 §3.3 D9（本函数只做入口级 fail-fast：tasks 缺失/空、
+ * slug 超长、time 超上界；tasks 元素/agents 数量错配由模板入口 fail-fast——run 即
+ * 失败，两条路径不重复实现同一约束）。
+ */
+export async function runSubagentsBatch(
+  params: SubagentsToolParams,
+  deps: LauncherDeps,
+  signal: AbortSignal | undefined,
+): Promise<SubagentsExecuteResult> {
+  // D9：tasks 缺失/空数组 → 入口 throw（pi 只对 execute throw 置 isError:true）。
+  // 文案带 Correct 示例：弱模型照抄即可自纠。
+  const tasks = params.tasks;
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    throw new Error(
+      'tasks is required (non-empty string array). Correct: {"tasks":["...","..."]}',
+    );
+  }
+
+  // slug 运行时护栏（与 workflow tool actionRun 对称的纵深防御；schema maxLength 是第一道关卡）
+  const providedSlug = params.slug?.trim();
+  assertSlugWithinLimit(providedSlug, ["tri-review", "scan-docs"]);
+  // 缺省（或空白）时 handler 生成 fan-out-<时间短码>：受益面 = 状态面（drawer run header /
+  // run 投影名）；对话流块面显示的是模型 input.slug（无 input 回写通路——D8 分面声明）。
+  const slug = providedSlug ? providedSlug : generateBatchSlug();
+
+  // OR-1 入口 fail-fast：schema 的 time 是 Type.Number 直通（无上界），超 setTimeout
+  // 安全域的值会穿透到 lifecycle 内层防线（assertSafeTimerDelay）——入口拦截让它永不
+  // 进入副作用链（判定与文案单点在 core shared/entry-guards）。
+  const time = params.time;
+  assertEntryTimeBudget(time);
+
+  // 执行体脚本按内置名解析（与 workflow tool actionRun 同一条链：registry.get 命中
+  // 内置/已保存名；本工具不允许换脚本，故不回落 getPath）。
+  const script = await deps.registry.get(FAN_OUT_SCRIPT_NAME);
+  if (!script || !script.available) {
+    const all = await deps.registry.loadAll();
+    const available = formatAvailableWorkflowList(all);
+    throw new Error(
+      `Built-in workflow '${FAN_OUT_SCRIPT_NAME}' is not available — the subagents tool runs it as its batch body. ` +
+      `Recovery: verify the @zhushanwen/subagent-core package ships workflows/${FAN_OUT_SCRIPT_NAME}.js (reinstall/repair it), then retry. ` +
+      `Workflows currently available:\n${available || "  (none)"}`,
+    );
+  }
+
+  // D3 确定性转译：tasks/agents/aggregate 原样进 args（模板参数面，$ARGS）；未提供的
+  // 缺省键不写入（模板侧 aggregate 缺省 false；空值不制造「都传/都缺」歧义形态）。
+  const args: Record<string, unknown> = { tasks };
+  if (params.agents !== undefined) args.agents = params.agents;
+  if (params.aggregate !== undefined) args.aggregate = params.aggregate;
+
+  const runId = await runWorkflow(
+    buildRunSpecFromScript(script, {
+      args,
+      budgetTokens: params.tokens,
+      budgetTimeMs: time,
+      slug,
+      model: params.model,
+      thinkingLevel: params.thinkingLevel,
+    }),
+    deps,
+    signal,
+  );
+
+  return {
+    content: [{ type: "text", text: subagentsStartupText(slug, runId, tasks.length, script.name) }],
+    details: {
+      runId,
+      status: "running",
+      scriptName: script.name,
+      slug,
+      taskCount: tasks.length,
+      stateFile: deps.store.stateFilePath(runId),
+    },
+  };
+}
+
+// ── Tool registration ────────────────────────────────────────
+
+/**
+ * 注册 `subagents` tool（唯一批量派发入口）。
+ *
+ * @param pi ExtensionAPI
+ * @param deps LauncherDeps（LifecycleDeps + registry）
+ * @param reentryRef reentry guard。**与 workflow tool 共用同一实例**（index.ts
+ *   factory 内创建的单例）——两者是同一条 runWorkflow 管道的入口，共用守卫避免
+ *   双 guard 语义漂移；workflow-script tool 的 isScriptRunning 是另一套 flag，
+ *   与本 guard 无关。
+ */
+export function registerSubagentsTool(
+  pi: ExtensionAPI,
+  deps: LauncherDeps,
+  reentryRef: ReentryGuardRef,
+): void {
+  pi.registerTool({
+    name: "subagents",
+    label: "Subagents (batch)",
+    description:
+      "Spawn multiple subagents in ONE call and collect all results together — for N INDEPENDENT tasks.\n" +
+      "Each member is a one-shot batch member: you cannot message or continue it (re-dispatch instead). Results arrive as ONE notification when the whole batch settles (not per member).\n" +
+      "For a single subagent you can message later, use the `subagent` tool. For tasks that depend on each other's output (step 2 needs step 1's result), use the `workflow` tool (chain / map-reduce) instead — batch members never see each other's results.",
+    promptSnippet: "Dispatch N independent subagent tasks in one batch",
+    promptGuidelines: [
+      "PRIORITY: 2+ independent tasks in one dispatch (results combined by you afterwards) → call `subagents` ONCE with the tasks array — do NOT issue N separate `subagent` starts and do NOT hand-build a workflow.",
+      "One-shot batch members: message/fork-from a batch member is not supported; to redo or extend a member's work, dispatch a new task (run the failed/extra task alone in a second batch).",
+      "Do NOT poll after starting — the batch result arrives as a single completion notification carrying every member's summary (plus optional aggregate).",
+      "Call shape (JSON): {\"tasks\":[\"<task 1>\",\"<task 2>\"],\"agents\":\"<abs .md path or comma-separated list>\",\"aggregate\":false,\"slug\":\"<short label>\"}. tasks is required and every element must be a complete self-contained task prompt.",
+      "agents: one path applies to all tasks; N paths map one-to-one onto tasks and N must equal tasks.length (a mismatch fails the run). Omit for the default executor.",
+      "slug: pass a short kebab-case label when you run more than one batch — it identifies the batch on the conversation block and in the run list.",
+      "Budget: Do NOT set tokens/time unless the user explicitly requests a limit. Batches run unlimited by default.",
+      "Model/thinkingLevel: omit by default (inherit the main agent's model). Only set them when the user explicitly requests a specific model or thinking depth for this batch.",
+      "Anti-patterns: nesting the tasks under an 'args' key (they are top-level), dispatching dependent steps in one batch (chain them across messages or use the workflow tool), and treating batch results as verified without checking them.",
+      "Run control (status/abort) lives in the workflow tool — use the runId printed in this tool's output.",
+    ],
+    parameters: SubagentsParams,
+
+    async execute(
+      _toolCallId: string,
+      params: SubagentsToolParams,
+      signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: ExtensionContext,
+    ): Promise<SubagentsExecuteResult> {
+      // throw（W4b 契约）：pi 只对 execute throw 置 isError:true，返回值里的 isError
+      // 被 agent-loop 丢弃——错误一律 throw（abort 前置判定收敛在 tool-shared）。
+      assertNotAborted(signal);
+      // reentry guard：与 workflow tool 共用（acquire 失败时尚未持有 guard，throw 前无需 release）
+      if (!acquireReentryGuard(reentryRef)) {
+        throw new Error(REENTRY_BUSY_MESSAGE);
+      }
+      try {
+        return await runSubagentsBatch(params, deps, signal);
+      } finally {
+        releaseReentryGuard(reentryRef);
+      }
+    },
+
+    renderCall(args: Record<string, unknown>, theme: Theme, _context?: unknown) {
+      // 单行标题：subagents <N tasks> · <slug>（TUI 惯例同 workflow tool 的 renderCall）
+      const count = Array.isArray(args.tasks) ? args.tasks.length : 0;
+      const bulk = count > 0 ? ` ${count} tasks` : "";
+      const slug = optionSlugSuffix(args.slug, theme);
+      return new Text(
+        theme.fg("toolTitle", theme.bold("subagents ")) +
+          theme.fg("muted", bulk) +
+          slug,
+        0,
+        0,
+      );
+    },
+
+    renderResult(result: { content?: Array<{ type: string; text?: string }> }, _options: unknown, _theme: Theme, _context?: unknown) {
+      return renderTextResult(result);
+    },
+  });
+}

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

@@ -17,8 +17,6 @@
  * 置 isError:true）；AbortSignal 的 aborted 检查留宿主层（C4 偏差 #4 已声明）。
  *
  * 层归属：Interface。依赖 Pi SDK + engine script-lint + infra workflow-files。
- *
- * 参考：domain-models.md §FR-5（tool 收口 4→2）。
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -43,7 +41,7 @@ import {
 } from "@zhushanwen/subagent-core";
 import type { WorkflowScriptRegistry } from "@zhushanwen/subagent-core";
 import { toGuiCtx } from "./gui-mappers.ts";
-import { renderTextFallback } from "./format.ts";
+import { assertNotAborted, renderTextResult } from "./tool-shared.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // ── Parameter schema ─────────────────────────────────────────
@@ -242,7 +240,7 @@ export function registerWorkflowScriptTool(
       _theme: Theme,
       _context?: unknown,
     ) {
-      return new Text(renderTextFallback(result), 0, 0);
+      return renderTextResult(result);
     },
   });
 }
@@ -250,11 +248,9 @@ export function registerWorkflowScriptTool(
 // ── generate action ──────────────────────────────────────────
 
 export function actionGenerate(params: ScriptParams, signal: AbortSignal | undefined): TextContent {
-  if (signal?.aborted) {
-    // throw（W4b）：pi 只对 execute throw 置 isError:true（返回值 isError 被丢弃）。
-    // AbortSignal 是 pi tool 契约层关注——core 管线不含 signal 检查，宿主自留（C4 偏差 #4）
-    throw new Error("Operation aborted before start");
-  }
+  // throw（W4b）：pi 只对 execute throw 置 isError:true（返回值 isError 被丢弃）。
+  // AbortSignal 是 pi tool 契约层关注——core 管线不含 signal 检查，宿主自留（C4 偏差 #4）
+  assertNotAborted(signal);
   const name = params.name ?? "";
   const script = params.script ?? "";
 

package/src/interface/tool-workflow.ts

@@ -12,8 +12,6 @@
  * 不可挂起，提前停止用 abort，要新结果开新 run）。
  *
  * 层归属：Interface。依赖 Pi SDK + Engine lifecycle/launcher + helpers。
- *
- * 参考：domain-models.md §FR-5（tool 收口 4→2）。
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -44,15 +42,25 @@ import {
   findFlattenedArgKeys,
   MAX_TIMER_DELAY_MS,
 } from "@zhushanwen/subagent-core";
+import { assertEntryTimeBudget, assertSlugWithinLimit } from "@zhushanwen/subagent-core";
 import { runSummary } from "@zhushanwen/subagent-core";
 import { mapRunIcon, mapRunStatus, toGuiCtx } from "./gui-mappers.ts";
+import { ID_PREVIEW_LENGTH } from "./id-preview.ts";
+import type { RunStartDetails, WorkflowToolResult } from "./tool-result.ts";
 import {
   acquireReentryGuard,
   REENTRY_BUSY_MESSAGE,
   type ReentryGuardRef,
   releaseReentryGuard,
 } from "./reentry-guard.ts";
-import { formatRunStatusElapsed, renderTextFallback } from "./format.ts";
+import { formatRunStatusElapsed } from "./format.ts";
+import {
+  assertNotAborted,
+  buildRunSpecFromScript,
+  formatAvailableWorkflowList,
+  optionSlugSuffix,
+  renderTextResult,
+} from "./tool-shared.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // ── Parameter schema ─────────────────────────────────────────
@@ -107,9 +115,6 @@ type WorkflowToolParams = Static<typeof WorkflowParams>;
 
 // ── Constants ────────────────────────────────────────────────
 
-/** runId 截断长度（显示用）。 */
-const RUNID_SHORT = 8;
-
 /**
  * tool 自身顶层键（workflow params schema 键）——workflow 参数名与 tool 键撞名时
  * （如 workflow 声明参数 name），顶层同名键是 tool 参数而非平铺（m6 评审 M-3）。
@@ -169,16 +174,12 @@ interface RunSummary {
  * without unsafe casts.
  */
 export type WorkflowToolDetails =
-  | { action: "run"; runId: string; status: "running" | "not_found" | "invalid_args"; name: string; slug?: string; stateFile?: string; __gui__?: GuiRenderResult }
+  | ({ action: "run"; name: string; __gui__?: GuiRenderResult } & RunStartDetails)
   | { action: "status"; runs: RunSummary[]; __gui__?: GuiRenderResult }
   | { action: "abort"; runId: string; status: string; reason?: string; __gui__?: GuiRenderResult };
 
-/** Result returned by the `workflow` tool's execute. */
-export interface ToolResult {
-  content: Array<{ type: "text"; text: string }>;
-  details: WorkflowToolDetails | undefined;
-  isError?: boolean;
-}
+/** Result returned by the `workflow` tool's execute（公共骨架见 tool-result.ts）。 */
+type WorkflowExecuteResult = WorkflowToolResult<WorkflowToolDetails | undefined>;
 
 // ── GUI 协议 helpers ───────────────────────────────────────
 
@@ -208,7 +209,7 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
     const statusStr = details.status;
     return guiComponent("list-tree", {
       items: [{
-        label: [details.name, details.slug, details.runId.slice(0, RUNID_SHORT)].filter(Boolean).join(" "),
+        label: [details.name, details.slug, details.runId.slice(0, ID_PREVIEW_LENGTH)].filter(Boolean).join(" "),
         status: mapRunStatus(statusStr),
         icon: mapRunIcon(statusStr),
       }],
@@ -219,7 +220,7 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
       items: details.runs.map((r) => {
         const statusStr = r.reason ? `${r.status} (${r.reason})` : r.status;
         return {
-          label: [r.name, r.slug, r.runId.slice(0, RUNID_SHORT)].filter(Boolean).join(" "),
+          label: [r.name, r.slug, r.runId.slice(0, ID_PREVIEW_LENGTH)].filter(Boolean).join(" "),
           status: mapRunStatus(statusStr),
           icon: mapRunIcon(statusStr),
         };
@@ -230,7 +231,7 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
   return guiComponent("stats-line", {
     items: [{
       label: details.action,
-      value: details.runId.slice(0, RUNID_SHORT),
+      value: details.runId.slice(0, ID_PREVIEW_LENGTH),
       severity: "warn" as const,
     }],
   });
@@ -270,7 +271,7 @@ export function registerWorkflowTool(
       "script file (script header has @pi-meta parameters + usage + phases). Do NOT use " +
       "workflow-script generate for patterns already covered by available workflows.",
       "run: pass the workflow ref as name — the listed <name> (builtin/saved workflow) or its <location> absolute .js path from <available_workflows> — then start in background (no user confirmation needed).",
-      "Do NOT poll status after starting — results appear automatically via notifyDone.",
+      "DO NOT bash sleep or poll status after starting — results appear automatically via notifyDone.",
       "Runs are one-shot: there is no pause/resume — to stop a run early use abort; for a fresh result start a new run.",
       "Call shapes (JSON): " +
       "- run: {\"action\":\"run\",\"name\":\"<script>\",\"args\":{...},\"tokens\":N,\"time\":N,\"model\":\"<provider/modelId>\",\"thinkingLevel\":\"<level>\"}. " +
@@ -291,19 +292,18 @@ export function registerWorkflowTool(
       signal: AbortSignal | undefined,
       _onUpdate: unknown,
       _ctx: ExtensionContext,
-    ): Promise<ToolResult> {
+    ): Promise<WorkflowExecuteResult> {
  // P1-2: Honor abort signal up-front
-      if (signal?.aborted) {
-        // throw（W4b）：pi 只对 execute throw 置 isError:true，返回值里的 isError
-        // 被 agent-loop 丢弃（agent-loop.js:453-483）——文案原样进 toolResult。
-        throw new Error("Operation aborted before start");
-      }
+      // throw（W4b）：pi 只对 execute throw 置 isError:true，返回值里的 isError
+      // 被 agent-loop 丢弃（agent-loop.js:453-483）——文案原样进 toolResult。
+      // abort 前置判定收敛在 tool-shared（三处 tool 同源）。
+      assertNotAborted(signal);
  // P1-6: Reentry guard（acquire 失败时尚未持有 guard，throw 前无需 release）
       if (!acquireReentryGuard(reentryRef)) {
         throw new Error(REENTRY_BUSY_MESSAGE);
       }
       try {
-        let result: ToolResult;
+        let result: WorkflowExecuteResult;
         // 断言为 WorkflowAction 联合——typebox Static 推断为 any，显式标注让 default
         // 分支的 never 穷尽检查生效（新增 action 时 tsc 报错强制补 case）。
         const action = params.action as WorkflowAction;
@@ -337,10 +337,8 @@ export function registerWorkflowTool(
       const action = String(args.action ?? "");
       const name = args.name ? ` ${String(args.name)}` : "";
       // run action 可选 slug：在 name 后追加 · slug（accent 色）
-      const slug = typeof args.slug === "string" && args.slug.trim()
-        ? `${theme.fg("dim", " · ")}${theme.fg("accent", String(args.slug))}`
-        : "";
-      const runId = args.runId ? ` ${String(args.runId).slice(0, RUNID_SHORT)}` : "";
+      const slug = optionSlugSuffix(args.slug, theme);
+      const runId = args.runId ? ` ${String(args.runId).slice(0, ID_PREVIEW_LENGTH)}` : "";
       return new Text(
         theme.fg("toolTitle", theme.bold("workflow ")) +
           theme.fg("muted", action) +
@@ -353,7 +351,7 @@ export function registerWorkflowTool(
     },
 
     renderResult(result: { content?: Array<{ type: string; text?: string }> }, _options: unknown, _theme: Theme, _context?: unknown) {
-      return new Text(renderTextFallback(result), 0, 0);
+      return renderTextResult(result);
     },
   });
 }
@@ -364,7 +362,7 @@ export async function actionRun(
   params: WorkflowToolParams,
   deps: LauncherDeps,
   signal: AbortSignal | undefined,
-): Promise<ToolResult> {
+): Promise<WorkflowExecuteResult> {
   const name = params.name;
   if (!name) {
     throw new Error("run requires 'name' parameter (absolute .js path from <available_workflows> <location>). Correct: {\"action\":\"run\",\"name\":\"<ref>\",\"args\":{...}}");
@@ -391,10 +389,7 @@ export async function actionRun(
  // 模糊匹配建议。throw（W4）：pi 只对 execute throw 置 isError:true，
  // 返回值里的 isError 被 agent-loop 丢弃（agent-loop.js:453-483）——文案原样进 toolResult。
     const all = await deps.registry.loadAll();
-    const available = all.filter((wf) => wf.available);
-    const suggestions = available
-      .map((wf) => `  - ${wf.name}: ${wf.meta.description || "(no description)"}\n    location: ${wf.path}`)
-      .join("\n");
+    const suggestions = formatAvailableWorkflowList(all);
     // [按名解析自救指引] 摘要逐条附绝对路径 location：run 的 name 形参最贴近的
     // 读取面就是本清单（<available_workflows> 注入面在 start 时已过时/可能不在
     // 上下文）——模型按清单里的名字重试（8.6.0 实装 getPath-only 时代的实测失败
@@ -429,42 +424,28 @@ export async function actionRun(
     );
   }
   // slug 运行时护栏（与 subagent startHandler 对称的纵深防御；schema maxLength 是第一道关卡）
-  if (params.slug !== undefined && params.slug.length > SLUG_MAX_LENGTH) {
-    throw new Error(
-      `slug exceeds ${SLUG_MAX_LENGTH} chars (got ${params.slug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`,
-    );
-  }
+  assertSlugWithinLimit(params.slug, ["fix-login", "extract-urls"]);
   const args = params.args ?? {};
   const tokens = params.tokens;
   const time = params.time;
   // OR-1 入口 fail-fast（crash-forensics-and-watchdog.md 附录 E（原 unbounded-wait-audit §7.2 T3①））：schema 的 time 是
   // Type.Number 直通（无上界）——超 setTimeout 安全域的值会穿透到 lifecycle 内层
-  // 防线（assertSafeTimerDelay），而入口拦截让它永不进入副作用链。错误带合法上限
-  // 与实际传入值，LLM 可据消息自纠（clamp 或省略走 unlimited 语义）。
-  if (time !== undefined && time > MAX_TIMER_DELAY_MS) {
-    throw new Error(
-      `time budget ${time} ms exceeds the maximum of ${MAX_TIMER_DELAY_MS} ms (~24.8 days). ` +
-        `Retry with a smaller "time", or omit it for unlimited.`,
-    );
-  }
+  // 防线（assertSafeTimerDelay），而入口拦截让它永不进入副作用链（判定与文案单点在
+  // core shared/entry-guards；LLM 可据消息自纠：clamp 或省略走 unlimited 语义）。
+  assertEntryTimeBudget(time);
 
  // 构建 RunSpec + 启动（m3：parameters 从 script.meta 拷贝——chokepoint 校验用；
  // 校验失败 → ArgsValidationError 直接 throw 给 pi（W4：err.message 含 §5.3 指引，
  // pi catch 后原文案进 toolResult content 并置 isError:true），其他错误保持传播）
   const runId = await runWorkflow(
-    {
-      scriptSource: script.toExecutable(),
+    buildRunSpecFromScript(script, {
       args,
       budgetTokens: tokens,
       budgetTimeMs: time,
-      scriptName: script.name,
       slug: params.slug,
-      scriptPath: script.path,
-      description: script.meta.description,
-      parameters: script.meta.parameters,
       model: params.model,
       thinkingLevel: params.thinkingLevel,
-    },
+    }),
     deps,
     signal,
   );
@@ -474,8 +455,8 @@ export async function actionRun(
       {
         type: "text",
         text: params.slug
-          ? `Started workflow '${script.name}' · ${params.slug} (${runId}). Running in background — do NOT poll status.`
-          : `Started workflow '${script.name}' (${runId}). Running in background — do NOT poll status.`,
+          ? `Started workflow '${script.name}' · ${params.slug} (${runId}). Running in background — DO NOT bash sleep or poll status; results are auto-delivered via notifyDone.`
+          : `Started workflow '${script.name}' (${runId}). Running in background — DO NOT bash sleep or poll status; results are auto-delivered via notifyDone.`,
       },
     ],
     details: { action: "run", runId, status: "running", name: script.name, slug: params.slug, stateFile: deps.store.stateFilePath(runId) },
@@ -485,7 +466,7 @@ export async function actionRun(
 
 // ── status action ────────────────────────────────────────────
 
-function actionStatus(deps: LauncherDeps): ToolResult {
+function actionStatus(deps: LauncherDeps): WorkflowExecuteResult {
   const runs = Array.from(deps.runs.values());
   if (runs.length === 0) {
     return {
@@ -499,7 +480,7 @@ function actionStatus(deps: LauncherDeps): ToolResult {
     // now 基准），不再随每次 status 查询的墙钟增长。
     const duration = s.startedAt ? ` (${formatRunStatusElapsed(s.startedAt, s.completedAt)})` : "";
     const reasonSuffix = s.reason && s.reason !== "completed" ? ` [${s.reason}]` : "";
-    return `[${s.status}${reasonSuffix}] ${s.name} (${s.runId.slice(0, RUNID_SHORT)})${duration}${s.error ? ` error: ${s.error}` : ""}`;
+    return `[${s.status}${reasonSuffix}] ${s.name} (${s.runId.slice(0, ID_PREVIEW_LENGTH)})${duration}${s.error ? ` error: ${s.error}` : ""}`;
   });
   return {
     content: [{ type: "text", text: lines.join("\n") }],
@@ -515,7 +496,7 @@ async function actionLifecycle(
   action: "abort",
   params: WorkflowToolParams,
   deps: LauncherDeps,
-): Promise<ToolResult> {
+): Promise<WorkflowExecuteResult> {
   const runId = params.runId;
   if (!runId) {
     throw new Error(`'runId' is required for ${action}. Correct: {"action":"${action}","runId":"<id>"} (use action:"status" to find runId)`);