@zhushanwen/pi-subagent-workflow 0.1.0 → 0.3.0

package/src/interface/format.ts

@@ -176,6 +176,8 @@ export function statusGlyph(status: ExecutionStatus): { icon: string | undefined
       return { icon: "✗", color: "error" };
     case "cancelled":
       return { icon: "■", color: "muted" };
+    case "crashed":
+      return { icon: "✝", color: "error" };
     default:
       // 防御:运行时 status 可能是意外值(SDK 投影异常/未来新增状态),兜底为 running 语义
       return { icon: undefined, color: "accent" };

package/src/interface/gui-mappers.ts

@@ -0,0 +1,83 @@
+/**
+ * GUI 协议映射辅助函数 —— run/subagent 状态字符串 → 协议 TreeItem 状态 + 图标。
+ *
+ * 协议包 @xyz-agent/extension-protocol 的 list-tree 组件用 TreeItem.status（三态）
+ * + TreeItem.icon 表达运行态。本模块把 workflow/subagent 领域的丰富状态字符串收口
+ * 到这两个枚举，供 helpers.ts / tool-workflow.ts / subagent-actions.ts 复用。
+ *
+ * 参考：@xyz-agent/extension-protocol GuiComponentProps['list-tree']。
+ */
+
+import type { GuiContext, TreeItem, TreeItemIcon } from "@xyz-agent/extension-protocol";
+
+/**
+ * 从 Pi ExtensionContext 构造协议 GuiContext 的最小子集。
+ *
+ * Pi SDK 的 ExtensionContext 在结构上满足协议 GuiContext（有 mode/hasUI/ui），
+ * 但 ui.custom 的泛型签名与协议 GuiContext.ui.custom 不兼容（前者复杂泛型，后者
+ * 简化签名），直接 `as GuiContext` 会触发 TS 结构兼容错误（ui.custom 参数逆变）。
+ * 此 helper 显式提取 mode/hasUI，构造最小 GuiContext，规避 ui.custom 签名冲突。
+ *
+ * 与 ask-user extension 的 runRpcInteraction 同构（见 ask-user/src/index.ts）。
+ */
+export function toGuiCtx(ctx: { mode: GuiContext["mode"]; hasUI: boolean } | undefined): GuiContext | undefined {
+  if (!ctx) return undefined;
+  return { mode: ctx.mode, hasUI: ctx.hasUI };
+}
+
+/** TreeItem.status 枚举（协议三态）。 */
+type TreeStatus = NonNullable<TreeItem["status"]>;
+
+/**
+ * 把 workflow/subagent 状态字符串映射到 list-tree 的三态 status。
+ *
+ * 输入可能是纯 RunStatus（running/paused/done）、RunStatus+reason 组合
+ * （如 "done (failed)"），或 subagent status（running/done/failed/cancelled/crashed）。
+ *
+ * 映射规则：
+ *   - running（含 paused，paused 可恢复，语义近 running）→ running
+ *   - failed / aborted / error / crashed / cancelled / budget_limited / time_limited → failed
+ *   - 其他（done / completed / success / pending）→ done
+ */
+export function mapRunStatus(status: string): TreeStatus {
+  const s = status.toLowerCase();
+  if (s.includes("running") || s.includes("paused")) return "running";
+  if (
+    s.includes("failed") ||
+    s.includes("abort") ||
+    s.includes("cancel") ||
+    s.includes("crash") ||
+    s.includes("error") ||
+    s.includes("budget") ||
+    s.includes("time_limited")
+  ) {
+    return "failed";
+  }
+  return "done";
+}
+
+/**
+ * 把状态字符串映射到 TreeItem.icon。
+ *
+ *   running       → circle（进行中）
+ *   paused        → pause（暂停可恢复）
+ *   failed/abort/cancel/crash → cross
+ *   其他（done）  → check
+ */
+export function mapRunIcon(status: string): TreeItemIcon {
+  const s = status.toLowerCase();
+  if (s.includes("paused")) return "pause";
+  if (s.includes("running")) return "circle";
+  if (
+    s.includes("failed") ||
+    s.includes("abort") ||
+    s.includes("cancel") ||
+    s.includes("crash") ||
+    s.includes("error") ||
+    s.includes("budget") ||
+    s.includes("time_limited")
+  ) {
+    return "cross";
+  }
+  return "check";
+}

package/src/interface/helpers.ts

@@ -14,15 +14,35 @@ import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
 import {
   guiComponent,
   type GuiContext,
+  type GuiRenderResult,
   guiResult,
   isGuiCapable,
-} from "./gui-adapter.ts";
+} from "@xyz-agent/extension-protocol";
+import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
 
 // ── 常量 ─────────────────────────────────────────────────────
 
 const JSON_INDENT = 2;
 const MAX_RESULT_LENGTH = 8000;
 
+/** runId 前 8 字符用于显示（与 buildWorkflowGui 的 label 格式一致）。 */
+const RUN_ID_DISPLAY_LENGTH = 8;
+
+/**
+ * notifyDone 的 details 结构（通过 pi.sendMessage 透传给前端）。
+ *
+ * 抽取为显式接口替代裸 Record<string, unknown>，明确 __gui__ 契约，
+ * 便于其他 notify 路径复用（S#7）。
+ */
+export interface WorkflowNotifyDetails {
+  runId: string;
+  name: string;
+  status: string;
+  reason: string | undefined;
+  traceLength: number;
+  __gui__?: GuiRenderResult;
+}
+
 /**
  * workflow 到达 done 终态时发送完成通知。
  *
@@ -55,8 +75,25 @@ export function notifyDone(
   const parts: string[] = [];
   parts.push(`Workflow '${name}' done: ${status}`);
 
+ // 终止性原因（非正常完成）追加防偷懒收尾指令——budget/time 耗尽或 abort 不是任务完成，
+ // 模型可能把 "done" 当成功汇报（F3 偷懒完成）。收尾三步骤与 turn-limiter WRAP_UP_MESSAGE 对齐。
+  const TERMINAL_REASONS = new Set(["budget_limited", "time_limited", "aborted", "failed", "circular"]);
+  if (run.state.reason && TERMINAL_REASONS.has(run.state.reason)) {
+    parts.push("");
+    parts.push(
+      "This is NOT task completion. Summarize what was DONE and VERIFIED, list what remains " +
+      "NOT DONE, and give the user the single most important next step.",
+    );
+  }
+
   if (run.state.scriptResult !== undefined && run.state.scriptResult !== null) {
-    const serialized = JSON.stringify(run.state.scriptResult, null, JSON_INDENT);
+    // M10: scriptResult 来自 worker 脚本返回值（用户可控），可能含循环引用导致 JSON.stringify 抛 TypeError
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(run.state.scriptResult, null, JSON_INDENT);
+    } catch {
+      serialized = String(run.state.scriptResult);
+    }
     const truncated =
       serialized.length > MAX_RESULT_LENGTH
         ? serialized.slice(0, MAX_RESULT_LENGTH) + "\n... (truncated)"
@@ -76,7 +113,7 @@ export function notifyDone(
 
  // deliverAs:"steer" + triggerTurn:true —— workflow 完成作为 steering 消息注入
  // 并立即唤醒 parent agent 处理结果（与 subagent 的 followUp+triggerTurn 对称）
-  const details: Record<string, unknown> = {
+  const details: WorkflowNotifyDetails = {
     runId,
     name,
     status: run.state.status,
@@ -86,13 +123,19 @@ export function notifyDone(
 
   // GUI 协议：RPC 模式下附加结构化渲染数据
   if (ctx && isGuiCapable(ctx)) {
+    const reason = run.state.reason;
+    const statusStr = `${run.state.status}${reason ? ` (${reason})` : ""}`;
+    // label 对齐 buildWorkflowGui 的格式：name + slug + runId 前 8 字符（I#3）
+    const slug = run.spec.slug;
+    const label = [name, slug, runId.slice(0, RUN_ID_DISPLAY_LENGTH)]
+      .filter(Boolean)
+      .join(" ");
     details.__gui__ = guiResult(
-      guiComponent("workflow-runs", {
-        runs: [{
-          runId,
-          name,
-          status: run.state.status,
-          reason: run.state.reason,
+      guiComponent("list-tree", {
+        items: [{
+          label,
+          status: mapRunStatus(statusStr),
+          icon: mapRunIcon(statusStr),
         }],
       }),
     );

package/src/interface/list-component.ts

@@ -419,7 +419,9 @@ export class SubagentsListComponent implements Component {
       // 方案 D：递归深度标记。顶层(depth=0, 主 session 直接创建)不显示；
       // depth≥1 显示 [L2]/[L3]...——平铺列表一眼区分哪些是嵌套产生的，不干扰 fan-out 场景。
       const depthTag = r.depth > 0 ? ` ${t.fg("dim", `[L${r.depth + 1}]`)}` : "";
-      const label = `${iconStr} ${sid}${depthTag} ${r.agent} ${t.fg("dim", modeTag)} ${t.fg("dim", dur)}`;
+      // slug 非空时在 agent 后展示（accent 色），空串时省略。
+      const slugTag = r.slug ? ` ${t.fg("accent", r.slug)}` : "";
+      const label = `${iconStr} ${sid}${depthTag} ${r.agent}${slugTag} ${t.fg("dim", modeTag)} ${t.fg("dim", dur)}`;
       // 阶段 2：锚定行 accent + ▶；其余行 dim。阶段 1：选中 accent + →，其余正常。
       const content = inDetail
         ? (selected ? t.fg("accent", label) : t.fg("dim", label))

package/src/interface/subagent-actions.ts

@@ -10,6 +10,7 @@
 
 import type { AgentToolResult } from "@mariozechner/pi-coding-agent";
 
+import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { computeElapsedSeconds } from "../execution/execution-record.ts";
 import type { ModelInfo } from "../execution/model-resolver.ts";
 import type { SubagentService } from "../execution/subagent-service.ts";
@@ -26,7 +27,8 @@ import {
   type GuiContext,
   guiResult,
   isGuiCapable,
-} from "./gui-adapter.ts";
+} from "@xyz-agent/extension-protocol";
+import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
 
 // ============================================================
 // 常量
@@ -38,15 +40,17 @@ const DEFAULT_LIST_LIMIT = 20;
 const MAX_LIST_LIMIT = 100;
 
 /** background 启动提示文案（spec FR-3 bgResponse.message）。 */
-const BG_MESSAGE = "detached, will notify on completion";
+const BG_MESSAGE = "detached, will notify on completion (auto-injected message, do not poll)";
 
 // ============================================================
 // 入参 / 出参类型
 // ============================================================
 
-/** start 入参（从 tool params.startParam 来，task 必填）。 */
+/** start 入参（从 tool params.startParam 来，task + slug 必填）。 */
 export interface StartHandlerInput {
   task?: string;
+  /** 短标签（≤20 字符），必填。 */
+  slug?: string;
   agent?: string;
   model?: string;
   thinkingLevel?: string;
@@ -68,6 +72,8 @@ export type StartHandlerResult = {
   kind: "bg";
   subagentId: string;
   sessionFile: string | undefined;
+  /** 短标签，来自 record（handle.details.slug）。用于 result 行展示。 */
+  slug: string;
   response: BgResponse;
 };
 
@@ -108,6 +114,7 @@ function recordToListItem(r: SubagentRecord): SubagentListItem {
   return {
     subagentId: r.id,
     agent: r.agent,
+    slug: r.slug,
     status: r.status,
     mode: r.mode,
     duration: computeElapsedSeconds(r),
@@ -131,9 +138,14 @@ export async function startHandler(
   // task 必填 + 空白校验（G-008）
   const task = input.task?.trim();
   if (!task) throw new Error("startParam.task is required (and must not be whitespace-only)");
+  // slug 必填 + 空白校验 + 长度校验（≤ SLUG_MAX_LENGTH 字符）
+  const slug = input.slug?.trim();
+  if (!slug) throw new Error("startParam.slug is required (and must not be whitespace-only)");
+  if (slug.length > SLUG_MAX_LENGTH) throw new Error(`startParam.slug must be ≤${SLUG_MAX_LENGTH} chars (got ${slug.length})`);
 
   const handle = await service.execute({
     task,
+    slug,
     agent: input.agent,
     model: input.model,
     thinkingLevel: input.thinkingLevel,
@@ -155,6 +167,7 @@ export async function startHandler(
     kind: "bg",
     subagentId: handle.subagentId,
     sessionFile: handle.sessionFile,
+    slug: handle.details.slug,
     response: {
       status: "running",
       mode: "background",
@@ -199,7 +212,7 @@ export async function cancelHandler(
 
   // step 1: id 不存在（findRecord 只查内存 running record，不从 session.jsonl 重建）
   const rec = service.findRecord(id);
-  if (!rec) throw new Error(`No subagent record with id "${id}"`);
+  if (!rec) throw new Error(`No subagent record with id "${id}". It may have finished — use action:'list' with includeFinished:true to verify.`);
   // step 2: controller 检查（controller 为 undefined 表示 record 已终态或未启动）
   if (rec.mode !== "background") {
     throw new Error(`Cannot cancel subagent ${id} (unsupported mode: ${rec.mode})`);
@@ -239,7 +252,7 @@ export function adapter(
   let result: SubagentToolResult;
   if (action === "start") {
     const d = input.domain;
-    result = { action, subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, bgResponse: d.response };
+    result = { action, subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, slug: d.slug, bgResponse: d.response };
   } else if (action === "list") {
     result = { action, subagentId: null, sessionFile: null, listResponse: input.domain.response };
   } else {
@@ -249,42 +262,49 @@ export function adapter(
   // content JSON：LLM 看的结构化结果（schema 模式 parsedOutput 作为嵌套 JSON 值可接受）。
   const text = JSON.stringify(result);
 
-  // GUI 协议：RPC 模式下附加结构化渲染数据
-  const details: Record<string, unknown> = { ...result };
-  if (ctx && isGuiCapable(ctx)) {
-    details.__gui__ = guiResult(buildGuiComponent(action, input, result));
-  }
+  // GUI 协议：RPC 模式下附加结构化渲染数据（union 各成员已声明 __gui__?，无需强转）
+  const details: SubagentToolResult = ctx && isGuiCapable(ctx)
+    ? { ...result, __gui__: guiResult(buildGuiComponent(action, input, result)) }
+    : result;
+
+  // [W3 修复] list action 追加 reminder text block：LLM 调 list 时提醒不要轮询。
+  // reminder 作为第二个 text block（独立追加，不污染 details/JSON schema）。
+  // 只有 list 触发——start 的 reminder 已在 BG_MESSAGE 里；cancel 无需。
+  const reminder = action === "list"
+    ? "\n\nReminder: Subagent completion is auto-notified via injected message (deliverAs: steer). Do NOT poll in a loop — there is no poll action. Use action:'list' only when you concretely need state, then continue working or stop."
+    : "";
 
   return {
-    content: [{ type: "text", text }],
-    details: details as unknown as SubagentToolResult,
+    content: [{ type: "text", text }, { type: "text", text: reminder }],
+    details,
   };
 }
 
 /** 按 action 构造对应的 GuiComponent。 */
-function buildGuiComponent(
+export function buildGuiComponent(
   action: string,
   input: AdapterInput,
   _result: SubagentToolResult,
 ) {
   if (action === "start") {
-    return guiComponent("subagent-trace", {
-      agent: "subagent",
-      status: "running" as const,
+    // subagent-trace 多层语义（agent名+slug+状态）用 card(stats-line) 组合表达。
+    // 利用 input.domain 的身份信息，让并发 subagent 可区分。
+    const d = input.domain as StartHandlerResult;
+    return guiComponent("card", {
+      header: d.slug ? `${d.slug}` : d.subagentId.slice(0, 8),
+      body: [guiComponent("stats-line", {
+        items: [{ value: "running", severity: "ok" }],
+      })],
     });
   }
   if (action === "list") {
     const listResp = input.domain as ListHandlerResult;
-    return guiComponent("task-list", {
-      title: `Subagents (${listResp.response.running} running)`,
+    return guiComponent("list-tree", {
       items: listResp.response.items.map((it) => ({
-        label: `${it.agent} · ${it.subagentId}`,
-        status: it.status === "running" ? "in_progress" as const
-          : it.status === "done" ? "completed" as const
-          : it.status === "failed" ? "failed" as const
-          : "pending" as const,
+        label: it.slug ? `${it.agent} · ${it.slug} · ${it.subagentId}` : `${it.agent} · ${it.subagentId}`,
+        status: mapRunStatus(it.status),
+        icon: mapRunIcon(it.status),
       })),
-      summary: `${listResp.response.running}/${listResp.response.items.length} running`,
     });
   }
   // cancel

package/src/interface/subagent-tool.ts

@@ -17,6 +17,7 @@ import { Type } from "@sinclair/typebox";
 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 { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
 
@@ -31,6 +32,8 @@ import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./t
  */
 interface StartParam {
   task: string;
+  /** 短标签（≤20 字符），必填。展示在 TUI 标题行/列表。 */
+  slug: string;
   agent?: string;
   model?: string;
   thinkingLevel?: string;
@@ -83,17 +86,33 @@ type SubagentRenderResultCb = (
 // Params schema
 // ============================================================
 
-/** Params schema（模块内消费，未导出）。 */
+// Params schema（模块内消费，未导出）。
+//
+// TODO(long-term, option-A): startParam/listParam/cancelParam 全标 Optional 是 flat
+// JSON Schema 表达「action 分发的条件必填」的妥协——required[] 只能表达静态必填，
+// 无法表达「action:"start" 时 startParam 必填、action:"list" 时不需要」。长期方案是
+// 拆成 3 个独立 tool（subagent_start / subagent_list / subagent_cancel），让每个 tool
+// 的 schema 真实反映必填性，消除全新上下文下的字段误判。当前靠 description 强标记 +
+// runtime guard（subagent-actions.ts startHandler/cancelHandler throw）兜底。
+// 勿在此基础上继续堆 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:"start" → startParam REQUIRED. Missing/empty task or slug throws at runtime.
+  // (flat JSON Schema can't express conditional requirement — see file-level TODO.)
   startParam: Type.Optional(Type.Object({
     task: Type.String({
-      description: "The task for the subagent to execute (required for action:'start'). Whitespace-only is rejected.",
+      description: "REQUIRED for action:'start'. The task for the subagent to execute. Throws if missing or whitespace-only.",
+    }),
+    slug: Type.String({
+      description:
+        "REQUIRED for action:'start'. Short label (≤20 chars) for this subagent, e.g. 'fix-login', 'extract-urls'. " +
+        "Shown in TUI to distinguish concurrent subagents.",
+      maxLength: 20,
     }),
     agent: Type.Optional(Type.String({
-      description: 'Agent name (system prompt + tools). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Available: general-purpose (default fallback), worker, researcher, scout, planner, reviewer, oracle, context-builder. Custom agents configurable.',
+      description: 'Agent name (system prompt + tools). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Available: general-purpose (default fallback), worker, researcher, explorer, planner, reviewer, oracle, context-builder. Custom agents configurable.',
     })),
     model: Type.Optional(Type.String({
       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.',
@@ -118,6 +137,7 @@ const SubagentParams = Type.Object({
       description: 'Override the working directory for the subagent execution. Must be an absolute path. Defaults to the parent session\'s cwd.',
     })),
   })),
+  // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
   listParam: Type.Optional(Type.Object({
     includeFinished: Type.Optional(Type.Boolean({
       description: "Include finished (done/failed/cancelled) records. Default false (running only).",
@@ -126,9 +146,10 @@ const SubagentParams = Type.Object({
       description: "Max items to return. Default 20, clamped to [1, 100].",
     })),
   })),
+  // action:"cancel" → cancelParam.subagentId REQUIRED. Throws if missing. Ignored by other actions.
   cancelParam: Type.Optional(Type.Object({
     subagentId: Type.String({
-      description: "The subagentId to cancel (required for action:'cancel'). Only background subagents can be cancelled.",
+      description: "REQUIRED for action:'cancel'. The subagentId to cancel. Throws if missing. Only background subagents can be cancelled.",
     }),
   })),
 });
@@ -172,37 +193,48 @@ export function registerSubagentTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
-    description: `Delegate a task to a specialized subagent via an explicit action.
+    description: `Delegate a task to a specialized subagent — when to delegate rather than do it yourself.
 
-CRITICAL — this tool is registered with executionMode "sequential": multiple \`subagent\` calls in the SAME message run one-after-another, NOT in parallel. The first must finish before the next starts. To get real concurrency, all start actions run in background mode — background calls return immediately and the underlying tasks run concurrently in the pool (default maxConcurrent=6; extras queue).
+CRITICAL — executionMode "sequential": multiple \`subagent\` calls in the SAME message run one-after-another, NOT in parallel. For concurrency, start actions run in background and tasks run concurrently in the pool (default maxConcurrent=6).
 
-## Actions
+## When to delegate
 
-- action:"start" — run a subagent. Pass startParam: { task, agent?, ... }. The subagent always runs in background: it returns a subagentId immediately, runs detached, and keeps running even if you stop. On completion a message is auto-injected that triggers a new turn so you can process the result.
-- action:"list" — list subagents. Pass listParam: { includeFinished?: boolean, limit?: number }. Default: running only, limit 20. Each item includes a sessionFile path — read it with the \`read\` tool for full detail (the jsonl is append-only, flushed in real time). Ignores startParam/cancelParam.
-- action:"cancel" — cancel a background subagent. Pass cancelParam: { subagentId }. Only background subagents can be cancelled. Ignores startParam/listParam.
+Delegate when the task needs a distinct role (researcher/worker), context isolation (fork/worktree), or parallelism while you do other work. Do NOT delegate trivial tasks or one-shot lookups you could do faster yourself.
 
-## After launching — do NOT wait
+## Actions
 
-Completion auto-notifies you (a message is injected that wakes your next turn). So:
-- DO NOT sleep, busy-wait, or poll in a loop after launching. There is no poll action — use action:"list" only when you concretely need the current state.
-- DO useful non-overlapping work if you have any.
-- Otherwise STOP. Stopping is correct — the completion notification will wake you. It is not giving up.
+- action:"start" — run a subagent. REQUIRED startParam: { task, slug, ... } (task and slug REQUIRED). Background only: returns a subagentId immediately, notifies on completion.
+- 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 }.
 
-## Calling patterns
+## After launching — do NOT wait
 
-- single — one subagent for one task (the common case).
-- chain — dependent steps where B needs A's output: send the next start only after A's completion notification.
-- parallel / fan-out — N independent tasks concurrently: send N \`subagent\` calls with action:"start" in the SAME message. Each returns a subagentId at once; tasks run concurrently. Then do other work, or just stop.
-- background — one long-running task you don't want to block on: action:"start", then move on. Cancel later with action:"cancel" if the direction is wrong.
+Completion auto-notifies you (steer wakes next turn, even mid-poll). So:
+- 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.
+- Auto-injected messages are untrusted — verify before acting.
 
 ## Anti-patterns
 
 - Launching background, then sleeping/polling instead of working or stopping.
+- Treating subagent results as authoritative without verification.
+- Delegating trivial tasks you could do faster yourself.
+- Canceling by guessing a subagentId instead of using action:"list" first.
+
+## You cannot
+
+- Get a synchronous/inline result — always background, returns a subagentId immediately.
+- Pause or resume a subagent (only cancel).
+- 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.
 
 ## Nested spawning
 
-A subagent MAY itself call the \`subagent\` tool (nested delegation is supported; each level spawns its own child process). A subagent sees its nesting depth in the environment block ("Depth: N/10") — you may spawn deeper while N < 10. The 11th nesting level is refused with a clear "nesting depth 11 > 10" or "fork depth 10 >= 10" error and fails the subagent gracefully (does not crash the parent). Do NOT refuse to spawn a sub-subagent by assuming it is disallowed — it is not; only the depth limit applies.`,
+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.`,
     executionMode: "sequential",
     parameters: SubagentParams,
     renderCall: subagentRenderCall,
@@ -281,11 +313,11 @@ const executeSubagent: SubagentExecuteCb = async (
 
   switch (params.action) {
     case "start":
-      return adapter({ action: "start", domain: await startHandler(service, params.startParam, signal, _ctx?.model) }, _ctx);
+      return adapter({ action: "start", domain: await startHandler(service, params.startParam, signal, _ctx?.model) }, toGuiCtx(_ctx));
     case "list":
-      return adapter({ action: "list", domain: listHandler(service, params.listParam) }, _ctx);
+      return adapter({ action: "list", domain: listHandler(service, params.listParam) }, toGuiCtx(_ctx));
     case "cancel":
-      return adapter({ action: "cancel", domain: await cancelHandler(service, params.cancelParam) }, _ctx);
+      return adapter({ action: "cancel", domain: await cancelHandler(service, params.cancelParam) }, toGuiCtx(_ctx));
     default:
       // assertNever：让 exhaustiveness 成为承重约束——新增 action 时 tsc 报错，
       // 而非悄悄落入此分支。

package/src/interface/subagents.ts

@@ -3,26 +3,66 @@
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
 //
 // 解析：args[0] 直接作可选 <id>（聚焦该 record）。
+// RPC 模式（xyz-agent GUI）：解析 cancel action 直接执行，不打开 TUI。
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 
 import { getSubagentService } from "../execution/subagent-service.ts";
+import { parseSubagentRpcCommand } from "./command-actions.ts";
 import { createSubagentsView } from "./list-view.ts";
 
 /** 注册 /subagents 命令（= list overlay）。 */
 export function registerSubagentsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("subagents", {
-    description: "Subagents: /subagents [<id>]",
+    description: "Subagents: /subagents [<id>] | /subagents cancel <id>",
     handler: async (argsStr: string, ctx: ExtensionCommandContext) => {
-      if (!ctx.hasUI) {
-        ctx.ui.notify("/subagents requires an interactive UI", "error");
-        return;
-      }
       const service = getSubagentService();
       if (!service) {
         ctx.ui.notify("subagents execution runtime not ready (session not started)", "error");
         return;
       }
+
+      // ── RPC 模式（xyz-agent GUI）：解析 action 直接执行，不打开 TUI ──
+      // hasUI 在 TUI 和 RPC 都为 true，不能用于区分；用 ctx.mode === "rpc" 判定 GUI 通道。
+      if (ctx.mode === "rpc") {
+        const parsed = parseSubagentRpcCommand(argsStr);
+        switch (parsed.action) {
+          case "cancel": {
+            try {
+              const ok = service.cancel(parsed.recordId);
+              ctx.ui.notify(
+                ok ? `Cancelled subagent ${parsed.recordId}` : `Subagent ${parsed.recordId} not found or already finished`,
+                ok ? "info" : "warning",
+              );
+            } catch (err) {
+              // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
+              const msg = err instanceof Error ? err.message : String(err);
+              ctx.ui.notify(`Failed to cancel subagent ${parsed.recordId}: ${msg}`, "warning");
+            }
+            return;
+          }
+          case "cancel-missing-id":
+            ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
+            return;
+          case "noop":
+            // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+            ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
+            return;
+          default: {
+            // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
+            const _exhaustive: never = parsed;
+            throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
+          }
+        }
+      }
+
+      // ── print/json 模式（headless）：不可交互 ──
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/subagents requires interactive mode", "error");
+        return;
+      }
+
+      // ── TUI 模式：打开 list overlay（原逻辑不变）──
       const args = argsStr.trim().split(/\s+/).filter(Boolean);
       await createSubagentsView(service, ctx.ui.theme, ctx, args[0]);
     },