@zhushanwen/pi-subagent-workflow 0.1.0

package/src/interface/subagent-actions.ts

@@ -0,0 +1,294 @@
+// src/interface/subagent-actions.ts
+//
+// subagent tool 的内部 handler + 唯一 adapter。
+//
+// 分层（spec FR-2）：
+//   1. startHandler / listHandler / cancelHandler —— 纯领域对象进出，不碰 {content, details}
+//   2. adapter(action, 领域对象) —— 唯一包装为 AgentToolResult<SubagentToolResult>
+//
+// content（JSON 字符串）给 LLM，details（SubagentToolResult）给 renderResult，同源同处生成。
+
+import type { AgentToolResult } from "@mariozechner/pi-coding-agent";
+
+import { computeElapsedSeconds } from "../execution/execution-record.ts";
+import type { ModelInfo } from "../execution/model-resolver.ts";
+import type { SubagentService } from "../execution/subagent-service.ts";
+import type {
+  BgResponse,
+  CancelResponse,
+  ListResponse,
+  SubagentListItem,
+  SubagentRecord,
+  SubagentToolResult,
+} from "../execution/types.ts";
+import {
+  guiComponent,
+  type GuiContext,
+  guiResult,
+  isGuiCapable,
+} from "./gui-adapter.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** list 默认 limit。 */
+const DEFAULT_LIST_LIMIT = 20;
+/** list limit 上限。 */
+const MAX_LIST_LIMIT = 100;
+
+/** background 启动提示文案（spec FR-3 bgResponse.message）。 */
+const BG_MESSAGE = "detached, will notify on completion";
+
+// ============================================================
+// 入参 / 出参类型
+// ============================================================
+
+/** start 入参（从 tool params.startParam 来，task 必填）。 */
+export interface StartHandlerInput {
+  task?: string;
+  agent?: string;
+  model?: string;
+  thinkingLevel?: string;
+  skillPath?: string;
+  appendSystemPrompt?: string[];
+  schema?: Record<string, unknown>;
+  maxTurns?: number;
+  graceTurns?: number;
+  /** fork 模式：继承主 session 上下文（D-018 两级降级）。 */
+  fork?: boolean;
+  /** worktree 模式：文件系统隔离运行（D-008 tmpdir）。 */
+  worktree?: boolean;
+  /** 覆盖子 agent 工作目录（默认 mainCwd）。 */
+  cwd?: string;
+}
+
+/** start 领域对象（adapter 包成 bgResponse）。 */
+export type StartHandlerResult = {
+  kind: "bg";
+  subagentId: string;
+  sessionFile: string | undefined;
+  response: BgResponse;
+};
+
+export interface ListHandlerInput {
+  includeFinished?: boolean;
+  limit?: number;
+}
+
+/** list 领域对象（adapter 包成 listResponse，最外层 subagentId/sessionFile 为 null）。 */
+export interface ListHandlerResult {
+  response: ListResponse;
+}
+
+export interface CancelHandlerInput {
+  subagentId?: string;
+}
+
+/** cancel 领域对象（adapter 包成 cancelResponse）。 */
+export interface CancelHandlerResult {
+  subagentId: string;
+  response: CancelResponse;
+}
+
+// ============================================================
+// helpers（模块内）
+// ============================================================
+
+/**
+ * list 数据源（诚实声明 G3-003）：
+ * collectRecords(limit, statusFilter) 合并内存(running) + 磁盘(sessions/*.jsonl 重建)。
+ * 磁盘源天然跨 session 可见——/new /resume /fork 后前 session 的终态 record 仍在
+ * sessions 目录里（直到 30 天 GC）。内存源仅当前 session 的 running record。
+ * 不新增 sessionId 到 ExecutionRecord（YAGNI，修跨 session 清理是独立问题）。
+ */
+
+/** SubagentRecord → SubagentListItem（8 字段，duration 实时计算）。 */
+function recordToListItem(r: SubagentRecord): SubagentListItem {
+  return {
+    subagentId: r.id,
+    agent: r.agent,
+    status: r.status,
+    mode: r.mode,
+    duration: computeElapsedSeconds(r),
+    model: r.model,
+    totalTokens: r.totalTokens,
+    sessionFile: r.sessionFile,
+  };
+}
+
+// ============================================================
+// start handler
+// ============================================================
+
+export async function startHandler(
+  service: SubagentService,
+  input: StartHandlerInput | undefined,
+  signal: AbortSignal | undefined,
+  ctxModel?: ModelInfo,
+): Promise<StartHandlerResult> {
+  if (!input) throw new Error("startParam is required for action:'start'");
+  // task 必填 + 空白校验（G-008）
+  const task = input.task?.trim();
+  if (!task) throw new Error("startParam.task is required (and must not be whitespace-only)");
+
+  const handle = await service.execute({
+    task,
+    agent: input.agent,
+    model: input.model,
+    thinkingLevel: input.thinkingLevel,
+    skillPath: input.skillPath,
+    appendSystemPrompt: input.appendSystemPrompt,
+    schema: input.schema,
+    maxTurns: input.maxTurns,
+    graceTurns: input.graceTurns,
+    fork: input.fork,
+    worktree: input.worktree,
+    cwd: input.cwd,
+    ctxModel,
+    signal,
+    // background 不回流 onUpdate：detached 运行，完成由 notify 驱动新 turn。
+    onUpdate: undefined,
+  });
+
+  return {
+    kind: "bg",
+    subagentId: handle.subagentId,
+    sessionFile: handle.sessionFile,
+    response: {
+      status: "running",
+      mode: "background",
+      message: BG_MESSAGE,
+    },
+  };
+}
+
+// ============================================================
+// list handler
+// ============================================================
+
+export function listHandler(
+  service: SubagentService,
+  input: ListHandlerInput | undefined,
+): ListHandlerResult {
+  const includeFinished = input?.includeFinished === true;
+  // limit 夹紧：默认 20，范围 [1, 100]
+  const rawLimit = input?.limit ?? DEFAULT_LIST_LIMIT;
+  const limit = Math.max(1, Math.min(rawLimit, MAX_LIST_LIMIT));
+
+  // collectRecords 是 service 核心能力：statusFilter 决定 running-only 还是全部。
+  // 防截断（先多取再过滤）已下沉到 store 层——这里直接传 limit + filter。
+  const filter = includeFinished ? "all" : "running";
+  const all = service.collectRecords(limit, filter);
+  const items: SubagentListItem[] = all.map(recordToListItem);
+  const running = items.filter((i) => i.status === "running").length;
+
+  return { response: { running, items } };
+}
+
+// ============================================================
+// cancel handler
+// ============================================================
+
+export async function cancelHandler(
+  service: SubagentService,
+  input: CancelHandlerInput | undefined,
+): Promise<CancelHandlerResult> {
+  const id = input?.subagentId?.trim();
+  if (!id) throw new Error("cancelParam.subagentId is required for action:'cancel'");
+
+  // step 1: id 不存在（findRecord 只查内存 running record，不从 session.jsonl 重建）
+  const rec = service.findRecord(id);
+  if (!rec) throw new Error(`No subagent record with id "${id}"`);
+  // step 2: controller 检查（controller 为 undefined 表示 record 已终态或未启动）
+  if (rec.mode !== "background") {
+    throw new Error(`Cannot cancel subagent ${id} (unsupported mode: ${rec.mode})`);
+  }
+  // step 3: service.cancel boolean（list-view 契约不变）；false = 已终态（CAS 抢锁失败）。
+  // 注意：不嵌入 rec.status——findRecord 快照可能已过期（TOCTOU：cancel 期间 detached
+  // 路径 CAS 到 done/failed）。重新查当前状态，避免「status: running」与「already finished」矛盾。
+  if (!service.cancel(id)) {
+    // CAS 失败 = record 在 cancel 期间被 detached 路径 finalize（done/failed）。
+    // re-query 查当前真实状态。终态 record 被 archive 立即移出内存，
+    // 诚实报告 "unknown (evicted from memory)" 而非回落到可能过期的 rec.status（BL-3）。
+    const now = service.findRecord(id);
+    const statusDesc = now ? now.status : "unknown (evicted from memory)";
+    throw new Error(`Subagent ${id} could not be cancelled (it likely just finished; status: ${statusDesc})`);
+  }
+  return { subagentId: id, response: { cancelled: true } };
+}
+
+// ============================================================
+// adapter（领域对象 → SubagentToolResult + {content, details}）
+// ============================================================
+
+/**
+ * action ↔ domain 配对的承重类型（替代三处松散 `as`）。
+ * 调用方必须传匹配的 {action, domain}——TS 在调用点校验，错配编译报错。
+ */
+type AdapterInput =
+  | { action: "start"; domain: StartHandlerResult }
+  | { action: "list"; domain: ListHandlerResult }
+  | { action: "cancel"; domain: CancelHandlerResult };
+
+export function adapter(
+  input: AdapterInput,
+  ctx?: GuiContext,
+): AgentToolResult<SubagentToolResult> {
+  const { action } = input;
+  let result: SubagentToolResult;
+  if (action === "start") {
+    const d = input.domain;
+    result = { action, subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, bgResponse: d.response };
+  } else if (action === "list") {
+    result = { action, subagentId: null, sessionFile: null, listResponse: input.domain.response };
+  } else {
+    result = { action, subagentId: input.domain.subagentId, sessionFile: null, cancelResponse: input.domain.response };
+  }
+
+  // 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));
+  }
+
+  return {
+    content: [{ type: "text", text }],
+    details: details as unknown as SubagentToolResult,
+  };
+}
+
+/** 按 action 构造对应的 GuiComponent。 */
+function buildGuiComponent(
+  action: string,
+  input: AdapterInput,
+  _result: SubagentToolResult,
+) {
+  if (action === "start") {
+    return guiComponent("subagent-trace", {
+      agent: "subagent",
+      status: "running" as const,
+    });
+  }
+  if (action === "list") {
+    const listResp = input.domain as ListHandlerResult;
+    return guiComponent("task-list", {
+      title: `Subagents (${listResp.response.running} running)`,
+      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,
+      })),
+      summary: `${listResp.response.running}/${listResp.response.items.length} running`,
+    });
+  }
+  // cancel
+  return guiComponent("stats-line", {
+    items: [{ label: "cancelled", value: (input.domain as CancelHandlerResult).subagentId, severity: "warn" }],
+  });
+}

package/src/interface/subagent-tool.ts

@@ -0,0 +1,294 @@
+// src/interface/subagent-tool.ts
+//
+// `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。
+
+import type { Component } from "@earendil-works/pi-tui";
+import { StringEnum } from "@mariozechner/pi-ai";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+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 { adapter, cancelHandler, listHandler, startHandler } from "./subagent-actions.ts";
+import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
+
+// ============================================================
+// 回调类型（抽 alias 绕 registerTool(unknown) 的 TS2307 误报）
+// ============================================================
+
+/**
+ * execute 回调的 params 类型（手写副本——stub registerTool 是 unknown，
+ * 无法从 SubagentParams schema 反向推断参数类型）。
+ * action 与对应 param 不匹配时 handler 内 throw。
+ */
+interface StartParam {
+  task: string;
+  agent?: string;
+  model?: string;
+  thinkingLevel?: string;
+  skillPath?: string;
+  appendSystemPrompt?: string[];
+  schema?: Record<string, unknown>;
+  maxTurns?: number;
+  graceTurns?: number;
+  fork?: boolean;
+  worktree?: boolean;
+  cwd?: string;
+}
+
+interface ListParam {
+  includeFinished?: boolean;
+  limit?: number;
+}
+
+interface CancelParam {
+  subagentId: string;
+}
+
+interface SubagentExecuteParams {
+  action: "start" | "list" | "cancel";
+  startParam?: StartParam;
+  listParam?: ListParam;
+  cancelParam?: CancelParam;
+}
+
+type SubagentExecuteCb = (
+  toolCallId: string,
+  params: SubagentExecuteParams,
+  signal: AbortSignal | undefined,
+  onUpdate?: (partialResult: AgentToolResult<SubagentToolResult>) => void,
+  // ctx 在 SDK 契约里必填；此处保持 optional 以兼容 onUpdate? 在前（TS 参数顺序约束），
+  // 结构兼容——registerTool(unknown) 不校验，运行时 SDK 必传入。
+  ctx?: ExtensionContext,
+) => Promise<AgentToolResult<SubagentToolResult>>;
+
+type SubagentRenderCallCb = (args: unknown, theme: Theme, ctx: RenderContext) => Component;
+
+type SubagentRenderResultCb = (
+  result: AgentToolResult<SubagentToolResult>,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  ctx: RenderContext,
+) => Component;
+
+// ============================================================
+// Params schema
+// ============================================================
+
+/** Params schema（模块内消费，未导出）。 */
+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.",
+  }),
+  startParam: Type.Optional(Type.Object({
+    task: Type.String({
+      description: "The task for the subagent to execute (required for action:'start'). Whitespace-only is rejected.",
+    }),
+    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.',
+    })),
+    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.',
+    })),
+    thinkingLevel: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const)),
+    skillPath: Type.Optional(Type.String()),
+    appendSystemPrompt: Type.Optional(Type.Array(Type.String())),
+    schema: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    maxTurns: Type.Optional(Type.Number({
+      description: "Turn limit. The subagent is terminated via SIGTERM after maxTurns turn_end events + graceTurns of slack. There is no graceful wrap-up message — the process is killed. 0 or omitted = unlimited.",
+    })),
+    graceTurns: Type.Optional(Type.Number({
+      description: "Extra turns allowed after maxTurns is reached before SIGTERM (default 2). Only meaningful when maxTurns is set.",
+    })),
+    fork: Type.Optional(Type.Boolean({
+      description: "Fork mode: inherit the parent's conversation context. When true, the subagent receives the parent's session file via --fork and builds a branched conversation (it sees prior turns/messages). The subagent still runs in a separate spawned child process (process isolation) — fork is about context inheritance, not process sharing. Use worktree:true (requires fork:true) for file-system isolation.",
+    })),
+    worktree: Type.Optional(Type.Boolean({
+      description: "Worktree isolation (requires fork:true): run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session. Prevents concurrent file-write conflicts between parent and subagent. Only takes effect when fork:true; passing worktree:true without fork:true throws an error.",
+    })),
+    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.',
+    })),
+  })),
+  listParam: Type.Optional(Type.Object({
+    includeFinished: Type.Optional(Type.Boolean({
+      description: "Include finished (done/failed/cancelled) records. Default false (running only).",
+    })),
+    limit: Type.Optional(Type.Number({
+      description: "Max items to return. Default 20, clamped to [1, 100].",
+    })),
+  })),
+  cancelParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "The subagentId to cancel (required for action:'cancel'). Only background subagents can be cancelled.",
+    }),
+  })),
+});
+
+// ============================================================
+// renderCall 预解析 helper
+// ============================================================
+
+// extractAgentName 已上移到 ../tui/format.ts 共享（tool-render / subagent-tool 复用）。
+
+/** exhaustiveness 承重 helper：default 分支把 action 收敛为 never，新增 action 时 tsc 报错。 */
+function assertNever(value: never): string {
+  return String(value);
+}
+
+/** unknown 是否为含 model/thinkingLevel 的对象（类型守卫，替代全可选结构 `as`）。 */
+function isModelOverrideObj(a: unknown): a is { model?: unknown; thinkingLevel?: unknown } {
+  return typeof a === "object" && a !== null;
+}
+
+/** unknown args 是否含 startParam（类型守卫，替代 `in` 后的 `as`）。 */
+function hasStartParam(a: unknown): a is { startParam?: unknown } {
+  return typeof a === "object" && a !== null && "startParam" in a;
+}
+
+/** 从 unknown args 安全提取 model/thinkingLevel override（传给 resolveModel）。 */
+function extractModelOverride(args: unknown): { model?: string; thinkingLevel?: string } | undefined {
+  if (!isModelOverrideObj(args)) return undefined;
+  const override: { model?: string; thinkingLevel?: string } = {};
+  if (typeof args.model === "string" && args.model.length > 0) override.model = args.model;
+  if (typeof args.thinkingLevel === "string" && args.thinkingLevel.length > 0) override.thinkingLevel = args.thinkingLevel;
+  return Object.keys(override).length > 0 ? override : undefined;
+}
+
+// ============================================================
+// 注册
+// ============================================================
+
+/** 注册 `subagent` 工具。由工厂调用。 */
+export function registerSubagentTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "subagent",
+    label: "Subagent",
+    description: `Delegate a task to a specialized subagent via an explicit action.
+
+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).
+
+## Actions
+
+- 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.
+
+## After launching — do NOT wait
+
+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.
+
+## Calling patterns
+
+- 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.
+
+## Anti-patterns
+
+- Launching background, then sleeping/polling instead of working or stopping.
+
+## 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.`,
+    executionMode: "sequential",
+    parameters: SubagentParams,
+    renderCall: subagentRenderCall,
+    renderResult: subagentRenderResult,
+    execute: executeSubagent,
+  });
+}
+
+// ============================================================
+// 回调实现（模块级 const）
+// ============================================================
+
+// ponytail: renderCall 每次 TUI invalidate 都触发，同一解析错误会重复刷屏。
+// 按错误消息去重（Set），session 内只报第一次。错误消息含 modelStr，足够区分。
+const reportedRenderErrors = new Set<string>();
+
+const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
+  // 预解析 model（同步）：让标题行能显示 model/thinking，不必等 execute。
+  // resolveModel 三层：override → agentConfig.model → 主 agent model（session 缓存）。
+  // 主 agent model 由 ModelConfigService 缓存（session_start 注入，model_select 刷新），
+  // 补偿 renderCall 的 ToolRenderContext 不含 model 的 SDK 限制。
+  // service 未就绪 / 缓存为空 / 解析失败 → 降级不显示 model。
+  const startParam = hasStartParam(args) ? args.startParam : undefined;
+  const agent = extractAgentName(startParam);
+  const override = extractModelOverride(startParam);
+  let resolved: { model: string; thinkingLevel?: string } | undefined;
+  try {
+    const service = getSubagentService();
+    const r = service?.resolveModel(agent, override);
+    if (r) resolved = { model: `${r.model.provider}/${r.model.id}`, thinkingLevel: r.thinkingLevel };
+  } catch (err) {
+    // service 未注册 / modelRegistry 未注入 / 无可用 model → 降级不显示 model（renderCall 不应崩）。
+    // 去重：同一 err.message 只 console.debug 一次，避免 TUI invalidate 反复刷屏。
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!reportedRenderErrors.has(msg)) {
+      reportedRenderErrors.add(msg);
+      void err; // 显式确认忽略：renderCall 降级是设计意图，不阻断渲染
+      console.debug("[subagents] renderCall model resolution failed, degrading:", err);
+    }
+  }
+  return renderSubagentCall(args, theme, ctx, resolved);
+};
+
+const subagentRenderResult: SubagentRenderResultCb = (result, options, theme, ctx) =>
+  renderSubagentResult(result, options, theme, ctx);
+
+/**
+ * execute 实现（action 路由 + adapter）。
+ *
+ *   ╔══════════════════════════════════════════════════════════════════╗
+ *   ║  service = getSubagentService() —— 未初始化 throw                  ║
+ *   ║                                                                    ║
+ *   ║  switch(params.action):                                           ║
+ *   ║    "start"  → startHandler(service, params.startParam, signal) → 领域对象  ║
+ *   ║    "list"   → listHandler(service, params.listParam) → 领域对象    ║
+ *   ║    "cancel" → cancelHandler(service, params.cancelParam) → 领域对象║
+ *   ║                                                                    ║
+ *   ║  result = adapter(action, 领域对象)                                ║
+ *   ║  return { content: [{text: JSON.stringify(result)}], details: result }║
+ *   ╚══════════════════════════════════════════════════════════════════╝
+ *
+ * handler 返回纯领域对象（不碰 {content, details}），adapter 唯一包装。
+ * content（JSON 字符串）给 LLM，details（领域对象 + action）给 renderResult，同源。
+ */
+const executeSubagent: SubagentExecuteCb = async (
+  _toolCallId,
+  params,
+  signal,
+  _onUpdate,
+  _ctx,
+) => {
+  // background 模式：execute 立即返回，detached 运行不向 tool 层回流 onUpdate
+  //（完成由 notify 驱动新 turn）。onUpdate 参数保留以兼容 SDK 回调签名，但不消费。
+  const service = getSubagentService();
+  if (!service) throw new Error("subagents runtime not initialized");
+
+  switch (params.action) {
+    case "start":
+      return adapter({ action: "start", domain: await startHandler(service, params.startParam, signal, _ctx?.model) }, _ctx);
+    case "list":
+      return adapter({ action: "list", domain: listHandler(service, params.listParam) }, _ctx);
+    case "cancel":
+      return adapter({ action: "cancel", domain: await cancelHandler(service, params.cancelParam) }, _ctx);
+    default:
+      // assertNever：让 exhaustiveness 成为承重约束——新增 action 时 tsc 报错，
+      // 而非悄悄落入此分支。
+      throw new Error(`Unknown subagent action: ${assertNever(params.action)}`);
+  }
+};

package/src/interface/subagents.ts

@@ -0,0 +1,30 @@
+// src/commands/subagents.ts
+//
+// /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
+//
+// 解析：args[0] 直接作可选 <id>（聚焦该 record）。
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+
+import { getSubagentService } from "../execution/subagent-service.ts";
+import { createSubagentsView } from "./list-view.ts";
+
+/** 注册 /subagents 命令（= list overlay）。 */
+export function registerSubagentsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("subagents", {
+    description: "Subagents: /subagents [<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;
+      }
+      const args = argsStr.trim().split(/\s+/).filter(Boolean);
+      await createSubagentsView(service, ctx.ui.theme, ctx, args[0]);
+    },
+  });
+}