shariq-pi-extensions 0.2.4 → 0.2.6

package/docs/EXTENSIONS.md

@@ -6,7 +6,7 @@ Last verified: 2026-08-20
 
 ### [Antigravity Provider](../extensions/antigravity-provider/README.md)
 
-Registers the `antigravity` provider and `/login antigravity` flow for supported Google Antigravity models. Repeating login adds or updates accounts in the secure `<agent-dir>/antigravity/accounts.json` pool. Requests use quota-aware least-recently-used balancing, rotate before streaming on account-specific auth/rate/quota/capacity failures, honor known reset times, and refresh stored OAuth tokens. `/antigravity` shows account state and live model quotas and can enable or disable accounts; `/antigravity.doctor` reports sanitized provider and rotation diagnostics.
+Registers the `antigravity` provider and `/login antigravity` flow for the latest Gemini Flash, Gemini Pro, Claude Sonnet, and Claude Opus families. Repeating login adds or updates accounts in the secure `<agent-dir>/antigravity/accounts.json` pool. Requests use quota-aware least-recently-used balancing, rotate before streaming on account-specific auth/rate/quota/capacity failures, honor known reset times, and refresh stored OAuth tokens. `/antigravity` shows account state plus the shared five-hour and weekly limits for the Gemini and Claude pools and can enable or disable accounts; `/antigravity.doctor` reports sanitized provider and rotation diagnostics.
 
 ### [Cursor provider](../extensions/cursor-provider/README.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 automatically sends a follow-up that starts the next parent turn; 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 is handed to Pi immediately as a turn-triggering follow-up, so Pi queues it while the parent is active or starts a new parent turn when idle; 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 automatically sends a completion or failure follow-up and starts the next parent turn. Reading a terminal no longer suppresses 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 immediately hands its completion or failure to Pi as a turn-triggering follow-up, which Pi queues while the parent is active or uses to start a new parent turn when idle. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
 
 ## Web access
 

package/extensions/antigravity-provider/README.md

@@ -8,19 +8,18 @@ Local persistent Pi provider for Google Antigravity-compatible models.
 - Account and quota dashboard: `/antigravity`
 - Doctor command: `/antigravity.doctor`
 
-The provider includes an IPv4 OAuth token-exchange fallback for Node environments where the default request fails. Its deterministic catalog follows Antigravity CLI 1.1.13 model identifiers and runtime behavior.
+The provider includes an IPv4 OAuth token-exchange fallback for Node environments where the default request fails. Its curated catalog follows current Antigravity model identifiers and runtime behavior.
 
 Successful logins are added to `<agent-dir>/antigravity/accounts.json`, written with owner-only permissions. Existing Pi OAuth credentials are migrated into that pool without exposing token values. Requests select the least recently used eligible account, skip disabled/cooling/exhausted accounts, refresh expiring OAuth tokens, and rotate to another account when an auth, rate, quota, or capacity failure occurs before response streaming begins. Cached per-model remaining quota and reset times guide selection; `/antigravity` refreshes the authoritative catalog and can reversibly enable or disable accounts.
 
 Current public model IDs:
 - `antigravity/gemini-3.7-flash`
-- `antigravity/gemini-3.6-flash`
-- `antigravity/gemini-3.5-flash`
 - `antigravity/gemini-3.1-pro`
 - `antigravity/claude-sonnet-4-6`
 - `antigravity/claude-opus-4-6`
-- `antigravity/gpt-oss-120b`
 
-Pi's thinking selector is normalized to Antigravity's runtime IDs: Flash models clamp `off`/`minimal` to `low` and `xhigh`/`max` to `high`; Gemini 3.1 Pro clamps to its `low`/`high` pair; Claude and GPT-OSS use their single fixed-thinking runtime regardless of the selected Pi level.
+The provider intentionally exposes only the latest Gemini Flash and Pro generations and the latest Claude Sonnet and Opus family. `/antigravity` shows the shared five-hour and weekly limits for the Gemini and Claude pools instead of listing every upstream runtime variant.
+
+Pi's thinking selector is normalized to Antigravity's runtime IDs: Gemini 3.7 Flash clamps `off`/`minimal` to `low` and `xhigh`/`max` to `high`; Gemini 3.1 Pro clamps to its `low`/`high` pair; Claude models use their fixed-thinking runtime regardless of the selected Pi level.
 
 The provider id intentionally remains `antigravity`; existing `~/.pi/agent/auth.json` credentials continue to work without moving secret values. After updating `agy`, compare `agy models` with `antigravity/models.ts` before changing this deterministic catalog.

package/extensions/antigravity-provider/antigravity/accounts.ts

@@ -14,11 +14,13 @@ const CAPACITY_COOLDOWN_MS = 60 * 1_000;
 const REFRESH_SKEW_MS = 60 * 1_000;
 
 export type AntigravityQuotaGroup = "gemini" | "non-gemini";
+export type AntigravityQuotaWindow = "five-hour" | "weekly";
 
 export interface AntigravityQuotaEntry {
   modelId: string;
   displayName?: string;
   group: AntigravityQuotaGroup;
+  window?: AntigravityQuotaWindow;
   remainingFraction: number;
   resetTime?: string;
 }
@@ -78,6 +80,7 @@ function normalizeAccount(value: unknown): AntigravityAccount | undefined {
           modelId: entry.modelId,
           displayName: typeof entry.displayName === "string" ? entry.displayName : undefined,
           group: entry.group,
+          window: entry.window === "five-hour" || entry.window === "weekly" ? entry.window : undefined,
           remainingFraction: Math.max(0, Math.min(1, remainingFraction)),
           resetTime: typeof entry.resetTime === "string" ? entry.resetTime : undefined,
         }];
@@ -281,7 +284,74 @@ export function updateAntigravityAccountQuota(id: string, quota: AntigravityQuot
 }
 
 export function parseAntigravityQuota(value: unknown): AntigravityQuotaEntry[] {
-  const entries: AntigravityQuotaEntry[] = [];
+  const findGroups = (node: unknown): unknown[] | undefined => {
+    if (!node || typeof node !== "object") return undefined;
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        const found = findGroups(item);
+        if (found) return found;
+      }
+      return undefined;
+    }
+    const raw = node as Record<string, unknown>;
+    if (Array.isArray(raw.groups)) return raw.groups;
+    for (const child of Object.values(raw)) {
+      const found = findGroups(child);
+      if (found) return found;
+    }
+    return undefined;
+  };
+
+  const summaryEntries: AntigravityQuotaEntry[] = [];
+  for (const groupValue of findGroups(value) ?? []) {
+    if (!groupValue || typeof groupValue !== "object") continue;
+    const group = groupValue as Record<string, unknown>;
+    const groupLabel = [group.displayName, group.name, group.id].find((item): item is string => typeof item === "string") ?? "";
+    const quotaGroup: AntigravityQuotaGroup | undefined = /gemini/i.test(groupLabel)
+      ? "gemini"
+      : /claude|third.party|3p|gpt/i.test(groupLabel)
+        ? "non-gemini"
+        : undefined;
+    if (!quotaGroup || !Array.isArray(group.buckets)) continue;
+    for (const bucketValue of group.buckets) {
+      if (!bucketValue || typeof bucketValue !== "object") continue;
+      const bucket = bucketValue as Record<string, unknown>;
+      const remaining = bucket.remaining && typeof bucket.remaining === "object"
+        ? bucket.remaining as Record<string, unknown>
+        : undefined;
+      const remainingFraction = finiteNumber(bucket.remainingFraction) ?? finiteNumber(remaining?.remainingFraction);
+      const windowLabel = [bucket.window, bucket.bucketId, bucket.displayName].find((item): item is string => typeof item === "string") ?? "";
+      const window: AntigravityQuotaWindow | undefined = /week/i.test(windowLabel)
+        ? "weekly"
+        : /5h|five.?hour/i.test(windowLabel)
+          ? "five-hour"
+          : undefined;
+      if (remainingFraction === undefined || !window) continue;
+      summaryEntries.push({
+        modelId: typeof bucket.bucketId === "string" ? bucket.bucketId : `${quotaGroup}-${window}`,
+        displayName: window === "weekly" ? "Weekly" : "5-Hour",
+        group: quotaGroup,
+        window,
+        remainingFraction: Math.max(0, Math.min(1, remainingFraction)),
+        resetTime: typeof bucket.resetTime === "string"
+          ? bucket.resetTime
+          : typeof remaining?.resetTime === "string"
+            ? remaining.resetTime
+            : undefined,
+      });
+    }
+  }
+  if (summaryEntries.length) return summaryEntries;
+
+  const supportedRuntimeIds = new Set(
+    Object.entries(ANTIGRAVITY_ROUTING).flatMap(([modelId, routing]) => [
+      modelId,
+      routing.off,
+      routing.defaultRequestId,
+      ...Object.values(routing.routing ?? {}),
+    ]).filter((item): item is string => typeof item === "string"),
+  );
+  const modelEntries: AntigravityQuotaEntry[] = [];
   const seen = new Set<string>();
   const visit = (node: unknown, keyHint?: string) => {
     if (!node || typeof node !== "object") return;
@@ -291,17 +361,17 @@ export function parseAntigravityQuota(value: unknown): AntigravityQuotaEntry[] {
     }
     const raw = node as Record<string, unknown>;
     const quota = raw.quotaInfo && typeof raw.quotaInfo === "object" ? raw.quotaInfo as Record<string, unknown> : raw;
-    const remaining = finiteNumber(quota.remainingFraction);
-    const modelId = [raw.modelId, raw.id, raw.name, raw.model, keyHint].find((item): item is string => typeof item === "string" && /gemini|claude|gpt-oss/i.test(item));
-    if (modelId && remaining !== undefined) {
+    const remainingFraction = finiteNumber(quota.remainingFraction);
+    const modelId = [raw.modelId, raw.id, raw.name, raw.model, keyHint].find((item): item is string => typeof item === "string");
+    if (modelId && remainingFraction !== undefined) {
       const normalized = modelId.replace(/^models\//, "");
-      if (!seen.has(normalized)) {
+      if (supportedRuntimeIds.has(normalized) && !seen.has(normalized)) {
         seen.add(normalized);
-        entries.push({
+        modelEntries.push({
           modelId: normalized,
-          displayName: typeof raw.displayName === "string" ? raw.displayName : typeof raw.label === "string" ? raw.label : undefined,
           group: normalized.startsWith("gemini-") ? "gemini" : "non-gemini",
-          remainingFraction: Math.max(0, Math.min(1, remaining)),
+          window: "five-hour",
+          remainingFraction: Math.max(0, Math.min(1, remainingFraction)),
           resetTime: typeof quota.resetTime === "string" ? quota.resetTime : undefined,
         });
       }
@@ -311,7 +381,16 @@ export function parseAntigravityQuota(value: unknown): AntigravityQuotaEntry[] {
     }
   };
   visit(value);
-  return entries;
+
+  return (["gemini", "non-gemini"] as const).flatMap((group) => {
+    const entries = modelEntries.filter((entry) => entry.group === group).sort((left, right) => left.remainingFraction - right.remainingFraction);
+    const mostConstrained = entries[0];
+    return mostConstrained ? [{
+      ...mostConstrained,
+      modelId: group === "gemini" ? "gemini-5h" : "claude-5h",
+      displayName: "5-Hour",
+    }] : [];
+  });
 }
 
 const refreshes = new Map<string, Promise<AntigravityAccount>>();

package/extensions/antigravity-provider/antigravity/dashboard.ts

@@ -29,7 +29,22 @@ function until(timestamp: number | string | undefined) {
 }
 
 function groupQuota(quota: AntigravityQuotaEntry[] | undefined, group: "gemini" | "non-gemini") {
-  return (quota ?? []).filter((entry) => entry.group === group).sort((left, right) => left.remainingFraction - right.remainingFraction);
+  const byWindow = new Map<"five-hour" | "weekly", AntigravityQuotaEntry>();
+  for (const entry of (quota ?? []).filter((candidate) => candidate.group === group)) {
+    const window = entry.window ?? "five-hour";
+    const existing = byWindow.get(window);
+    if (!existing || entry.remainingFraction < existing.remainingFraction) {
+      byWindow.set(window, {
+        ...entry,
+        window,
+        displayName: window === "weekly" ? "Weekly" : "5-Hour",
+      });
+    }
+  }
+  return (["five-hour", "weekly"] as const).flatMap((window) => {
+    const entry = byWindow.get(window);
+    return entry ? [entry] : [];
+  });
 }
 
 function accountState(account: AntigravityAccountStatus) {
@@ -50,8 +65,7 @@ function stateColor(state: string) {
 
 function compactGroup(label: string, entries: AntigravityQuotaEntry[]) {
   if (!entries.length) return `${label}: unavailable`;
-  const worst = entries[0]!;
-  return `${label}: ${remaining(worst.remainingFraction)} remaining${worst.resetTime ? ` · resets ${until(worst.resetTime)}` : ""}`;
+  return `${label}: ${entries.map((entry) => `${entry.displayName} ${remaining(entry.remainingFraction)}${entry.resetTime ? ` · resets ${until(entry.resetTime)}` : ""}`).join(" · ")}`;
 }
 
 export class AntigravityDashboard implements Component {
@@ -159,7 +173,7 @@ export class AntigravityDashboard implements Component {
     const lines = width >= 64
       ? [joinSides(title, `${right}  `, width)]
       : [truncateToWidth(title, width, ""), truncateToWidth(`  ${right}`, width, "")];
-    lines.push(frameTop(this.theme, width, `ACCOUNTS ${accounts.length} · QUOTA REMAINING`));
+    lines.push(frameTop(this.theme, width, `ACCOUNTS ${accounts.length} · 5-HOUR + WEEKLY LIMITS REMAINING`));
     const inner = Math.max(1, width - 2);
     if (width >= 104 && selected) {
       const leftWidth = Math.max(46, Math.floor((inner - 1) * 0.45));
@@ -195,7 +209,7 @@ export class AntigravityDashboard implements Component {
       lines.push(selected ? this.theme.bg("selectedBg", padLine(first, width)) : first);
       if (!compact) {
         lines.push(`   ${this.theme.fg("muted", compactGroup("Gemini", groupQuota(account.quota, "gemini")))}`);
-        lines.push(`   ${this.theme.fg("muted", compactGroup("Claude / GPT", groupQuota(account.quota, "non-gemini")))}`);
+        lines.push(`   ${this.theme.fg("muted", compactGroup("Claude", groupQuota(account.quota, "non-gemini")))}`);
         lines.push("");
       }
     }
@@ -211,8 +225,8 @@ export class AntigravityDashboard implements Component {
     if (account.cooldownUntil && account.cooldownUntil > Date.now()) lines.push(` ${this.theme.fg("warning", `${account.cooldownReason || "rotation"} cooldown · ${until(account.cooldownUntil)}`)}`);
     if (account.quotaError) lines.push(` ${this.theme.fg("error", oneLine(account.quotaError))}`);
     if (account.lastError) lines.push(` ${this.theme.fg("warning", oneLine(account.lastError))}`);
-    lines.push("", ...this.renderQuotaGroup("Gemini", groupQuota(account.quota, "gemini"), width));
-    lines.push("", ...this.renderQuotaGroup("Claude / GPT-OSS", groupQuota(account.quota, "non-gemini"), width));
+    lines.push("", ...this.renderQuotaGroup("Gemini models", groupQuota(account.quota, "gemini"), width));
+    lines.push("", ...this.renderQuotaGroup("Claude models", groupQuota(account.quota, "non-gemini"), width));
     if (account.lastUsedAt) lines.push("", ` ${this.theme.fg("muted", "LAST USED")} ${this.theme.fg("text", new Date(account.lastUsedAt).toLocaleString())}`);
     return lines.slice(0, height);
   }
@@ -221,7 +235,7 @@ export class AntigravityDashboard implements Component {
     const lines = [` ${this.theme.fg("accent", this.theme.bold(`${name.toUpperCase()} · REMAINING`))}`];
     if (!entries.length) return [...lines, ` ${this.theme.fg("muted", "Unavailable")}`];
     const meterWidth = Math.max(10, width - 29);
-    for (const entry of entries.slice(0, 8)) {
+    for (const entry of entries) {
       const percent = entry.remainingFraction * 100;
       const color = percent <= 0 ? "error" : percent <= 15 ? "warning" : "active";
       const label = oneLine(entry.displayName || entry.modelId).slice(0, 16).padEnd(16);

package/extensions/antigravity-provider/antigravity/models.ts

@@ -59,42 +59,6 @@ export const ANTIGRAVITY_ROUTING: Record<string, AntigravityRouting> = {
 		},
 		defaultRequestId: "gemini-3.7-flash-low",
 	},
-	"gemini-3.6-flash": {
-		off: "gemini-3.6-flash-low",
-		routing: {
-			minimal: "gemini-3.6-flash-low",
-			low: "gemini-3.6-flash-low",
-			medium: "gemini-3.6-flash-medium",
-			high: "gemini-3.6-flash-high",
-			xhigh: "gemini-3.6-flash-high",
-			max: "gemini-3.6-flash-high",
-		},
-		defaultRequestId: "gemini-3.6-flash-low",
-	},
-	"gemini-3.5-flash": {
-		off: "gemini-3.5-flash-extra-low",
-		routing: {
-			minimal: "gemini-3.5-flash-extra-low",
-			low: "gemini-3.5-flash-extra-low",
-			medium: "gemini-3.5-flash-low",
-			high: "gemini-3-flash-agent",
-			xhigh: "gemini-3-flash-agent",
-			max: "gemini-3-flash-agent",
-		},
-		defaultRequestId: "gemini-3.5-flash-low",
-	},
-	"gpt-oss-120b": {
-		off: "gpt-oss-120b-medium",
-		routing: {
-			minimal: "gpt-oss-120b-medium",
-			low: "gpt-oss-120b-medium",
-			medium: "gpt-oss-120b-medium",
-			high: "gpt-oss-120b-medium",
-			xhigh: "gpt-oss-120b-medium",
-			max: "gpt-oss-120b-medium",
-		},
-		defaultRequestId: "gpt-oss-120b-medium",
-	},
 };
 
 export const ANTIGRAVITY_MODELS: ProviderModelConfig[] = [
@@ -138,36 +102,6 @@ export const ANTIGRAVITY_MODELS: ProviderModelConfig[] = [
 		contextWindow: 1048576,
 		maxTokens: 65536,
 	},
-	{
-		id: "gemini-3.6-flash",
-		name: "Gemini 3.6 Flash (Antigravity)",
-		reasoning: true,
-		thinkingLevelMap: { off: null, minimal: "LOW", low: "LOW", medium: "MEDIUM", high: "HIGH", xhigh: "HIGH", max: "HIGH" } as any,
-		input: ["text", "image"],
-		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-		contextWindow: 1048576,
-		maxTokens: 65536,
-	},
-	{
-		id: "gemini-3.5-flash",
-		name: "Gemini 3.5 Flash (Antigravity)",
-		reasoning: true,
-		thinkingLevelMap: { off: null, minimal: "LOW", low: "LOW", medium: "MEDIUM", high: "HIGH", xhigh: "HIGH", max: "HIGH" } as any,
-		input: ["text", "image"],
-		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-		contextWindow: 1048576,
-		maxTokens: 65536,
-	},
-	{
-		id: "gpt-oss-120b",
-		name: "GPT-OSS 120B (Antigravity)",
-		reasoning: true,
-		thinkingLevelMap: { off: null, minimal: "MEDIUM", low: "MEDIUM", medium: "MEDIUM", high: "MEDIUM", xhigh: "MEDIUM", max: "MEDIUM" } as any,
-		input: ["text"],
-		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-		contextWindow: 131072,
-		maxTokens: 32768,
-	},
 ];
 
 export function getAntigravityRequestModelId(modelId: string, effort: string | undefined): string {

package/extensions/antigravity-provider/antigravity/oauth.ts

@@ -322,8 +322,28 @@ function findDynamicModel(value: any, requestedId: string): DynamicModelInfo | u
 
 export async function fetchAntigravityQuotaCatalog(token: string, projectId: string, signal?: AbortSignal): Promise<unknown> {
 	let lastFailure = "Antigravity quota catalog is unavailable.";
-	const bodies = [{}, { cloudaicompanionProject: projectId }, { project: projectId }];
 	for (const endpoint of endpointCandidates()) {
+		try {
+			const res = await fetch(`${endpoint}/v1internal:retrieveUserQuotaSummary`, {
+				method: "POST",
+				headers: antigravityHeaders(token),
+				body: "{}",
+				signal: boundedFetchSignal(signal),
+			});
+			lastStatus = res.status;
+			lastEndpoint = endpoint;
+			if (res.ok) {
+				const summary = await res.json() as { groups?: unknown[] };
+				if (Array.isArray(summary.groups) && summary.groups.length) return summary;
+			}
+			else lastFailure = `HTTP ${res.status}: ${jsonOrTextError(await res.text())}`;
+		} catch (error) {
+			if (signal?.aborted) throw error;
+			lastFailure = safeError(error);
+			lastError = lastFailure;
+		}
+
+		const bodies = [{}, { cloudaicompanionProject: projectId }, { project: projectId }];
 		for (const candidateBody of bodies) {
 			try {
 				const res = await fetch(`${endpoint}/v1internal:fetchAvailableModels`, {

package/extensions/antigravity-provider/antigravity/quotas.ts

@@ -20,7 +20,9 @@ export function refreshAntigravityQuotas(options: { force?: boolean; signal?: Ab
     const accounts = antigravityAccountStatuses(now);
     for (const account of accounts) {
       if (account.disabled) continue;
-      if (!options.force && account.quotaUpdatedAt && now - account.quotaUpdatedAt < ANTIGRAVITY_QUOTA_TTL_MS) continue;
+      const hasBothWindows = account.quota?.some((entry) => entry.window === "five-hour") &&
+        account.quota.some((entry) => entry.window === "weekly");
+      if (!options.force && hasBothWindows && account.quotaUpdatedAt && now - account.quotaUpdatedAt < ANTIGRAVITY_QUOTA_TTL_MS) continue;
       try {
         const resolved = await resolveAntigravityAccount(account, refreshAntigravityToken, now);
         const catalog = await fetchAntigravityQuotaCatalog(resolved.access, resolved.projectId, options.signal);

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. Completion wakes the parent automatically, so it 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 is handed to Pi immediately: it queues a follow-up while the parent is active or starts a new parent turn when idle, so the parent can continue other work or end its turn rather than poll.
 
 ## User interface
 
@@ -34,7 +34,7 @@ Each output response carries a byte cursor. Pass it to the next read/write opera
 - Output is sanitized before TUI or model rendering.
 - Processes run in their own PTY process group and are stopped on session shutdown, replacement, or reload.
 - Shutdown and stop operations are bounded and escalate from SIGTERM to SIGKILL.
-- Model-started terminals automatically deliver one completion/failure follow-up that starts the next parent turn.
+- Model-started terminals immediately hand one completion/failure follow-up to Pi; Pi queues it while the parent is active or starts the next parent turn when idle.
 - Reading settled output does not consume or suppress the automatic completion delivery.
 - Completion delivery is keyed by terminal id to prevent duplicate follow-ups.
 

package/extensions/background-terminals/index.ts

@@ -3,12 +3,12 @@ import * as path from "node:path";
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
-  ExtensionContext,
   ExtensionUIContext,
 } from "@earendil-works/pi-coding-agent";
 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 { oneLine, sanitizeTerminalText, stateLabel } from "../shared/tui-dashboard.ts";
 import { TerminalManager, MAX_RUNNING_TERMINALS } from "./src/manager.ts";
 import {
@@ -37,12 +37,12 @@ function resolveCwd(base: string, requested?: string): string {
 
 export default function backgroundTerminals(pi: ExtensionAPI) {
   let manager: TerminalManager | undefined;
-  let sessionContext: ExtensionContext | undefined;
   let ui: ExtensionUIContext | undefined;
   let unsubscribe: (() => void) | undefined;
   let lastStatus = "";
   const pendingResults = new Map<string, TerminalSnapshot>();
   const modelOwned = new Set<string>();
+  const starting = new Set<string>();
 
   const getManager = (): TerminalManager => {
     if (manager) return manager;
@@ -56,7 +56,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
         return;
       }
       pendingResults.set(snapshot.id, snapshot);
-      if (sessionContext?.isIdle()) flushResults();
+      if (!starting.has(snapshot.id)) flushResult(snapshot.id);
     });
     unsubscribe = manager.view.subscribe(updateStatus);
     updateStatus();
@@ -85,40 +85,31 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     }
   }
 
-  function deliver(snapshot: TerminalSnapshot): void {
-    pi.sendMessage(
-      {
-        customType: "background-terminal-result",
-        content: formatCompletion(snapshot),
-        display: true,
-        details: {
-          id: snapshot.id,
-          title: snapshot.title,
-          status: snapshot.status,
-          exitCode: snapshot.exitCode,
-        },
+  function flushResult(id: string): void {
+    const snapshot = pendingResults.get(id);
+    if (!snapshot) return;
+    pendingResults.delete(id);
+    deliverSettlement(pi, {
+      customType: "background-terminal-result",
+      content: formatCompletion(snapshot),
+      display: true,
+      details: {
+        id: snapshot.id,
+        title: snapshot.title,
+        status: snapshot.status,
+        exitCode: snapshot.exitCode,
       },
-      { deliverAs: "followUp", triggerTurn: true },
-    );
-  }
-
-  function flushResults(): void {
-    const results = [...pendingResults.values()];
-    pendingResults.clear();
-    for (const snapshot of results) deliver(snapshot);
+    });
   }
 
   pi.on("session_start", (_event, ctx) => {
-    sessionContext = ctx;
     if (ctx.hasUI) ui = ctx.ui;
   });
 
-  pi.on("agent_settled", flushResults);
-
   pi.on("session_shutdown", async () => {
-    sessionContext = undefined;
     pendingResults.clear();
     modelOwned.clear();
+    starting.clear();
     unsubscribe?.();
     unsubscribe = undefined;
     ui?.setStatus(STATUS_KEY, undefined);
@@ -140,7 +131,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. The terminal completion automatically sends a follow-up and starts the next parent turn; 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 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.",
       "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({
@@ -158,6 +149,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
         cwd: resolveCwd(ctx.cwd, params.working_dir),
       });
       modelOwned.add(terminal.id);
+      starting.add(terminal.id);
       let result: TerminalReadResult;
       try {
         result = await getManager().read(terminal.id, {
@@ -166,12 +158,15 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
           signal,
         });
       } catch (error) {
-        await getManager().kill([terminal.id]).catch(() => undefined);
+        starting.delete(terminal.id);
         modelOwned.delete(terminal.id);
+        await getManager().kill([terminal.id]).catch(() => undefined);
         consume(terminal.id);
         throw error;
       }
+      starting.delete(terminal.id);
       if (result.snapshot.status !== "running") consume(terminal.id);
+      else flushResult(terminal.id);
       let text = `Started background terminal ${terminal.id} "${oneLine(terminal.title)}" (pid ${terminal.pid}). Use cursor ${result.cursor} for incremental reads.`;
       if (result.text || result.snapshot.status !== "running") {
         text += `\n\n${formatReadResult(result)}`;

package/extensions/shared/README.md

@@ -8,6 +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 turn-triggering follow-ups.
 - `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

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type SettlementMessage = Parameters<ExtensionAPI["sendMessage"]>[0];
+
+/**
+ * Hand settlement to Pi immediately. Pi starts a turn when idle and queues the
+ * same message as a follow-up when the parent is still running.
+ */
+export function deliverSettlement(pi: ExtensionAPI, message: SettlementMessage): void {
+  pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+}

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. Background completions wake the parent automatically, 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 is handed to Pi immediately: it queues a follow-up while the parent is active or starts a new parent turn when idle, so the main turn can continue independent work or end and remain available to the user.
 
 ## Profiles and capabilities
 
@@ -86,4 +86,3 @@ Children share the requested workspace by default. Use `isolation: "worktree"` o
 - `src/worktree.ts` — isolated worktree creation, inspection, conflict preflight, integration, and cleanup
 - `src/runtime.ts` — managed runtime and Pi backend registry
 - `src/ui/` — dashboard, transcript, and takeover components
-- `src/result-delivery.ts` — deferred automatic result delivery

package/extensions/subagents/index.ts

@@ -26,6 +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 {
   formatElapsed,
   latestText,
@@ -56,7 +57,6 @@ import {
   SUBAGENT_WAIT_TOOL_DESCRIPTION,
   WORKTREE_ISOLATION_DESCRIPTION,
 } from "./src/prompt.ts";
-import { createDeferredResultDelivery } from "./src/result-delivery.ts";
 import {
   CAPABILITY_MODES,
   ISOLATION_MODES,
@@ -197,10 +197,8 @@ function resolveChildProjectTrust(options: {
 export default function (pi: ExtensionAPI) {
   let runtime: SubagentRuntime | undefined;
   let managerPromise: Promise<SubagentManagerShape> | undefined;
-  let sessionContext: ExtensionContext | undefined;
   let ui: ExtensionUIContext | undefined;
   let unsubStatus: (() => void) | undefined;
-  const resultDelivery = createDeferredResultDelivery<SubagentSnapshot>();
   const archived = new Map<string, ArchivedSubagent>();
   const peerHistory: PeerMessage[] = [];
   const pendingQuestions = new Map<
@@ -524,35 +522,24 @@ export default function (pi: ExtensionAPI) {
   };
 
   const deliverResult = (snap: SubagentSnapshot) => {
-    pi.sendMessage(
-      {
-        customType: "subagent-result",
-        content: buildSubagentResultMessage({
-          id: snap.id,
-          title: snap.title,
-          status: snap.status,
-          errorText: snap.errorText,
-          output: truncatedOutput(snap),
-        }),
-        display: true,
-        details: { id: snap.id, title: snap.title, status: snap.status },
-      },
-      { deliverAs: "followUp", triggerTurn: true },
-    );
-  };
-
-  const flushResults = () => {
-    for (const snap of resultDelivery.drain()) deliverResult(snap);
+    deliverSettlement(pi, {
+      customType: "subagent-result",
+      content: buildSubagentResultMessage({
+        id: snap.id,
+        title: snap.title,
+        status: snap.status,
+        errorText: snap.errorText,
+        output: truncatedOutput(snap),
+      }),
+      display: true,
+      details: { id: snap.id, title: snap.title, status: snap.status },
+    });
   };
 
   const onSettled = (snap: SubagentSnapshot, consumed: boolean) => {
     persistSnapshot(snap);
-    if (snap.meta.origin === "orchestration") {
-      resultDelivery.consume([snap.id]);
-      return;
-    }
+    if (snap.meta.origin === "orchestration") return;
     if (snap.meta.origin === "btw") {
-      resultDelivery.consume([snap.id]);
       pi.appendEntry<BtwEntryData>(BTW_ENTRY_TYPE, {
         id: snap.id,
         title: snap.title,
@@ -562,16 +549,10 @@ export default function (pi: ExtensionAPI) {
       });
       return;
     }
-    if (consumed) {
-      resultDelivery.consume([snap.id]);
-      return;
-    }
-    // Keep the result retractable while the parent is working. A later
-    // wait_agent can consume it before agent_settled flushes follow-ups.
-    // Defer a copy: the live snapshot keeps mutating if the subagent is
-    // restarted before the deferred result flushes.
-    resultDelivery.defer({ ...snap, meta: { ...snap.meta } });
-    if (sessionContext?.isIdle()) flushResults();
+    if (consumed) return;
+    // Hand the immutable settlement to Pi immediately. Pi queues it when the
+    // parent is active and starts a new parent turn when idle.
+    deliverResult({ ...snap, meta: { ...snap.meta } });
   };
 
   const coordinator: SubagentCoordinator = {
@@ -641,7 +622,6 @@ export default function (pi: ExtensionAPI) {
   );
 
   pi.on("session_start", (_event, ctx) => {
-    sessionContext = ctx;
     archived.clear();
     peerHistory.length = 0;
     for (const record of loadSubagentCatalog().values()) archived.set(record.id, record);
@@ -662,12 +642,8 @@ export default function (pi: ExtensionAPI) {
     if (ctx.hasUI) ui = ctx.ui;
   });
 
-  pi.on("agent_settled", flushResults);
-
   pi.on("session_shutdown", async () => {
-    sessionContext = undefined;
     unsubscribeCoordinator();
-    resultDelivery.clear();
     for (const pending of pendingQuestions.values()) {
       pending.reject(new Error("Parent Pi session shut down before replying."));
     }
@@ -692,7 +668,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; completion automatically starts the next parent turn.",
+      "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.",
     ],
     parameters: Type.Object({
       message: Type.String({
@@ -832,7 +808,6 @@ export default function (pi: ExtensionAPI) {
       const snapshots = ids.map((id) => manager.view.get(id)!);
       const settled = snapshots.filter((snap) => snap.status !== "running");
       const pending = snapshots.filter((snap) => snap.status === "running");
-      resultDelivery.consume(settled.map((snap) => snap.id));
 
       const sections: string[] = [];
       let remainingBytes = WAIT_OUTPUT_MAX_BYTES;
@@ -1121,7 +1096,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; completion automatically starts the next parent turn.",
+      "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.",
     ],
     parameters: Type.Object({
       tasks: Type.Array(

package/extensions/subagents/src/prompt.ts

@@ -19,6 +19,7 @@ export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
   "Use resume_from to continue a completed child's existing context instead of restating its original task.",
   "After spawn_agent or task starts background work, continue useful parent work; otherwise end the turn so Pi remains available to the user.",
   "Do not poll background agents. Completion notices arrive automatically and wake the parent; wait_agent only collects results already available and reports running agents without blocking.",
+  "When a completion notice invokes the parent, use its attached summary and continue the original task immediately; do not wait for another user message or call a status tool for the same result.",
 ];
 
 export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
@@ -51,7 +52,7 @@ export function buildSubagentSpawnResult(options: {
   ].filter(Boolean);
   return (
     `Started Pi subagent ${options.id} "${options.title}" (${attributes.join(", ")}).\n` +
-    "It will report and wake the parent when finished. Continue useful work or end the turn instead of polling."
+    "It will report and wake the parent when finished. Continue useful work or end the turn instead of polling; when invoked by the result, continue the original task immediately."
   );
 }
 

package/package.json

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

package/skills/background-terminals/SKILL.md

@@ -24,7 +24,9 @@ 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. Terminal settlement automatically sends a follow-up and starts the next parent turn with the final status and bounded output. 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 is handed to Pi immediately, queued as a follow-up if the parent is still active, and otherwise starts the next parent turn with the final status and bounded output. 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 attached 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.
 
 ## Inspect and interact only when necessary
 

package/skills/subagents/SKILL.md

@@ -24,14 +24,14 @@ 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 completion notice automatically starts the next main-agent turn. 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 is handed to Pi immediately, queued as a follow-up if the parent is still active, and otherwise starts the next main-agent turn. The parent does not need to remain active or check once before ending its turn.
 
 After dispatch:
 
 1. Continue only parent work that is independently useful to the requested result.
 2. If no such work remains, end the turn immediately. A short progress note is enough when the user needs one.
 3. Do not call `wait_agent`, `list_agents`, or `check_agent` in the same turn merely because the child was just launched. Ending the turn is the waiting mechanism.
-4. Resume when a child completion notice invokes the main agent. Collect the completed result, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications.
+4. When a child completion notice invokes the main agent, treat the attached summary as the child result and continue the original task immediately. Reconcile completed results, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications. Do not wait for the user to prompt you again or call a status tool to retrieve the same result.
 
 A progress check is reasonable when the user asks for status, a child has run materially longer than expected for its task and model, an interruption left its state unclear, or current status will change an immediate coordination decision. Prefer `check_agent` for one known child and `list_agents` for a batch overview. Use `wait_agent` to collect results already expected to be available, not as a running-status probe.
 

package/extensions/subagents/src/result-delivery.ts

@@ -1,20 +0,0 @@
-export function createDeferredResultDelivery<T extends { id: string }>() {
-  const pending = new Map<string, T>();
-
-  return {
-    defer(result: T) {
-      pending.set(result.id, result);
-    },
-    consume(ids: Iterable<string>) {
-      for (const id of ids) pending.delete(id);
-    },
-    drain() {
-      const results = [...pending.values()];
-      pending.clear();
-      return results;
-    },
-    clear() {
-      pending.clear();
-    },
-  };
-}