@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

package/src/interface/subagent-tool.ts

@@ -21,7 +21,7 @@ import { getSubagentService } from "../execution/subagent-service.ts";
 import type { SubagentToolResult } from "../execution/types.ts";
 import { extractAgentName } from "./format.ts";
 import { toGuiCtx } from "./gui-mappers.ts";
-import { adapter, cancelHandler, listHandler, startHandler } from "./subagent-actions.ts";
+import { adapter, cancelHandler, closeHandler, listHandler, messageHandler, startHandler } from "./subagent-actions.ts";
 import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
 
 // ============================================================
@@ -71,8 +71,8 @@ type SubagentRenderResultCb = (
 // （subagent_start / subagent_list / subagent_cancel），让每个 tool 的 schema 真实
 // 反映必填性。勿在此基础上继续堆 action 条件逻辑——要加就拆 tool。
 const SubagentParams = Type.Object({
-  action: StringEnum(["start", "list", "cancel"], {
-    description: "Operation: 'start' runs a subagent, 'list' shows running subagents (optional includeFinished), 'cancel' stops a background subagent by id.",
+  action: StringEnum(["start", "list", "cancel", "message", "close"], {
+    description: "Operation: 'start' runs a subagent, 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to a running subagent (one-shot subagents are auto-upgraded to conversation mode on first message), 'close' ends a running subagent (conversation-mode or one-shot).",
   }),
   // ── action:"start" fields (flattened to top level). task/slug REQUIRED for start. ──
   // Missing/empty task or slug throws at runtime (startHandler).
@@ -93,7 +93,7 @@ const SubagentParams = Type.Object({
     description: 'Model override in "provider/modelId" format. Resolution order (top wins): (1) this param, (2) agent .md frontmatter model, (3) the main agent\'s current model (zero-config default). An explicit model (param or frontmatter) that is missing or unauthorized THROWS — there is no silent fallback to the main model. Omit this param to inherit the main model.',
   })),
   thinkingLevel: Type.Optional(StringEnum(THINKING_ORDER, {
-    description: "Thinking depth override (derived from THINKING_ORDER SSOT, includes 'max'). Omit to inherit the main agent's thinking level.",
+    description: "Thinking depth override (derived from THINKING_ORDER SSOT, includes 'max'). Omit to default to the model's highest available level (not the main agent's level).",
   })),
   skillPath: Type.Optional(Type.String()),
   appendSystemPrompt: Type.Optional(Type.Array(Type.String())),
@@ -113,6 +113,20 @@ const SubagentParams = Type.Object({
   cwd: Type.Optional(Type.String({
     description: 'Override the working directory for the subagent execution. Must be an absolute path. Defaults to the parent session\'s cwd.',
   })),
+  conversation: Type.Optional(Type.Boolean({
+    description:
+      "Enable continuous chat with this subagent. When true, the subagent stays available after each reply — you can send follow-up messages (action:'message') and it keeps the full conversation context across rounds, with no need to re-spawn or re-explain. " +
+      "\nUse conversation:true for: multi-round collaboration (iterative review-fix loops, back-and-forth refinement), any task where you expect to send follow-up messages after the initial result. " +
+      "\nOmit (or false) for: one-shot tasks — single exploration, lookup, file read, code generation that needs no follow-up. The subagent runs once, notifies on completion, and is cleaned up automatically (default). " +
+      "\nFor long-interval collaboration (each round spaced >5min apart), set conversation:true AND increase idleTimeoutMs to avoid premature timeout. " +
+      "Cost: a conversation-mode subagent holds resources (memory, and a worktree if enabled) until you explicitly end it with action:'close'. Always close when done.",
+  })),
+  idleTimeoutMs: Type.Optional(Type.Number({
+    description:
+      "Idle timeout in milliseconds for conversation-mode subagents. Controls how long an idle subagent (between rounds) stays alive before automatic cleanup. " +
+      "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.",
+  })),
   // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
   listParam: Type.Optional(Type.Object({
     includeFinished: Type.Optional(Type.Boolean({
@@ -128,6 +142,29 @@ const SubagentParams = Type.Object({
       description: "REQUIRED for action:'cancel'. The subagentId to cancel. Throws if missing. Only background subagents can be cancelled.",
     }),
   })),
+  // action:"message" → messageParam.subagentId + text REQUIRED. Any RUNNING subagent works —
+  // one-shot subagents are auto-upgraded to conversation mode on first message (SP-5); ended ones throw.
+  messageParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'message'. The subagentId to message (any running subagent; a one-shot subagent is auto-upgraded to conversation mode on first message, so you may also message one-shot subagents that are still running).",
+    }),
+    text: Type.String({
+      description: "REQUIRED for action:'message'. The message to send. Whitespace-only throws.",
+    }),
+    interrupt: Type.Optional(Type.Boolean({
+      description: "If true, interrupt the subagent's current work immediately (in-progress output stops, it switches to your new message). If false (default), the message is queued and processed after the current round completes. When the subagent is idle (between rounds), interrupt has no effect — the message always starts a new round.",
+    })),
+  })),
+  // action:"close" → closeParam.subagentId REQUIRED. Ends a running subagent (conversation-mode
+  // or one-shot — closeSubagent behavior split covers both).
+  closeParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'close'. The subagentId to close (any running subagent, conversation-mode or one-shot).",
+    }),
+    force: Type.Optional(Type.Boolean({
+      description: "If true, terminate immediately even if mid-round (in-progress work is lost). If false (default), let the current round finish, then close. When idle, the subagent closes immediately regardless.",
+    })),
+  })),
 });
 
 // ============================================================
@@ -142,13 +179,13 @@ function assertNever(value: never): string {
 }
 
 /** Subagent action 字面量联合（与 parameters schema 的 StringEnum 取值一致）。 */
-type SubagentAction = "start" | "list" | "cancel";
+type SubagentAction = "start" | "list" | "cancel" | "message" | "close";
 
 /** 类型守卫：把 schema 投影出的 string 形式 action 收窄回字面量联合。
  *  typebox v1 的 StringEnum Static 退化为 string，需运行时校验 + 类型收窄
  *  才能恢复 switch 的 exhaustiveness 约束。 */
 function isSubagentAction(value: string): value is SubagentAction {
-  return value === "start" || value === "list" || value === "cancel";
+  return value === "start" || value === "list" || value === "cancel" || value === "message" || value === "close";
 }
 
 /** unknown 是否为含 model/thinkingLevel 的对象（类型守卫，替代全可选结构 `as`）。 */
@@ -182,26 +219,36 @@ CRITICAL — executionMode "sequential": multiple \`subagent\` calls in the SAME
 
 ## When to delegate
 
-Delegate when the task needs a distinct specialized role, context isolation (fork/worktree), or parallelism while you do other work. Delegate FIRST when the task involves any of: reading 3+ files, writing 100+ lines of implementation, parallel research, or specialized review — doing these yourself floods your context with implementation detail and loses the orchestration view.
+Delegate when the task needs a distinct specialized role, context isolation (fork/worktree), or parallelism while you do other work. Delegate FIRST when the task involves any of: reading 3+ files, writing 100+ lines of implementation, parallel research, or specialized review — doing these yourself floods your context.
+
+## Before starting — list first
+
+action:"list" before action:"start" — a reusable running 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, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd. Background only: returns a subagentId immediately, notifies on completion.
+- action:"start" — run a subagent. Pass task and slug as top-level fields (REQUIRED). Optional: agent, model, thinkingLevel, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd, conversation, idleTimeoutMs. Background only: returns a subagentId immediately, notifies on completion.
+- action:"message" — send a follow-up message to a running subagent (conversation-mode or one-shot); it keeps the full context across rounds. REQUIRED messageParam: { subagentId, text }. Optional: interrupt (default false). The reply auto-notifies when the round completes.
+- action:"close" — end a running subagent and release its resources. REQUIRED closeParam: { subagentId }. Optional: force (default false; true terminates mid-round immediately). Always close when done.
 - action:"list" — list subagents. Pass listParam: { includeFinished?, limit? } (all optional). Read an item's sessionFile for full detail.
-- action:"cancel" — cancel a background subagent. REQUIRED cancelParam: { subagentId }.
+- action:"cancel" — stop a background subagent (legacy verb; for conversation-mode use close). REQUIRED cancelParam: { subagentId }.
 
 ## Examples
 
 \`\`\`
 {"action":"start","task":"<your task>","slug":"<kebab-case>"}
 {"action":"start","task":"...","slug":"fix-login","agent":"coder","model":"anthropic/claude-3.5-sonnet","fork":true}
+{"action":"start","task":"review iteratively","slug":"review","conversation":true}
+{"action":"message","messageParam":{"subagentId":"sa-550e8400","text":"now also handle the empty-list case"}}
+{"action":"message","messageParam":{"subagentId":"sa-550e8400","text":"stop, switch direction to X","interrupt":true}}
+{"action":"close","closeParam":{"subagentId":"sa-550e8400"}}
 {"action":"list","listParam":{"includeFinished":false,"limit":20}}
 {"action":"cancel","cancelParam":{"subagentId":"sa-550e8400"}}
 \`\`\`
 
 ## After launching — do NOT wait
 
-Completion auto-notifies you (steer wakes next turn, even mid-poll). So:
+Completion auto-notifies you (steer wakes the next turn):
 - DO NOT sleep, busy-wait, or poll — there is no poll action; use action:"list" only when you concretely need state.
 - DO useful non-overlapping work, otherwise STOP.
 - On auto-injected completion: process directly. The notification IS the confirmation — do NOT call action:"list" to re-confirm.
@@ -209,25 +256,39 @@ Completion auto-notifies you (steer wakes next turn, even mid-poll). So:
 
 ## Anti-patterns
 
-- Forgetting the REQUIRED top-level task/slug fields for action:"start" — both must be present at the top level (not nested).
+- 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 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.
 
+## Continuous chat (conversation mode)
+
+For multi-round work, set conversation:true on start. The subagent stays available across replies — action:"message" continues with full context retained, action:"close" releases it. Always close when finished.
+
+When to use:
+- ✅ Multi-round collaboration (review/fix loops) → conversation:true
+- ✅ Long-interval rounds (>5min apart) → conversation:true + idleTimeoutMs increased
+- ❌ Single exploration/lookup → default (one-shot)
+
+idleTimeoutMs: per-subagent idle timeout (default 300000 / 5min). Env XYZ_SUBAGENT_IDLE_TIMEOUT_MS sets the global default; per-call param takes precedence.
+
 ## You cannot
 
-- Get a synchronous/inline result — always background, returns a subagentId immediately.
-- Pause or resume a subagent (only cancel).
+- Get a synchronous/inline result — start always returns a subagentId immediately (background).
 - Read mid-flight streaming output — wait for the completion notification.
 
 ## Calling patterns
 
-Single (one subagent, one task) is the common case. Chain dependent tasks: send the next start after the prior completion. Run N independent tasks concurrently: send N action:"start" calls in the SAME message — each returns a subagentId at once. Start long tasks and move on; cancel if the direction changes.
+Chain dependent tasks: send the next start after prior completion. Run N independent tasks concurrently: N action:"start" calls in the SAME message. Cancel if direction changes.
+
+## Nested spawning (recursion)
+
+A subagent MAY call the \`subagent\` tool itself (depth appears in the environment block as "Depth: N/10"). The hard cap is 10 levels — depth 11 fails as a tool error, NOT a reason to avoid nesting entirely (Do NOT refuse a sub-subagent).
 
-## Nested spawning
+Recursion is for TREE-SHAPED work only: a task that decomposes naturally into independent, independently-verifiable sub-tasks. Each level's \`task\` must be SELF-CONTAINED — the child does not see your conversation (unless fork:true). Each level must have its own acceptance criteria, or errors compound silently down the chain.
 
-A subagent MAY call the \`subagent\` tool itself (each level spawns its own child process). Nesting depth appears in the environment block ("Depth: N/10") — spawn deeper while N < 10; the 11th level fails gracefully. Do NOT refuse a sub-subagent — only the depth limit applies.`,
+Do NOT recurse when: the work is linear/flat (use chain or parallel instead); the child needs your context to do the job; or you are delegating the judgment/decision your own level is responsible for. Depth should match the task tree (2-3 levels for most work; deep trees only when the decomposition genuinely demands it) — 10 is a safety rail against infinite delegation loops, not a budget to spend. Prefer fork:false in recursion: fork chains copy parent history at every level and blow up context volume linearly.`,
     executionMode: "sequential",
     parameters: SubagentParams,
     renderCall: subagentRenderCall,
@@ -321,6 +382,10 @@ const executeSubagent: SubagentExecuteCb = async (
       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));
+    case "close":
+      return adapter({ action: "close", domain: await closeHandler(service, params.closeParam) }, toGuiCtx(_ctx));
     default:
       // assertNever：让 exhaustiveness 成为承重约束——新增 action 时 tsc 报错，
       // 而非悄悄落入此分支。

package/src/interface/subagents.ts

@@ -8,6 +8,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 import { getSubagentService } from "../execution/subagent-service.ts";
+import { displayAgentName } from "../shared/agent-ref.ts";
 import { parseSubagentRpcCommand } from "./command-actions.ts";
 import { LIST_LIMIT } from "./list-shared.ts";
 import { createSubagentsView } from "./list-view.ts";
@@ -39,7 +40,7 @@ export function registerSubagentsCommand(pi: ExtensionAPI): void {
           return records.map((r) => ({
             label: r.id,
             value: r.id,
-            description: `${r.agent} [${r.status}]`,
+            description: `${displayAgentName(r.agent)} [${r.status}]`,
           }));
         } catch {
           // 拿不到运行时数据（service disposed 等）→ 静默降级，补全失败不影响 command

package/src/interface/tool-render.ts

@@ -25,6 +25,7 @@ import type {
   ListResponse,
   SubagentToolResult,
 } from "../execution/types.ts";
+import { displayAgentName } from "../shared/agent-ref.ts";
 import {
   extractAgentName,
   firstLine,
@@ -45,13 +46,19 @@ const STREAM_PREFIX = "  ⎿ ";
 /** footer 用的纯空格缩进（与 STREAM_PREFIX 等宽 4 列，但不带 ⎿）。 */
 const FOOTER_PREFIX = "    ";
 
+/** process.stdout.columns 不可用（非 TTY 等）时的终端宽度兜底（列）。 */
+const DEFAULT_TERM_WIDTH_COLUMNS = 120;
+
+/** 终端宽度扣减（列）：Pi Box paddingX=1（左右各 1 列）+ 安全余量。 */
+const TERM_WIDTH_BOX_INSET_COLUMNS = 4;
+
 /**
  * 获取终端宽度（参照 nicobailon getTermWidth）。
  * truncLine 需要在创建 Text 之前执行——此时 Pi 的 Box.render(contentWidth) 还未调用，
- * 只能从 process.stdout 估算。-4 对应 Pi Box paddingX=1（左右各 1 列）+ 安全余量。
+ * 只能从 process.stdout 估算。
  */
 function getTermWidth(): number {
-  return (process.stdout.columns || 120) - 4;
+  return (process.stdout.columns || DEFAULT_TERM_WIDTH_COLUMNS) - TERM_WIDTH_BOX_INSET_COLUMNS;
 }
 
 // ============================================================
@@ -75,9 +82,9 @@ export interface RenderContext {
 // ============================================================
 
 /**
- * renderCall：tool 标题行（agent + model + thinking，不变信息）。
+ * renderCall：tool 标题行（agent + model + thinking 等级，不变信息）。
  *
- *   "subagent worker · glm-5.2 · thinking high"
+ *   "subagent worker · glm-5.2 · high"
  *
  * model/thinkingLevel 由调用方（subagent-tool.ts 的闭包）预解析后传入，
  * 因为 renderCall 在 execute 前调用，但 model 解析是同步的（只读配置）。
@@ -94,11 +101,13 @@ export function renderSubagentCall(
   const t = theme as ThemeLike;
   // args 结构（拍平后）：{ action:"start", agent, task, slug, ... }（见 subagent-tool.ts schema）。
   // 13 字段直接在顶层，extractAgentName / slug / task 都从 args 顶层提取，
-  // 对齐 nicobailon 的 renderCall 多行布局。
-  const agent = extractAgentName(args);
+  // 对齐 nicobailon 的 renderCall 多行布局。agent ref 是绝对路径，显示取 basename 短名
+  // （displayAgentName）；extractAgentName 原值另被 subagent-tool 的 resolveModel 消费，不动。
+  const agent = displayAgentName(extractAgentName(args));
   // slug：从顶层 args 提取（必填字段），非空时在 agent 后用 · 分隔展示。
+  // 断言目标含必填 slug 字段（in 守卫已确认存在），对齐 format.ts extractAgentName 先例。
   const slug = typeof args === "object" && args !== null && "slug" in args
-    ? (args as { slug?: unknown }).slug
+    ? (args as { slug: unknown }).slug
     : undefined;
   const slugStr = typeof slug === "string" ? slug.trim() : "";
   const parts = slugStr
@@ -111,26 +120,12 @@ export function renderSubagentCall(
     parts.push(t.fg("dim", " ("));
     parts.push(t.fg("accent", resolved.model));
     if (resolved.thinkingLevel) {
-      parts.push(t.fg("dim", ` · thinking ${resolved.thinkingLevel})`));
+      parts.push(t.fg("dim", ` · ${resolved.thinkingLevel})`));
     } else {
       parts.push(t.fg("dim", ")"));
     }
   }
 
-  // task preview 行——对齐 nicobailon：renderCall 输出多行（标题 + \n + task 预览）。
-  // 实验假设：call 多行让首帧（无 result）与后续帧（有 result）的高度跳变模式
-  // 与 nicobailon 一致，可能影响 pi diff 引擎的行对齐路径。preview 截断到 60 字符。
-  const task = typeof args === "object" && args !== null && "task" in args
-    ? (args as { task?: unknown }).task
-    : undefined;
-  if (typeof task === "string" && task.length > 0) {
-    // task 取首行——prompt 常含换行（多行指令），直接 slice 会保留 \n，
-    // 渲染时意外换行破坏 tool block 行对齐。
-    const taskFirst = task.split("\n").find((l) => l.trim())?.trim() ?? "";
-    const preview = taskFirst.length > 60 ? `${taskFirst.slice(0, 60)}...` : taskFirst;
-    if (preview) parts.push(`\n  ${t.fg("dim", preview)}`);
-  }
-
   return new Text(parts.join(""), 0, 0);
 }
 
@@ -215,10 +210,9 @@ function buildCompactLines(d: SubagentToolResult, theme: ThemeLike): string[] {
   }
   // ── start 分支：background ──
   if ("bgResponse" in d) {
-    const slugPart = d.slug ? `${theme.fg("dim", " · ")}${theme.fg("accent", d.slug)}` : "";
     return [truncLine(
-      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}${slugPart}`
-      + ` ${theme.fg("dim", "· running detached · will notify on completion")}`,
+      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}`
+      + ` ${theme.fg("dim", "· detached")}`,
       width,
     )];
   }
@@ -244,9 +238,9 @@ function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
   const lines: string[] = [];
   // bg 占位 expanded 与 compact 同（一次性 block 无细节可展开）
   if ("bgResponse" in d) {
-    const slugPart = d.slug ? `${theme.fg("dim", " · ")}${theme.fg("accent", d.slug)}` : "";
     lines.push(truncLine(
-      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}${slugPart}`,
+      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}`
+      + ` ${theme.fg("dim", "· detached")}`,
       width,
     ));
     return lines;

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

@@ -211,8 +211,9 @@ export function registerWorkflowScriptTool(
           result = await actionList(registry);
           break;
         default:
-          result = textResult(`Unknown action: ${String(params.action)}`, true);
-          break;
+          // 防御性（schema StringEnum 先拦）：throw（W4b）——pi 只对 execute throw 置
+          // 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));
@@ -241,28 +242,27 @@ export function registerWorkflowScriptTool(
 
 export function actionGenerate(params: ScriptParams, signal: AbortSignal | undefined): TextContent {
   if (signal?.aborted) {
-    return textResult("Operation aborted before start", true);
+    // throw（W4b）：pi 只对 execute throw 置 isError:true（返回值 isError 被丢弃）
+    throw new Error("Operation aborted before start");
   }
   const name = params.name;
   const script = params.script;
   if (!name || !script) {
-    return textResult("generate requires 'name' and 'script' parameters", true);
+    throw new Error("generate requires 'name' and 'script' parameters");
   }
 
  // 1. Reject ESM syntax (Worker runs CJS); 'export const meta' 例外
   const stripped = script.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
   if (/\bimport\s+(?:type\s+)?[\w{*]/.test(stripped)) {
-    return textResult(
+    throw new Error(
       "Script uses ESM 'import' syntax. Workflow scripts run in a CJS Worker — use require() instead.",
-      true,
     );
   }
   const hasExportMeta = /\bexport\s+const\s+meta\s*=/.test(stripped);
   const otherExports = stripped.match(/\bexport\s+(?:const|let|var|function|default|\{)/g);
   if (otherExports && !hasExportMeta) {
-    return textResult(
+    throw new Error(
       "Script uses ESM 'export' (non-meta). Use 'const meta = {...}' at top level instead.",
-      true,
     );
   }
 
@@ -270,17 +270,15 @@ export function actionGenerate(params: ScriptParams, signal: AbortSignal | undef
   const hasPiMeta = /\/\*\s*@pi-meta\s*\n/.test(script);
   const hasLegacyMeta = script.includes("const meta") || script.includes("export const meta");
   if (!hasPiMeta && !hasLegacyMeta) {
-    return textResult(
+    throw new Error(
       "Script must contain a meta declaration: a /* @pi-meta */ YAML block comment (preferred) or legacy const meta = { ... }. The block has the form: a block comment starting with /* @pi-meta followed by YAML (name/description/phases/parameters?/usage?), closed by */ on its own line.",
-      true,
     );
   }
 
  // 3. Check agent usage
   if (!/\bagent\s*\(/.test(stripped)) {
-    return textResult(
+    throw new Error(
       "Script does not contain any agent() calls. A workflow must call agent() at least once.",
-      true,
     );
   }
 
@@ -290,7 +288,7 @@ export function actionGenerate(params: ScriptParams, signal: AbortSignal | undef
     new Function(`(async () => { ${cjsScript} })();`);
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
-    return textResult(`Syntax error in script: ${msg}`, true);
+    throw new Error(`Syntax error in script: ${msg}`);
   }
 
  // 4b. Round-trip: validate /* @pi-meta */ YAML before writing (v5 §4.7 / ERR4 — report linePos, don't write bad files)
@@ -300,9 +298,8 @@ export function actionGenerate(params: ScriptParams, signal: AbortSignal | undef
       const loc = "linePos" in detailed && detailed.linePos
         ? ` (line ${detailed.linePos.line}, col ${detailed.linePos.col})`
         : "";
-      return textResult(
+      throw new Error(
         `Generated /* @pi-meta */ YAML cannot be parsed${loc}: ${detailed.error}. Common causes: YAML indent errors, patternProperties regex must use double backslash (\\d not \d), or a stray star-slash inside the YAML body. Fix the meta block and retry.`,
-        true,
       );
     }
   }
@@ -332,7 +329,7 @@ async function actionLint(
 ): Promise<TextContent> {
   const name = params.name;
   if (!name) {
-    return textResult("lint requires 'name' parameter", true);
+    throw new Error("lint requires 'name' parameter");
   }
   const source = await loadScriptSource(name, registry);
   if (!source) {
@@ -341,9 +338,8 @@ async function actionLint(
     const suggestions = available
       .map((wf) => `  - ${wf.name}: ${wf.meta.description || "(no description)"}`)
       .join("\n");
-    return textResult(
+    throw new Error(
       `Workflow '${name}' not found or not available.\nAvailable:\n${suggestions || "  (none)"}`,
-      true,
     );
   }
 
@@ -386,7 +382,7 @@ async function loadScriptSource(
 async function actionSave(params: ScriptParams): Promise<TextContent> {
   const name = params.name;
   if (!name) {
-    return textResult("save requires 'name' parameter (tmp script name)", true);
+    throw new Error("save requires 'name' parameter (tmp script name)");
   }
   try {
     const result = await saveWorkflow(name, params.newName);
@@ -395,12 +391,10 @@ 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 = err instanceof Error ? err.message : String(err);
-    return {
-      content: [{ type: "text", text: `Save failed: ${msg}` }],
-      details: { action: "save", name, ok: false },
-      isError: true,
-    };
+    throw new Error(`Save failed: ${msg}`);
   }
 }
 
@@ -413,7 +407,7 @@ function actionDelete(
 ): TextContent {
   const name = params.name;
   if (!name) {
-    return textResult("delete requires 'name' parameter", true);
+    throw new Error("delete requires 'name' parameter");
   }
  // deleteWorkflow 内部检查 isRunning（防止删运行中脚本）
   try {
@@ -425,12 +419,9 @@ function actionDelete(
       details: { action: "delete", name, ok: true },
     };
   } catch (err: unknown) {
+    // throw（W4）：同 save——pi 契约只有 throw 才置 isError:true。
     const msg = err instanceof Error ? err.message : String(err);
-    return {
-      content: [{ type: "text", text: `Delete failed: ${msg}` }],
-      details: { action: "delete", name, ok: false },
-      isError: true,
-    };
+    throw new Error(`Delete failed: ${msg}`);
   }
 }
 
@@ -451,17 +442,22 @@ async function actionList(registry: WorkflowScriptRegistry): Promise<TextContent
       details: { action: "list", count: available.length },
     };
   } catch (err: unknown) {
+    // throw（W4b）：list 失败改 throw（原 return isError 被 pi 丢弃），文案保持
     const msg = err instanceof Error ? err.message : String(err);
-    return textResult(`List failed: ${msg}`, true);
+    throw new Error(`List failed: ${msg}`);
   }
 }
 
 // ── helper ───────────────────────────────────────────────────
 
-function textResult(text: string, isError = false): TextContent {
+/**
+ * 构造纯文本非错误结果（W4b：isError 参数已删除——pi 只对 execute throw 置
+ * isError:true，返回值里的 isError 被 agent-loop 丢弃（agent-loop.js:453-483），
+ * 错误一律 throw，编译器兜底防回潮）。
+ */
+function textResult(text: string): TextContent {
   return {
     content: [{ type: "text", text }],
     details: undefined,
-    isError: isError || undefined,
   };
 }