@tt-a1i/openpi 0.3.1 → 0.5.0

package/extensions/subagents/index.ts

@@ -16,7 +16,8 @@
  * settle. `/subagents` opens a picker + full interactive takeover view.
  *
  * Agent types (`src/agent-types.ts`) are optional named presets that fix a
- * child's system prompt, model, and tool allowlist; see `docs/agent-types.md`.
+ * child's system prompt, model, and tool allowlist; see
+ * `skills/subagents/REFERENCE.md`.
  *
  * Architecture: Effect v4 generators throughout (backend -> manager ->
  * runtime); this file is the async boundary where tool handlers run effects
@@ -25,7 +26,6 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { StringEnum } from "@earendil-works/pi-ai";
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
@@ -37,7 +37,6 @@ import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
   defineTool,
-  formatSize,
   getAgentDir,
   getMarkdownTheme,
   keyHint,
@@ -45,42 +44,83 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import {
+  createStatusWriter,
+  formatActivityStatus,
+  hasActivity,
+  unreadActivityCounts,
+} from "../shared/activity-status.ts";
+import { sanitizeText } from "../shared/agent-transcript.ts";
+import {
+  BelowEditorNavigationEditor,
+  BelowEditorStripState,
+} from "../shared/below-editor-navigation.ts";
+import {
+  effectiveChildToolAllowlist,
+  resolveStandaloneChildProjectTrust,
+} from "../shared/child-session.ts";
+import { formatContextUtilization } from "../shared/context-utilization.ts";
+import {
+  registerEditorLayer,
+  removeEditorLayer,
+} from "../shared/editor-layers.ts";
+import {
+  PLAN_MODE_CHANNEL,
+  type PlanModeState,
+  planModeAllowsDeclaredTools,
+  planModeChildTools,
+} from "../shared/plan-mode-state.ts";
+import {
+  allocateResultBudgets,
+  type ParentContextUsage,
+} from "../shared/result-budget.ts";
+import { type DetailDisplay, loadSetupConfig } from "../shared/setup-config.ts";
+import {
+  OPENPI_TOOL_SURFACE,
+  patchOwnedTools,
+} from "../shared/tool-surface.ts";
+import {
+  projectSubagentCapability,
+  registerWebCapability,
+} from "../shared/web-observer-registry.ts";
+import {
+  createWorktree,
+  formatWorktreeCleanupWarning,
+  reclaimWorktree,
+  type Worktree,
+} from "../shared/worktree.ts";
+import {
+  normalizeSubagentTitle,
+  SubagentStripWidget,
+  selectSubagentStripEntry,
+  subagentStripEntryKey,
+} from "./navigation.ts";
 import {
   formatAgentTypeDiagnostics,
   loadAgentTypes,
   roleModelForAgentType,
   selectSubagentModel,
-  type AgentType,
 } from "./src/agent-types.ts";
 import { deriveBtwTitle, isModelVisible } from "./src/by-the-way.ts";
 import {
   BACKEND_NAMES,
   formatElapsed,
   latestText,
-  REASONING_EFFORTS,
   type SubagentSnapshot,
 } from "./src/domain.ts";
 import {
-  formatActivityStatus,
-  hasActivity,
-  unreadActivityCounts,
-} from "../shared/activity-status.ts";
-import {
-  OPENPI_TOOL_SURFACE,
-  patchOwnedTools,
-} from "../shared/tool-surface.ts";
-import {
-  registerEditorLayer,
-  removeEditorLayer,
-} from "../shared/editor-layers.ts";
-import { formatContextUtilization } from "./src/format.ts";
+  restoreSubagentIdCounters,
+  SUBAGENT_ID_WATERMARK_ENTRY_TYPE,
+  type SubagentIdCounters,
+  subagentIdWatermark,
+} from "./src/id-sequence.ts";
 import { SubagentManager, type SubagentManagerShape } from "./src/manager.ts";
 import {
+  buildSubagentResultDisplayMessage,
   buildSubagentResultMessage,
-  createAgentTypeParameterSchema,
   buildSubagentSendResult,
   buildSubagentSpawnResult,
-  buildSubagentSpawnToolDescription,
+  createSubagentSpawnToolSurface,
   SUBAGENT_CANCEL_PARAMETER_DESCRIPTIONS,
   SUBAGENT_CANCEL_TOOL_DESCRIPTION,
   SUBAGENT_CHECK_PARAMETER_DESCRIPTIONS,
@@ -88,54 +128,40 @@ import {
   SUBAGENT_LIST_TOOL_DESCRIPTION,
   SUBAGENT_SEND_PARAMETER_DESCRIPTIONS,
   SUBAGENT_SEND_TOOL_DESCRIPTION,
-  SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS,
   SUBAGENT_SPAWN_PROMPT_GUIDELINES,
   SUBAGENT_SPAWN_PROMPT_SNIPPET,
-  SUBAGENT_SPAWN_TOOL_DESCRIPTION,
   SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS,
   SUBAGENT_WAIT_TOOL_DESCRIPTION,
+  stripSubagentResultTransportInstruction,
 } from "./src/prompt.ts";
-import { createSubagentResultDelivery } from "./src/result-delivery.ts";
 import {
-  effectiveChildToolAllowlist,
-  resolveStandaloneChildProjectTrust,
-} from "../shared/child-session.ts";
-import {
-  BelowEditorNavigationEditor,
-  BelowEditorStripState,
-} from "../shared/below-editor-navigation.ts";
-import { loadSetupConfig } from "../shared/setup-config.ts";
-import {
-  PLAN_MODE_CHANNEL,
-  planModeAllowsDeclaredTools,
-  planModeChildTools,
-  type PlanModeState,
-} from "../shared/plan-mode-state.ts";
-import {
-  createWorktree,
-  reclaimWorktree,
-  type Worktree,
-} from "../shared/worktree.ts";
+  persistResultArtifact,
+  projectResult,
+  type ResultProjection,
+} from "./src/result-artifact.ts";
+import { createSubagentResultDelivery } from "./src/result-delivery.ts";
 import {
   createSubagentRuntime,
   runTool,
   type SubagentRuntime,
 } from "./src/runtime.ts";
-import {
-  normalizeSubagentTitle,
-  selectSubagentStripEntry,
-  SubagentStripWidget,
-} from "./navigation.ts";
 import { openSubagentPicker, openSubagentTakeover } from "./src/ui/takeover.ts";
 import {
-  buildWaitResultPreview,
   renderWaitResult,
+  renderWaitResultPreview,
   type WaitResultDetails,
 } from "./src/ui/wait-result.ts";
 
 const SUBAGENT_OUTPUT_MAX_BYTES = 24 * 1024;
+const AUTOMATIC_OUTPUT_MAX_BYTES = 48 * 1024;
+const AUTOMATIC_MIN_RESULT_BYTES = 2 * 1024;
 const WAIT_OUTPUT_MAX_BYTES = 48 * 1024;
 const WAIT_PER_AGENT_MAX_BYTES = 16 * 1024;
+const WAIT_MIN_RESULT_BYTES = 512;
+const RESULT_HEADROOM_SHARE = 0.5;
+const ESTIMATED_BYTES_PER_TOKEN = 4;
+const AUTOMATIC_BATCH_TRUNCATION_NOTICE =
+  "\n\n[Automatic subagent result batch truncated at the 48 KiB total limit.]";
 
 interface SpawnResultDetails {
   readonly id?: string;
@@ -156,12 +182,24 @@ interface SubagentResultDetails {
   readonly id?: string;
   readonly title?: string;
   readonly status?: SubagentSnapshot["status"];
+  readonly outcome?: SubagentSnapshot["outcome"];
+  readonly worktreeBranch?: string;
+  readonly elapsed?: string;
+  readonly artifactSaveFailed?: boolean;
+  readonly fullResultSaved?: boolean;
   readonly count?: number;
   readonly results?: ReadonlyArray<{
     readonly id: string;
     readonly title: string;
     readonly status: SubagentSnapshot["status"];
+    readonly outcome?: SubagentSnapshot["outcome"];
+    readonly worktreeBranch?: string;
+    readonly elapsed?: string;
+    readonly artifactSaveFailed?: boolean;
+    readonly fullResultSaved?: boolean;
   }>;
+  /** Display-only projection for the custom message renderer. */
+  readonly displayContent?: string;
 }
 
 interface SubagentResultEntryData {
@@ -189,56 +227,171 @@ function describeSubagent(snap: SubagentSnapshot) {
   return `${snap.id} [${snap.status}] "${snap.title}" (${details.join(", ")})`;
 }
 
-function truncatedOutput(
+export function truncatedOutput(
   snap: SubagentSnapshot,
   maxBytes = SUBAGENT_OUTPUT_MAX_BYTES,
+  writeArtifact: (content: string) => string = (content) =>
+    persistResultArtifact(getAgentDir(), content),
 ): string {
   const output = snap.finalText || "(no output)";
-  const truncation = truncateHead(output, {
+  return projectResult(output, {
+    maxBytes: Math.min(maxBytes, DEFAULT_MAX_BYTES),
+    maxLines: Math.min(600, DEFAULT_MAX_LINES),
+    writeArtifact,
+  }).text;
+}
+
+function projectSubagentOutput(
+  snap: SubagentSnapshot,
+  maxBytes: number,
+): ResultProjection {
+  const output = snap.finalText || "(no output)";
+  return projectResult(output, {
     maxBytes: Math.min(maxBytes, DEFAULT_MAX_BYTES),
     maxLines: Math.min(600, DEFAULT_MAX_LINES),
+    writeArtifact: (content) => persistResultArtifact(getAgentDir(), content),
   });
-  let text = truncation.content;
-  if (truncation.truncated) {
-    text += `\n\n[Output truncated: ${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)} shown. Full transcript in session file: ${snap.meta.sessionFilePath ?? "?"}]`;
-  }
-  return text;
+}
+
+type OutputProjection = Pick<
+  ResultProjection,
+  "text" | "artifactPath" | "artifactSaveFailed"
+>;
+
+function normalizeProjection(
+  output: string | OutputProjection,
+): OutputProjection {
+  return typeof output === "string" ? { text: output } : output;
+}
+
+function boundAutomaticResultBatch(content: string) {
+  const probe = truncateHead(content, {
+    maxBytes: AUTOMATIC_OUTPUT_MAX_BYTES,
+    maxLines: Number.MAX_SAFE_INTEGER,
+  });
+  if (!probe.truncated) return content;
+
+  const noticeBytes = Buffer.byteLength(
+    AUTOMATIC_BATCH_TRUNCATION_NOTICE,
+    "utf8",
+  );
+  const bounded = truncateHead(content, {
+    maxBytes: Math.max(0, AUTOMATIC_OUTPUT_MAX_BYTES - noticeBytes),
+    maxLines: Number.MAX_SAFE_INTEGER,
+  });
+  return `${bounded.content}${AUTOMATIC_BATCH_TRUNCATION_NOTICE}`;
 }
 
 export function createSubagentResultDispatcher(
   pi: ExtensionAPI,
-  outputFor: (snap: SubagentSnapshot) => string = truncatedOutput,
+  outputFor: (
+    snap: SubagentSnapshot,
+    maxBytes: number,
+  ) => string | OutputProjection = projectSubagentOutput,
+  getContextUsage: () => ParentContextUsage | undefined = () => undefined,
 ) {
   return (snaps: readonly SubagentSnapshot[]) => {
     if (snaps.length === 0) return;
-    const content = snaps
-      .map((snap) =>
-        buildSubagentResultMessage({
-          id: snap.id,
-          title: snap.title,
-          status: snap.status,
-          errorText: snap.errorText,
-          output: outputFor(snap),
-        }),
-      )
-      .join("\n\n");
+    const emptyMessages = snaps.map((snap) =>
+      buildSubagentResultMessage({
+        id: snap.id,
+        title: snap.title,
+        status: snap.status,
+        errorText: snap.errorText,
+        output: "",
+      }),
+    );
+    const wrapperBytes =
+      emptyMessages.reduce(
+        (sum, message) => sum + Buffer.byteLength(message, "utf8"),
+        0,
+      ) +
+      Math.max(0, snaps.length - 1) * 2;
+    const projectionBatchBytes = Math.max(
+      0,
+      AUTOMATIC_OUTPUT_MAX_BYTES - wrapperBytes,
+    );
+    const allocation = allocateResultBudgets(
+      snaps.map((snap) =>
+        Buffer.byteLength(snap.finalText || "(no output)", "utf8"),
+      ),
+      getContextUsage(),
+      {
+        maxBatchBytes: projectionBatchBytes,
+        maxResultBytes: SUBAGENT_OUTPUT_MAX_BYTES,
+        minResultBytes: AUTOMATIC_MIN_RESULT_BYTES,
+        headroomShare: RESULT_HEADROOM_SHARE,
+        estimatedBytesPerToken: ESTIMATED_BYTES_PER_TOKEN,
+        fixedBytes: wrapperBytes,
+      },
+    );
+    const projections = snaps.map((snap, index) =>
+      normalizeProjection(outputFor(snap, allocation.budgets[index]!)),
+    );
+    const outputs = projections.map((projection) => projection.text);
+    const displayContent = boundAutomaticResultBatch(
+      snaps
+        .map((snap, index) =>
+          buildSubagentResultDisplayMessage({
+            id: snap.id,
+            title: snap.title,
+            status: snap.status,
+            errorText: snap.errorText,
+            output: outputs[index]!,
+          }),
+        )
+        .join("\n\n"),
+    );
+    const content = boundAutomaticResultBatch(
+      snaps
+        .map((snap, index) =>
+          buildSubagentResultMessage({
+            id: snap.id,
+            title: snap.title,
+            status: snap.status,
+            errorText: snap.errorText,
+            output: outputs[index]!,
+          }),
+        )
+        .join("\n\n"),
+    );
     const details: SubagentResultDetails =
       snaps.length === 1
         ? {
             id: snaps[0]!.id,
             title: snaps[0]!.title,
             status: snaps[0]!.status,
+            ...(snaps[0]!.outcome ? { outcome: snaps[0]!.outcome } : {}),
+            ...(snaps[0]!.worktreeBranch
+              ? { worktreeBranch: snaps[0]!.worktreeBranch }
+              : {}),
+            elapsed: formatElapsed(snaps[0]!),
+            ...(projections[0]!.artifactPath ? { fullResultSaved: true } : {}),
+            ...(projections[0]!.artifactSaveFailed
+              ? { artifactSaveFailed: true }
+              : {}),
           }
         : {
             count: snaps.length,
-            results: snaps.map((snap) => ({
+            results: snaps.map((snap, index) => ({
               id: snap.id,
               title: snap.title,
               status: snap.status,
+              ...(snap.outcome ? { outcome: snap.outcome } : {}),
+              ...(snap.worktreeBranch
+                ? { worktreeBranch: snap.worktreeBranch }
+                : {}),
+              elapsed: formatElapsed(snap),
+              ...(projections[index]!.artifactPath
+                ? { fullResultSaved: true }
+                : {}),
+              ...(projections[index]!.artifactSaveFailed
+                ? { artifactSaveFailed: true }
+                : {}),
             })),
           };
     pi.appendEntry<SubagentResultEntryData>("subagent-result", {
-      content,
+      content: displayContent,
       details,
     });
     pi.sendMessage(
@@ -246,7 +399,7 @@ export function createSubagentResultDispatcher(
         customType: "subagent-result",
         content,
         display: false,
-        details,
+        details: { ...details, displayContent },
       },
       { deliverAs: "followUp", triggerTurn: true },
     );
@@ -259,36 +412,52 @@ function renderSubagentResult(
   content: string,
   details: SubagentResultDetails,
   expanded: boolean,
+  resultDisplay: DetailDisplay,
   theme: SubagentResultTheme,
 ) {
-  if (!expanded && loadSetupConfig().ui.subagentResultDisplay === "compact") {
-    const results = details.results?.length
-      ? details.results
-      : details.id
-        ? [
-            {
-              id: details.id,
-              title: details.title,
-              status: details.status,
-            },
-          ]
-        : [];
-    return new Text(buildWaitResultPreview(content, { results }, theme), 0, 0);
+  const displayContent = sanitizeText(
+    details.displayContent ?? stripSubagentResultTransportInstruction(content),
+  );
+  const results = details.results?.length
+    ? details.results
+    : details.id
+      ? [
+          {
+            id: details.id,
+            title: details.title,
+            status: details.status,
+            outcome: details.outcome,
+            worktreeBranch: details.worktreeBranch,
+            elapsed: details.elapsed,
+            artifactSaveFailed: details.artifactSaveFailed,
+            fullResultSaved: details.fullResultSaved,
+          },
+        ]
+      : [];
+  if (!expanded && resultDisplay === "compact") {
+    return renderWaitResultPreview(displayContent, { results }, theme);
   }
 
-  const failed = details.status === "error";
-  const icon = failed ? theme.fg("error", "x") : theme.fg("success", "■");
-  const header =
-    `${icon} ` +
-    theme.fg("accent", theme.bold(`subagent ${details.id ?? "?"}`)) +
-    theme.fg(
-      "muted",
-      ` · ${details.title ?? ""} · ${failed ? "failed" : "finished"}`,
-    );
+  const failed = results.some((result) => result.status === "error");
+  const batched = results.length > 1;
+  const icon = failed ? theme.fg("error", "x") : theme.fg("success", "✓");
+  const header = batched
+    ? `${icon} ${theme.fg("accent", theme.bold(`${results.length} subagents`))}${theme.fg("muted", ` · ${failed ? `${results.filter((result) => result.status === "error").length} failed` : "finished"}`)}`
+    : `${icon} ` +
+      theme.fg(
+        "accent",
+        theme.bold(`subagent ${sanitizeText(details.id ?? "?")}`),
+      ) +
+      theme.fg(
+        "muted",
+        ` · ${sanitizeText(details.title ?? "")} · ${failed ? "failed" : "finished"}${details.elapsed ? ` · ${sanitizeText(details.elapsed)}` : ""}`,
+      );
 
-  // Remove only the summary line. The following Error line (when present)
-  // is part of the actual result and must remain visible.
-  const body = content.split("\n").slice(1).join("\n").trim();
+  // Remove only the single-result summary line. Error lines and batched result
+  // summaries are part of the display projection and must remain visible.
+  const body = batched
+    ? displayContent.trim()
+    : displayContent.split("\n").slice(1).join("\n").trim();
   const md = new Markdown(body, 0, 0, getMarkdownTheme());
   const container = new Text(header, 0, 0);
   return {
@@ -303,9 +472,23 @@ function renderSubagentResult(
   };
 }
 
-export default function (pi: ExtensionAPI) {
+interface SubagentExtensionOptions {
+  readonly getResultDisplay?: () => DetailDisplay;
+}
+
+export default function (
+  pi: ExtensionAPI,
+  options: SubagentExtensionOptions = {},
+) {
+  const getResultDisplay =
+    options.getResultDisplay ??
+    (() => loadSetupConfig().ui.subagentResultDisplay);
   let runtime: SubagentRuntime | undefined;
   let managerPromise: Promise<SubagentManagerShape> | undefined;
+  let restoredIdCounters: SubagentIdCounters = {
+    modelCounter: 0,
+    btwCounter: 0,
+  };
   let sessionContext: ExtensionContext | undefined;
   let ui: ExtensionUIContext | undefined;
   let unsubStatus: (() => void) | undefined;
@@ -315,13 +498,20 @@ export default function (pi: ExtensionAPI) {
    */
   let settledAcknowledgedAt = 0;
   const stripState = new BelowEditorStripState();
+  const statusWriter = createStatusWriter("subagents");
   const widgetKey = "subagent-navigation";
   let navigationManager: SubagentManagerShape | undefined;
+  let unregisterWebCapability: (() => void) | undefined;
   let widgetVisible = false;
+  let widgetEntryKey: string | undefined;
   let requestWidgetRender: (() => void) | undefined;
   let navigationLayerRegistered = false;
   let dashboardOpen = false;
-  const dispatchResults = createSubagentResultDispatcher(pi);
+  const dispatchResults = createSubagentResultDispatcher(
+    pi,
+    projectSubagentOutput,
+    () => sessionContext?.getContextUsage(),
+  );
   const resultDelivery = createSubagentResultDelivery<SubagentSnapshot>({
     isIdle: () => sessionContext?.isIdle() === true,
     // Every unconsumed fire-and-forget result must reach the parent. The
@@ -329,23 +519,36 @@ export default function (pi: ExtensionAPI) {
     deliver: dispatchResults,
   });
   pi.on("agent_settled", () => resultDelivery.parentSettled());
-  const hideLifecycleTools = () =>
+  const registerStableToolFamily = () =>
     patchOwnedTools(pi, "subagents", {
-      disable: OPENPI_TOOL_SURFACE.subagents.deferred,
-    });
-  const showLifecycleTools = () =>
-    patchOwnedTools(pi, "subagents", {
-      enable: OPENPI_TOOL_SURFACE.subagents.deferred,
+      enable: OPENPI_TOOL_SURFACE.subagents.entry,
     });
 
-  const getRuntime = () => (runtime ??= createSubagentRuntime());
+  const getRuntime = () =>
+    (runtime ??= createSubagentRuntime({
+      initialModelCounter: restoredIdCounters.modelCounter,
+      initialBtwCounter: restoredIdCounters.btwCounter,
+    }));
+
+  const persistId = (id: string) =>
+    pi.appendEntry(SUBAGENT_ID_WATERMARK_ENTRY_TYPE, subagentIdWatermark(id));
 
   /** Resolve the manager service once per runtime and wire the extension hooks. */
   const getManager = () => {
+    const scope = sessionContext?.sessionManager;
     managerPromise ??= getRuntime()
       .runPromise(SubagentManager)
       .then((manager) => {
         navigationManager = manager;
+        unregisterWebCapability?.();
+        unregisterWebCapability =
+          scope && sessionContext?.sessionManager === scope
+            ? registerWebCapability(scope, {
+                kind: "subagents",
+                snapshot: () => projectSubagentCapability(manager.view.list()),
+                subscribe: (listener) => manager.view.subscribe(listener),
+              })
+            : undefined;
         manager.view.setOnSettled(onSettled);
         unsubStatus?.();
         unsubStatus = manager.view.subscribe(() => updateStatus(manager));
@@ -366,10 +569,19 @@ export default function (pi: ExtensionAPI) {
   const updateSubagentWidget = () => {
     const ctx = sessionContext;
     if (!ctx || ctx.mode !== "tui") return;
-    const visible = Boolean(stripEntry());
-    if (visible === widgetVisible) return;
+    const entry = stripEntry();
+    const visible = Boolean(entry);
+    const entryKey = subagentStripEntryKey(entry);
+    if (visible === widgetVisible) {
+      if (visible && entryKey !== widgetEntryKey) {
+        widgetEntryKey = entryKey;
+        requestWidgetRender?.();
+      }
+      return;
+    }
     if (!visible) {
       stripState.focused = false;
+      widgetEntryKey = undefined;
       requestWidgetRender = undefined;
       ctx.ui.setWidget(widgetKey, undefined);
       widgetVisible = false;
@@ -384,6 +596,7 @@ export default function (pi: ExtensionAPI) {
       { placement: "belowEditor" },
     );
     widgetVisible = true;
+    widgetEntryKey = entryKey;
   };
 
   const updateStatus = (manager: SubagentManagerShape) => {
@@ -392,9 +605,12 @@ export default function (pi: ExtensionAPI) {
       manager.view.list(),
       settledAcknowledgedAt,
     );
-    ui.setStatus(
-      "subagents",
-      hasActivity(counts)
+    // In the TUI the below-editor strip already reports the same activity and
+    // carries the manage affordance, so a footer status line would repeat it.
+    const tui = sessionContext?.mode === "tui";
+    statusWriter.write(
+      ui,
+      !tui && hasActivity(counts)
         ? formatActivityStatus(ui.theme, "subagents", counts)
         : undefined,
     );
@@ -493,8 +709,11 @@ export default function (pi: ExtensionAPI) {
   };
 
   pi.on("session_start", (_event, ctx) => {
+    restoredIdCounters = restoreSubagentIdCounters(
+      ctx.sessionManager.getBranch(),
+    );
     refreshAgentTypes(ctx.cwd, ctx.isProjectTrusted());
-    hideLifecycleTools();
+    registerStableToolFamily();
     sessionContext = ctx;
     settledAcknowledgedAt = 0;
     if (ctx.hasUI) ui = ctx.ui;
@@ -524,16 +743,20 @@ export default function (pi: ExtensionAPI) {
     resultDelivery.clear();
     unsubStatus?.();
     unsubStatus = undefined;
+    unregisterWebCapability?.();
+    unregisterWebCapability = undefined;
     try {
       ui?.setStatus("subagents", undefined);
       sessionContext?.ui.setWidget(widgetKey, undefined);
     } catch {
       // UI may already be disposed.
     }
+    statusWriter.reset();
     sessionContext = undefined;
     ui = undefined;
     navigationManager = undefined;
     widgetVisible = false;
+    widgetEntryKey = undefined;
     requestWidgetRender = undefined;
     stripState.focused = false;
     dashboardOpen = false;
@@ -592,57 +815,22 @@ export default function (pi: ExtensionAPI) {
     agentTypes = loaded.agentTypes;
     agentTypeDiagnostics = loaded.diagnostics;
     agentTypeList = [...agentTypes.values()];
-    subagentSpawnTool.description =
-      buildSubagentSpawnToolDescription(agentTypeList);
-    subagentSpawnTool.parameters = createSubagentSpawnParameters();
+    const surface = createSubagentSpawnToolSurface(agentTypeList);
+    subagentSpawnTool.description = surface.description;
+    subagentSpawnTool.parameters = surface.parameters;
     registerSubagentSpawnTool();
   };
 
   // --- Tools -------------------------------------------------------------
 
-  const createSubagentSpawnParameters = () =>
-    Type.Object({
-      agent_type: createAgentTypeParameterSchema(agentTypeList),
-      prompt: Type.String({
-        description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.prompt,
-      }),
-      name: Type.String({
-        description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.name,
-      }),
-      harness: Type.Optional(
-        StringEnum(BACKEND_NAMES, {
-          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.harness,
-        }),
-      ),
-      working_dir: Type.Optional(
-        Type.String({
-          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.workingDir,
-        }),
-      ),
-      isolation: Type.Optional(
-        StringEnum(["worktree"] as const, {
-          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.isolation,
-        }),
-      ),
-      model: Type.Optional(
-        Type.String({
-          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.model,
-        }),
-      ),
-      reasoning_effort: Type.Optional(
-        StringEnum(REASONING_EFFORTS, {
-          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.reasoningEffort,
-        }),
-      ),
-    });
+  const initialSpawnSurface = createSubagentSpawnToolSurface(agentTypeList);
 
   const subagentSpawnTool = defineTool({
     name: "subagent_spawn",
     label: "Spawn Subagent",
-    description: buildSubagentSpawnToolDescription(agentTypeList),
+    ...initialSpawnSurface,
     promptSnippet: SUBAGENT_SPAWN_PROMPT_SNIPPET,
     promptGuidelines: SUBAGENT_SPAWN_PROMPT_GUIDELINES,
-    parameters: createSubagentSpawnParameters(),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       // Only one backend exists; harness is optional and defaults to it.
       const harness = params.harness ?? BACKEND_NAMES[0];
@@ -764,11 +952,40 @@ export default function (pi: ExtensionAPI) {
       } catch (error) {
         // The session scope owns reclamation, but it never opened, so this
         // worktree would otherwise be orphaned on disk.
-        if (worktree) await reclaimWorktree(cwd, worktree).catch(() => {});
+        if (worktree) {
+          const spawnError =
+            error instanceof Error ? error.message : String(error);
+          let cleanupWarning: string | undefined;
+          let cleanupError: unknown;
+          try {
+            const cleanup = await reclaimWorktree(cwd, worktree);
+            cleanupWarning = formatWorktreeCleanupWarning(
+              cleanup,
+              worktree.path,
+            );
+          } catch (failure) {
+            cleanupError = failure;
+          }
+          if (cleanupError) {
+            const reason =
+              cleanupError instanceof Error
+                ? cleanupError.message
+                : String(cleanupError);
+            throw new Error(
+              `${spawnError}; worktree cleanup failed: ${reason}; checkout preserved at ${worktree.path}`,
+              { cause: error },
+            );
+          }
+          if (cleanupWarning) {
+            throw new Error(
+              `${spawnError}; worktree cleanup warning: ${cleanupWarning}`,
+              { cause: error },
+            );
+          }
+        }
         throw error;
       }
-
-      showLifecycleTools();
+      persistId(snap.id);
 
       return {
         content: [
@@ -813,8 +1030,11 @@ export default function (pi: ExtensionAPI) {
       const meta = [details.harness, details.model]
         .filter(Boolean)
         .join(" \u00b7 ");
+      // A spawn is an event, not a state, so it speaks in the activity rows'
+      // verb language ("Wrote" / "Ran" / "Spawned") rather than a glyph; the
+      // strip's spinner carries the running state from here on.
       return new Text(
-        `${theme.fg("success", "\u25cf")} ${theme.bold(details.title ?? details.id)} ${theme.fg("dim", meta)}`,
+        `${theme.fg("toolTitle", "Spawned")}  ${theme.bold(details.title ?? details.id)} ${theme.fg("dim", meta)}`,
         0,
         0,
       );
@@ -834,7 +1054,7 @@ export default function (pi: ExtensionAPI) {
         description: SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS.ids,
       }),
     }),
-    async execute(_toolCallId, params, signal, onUpdate) {
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const manager = await getManager();
       const ids = [...new Set(params.ids)];
       if (ids.length === 0)
@@ -870,33 +1090,71 @@ export default function (pi: ExtensionAPI) {
       // deferred automatic delivery now that the tool is returning the result.
       resultDelivery.consume(ids);
 
-      const sections: string[] = [];
-      let remainingBytes = WAIT_OUTPUT_MAX_BYTES;
-      for (const id of ids) {
+      const entries: Array<
+        | { readonly id: string; readonly section: string }
+        | {
+            readonly id: string;
+            readonly snap: SubagentSnapshot;
+            readonly header: string;
+          }
+      > = ids.map((id) => {
         const snap = manager.view.get(id);
-        if (!snap) {
-          sections.push(`## ${id}\n\n(no longer tracked)`);
-          continue;
-        }
+        if (!snap) return { id, section: `## ${id}\n\n(no longer tracked)` };
         const verb = snap.status === "error" ? "failed" : "finished";
-        let section = `## ${snap.id} "${snap.title}" ${verb}`;
-        if (snap.errorText) section += `\nError: ${snap.errorText}`;
-        const headerBytes = Buffer.byteLength(section, "utf8") + 2;
-        const outputBudget = Math.max(
-          512,
-          Math.min(WAIT_PER_AGENT_MAX_BYTES, remainingBytes - headerBytes),
+        let header = `## ${snap.id} "${snap.title}" ${verb}`;
+        if (snap.errorText) header += `\nError: ${snap.errorText}`;
+        return { id, snap, header };
+      });
+      const separatorsBytes = Math.max(0, entries.length - 1) * 7;
+      const fixedBytes =
+        separatorsBytes +
+        entries.reduce(
+          (sum, entry) =>
+            sum +
+            Buffer.byteLength(
+              "section" in entry ? entry.section : `${entry.header}\n\n`,
+              "utf8",
+            ),
+          0,
         );
-        section += `\n\n${truncatedOutput(snap, outputBudget)}`;
-        const sectionBytes = Buffer.byteLength(section, "utf8");
-        if (sectionBytes > remainingBytes) {
-          sections.push(
-            `## ${snap.id} "${snap.title}"\n\n[omitted: total wait output limit reached]`,
-          );
-          break;
-        }
-        sections.push(section);
-        remainingBytes -= sectionBytes;
-      }
+      const resultEntries = entries.filter(
+        (
+          entry,
+        ): entry is {
+          readonly id: string;
+          readonly snap: SubagentSnapshot;
+          readonly header: string;
+        } => "snap" in entry,
+      );
+      const projectionBatchBytes = Math.max(
+        WAIT_MIN_RESULT_BYTES * resultEntries.length,
+        WAIT_OUTPUT_MAX_BYTES - fixedBytes,
+      );
+      const allocation = allocateResultBudgets(
+        resultEntries.map(({ snap }) =>
+          Buffer.byteLength(snap.finalText || "(no output)", "utf8"),
+        ),
+        ctx.getContextUsage(),
+        {
+          maxBatchBytes: projectionBatchBytes,
+          maxResultBytes: WAIT_PER_AGENT_MAX_BYTES,
+          minResultBytes: WAIT_MIN_RESULT_BYTES,
+          headroomShare: RESULT_HEADROOM_SHARE,
+          estimatedBytesPerToken: ESTIMATED_BYTES_PER_TOKEN,
+          fixedBytes,
+        },
+      );
+      let resultIndex = 0;
+      const artifactSaveFailures = new Set<string>();
+      const fullResultsSaved = new Set<string>();
+      const sections = entries.map((entry) => {
+        if ("section" in entry) return entry.section;
+        const outputBudget = allocation.budgets[resultIndex++]!;
+        const projection = projectSubagentOutput(entry.snap, outputBudget);
+        if (projection.artifactSaveFailed) artifactSaveFailures.add(entry.id);
+        if (projection.artifactPath) fullResultsSaved.add(entry.id);
+        return `${entry.header}\n\n${projection.text}`;
+      });
 
       const combined = sections.join("\n\n---\n\n");
       const bounded = truncateHead(combined, {
@@ -911,7 +1169,20 @@ export default function (pi: ExtensionAPI) {
         details: {
           results: ids.map((id) => {
             const snap = manager.view.get(id);
-            return { id, title: snap?.title, status: snap?.status };
+            return {
+              id,
+              title: snap?.title,
+              status: snap?.status,
+              ...(snap?.outcome ? { outcome: snap.outcome } : {}),
+              ...(snap?.worktreeBranch
+                ? { worktreeBranch: snap.worktreeBranch }
+                : {}),
+              ...(snap ? { elapsed: formatElapsed(snap) } : {}),
+              ...(fullResultsSaved.has(id) ? { fullResultSaved: true } : {}),
+              ...(artifactSaveFailures.has(id)
+                ? { artifactSaveFailed: true }
+                : {}),
+            };
           }),
         },
       };
@@ -936,7 +1207,7 @@ export default function (pi: ExtensionAPI) {
       return renderWaitResult(
         content,
         result.details as WaitResultDetails | undefined,
-        expanded || loadSetupConfig().ui.subagentResultDisplay === "full",
+        expanded || getResultDisplay() === "full",
         theme,
       );
     },
@@ -1131,6 +1402,7 @@ export default function (pi: ExtensionAPI) {
         content,
         (message.details ?? {}) as SubagentResultDetails,
         expanded,
+        getResultDisplay(),
         theme,
       );
     },
@@ -1143,6 +1415,7 @@ export default function (pi: ExtensionAPI) {
         entry.data?.content ?? "",
         entry.data?.details ?? {},
         expanded,
+        getResultDisplay(),
         theme,
       ),
   );
@@ -1152,11 +1425,12 @@ export default function (pi: ExtensionAPI) {
     (entry, _options, theme) => {
       const data = entry.data;
       const failed = data?.status === "error";
+      const icon = failed ? theme.fg("error", "x") : theme.fg("success", "✓");
       return new Text(
-        `${theme.fg(failed ? "error" : "success", "\u25cf")} ` +
+        `${icon} ${theme.fg("accent", data?.title ?? "?")}` +
           theme.fg(
-            "muted",
-            `Agent "${data?.title ?? "?"}" ${failed ? "failed" : "finished"} \u00b7 ${data?.elapsed ?? "?"}`,
+            "dim",
+            ` ${failed ? "failed" : "finished"} · ${data?.elapsed ?? "?"}`,
           ),
         1,
         0,
@@ -1169,7 +1443,7 @@ export default function (pi: ExtensionAPI) {
     (entry, { expanded }, theme) => {
       const data = entry.data;
       const failed = data?.status === "error";
-      const icon = failed ? theme.fg("error", "x") : theme.fg("success", "■");
+      const icon = failed ? theme.fg("error", "x") : theme.fg("success", "✓");
       const header =
         `${icon} ` +
         theme.fg("accent", theme.bold(`by the way · ${data?.title ?? "?"}`)) +
@@ -1184,7 +1458,7 @@ export default function (pi: ExtensionAPI) {
         .filter(Boolean)
         .join("\n\n");
 
-      if (expanded || loadSetupConfig().ui.subagentResultDisplay === "full") {
+      if (expanded || getResultDisplay() === "full") {
         const md = new Markdown(body, 0, 0, getMarkdownTheme());
         const container = new Text(header, 0, 0);
         return {
@@ -1253,6 +1527,7 @@ export default function (pi: ExtensionAPI) {
       );
       return;
     }
+    persistId(snap.id);
 
     await openSubagentTakeover(ctx, manager.view, snap.id, {
       badge: "by the way",