pi-subagent-in-memory 0.1.6 → 0.2.2

package/README.md

@@ -23,11 +23,25 @@ Spawns an in-process subagent session using pi's `createAgentSession` SDK. The s
 | `provider` | string | | LLM provider (e.g. `anthropic`, `google`, `openai`) |
 | `model` | string | | Model ID. Supports `provider/model` format (e.g. `openai/gpt-4o-mini`) |
 | `cwd` | string | | Working directory for the subagent |
-| `timeout` | number | | Timeout in seconds. Aborts the subagent if exceeded |
+| `timeout` | number | | Timeout in seconds. Aborts the subagent if exceeded. Defaults to the configured default timeout (300s, see `/saim-timeout`) |
 | `columnWidthPercent` | number | | Card width as % of terminal (33–100). Controls card grid layout |
 
 If `provider` and `model` are omitted, the subagent inherits the main agent's model.
 
+### ⏱️ Timeouts That Don't Destroy Child Work
+
+Every subagent has a timeout (default **300s**, configurable via `--saim-timeout` / `/saim-timeout`, `0` = unlimited). When a parent agent is aborted or times out while a child subagent is still running, the child is **not killed**. Instead it detaches:
+
+- The parent's tool call returns immediately with a note that the child continues in the background
+- The child keeps running, still bounded by its **own** timeout
+- When it finishes, its output is written to `result.md` (or `error.md` on failure) as usual, so the work can be harvested later
+
+On any failure (timeout, error), whatever text the subagent had already produced is salvaged to `partial-result.md` alongside `error.md` — nothing is silently discarded.
+
+### 🛑 Nesting Depth Limit
+
+Subagents may spawn their own subagents, but only up to a configured max depth (default **2**: main agent → subagent → sub-subagent). Subagents at the max depth don't receive the `subagent_create` tool at all, so a runaway fork cascade is structurally impossible. Configure via `--saim-max-depth` / `/saim-max-depth` (1–10).
+
 ### 📊 Live TUI Card Widgets
 
 Each running subagent is displayed as a colored card widget above the editor:
@@ -40,12 +54,20 @@ Each running subagent is displayed as a colored card widget above the editor:
 
 ### 🔍 Subagent Detail Overlay (`Ctrl+N`)
 
-Press **Ctrl+1** through **Ctrl+9** to open a detail popup for the corresponding subagent:
+Press **Ctrl+1** through **Ctrl+9** to open a detail popup for the **N-th visible** subagent card (1 = leftmost/topmost in the current window):
 
 - **Prompt** — Full prompt text with word wrapping (up to 5 lines)
 - **Messages** — Live-updating stream of the subagent's activity (text output, tool calls, status changes), always showing the latest 5 lines
 - Press the same **Ctrl+N** shortcut or **Escape** to close the overlay
 
+### 📑 Paging Through Cards (`Ctrl+Alt+←/→`)
+
+When more subagents have been spawned than fit in the visible window (see `/saim-set-max-tui-overlays` below):
+
+- **Ctrl+Alt+←** scrolls back to older subagent cards
+- **Ctrl+Alt+→** scrolls forward to newer subagent cards
+- A `subagents X–Y of N (Ctrl+Alt+←/→ to page)` hint is displayed above the cards whenever paging is active
+
 ### 📝 JSONL Session Logging
 
 Every subagent session is logged to disk for debugging and auditing:
@@ -53,11 +75,12 @@ Every subagent session is logged to disk for debugging and auditing:
 ```
 .pi/subagent-in-memory/<mainSessionId>/
 ├── subagent_1/
-│   ├── events.jsonl    # Full event stream (text, tool calls, results)
-│   └── result.md       # Final subagent output (or error.md on failure)
+│   ├── events.jsonl        # Full event stream (text, tool calls, results)
+│   └── result.md           # Final subagent output
 ├── subagent_2/
 │   ├── events.jsonl
-│   └── result.md
+│   ├── error.md            # On failure: what went wrong
+│   └── partial-result.md   # On failure: any text produced before the failure
 └── ...
 ```
 
@@ -69,11 +92,25 @@ The JSONL log includes:
 
 ### 🔄 Nested Subagent Support
 
-Subagents can spawn their own subagents. All nested cards render in the main agent's widget — they share the same module-level state regardless of nesting depth. This is achieved by passing the `subagent_create` tool directly as an `AgentTool` to child sessions.
+Subagents can spawn their own subagents, up to the configured max depth (see above). All nested cards render in the main agent's widget — they share the same module-level state regardless of nesting depth. This is achieved by passing the `subagent_create` tool directly as an `AgentTool` to child sessions.
+
+### 🎛️ Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/saim-max-depth [n]` | Show or set the max subagent nesting depth (1–10, default 2). Applies to newly created subagents. |
+| `/saim-timeout [seconds]` | Show or set the default subagent timeout in seconds (default 300, `0` = unlimited). A per-call `timeout` parameter overrides it. |
+| `/saim-toggle-overlay [on\|off\|toggle]` | Enable, disable, or toggle the subagent TUI overlay. When disabled, **no card widget is mounted even while subagents are actively running** — they continue executing silently in the background. |
+| `/saim-set-max-tui-overlays <N>` | Set the maximum number of cards displayed at once (1–9, default 3). Older cards remain accessible via **Ctrl+Alt+←/→**. |
+| `/saim-clear-tui-overlay` | Clear all subagent cards from the TUI and close any open detail overlay. |
 
-### 🧹 `/in-memory-clear-widgets` Slash Command
+### 🚩 CLI Flags
 
-Type `/in-memory-clear-widgets` in the pi prompt to clear all subagent card widgets from the TUI. Useful after a batch of subagent runs when you want a clean view.
+| Flag | Description |
+|------|-------------|
+| `--saim-max-depth <n>` | Max subagent nesting depth (1–10, default 2). Same as `/saim-max-depth`. |
+| `--saim-timeout <seconds>` | Default subagent timeout in seconds (default 300, `0` = unlimited). Same as `/saim-timeout`. |
+| `--saim-no-tui` | Start with the subagent overlay disabled (equivalent to running `/saim-toggle-overlay off` immediately on startup). Subagents still run normally — only the TUI cards are hidden. |
 
 ## Install
 
@@ -92,7 +129,7 @@ pi remove npm:pi-subagent-in-memory
 After installing, start pi and check:
 
 1. The `subagent_create` tool should appear in the tool list
-2. The `/in-memory-clear-widgets` command should be available (type `/` to see commands)
+2. The `/saim-max-depth`, `/saim-timeout`, `/saim-toggle-overlay`, `/saim-set-max-tui-overlays`, and `/saim-clear-tui-overlay` commands should be available (type `/` to see commands)
 3. Ask the agent to "run a subagent to list files" — you should see a card widget appear
 
 ## Usage Examples
@@ -118,7 +155,7 @@ Once installed, the LLM will discover the `subagent_create` tool from its schema
 
 ## How It Works
 
-1. **Tool registration** — On load, registers `subagent_create` as a tool and `/in-memory-clear-widgets` as a command. No system prompt modifications.
+1. **Tool registration** — On load, registers `subagent_create` as a tool plus the `/saim-*` commands and `--saim-no-tui` flag. No system prompt modifications.
 2. **Session creation** — When the LLM calls `subagent_create`, a new `createAgentSession` is created in-process with its own model, auth, and coding tools (read, write, edit, bash, grep, find, ls).
 3. **Event streaming** — All subagent events (text deltas, tool calls, completions) are forwarded as `tool_execution_update` events to the parent agent and logged to JSONL.
 4. **Widget rendering** — A TUI widget renders card(s) above the editor, updated on every event.

package/extensions/index.ts

@@ -13,9 +13,22 @@
  * - Live TUI card widgets showing subagent status and output
  * - JSONL event logging to ~/.pi/subagent-in-memory/<sessionId>/
  * - Nested subagent support (subagents can spawn subagents)
- * - /in-memory-clear-widgets slash command to remove widget cards
+ * - Slash commands to control TUI overlay:
+ *     /saim-toggle-overlay [on|off]   — enable/disable rendering
+ *     /saim-set-max-tui-overlays <N>  — limit visible cards (1-9)
+ *     /saim-clear-tui-overlay         — clear all cards & close any overlay
+ * - Runtime limits (each also available as a CLI flag):
+ *     /saim-max-depth [n]             — max subagent nesting depth (default 2)
+ *     /saim-timeout [seconds]         — default subagent timeout (default 300s,
+ *                                       0 = unlimited)
+ * - Parent aborts/timeouts do NOT kill running children: the child detaches,
+ *   keeps running under its own timeout, and still writes result.md /
+ *   error.md (plus partial-result.md salvaging any text produced so far).
  * - Multi-provider support (Anthropic, OpenAI, Google, etc.)
- * - Ctrl+Alt+<N> to inspect subagent prompt & live messages
+ * - Ctrl+<N> to inspect subagent prompt & live messages
+ * - Ctrl+Alt+Left / Ctrl+Alt+Right to page through cards when there are
+ *   more subagents than the visible window allows
+ * - --saim-no-tui CLI flag to start with the overlay disabled
  *
  * Results are written to ./.pi/subagent-in-memory/<mainSessionId>/subagent_<N>/result.md
  * (or error.md on failure) so the calling agent gets a short pointer instead of
@@ -24,19 +37,12 @@
 
 import { Type, type Static } from "@sinclair/typebox";
 import {
-  createAgentSession,
+  createAgentSessionFromServices,
+  createAgentSessionServices,
   SessionManager,
-  AuthStorage,
-  DefaultResourceLoader,
-  getAgentDir,
-  createCodingTools,
-  createGrepTool,
-  createFindTool,
-  createLsTool,
 } from "@mariozechner/pi-coding-agent";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { AgentToolResult, AgentToolUpdateCallback } from "@mariozechner/pi-coding-agent";
-import { resolveModel } from "./model.ts";
+import type { AgentToolResult, AgentToolUpdateCallback, ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { renderCard, type CardTheme } from "./tui-draw.ts";
 
 import { visibleWidth, truncateToWidth, wrapTextWithAnsi, matchesKey, Key } from "@mariozechner/pi-tui";
@@ -142,21 +148,99 @@ let widgetRenderVersion = 0;
 
 // Track open detail overlay so we can trigger re-renders
 let activeDetailTui: any = null;
+let activeDetailDone: ((result: void) => void) | null = null;
+
+// ── Runtime limits (commands & flags) ───────────────────────────
+const DEFAULT_MAX_DEPTH = 2;
+const MAX_DEPTH_HARD_LIMIT = 10;
+const DEFAULT_TIMEOUT_SECS = 300;
+// Max nesting depth: 1 = only the main agent may spawn subagents,
+// 2 = subagents may spawn one further level, etc. Prevents runaway forks.
+let maxSubagentDepth = DEFAULT_MAX_DEPTH;
+// Default per-subagent timeout in seconds, used when a subagent_create call
+// doesn't pass `timeout` explicitly. 0 = unlimited.
+let defaultTimeoutSecs = DEFAULT_TIMEOUT_SECS;
+
+/** Thrown into the tool-call promise when the PARENT aborts, so the child can
+ * detach and keep running instead of being killed mid-flight. */
+class ParentAbortedError extends Error {
+  constructor() {
+    super("Subagent was aborted by parent");
+  }
+}
 
-function renderSubagentCards(theme: any, width: number): string[] {
+function parseIntSetting(raw: unknown): number | undefined {
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  if (trimmed === "") return undefined;
+  const n = Number(trimmed);
+  return Number.isInteger(n) ? n : Number.NaN;
+}
+
+// ── TUI overlay controls (commands & flag) ──────────────────────
+const DEFAULT_MAX_VISIBLE_OVERLAYS = 3;
+const MAX_OVERLAYS_HARD_LIMIT = 9;
+let overlayEnabled = true;
+let maxVisibleOverlays = DEFAULT_MAX_VISIBLE_OVERLAYS;
+// Number of cards to skip from the END of the list. 0 means "show the latest
+// `maxVisibleOverlays`". Increasing windowOffset pages back into older cards.
+let windowOffset = 0;
+
+function getVisibleSubagents(): SubagentCard[] {
   if (subagents.length === 0) return [];
+  const total = subagents.length;
+  const window = Math.min(maxVisibleOverlays, total);
+  // Clamp offset to valid range; user paging may have left it stale.
+  const maxOffset = Math.max(0, total - window);
+  if (windowOffset > maxOffset) windowOffset = maxOffset;
+  if (windowOffset < 0) windowOffset = 0;
+  const end = total - windowOffset;
+  const start = Math.max(0, end - window);
+  return subagents.slice(start, end);
+}
+
+function unmountWidget() {
+  if (!currentCtx) return;
+  if (widgetMounted) {
+    currentCtx.ui.setWidget("in-memory-subagent-cards", undefined);
+  }
+  widgetMounted = false;
+  widgetTui = null;
+}
+
+function closeActiveDetail() {
+  if (activeDetailDone) {
+    try { activeDetailDone(); } catch {}
+  }
+  activeDetailTui = null;
+  activeDetailDone = null;
+}
+
+function renderSubagentCards(theme: any, width: number): string[] {
+  if (!overlayEnabled) return [];
+  const visible = getVisibleSubagents();
+  if (visible.length === 0) return [];
 
   // Derive cols from columnWidthPercent (all cards share the same value).
-  const pct = subagents[subagents.length - 1].columnWidthPercent;
+  const pct = visible[visible.length - 1].columnWidthPercent;
   const cols = Math.min(3, Math.max(1, Math.round(100 / pct)));
   const gap = 1;
   const colWidth = Math.floor((width - gap * (cols - 1)) / cols);
   const maxContentLines = 4;
   const lines: string[] = [""];
 
-  for (let i = 0; i < subagents.length; i += cols) {
-    const rowCards = subagents.slice(i, i + cols).map((sa, idx) => {
-      const cardTheme = CARD_THEMES[(i + idx) % CARD_THEMES.length];
+  // Page indicator if there are more cards than fit on screen
+  const total = subagents.length;
+  if (total > visible.length) {
+    const firstVisible = total - windowOffset - visible.length + 1;
+    const lastVisible = total - windowOffset;
+    const hint = `subagents ${firstVisible}–${lastVisible} of ${total}  (Ctrl+Alt+←/→ to page)`;
+    lines.push(theme.fg("dim", truncateToWidth(hint, width)));
+  }
+
+  for (let i = 0; i < visible.length; i += cols) {
+    const rowCards = visible.slice(i, i + cols).map((sa, idx) => {
+      const cardTheme = CARD_THEMES[(sa.num - 1) % CARD_THEMES.length];
 
       const titleText = `${sa.title} [${sa.modelLabel}]`;
       const innerW = colWidth - 4;
@@ -166,8 +250,8 @@ function renderSubagentCards(theme: any, width: number): string[] {
       const trimmedLines = contentLines.map((l) =>
         visibleWidth(l) > innerW ? truncateToWidth(l, innerW - 1) + "…" : l
       );
-      const visible = trimmedLines.slice(0, maxContentLines);
-      const content = visible.join("\n") + (contentLines.length > maxContentLines ? "\n…" : "");
+      const visibleContentLines = trimmedLines.slice(0, maxContentLines);
+      const content = visibleContentLines.join("\n") + (contentLines.length > maxContentLines ? "\n…" : "");
 
       let statusRaw: string;
       if (sa.status === "created") {
@@ -286,12 +370,8 @@ function requestSubagentRender() {
   syncAnimationTimer();
 
   if (!currentCtx) return;
-  if (subagents.length === 0) {
-    if (widgetMounted) {
-      currentCtx.ui.setWidget("in-memory-subagent-cards", undefined);
-      widgetMounted = false;
-      widgetTui = null;
-    }
+  if (!overlayEnabled || subagents.length === 0) {
+    unmountWidget();
     try { activeDetailTui?.requestRender(); } catch {}
     return;
   }
@@ -431,8 +511,9 @@ const SubagentParams = Type.Object({
   timeout: Type.Optional(
     Type.Number({
       description:
-        "Timeout in seconds for the subagent execution. If exceeded, the subagent is aborted. " +
-        "Defaults to unlimited (no timeout).",
+        "Timeout in seconds for the subagent execution. If exceeded, the subagent is aborted " +
+        "(its own in-flight nested subagents keep running and still write their results). " +
+        "Defaults to the configured default timeout (300s unless changed via --saim-timeout or /saim-timeout).",
       minimum: 1,
     })
   ),
@@ -458,7 +539,18 @@ async function executeSubagent(
   fallbackProvider?: string,
   fallbackModel?: string,
   fallbackCwd?: string,
+  depth: number = 1,
 ): Promise<AgentToolResult<any>> {
+  if (depth > maxSubagentDepth) {
+    throw new Error(
+      `Subagent nesting depth limit reached (max depth ${maxSubagentDepth}, see /saim-max-depth). ` +
+        "Perform the task directly instead of delegating to another subagent.",
+    );
+  }
+  if (signal?.aborted) {
+    throw new Error("Subagent was aborted before it started");
+  }
+
   subagentCount++;
   const subagentNum = subagents.length + 1; // display number based on currently visible cards
   const outDir = join(".pi", "subagent-in-memory", mainSessionId, `subagent_${subagentCount}`);
@@ -477,36 +569,49 @@ async function executeSubagent(
     throw new Error("Could not determine model. Provide provider and model parameters.");
   }
 
-  const { model: resolvedModel, apiKey } = await resolveModel(providerName, modelId);
-
   const cwd = params.cwd ?? fallbackCwd ?? process.cwd();
 
-  const authStorage = AuthStorage.create();
-  authStorage.setRuntimeApiKey(providerName, apiKey);
-
-  // Create tools for the subagent, including nested subagent support
-  const tools = [
-    ...createCodingTools(cwd),
-    createGrepTool(cwd),
-    createFindTool(cwd),
-    createLsTool(cwd),
-    createSubagentAgentTool(providerName, modelId, cwd),
-  ];
-
-  const resourceLoader = new DefaultResourceLoader({
-    cwd,
-    agentDir: getAgentDir(),
-  });
-  await resourceLoader.reload();
+  // Create pi's normal cwd-bound services first. This loads packages from
+  // ~/.pi/agent/settings.json and <cwd>/.pi/settings.json, then applies any
+  // extension-provided registerProvider() calls to the model registry. Resolving
+  // the requested model after this step is what makes package-provided models
+  // such as openai-codex/gpt-5.5 visible to subagents.
+  const services = await createAgentSessionServices({ cwd });
+  const resolvedModel = services.modelRegistry.find(providerName, modelId);
+  if (!resolvedModel) {
+    const providerModels = services.modelRegistry
+      .getAll()
+      .filter((model) => model.provider === providerName)
+      .map((model) => model.id)
+      .sort();
+    const diagnostics = services.diagnostics
+      .filter((diagnostic) => diagnostic.type === "error")
+      .map((diagnostic) => diagnostic.message);
+    const details = [
+      providerModels.length > 0
+        ? `Known models for ${providerName}: ${providerModels.join(", ")}`
+        : `Provider ${providerName} has no registered models.`,
+      diagnostics.length > 0 ? `Service diagnostics: ${diagnostics.join("; ")}` : undefined,
+    ].filter(Boolean).join(" ");
+    throw new Error(`Could not find model ${providerName}/${modelId}. ${details}`.trim());
+  }
 
-  const { session } = await createAgentSession({
+  // Subagents at the max depth don't get the subagent_create tool at all, so
+  // the LLM can't even attempt a deeper fork.
+  const canNest = depth < maxSubagentDepth;
+  const { session } = await createAgentSessionFromServices({
+    services,
+    sessionManager: SessionManager.inMemory(),
     model: resolvedModel,
-    authStorage,
-    tools,
     thinkingLevel: "off",
-    cwd,
-    sessionManager: SessionManager.inMemory(),
-    resourceLoader,
+    // Keep subagent context/tool surface intentionally small: built-in coding
+    // tools plus nested subagent support. Package extensions are still loaded
+    // above so provider registrations are available, but their tools are not
+    // activated unless explicitly listed here.
+    tools: canNest
+      ? ["read", "bash", "edit", "write", "grep", "find", "ls", "subagent_create"]
+      : ["read", "bash", "edit", "write", "grep", "find", "ls"],
+    customTools: canNest ? [createSubagentAgentTool(providerName, modelId, cwd, depth + 1)] : [],
   });
 
   // Set up JSONL event log
@@ -522,6 +627,7 @@ async function executeSubagent(
     model: modelId,
     task: params.task,
     title: params.title,
+    depth,
   });
   let lastEventId = session.sessionId;
 
@@ -545,26 +651,21 @@ async function executeSubagent(
     details: { sessionId: session.sessionId, status: "created" },
   });
 
-  // Timeout handling
+  // Timeout handling — explicit params.timeout wins, otherwise the configured
+  // default applies. 0 means unlimited.
+  const timeoutSecs = params.timeout ?? defaultTimeoutSecs;
   let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
   const timeoutController = new AbortController();
-  if (params.timeout) {
+  if (timeoutSecs > 0) {
     timeoutTimer = setTimeout(() => {
       timeoutController.abort();
-    }, params.timeout * 1000);
+    }, timeoutSecs * 1000);
   }
 
-  const combinedAbort = () => {
-    session.abort();
-    card.status = "error";
-    card.endedAt = Date.now();
-    appendMessage(card, "[aborted]");
-    requestSubagentRender();
-  };
+  // Hoisted out of the run promise so error paths can salvage partial output.
+  let finalText = "";
 
-  try {
-    const result = await new Promise<string>((resolve, reject) => {
-      let finalText = "";
+  const runPromise = new Promise<string>((resolve, reject) => {
       let textDeltaBuffer = "";
       let toolcallDeltaBuffer = "";
       let lastPartialUpdateAt = 0;
@@ -714,15 +815,17 @@ async function executeSubagent(
         }
       });
 
-      if (signal) {
-        signal.addEventListener("abort", () => {
-          combinedAbort();
-          reject(new Error("Subagent was aborted"));
-        });
-      }
       timeoutController.signal.addEventListener("abort", () => {
-        combinedAbort();
-        reject(new Error(`Subagent timed out after ${params.timeout}s`));
+        // Abort only this subagent's own session. Its in-flight nested
+        // subagents receive the abort as a PARENT abort and detach instead of
+        // dying (see ParentAbortedError handling below), so their work is
+        // still written to disk.
+        session.abort();
+        card.status = "error";
+        card.endedAt = Date.now();
+        appendMessage(card, `[timed out after ${timeoutSecs}s]`);
+        requestSubagentRender();
+        reject(new Error(`Subagent timed out after ${timeoutSecs}s`));
       });
 
       session.prompt(params.task).catch((err) => {
@@ -732,30 +835,85 @@ async function executeSubagent(
         requestSubagentRender();
         reject(err);
       });
-    });
+  });
 
+  const finalizeSuccess = async (result: string): Promise<string> => {
     if (timeoutTimer) clearTimeout(timeoutTimer);
     session.dispose();
     await flushJsonl(jsonlPath);
-
     const resultPath = join(outDir, "result.md");
     writeFileSync(resultPath, result, "utf-8");
+    return resultPath;
+  };
 
-    return {
-      content: [{ type: "text", text: `Execution succeeded. Result is in \`${resultPath}\`` }],
-      details: { sessionId: session.sessionId, status: "completed", outputDir: outDir },
-    };
-  } catch (err: any) {
+  const finalizeError = async (err: any): Promise<{ errorPath: string; partialPath?: string }> => {
     if (timeoutTimer) clearTimeout(timeoutTimer);
     session.dispose();
     await flushJsonl(jsonlPath);
-
     const errorMsg = err?.message ?? String(err);
     const errorPath = join(outDir, "error.md");
-    writeFileSync(errorPath, `# Subagent Error\n\n${errorMsg}\n`, "utf-8");
+    let body = `# Subagent Error\n\n${errorMsg}\n`;
+    let partialPath: string | undefined;
+    if (finalText.trim()) {
+      partialPath = join(outDir, "partial-result.md");
+      writeFileSync(partialPath, finalText, "utf-8");
+      body += `\nPartial output produced before the failure was saved to \`partial-result.md\`.\n`;
+    }
+    writeFileSync(errorPath, body, "utf-8");
+    return { errorPath, partialPath };
+  };
+
+  // A parent abort races against the run instead of killing the session, so
+  // a timed-out/aborted parent can no longer destroy useful child work.
+  let parentAbortPromise: Promise<never> | undefined;
+  if (signal) {
+    parentAbortPromise = new Promise<never>((_, reject) => {
+      signal.addEventListener("abort", () => reject(new ParentAbortedError()), { once: true });
+    });
+  }
 
+  try {
+    const result = await (parentAbortPromise ? Promise.race([runPromise, parentAbortPromise]) : runPromise);
+    const resultPath = await finalizeSuccess(result);
     return {
-      content: [{ type: "text", text: `Execution failed. Detail is in \`${errorPath}\`` }],
+      content: [{ type: "text", text: `Execution succeeded. Result is in \`${resultPath}\`` }],
+      details: { sessionId: session.sessionId, status: "completed", outputDir: outDir },
+    };
+  } catch (err: any) {
+    if (err instanceof ParentAbortedError) {
+      // The parent aborted (typically because it hit its own timeout) while
+      // this subagent was still working. Don't kill it — detach: let it run
+      // to completion, still bounded by its own timeout, and write result.md
+      // / error.md as usual so the work can be harvested later.
+      appendMessage(card, "[parent aborted — continuing detached]");
+      requestSubagentRender();
+      runPromise
+        .then((result) => finalizeSuccess(result))
+        .catch((e) => finalizeError(e))
+        .catch(() => {});
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "Subagent was aborted by its parent but continues running detached (its own timeout still applies). " +
+              `Its result will be written to \`${outDir}\` when it finishes.`,
+          },
+        ],
+        details: { sessionId: session.sessionId, status: "detached", outputDir: outDir },
+      };
+    }
+
+    const { errorPath, partialPath } = await finalizeError(err);
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `Execution failed. Detail is in \`${errorPath}\`` +
+            (partialPath ? ` (partial output in \`${partialPath}\`)` : ""),
+        },
+      ],
       details: { sessionId: session.sessionId, status: "error", outputDir: outDir },
     };
   }
@@ -766,19 +924,22 @@ function createSubagentAgentTool(
   parentProvider: string,
   parentModel: string,
   parentCwd: string,
-) {
+  childDepth: number,
+): ToolDefinition<typeof SubagentParams> {
   return {
     name: "subagent_create",
     label: "Subagent",
     description:
       "Create a subagent to perform a task. The subagent runs in-process with its own session. " +
-      "Progress is streamed back as execution updates. Returns the final result when the subagent finishes.",
+      "Progress is streamed back as execution updates. Returns the final result when the subagent finishes. " +
+      "Nesting is limited to a configured max depth — if the limit is reached, do the work directly instead.",
     parameters: SubagentParams,
     async execute(
       toolCallId: string,
       params: SubagentParamsType,
       signal?: AbortSignal,
       onUpdate?: AgentToolUpdateCallback,
+      _ctx?: any,
     ) {
       return executeSubagent(
         toolCallId,
@@ -788,6 +949,7 @@ function createSubagentAgentTool(
         parentProvider,
         parentModel,
         parentCwd,
+        childDepth,
       );
     },
   };
@@ -795,46 +957,213 @@ function createSubagentAgentTool(
 
 // ── Extension entry point ───────────────────────────────────────
 export default function (pi: ExtensionAPI) {
+  pi.registerFlag("saim-no-tui", {
+    description: "Start with the subagent TUI overlay disabled (equivalent to /saim-toggle-overlay off).",
+    type: "boolean",
+    default: false,
+  });
+
+  pi.registerFlag("saim-max-depth", {
+    description: `Max subagent nesting depth, 1-${MAX_DEPTH_HARD_LIMIT} (default ${DEFAULT_MAX_DEPTH}). Prevents runaway subagent forks.`,
+    type: "string",
+  });
+
+  pi.registerFlag("saim-timeout", {
+    description: `Default subagent timeout in seconds, 0 = unlimited (default ${DEFAULT_TIMEOUT_SECS}). Per-call \`timeout\` parameter overrides it.`,
+    type: "string",
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
     mainSessionId = ctx.sessionManager.getSessionId?.() ?? `session-${Date.now()}`;
     subagentCount = 0;
     subagents.length = 0;
     activeDetailTui = null;
+    activeDetailDone = null;
     widgetMounted = false;
     widgetTui = null;
+    windowOffset = 0;
     if (flashTimer) { clearInterval(flashTimer); flashTimer = null; }
     ctx.ui.setWidget("in-memory-subagent-cards", undefined);
+
+    // Apply --saim-no-tui flag if present
+    if (pi.getFlag("saim-no-tui") === true) {
+      overlayEnabled = false;
+    }
+
+    // Apply --saim-max-depth / --saim-timeout flags if present
+    const depthFlag = parseIntSetting(pi.getFlag("saim-max-depth"));
+    if (depthFlag !== undefined) {
+      if (Number.isInteger(depthFlag) && depthFlag >= 1 && depthFlag <= MAX_DEPTH_HARD_LIMIT) {
+        maxSubagentDepth = depthFlag;
+      } else {
+        ctx.ui.notify(
+          `Invalid --saim-max-depth (expected 1-${MAX_DEPTH_HARD_LIMIT}); keeping ${maxSubagentDepth}`,
+          "warning",
+        );
+      }
+    }
+    const timeoutFlag = parseIntSetting(pi.getFlag("saim-timeout"));
+    if (timeoutFlag !== undefined) {
+      if (Number.isInteger(timeoutFlag) && timeoutFlag >= 0) {
+        defaultTimeoutSecs = timeoutFlag;
+      } else {
+        ctx.ui.notify(
+          `Invalid --saim-timeout (expected seconds >= 0); keeping ${defaultTimeoutSecs}`,
+          "warning",
+        );
+      }
+    }
+
     requestSubagentRender();
   });
 
-  pi.registerCommand("in-memory-clear-widgets", {
-    description: "Clear all in-memory subagent card widgets",
+  pi.registerCommand("saim-max-depth", {
+    description: `Show or set max subagent nesting depth (1-${MAX_DEPTH_HARD_LIMIT}, default ${DEFAULT_MAX_DEPTH}). Usage: /saim-max-depth [n]`,
+    handler: async (args, ctx) => {
+      const arg = (args ?? "").trim();
+      if (arg === "") {
+        ctx.ui.notify(`Max subagent nesting depth: ${maxSubagentDepth}`, "info");
+        return;
+      }
+      const n = Number(arg);
+      if (!Number.isInteger(n) || n < 1 || n > MAX_DEPTH_HARD_LIMIT) {
+        ctx.ui.notify(`Provide an integer between 1 and ${MAX_DEPTH_HARD_LIMIT}.`, "warning");
+        return;
+      }
+      maxSubagentDepth = n;
+      ctx.ui.notify(`Max subagent nesting depth set to ${n} (applies to newly created subagents)`, "info");
+    },
+  });
+
+  pi.registerCommand("saim-timeout", {
+    description: `Show or set the default subagent timeout in seconds (0 = unlimited, default ${DEFAULT_TIMEOUT_SECS}). Usage: /saim-timeout [seconds]`,
+    handler: async (args, ctx) => {
+      const arg = (args ?? "").trim();
+      const fmt = (secs: number) => (secs === 0 ? "unlimited" : `${secs}s`);
+      if (arg === "") {
+        ctx.ui.notify(`Default subagent timeout: ${fmt(defaultTimeoutSecs)}`, "info");
+        return;
+      }
+      const n = Number(arg);
+      if (!Number.isInteger(n) || n < 0) {
+        ctx.ui.notify("Provide a non-negative integer number of seconds (0 = unlimited).", "warning");
+        return;
+      }
+      defaultTimeoutSecs = n;
+      ctx.ui.notify(`Default subagent timeout set to ${fmt(n)} (applies to newly created subagents)`, "info");
+    },
+  });
+
+  pi.registerCommand("saim-clear-tui-overlay", {
+    description: "Clear subagent TUI cards and close any open detail overlay",
     handler: async (_args, ctx) => {
       subagents.length = 0;
-      activeDetailTui = null;
-      widgetMounted = false;
-      widgetTui = null;
+      windowOffset = 0;
+      closeActiveDetail();
+      unmountWidget();
       if (flashTimer) { clearInterval(flashTimer); flashTimer = null; }
-      ctx.ui.setWidget("in-memory-subagent-cards", undefined);
-      ctx.ui.notify("In-memory subagent widgets cleared", "info");
+      ctx.ui.notify("Subagent TUI cards cleared", "info");
+    },
+  });
+
+  pi.registerCommand("saim-toggle-overlay", {
+    description: "Enable or disable subagent detail overlays. Usage: /saim-toggle-overlay [on|off|toggle]",
+    handler: async (args, ctx) => {
+      const arg = (args ?? "").trim().toLowerCase();
+      let next: boolean;
+      if (arg === "on" || arg === "true" || arg === "1") {
+        next = true;
+      } else if (arg === "off" || arg === "false" || arg === "0") {
+        next = false;
+      } else if (arg === "" || arg === "toggle") {
+        next = !overlayEnabled;
+      } else {
+        ctx.ui.notify(`Unknown argument "${arg}". Use on, off, or toggle.`, "warning");
+        return;
+      }
+      overlayEnabled = next;
+      if (!overlayEnabled) {
+        // Force-tear down even while subagents are running.
+        closeActiveDetail();
+        unmountWidget();
+      }
+      requestSubagentRender();
+      ctx.ui.notify(`Subagent TUI overlay ${overlayEnabled ? "enabled" : "disabled"}`, "info");
+    },
+  });
+
+  pi.registerCommand("saim-set-max-tui-overlays", {
+    description: `Set max visible subagent cards (1-${MAX_OVERLAYS_HARD_LIMIT}). Older cards remain accessible via Ctrl+Alt+←/→.`,
+    handler: async (args, ctx) => {
+      const n = parseInt((args ?? "").trim(), 10);
+      if (!Number.isFinite(n) || n < 1 || n > MAX_OVERLAYS_HARD_LIMIT) {
+        ctx.ui.notify(
+          `Provide an integer between 1 and ${MAX_OVERLAYS_HARD_LIMIT}.`,
+          "warning",
+        );
+        return;
+      }
+      maxVisibleOverlays = n;
+      windowOffset = 0;
+      requestSubagentRender();
+      ctx.ui.notify(`Max visible subagent cards set to ${n}`, "info");
+    },
+  });
+
+  // Page through cards when there are more subagents than fit on screen.
+  pi.registerShortcut(Key.ctrlAlt("left"), {
+    description: "Page to older subagent cards",
+    handler: async (ctx) => {
+      if (!overlayEnabled) return;
+      const total = subagents.length;
+      const window = Math.min(maxVisibleOverlays, total);
+      const maxOffset = Math.max(0, total - window);
+      if (windowOffset >= maxOffset) {
+        ctx.ui.notify("Already showing the oldest subagents", "info");
+        return;
+      }
+      windowOffset = Math.min(maxOffset, windowOffset + window);
+      requestSubagentRender();
     },
   });
 
-  // Register Ctrl+1 through Ctrl+9 to open subagent detail overlay
+  pi.registerShortcut(Key.ctrlAlt("right"), {
+    description: "Page to newer subagent cards",
+    handler: async (ctx) => {
+      if (!overlayEnabled) return;
+      if (windowOffset === 0) {
+        ctx.ui.notify("Already showing the latest subagents", "info");
+        return;
+      }
+      const window = Math.min(maxVisibleOverlays, subagents.length);
+      windowOffset = Math.max(0, windowOffset - window);
+      requestSubagentRender();
+    },
+  });
+
+  // Register Ctrl+1 through Ctrl+9 to open subagent detail overlay.
+  // The number maps to the position WITHIN the currently visible window
+  // (1 = first visible card), not the absolute subagent number.
   for (let n = 1; n <= 9; n++) {
     pi.registerShortcut(Key.ctrl(`${n}` as any), {
-      description: `Inspect subagent #${n}`,
+      description: `Inspect visible subagent #${n}`,
       handler: async (ctx) => {
-        const card = subagents.find((sa) => sa.num === n);
+        if (!overlayEnabled) {
+          ctx.ui.notify("Subagent TUI overlay is disabled", "warning");
+          return;
+        }
+        const visible = getVisibleSubagents();
+        const card = visible[n - 1];
         if (!card) {
-          ctx.ui.notify(`No subagent #${n}`, "warning");
+          ctx.ui.notify(`No visible subagent #${n}`, "warning");
           return;
         }
 
         await ctx.ui.custom<void>(
           (tui: any, theme: any, _keybindings: any, done: (result: void) => void) => {
             activeDetailTui = tui;
+            activeDetailDone = done;
             return new SubagentDetailOverlay(card, n, theme, done);
           },
           {
@@ -849,6 +1178,7 @@ export default function (pi: ExtensionAPI) {
         );
 
         activeDetailTui = null;
+        activeDetailDone = null;
         syncAnimationTimer();
         requestSubagentRender();
       },
@@ -860,7 +1190,8 @@ export default function (pi: ExtensionAPI) {
     label: "Subagent",
     description:
       "Create a subagent to perform a task. The subagent runs in-process with its own session. " +
-      "Progress is streamed back as execution updates. Returns the final result when the subagent finishes.",
+      "Progress is streamed back as execution updates. Returns the final result when the subagent finishes. " +
+      "Nesting is limited to a configured max depth — if the limit is reached, do the work directly instead.",
     parameters: SubagentParams,
 
     async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -877,6 +1208,7 @@ export default function (pi: ExtensionAPI) {
         providerName,
         modelId,
         cwd,
+        1,
       );
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagent-in-memory",
-  "version": "0.1.6",
+  "version": "0.2.2",
   "description": "In-process subagent tool for pi with live TUI card widgets, JSONL session logging, and zero system-prompt overhead.",
   "repository": {
     "type": "git",