@tt-a1i/openpi 0.4.0 → 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
@@ -44,10 +45,12 @@ import {
 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,
@@ -67,13 +70,22 @@ import {
   planModeAllowsDeclaredTools,
   planModeChildTools,
 } from "../shared/plan-mode-state.ts";
-import { loadSetupConfig } from "../shared/setup-config.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";
@@ -81,9 +93,9 @@ import {
   normalizeSubagentTitle,
   SubagentStripWidget,
   selectSubagentStripEntry,
+  subagentStripEntryKey,
 } from "./navigation.ts";
 import {
-  type AgentType,
   formatAgentTypeDiagnostics,
   loadAgentTypes,
   roleModelForAgentType,
@@ -104,6 +116,7 @@ import {
 } from "./src/id-sequence.ts";
 import { SubagentManager, type SubagentManagerShape } from "./src/manager.ts";
 import {
+  buildSubagentResultDisplayMessage,
   buildSubagentResultMessage,
   buildSubagentSendResult,
   buildSubagentSpawnResult,
@@ -119,12 +132,13 @@ import {
   SUBAGENT_SPAWN_PROMPT_SNIPPET,
   SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS,
   SUBAGENT_WAIT_TOOL_DESCRIPTION,
+  stripSubagentResultTransportInstruction,
 } from "./src/prompt.ts";
-import { persistResultArtifact, projectResult } from "./src/result-artifact.ts";
 import {
-  allocateResultBudgets,
-  type ParentContextUsage,
-} from "../shared/result-budget.ts";
+  persistResultArtifact,
+  projectResult,
+  type ResultProjection,
+} from "./src/result-artifact.ts";
 import { createSubagentResultDelivery } from "./src/result-delivery.ts";
 import {
   createSubagentRuntime,
@@ -133,8 +147,8 @@ import {
 } from "./src/runtime.ts";
 import { openSubagentPicker, openSubagentTakeover } from "./src/ui/takeover.ts";
 import {
-  buildWaitResultPreview,
   renderWaitResult,
+  renderWaitResultPreview,
   type WaitResultDetails,
 } from "./src/ui/wait-result.ts";
 
@@ -146,6 +160,8 @@ 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;
@@ -166,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 {
@@ -213,12 +241,53 @@ export function truncatedOutput(
   }).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),
+  });
+}
+
+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,
     maxBytes: number,
-  ) => string = truncatedOutput,
+  ) => string | OutputProjection = projectSubagentOutput,
   getContextUsage: () => ParentContextUsage | undefined = () => undefined,
 ) {
   return (snaps: readonly SubagentSnapshot[]) => {
@@ -239,7 +308,7 @@ export function createSubagentResultDispatcher(
       ) +
       Math.max(0, snaps.length - 1) * 2;
     const projectionBatchBytes = Math.max(
-      AUTOMATIC_MIN_RESULT_BYTES * snaps.length,
+      0,
       AUTOMATIC_OUTPUT_MAX_BYTES - wrapperBytes,
     );
     const allocation = allocateResultBudgets(
@@ -256,34 +325,73 @@ export function createSubagentResultDispatcher(
         fixedBytes: wrapperBytes,
       },
     );
-    const content = snaps
-      .map((snap, index) =>
-        buildSubagentResultMessage({
-          id: snap.id,
-          title: snap.title,
-          status: snap.status,
-          errorText: snap.errorText,
-          output: outputFor(snap, allocation.budgets[index]!),
-        }),
-      )
-      .join("\n\n");
+    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(
@@ -291,7 +399,7 @@ export function createSubagentResultDispatcher(
         customType: "subagent-result",
         content,
         display: false,
-        details,
+        details: { ...details, displayContent },
       },
       { deliverAs: "followUp", triggerTurn: true },
     );
@@ -304,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 failed = results.some((result) => result.status === "error");
+  const batched = results.length > 1;
   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 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 {
@@ -348,7 +472,17 @@ 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 = {
@@ -364,15 +498,18 @@ 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,
-    truncatedOutput,
+    projectSubagentOutput,
     () => sessionContext?.getContextUsage(),
   );
   const resultDelivery = createSubagentResultDelivery<SubagentSnapshot>({
@@ -398,10 +535,20 @@ export default function (pi: ExtensionAPI) {
 
   /** 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));
@@ -422,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;
@@ -440,6 +596,7 @@ export default function (pi: ExtensionAPI) {
       { placement: "belowEditor" },
     );
     widgetVisible = true;
+    widgetEntryKey = entryKey;
   };
 
   const updateStatus = (manager: SubagentManagerShape) => {
@@ -451,8 +608,8 @@ export default function (pi: ExtensionAPI) {
     // 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";
-    ui.setStatus(
-      "subagents",
+    statusWriter.write(
+      ui,
       !tui && hasActivity(counts)
         ? formatActivityStatus(ui.theme, "subagents", counts)
         : undefined,
@@ -586,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;
@@ -791,7 +952,37 @@ 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;
       }
       persistId(snap.id);
@@ -954,10 +1145,15 @@ export default function (pi: ExtensionAPI) {
         },
       );
       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++]!;
-        return `${entry.header}\n\n${truncatedOutput(entry.snap, outputBudget)}`;
+        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");
@@ -973,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 }
+                : {}),
+            };
           }),
         },
       };
@@ -998,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,
       );
     },
@@ -1193,6 +1402,7 @@ export default function (pi: ExtensionAPI) {
         content,
         (message.details ?? {}) as SubagentResultDetails,
         expanded,
+        getResultDisplay(),
         theme,
       );
     },
@@ -1205,6 +1415,7 @@ export default function (pi: ExtensionAPI) {
         entry.data?.content ?? "",
         entry.data?.details ?? {},
         expanded,
+        getResultDisplay(),
         theme,
       ),
   );
@@ -1247,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 {

package/extensions/subagents/navigation.ts

@@ -19,6 +19,11 @@ export interface SubagentStripEntry {
   counts: ActivityCounts;
 }
 
+/** Changes only when the strip needs an immediate lifecycle repaint. */
+export function subagentStripEntryKey(entry: SubagentStripEntry | undefined) {
+  return entry ? `${entry.snapshot.id}:${entry.snapshot.status}` : undefined;
+}
+
 function cleanLine(value: string) {
   return sanitizeTerminalText(value).replace(/\s+/g, " ").trim();
 }
@@ -71,9 +76,11 @@ function statusGlyph(snapshot: SubagentSnapshot, theme: Theme, now: number) {
   return theme.fg("error", "✗");
 }
 
+const SUBAGENT_STRIP_INTERVAL_MS = 500;
+
 /** One-line subagent manager entry with the same affordance as Workflow. */
 export class SubagentStripWidget {
-  private readonly timer: ReturnType<typeof setInterval>;
+  private timer: ReturnType<typeof setInterval> | undefined;
   private readonly tui: TUI;
   private readonly theme: Theme;
   private readonly strip: BelowEditorStripState;
@@ -89,17 +96,39 @@ export class SubagentStripWidget {
     this.theme = theme;
     this.strip = strip;
     this.getEntry = getEntry;
-    this.timer = setInterval(() => this.tui.requestRender(), 500);
-    this.timer.unref?.();
+    this.syncSpinner();
   }
 
   dispose() {
-    clearInterval(this.timer);
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
   }
 
-  invalidate() {}
+  invalidate() {
+    this.syncSpinner();
+  }
+
+  private syncSpinner() {
+    if (this.getEntry()?.snapshot.status === "running") {
+      if (this.timer) return;
+      const timer = setInterval(() => {
+        if (this.timer !== timer) return;
+        if (this.getEntry()?.snapshot.status !== "running") {
+          clearInterval(timer);
+          this.timer = undefined;
+        }
+        this.tui.requestRender();
+      }, SUBAGENT_STRIP_INTERVAL_MS);
+      this.timer = timer;
+      timer.unref?.();
+      return;
+    }
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
 
   render(width: number) {
+    this.syncSpinner();
     const entry = this.getEntry();
     if (!entry || width <= 0) return [];
     const { snapshot, counts } = entry;

package/extensions/subagents/src/backend.ts

@@ -5,11 +5,11 @@
  * on it rather than on the pi session directly.
  *
  * - pi (./backends/pi.ts): in-process `createAgentSession()` via the pi SDK.
- * - stub (./backends/stub.ts): scripted sessions, test-only.
  */
 
 import type { Effect, Scope, Stream } from "effect";
 import { Context } from "effect";
+import type { AgentToolRenderer } from "../../shared/agent-tool-renderer.ts";
 import type {
   BackendName,
   SendError,
@@ -19,6 +19,13 @@ import type {
   SubagentMeta,
 } from "./domain.ts";
 
+export interface SubagentCleanupReceipt {
+  /** True when the session/worktree state could not be proven quiescent. */
+  readonly uncertain: boolean;
+  /** Bounded operator-facing explanation of the cleanup result. */
+  readonly message: string;
+}
+
 /**
  * A live subagent session. The manager is the single consumer of `events`;
  * it folds them into the `SubagentSnapshot` everything else reads.
@@ -42,6 +49,10 @@ export interface SubagentSession {
    * this with a timeout and fall back to closing the session scope.
    */
   readonly interrupt: Effect.Effect<void>;
+  /** Ephemeral Pi-native tool projection for the operator-facing child page. */
+  readonly toolRenderer?: AgentToolRenderer;
+  /** Cleanup receipt populated when scope teardown cannot prove safety. */
+  readonly cleanupReceipt?: () => SubagentCleanupReceipt | undefined;
 }
 
 export interface SubagentBackend {