@zhushanwen/pi-subagent-workflow 8.14.7 → 9.0.0

package/src/interface/subagent-tool.ts

@@ -3,11 +3,12 @@
 // `subagent` LLM 工具。薄壳——参数解析 + 调 runtime.execute。
 // 不创建 state、不节流 onUpdate、不持久化（全部在 runtime 层统一）。
 //
-// 设计说明：renderCall/renderResult/execute 三个回调均抽成模块级 const +
-// 顶层 type alias。原因：stub 的 registerTool(tool: unknown) 参数是 unknown，
-// 在其对象字面量内直接标注从 pi-coding-agent 导入的泛型（AgentToolResult<X>、
-// Theme、ExtensionContext）会触发 TS2307 误报（probe5d/5f 验证）。
-// 抽到顶层后参数类型由 alias 提供，绕过该 quirk。
+// 设计说明：execute / renderCall 两个回调抽成模块级 const + 顶层 type alias。
+// 原因：stub 的 registerTool(tool: unknown) 参数是 unknown，在其对象字面量内直接
+// 标注从 pi-coding-agent 导入的泛型（AgentToolResult<X>、Theme、ExtensionContext）
+// 会触发 TS2307 误报（probe5d/5f 验证）。抽到顶层后参数类型由 alias 提供，绕过
+// 该 quirk。renderResult 直接引用 tool-render.ts 导出的 renderSubagentResult
+// 函数值——值引用不涉及类型标注，不受该 quirk 影响。
 
 import { isAbsolute } from "node:path";
 
@@ -18,9 +19,17 @@ import type { Static } from "typebox";
 
 import { getSubagentService } from "@zhushanwen/subagent-core";
 import type { SubagentToolResult } from "@zhushanwen/subagent-core";
+import {
+  cancelHandler,
+  closeHandler,
+  forkFromHandler,
+  listHandler,
+  messageHandler,
+  startHandler,
+} from "@zhushanwen/subagent-core";
 import { extractAgentName } from "./format.ts";
 import { toGuiCtx } from "./gui-mappers.ts";
-import { adapter, cancelHandler, closeHandler, forkFromHandler, listHandler, messageHandler, startHandler } from "./subagent-actions.ts";
+import { adapter } from "./subagent-actions.ts";
 import { SubagentParams } from "./subagent-tool-schema.ts";
 import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
@@ -48,13 +57,6 @@ type SubagentExecuteCb = (
 
 type SubagentRenderCallCb = (args: unknown, theme: Theme, ctx: RenderContext) => Component;
 
-type SubagentRenderResultCb = (
-  result: AgentToolResult<SubagentToolResult>,
-  options: { expanded: boolean; isPartial: boolean },
-  theme: Theme,
-  ctx: RenderContext,
-) => Component;
-
 // ============================================================
 // renderCall 预解析 helper
 // ============================================================
@@ -221,7 +223,7 @@ Do NOT recurse when: the work is linear/flat; the child needs your context; or y
     executionMode: "sequential",
     parameters: SubagentParams,
     renderCall: subagentRenderCall,
-    renderResult: subagentRenderResult,
+    renderResult: renderSubagentResult,
     execute: executeSubagent,
   });
 }
@@ -260,9 +262,6 @@ const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
   return renderSubagentCall(args, theme, ctx, resolved);
 };
 
-const subagentRenderResult: SubagentRenderResultCb = (result, options, theme, ctx) =>
-  renderSubagentResult(result, options, theme, ctx);
-
 /**
  * execute 实现（action 路由 + adapter）。
  *
@@ -295,7 +294,16 @@ const executeSubagent: SubagentExecuteCb = async (
   // background 模式：execute 立即返回，detached 运行不向 tool 层回流 onUpdate
   //（完成由 notify 驱动新 turn）。onUpdate 参数保留以兼容 SDK 回调签名，但不消费。
   const service = getSubagentService();
-  if (!service) throw new Error("subagents runtime not initialized");
+  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.",
+    );
+  }
 
   // typebox v1 的 StringEnum 在 Static 投影下退化为 string，此处类型守卫收窄回
   // 字面量联合，恢复 switch 的 exhaustiveness 约束（default 分支 = never）。

package/src/interface/subagents.ts

@@ -13,23 +13,17 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { getSubagentService } from "@zhushanwen/subagent-core";
 import type { SubagentService } from "@zhushanwen/subagent-core";
 import { displayAgentName } from "@zhushanwen/subagent-core";
-import { messageHandler, startHandler } from "./subagent-actions.ts";
+import { messageHandler, startHandler } from "@zhushanwen/subagent-core";
+import { SUBAGENT_DIRECTIVE_CUSTOM_TYPE } from "@zhushanwen/extension-protocol";
 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";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
-/**
- * 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 customType 经 extension-protocol 单源（与 shared/runtime 消费侧
+// 同源；等值锁 = src/__tests__/contract.notify-custom-types.test.ts）。定向消息留痕
+// 载体语义见下方 emitSubagentDirective 注释。
 
 /** subagent-directive entry 的 details 形状（GUI 定向气泡渲染契约）。 */
 export interface SubagentDirectiveDetails {

package/src/interface/tool-render.ts

@@ -32,8 +32,8 @@ import {
   formatElapsedSeconds,
   statusGlyph,
   type ThemeLike,
-  truncLine,
 } from "./format.ts";
+import { truncLine } from "./tui-kit.ts";
 
 // ============================================================
 // 常量
@@ -65,14 +65,14 @@ function getTermWidth(): number {
 // ============================================================
 
 /**
- * renderResult 的 context（SDK ToolRenderContext 的有意子集——只读 state/invalidate）。
- * SDK 实际传入更完整的 { args, toolCallId, cwd, executionStarted, argsComplete, isPartial,
- * expanded, showImages, isError, lastComponent, ... }，本组件结构兼容只取需要的字段。
+ * renderResult 的 context（SDK ToolRenderContext 的有意子集——结构兼容只声明
+ * 本组件需要的字段）。SDK 实际传入更完整的 { args, toolCallId, cwd,
+ * executionStarted, argsComplete, isPartial, expanded, showImages, isError,
+ * lastComponent, ... }。
  *
  * 注意：不使用 lastComponent。每次 renderResult 返回新 Container（参照 nicobailon）。
  */
 export interface RenderContext {
-  state: Record<string, never>;
   invalidate(): void;
 }
 
@@ -228,7 +228,10 @@ function buildCompactLines(d: SubagentToolResult, theme: ThemeLike): string[] {
 }
 
 /**
- * 展开视图行内容生成。完整 eventLog + 交付物。
+ * 展开视图行内容生成。除下列两个特例外与 compact 逐字节相同（一次性 block 无
+ * 细节可展开），测试锁字节等价：
+ * - list：compact 结果之上每 item 追加 sessionFile 路径行（renderListExpanded）
+ * - fork-from：源文件用完整路径（compact 用 basename 短标签）
  */
 function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
   const width = getTermWidth();
@@ -236,34 +239,15 @@ function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
   if (d.action === "list" && d.listResponse) {
     return renderListExpanded(d.listResponse, theme, width);
   }
-  if (d.action === "cancel" && d.cancelResponse) {
+  if (d.action === "fork-from" && d.forkFromResponse) {
     return [truncLine(
-      `${theme.fg("muted", "■")} ${theme.fg("dim", "cancelled ")}${theme.fg("accent", d.subagentId ?? "?")}`,
+      `${theme.fg("accent", "⑂")} ${theme.fg("dim", "forked-from ")}${theme.fg("accent", d.forkFromResponse.sourceSessionFile)}` +
+      ` ${theme.fg("dim", "→ new: ")}${theme.fg("accent", d.subagentId ?? "?")}`,
       width,
     )];
   }
-  if (d.action === "fork-from" && d.forkFromResponse) {
-    // expanded 与 compact 同形（一次性 block 无细节可展开），另附源文件完整路径行。
-    return [
-      truncLine(
-        `${theme.fg("accent", "⑂")} ${theme.fg("dim", "forked-from ")}${theme.fg("accent", d.forkFromResponse.sourceSessionFile)}` +
-        ` ${theme.fg("dim", "→ new: ")}${theme.fg("accent", d.subagentId ?? "?")}`,
-        width,
-      ),
-    ];
-  }
-
-  const lines: string[] = [];
-  // bg 占位 expanded 与 compact 同（一次性 block 无细节可展开）
-  if ("bgResponse" in d) {
-    lines.push(truncLine(
-      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}`
-      + ` ${theme.fg("dim", "· detached")}`,
-      width,
-    ));
-    return lines;
-  }
-  return [truncLine(theme.fg("warning", "(subagent: no response)"), width)];
+  // cancel / start(bg) / fallback：expanded 与 compact 逐字节相同
+  return buildCompactLines(d, theme);
 }
 
 // ============================================================

package/src/interface/tool-shared.ts

@@ -4,8 +4,16 @@
  * 抽取边界（findings g11a-F1/F2/F3）：
  * - `assertNotAborted` / `optionSlugSuffix` / `renderTextResult`：三处逐字重复的
  *   入口前置与渲染片段（同粒度小函数）。
- * - `buildRunSpecFromScript` / `formatAvailableWorkflowList`：RunSpec 组装字面量与
- *   「可用脚本清单」串——RunSpec 是 core 启动契约，两份字面量漏改即静默丢字段。
+ * - `buildRunSpecFromScript`：RunSpec 组装字面量——RunSpec 是 core 启动契约，
+ *   字面量漏改即静默丢字段。
+ * - `withGuiAttach`：RPC 模式给 details 附加 `__gui__` 的唯一实现（workflow-script /
+ *   subagent 两个 tool 的 attach 点收敛于此，组件构造回调由调用方提供；workflow /
+ *   subagents 走 isWorkflow 块分支不消费 `__gui__`，不构造——D8）。
+ * - `throwPrefixed`：catch 内 `<前缀>: <msg>` 重抛（pi 的 execute-throw 契约，
+ *   toErrorMessage 规整单点）。
+ *
+ * 「可用脚本清单」串不在本文件：已并入 core 单源
+ *（@zhushanwen/subagent-core 的 formatAvailableWorkflowRefs，经 barrel 消费）。
  *
  * **不**把 execute 包成 HOF：reentry-guard.ts 文件头已裁决（HOF 包装会破坏 union
  * 返回类型推断），本文件只放同粒度小函数，guard 的 check → try/finally release
@@ -17,7 +25,10 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 
+import type { GuiComponent, GuiContext, GuiRenderResult } from "@zhushanwen/extension-protocol";
+import { guiResult, isGuiCapable } from "@zhushanwen/extension-protocol";
 import type { RunSpec, WorkflowScript } from "@zhushanwen/subagent-core";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { renderTextFallback } from "./format.ts";
 
 /** renderResult 回调的宽入参形态（content 可缺省，由 renderTextFallback 兜底）。 */
@@ -93,17 +104,49 @@ export function buildRunSpecFromScript(
   };
 }
 
+/** withGuiAttach 的 details 约束：已声明 `__gui__?`（消费 attach 的 details union 均满足）。 */
+interface GuiAttachableDetails {
+  __gui__?: GuiRenderResult;
+}
+
+/**
+ * GUI attach 单点：RPC 模式（isGuiCapable，仅 mode==="rpc"）下为 details 附加
+ * `__gui__`，其余模式原样返回；details 为 undefined 时原样返回（过载签名区分
+ * 可空/非空入参，非空入参的返回不带 undefined——调用方无需收窄）。
+ *
+ * 组件构造是各 tool 特有逻辑，经 build 回调注入——回调只在 attach 分支被调用
+ * （非 RPC 模式零构造成本）。union 各成员已声明 `__gui__?`，spread + 补字段类型
+ * 安全，无需强转。
+ */
+export function withGuiAttach<Details extends GuiAttachableDetails>(
+  details: Details,
+  ctx: GuiContext | undefined,
+  build: (details: Details) => GuiComponent,
+): Details;
+export function withGuiAttach<Details extends GuiAttachableDetails>(
+  details: Details | undefined,
+  ctx: GuiContext | undefined,
+  build: (details: Details) => GuiComponent,
+): Details | undefined;
+export function withGuiAttach<Details extends GuiAttachableDetails>(
+  details: Details | undefined,
+  ctx: GuiContext | undefined,
+  build: (details: Details) => GuiComponent,
+): Details | undefined {
+  if (!details) return details;
+  if (ctx && isGuiCapable(ctx)) {
+    return { ...details, __gui__: guiResult(build(details)) };
+  }
+  return details;
+}
+
 /**
- * 「可用脚本清单」串（无可用项 → 空串，调用方自行补 `|| "  (none)"`）。
+ * catch 内重抛单点：`<prefix>: <msg>`（msg 经 toErrorMessage 规整）。
  *
- * 每项两行（name + description，缩进 location 绝对路径）——弱模型按清单里的名字
- * / 路径重试的自救主路径，两个 tool 的文案必须同源。
+ * pi 只对 execute throw 置 isError:true——返回值里的 isError 被 agent-loop 丢弃
+ * （agent-loop.js:453-483），错误一律 throw，本函数是四个 catch 点共享的唯一包装
+ * 形态；前缀是 LLM 可见文案，调用方逐字保持既有形态。
  */
-export function formatAvailableWorkflowList(all: readonly WorkflowScript[]): string {
-  return all
-    .filter((wf) => wf.available)
-    .map(
-      (wf) => `  - ${wf.name}: ${wf.meta.description || "(no description)"}\n    location: ${wf.path}`,
-    )
-    .join("\n");
+export function throwPrefixed(prefix: string, err: unknown): never {
+  throw new Error(`${prefix}: ${toErrorMessage(err)}`);
 }

package/src/interface/tool-subagents.ts

@@ -10,6 +10,11 @@
  * - 唯一批量入口：N 个已知独立任务一次派发；handler 确定性转译
  *   runWorkflow("fan-out")（执行管道唯一——collect 时代的批协调状态已退役，
  *   不存在第二套批机制）。
+ * - 批量派发的等价性契约：tasks[] 经 handler 确定性转译为内置 fan-out 模板脚本，
+ *   走 runWorkflow 完整管道执行——模板仅由 tasks[] 确定性生成、不含任何批协调
+ *   状态，执行管道唯一（不存在第二套批机制）；走管道使批量派发继承 workflow 的
+ *   持久化、journal、GUI 投影与断点恢复（resume）全套能力，这是刻意保留间接层
+ *   的原因。
  * - 无 action 分发：status/abort 不复制，直接指路 workflow tool（runId 同体系）。
  * - 无 args 嵌套：tasks/agents/aggregate/... 全在顶层（弱模型信任 schema 结构信号，
  *   两跳转译是事故高发区——对照 workflow tool 的 name+args 形态）。
@@ -18,7 +23,7 @@
  * - 不构造 `details.__gui__`：GUI 挂载按 WORKFLOW_TOOL_NAMES 集合分流，批量块走
  *   workflow 块分支（恒折叠单行 + openWorkflowDrawer）；`__gui__` 的渲染点在普通
  *   tool 分支（v-else）的展开区内，isWorkflow 分支无展开路径不消费——构造即死代码
- *   （D8 裁决；workflow tool 现状构造 `__gui__` 但块面同样不消费，本工具不复制该漂移）。
+ *   （D8 裁决；workflow tool 的 `__gui__` 死构造已随之删除，isWorkflow 集合内工具零消费）。
  *
  * 层归属：Interface。依赖 Pi SDK + core lifecycle/registry + reentry-guard。
  */
@@ -30,7 +35,13 @@ 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";
+// formatAvailableWorkflowRefs：拒单可用清单单源（core launcher，副本已并入）。
+import {
+  assertEntryTimeBudget,
+  assertSlugWithinLimit,
+  formatAvailableWorkflowRefs,
+  runWorkflow,
+} from "@zhushanwen/subagent-core";
 import {
   acquireReentryGuard,
   REENTRY_BUSY_MESSAGE,
@@ -40,7 +51,6 @@ import {
 import {
   assertNotAborted,
   buildRunSpecFromScript,
-  formatAvailableWorkflowList,
   optionSlugSuffix,
   renderTextResult,
 } from "./tool-shared.ts";
@@ -163,11 +173,12 @@ export async function runSubagentsBatch(
   signal: AbortSignal | undefined,
 ): Promise<SubagentsExecuteResult> {
   // D9：tasks 缺失/空数组 → 入口 throw（pi 只对 execute throw 置 isError:true）。
-  // 文案带 Correct 示例：弱模型照抄即可自纠。
+  // 文案与其他 tool 的必填参数拒单同模板（<subject> requires '<param>' parameter.
+  // Correct: <最小正确调用例>）：本工具无 action，主语用工具名。
   const tasks = params.tasks;
   if (!Array.isArray(tasks) || tasks.length === 0) {
     throw new Error(
-      'tasks is required (non-empty string array). Correct: {"tasks":["...","..."]}',
+      'subagents requires \'tasks\' parameter (non-empty string array). Correct: {"tasks":["...","..."]}',
     );
   }
 
@@ -184,12 +195,13 @@ export async function runSubagentsBatch(
   const time = params.time;
   assertEntryTimeBudget(time);
 
-  // 执行体脚本按内置名解析（与 workflow tool actionRun 同一条链：registry.get 命中
-  // 内置/已保存名；本工具不允许换脚本，故不回落 getPath）。
+  // 执行体脚本按固定内置名解析（registry.get 精确名匹配；脚本名是工具自带常量
+  // FAN_OUT_SCRIPT_NAME 而非用户参数——workflow tool actionRun 的按名解析已退役
+  // 走 getPath 单通道，本工具不允许换脚本，无 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);
+    const available = formatAvailableWorkflowRefs(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. ` +
@@ -303,8 +315,6 @@ export function registerSubagentsTool(
       );
     },
 
-    renderResult(result: { content?: Array<{ type: string; text?: string }> }, _options: unknown, _theme: Theme, _context?: unknown) {
-      return renderTextResult(result);
-    },
+    renderResult: renderTextResult,
   });
 }

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

@@ -14,7 +14,8 @@
  * generateWorkflowScript（报错文案逐字平移，CA2 前提）；save/delete 改调 core
  * barrel（第三可选目录参数缺省即 pi 布局 .pi/workflows——pi 现两参调用形态零变化）。
  * 结构化 {ok}|{error} → pi 的 execute-throw 契约转换在本层（pi 只对 execute throw
- * 置 isError:true）；AbortSignal 的 aborted 检查留宿主层（C4 偏差 #4 已声明）。
+ * 置 isError:true）；AbortSignal 的 aborted 检查在 execute 入口统一拦截（与
+ * workflow / subagents 两 tool 同源，tool-shared assertNotAborted；C4 偏差 #4）。
  *
  * 层归属：Interface。依赖 Pi SDK + engine script-lint + infra workflow-files。
  */
@@ -26,23 +27,21 @@ import { type Static, Type } from "typebox";
 
 import {
   guiComponent,
-  type GuiContext,
   type GuiRenderResult,
-  guiResult,
-  isGuiCapable,
 } from "@zhushanwen/extension-protocol";
 // C5②/C5⑦：创作闭环统一走 core barrel（generateWorkflowScript/saveWorkflow/
 // deleteWorkflow/lintScript 均为 barrel 导出面；深路径在 npm/vendored 形态不可达）
 import {
   deleteWorkflow,
+  formatAvailableWorkflowRefs,
   generateWorkflowScript,
   lintScript,
   saveWorkflow,
 } from "@zhushanwen/subagent-core";
 import type { WorkflowScriptRegistry } from "@zhushanwen/subagent-core";
 import { toGuiCtx } from "./gui-mappers.ts";
-import { assertNotAborted, renderTextResult } from "./tool-shared.ts";
-import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import type { WorkflowToolResult } from "./tool-result.ts";
+import { assertNotAborted, renderTextResult, throwPrefixed, withGuiAttach } from "./tool-shared.ts";
 
 // ── Parameter schema ─────────────────────────────────────────
 
@@ -82,17 +81,13 @@ export type WorkflowScriptToolDetails =
   | { action: "save"; name: string; ok: boolean; __gui__?: GuiRenderResult }
   | { action: "delete"; name: string; ok: boolean; __gui__?: GuiRenderResult };
 
-/** Result returned by the `workflow-script` tool's execute. */
-export interface TextContent {
-  content: Array<{ type: "text"; text: string }>;
-  details: WorkflowScriptToolDetails | undefined;
-  isError?: boolean;
-}
+/** Result returned by the `workflow-script` tool's execute（公共骨架见 tool-result.ts）。 */
+export type WorkflowScriptExecuteResult = WorkflowToolResult<WorkflowScriptToolDetails | undefined>;
 
 // ── GUI 协议 helpers ───────────────────────────────────────
 
 /**
- * 为 details 附加 __gui__（RPC 模式下）。
+ * 按 WorkflowScriptToolDetails 构造 stats-line GuiComponent。
  *
  * 所有 5 个 action 都映射到 stats-line（单行统计，无复杂结构）：
  *   - generate: 显示生成的脚本名
@@ -100,20 +95,6 @@ export interface TextContent {
  *   - list: 脚本数量
  *   - save/delete: ok/warn
  */
-function withScriptGui(
-  result: TextContent,
-  ctx?: GuiContext,
-): TextContent {
-  if (!ctx || !isGuiCapable(ctx) || !result.details) return result;
-  const details = result.details;
-  // union 各成员已声明 __gui__?，spread + 补字段类型安全，无需强转
-  return {
-    ...result,
-    details: { ...details, __gui__: guiResult(buildScriptGui(details)) },
-  };
-}
-
-/** 按 WorkflowScriptToolDetails 构造 stats-line GuiComponent。 */
 export function buildScriptGui(details: WorkflowScriptToolDetails) {
   switch (details.action) {
     case "generate":
@@ -199,11 +180,15 @@ export function registerWorkflowScriptTool(
       signal: AbortSignal | undefined,
       _onUpdate: unknown,
       ctx: ExtensionContext,
-    ): Promise<TextContent> {
-      let result: TextContent;
+    ): Promise<WorkflowScriptExecuteResult> {
+      // P1-2 abort 前置（三 tool 对称）：5 个 action 统一在 execute 入口拦截——
+      // 原先只在 generate 内检查，lint/save/delete/list 四路径漏拦。throw（W4b）：
+      // pi 只对 execute throw 置 isError:true，返回值里的 isError 被 agent-loop 丢弃。
+      assertNotAborted(signal);
+      let result: WorkflowScriptExecuteResult;
       switch (params.action) {
         case "generate":
-          result = actionGenerate(params, signal);
+          result = actionGenerate(params);
           break;
         case "lint":
           result = await actionLint(params, registry);
@@ -222,8 +207,11 @@ export function registerWorkflowScriptTool(
           // isError:true，返回值里的 isError 被 agent-loop 丢弃（agent-loop.js:453-483）。
           throw new Error(`Unknown action: ${String(params.action)}`);
       }
-      // GUI 协议：RPC 模式下附加 __gui__ 到 details
-      return withScriptGui(result, toGuiCtx(ctx));
+      // GUI 协议：RPC 模式下附加 __gui__ 到 details（attach 单点在 tool-shared）
+      return {
+        ...result,
+        details: withGuiAttach(result.details, toGuiCtx(ctx), buildScriptGui),
+      };
     },
 
     renderCall(args: ScriptParams, theme: Theme, _context?: unknown) {
@@ -234,23 +222,16 @@ export function registerWorkflowScriptTool(
       return new Text(text, 0, 0);
     },
 
-    renderResult(
-      result: { content?: Array<{ type: string; text?: string }> },
-      _options: unknown,
-      _theme: Theme,
-      _context?: unknown,
-    ) {
-      return renderTextResult(result);
-    },
+    renderResult: renderTextResult,
   });
 }
 
 // ── generate action ──────────────────────────────────────────
 
-export function actionGenerate(params: ScriptParams, signal: AbortSignal | undefined): TextContent {
+export function actionGenerate(params: ScriptParams): WorkflowScriptExecuteResult {
   // throw（W4b）：pi 只对 execute throw 置 isError:true（返回值 isError 被丢弃）。
-  // AbortSignal 是 pi tool 契约层关注——core 管线不含 signal 检查，宿主自留（C4 偏差 #4）
-  assertNotAborted(signal);
+  // abort 前置在 execute 入口统一拦截（三 tool 同源，tool-shared assertNotAborted），
+  // 本函数不再自带 signal 检查。
   const name = params.name ?? "";
   const script = params.script ?? "";
 
@@ -281,18 +262,20 @@ export function actionGenerate(params: ScriptParams, signal: AbortSignal | undef
 async function actionLint(
   params: ScriptParams,
   registry: WorkflowScriptRegistry,
-): Promise<TextContent> {
+): Promise<WorkflowScriptExecuteResult> {
   const name = params.name;
   if (!name) {
-    throw new Error("lint requires 'name' parameter");
+    throw new Error(
+      "lint requires 'name' parameter. Correct: {\"action\":\"lint\",\"name\":\"<script>\"}",
+    );
   }
   const source = await loadScriptSource(name, registry);
   if (!source) {
+    // 清单 item 走 core formatAvailableWorkflowRefs 缺省形态（有意统一：与 run 拒单
+    // 一致带 location 行，自纠指引同构）；"Available:" 标题与 (none) 空态是本调用点
+    // 的语境文案。
     const all = await registry.loadAll();
-    const available = all.filter((wf) => wf.available);
-    const suggestions = available
-      .map((wf) => `  - ${wf.name}: ${wf.meta.description || "(no description)"}`)
-      .join("\n");
+    const suggestions = formatAvailableWorkflowRefs(all);
     throw new Error(
       `Workflow '${name}' not found or not available.\nAvailable:\n${suggestions || "  (none)"}`,
     );
@@ -334,10 +317,12 @@ async function loadScriptSource(
 
 // ── save action ──────────────────────────────────────────────
 
-async function actionSave(params: ScriptParams): Promise<TextContent> {
+async function actionSave(params: ScriptParams): Promise<WorkflowScriptExecuteResult> {
   const name = params.name;
   if (!name) {
-    throw new Error("save requires 'name' parameter (tmp script name)");
+    throw new Error(
+      "save requires 'name' parameter (tmp script name). Correct: {\"action\":\"save\",\"name\":\"<tmp-script>\"}",
+    );
   }
   try {
     const result = await saveWorkflow(name, params.newName);
@@ -346,10 +331,7 @@ async function actionSave(params: ScriptParams): Promise<TextContent> {
       details: { action: "save", name, ok: true },
     };
   } catch (err: unknown) {
-    // throw（W4）：pi 只对 execute throw 置 isError:true（返回值里的 isError 被
-    // agent-loop 丢弃，agent-loop.js:453-483）——文案原样进 toolResult。
-    const msg = toErrorMessage(err);
-    throw new Error(`Save failed: ${msg}`);
+    throwPrefixed("Save failed", err);
   }
 }
 
@@ -359,10 +341,12 @@ function actionDelete(
   params: ScriptParams,
   registry: WorkflowScriptRegistry,
   isRunning: (name: string) => boolean,
-): TextContent {
+): WorkflowScriptExecuteResult {
   const name = params.name;
   if (!name) {
-    throw new Error("delete requires 'name' parameter");
+    throw new Error(
+      "delete requires 'name' parameter. Correct: {\"action\":\"delete\",\"name\":\"<script>\"}",
+    );
   }
  // deleteWorkflow 内部检查 isRunning（防止删运行中脚本）
   try {
@@ -374,32 +358,28 @@ function actionDelete(
       details: { action: "delete", name, ok: true },
     };
   } catch (err: unknown) {
-    // throw（W4）：同 save——pi 契约只有 throw 才置 isError:true。
-    const msg = toErrorMessage(err);
-    throw new Error(`Delete failed: ${msg}`);
+    throwPrefixed("Delete failed", err);
   }
 }
 
 // ── list action ──────────────────────────────────────────────
 
-async function actionList(registry: WorkflowScriptRegistry): Promise<TextContent> {
+async function actionList(registry: WorkflowScriptRegistry): Promise<WorkflowScriptExecuteResult> {
   try {
     const all = await registry.loadAll();
-    const available = all.filter((wf) => wf.available);
-    if (available.length === 0) {
+    // item 行走 core formatAvailableWorkflowRefs（includeSource 保留 [saved]/[tmp]
+    // 标签、去 location 行、分隔符统一为 ":"——与拒单 item 模板单源）；标题与空态
+    // 是本调用点的语境文案。
+    const lines = formatAvailableWorkflowRefs(all, { includeSource: true, includeLocation: false });
+    if (lines === "") {
       return textResult("No workflow scripts available.");
     }
-    const lines = available.map(
-      (wf) => `  [${wf.source}] ${wf.name} — ${wf.meta.description || "(no description)"}`,
-    );
     return {
-      content: [{ type: "text", text: `Available workflows:\n${lines.join("\n")}` }],
-      details: { action: "list", count: available.length },
+      content: [{ type: "text", text: `Available workflows:\n${lines}` }],
+      details: { action: "list", count: all.filter((wf) => wf.available).length },
     };
   } catch (err: unknown) {
-    // throw（W4b）：list 失败改 throw（原 return isError 被 pi 丢弃），文案保持
-    const msg = toErrorMessage(err);
-    throw new Error(`List failed: ${msg}`);
+    throwPrefixed("List failed", err);
   }
 }
 
@@ -410,7 +390,7 @@ async function actionList(registry: WorkflowScriptRegistry): Promise<TextContent
  * isError:true，返回值里的 isError 被 agent-loop 丢弃（agent-loop.js:453-483），
  * 错误一律 throw，编译器兜底防回潮）。
  */
-function textResult(text: string): TextContent {
+function textResult(text: string): WorkflowScriptExecuteResult {
   return {
     content: [{ type: "text", text }],
     details: undefined,