shariq-pi-extensions 0.2.8 → 0.2.10

package/docs/EXTENSIONS.md

@@ -38,7 +38,7 @@ The goal extension adds persistent, branch-safe objectives, progress evidence, b
 
 The subagent extension runs flat Pi child agents with profiles, capability policies, continuation, result delivery, optional worktrees, and a dashboard. Configuration lives in `<agent-dir>/subagents.json`; trusted projects may override it through their Pi config directory. The configured concurrency ceiling is 50.
 
-The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement is handed to Pi immediately as an extension-originated user follow-up, so Pi queues it while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context; status tools are for explicit inspection, not waiting.
+The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement stays in a private extension queue while the parent is active, then starts one custom-result turn at Pi's safe idle edge with the summary guaranteed in model context and never rendered as user-authored or follow-up input; status tools are for explicit inspection, not waiting.
 
 ### [Orchestration](../extensions/orchestration/README.md)
 
@@ -50,7 +50,7 @@ The model-facing `create_orchestration` tool starts planning only after an expli
 
 Managed PTYs support servers, watchers, long builds, downloads, and interactive processes. The extension tracks up to eight concurrent terminals, retains bounded output, stores full logs in restrictive temporary directories, and stops process groups during shutdown or reload.
 
-Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal immediately hands its completion or failure to Pi as an extension-originated user follow-up, which Pi queues while the parent is active or uses to start a new parent turn when idle with the bounded output guaranteed in model context. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
+Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal keeps completion or failure in a private extension queue while the parent is active, then starts one custom-result turn at Pi's safe idle edge with bounded output guaranteed in model context and never rendered as user-authored or follow-up input. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
 
 ## Web access
 

package/extensions/background-terminals/README.md

@@ -10,7 +10,7 @@ Session-scoped background pseudo-terminals for Pi. The extension combines Codex-
 - `list_terminals` — list running and settled terminals.
 - `stop_terminal` — stop complete process groups with TERM-to-KILL escalation.
 
-Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with bounded output guaranteed in model context, so the parent can continue other work or end its turn rather than poll.
+Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Settlement stays in a private extension queue while the parent is active, then starts one custom-result turn at Pi's safe idle edge with bounded output guaranteed in model context and never rendered as user-authored or follow-up input, so the parent can continue other work or end its turn rather than poll.
 
 ## User interface
 

package/extensions/background-terminals/index.ts

@@ -8,7 +8,7 @@ import type {
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { deliverSettlement } from "../shared/settlement-delivery.ts";
+import { settlementDelivery } from "../shared/settlement-delivery.ts";
 import { oneLine, sanitizeTerminalText, stateLabel } from "../shared/tui-dashboard.ts";
 import { TerminalManager, MAX_RUNNING_TERMINALS } from "./src/manager.ts";
 import {
@@ -36,6 +36,7 @@ function resolveCwd(base: string, requested?: string): string {
 }
 
 export default function backgroundTerminals(pi: ExtensionAPI) {
+  const deliverSettlement = settlementDelivery(pi);
   let manager: TerminalManager | undefined;
   let ui: ExtensionUIContext | undefined;
   let unsubscribe: (() => void) | undefined;
@@ -89,7 +90,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     const snapshot = pendingResults.get(id);
     if (!snapshot) return;
     pendingResults.delete(id);
-    deliverSettlement(pi, {
+    deliverSettlement({
       customType: "background-terminal-result",
       content: formatCompletion(snapshot),
       display: true,
@@ -131,7 +132,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     promptSnippet: "Start an interactive or long-running command in a managed background PTY.",
     promptGuidelines: [
       "Use start_terminal by default for servers, watchers, downloads, long or uncertain builds and tests, interactive shells, and any command that should not occupy the main turn; reserve bash for short commands whose result is needed immediately. Never use a large bash timeout merely to wait for long work.",
-      "After start_terminal returns, continue only genuinely independent work. If none remains, end the turn immediately. Terminal settlement is handed to Pi immediately: it queues a follow-up while the parent is active or starts the next parent turn when idle. When that result invokes the parent, continue the original task immediately without waiting for the user or rereading the same terminal; do not call read_terminal, list_terminals, or start a timer merely to check whether it finished.",
+      "After start_terminal returns, continue only genuinely independent work. If none remains, end the turn immediately. Terminal settlement stays in a private extension queue while the parent is active and starts one custom-result turn at Pi's safe idle edge. When that result invokes the parent, continue the original task immediately without waiting for the user or rereading the same terminal; do not call read_terminal, list_terminals, or start a timer merely to check whether it finished.",
       "Use stop_terminal when a managed process is no longer needed. Background terminals are session-scoped and are stopped during session shutdown or reload.",
     ],
     parameters: Type.Object({

package/extensions/cursor-provider/README.md

@@ -22,12 +22,12 @@ Secrets are passed directly to the SDK and are never placed in command arguments
 - Refreshes Cursor's authenticated model catalog and caches only Composer and Cursor Grok metadata for the next extension reload.
 - Exposes image input for every registered Cursor model.
 - Maps Composer fast mode and Cursor Grok reasoning effort to native model parameters.
-- Uses the SDK's local hosted-model runtime in an isolated temporary workspace with ambient Cursor settings disabled.
+- Uses the SDK's local hosted-model runtime with warm agent instance pooling and ambient Cursor settings (`settingSources: []`) disabled.
 - Disables Cursor's built-in workspace tools and exposes Pi's active tools as native SDK custom tools. Tool execution remains owned by Pi.
 - Streams native text and thinking deltas, structured tool calls, stop reasons, and Cursor-reported input/output/cache/reasoning usage.
-- Propagates cancellation and timeouts, enables safe SDK transport retries, and maps common authentication, rate-limit, quota, capacity, timeout, and context failures to actionable Pi errors.
+- Propagates cancellation and timeouts, enables safe SDK transport retries, redacts credential literals from error traces, and maps common authentication, rate-limit, quota, capacity, timeout, and context failures to actionable Pi errors.
 - Forwards base64 image payloads separately from the textual conversation transcript.
-- Removes temporary workspace and SDK state after each request.
+- Automatically cleans up warm agent workspaces on idle TTL and session shutdown.
 
 ## Cursor dashboard
 

package/extensions/cursor-provider/cursor/stream.ts

@@ -21,6 +21,8 @@ import {
 import { loadCursorCatalog, resolveCursorModelSelection } from "./models.ts";
 
 const TOOL_DELEGATION_RESULT = "Tool execution was delegated to Pi. End this run without further output.";
+const MAX_CACHED_AGENTS = 8;
+const AGENT_IDLE_TTL_MS = 10 * 60 * 1_000;
 
 function asJsonValue(value: unknown): SDKJsonValue {
   return JSON.parse(JSON.stringify(value ?? null)) as SDKJsonValue;
@@ -30,6 +32,13 @@ function asArguments(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
 }
 
+export function redactCursorError(value: unknown): string {
+  return String(value ?? "Cursor request failed")
+    .replace(/crsr_[A-Za-z0-9_-]+/g, "[REDACTED]")
+    .replace(/(authorization|api[-_ ]?key|token)([\s:=]+)([^\s,;]+)/gi, "$1$2[REDACTED]")
+    .slice(0, 4096);
+}
+
 export function serializeCursorContext(context: Context): { text: string; images: SDKImage[] } {
   const lines = [
     "Continue the Pi conversation below as the assistant.",
@@ -45,6 +54,9 @@ export function serializeCursorContext(context: Context): { text: string; images
 
   for (const message of context.messages) {
     lines.push(`<message role=${JSON.stringify(message.role)}>`);
+    if (message.role === "toolResult") {
+      lines.push(`[Tool result for ${(message as any).toolCallId || "unknown"}; error=${Boolean((message as any).isError)}]`);
+    }
     if (typeof message.content === "string") {
       lines.push(message.content);
     } else if (Array.isArray(message.content)) {
@@ -58,9 +70,6 @@ export function serializeCursorContext(context: Context): { text: string; images
         }
       }
     }
-    if (message.role === "toolResult") {
-      lines.push(`[Tool result for ${(message as any).toolCallId}; error=${Boolean((message as any).isError)}]`);
-    }
     lines.push("</message>");
   }
   lines.push("</conversation>");
@@ -81,7 +90,7 @@ function usageFromCursor(usage: TokenUsage | undefined, output: AssistantMessage
 }
 
 export function formatCursorError(error: unknown): string {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = redactCursorError(error instanceof Error ? error.message : error);
   if (/401|403|unauth|api key|credential/i.test(message)) return "Cursor authentication failed. Run `/login cursor`, then retry.";
   if (/429|rate.?limit/i.test(message)) return "Cursor rate limit reached. Wait for the reported reset, then retry.";
   if (/quota|usage limit|billing|credit|exhaust/i.test(message)) return "Cursor usage limit reached. Open `/cursor` for account status and reset information.";
@@ -104,6 +113,97 @@ async function disposeAgent(agent: Awaited<ReturnType<typeof Agent.create>> | un
   }
 }
 
+interface ActiveToolHandler {
+  onToolCall(toolName: string, args: unknown, toolCallId?: string): void;
+}
+
+interface CachedAgentEntry {
+  agent: Awaited<ReturnType<typeof Agent.create>>;
+  workspace: string;
+  activeHandlerRef: { current: ActiveToolHandler | null };
+  lastUsedAt: number;
+}
+
+const agentPool = new Map<string, CachedAgentEntry>();
+
+async function disposeCachedEntry(entry: CachedAgentEntry): Promise<void> {
+  await disposeAgent(entry.agent);
+  await rm(entry.workspace, { recursive: true, force: true }).catch(() => undefined);
+}
+
+export async function clearCursorAgentPool(): Promise<void> {
+  const entries = [...agentPool.values()];
+  agentPool.clear();
+  await Promise.allSettled(entries.map(disposeCachedEntry));
+}
+
+async function getOrInitWarmAgent(
+  apiKey: string,
+  selection: ReturnType<typeof resolveCursorModelSelection>,
+  tools: Context["tools"],
+  activeHandler: ActiveToolHandler,
+  enableRetries: boolean,
+): Promise<{ agent: Awaited<ReturnType<typeof Agent.create>>; activeHandlerRef: { current: ActiveToolHandler | null } }> {
+  const toolSignatures = (tools ?? []).map((t) => ({ name: t.name, schema: t.parameters ?? null }));
+  const cacheKey = JSON.stringify({ key: apiKey, model: selection, tools: toolSignatures });
+
+  const existing = agentPool.get(cacheKey);
+  if (existing) {
+    existing.lastUsedAt = Date.now();
+    existing.activeHandlerRef.current = activeHandler;
+    return { agent: existing.agent, activeHandlerRef: existing.activeHandlerRef };
+  }
+
+  // Evict oldest or expired agents if pool is full
+  const now = Date.now();
+  for (const [key, entry] of [...agentPool.entries()]) {
+    if (now - entry.lastUsedAt > AGENT_IDLE_TTL_MS) {
+      agentPool.delete(key);
+      void disposeCachedEntry(entry);
+    }
+  }
+  if (agentPool.size >= MAX_CACHED_AGENTS) {
+    const oldestKey = [...agentPool.entries()].sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt)[0]?.[0];
+    if (oldestKey) {
+      const oldest = agentPool.get(oldestKey);
+      agentPool.delete(oldestKey);
+      if (oldest) void disposeCachedEntry(oldest);
+    }
+  }
+
+  const workspace = await mkdtemp(join(tmpdir(), "pi-cursor-sdk-"));
+  const activeHandlerRef = { current: activeHandler as ActiveToolHandler | null };
+
+  const customTools: Record<string, SDKCustomTool> = {};
+  for (const tool of tools ?? []) {
+    customTools[tool.name] = {
+      description: tool.description,
+      inputSchema: asJsonValue(tool.parameters ?? { type: "object" }) as Record<string, SDKJsonValue>,
+      async execute(args, toolContext) {
+        activeHandlerRef.current?.onToolCall(tool.name, args, toolContext.toolCallId);
+        return { content: [{ type: "text", text: TOOL_DELEGATION_RESULT }], isError: true };
+      },
+    };
+  }
+
+  const agent = await Agent.create({
+    apiKey,
+    model: selection,
+    tools: tools?.length ? ["mcp"] : [],
+    local: {
+      cwd: workspace,
+      store: new JsonlLocalAgentStore(join(workspace, "state")),
+      customTools,
+      settingSources: [],
+      enableAgentRetries: enableRetries,
+    },
+  });
+
+  const entry: CachedAgentEntry = { agent, workspace, activeHandlerRef, lastUsedAt: Date.now() };
+  agentPool.set(cacheKey, entry);
+  return { agent, activeHandlerRef };
+}
+
 export function streamCursorSdk(model: Model<any>, context: Context, options?: ProviderStreamOptions) {
   const stream = createAssistantMessageEventStream();
   const output: AssistantMessage = {
@@ -119,8 +219,6 @@ export function streamCursorSdk(model: Model<any>, context: Context, options?: P
   stream.push({ type: "start", partial: output });
 
   void (async () => {
-    let workspace: string | undefined;
-    let agent: Awaited<ReturnType<typeof Agent.create>> | undefined;
     let run: Run | undefined;
     let timeout: ReturnType<typeof setTimeout> | undefined;
     let textIndex: number | undefined;
@@ -168,47 +266,31 @@ export function streamCursorSdk(model: Model<any>, context: Context, options?: P
       const apiKey = options?.apiKey?.trim();
       if (!apiKey) throw new Error("Cursor is not authenticated. Run `/login cursor`.");
       if (options?.signal?.aborted) throw new Error("Cursor request cancelled.");
-      workspace = await mkdtemp(join(tmpdir(), "pi-cursor-sdk-"));
-      const customTools: Record<string, SDKCustomTool> = {};
-      for (const tool of context.tools ?? []) {
-        customTools[tool.name] = {
-          description: tool.description,
-          inputSchema: asJsonValue(tool.parameters ?? { type: "object" }) as Record<string, SDKJsonValue>,
-          async execute(args, toolContext) {
-            if (!delegated) {
-              delegated = true;
-              endText();
-              endReasoning();
-              const toolCall = {
-                type: "toolCall" as const,
-                id: toolContext.toolCallId || `cursor_${randomUUID()}`,
-                name: tool.name,
-                arguments: asArguments(args),
-              };
-              const contentIndex = output.content.length;
-              output.content.push(toolCall);
-              stream.push({ type: "toolcall_start", contentIndex, partial: output });
-              stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(toolCall.arguments), partial: output });
-              stream.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
-              queueMicrotask(() => { void run?.cancel().catch(() => undefined); });
-            }
-            return { content: [{ type: "text", text: TOOL_DELEGATION_RESULT }], isError: true };
-          },
-        };
-      }
 
-      const selection = resolveCursorModelSelection(model, typeof options?.reasoning === "string" ? options.reasoning : undefined, loadCursorCatalog());
-      agent = await Agent.create({
-        apiKey,
-        model: selection,
-        tools: context.tools?.length ? ["mcp"] : [],
-        local: {
-          cwd: workspace,
-          store: new JsonlLocalAgentStore(join(workspace, "state")),
-          customTools,
-          enableAgentRetries: options?.maxRetries !== 0,
+      const activeHandler: ActiveToolHandler = {
+        onToolCall(toolName, args, toolCallId) {
+          if (!delegated) {
+            delegated = true;
+            endText();
+            endReasoning();
+            const toolCall = {
+              type: "toolCall" as const,
+              id: toolCallId || `cursor_${randomUUID()}`,
+              name: toolName,
+              arguments: asArguments(args),
+            };
+            const contentIndex = output.content.length;
+            output.content.push(toolCall);
+            stream.push({ type: "toolcall_start", contentIndex, partial: output });
+            stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(toolCall.arguments), partial: output });
+            stream.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
+            queueMicrotask(() => { void run?.cancel().catch(() => undefined); });
+          }
         },
-      });
+      };
+
+      const selection = resolveCursorModelSelection(model, typeof options?.reasoning === "string" ? options.reasoning : undefined, loadCursorCatalog());
+      const { agent } = await getOrInitWarmAgent(apiKey, selection, context.tools, activeHandler, options?.maxRetries !== 0);
 
       const request = serializeCursorContext(context);
       run = await agent.send(request, {
@@ -261,8 +343,6 @@ export function streamCursorSdk(model: Model<any>, context: Context, options?: P
       stream.end();
     } finally {
       if (timeout) clearTimeout(timeout);
-      await disposeAgent(agent);
-      if (workspace) await rm(workspace, { recursive: true, force: true }).catch(() => undefined);
     }
   })();
 

package/extensions/cursor-provider/index.ts

@@ -9,7 +9,7 @@ import {
   loadCursorCatalog,
   toCursorPiModels,
 } from "./cursor/models.ts";
-import { streamCursorSdk } from "./cursor/stream.ts";
+import { clearCursorAgentPool, streamCursorSdk } from "./cursor/stream.ts";
 import { fetchCursorUsage } from "./cursor/usage.ts";
 
 export default async function cursorProviderExtension(pi: ExtensionAPI) {
@@ -50,6 +50,10 @@ export default async function cursorProviderExtension(pi: ExtensionAPI) {
     (ctx.modelRegistry as any).authStorage?.reload?.();
   });
 
+  pi.on("session_shutdown", async () => {
+    await clearCursorAgentPool();
+  });
+
   pi.registerCommand("cursor", {
     description: "Open Cursor account, monthly usage, and limits dashboard",
     handler: async (_args, ctx) => {
@@ -83,6 +87,7 @@ export default async function cursorProviderExtension(pi: ExtensionAPI) {
     deactivate: async () => {
       try {
         pi.unregisterProvider(CURSOR_PROVIDER_ID);
+        await clearCursorAgentPool();
       } catch {
         // Ignore teardown after partial startup.
       }

package/extensions/input-mode/README.md

@@ -3,7 +3,7 @@
 Controls what ordinary **Enter** does when the interactive Pi agent is already running:
 
 - `steer` (default) queues the message before the agent's next model step.
-- `interrupt` signals Pi's active abort controller immediately, then preserves the submitted text, images, prompt-template expansion, and normal delivery as the next input.
+- `interrupt` signals Pi's active abort controller immediately, retains the submitted text and images, then starts a fresh turn at Pi's safe `agent_settled` boundary. Multiple inputs received during cancellation are preserved in order in that replacement turn.
 - `follow-up` queues the message until the active run finishes.
 
 Use `/input-mode` for the picker or `/input-mode steer|interrupt|follow-up` for direct selection. The global choice is stored with restrictive permissions in `<agent-dir>/input-mode.json`; non-default modes appear in Pi's status area.

package/extensions/input-mode/index.ts

@@ -14,20 +14,30 @@ import {
 } from "./config.ts";
 
 const STATUS_KEY = "input-mode";
+type ModelInput = Parameters<ExtensionAPI["sendUserMessage"]>[0];
 
 interface InputModeExtensionOptions {
   configFile?: string;
 }
 
-function modelInput(event: InputEvent) {
+function modelInput(event: InputEvent): ModelInput {
   if (!event.images?.length) return event.text;
   return [{ type: "text" as const, text: event.text }, ...event.images];
 }
 
+function mergeInputs(inputs: ModelInput[]): ModelInput {
+  if (inputs.length === 1) return inputs[0]!;
+  return inputs.flatMap((input, index) => [
+    ...(index === 0 ? [] : [{ type: "text" as const, text: "\n\n---\n\n" }]),
+    ...(typeof input === "string" ? [{ type: "text" as const, text: input }] : input),
+  ]);
+}
+
 export function createInputModeExtension(options: InputModeExtensionOptions = {}) {
   return (pi: ExtensionAPI) => {
     let mode = loadInputMode(options.configFile);
     let ui: ExtensionUIContext | undefined;
+    const pendingInterrupts: ModelInput[] = [];
 
     const updateStatus = () => {
       if (!ui) return;
@@ -74,7 +84,14 @@ export function createInputModeExtension(options: InputModeExtensionOptions = {}
       updateStatus();
     });
 
+    pi.on("agent_settled", () => {
+      if (pendingInterrupts.length === 0) return;
+      const input = mergeInputs(pendingInterrupts.splice(0));
+      pi.sendUserMessage(input, { expandPromptTemplates: true });
+    });
+
     pi.on("session_shutdown", () => {
+      pendingInterrupts.length = 0;
       ui?.setStatus(STATUS_KEY, undefined);
       ui = undefined;
     });
@@ -91,12 +108,12 @@ export function createInputModeExtension(options: InputModeExtensionOptions = {}
         return { action: "handled" };
       }
 
-      // Abort is signalled synchronously. Returning continue preserves Pi's
-      // normal template expansion, image handling, history, and queue logic;
-      // the prompt becomes a fresh turn if abort settlement wins the race, or
-      // a steering message consumed immediately after the aborted run.
+      // Store before signalling abort so even a very fast settlement cannot
+      // race past the replacement input. agent_settled is Pi's safe idle edge;
+      // it starts one fresh turn after model/tool cancellation completes.
+      pendingInterrupts.push(modelInput(event));
       ctx.abort();
-      return { action: "continue" };
+      return { action: "handled" };
     });
   };
 }

package/extensions/shared/README.md

@@ -8,7 +8,7 @@ Internal runtime utilities used by more than one extension. This directory is no
 - `child-session.ts` owns trust-aware child resources and bounded session shutdown.
 - `context-utilization.ts` formats model-context usage and capacity.
 - `dashboard-state.ts` keeps list selection stable as live rows change.
-- `settlement-delivery.ts` immediately hands asynchronous results to Pi as extension-originated user follow-ups, guaranteeing model-visible settlement context.
+- `settlement-delivery.ts` coordinates asynchronous output in a private package-wide queue and starts one custom-result turn at Pi's safe idle edge, guaranteeing model-visible context without user-authored or follow-up rendering.
 - `tool-call-timeout.ts` applies cancellation-aware execution limits to registered tools.
 - `tui-dashboard.ts` provides bounded, sanitized terminal-dashboard rendering helpers.
 

package/extensions/shared/settlement-delivery.ts

@@ -1,19 +1,82 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 type SettlementMessage = Parameters<ExtensionAPI["sendMessage"]>[0];
+type DeliverSettlement = (message: SettlementMessage) => void;
+
+type SessionKey = object;
+
+interface Coordinator {
+  parentActive: boolean;
+  shuttingDown: boolean;
+  pending: SettlementMessage[];
+  flush(): void;
+}
+
+const coordinators = new WeakMap<SessionKey, Coordinator>();
+
+function createCoordinator(pi: ExtensionAPI): Coordinator {
+  const coordinator: Coordinator = {
+    parentActive: false,
+    shuttingDown: false,
+    pending: [],
+    flush() {
+      if (coordinator.parentActive || coordinator.shuttingDown || coordinator.pending.length === 0) return;
+      const batch = coordinator.pending.splice(0);
+      for (const message of batch.slice(0, -1)) {
+        pi.sendMessage(message, { triggerTurn: false });
+      }
+      pi.sendMessage(batch.at(-1)!, { triggerTurn: true });
+    },
+  };
+  return coordinator;
+}
 
 /**
- * Hand settlement to Pi as an extension-originated user follow-up. A custom
- * message can wake the parent yet fail to appear in the invoked model turn;
- * sendUserMessage guarantees that the bounded result is model-visible. Pi
- * starts a turn when idle and queues the same input while the parent is active.
+ * Coordinate asynchronous results across every suite extension in one Pi
+ * session. Results that settle during a parent run stay in a private local
+ * queue until agent_settled; Pi never renders them as queued user/follow-up
+ * input. At the safe idle edge, earlier results are appended and the final
+ * custom result starts exactly one model turn with the whole batch in context.
  */
-export function deliverSettlement(pi: ExtensionAPI, message: SettlementMessage): void {
-  const content = typeof message.content === "string"
-    ? message.content
-    : message.content
-      .filter((part) => part.type === "text")
-      .map((part) => part.text)
-      .join("\n");
-  pi.sendUserMessage(content, { deliverAs: "followUp" });
+export function settlementDelivery(pi: ExtensionAPI): DeliverSettlement {
+  let coordinator: Coordinator | undefined;
+  let sessionKey: SessionKey | undefined;
+
+  pi.on("session_start", (_event, ctx) => {
+    sessionKey = (ctx.sessionManager ?? ctx) as SessionKey;
+    coordinator = coordinators.get(sessionKey);
+    if (!coordinator) {
+      coordinator = createCoordinator(pi);
+      coordinators.set(sessionKey, coordinator);
+    }
+    coordinator.parentActive = false;
+    coordinator.shuttingDown = false;
+  });
+  pi.on("agent_start", () => {
+    if (coordinator) coordinator.parentActive = true;
+  });
+  pi.on("agent_settled", () => {
+    if (!coordinator) return;
+    coordinator.parentActive = false;
+    coordinator.flush();
+  });
+  pi.on("session_shutdown", () => {
+    if (coordinator) {
+      coordinator.shuttingDown = true;
+      coordinator.parentActive = false;
+      coordinator.pending.length = 0;
+    }
+    if (sessionKey) coordinators.delete(sessionKey);
+    coordinator = undefined;
+    sessionKey = undefined;
+  });
+
+  return (message) => {
+    // session_start precedes model-owned terminal/subagent work. Fail closed if
+    // a malformed host calls delivery before initialization instead of showing
+    // asynchronous output as user-authored input.
+    if (!coordinator || coordinator.shuttingDown) return;
+    coordinator.pending.push(message);
+    coordinator.flush();
+  };
 }

package/extensions/subagents/README.md

@@ -19,7 +19,7 @@ The system is deliberately flat. Only the main Pi thread can spawn subagents. Ch
 - `reply_question` — answer a child’s blocking `ask_parent` request
 - `task` — atomically reserve capacity for up to the configured limit (maximum 50), start the fan-out in the background, and return child ids immediately
 
-Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Child settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context, so the main turn can continue independent work or end and remain available to the user.
+Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Child settlement stays in a private extension queue while the parent is active, then starts one custom-result turn at Pi's safe idle edge with the summary guaranteed in model context and never rendered as user-authored or follow-up input, so the main turn can continue independent work or end and remain available to the user.
 
 ## Profiles and capabilities
 

package/extensions/subagents/index.ts

@@ -26,7 +26,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { deliverSettlement } from "../shared/settlement-delivery.ts";
+import { settlementDelivery } from "../shared/settlement-delivery.ts";
 import {
   formatElapsed,
   latestText,
@@ -195,6 +195,7 @@ function resolveChildProjectTrust(options: {
 }
 
 export default function (pi: ExtensionAPI) {
+  const deliverSettlement = settlementDelivery(pi);
   let runtime: SubagentRuntime | undefined;
   let managerPromise: Promise<SubagentManagerShape> | undefined;
   let ui: ExtensionUIContext | undefined;
@@ -522,7 +523,7 @@ export default function (pi: ExtensionAPI) {
   };
 
   const deliverResult = (snap: SubagentSnapshot) => {
-    deliverSettlement(pi, {
+    deliverSettlement({
       customType: "subagent-result",
       content: buildSubagentResultMessage({
         id: snap.id,
@@ -668,7 +669,7 @@ export default function (pi: ExtensionAPI) {
     promptSnippet: SUBAGENT_SPAWN_PROMPT_SNIPPET,
     promptGuidelines: [
       ...SUBAGENT_SPAWN_PROMPT_GUIDELINES,
-      "After spawn_agent starts a child, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch it run. Settlement is handed to Pi immediately; when its attached summary invokes the parent, continue the original task without waiting for another user message.",
+      "After spawn_agent starts a child, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch it run. Settlement stays private until it starts a custom-result turn at Pi's safe idle edge; when its attached summary invokes the parent, continue the original task without waiting for another user message.",
     ],
     parameters: Type.Object({
       message: Type.String({
@@ -1096,7 +1097,7 @@ export default function (pi: ExtensionAPI) {
     label: "Start Pi Subagent Tasks",
     description: "Start independent subagent tasks together in the background and return their ids immediately. Completion notices automatically start the next parent turn, so the parent should end its current turn when no independent work remains instead of checking status.",
     promptGuidelines: [
-      "After task starts children, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch them run. Settlements are handed to Pi immediately; when their attached summaries invoke the parent, continue the original task without waiting for another user message.",
+      "After task starts children, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch them run. Settlements stay private until they start a custom-result turn at Pi's safe idle edge; when their attached summaries invoke the parent, continue the original task without waiting for another user message.",
     ],
     parameters: Type.Object({
       tasks: Type.Array(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",

package/skills/background-terminals/SKILL.md

@@ -24,7 +24,7 @@ Provide:
 - the working directory when it differs from the current directory;
 - an initial wait only when startup output is needed for the next decision.
 
-After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Ending the turn is the waiting mechanism: terminal settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next parent turn with the final status and bounded output visible in model context. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
+After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Ending the turn is the waiting mechanism: terminal settlement stays in a private extension queue while the parent is active and otherwise starts the next custom-result turn at Pi's safe idle edge, with final status and bounded output visible in model context without appearing as user-authored or follow-up input. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
 
 When that completion follow-up invokes the next turn, treat its model-visible output as the terminal result and continue the original task immediately. Do not wait for another user message, announce that you are still waiting, or call `read_terminal` to retrieve the same result again. If `start_terminal` itself returns a settled result, the output is already synchronous and no second completion notice is needed.
 

package/skills/subagents/SKILL.md

@@ -24,7 +24,7 @@ This skill governs temporary Pi child agents. The `codex-thread-orchestrator` sk
 
 ## Wait by notification; inspect progress only when justified
 
-A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next main-agent turn with the summary visible in model context. The parent does not need to remain active or check once before ending its turn.
+A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its settlement stays in a private extension queue while the parent is active and otherwise starts the next custom-result turn at Pi's safe idle edge, with the summary visible in model context without appearing as user-authored or follow-up input. The parent does not need to remain active or check once before ending its turn.
 
 After dispatch: