@maplezzk/pi-interactive-subagents 3.7.1

package/pi-extension/subagents/index.ts

@@ -0,0 +1,2248 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "@sinclair/typebox";
+import { Box, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  unlinkSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import {
+  createSurface,
+  sendLongCommand,
+  pollForExit,
+  closeSurface,
+  muxLog,
+  getMuxBackend,
+  isMuxAvailable,
+  sendEscape,
+  shellEscape,
+  renameCurrentTab,
+  renameWorkspace,
+  renameAgent,
+  readScreen,
+  getLastSplitSource,
+  clearLastSplitSource,
+} from "pi-terminal-mux";
+
+import {
+  findLastAssistantMessage,
+  getNewEntries,
+  seedSubagentSessionFile,
+} from "./session.ts";
+import {
+  type StatusSnapshot,
+  type SubagentStatusState,
+  advanceStatusState,
+  capStatusLines,
+  classifyStatus,
+  createStatusState,
+  forceStatusAfterInterrupt,
+  formatStatusAggregate,
+  formatTransitionLine,
+  observeStatus,
+  loadStatusConfig,
+} from "./status.ts";
+import {
+  getSubagentActivityFile,
+  readSubagentActivityFile,
+  type ActivityReadResult,
+  type SubagentActivityState,
+} from "./activity.ts";
+
+/** Absolute path to `pi-extension/subagents`. https://github.com/nodejs/node/issues/37845 */
+const SUBAGENTS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** 从 content 数组提取第一个 TextContent 的文本（若存在） */
+function extractFirstText(content: Array<{ type: string; text?: string }>): string {
+  const first = content[0];
+  return first && typeof first.text === "string" ? first.text : "";
+}
+
+/**
+ * 默认 subagent 模型。
+ *
+ * 解析优先级（高 → 低）：
+ *   1. 调用方传入的 `model` 参数（subagent tool 调用时显式指定）
+ *   2. agent 配置文件 frontmatter 里的 `model` 字段
+ *   3. 环境变量 PI_SUBAGENT_DEFAULT_MODEL
+ *   4. undefined — 不传 --model，子 pi 继承父 session 的默认模型
+ */
+function getDefaultSubagentModel(): string | undefined {
+  return process.env.PI_SUBAGENT_DEFAULT_MODEL?.trim() || undefined;
+}
+
+// Survive /reload: clear timers and abort poll loops from the previous module load.
+// /reload re-imports this file, giving fresh module-level state, but closures from
+// the old module keep running. See https://github.com/HazAT/pi-interactive-subagents/issues/5
+const WIDGET_INTERVAL_KEY = Symbol.for("pi-subagents/widget-interval");
+const STATUS_INTERVAL_KEY = Symbol.for("pi-subagents/status-interval");
+const POLL_ABORT_KEY = Symbol.for("pi-subagents/poll-abort-controller");
+
+{
+  const prevInterval = (globalThis as any)[WIDGET_INTERVAL_KEY];
+  if (prevInterval) {
+    clearInterval(prevInterval);
+    (globalThis as any)[WIDGET_INTERVAL_KEY] = null;
+  }
+  const prevStatusInterval = (globalThis as any)[STATUS_INTERVAL_KEY];
+  if (prevStatusInterval) {
+    clearInterval(prevStatusInterval);
+    (globalThis as any)[STATUS_INTERVAL_KEY] = null;
+  }
+  const prevAbort = (globalThis as any)[POLL_ABORT_KEY] as AbortController | undefined;
+  if (prevAbort) prevAbort.abort();
+  (globalThis as any)[POLL_ABORT_KEY] = new AbortController();
+}
+
+function getModuleAbortSignal(): AbortSignal {
+  // 自愈：若 controller 已被 abort（session_shutdown 会调 abort 但不重置），
+  // 自动重建一个新 controller，避免下一次 watchSubagent 拿到 aborted signal
+  // 导致 pollForExit 第一行 throw "Aborted while waiting..."、子 pi 来不及启动
+  // 就被 close。现象：pane run 后 ~0ms pane close、无任何 pane read 轮询日志、
+  // workflow 报 "subagent never actually started"。
+  const existing = (globalThis as any)[POLL_ABORT_KEY] as AbortController | undefined;
+  if (!existing || existing.signal.aborted) {
+    const fresh = new AbortController();
+    (globalThis as any)[POLL_ABORT_KEY] = fresh;
+    muxLog(`[getModuleAbortSignal] self-healed: ${existing ? "was aborted" : "missing"} → created new controller\n`);
+    return fresh.signal;
+  }
+  return existing.signal;
+}
+
+const SubagentParams = Type.Object({
+  name: Type.String({ description: "Display name for the subagent" }),
+  task: Type.String({ description: "Task/prompt for the sub-agent" }),
+  agent: Type.Optional(
+    Type.String({
+      description:
+        "Agent name to load defaults from (e.g. 'worker', 'scout', 'reviewer'). Reads ~/.pi/agent/agents/<name>.md for model, tools, skills.",
+    }),
+  ),
+  systemPrompt: Type.Optional(
+    Type.String({ description: "Appended to system prompt (role instructions)" }),
+  ),
+  model: Type.Optional(Type.String({ description: "Model override (overrides agent default)" })),
+  skills: Type.Optional(
+    Type.String({ description: "Comma-separated skills (overrides agent default)" }),
+  ),
+  tools: Type.Optional(
+    Type.String({ description: "Comma-separated tools (overrides agent default)" }),
+  ),
+  cwd: Type.Optional(
+    Type.String({
+      description:
+        "Working directory for the sub-agent. The agent starts in this folder and picks up its local .pi/ config, CLAUDE.md, skills, and extensions. Use for role-specific subfolders.",
+    }),
+  ),
+  fork: Type.Optional(
+    Type.Boolean({
+      description:
+        "Force the full-context fork mode for this spawn. The sub-agent inherits the current session conversation, overriding any agent frontmatter session-mode.",
+    }),
+  ),
+  interactive: Type.Optional(
+    Type.Boolean({
+      description:
+        "Mark the subagent as interactive (long-running, user drives the conversation in its own pane). When true, the main session is not woken by status transitions (stalled/recovered) for this subagent. If omitted, falls back to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit` (agents that auto-exit are autonomous and get stall pings; agents that don't are interactive and stay quiet).",
+    }),
+  ),
+  resumeSessionId: Type.Optional(
+    Type.String({
+      description:
+        "Resume a previous Claude Code session by its ID. Loads the conversation history and continues where it left off. The session ID is returned in details of every claude tool call. Use this to retry cancelled runs or ask follow-up questions.",
+    }),
+  ),
+  structuredOutputSchema: Type.Optional(
+    // 用带 type:"object" 的定义，避免 Type.Any 无 type 导致 LLM 把对象
+    // 序列化成字符串（进而触发子进程 ajv.compile(字符串) 崩
+    // "schema must be object or boolean"）。
+    Type.Object(
+      {},
+      {
+        additionalProperties: true,
+        description:
+          "Optional JSON Schema object. When set, the sub-agent will be provisioned with a structured_output tool that validates its final arguments against this schema before returning. On validation failure the sub-agent sees the errors and can retry; on success the validated value is delivered via the .exit sidecar file.",
+      },
+    ),
+  ),
+});
+
+type SubagentSessionMode = "standalone" | "lineage-only" | "fork";
+
+interface AgentDefaults {
+  model?: string;
+  tools?: string;
+  skills?: string;
+  thinking?: string;
+  denyTools?: string;
+  spawning?: boolean;
+  autoExit?: boolean;
+  interactive?: boolean;
+  systemPromptMode?: "append" | "replace";
+  sessionMode?: SubagentSessionMode;
+  cwd?: string;
+  cli?: string;
+  body?: string;
+  disableModelInvocation?: boolean;
+}
+
+type AgentSource = "package" | "global" | "project";
+
+interface AgentDefinition extends AgentDefaults {
+  name: string;
+  description?: string;
+  disableModelInvocation: boolean;
+}
+
+interface ListedAgentDefinition extends AgentDefinition {
+  source: AgentSource;
+}
+
+/** Tools that are gated by `spawning: false` */
+const SPAWNING_TOOLS = new Set([
+  "subagent",
+  "subagent_interrupt",
+  "subagents_list",
+  "subagent_resume",
+]);
+
+/**
+ * Resolve the effective set of denied tool names from agent defaults.
+ * `spawning: false` expands to all SPAWNING_TOOLS.
+ * `deny-tools` adds individual tool names on top.
+ */
+function resolveDenyTools(agentDefs: AgentDefaults | null): Set<string> {
+  const denied = new Set<string>();
+  if (!agentDefs) return denied;
+
+  // spawning: false → deny all spawning tools
+  if (agentDefs.spawning === false) {
+    for (const t of SPAWNING_TOOLS) denied.add(t);
+  }
+
+  // deny-tools: explicit list
+  if (agentDefs.denyTools) {
+    for (const t of agentDefs.denyTools
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean)) {
+      denied.add(t);
+    }
+  }
+
+  return denied;
+}
+
+/** Resolve the global agent config directory, respecting PI_CODING_AGENT_DIR. */
+function getAgentConfigDir(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+function getBundledAgentsDir(): string {
+  return join(SUBAGENTS_DIR, "../../agents");
+}
+
+function getFrontmatterValue(frontmatter: string, key: string): string | undefined {
+  const match = frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+  return match ? match[1].trim() : undefined;
+}
+
+function parseOptionalBoolean(value: string | undefined): boolean | undefined {
+  return value != null ? value === "true" : undefined;
+}
+
+function parseSessionMode(value: string | undefined): SubagentSessionMode | undefined {
+  if (value === "standalone" || value === "lineage-only" || value === "fork") {
+    return value;
+  }
+  return undefined;
+}
+
+function parseAgentDefinition(content: string, fallbackName: string): AgentDefinition | null {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const frontmatter = match[1];
+  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "").trim();
+  const systemPromptMode = getFrontmatterValue(frontmatter, "system-prompt");
+
+  return {
+    name: getFrontmatterValue(frontmatter, "name") ?? fallbackName,
+    description: getFrontmatterValue(frontmatter, "description"),
+    model: getFrontmatterValue(frontmatter, "model"),
+    tools: getFrontmatterValue(frontmatter, "tools"),
+    systemPromptMode:
+      systemPromptMode === "replace"
+        ? "replace"
+        : systemPromptMode === "append"
+          ? "append"
+          : undefined,
+    skills: getFrontmatterValue(frontmatter, "skill") ?? getFrontmatterValue(frontmatter, "skills"),
+    thinking: getFrontmatterValue(frontmatter, "thinking"),
+    denyTools: getFrontmatterValue(frontmatter, "deny-tools"),
+    spawning: parseOptionalBoolean(getFrontmatterValue(frontmatter, "spawning")),
+    autoExit: parseOptionalBoolean(getFrontmatterValue(frontmatter, "auto-exit")),
+    interactive: parseOptionalBoolean(getFrontmatterValue(frontmatter, "interactive")),
+    sessionMode: parseSessionMode(getFrontmatterValue(frontmatter, "session-mode")),
+    cwd: getFrontmatterValue(frontmatter, "cwd"),
+    cli: getFrontmatterValue(frontmatter, "cli"),
+    body: body || undefined,
+    disableModelInvocation:
+      getFrontmatterValue(frontmatter, "disable-model-invocation")?.toLowerCase() === "true",
+  };
+}
+
+function discoverAgentDefinitions(): ListedAgentDefinition[] {
+  const agents = new Map<string, ListedAgentDefinition>();
+  const dirs: Array<{ path: string; source: AgentSource }> = [
+    { path: getBundledAgentsDir(), source: "package" },
+    { path: join(getAgentConfigDir(), "agents"), source: "global" },
+    { path: join(process.cwd(), ".pi", "agents"), source: "project" },
+  ];
+
+  for (const { path: dir, source } of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir).filter((entry) => entry.endsWith(".md"))) {
+      const parsed = parseAgentDefinition(
+        readFileSync(join(dir, file), "utf8"),
+        file.replace(/\.md$/, ""),
+      );
+      if (!parsed) continue;
+      agents.set(parsed.name, { ...parsed, source });
+    }
+  }
+
+  return [...agents.values()];
+}
+
+function resolveSubagentPaths(
+  params: Static<typeof SubagentParams>,
+  agentDefs: AgentDefaults | null,
+): { effectiveCwd: string | null; localAgentDir: string | null; effectiveAgentDir: string } {
+  const rawCwd = params.cwd ?? agentDefs?.cwd ?? null;
+  const cwdIsFromAgent = !params.cwd && agentDefs?.cwd != null;
+  const cwdBase = cwdIsFromAgent ? getAgentConfigDir() : process.cwd();
+  const effectiveCwd = rawCwd
+    ? rawCwd.startsWith("/")
+      ? rawCwd
+      : join(cwdBase, rawCwd)
+    : null;
+  const localAgentDir = effectiveCwd ? join(effectiveCwd, ".pi", "agent") : null;
+  const effectiveAgentDir =
+    localAgentDir && existsSync(localAgentDir) ? localAgentDir : getAgentConfigDir();
+  return { effectiveCwd, localAgentDir, effectiveAgentDir };
+}
+
+function getDefaultSessionDirFor(cwd: string, _agentDir: string): string {
+  const safePath = `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+  const sessionDir = join(homedir(), ".pi", "subagent-sessions", safePath);
+  if (!existsSync(sessionDir)) {
+    mkdirSync(sessionDir, { recursive: true });
+  }
+  return sessionDir;
+}
+
+function resolveEffectiveSessionMode(
+  params: Static<typeof SubagentParams>,
+  agentDefs: AgentDefaults | null,
+): SubagentSessionMode {
+  if (params.fork) return "fork";
+  return agentDefs?.sessionMode ?? "standalone";
+}
+
+function resolveLaunchBehavior(
+  params: Static<typeof SubagentParams>,
+  agentDefs: AgentDefaults | null,
+): {
+  sessionMode: SubagentSessionMode;
+  seededSessionMode: "lineage-only" | "fork" | null;
+  inheritsConversationContext: boolean;
+  taskDelivery: "direct" | "artifact";
+} {
+  const sessionMode = resolveEffectiveSessionMode(params, agentDefs);
+  const inheritsConversationContext = sessionMode === "fork";
+  return {
+    sessionMode,
+    seededSessionMode: sessionMode === "standalone" ? null : sessionMode,
+    inheritsConversationContext,
+    taskDelivery: inheritsConversationContext ? "direct" : "artifact",
+  };
+}
+
+/**
+ * Decide whether a subagent is interactive (user-driven, long-running).
+ *
+ * Resolution order:
+ *   1. Explicit `interactive` tool parameter wins.
+ *   2. Explicit `interactive` frontmatter field on the agent.
+ *   3. Default: the inverse of `auto-exit`. Agents that auto-exit are
+ *      autonomous (scout, worker, reviewer) and the parent session should be
+ *      woken on stall/recovery transitions. Agents that don't auto-exit are
+ *      driven by the user in their own pane (planner, iterate/fork) and
+ *      stall pings are noise.
+ *
+ * When no agent defs exist at all (bare `subagent({ name, task })` call,
+ * typical for `/iterate` with `fork: true`), `autoExit` is undefined and the
+ * subagent is treated as interactive — matching the intent of iterate.
+ */
+function resolveEffectiveInteractive(
+  params: Static<typeof SubagentParams>,
+  agentDefs: AgentDefaults | null,
+): boolean {
+  if (params.interactive != null) return params.interactive;
+  if (agentDefs?.interactive != null) return agentDefs.interactive;
+  return !(agentDefs?.autoExit ?? false);
+}
+
+function loadAgentDefaults(agentName: string): AgentDefaults | null {
+  const configDir = getAgentConfigDir();
+  const paths = [
+    join(process.cwd(), ".pi", "agents", `${agentName}.md`),
+    join(configDir, "agents", `${agentName}.md`),
+    join(getBundledAgentsDir(), `${agentName}.md`),
+  ];
+
+  for (const p of paths) {
+    if (!existsSync(p)) continue;
+    const parsed = parseAgentDefinition(readFileSync(p, "utf8"), agentName);
+    if (parsed) return parsed;
+  }
+
+  return null;
+}
+
+function formatElapsed(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return `${m}m ${s}s`;
+}
+
+/**
+ * Wait long enough for a freshly created pane to finish shell startup.
+ *
+ * Some environments do extra shell-init work before the prompt is ready
+ * (for example direnv/devenv), so the delay is configurable for users who hit
+ * dropped commands. Keep the historical default at 500ms.
+ */
+function getShellReadyDelayMs(): number {
+  const raw = process.env.PI_SUBAGENT_SHELL_READY_DELAY_MS?.trim();
+  const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 500;
+}
+
+/**
+ * Build the internal artifact directory path for the current session.
+ * Used by the subagents extension to stash task files, system prompts, and
+ * launch scripts for sub-agents. Path convention:
+ *   <sessionDir>/artifacts/<session-id>/
+ */
+function getArtifactDir(sessionDir: string, sessionId: string): string {
+  return join(sessionDir, "artifacts", sessionId);
+}
+
+const statusConfig = loadStatusConfig();
+
+function formatWidgetRightLabel(snapshot: StatusSnapshot): string {
+  if (snapshot.kind === "starting") return " starting… ";
+  if (snapshot.kind === "running") return ` running ${snapshot.elapsedText} `;
+  if (snapshot.kind === "active") {
+    const label = snapshot.activityLabel ?? snapshot.activeScope;
+    const duration = snapshot.activeDurationText ? ` ${snapshot.activeDurationText}` : "";
+    return label ? ` active · ${label}${duration} ` : " active ";
+  }
+  if (snapshot.kind === "waiting") {
+    const duration = snapshot.waitingDurationText ? ` ${snapshot.waitingDurationText}` : "";
+    const detail = snapshot.statusLabel ? ` · ${snapshot.statusLabel}` : "";
+    return ` waiting${duration}${detail} `;
+  }
+
+  const detail = snapshot.statusLabel ? ` · ${snapshot.statusLabel}` : "";
+  const duration = snapshot.snapshotProblemText ? ` ${snapshot.snapshotProblemText}` : "";
+  return ` stalled${detail}${duration} `;
+}
+
+function resolveResultPresentation(
+  result: Pick<SubagentResult, "exitCode" | "elapsed" | "summary" | "sessionFile">,
+  name: string,
+): string {
+  const sessionRef = result.sessionFile
+    ? `\n\nSession: ${result.sessionFile}\nResume: pi --session ${result.sessionFile}`
+    : "";
+
+  return result.exitCode !== 0
+    ? `Sub-agent "${name}" failed (exit code ${result.exitCode}).\n\n${result.summary}${sessionRef}`
+    : `Sub-agent "${name}" completed (${formatElapsed(result.elapsed)}).\n\n${result.summary}${sessionRef}`;
+}
+
+/**
+ * Result from running a single subagent.
+ */
+interface SubagentResult {
+  name: string;
+  task: string;
+  summary: string;
+  sessionFile?: string;
+  claudeSessionId?: string;
+  exitCode: number;
+  elapsed: number;
+  error?: string;
+  ping?: { name: string; message: string };
+  /** Validated structured output (when subagent called structured_output tool) */
+  structuredOutput?: unknown;
+}
+
+/**
+ * State for a launched (but not yet completed) subagent.
+ */
+interface RunningSubagent {
+  id: string;
+  name: string;
+  task: string;
+  agent?: string;
+  surface: string;
+  startTime: number;
+  sessionFile: string;
+  launchScriptFile?: string;
+  activityFile?: string;
+  activity?: SubagentActivityState;
+  activityRead?: {
+    ok: boolean;
+    reason?: "missing" | "invalid" | "wrong-id";
+    error?: string;
+  };
+  abortController?: AbortController;
+  cli?: string;
+  sentinelFile?: string;
+  statusState: SubagentStatusState;
+  /**
+   * When true, status transitions (stalled/recovered) do not wake the parent
+   * session via a steer message. The widget still updates locally. Used for
+   * long-running agents where the user drives the conversation in the
+   * subagent's pane (e.g. planner).
+   */
+  interactive: boolean;
+  /** 新分屏的来源 pane ID，用于在 TUI 中展示 */
+  splitFrom?: string;
+}
+
+/** All currently running subagents, keyed by id. */
+const runningSubagents = new Map<string, RunningSubagent>();
+
+// ── Widget management ──
+
+/** Latest ExtensionContext from session_start, used for widget updates. */
+let latestCtx: ExtensionContext | null = null;
+
+/** Interval timer for widget re-renders. */
+let widgetInterval: ReturnType<typeof setInterval> | null = null;
+
+/** Interval timer for status transition checks. */
+let statusInterval: ReturnType<typeof setInterval> | null = null;
+
+function formatElapsedMMSS(startTime: number): string {
+  const seconds = Math.floor((Date.now() - startTime) / 1000);
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+}
+
+const ACCENT = "\x1b[38;2;77;163;255m";
+const RST = "\x1b[0m";
+
+/**
+ * Build a bordered content line: │left          right│
+ * Left content is truncated if needed, right is preserved, padded to fill width.
+ */
+function borderLine(left: string, right: string, width: number): string {
+  if (width <= 0) return "";
+  if (width === 1) return `${ACCENT}│${RST}`;
+
+  // width = total visible chars for the whole line including │ and │
+  const contentWidth = Math.max(0, width - 2); // space inside the two │ chars
+  const rightVis = visibleWidth(right);
+
+  // If the status chunk alone is too wide, prefer preserving it in compact form
+  // rather than overflowing the terminal.
+  if (rightVis >= contentWidth) {
+    const truncRight = truncateToWidth(right, contentWidth);
+    const rightPad = Math.max(0, contentWidth - visibleWidth(truncRight));
+    return `${ACCENT}│${RST}${truncRight}${" ".repeat(rightPad)}${ACCENT}│${RST}`;
+  }
+
+  const maxLeft = Math.max(0, contentWidth - rightVis);
+  const truncLeft = truncateToWidth(left, maxLeft);
+  const leftVis = visibleWidth(truncLeft);
+  const pad = Math.max(0, contentWidth - leftVis - rightVis);
+  return `${ACCENT}│${RST}${truncLeft}${" ".repeat(pad)}${right}${ACCENT}│${RST}`;
+}
+
+/**
+ * Build the bordered top line: ╭─ Title ──── info ─╮
+ * All chars are accounted for within `width`.
+ */
+function borderTop(title: string, info: string, width: number): string {
+  if (width <= 0) return "";
+  if (width === 1) return `${ACCENT}╭${RST}`;
+
+  // ╭─ Title ───...─── info ─╮
+  // overhead: ╭─ (2) + space around title (2) + space around info (2) + ─╮ (2) = but we simplify
+  const inner = Math.max(0, width - 2); // inside ╭ and ╮
+  const titlePart = `─ ${title} `;
+  const infoPart = ` ${info} ─`;
+  const fillLen = Math.max(0, inner - titlePart.length - infoPart.length);
+  const fill = "─".repeat(fillLen);
+  const content = `${titlePart}${fill}${infoPart}`.slice(0, inner).padEnd(inner, "─");
+  return `${ACCENT}╭${content}╮${RST}`;
+}
+
+/**
+ * Build the bordered bottom line: ╰──────────────────╯
+ */
+function borderBottom(width: number): string {
+  if (width <= 0) return "";
+  if (width === 1) return `${ACCENT}╰${RST}`;
+
+  const inner = Math.max(0, width - 2);
+  return `${ACCENT}╰${"─".repeat(inner)}╯${RST}`;
+}
+
+function renderSubagentWidgetLines(agents: RunningSubagent[], width: number): string[] {
+  const count = agents.length;
+  const title = "Subagents";
+  const info = `${count} running`;
+
+  const lines: string[] = [borderTop(title, info, width)];
+
+  for (const agent of agents) {
+    const elapsed = formatElapsedMMSS(agent.startTime);
+    const agentTag = agent.agent ? ` (${agent.agent})` : "";
+    const left = ` ${elapsed}  ${agent.name}${agentTag} `;
+    const snapshot = classifyStatus(agent.statusState, Date.now());
+    const right = statusConfig.enabled
+      ? formatWidgetRightLabel(snapshot)
+      : agent.cli === "claude"
+        ? " running… "
+        : " starting… ";
+
+    lines.push(borderLine(left, right, width));
+  }
+
+  lines.push(borderBottom(width));
+  return lines;
+}
+
+function updateWidget() {
+  if (!latestCtx?.hasUI) return;
+
+  if (runningSubagents.size === 0) {
+    latestCtx.ui.setWidget("subagent-status", undefined);
+    if (widgetInterval) {
+      clearInterval(widgetInterval);
+      widgetInterval = null;
+      (globalThis as any)[WIDGET_INTERVAL_KEY] = null;
+    }
+    return;
+  }
+
+  latestCtx.ui.setWidget(
+    "subagent-status",
+    (_tui: any, _theme: any) => {
+      return {
+        invalidate() {},
+        render(width: number) {
+          return renderSubagentWidgetLines(Array.from(runningSubagents.values()), width);
+        },
+      };
+    },
+    { placement: "aboveEditor" },
+  );
+}
+
+/**
+ * Build the positional prompt args for a Pi CLI subagent launch.
+ *
+ * In artifact-backed launches (lineage-only, standalone), Pi's buildInitialMessage()
+ * concatenates @file content with messages[0] into one initial prompt. That breaks
+ * /skill: expansion because the message no longer starts with "/skill:". Only
+ * messages[1..] are sent as separate follow-up prompts where /skill: is recognized.
+ *
+ * When there are skill prompts AND artifact-backed delivery, we prepend an empty
+ * first positional message so that /skill: args land in messages[1..] and arrive
+ * as standalone prompts in the child session.
+ */
+const SUBAGENT_CONTROL_TOOLS = ["caller_ping", "subagent_done"] as const;
+
+/**
+ * Build the child --tools allowlist.
+ *
+ * Pi 0.70+ applies --tools to built-in, extension, and custom tools. If a
+ * subagent definition restricts tools to e.g. "read,bash,write", the child
+ * control tools from subagent-done.ts would otherwise be hidden, leaving a
+ * manually resumed or user-touched subagent unable to call subagent_done.
+ */
+function buildSubagentToolAllowlist(effectiveTools?: string): string | null {
+  const requested = (effectiveTools ?? "")
+    .split(",")
+    .map((tool) => tool.trim())
+    .filter(Boolean);
+
+  if (requested.length === 0) return null;
+
+  const allow = new Set(requested);
+  for (const tool of SUBAGENT_CONTROL_TOOLS) {
+    allow.add(tool);
+  }
+
+  return [...allow].join(",");
+}
+
+function buildPiPromptArgs(params: {
+  effectiveSkills?: string;
+  taskDelivery: "direct" | "artifact";
+  taskArg: string;
+}): string[] {
+  const skillPrompts = (params.effectiveSkills ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((skill) => `/skill:${skill}`);
+
+  const needsSeparator = params.taskDelivery === "artifact" && skillPrompts.length > 0;
+
+  return [
+    ...(needsSeparator ? [""] : []),
+    ...skillPrompts,
+    params.taskArg,
+  ];
+}
+
+function activityLabel(activity: SubagentActivityState): string | undefined {
+  if (activity.phase !== "active") return undefined;
+  if (activity.activeScope === "tool") return activity.toolName ?? "tool";
+  if (activity.activeScope === "provider") return "provider";
+  if (activity.activeScope === "streaming") return "streaming";
+  return activity.activeScope;
+}
+
+/** 类型守卫：判别联合在 strictNullChecks 关闭时控制流收窄失效，用 predicate 强制收窄到失败分支。 */
+function isReadFailure(
+  r: ActivityReadResult,
+): r is { ok: false; reason: "missing" | "invalid" | "wrong-id"; error?: string } {
+  return !r.ok;
+}
+
+function observeRunningSubagent(running: RunningSubagent, observedAt = Date.now()) {
+  if (running.cli === "claude") return;
+
+  const activityFile = running.activityFile;
+  const read: ActivityReadResult = activityFile
+    ? readSubagentActivityFile(activityFile, running.id)
+    : { ok: false, reason: "missing" };
+
+  if (!isReadFailure(read)) {
+    running.activityRead = { ok: true };
+    running.activity = read.activity;
+    running.statusState = observeStatus(running.statusState, {
+      snapshot: "present",
+      updatedAt: read.activity.updatedAt,
+      sequence: read.activity.sequence,
+      phase: read.activity.phase,
+      active: read.activity.phase === "active",
+      activeScope: read.activity.activeScope,
+      activeSince: read.activity.activeSince,
+      waitingSince: read.activity.waitingSince,
+      latestEvent: read.activity.latestEvent,
+      activityLabel: activityLabel(read.activity),
+    }, observedAt);
+  } else {
+    running.activityRead = { ok: false, reason: read.reason, error: read.error };
+    running.statusState = observeStatus(running.statusState, {
+      snapshot: read.reason,
+      snapshotError: read.error,
+    }, observedAt);
+  }
+}
+
+function resolveInterruptTarget(params: { id?: string; name?: string }):
+  | { running: RunningSubagent }
+  | { error: string } {
+  const requestedId = params.id?.trim();
+  if (requestedId) {
+    const running = runningSubagents.get(requestedId);
+    return running ? { running } : { error: `No running subagent with id "${requestedId}".` };
+  }
+
+  const requestedName = params.name?.trim();
+  if (!requestedName) {
+    return { error: "Provide a running subagent id or exact display name." };
+  }
+
+  const matches = Array.from(runningSubagents.values()).filter((running) => running.name === requestedName);
+  if (matches.length === 1) return { running: matches[0] };
+  if (matches.length === 0) {
+    return { error: `No running subagent named "${requestedName}".` };
+  }
+
+  const candidates = matches.map((running) => `${running.name} [${running.id}]`).join(", ");
+  return { error: `Ambiguous subagent name "${requestedName}". Matches: ${candidates}` };
+}
+
+function requestSubagentInterrupt(
+  running: RunningSubagent,
+  sendEscapeKey: (surface: string) => void = sendEscape,
+): { ok: true } | { error: string } {
+  try {
+    sendEscapeKey(running.surface);
+    return { ok: true };
+  } catch (error: any) {
+    const backend = getMuxBackend() ?? "unknown";
+    return {
+      error:
+        `Failed to send Escape to subagent "${running.name}" via ${backend}: ` +
+        `${error?.message ?? String(error)}`,
+    };
+  }
+}
+
+interface InterruptResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: { error?: string; id?: string; name?: string; status?: string };
+}
+
+function handleSubagentInterrupt(
+  params: { id?: string; name?: string },
+  sendEscapeKey: (surface: string) => void = sendEscape,
+): InterruptResult {
+  const resolved = resolveInterruptTarget(params);
+  if ("error" in resolved) {
+    return {
+      content: [{ type: "text" as const, text: resolved.error }],
+      details: { error: resolved.error },
+    };
+  }
+
+  const running = resolved.running;
+  if (running.cli === "claude") {
+    return {
+      content: [{
+        type: "text" as const,
+        text:
+          "Turn-only Escape interrupt is currently supported only for Pi-backed subagents. Claude-backed semantics have not been verified yet.",
+      }],
+      details: { error: "claude interrupt unsupported", id: running.id, name: running.name },
+    };
+  }
+
+  const now = Date.now();
+  observeRunningSubagent(running, now);
+
+  const interruption = requestSubagentInterrupt(running, sendEscapeKey);
+  if ("error" in interruption) {
+    return {
+      content: [{ type: "text" as const, text: interruption.error }],
+      details: { error: interruption.error, id: running.id, name: running.name },
+    };
+  }
+
+  running.statusState = forceStatusAfterInterrupt(running.statusState, now);
+  updateWidget();
+
+  // After aborting the current generation, also signal done so the subagent
+  // properly finishes (parent's pollForExit detects the .exit file and
+  // returns the result).
+  if (running.sessionFile) {
+    const exitFile = `${running.sessionFile}.exit`;
+    try {
+      writeFileSync(exitFile, JSON.stringify({ type: "done" }));
+    } catch (writeErr: any) {
+      process.stderr.write(
+        `[interrupt] .exit 写入失败 file=${exitFile} err=${writeErr?.message ?? String(writeErr)}\n`,
+      );
+    }
+  }
+
+  return {
+    content: [{ type: "text" as const, text: `Interrupt requested for subagent "${running.name}".` }],
+    details: { id: running.id, name: running.name, status: "interrupt_requested" },
+  };
+}
+
+function startStatusRefresh(pi: ExtensionAPI) {
+  if (!statusConfig.enabled || statusInterval) return;
+
+  statusInterval = setInterval(() => {
+    if (runningSubagents.size === 0) {
+      if (statusInterval) {
+        clearInterval(statusInterval);
+        statusInterval = null;
+        (globalThis as any)[STATUS_INTERVAL_KEY] = null;
+      }
+      return;
+    }
+
+    const transitionLines: string[] = [];
+    const now = Date.now();
+    let shouldRefreshWidget = false;
+
+    for (const running of runningSubagents.values()) {
+      observeRunningSubagent(running, now);
+      const { nextState, snapshot, transition } = advanceStatusState(running.statusState, now);
+      if (nextState.currentKind !== running.statusState.currentKind) {
+        shouldRefreshWidget = true;
+      }
+      running.statusState = nextState;
+
+      // Interactive subagents (long-running, user-driven) intentionally don't
+      // wake the parent session on stalled/recovered transitions — the user is
+      // working in the subagent's pane, and a steer message here would burn an
+      // orchestrator turn on a no-op "still waiting" ping. Widget still updates.
+      if (transition && !running.interactive) {
+        transitionLines.push(formatTransitionLine(running.name, snapshot, transition));
+      }
+    }
+
+    if (shouldRefreshWidget) updateWidget();
+
+    if (transitionLines.length > 0) {
+      const capped = capStatusLines(transitionLines, statusConfig.lineLimit);
+      pi.sendMessage(
+        {
+          customType: "subagent_status",
+          content: formatStatusAggregate(transitionLines, statusConfig.lineLimit),
+          display: true,
+          details: { lines: capped.visibleLines, overflow: capped.overflow },
+        },
+        { triggerTurn: true, deliverAs: "steer" },
+      );
+    }
+  }, 1000);
+
+  (globalThis as any)[STATUS_INTERVAL_KEY] = statusInterval;
+}
+
+function resolveResumeLaunchBehavior(params: { autoExit?: boolean }): { autoExit: boolean; interactive: boolean } {
+  const autoExit = params.autoExit ?? true;
+  return { autoExit, interactive: !autoExit };
+}
+
+export const __test__ = {
+  borderLine,
+  getShellReadyDelayMs,
+  renderSubagentWidgetLines,
+  loadAgentDefaults,
+  discoverAgentDefinitions,
+  resolveEffectiveSessionMode,
+  resolveLaunchBehavior,
+  resolveEffectiveInteractive,
+  buildSubagentToolAllowlist,
+  buildPiPromptArgs,
+  formatWidgetRightLabel,
+  observeRunningSubagent,
+  resolveDenyTools,
+  resolveInterruptTarget,
+  requestSubagentInterrupt,
+  handleSubagentInterrupt,
+  resolveResultPresentation,
+  resolveResumeLaunchBehavior,
+  runningSubagents,
+};
+
+function startWidgetRefresh() {
+  if (widgetInterval) return;
+  updateWidget(); // immediate first render
+  widgetInterval = setInterval(() => {
+    updateWidget();
+  }, 1000);
+  (globalThis as any)[WIDGET_INTERVAL_KEY] = widgetInterval;
+}
+
+/**
+ * Launch a subagent: creates the multiplexer pane, builds the command, and
+ * sends it. Returns a RunningSubagent — does NOT poll.
+ *
+ * Call watchSubagent() on the returned object to observe completion.
+ */
+async function launchSubagent(
+  params: typeof SubagentParams.static,
+  ctx: { sessionManager: { getSessionFile(): string | null; getSessionId(): string; getSessionDir(): string }; cwd: string },
+  options?: { surface?: string },
+): Promise<RunningSubagent> {
+  const startTime = Date.now();
+  const id = Math.random().toString(16).slice(2, 10);
+
+  const agentDefs = params.agent ? loadAgentDefaults(params.agent) : null;
+  const effectiveModel = params.model ?? agentDefs?.model ?? getDefaultSubagentModel();
+  const effectiveTools = params.tools ?? agentDefs?.tools;
+  const effectiveSkills = params.skills ?? agentDefs?.skills;
+  const effectiveThinking = agentDefs?.thinking;
+  const effectiveInteractive = resolveEffectiveInteractive(params, agentDefs);
+
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  if (!sessionFile) throw new Error("No session file");
+  const sessionId = ctx.sessionManager.getSessionId();
+  const artifactDir = getArtifactDir(ctx.sessionManager.getSessionDir(), sessionId);
+
+  const { effectiveCwd, localAgentDir, effectiveAgentDir } = resolveSubagentPaths(params, agentDefs);
+  const targetCwdForSession = effectiveCwd ?? ctx.cwd;
+  const sessionDir = getDefaultSessionDirFor(targetCwdForSession, effectiveAgentDir);
+
+  // Generate a deterministic session file path for this subagent.
+  // This eliminates race conditions when multiple agents launch simultaneously —
+  // each agent knows exactly which file is theirs.
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 23) + "Z";
+  const uuid = [
+    id,
+    Math.random().toString(16).slice(2, 10),
+    Math.random().toString(16).slice(2, 10),
+    Math.random().toString(16).slice(2, 6),
+  ].join("-");
+  const subagentSessionFile = join(sessionDir, `${timestamp}_${uuid}.jsonl`);
+
+  // Use pre-created surface (parallel mode) or create a new one.
+  // For new surfaces, pause briefly so the shell is ready before sending the command.
+  const surfacePreCreated = !!options?.surface;
+  const surface = options?.surface ?? createSurface(params.name);
+  const splitFrom = surfacePreCreated ? undefined : (getLastSplitSource() ?? undefined);
+  if (!surfacePreCreated) clearLastSplitSource();
+  if (!surfacePreCreated) {
+    await new Promise<void>((resolve) => setTimeout(resolve, getShellReadyDelayMs()));
+  }
+
+  const launchBehavior = resolveLaunchBehavior(params, agentDefs);
+
+  if (launchBehavior.seededSessionMode) {
+    seedSubagentSessionFile({
+      mode: launchBehavior.seededSessionMode,
+      parentSessionFile: sessionFile,
+      childSessionFile: subagentSessionFile,
+      childCwd: targetCwdForSession,
+    });
+  }
+
+  const activityFile = getSubagentActivityFile(artifactDir, id);
+  mkdirSync(dirname(activityFile), { recursive: true });
+  const { inheritsConversationContext } = launchBehavior;
+
+  // Build the task message
+  // Only full-context fork mode inherits prior conversation state.
+  // Blank-session modes need the wrapper instructions and artifact-backed handoff.
+  const modeHint = agentDefs?.autoExit
+    ? "Complete your task autonomously."
+    : "Complete your task. When finished, call the subagent_done tool. The user can interact with you at any time.";
+  const summaryInstruction = agentDefs?.autoExit
+    ? "Your FINAL assistant message should summarize what you accomplished."
+    : "Your FINAL assistant message (before calling subagent_done or before the user exits) should summarize what you accomplished.";
+  const denySet = resolveDenyTools(agentDefs);
+  const identity = agentDefs?.body ?? params.systemPrompt ?? null;
+  const systemPromptMode = agentDefs?.systemPromptMode;
+  const identityInSystemPrompt = systemPromptMode && identity;
+  const roleBlock = identity && !identityInSystemPrompt ? `\n\n${identity}` : "";
+  const fullTask = inheritsConversationContext
+    ? params.task
+    : `${roleBlock}\n\n${modeHint}\n\n${params.task}\n\n${summaryInstruction}`;
+  // ── Claude Code CLI path ──
+  if (agentDefs?.cli === "claude") {
+    const sentinelFile = `/tmp/pi-claude-${id}-done`;
+    const pluginDir = join(SUBAGENTS_DIR, "plugin");
+
+    const cmdParts: string[] = [];
+    cmdParts.push(`PI_CLAUDE_SENTINEL=${shellEscape(sentinelFile)}`);
+    cmdParts.push("claude");
+    cmdParts.push("--dangerously-skip-permissions");
+
+    if (existsSync(pluginDir)) {
+      cmdParts.push("--plugin-dir", shellEscape(pluginDir));
+    }
+
+    if (effectiveModel) {
+      cmdParts.push("--model", shellEscape(effectiveModel));
+    }
+
+    const sp = params.systemPrompt ?? agentDefs.body;
+    if (sp) {
+      cmdParts.push("--append-system-prompt", shellEscape(sp));
+    }
+
+    if (params.resumeSessionId) {
+      cmdParts.push("--resume", shellEscape(params.resumeSessionId));
+    }
+
+    // Always pass the task as the prompt — even for resumed sessions,
+    // the caller's task is the follow-up instruction.
+    cmdParts.push(shellEscape(params.task));
+
+    const cdPrefix = effectiveCwd ? `cd ${shellEscape(effectiveCwd)} && ` : "";
+    const command = `${cdPrefix}${cmdParts.join(" ")}; echo '__SUBAGENT_DONE_'$?'__'`;
+
+    const launchScriptName = `${(params.name || "subagent")
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, "")
+      .replace(/\s+/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "") || "subagent"}-${id}.sh`;
+    const launchScriptFile = join(artifactDir, "subagent-scripts", launchScriptName);
+
+    sendLongCommand(surface, command, {
+      scriptPath: launchScriptFile,
+      scriptPreamble: [
+        `# Claude Code subagent launch script for ${params.name}`,
+        `# Generated: ${new Date().toISOString()}`,
+        `# Surface: ${surface}`,
+      ].join("\n"),
+    });
+
+    const running: RunningSubagent = {
+      id,
+      name: params.name,
+      task: params.task,
+      agent: params.agent,
+      surface,
+      startTime,
+      sessionFile: subagentSessionFile,
+      launchScriptFile,
+      cli: "claude",
+      sentinelFile,
+      interactive: effectiveInteractive,
+      splitFrom,
+      statusState: createStatusState({
+        source: "claude",
+        startTimeMs: startTime,
+      }),
+    };
+
+    runningSubagents.set(id, running);
+    return running;
+  }
+
+  // ── Pi CLI path ──
+
+  // Build pi command
+  const parts: string[] = ["pi"];
+  parts.push("--session", shellEscape(subagentSessionFile));
+
+  const subagentDonePath = join(SUBAGENTS_DIR, "subagent-done.ts");
+  parts.push("-e", shellEscape(subagentDonePath));
+
+  if (effectiveModel) {
+    const model = effectiveThinking ? `${effectiveModel}:${effectiveThinking}` : effectiveModel;
+    parts.push("--model", shellEscape(model));
+  }
+
+  // Pass agent body as system prompt via file to avoid shell escaping issues
+  // with multiline content. Pi's --append-system-prompt and --system-prompt
+  // auto-detect file paths and read their contents.
+  if (identityInSystemPrompt && identity) {
+    const flag = systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt";
+    const spTimestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const spSafeName = params.name
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, "")
+      .replace(/\s+/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "");
+    const syspromptPath = join(artifactDir, `context/${spSafeName || "subagent"}-sysprompt-${spTimestamp}.md`);
+    mkdirSync(dirname(syspromptPath), { recursive: true });
+    writeFileSync(syspromptPath, identity, "utf8");
+    parts.push(flag, shellEscape(syspromptPath));
+  }
+
+  const toolAllowlist = buildSubagentToolAllowlist(effectiveTools);
+  if (toolAllowlist) {
+    parts.push("--tools", shellEscape(toolAllowlist));
+  }
+
+  // Build env prefix: denied tools + subagent identity + config dir propagation
+  const envParts: string[] = [];
+
+  // If the target cwd has its own .pi/agent/, use that as the config root.
+  // Otherwise propagate the current/global agent dir.
+  if (localAgentDir && existsSync(localAgentDir)) {
+    envParts.push(`PI_CODING_AGENT_DIR=${shellEscape(localAgentDir)}`);
+  } else if (process.env.PI_CODING_AGENT_DIR) {
+    envParts.push(`PI_CODING_AGENT_DIR=${shellEscape(process.env.PI_CODING_AGENT_DIR)}`);
+  }
+
+  if (denySet.size > 0) {
+    envParts.push(`PI_DENY_TOOLS=${shellEscape([...denySet].join(","))}`);
+  }
+  envParts.push(`PI_SUBAGENT_NAME=${shellEscape(params.name)}`);
+  if (params.agent) {
+    envParts.push(`PI_SUBAGENT_AGENT=${shellEscape(params.agent)}`);
+  }
+  if (agentDefs?.autoExit) {
+    envParts.push(`PI_SUBAGENT_AUTO_EXIT=1`);
+  }
+  envParts.push(`PI_SUBAGENT_SESSION=${shellEscape(subagentSessionFile)}`);
+  envParts.push(`PI_SUBAGENT_ID=${shellEscape(id)}`);
+  envParts.push(`PI_SUBAGENT_ACTIVITY_FILE=${shellEscape(activityFile)}`);
+  envParts.push(`PI_SUBAGENT_SURFACE=${shellEscape(surface)}`);
+  if (params.structuredOutputSchema) {
+    envParts.push(
+      `PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA=${shellEscape(JSON.stringify(params.structuredOutputSchema))}`,
+    );
+  }
+  const envPrefix = envParts.join(" ") + " ";
+
+  // Pass task and skill prompts to the sub-agent.
+  // Only full-context fork mode gets a direct task argument because it already
+  // inherits the parent conversation. Blank-session modes use artifact-backed
+  // handoff so the wrapper instructions arrive as the initial user message.
+  let taskArg: string;
+  if (launchBehavior.taskDelivery === "direct") {
+    taskArg = fullTask;
+  } else {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const safeName = params.name
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, "") // strip everything except alphanumeric, spaces, hyphens
+      .replace(/\s+/g, "-") // spaces to hyphens
+      .replace(/-+/g, "-") // collapse multiple hyphens
+      .replace(/^-|-$/g, ""); // trim leading/trailing hyphens
+    const artifactName = `context/${safeName || "subagent"}-${timestamp}.md`;
+    const artifactPath = join(artifactDir, artifactName);
+    mkdirSync(dirname(artifactPath), { recursive: true });
+    writeFileSync(artifactPath, fullTask, "utf8");
+    taskArg = `@${artifactPath}`;
+  }
+
+  for (const promptArg of buildPiPromptArgs({
+    effectiveSkills,
+    taskDelivery: launchBehavior.taskDelivery,
+    taskArg,
+  })) {
+    parts.push(shellEscape(promptArg));
+  }
+
+  // Resolve cwd — param overrides agent default, supports absolute and relative paths.
+  // This was already computed above so session placement, PI_CODING_AGENT_DIR, and cd agree.
+  const cdPrefix = effectiveCwd ? `cd ${shellEscape(effectiveCwd)} && ` : "";
+
+  const piCommand = cdPrefix + envPrefix + parts.join(" ");
+  const command = `${piCommand}; echo '__SUBAGENT_DONE_'$?'__'`;
+  const launchScriptName = `${(params.name || "subagent")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "") || "subagent"}-${id}.sh`;
+  const launchScriptFile = join(artifactDir, "subagent-scripts", launchScriptName);
+  sendLongCommand(surface, command, {
+    scriptPath: launchScriptFile,
+    scriptPreamble: [
+      `# Subagent launch script for ${params.name}`,
+      `# Generated: ${new Date().toISOString()}`,
+      `# Session: ${subagentSessionFile}`,
+      `# Surface: ${surface}`,
+    ].join("\n"),
+  });
+
+  // 延迟重命名 agent 标题（左侧侧栏），需要等 pi 启动被 herdr 检测到
+  const agentName = params.name;
+  const agentSurface = surface;
+  setTimeout(() => renameAgent(agentSurface, agentName), 3000);
+  setTimeout(() => renameAgent(agentSurface, agentName), 5000);
+
+  const running: RunningSubagent = {
+    id,
+    name: params.name,
+    task: params.task,
+    agent: params.agent,
+    surface,
+    startTime,
+    sessionFile: subagentSessionFile,
+    launchScriptFile,
+    activityFile,
+    interactive: effectiveInteractive,
+    splitFrom,
+    statusState: createStatusState({
+      source: "pi",
+      startTimeMs: startTime,
+    }),
+  };
+
+  runningSubagents.set(id, running);
+  return running;
+}
+
+/**
+ * Watch a launched subagent until it exits. Polls for completion, extracts
+ * the summary from the session file, cleans up the surface,
+ * and removes the entry from runningSubagents.
+ */
+const CLAUDE_SESSIONS_DIR = join(
+  process.env.HOME ?? "/tmp",
+  ".pi", "agent", "sessions", "claude-code",
+);
+
+function copyClaudeSession(sentinelFile: string): string | null {
+  try {
+    const transcriptFile = sentinelFile + ".transcript";
+    if (!existsSync(transcriptFile)) return null;
+    const transcriptPath = readFileSync(transcriptFile, "utf-8").trim();
+    if (!transcriptPath || !existsSync(transcriptPath)) return null;
+    mkdirSync(CLAUDE_SESSIONS_DIR, { recursive: true });
+    const filename = transcriptPath.split("/").pop() ?? `claude-${Date.now()}.jsonl`;
+    const dest = join(CLAUDE_SESSIONS_DIR, filename);
+    copyFileSync(transcriptPath, dest);
+    return filename;
+  } catch {
+    return null;
+  }
+}
+
+async function watchSubagent(
+  running: RunningSubagent,
+  signal: AbortSignal,
+): Promise<SubagentResult> {
+  const { name, task, surface, startTime, sessionFile } = running;
+
+  // ── 诊断日志：检查 module abort controller 状态 ──
+  // 若 session_shutdown 调用了 moduleAbort.abort() 但 session_start 没重置，
+  // watchSubagent 会拿到 aborted signal，子 pi 来不及启动就被 close。
+  const moduleSig = getModuleAbortSignal();
+  const compositeSig = AbortSignal.any([signal, moduleSig]);
+  muxLog(`[watchSubagent] ENTER surface=${surface} session=${sessionFile} callerSignal.aborted=${signal.aborted} moduleSignal.aborted=${moduleSig.aborted} compositeSignal.aborted=${compositeSig.aborted}\n`);
+
+  try {
+    const result = await pollForExit(surface, compositeSig, {
+      interval: 1000,
+      sessionFile,
+      sentinelFile: running.sentinelFile,
+      onTick() {
+        observeRunningSubagent(running);
+      },
+    });
+
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+
+    if (running.cli === "claude") {
+      // Claude Code result extraction
+      let summary = "";
+
+      if (running.sentinelFile) {
+        try {
+          summary = readFileSync(running.sentinelFile, "utf-8").trim();
+        } catch {}
+      }
+
+      if (!summary) {
+        summary = readScreen(surface, 200)
+          .replace(/__SUBAGENT_DONE_\d+__/, "")
+          .trimEnd();
+      }
+
+      if (!summary) {
+        summary = result.exitCode !== 0
+          ? `Claude Code exited with code ${result.exitCode}`
+          : "Claude Code exited without output";
+      }
+
+      // Copy Claude session transcript
+      let sessionId: string | null = null;
+      if (running.sentinelFile) {
+        sessionId = copyClaudeSession(running.sentinelFile);
+        try { unlinkSync(running.sentinelFile); } catch {}
+        try { unlinkSync(running.sentinelFile + ".transcript"); } catch {}
+      }
+
+      closeSurface(surface);
+      runningSubagents.delete(running.id);
+
+      return { name, task, summary, exitCode: result.exitCode, elapsed, ...(sessionId ? { claudeSessionId: sessionId } : {}) };
+    }
+
+    // Pi subagent result extraction
+    let summary: string;
+    let structuredOutput: unknown;
+    if (existsSync(sessionFile)) {
+      const allEntries = getNewEntries(sessionFile, 0);
+      summary =
+        findLastAssistantMessage(allEntries) ??
+        (result.exitCode !== 0
+          ? `Sub-agent exited with code ${result.exitCode}`
+          : "Sub-agent exited without output");
+    } else {
+      summary =
+        result.exitCode !== 0
+          ? `Sub-agent exited with code ${result.exitCode}`
+          : "Sub-agent exited without output";
+    }
+
+    // Extract structured output if the subagent used the structured_output tool
+    if (result.reason === "structured_output") {
+      structuredOutput = result.structuredOutput;
+    }
+
+    closeSurface(surface);
+    runningSubagents.delete(running.id);
+
+    return {
+      name,
+      task,
+      summary,
+      sessionFile,
+      exitCode: result.exitCode,
+      elapsed,
+      ping: result.ping,
+      ...(structuredOutput !== undefined ? { structuredOutput } : {}),
+    };
+  } catch (err: any) {
+    try {
+      closeSurface(surface);
+    } catch (closeErr: any) {
+      // closeSurface 失败 → pane 可能残留！让用户事后能看到。
+      const sessionRef = running.sessionFile ?? "<no-session>";
+      process.stderr.write(
+        `[watchSubagent] closeSurface FAILED surface=${surface} session=${sessionRef} err=${closeErr?.message ?? String(closeErr)}\n`,
+      );
+    }
+    runningSubagents.delete(running.id);
+
+    if (signal.aborted) {
+      return {
+        name,
+        task,
+        summary: "Subagent cancelled.",
+        exitCode: 1,
+        elapsed: Math.floor((Date.now() - startTime) / 1000),
+        error: "cancelled",
+        sessionFile,
+      };
+    }
+    return {
+      name,
+      task,
+      summary: `Subagent error: ${err?.message ?? String(err)}`,
+      exitCode: 1,
+      elapsed: Math.floor((Date.now() - startTime) / 1000),
+      error: err?.message ?? String(err),
+    };
+  }
+}
+
+export default function subagentsExtension(pi: ExtensionAPI) {
+  // Expose launchSubagent / watchSubagent for programmatic use by other extensions
+  (globalThis as any).__pi_subagents = { launchSubagent, watchSubagent };
+
+  // Capture the UI context for widget updates
+  pi.on("session_start", (_event, ctx) => {
+    latestCtx = ctx;
+  });
+
+  // Clean up on session shutdown
+  pi.on("session_shutdown", (_event, _ctx) => {
+    if (widgetInterval) {
+      clearInterval(widgetInterval);
+      widgetInterval = null;
+      (globalThis as any)[WIDGET_INTERVAL_KEY] = null;
+    }
+    if (statusInterval) {
+      clearInterval(statusInterval);
+      statusInterval = null;
+      (globalThis as any)[STATUS_INTERVAL_KEY] = null;
+    }
+    const moduleAbort = (globalThis as any)[POLL_ABORT_KEY] as AbortController | undefined;
+    if (moduleAbort) moduleAbort.abort();
+    for (const [_id, agent] of runningSubagents) {
+      agent.abortController?.abort();
+    }
+    runningSubagents.clear();
+  });
+
+  // Tools denied via PI_DENY_TOOLS env var (set by parent agent based on frontmatter)
+  const deniedTools = new Set(
+    (process.env.PI_DENY_TOOLS ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+
+  const shouldRegister = (name: string) => !deniedTools.has(name);
+
+  // ── subagent tool ──
+  if (shouldRegister("subagent"))
+    pi.registerTool({
+      name: "subagent",
+      label: "Subagent",
+      description:
+        "Spawn a sub-agent in a background process or terminal multiplexer pane. " +
+        "This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. " +
+        "When the sub-agent finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. " +
+        "DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT call subagents_list or any other tool to 'check' status. All of that is wasted work — the harness handles delivery for you. " +
+        "DO NOT fabricate, assume, or summarize results after calling this tool. " +
+        "After spawning, either end your turn immediately, or work on other independent tasks (including spawning more subagents in parallel). The harness will wake you with the result when it is ready.",
+      promptSnippet:
+        "Spawn a sub-agent in a background process or terminal multiplexer pane. " +
+        "This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. " +
+        "When the sub-agent finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. " +
+        "DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT call subagents_list or any other tool to 'check' status. All of that is wasted work — the harness handles delivery for you. " +
+        "DO NOT fabricate, assume, or summarize results after calling this tool. " +
+        "After spawning, either end your turn immediately, or work on other independent tasks (including spawning more subagents in parallel). The harness will wake you with the result when it is ready.",
+      parameters: SubagentParams,
+
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        // Prevent self-spawning (e.g. planner spawning another planner)
+        const currentAgent = process.env.PI_SUBAGENT_AGENT;
+        if (params.agent && currentAgent && params.agent === currentAgent) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `You are the ${currentAgent} agent — do not start another ${currentAgent}. You were spawned to do this work yourself. Complete the task directly.`,
+              },
+            ],
+            details: { error: "self-spawn blocked" },
+          };
+        }
+
+        if (!ctx.sessionManager.getSessionFile()) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: no session file. Start pi with a persistent session to use subagents.",
+              },
+            ],
+            details: { error: "no session file" },
+          };
+        }
+
+        // Launch the subagent (creates pane, sends command)
+        const running = await launchSubagent(params, ctx);
+
+        // Create a separate AbortController for the watcher
+        // (the tool's signal completes when we return)
+        const watcherAbort = new AbortController();
+        running.abortController = watcherAbort;
+
+        // Start widget refresh and status supervision when the first agent launches
+        startWidgetRefresh();
+        startStatusRefresh(pi);
+
+        // Fire-and-forget: start watching in background
+        watchSubagent(running, watcherAbort.signal)
+          .then((result) => {
+            updateWidget(); // reflect removal from Map immediately
+
+            if (result.ping) {
+              // Subagent is requesting help — steer a ping message with session path for resume
+              const sessionRef = `\n\nSession: ${result.sessionFile}\nResume: pi --session ${result.sessionFile}`;
+              pi.sendMessage(
+                {
+                  customType: "subagent_ping",
+                  content: `Sub-agent "${result.ping.name}" needs help (${formatElapsed(result.elapsed)}):\n\n${result.ping.message}${sessionRef}`,
+                  display: true,
+                  details: {
+                    name: result.ping.name,
+                    message: result.ping.message,
+                    agent: running.agent,
+                    sessionFile: result.sessionFile,
+                  },
+                },
+                { triggerTurn: true, deliverAs: "steer" },
+              );
+              return;
+            }
+
+            const presentation = resolveResultPresentation(result, running.name);
+
+            pi.sendMessage(
+              {
+                customType: "subagent_result",
+                content: presentation,
+                display: true,
+                details: {
+                  name: running.name,
+                  task: running.task,
+                  agent: running.agent,
+                  exitCode: result.exitCode,
+                  elapsed: result.elapsed,
+                  sessionFile: result.sessionFile,
+                  ...(result.claudeSessionId ? { claudeSessionId: result.claudeSessionId } : {}),
+                  ...(result.structuredOutput !== undefined ? { structuredOutput: result.structuredOutput } : {}),
+                },
+              },
+              { triggerTurn: true, deliverAs: "steer" },
+            );
+          })
+          .catch((err) => {
+            updateWidget();
+            pi.sendMessage(
+              {
+                customType: "subagent_result",
+                content: `Sub-agent "${running.name}" error: ${err?.message ?? String(err)}`,
+                display: true,
+                details: { name: running.name, task: running.task, error: err?.message },
+              },
+              { triggerTurn: true, deliverAs: "steer" },
+            );
+          });
+
+        // Return immediately
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `Sub-agent "${params.name}" launched and is now running in the background. ` +
+                `Do NOT generate or assume any results — you have no idea what the sub-agent will do or produce. ` +
+                `The results will be delivered to you automatically as a steer message when the sub-agent finishes. ` +
+                `Until then, move on to other work or tell the user you're waiting.`,
+            },
+          ],
+          details: {
+            id: running.id,
+            name: params.name,
+            task: params.task,
+            agent: params.agent,
+            sessionFile: running.sessionFile,
+            launchScriptFile: running.launchScriptFile,
+            surface: running.surface,
+            splitFrom: running.splitFrom,
+            status: "started",
+          },
+        };
+      },
+
+      renderCall(args, theme) {
+        const partialArgs = args as Record<string, unknown>;
+        const name = typeof partialArgs.name === "string" && partialArgs.name ? partialArgs.name : "(unnamed)";
+        const task = typeof partialArgs.task === "string" ? partialArgs.task : "";
+        const agent = typeof partialArgs.agent === "string" && partialArgs.agent
+          ? theme.fg("dim", ` (${partialArgs.agent})`)
+          : "";
+        const cwdHint = typeof partialArgs.cwd === "string" && partialArgs.cwd
+          ? theme.fg("dim", ` in ${partialArgs.cwd}`)
+          : "";
+        let text =
+          "▸ " +
+          theme.fg("toolTitle", theme.bold(name)) +
+          agent +
+          cwdHint;
+
+        // Show a one-line task preview. renderCall is called repeatedly as the
+        // LLM generates tool arguments, so args.task grows token by token.
+        // We keep it compact here — Ctrl+O on renderResult expands the full content.
+        if (task) {
+          const firstLine = task.split("\n").find((l: string) => l.trim()) ?? "";
+          const preview = firstLine.length > 100 ? firstLine.slice(0, 100) + "…" : firstLine;
+          if (preview) {
+            text += "\n" + theme.fg("toolOutput", preview);
+          }
+          const totalLines = task.split("\n").length;
+          if (totalLines > 1) {
+            text += theme.fg("muted", ` (${totalLines} lines)`);
+          }
+        }
+
+        return new Text(text, 0, 0);
+      },
+
+      renderResult(result, _opts, theme) {
+        const details = result.details as any;
+        const name = details?.name ?? "(unnamed)";
+
+        // "Started" result — tool returned immediately
+        if (details?.status === "started") {
+          const splitHint = details?.splitFrom
+            ? theme.fg("dim", ` (from ${details.splitFrom})`)
+            : "";
+          return new Text(
+            theme.fg("accent", "▸") +
+              " " +
+              theme.fg("toolTitle", theme.bold(name)) +
+              theme.fg("dim", " — started") +
+              splitHint,
+            0,
+            0,
+          );
+        }
+
+        // Fallback (shouldn't happen)
+        const text = extractFirstText(result.content);
+        return new Text(theme.fg("dim", text), 0, 0);
+      },
+    });
+
+  // ── subagent_interrupt tool ──
+  if (shouldRegister("subagent_interrupt"))
+    pi.registerTool({
+      name: "subagent_interrupt",
+      label: "Interrupt Subagent",
+      description:
+        "Send Escape to the active turn of a currently running Pi-backed subagent. " +
+        "The child pane, session, watcher, and running entry remain alive; this returns only a local acknowledgement " +
+        "and does not emit a subagent_result solely because of this request.",
+      promptSnippet:
+        "Send Escape to the active turn of a currently running Pi-backed subagent. " +
+        "The child pane, session, watcher, and running entry remain alive; this returns only a local acknowledgement " +
+        "and does not emit a subagent_result solely because of this request.",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ description: "Exact running subagent id" })),
+        name: Type.Optional(Type.String({ description: "Exact running subagent display name" })),
+      }),
+
+      async execute(_toolCallId, params) {
+        return handleSubagentInterrupt(params);
+      },
+
+      renderCall(args, theme) {
+        const target = args.id ? `${args.id}` : args.name ?? "(unknown)";
+        return new Text(
+          theme.fg("accent", "▸") +
+            " " +
+            theme.fg("toolTitle", theme.bold(target)) +
+            theme.fg("dim", " — interrupt turn"),
+          0,
+          0,
+        );
+      },
+
+      renderResult(result, _opts, theme) {
+        const details = result.details as any;
+        if (details?.status === "interrupt_requested") {
+          return new Text(
+            theme.fg("accent", "▸") +
+              " " +
+              theme.fg("toolTitle", theme.bold(details.name ?? details.id ?? "subagent")) +
+              theme.fg("dim", " — interrupt requested"),
+            0,
+            0,
+          );
+        }
+
+        const text = extractFirstText(result.content);
+        return new Text(theme.fg("dim", text), 0, 0);
+      },
+    });
+
+  // ── subagents_list tool ──
+  if (shouldRegister("subagents_list"))
+    pi.registerTool({
+      name: "subagents_list",
+      label: "List Subagents",
+      description:
+        "List all available subagent definitions. " +
+        "Scans project-local .pi/agents/ and global ~/.pi/agent/agents/. " +
+        "Project-local agents override global ones with the same name.",
+      promptSnippet:
+        "List all available subagent definitions. " +
+        "Scans project-local .pi/agents/ and global ~/.pi/agent/agents/. " +
+        "Project-local agents override global ones with the same name.",
+      parameters: Type.Object({}),
+
+      async execute() {
+        const list = discoverAgentDefinitions().filter((agent) => !agent.disableModelInvocation);
+
+        if (list.length === 0) {
+          return {
+            content: [{ type: "text", text: "No subagent definitions found." }],
+            details: { agents: [] },
+          };
+        }
+
+        const lines = list.map((a) => {
+          const badge = a.source === "project" ? " (project)" : "";
+          const desc = a.description ? ` — ${a.description}` : "";
+          const model = a.model ? ` [${a.model}]` : "";
+          return `• ${a.name}${badge}${model}${desc}`;
+        });
+
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          details: { agents: list },
+        };
+      },
+
+      renderResult(result, _opts, theme) {
+        const details = result.details as any;
+        const agents = details?.agents ?? [];
+        if (agents.length === 0) {
+          return new Text(theme.fg("dim", "No subagent definitions found."), 0, 0);
+        }
+        const lines = agents.map((a: any) => {
+          const badge = a.source === "project" ? theme.fg("accent", " (project)") : "";
+          const desc = a.description ? theme.fg("dim", ` — ${a.description}`) : "";
+          const model = a.model ? theme.fg("dim", ` [${a.model}]`) : "";
+          return `  ${theme.fg("toolTitle", theme.bold(a.name))}${badge}${model}${desc}`;
+        });
+        return new Text(lines.join("\n"), 0, 0);
+      },
+    });
+
+
+
+  // ── subagent_resume tool ──
+  if (shouldRegister("subagent_resume"))
+    pi.registerTool({
+      name: "subagent_resume",
+      label: "Resume Subagent",
+      description:
+        "Resume a previous sub-agent session in a background process or new multiplexer pane. " +
+        "This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. " +
+        "When the resumed sub-agent finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. " +
+        "DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT poll for status. All of that is wasted work — the harness delivers the result for you. " +
+        "DO NOT fabricate or assume results. After resuming, either end your turn or work on other independent tasks; the harness will wake you when the result is ready. " +
+        "Use when a sub-agent was cancelled or needs follow-up work.",
+      promptSnippet:
+        "Resume a previous sub-agent session in a background process or new multiplexer pane. " +
+        "This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. " +
+        "When the resumed sub-agent finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. " +
+        "DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT poll for status. All of that is wasted work — the harness delivers the result for you. " +
+        "DO NOT fabricate or assume results. After resuming, either end your turn or work on other independent tasks; the harness will wake you when the result is ready. " +
+        "Use when a sub-agent was cancelled or needs follow-up work.",
+      parameters: Type.Object({
+        sessionPath: Type.String({ description: "Path to the session .jsonl file to resume" }),
+        name: Type.Optional(
+          Type.String({ description: "Display name for the terminal tab. Default: 'Resume'" }),
+        ),
+        message: Type.Optional(
+          Type.String({
+            description: "Optional message to send after resuming (e.g. follow-up instructions)",
+          }),
+        ),
+        autoExit: Type.Optional(
+          Type.Boolean({
+            description:
+              "Whether the resumed session should automatically exit after completing its response. Defaults to true for autonomous follow-up work; set false for interactive resumed sessions.",
+          }),
+        ),
+      }),
+
+      renderCall(args, theme) {
+        const name = args.name ?? "Resume";
+        const text =
+          "▸ " +
+          theme.fg("toolTitle", theme.bold(name)) +
+          theme.fg("dim", " — resuming session");
+        return new Text(text, 0, 0);
+      },
+
+      renderResult(result, _opts, theme) {
+        const details = result.details as any;
+        const name = details?.name ?? "Resume";
+
+        if (details?.status === "started") {
+          return new Text(
+            theme.fg("accent", "▸") +
+              " " +
+              theme.fg("toolTitle", theme.bold(name)) +
+              theme.fg("dim", " — resumed"),
+            0,
+            0,
+          );
+        }
+
+        // Fallback
+        const text = extractFirstText(result.content);
+        return new Text(theme.fg("dim", text), 0, 0);
+      },
+
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const name = params.name ?? "Resume";
+        const { autoExit, interactive } = resolveResumeLaunchBehavior(params);
+        const startTime = Date.now();
+        const id = Math.random().toString(16).slice(2, 10);
+
+        if (!existsSync(params.sessionPath)) {
+          return {
+            content: [
+              { type: "text", text: `Error: session file not found: ${params.sessionPath}` },
+            ],
+            details: { error: "session not found" },
+          };
+        }
+
+        // Record entry count before resuming so we can extract new messages
+        const entryCountBefore = getNewEntries(params.sessionPath, 0).length;
+
+        const surface = createSurface(name);
+        await new Promise<void>((resolve) => setTimeout(resolve, getShellReadyDelayMs()));
+
+        // Build pi resume command
+        const parts = ["pi", "--session", shellEscape(params.sessionPath)];
+
+        // Load subagent-done extension so the agent can self-terminate if needed
+        const subagentDonePath = join(SUBAGENTS_DIR, "subagent-done.ts");
+        parts.push("-e", shellEscape(subagentDonePath));
+
+        const sessionId = ctx.sessionManager.getSessionId();
+        const artifactDir = getArtifactDir(ctx.sessionManager.getSessionDir(), sessionId);
+        const activityFile = getSubagentActivityFile(artifactDir, id);
+        mkdirSync(dirname(activityFile), { recursive: true });
+
+        let resumeMsgFile: string | undefined;
+        if (params.message) {
+          const msgTimestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+          resumeMsgFile = join(
+            artifactDir,
+            "subagent-resume",
+            `${name
+              .toLowerCase()
+              .replace(/[^a-z0-9\s-]/g, "")
+              .replace(/\s+/g, "-")
+              .replace(/-+/g, "-")
+              .replace(/^-|-$/g, "") || "resume"}-${msgTimestamp}.md`,
+          );
+          mkdirSync(dirname(resumeMsgFile), { recursive: true });
+          writeFileSync(resumeMsgFile, params.message, "utf8");
+          parts.push(shellEscape(`@${resumeMsgFile}`));
+        }
+
+        // Build env prefix — propagate PI_CODING_AGENT_DIR for config isolation
+        const resumeEnvParts: string[] = [];
+        if (process.env.PI_CODING_AGENT_DIR) {
+          resumeEnvParts.push(`PI_CODING_AGENT_DIR=${shellEscape(process.env.PI_CODING_AGENT_DIR)}`);
+        }
+        resumeEnvParts.push(`PI_SUBAGENT_NAME=${shellEscape(name)}`);
+        resumeEnvParts.push(`PI_SUBAGENT_SESSION=${shellEscape(params.sessionPath)}`);
+        resumeEnvParts.push(`PI_SUBAGENT_ID=${shellEscape(id)}`);
+        resumeEnvParts.push(`PI_SUBAGENT_ACTIVITY_FILE=${shellEscape(activityFile)}`);
+        if (autoExit) {
+          resumeEnvParts.push(`PI_SUBAGENT_AUTO_EXIT=1`);
+        }
+        const resumeEnvPrefix = resumeEnvParts.join(" ") + " ";
+
+        const command = `${resumeEnvPrefix}${parts.join(" ")}; echo '__SUBAGENT_DONE_'$?'__'`;
+        const launchScriptFile = join(
+          artifactDir,
+          "subagent-scripts",
+          `${name
+            .toLowerCase()
+            .replace(/[^a-z0-9\s-]/g, "")
+            .replace(/\s+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "") || "resume"}-resume-${Date.now()}.sh`,
+        );
+        sendLongCommand(surface, command, {
+          scriptPath: launchScriptFile,
+          scriptPreamble: [
+            `# Subagent resume script for ${name}`,
+            `# Generated: ${new Date().toISOString()}`,
+            `# Session: ${params.sessionPath}`,
+            `# Surface: ${surface}`,
+            ...(resumeMsgFile ? [`# Resume message file: ${resumeMsgFile}`] : []),
+          ].join("\n"),
+        });
+
+        // Register as a running subagent for widget tracking
+        const running: RunningSubagent = {
+          id,
+          name,
+          task: params.message ?? "resumed session",
+          surface,
+          startTime,
+          sessionFile: params.sessionPath,
+          launchScriptFile,
+          activityFile,
+          interactive,
+          statusState: createStatusState({
+            source: "pi",
+            startTimeMs: startTime,
+          }),
+        };
+        runningSubagents.set(id, running);
+        startWidgetRefresh();
+        startStatusRefresh(pi);
+
+        // Fire-and-forget watcher
+        const watcherAbort = new AbortController();
+        running.abortController = watcherAbort;
+
+        watchSubagent(running, watcherAbort.signal)
+          .then((result) => {
+            updateWidget();
+
+            if (result.ping) {
+              const sessionRef = `\n\nSession: ${params.sessionPath}\nResume: pi --session ${params.sessionPath}`;
+              pi.sendMessage(
+                {
+                  customType: "subagent_ping",
+                  content: `Sub-agent "${result.ping.name}" needs help (${formatElapsed(result.elapsed)}):\n\n${result.ping.message}${sessionRef}`,
+                  display: true,
+                  details: {
+                    name: result.ping.name,
+                    message: result.ping.message,
+                    sessionFile: params.sessionPath,
+                  },
+                },
+                { triggerTurn: true, deliverAs: "steer" },
+              );
+              return;
+            }
+
+            const allEntries = getNewEntries(params.sessionPath, entryCountBefore);
+            const summary = findLastAssistantMessage(allEntries) ??
+              (result.exitCode !== 0
+                ? `Resumed session exited with code ${result.exitCode}`
+                : "Resumed session exited without new output");
+            const presentation = resolveResultPresentation(
+              { ...result, summary, sessionFile: params.sessionPath },
+              name,
+            );
+
+            pi.sendMessage(
+              {
+                customType: "subagent_result",
+                content: presentation,
+                display: true,
+                details: {
+                  name,
+                  task: params.message ?? "resumed session",
+                  exitCode: result.exitCode,
+                  elapsed: result.elapsed,
+                  sessionFile: params.sessionPath,
+                },
+              },
+              { triggerTurn: true, deliverAs: "steer" },
+            );
+          })
+          .catch((err) => {
+            updateWidget();
+            pi.sendMessage(
+              {
+                customType: "subagent_result",
+                content: `Resume error: ${err?.message ?? String(err)}`,
+                display: true,
+                details: { name, error: err?.message },
+              },
+              { triggerTurn: true, deliverAs: "steer" },
+            );
+          });
+
+        return {
+          content: [{ type: "text", text: `Session "${name}" resumed.` }],
+          details: {
+            id,
+            name,
+            sessionPath: params.sessionPath,
+            launchScriptFile,
+            status: "started",
+          },
+        };
+      },
+    });
+
+  // /iterate command — fork the session into a subagent
+  pi.registerCommand("iterate", {
+    description: "Fork session into a subagent for focused work (bugfixes, iteration)",
+    handler: async (args, _ctx) => {
+      const task = args.trim() || "";
+      const toolCall = task
+        ? `Use subagent to fork a session. fork: true, name: "Iterate", task: ${JSON.stringify(task)}`
+        : `Use subagent to fork a session. fork: true, name: "Iterate", task: "The user wants to do some hands-on work. Help them with whatever they need."`;
+      pi.sendUserMessage(toolCall);
+    },
+  });
+
+  // /subagent command — spawn a subagent by name
+  pi.registerCommand("subagent", {
+    description: "Spawn a subagent: /subagent <agent> <task>",
+    handler: async (args, ctx) => {
+      const trimmed = args.trim();
+      if (!trimmed) {
+        ctx.ui.notify("Usage: /subagent <agent> [task]", "warning");
+        return;
+      }
+
+      const spaceIdx = trimmed.indexOf(" ");
+      const agentName = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+      const task = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1).trim();
+
+      const defs = loadAgentDefaults(agentName);
+      if (!defs) {
+        ctx.ui.notify(
+          `Agent "${agentName}" not found in ~/.pi/agent/agents/ or .pi/agents/`,
+          "error",
+        );
+        return;
+      }
+
+      const taskText = task || `You are the ${agentName} agent. Wait for instructions.`;
+      const displayName = agentName[0].toUpperCase() + agentName.slice(1);
+      const toolCall = `Use subagent with agent: "${agentName}", name: "${displayName}", task: ${JSON.stringify(taskText)}`;
+      pi.sendUserMessage(toolCall);
+    },
+  });
+
+  // ── subagent_result message renderer ──
+  pi.registerMessageRenderer("subagent_result", (message, options, theme) => {
+    const details = message.details as any;
+    if (!details) return undefined;
+
+    return {
+      render(width: number): string[] {
+        const name = details.name ?? "subagent";
+        const exitCode = details.exitCode ?? 0;
+        const elapsed = details.elapsed != null ? formatElapsed(details.elapsed) : "?";
+        const bgFn = exitCode === 0
+          ? (text: string) => theme.bg("toolSuccessBg", text)
+          : (text: string) => theme.bg("toolErrorBg", text);
+        const icon = exitCode === 0
+          ? theme.fg("success", "✓")
+          : theme.fg("error", "✗");
+        const status = exitCode === 0
+          ? "completed"
+          : `failed (exit ${exitCode})`;
+        const agentTag = details.agent ? theme.fg("dim", ` (${details.agent})`) : "";
+
+        const header = `${icon} ${theme.fg("toolTitle", theme.bold(name))}${agentTag} ${theme.fg("dim", "—")} ${status} ${theme.fg("dim", `(${elapsed})`)}`;
+        const rawContent = typeof message.content === "string" ? message.content : "";
+
+        // Clean summary (remove session ref and leading label for display)
+        const summary = rawContent
+          .replace(/\n\nSession: .+\nResume: .+$/, "")
+          .replace(`Sub-agent "${name}" completed (${elapsed}).\n\n`, "")
+          .replace(`Sub-agent "${name}" failed (exit code ${exitCode}).\n\n`, "");
+
+        // Build content for the box
+        const contentLines = [header];
+
+        if (options.expanded) {
+          // Full view: complete summary + session info
+          if (summary) {
+            for (const line of summary.split("\n")) {
+              contentLines.push(line.slice(0, width - 6));
+            }
+          }
+          if (details.sessionFile) {
+            contentLines.push("");
+            contentLines.push(theme.fg("dim", `Session: ${details.sessionFile}`));
+            contentLines.push(theme.fg("dim", `Resume:  pi --session ${details.sessionFile}`));
+          }
+        } else {
+          // Collapsed: preview + expand hint
+          if (summary) {
+            const previewLines = summary.split("\n").slice(0, 5);
+            for (const line of previewLines) {
+              contentLines.push(theme.fg("dim", line.slice(0, width - 6)));
+            }
+            const totalLines = summary.split("\n").length;
+            if (totalLines > 5) {
+              contentLines.push(theme.fg("muted", `… ${totalLines - 5} more lines`));
+            }
+          }
+          contentLines.push(theme.fg("muted", keyHint("app.tools.expand", "to expand")));
+        }
+
+        // Render via Box for background + padding, with blank line above for separation
+        const box = new Box(1, 1, bgFn);
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+      invalidate(): void {},
+    };
+  });
+
+  // ── subagent_status message renderer ──
+  pi.registerMessageRenderer("subagent_status", (message, options, theme) => {
+    const details = message.details as any;
+    const lines = Array.isArray(details?.lines) ? details.lines : [];
+    const overflow = typeof details?.overflow === "number" ? details.overflow : 0;
+    if (lines.length === 0 && overflow === 0) return undefined;
+
+    return {
+      render(width: number): string[] {
+        const lineWidth = Math.max(0, width - 6);
+        const contentLines = [
+          `${theme.fg("accent", "•")} ${theme.fg("toolTitle", theme.bold("Subagent status"))}`,
+          ...lines.map((line: string) => theme.fg("dim", truncateToWidth(line, lineWidth))),
+        ];
+
+        if (overflow > 0) {
+          contentLines.push(theme.fg("muted", `+${overflow} more running.`));
+        }
+        if (!options.expanded) {
+          contentLines.push(theme.fg("muted", keyHint("app.tools.expand", "to expand")));
+        }
+
+        const box = new Box(1, 1, (text: string) => theme.bg("customMessageBg", text));
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+      invalidate(): void {},
+    };
+  });
+
+  // ── subagent_ping message renderer ──
+  pi.registerMessageRenderer("subagent_ping", (message, options, theme) => {
+    const details = message.details as any;
+    if (!details) return undefined;
+
+    return {
+      render(width: number): string[] {
+        const name = details.name ?? "subagent";
+        const agentTag = details.agent ? theme.fg("dim", ` (${details.agent})`) : "";
+        const bgFn = (text: string) => theme.bg("toolSuccessBg", text);
+
+        const icon = theme.fg("accent", "?");
+        const header = `${icon} ${theme.fg("toolTitle", theme.bold(name))}${agentTag} ${theme.fg("dim", "— needs help")}`;
+
+        const contentLines = [header];
+
+        if (options.expanded) {
+          contentLines.push("");
+          contentLines.push(details.message ?? "");
+          if (details.sessionFile) {
+            contentLines.push("");
+            contentLines.push(theme.fg("dim", `Session: ${details.sessionFile}`));
+          }
+        } else {
+          const preview = (details.message ?? "").split("\n")[0].slice(0, width - 10);
+          contentLines.push(theme.fg("dim", preview));
+          contentLines.push(theme.fg("muted", keyHint("app.tools.expand", "to expand")));
+        }
+
+        const box = new Box(1, 1, bgFn);
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+      invalidate(): void {},
+    };
+  });
+
+  // /plan command — start the full planning workflow
+  pi.registerCommand("plan", {
+    description: "Start a planning session: /plan <what to build>",
+    handler: async (args, ctx) => {
+      const task = args.trim();
+      if (!task) {
+        ctx.ui.notify("Usage: /plan <what to build>", "warning");
+        return;
+      }
+
+      // Rename workspace and tab to show this is a planning session
+      if (isMuxAvailable()) {
+        try {
+          const label = task.length > 40 ? task.slice(0, 40) + "..." : task;
+          renameWorkspace(`🎯 ${label}`);
+          renameCurrentTab(`🎯 Plan: ${label}`);
+        } catch {
+          // non-critical -- do not block the plan
+        }
+      }
+
+      // Load the plan skill from the subagents extension directory
+      const planSkillPath = join(SUBAGENTS_DIR, "plan-skill.md");
+      let content = readFileSync(planSkillPath, "utf8");
+      content = content.replace(/^---\n[\s\S]*?\n---\n*/, "");
+      pi.sendUserMessage(
+        `<skill name="plan" location="${planSkillPath}">\n${content.trim()}\n</skill>\n\n${task}`,
+      );
+    },
+  });
+}
+
+// ── Exported for direct programmatic use (e.g. pi-dynamic-workflows) ──
+export { launchSubagent, watchSubagent };
+export type { RunningSubagent, SubagentResult };