pi-subagents-lite 1.4.2 → 1.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",

package/src/agents/agent-discovery.ts

@@ -257,7 +257,6 @@ function compactDefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
  */
 export function parseAgentFile(
   content: string,
-  _filename: string,
   source: "user" | "project",
 ): AgentConfigFromMd {
   const { frontmatter, body } = parseFrontmatter(content);
@@ -310,7 +309,7 @@ export async function scanAgentFilesInDir(
     const filePath = path.join(dirPath, entry.name);
     try {
       const content = await fs.promises.readFile(filePath, "utf-8");
-      const info = parseAgentFile(content, entry.name, source);
+      const info = parseAgentFile(content, source);
       if (info.name) {
         agents.push(info);
       }

package/src/agents/agent-runner.ts

@@ -21,21 +21,14 @@ import {
 import { getAgentConfig, getConfig, getToolNamesForType, resolveVisibleTools } from "./agent-types.js";
 import { extractText } from "../prompt/context.js";
 import type { LifetimeUsage } from "./usage.js";
-import { findModelInRegistry } from "../utils.js";
+import { findModelInRegistry, GIT_EXEC_TIMEOUT_MS } from "../utils.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { buildAgentPrompt, type PromptExtras } from "../prompt/prompts.js";
 import { preloadSkills, loadSkillMeta, type SkillMeta } from "../prompt/skill-loader.js";
 import { type EnvInfo, type RunCallbacks, type RunTunables, SHORT_ID_LENGTH } from "../types.js";
 import type { SubagentType, SystemPromptMode } from "./types.js";
 import { getStore } from "../shell.js";
-import { DEFAULT_GRACE_TURNS } from "../config/config-io.js";
-
-/** Path to custom prompt file. Exported for use in menus.ts. */
-export const CUSTOM_PROMPT_PATH = path.join(process.env.HOME || "", ".pi", "agent", "subagents-lite-prompt.md");
-
-
-/** Timeout for quick git commands (branch detection, repo check). */
-const GIT_EXEC_TIMEOUT_MS = 5000;
+import { DEFAULT_GRACE_TURNS, CUSTOM_PROMPT_PATH } from "../config/config-io.js";
 
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 function normalizeMaxTurns(n: number | undefined): number | undefined {

package/src/agents/agent-types.ts

@@ -66,6 +66,15 @@ export function setAgentScanDirs(userDir: string, projectDir: string): void {
   projectAgentDir = projectDir;
 }
 
+/** Scan user and project agent directories, merge with defaults. Returns the merged Map. */
+async function scanAndMerge(options?: { disableDefaultAgents?: boolean }): Promise<Map<string, AgentConfig>> {
+  const [userAgents, projectAgents] = await Promise.all([
+    scanAgentFilesInDir(userAgentDir, "user"),
+    scanAgentFilesInDir(projectAgentDir, "project"),
+  ]);
+  const defaults = options?.disableDefaultAgents ? new Map<string, AgentConfig>() : DEFAULT_AGENTS;
+  return mergeAgents(defaults, userAgents, projectAgents);
+}
 /**
  * Scan the known agent directories and register any newly discovered agents
  * that aren't already in the registry. Returns the number of new agents added.
@@ -77,13 +86,7 @@ export function setAgentScanDirs(userDir: string, projectDir: string): void {
  * @param options - Optional settings. disableDefaultAgents skips DEFAULT_AGENTS in the merge.
  */
 export async function discoverNewAgents(worktreeDir?: string, options?: { disableDefaultAgents?: boolean }): Promise<number> {
-  const [userAgents, projectAgents] = await Promise.all([
-    scanAgentFilesInDir(userAgentDir, "user"),
-    scanAgentFilesInDir(projectAgentDir, "project"),
-  ]);
-
-  const defaults = options?.disableDefaultAgents ? new Map<string, AgentConfig>() : DEFAULT_AGENTS;
-  const merged = mergeAgents(defaults, userAgents, projectAgents);
+  const merged = await scanAndMerge(options);
 
   let count = 0;
   for (const [name, config] of merged) {
@@ -96,8 +99,6 @@ export async function discoverNewAgents(worktreeDir?: string, options?: { disabl
   // Scan worktree-local agents (only when worktreeDir is provided)
   if (worktreeDir) {
     const worktreeAgents = await scanAgentFilesInDir(worktreeDir, "project");
-    // Use mergeAgents to convert AgentConfigFromMd to AgentConfig (applies fromMd
-    // and BASE_DEFAULTS), then add only names not already in the registry.
     const wtMerged = mergeAgents(new Map(), [], worktreeAgents);
     for (const [name, config] of wtMerged) {
       if (!agents.has(name)) {
@@ -302,22 +303,23 @@ function applyGlobalDefaults(
   };
 }
 
+/** Find the first non-hidden config: resolved type, then general-purpose, then undefined. */
+function findActiveConfig(type: string): AgentConfig | undefined {
+  const key = resolveType(type);
+  const config = key ? agents.get(key) : undefined;
+  if (config?.hidden !== true) return config;
+  return agents.get("general-purpose");
+}
+
 /** Get config for a type (case-insensitive). Falls back to general-purpose. */
 export function getConfig(
   type: string,
   loadSkillsImplicitly: boolean = true,
   loadExtensionsImplicitly: boolean = true,
 ): ResolvedAgentConfig {
-  const resolvedKey = resolveType(type);
-  const config = resolvedKey ? agents.get(resolvedKey) : undefined;
-
-  // If config exists and is not hidden, use it; otherwise fall back to general-purpose
-  const activeConfig = config?.hidden !== true
-    ? config
-    : agents.get("general-purpose");
-
-  if (activeConfig && activeConfig.hidden !== true) {
-    const { skills, extensions, ...rest } = activeConfig;
+  const config = findActiveConfig(type);
+  if (config) {
+    const { skills, extensions, ...rest } = config;
     const defaults = applyGlobalDefaults(skills, extensions, loadSkillsImplicitly, loadExtensionsImplicitly);
     return {
       displayName: rest.displayName ?? rest.name,
@@ -328,7 +330,7 @@ export function getConfig(
     };
   }
 
-  // Absolute fallback — general-purpose was hidden or missing
+  // Absolute fallback — no config found at all
   const defaults = applyGlobalDefaults(undefined, undefined, loadSkillsImplicitly, loadExtensionsImplicitly);
   return {
     displayName: "Agent",

package/src/agents/output-file.ts

@@ -25,6 +25,13 @@ function findLastSentenceBoundary(text: string): number {
   }
   return -1;
 }
+
+/** Format the [DONE] summary line with final stats. */
+function formatDoneLine(stats: { turnCount: number; toolUseCount: number; totalTokens: number; cost: number }): string {
+  const tokensStr = `${formatTokens(stats.totalTokens)} tokens`;
+  const costStr = `$${stats.cost.toFixed(3)}`;
+  return `${timestamp()} [DONE] ${stats.turnCount} turns, ${stats.toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`;
+}
 /** Max content length for full tool result display — longer results get a summary line. */
 const MAX_TOOL_RESULT_DISPLAY_LENGTH = 500;
 
@@ -176,7 +183,7 @@ export function streamToOutputFile(
 
   const flushThinkingBuffer = () => {
     if (thinkingBuffer.length > 0) {
-      safeAppend(path, splitAndPrefix(thinkingBuffer, "THINKING"));
+      safeAppend(path, `${timestamp()} [THINKING] ${thinkingBuffer}\n`);
       streamedThinkingChars += thinkingBuffer.length;
       thinkingBuffer = "";
     }
@@ -225,21 +232,16 @@ export function streamToOutputFile(
         thinkingBlockInProgress = true;
       } else if (assistantEvent.type === "thinking_delta") {
         thinkingBuffer += assistantEvent.delta;
-        if (thinkingBuffer.length >= bufferSize || thinkingBuffer.includes("\n")) {
+        if (thinkingBuffer.length >= bufferSize) {
           // Round down to nearest sentence boundary when possible
-          if (thinkingBuffer.length >= bufferSize) {
-            const boundary = findLastSentenceBoundary(thinkingBuffer);
-            if (boundary >= 0) {
-              const flushText = thinkingBuffer.slice(0, boundary + 1);
-              thinkingBuffer = thinkingBuffer.slice(boundary + 1);
-              safeAppend(path, splitAndPrefix(flushText, "THINKING"));
-              streamedThinkingChars += flushText.length;
-            } else {
-              // No sentence boundary found, flush at buffer limit
-              flushThinkingBuffer();
-            }
+          const boundary = findLastSentenceBoundary(thinkingBuffer);
+          if (boundary >= 0) {
+            const flushText = thinkingBuffer.slice(0, boundary + 1);
+            thinkingBuffer = thinkingBuffer.slice(boundary + 1);
+            safeAppend(path, `${timestamp()} [THINKING] ${flushText}\n`);
+            streamedThinkingChars += flushText.length;
           } else {
-            // Newline found before buffer limit
+            // No sentence boundary found, flush at buffer limit
             flushThinkingBuffer();
           }
         }
@@ -249,7 +251,7 @@ export function streamToOutputFile(
         flushThinkingBuffer();
         if (assistantEvent.content && assistantEvent.content.length > streamedThinkingChars) {
           const remaining = assistantEvent.content.slice(streamedThinkingChars);
-          safeAppend(path, splitAndPrefix(remaining, "THINKING"));
+          safeAppend(path, `${timestamp()} [THINKING] ${remaining}\n`);
           streamedThinkingChars = assistantEvent.content.length;
         }
         streamedThinkingBlocks++;
@@ -264,10 +266,8 @@ export function streamToOutputFile(
     flush();
 
     // Write DONE line
-    const { turnCount = 0, toolUseCount = 0, totalTokens = 0, cost = 0 } = stats ?? {};
-    const tokensStr = `${formatTokens(totalTokens)} tokens`;
-    const costStr = `$${cost.toFixed(3)}`;
-    safeAppend(path, `${timestamp()} [DONE] ${turnCount} turns, ${toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`);
+    const doneStats = stats ?? { turnCount: 0, toolUseCount: 0, totalTokens: 0, cost: 0 };
+    safeAppend(path, formatDoneLine(doneStats));
 
     // Unsubscribe from session events
     unsubscribe();
@@ -336,9 +336,7 @@ export class AgentOutputLog {
       this.statsRef = undefined;
     } else {
       // No attach was called — write DONE directly
-      const tokensStr = `${formatTokens(stats.totalTokens)} tokens`;
-      const costStr = `$${stats.cost.toFixed(3)}`;
-      safeAppend(this.path, `${timestamp()} [DONE] ${stats.turnCount} turns, ${stats.toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`);
+      safeAppend(this.path, formatDoneLine(stats));
     }
   }
 }

package/src/agents/tool-execution.ts

@@ -52,16 +52,9 @@ function errorResult(text: string, details?: Record<string, unknown>) {
  * Consolidates the identical field-selection logic previously duplicated
  * across emitIndividualNudge, executeSpawnForeground, and executeSpawnBackground.
  */
-interface AgentDetailsOptions {
-  /** Include full stats (turns, tokens, context%, compactions, cost). Default: false. */
-  includeStats?: boolean;
-  /** Include status and outputFile. Default: false. */
-  includeStatus?: boolean;
-}
-
 export function buildAgentDetails(
   record: AgentRecord,
-  options?: AgentDetailsOptions,
+  opts?: { includeStats?: boolean; includeStatus?: boolean },
 ): Record<string, unknown> {
   const details: Record<string, unknown> = {
     type: record.display.type,
@@ -72,12 +65,12 @@ export function buildAgentDetails(
     details.worktreePath = record.display.worktreePath;
   }
 
-  if (options?.includeStatus) {
+  if (opts?.includeStatus) {
     details.status = record.lifecycle.status;
     details.outputFile = record.display.outputFile;
   }
 
-  if (options?.includeStats) {
+  if (opts?.includeStats) {
     const elapsedMs = record.lifecycle.completedAt ? record.lifecycle.completedAt - record.lifecycle.startedAt : 0;
 
     details.turnCount = record.stats.turnCount;

package/src/agents/usage.ts

@@ -29,17 +29,10 @@ type SessionStatsLike = {
 };
 export type SessionLike = { getSessionStats(): SessionStatsLike };
 
-/** Format a token count compactly: "12.3k", "1.2M", or raw number. */
-export function formatTokens(count: number): string {
+/** Format a token count compactly: "12.3k", "1.2M", or raw number. When compact is true, thousands round to whole numbers. */
+export function formatTokens(count: number, compact = false): string {
   if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
-  return `${count}`;
-}
-
-/** Format token count for widget display: rounded to whole number for k. */
-export function formatTokensCompact(count: number): string {
-  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-  if (count >= 1_000) return `${Math.round(count / 1_000)}k`;
+  if (count >= 1_000) return compact ? `${Math.round(count / 1_000)}k` : `${(count / 1_000).toFixed(1)}k`;
   return `${count}`;
 }
 

package/src/config/config-io.ts

@@ -11,46 +11,57 @@ import type { SubagentsConfig } from "../models/model-precedence.js";
 
 const CONFIG_DIR = path.join(process.env.HOME || "", ".pi", "agent");
 const CONFIG_PATH = path.join(CONFIG_DIR, "subagents-lite.json");
-
+/** Path to custom prompt file for subagent system prompts. */
+export const CUSTOM_PROMPT_PATH = path.join(CONFIG_DIR, "subagents-lite-prompt.md");
 /** Default number of grace turns before an agent is force-stopped. */
 export const DEFAULT_GRACE_TURNS = 6;
 
-/** Default configuration — used when config file doesn't exist or is invalid. */
-export const DEFAULT_CONFIG: SubagentsConfig = {
-  agent: {
-    default: null,
-    forceBackground: false,
-    graceTurns: DEFAULT_GRACE_TURNS,
-    widgetMaxLines: 12,
-    // widgetMaxLinesCompact intentionally omitted — derives from widgetMaxLines
-    widgetDescLengthFull: 50,
-    widgetDescLengthCompact: 30,
-    widgetCompact: false,
-    widgetShortcut: false,
-    systemPromptMode: "replace",
-    includeContextFiles: true,
-    disableDefaultAgents: false,
-    showTools: true,
-    showTurns: true,
-    showInput: true,
-    showOutput: true,
-    showContext: true,
-    showCost: false,
-    showTime: true,
-  },
-  concurrency: { default: 4 },
+/** Valid system prompt modes. */
+export const VALID_SYSTEM_PROMPT_MODES = new Set<string>(["replace", "inherit", "custom"]);
+
+/** Default concurrency config — used for resets. */
+export const DEFAULT_CONCURRENCY: SubagentsConfig["concurrency"] = { default: 4 };
+
+/** Default agent settings — merged into loaded config so callers get a complete shape. */
+const DEFAULT_AGENT: SubagentsConfig["agent"] = {
+  default: null,
+  forceBackground: false,
+  graceTurns: DEFAULT_GRACE_TURNS,
+  widgetMaxLines: 12,
+  widgetDescLengthFull: 50,
+  widgetDescLengthCompact: 30,
+  widgetCompact: false,
+  widgetShortcut: false,
+  systemPromptMode: "replace",
+  includeContextFiles: true,
+  disableDefaultAgents: false,
+  showTools: true,
+  showTurns: true,
+  showInput: true,
+  showOutput: true,
+  showContext: true,
+  showCost: false,
+  showTime: true,
 };
 
 /**
- * Read config from disk. Returns defaults if file doesn't exist or is invalid.
+ * Read config from disk. Merges loaded values over defaults so the result
+ * is always a complete SubagentsConfig — no partial shapes for callers to handle.
  */
 export function loadConfig(): SubagentsConfig {
+  let raw: SubagentsConfig;
   try {
-    const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
-    return JSON.parse(raw) as SubagentsConfig;
+    raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8")) as SubagentsConfig;
   } catch {
-    return { ...DEFAULT_CONFIG, agent: { ...DEFAULT_CONFIG.agent }, concurrency: { ...DEFAULT_CONFIG.concurrency } };
+    raw = {} as SubagentsConfig;
   }
+
+  // @ts-expect-error TS2783: spread may override 'default', which is intentional (loaded value wins)
+  const concurrency = { default: 4, ...(raw.concurrency ?? {}) } as SubagentsConfig["concurrency"];
+  return {
+    agent: { ...DEFAULT_AGENT, ...raw.agent },
+    concurrency,
+  };
 }
 
 /** Write config to disk with atomic rename. */

package/src/config/config-store.ts

@@ -20,10 +20,8 @@ import type { AgentManager } from "../agents/agent-manager.js";
 import { CONFIG_AGENT_NON_MODEL_KEYS } from "./types.js";
 import type { SystemPromptMode } from "../agents/types.js";
 import type { ThinkingLevel } from "../types.js";
-import { DEFAULT_CONFIG, loadConfig, saveConfigAtomic } from "./config-io.js";
+import { VALID_SYSTEM_PROMPT_MODES, DEFAULT_CONCURRENCY, loadConfig, saveConfigAtomic } from "./config-io.js";
 
-/** Valid values for systemPromptMode — checked once at module load. */
-const VALID_SYSTEM_PROMPT_MODES = new Set<string>(["replace", "inherit", "custom"]);
 
 /** Injected persistence adapter. Swap for an in-memory adapter in tests. */
 export interface ConfigIO {
@@ -108,29 +106,22 @@ export class ConfigStore {
 
   get agent(): ResolvedAgentSettings {
     const a = this.config.agent;
-    const widgetMaxLines = a.widgetMaxLines ?? DEFAULT_CONFIG.agent.widgetMaxLines ?? 12;
+    const widgetMaxLines = a.widgetMaxLines!; // guaranteed by loadConfig default merge
     const widgetMaxLinesCompact = a.widgetMaxLinesCompact ?? Math.floor(widgetMaxLines / 2);
-    const widgetCompact = a.widgetCompact === true;
-    const widgetShortcut = a.widgetShortcut === true;
-    const widgetDescLengthFull = a.widgetDescLengthFull ?? DEFAULT_CONFIG.agent.widgetDescLengthFull ?? 50;
-    const widgetDescLengthCompact = a.widgetDescLengthCompact ?? DEFAULT_CONFIG.agent.widgetDescLengthCompact ?? 30;
-    const rawMode = a.systemPromptMode;
-    const systemPromptMode = VALID_SYSTEM_PROMPT_MODES.has(rawMode as string) ? rawMode as SystemPromptMode : "replace";
-    const includeContextFiles = a.includeContextFiles ?? DEFAULT_CONFIG.agent.includeContextFiles ?? true;
 
     return {
       defaultModel: a.default ?? null,
       forceBackground: a.forceBackground === true,
       showCost: this.sessionShowCost ?? (a.showCost === true),
-      graceTurns: a.graceTurns ?? DEFAULT_CONFIG.agent.graceTurns ?? 6,
+      graceTurns: a.graceTurns ?? 6,
       widgetMaxLines,
       widgetMaxLinesCompact,
-      widgetCompact,
-      widgetShortcut,
-      widgetDescLengthFull,
-      widgetDescLengthCompact,
-      systemPromptMode,
-      includeContextFiles,
+      widgetCompact: a.widgetCompact === true,
+      widgetShortcut: a.widgetShortcut === true,
+      widgetDescLengthFull: a.widgetDescLengthFull ?? 50,
+      widgetDescLengthCompact: a.widgetDescLengthCompact ?? 30,
+      systemPromptMode: VALID_SYSTEM_PROMPT_MODES.has(a.systemPromptMode as string) ? (a.systemPromptMode as SystemPromptMode) : "replace",
+      includeContextFiles: a.includeContextFiles ?? true,
       defaultThinking: a.defaultThinking as ThinkingLevel | undefined,
       defaultMaxTurns: a.defaultMaxTurns,
       loadSkillsImplicitly: a.loadSkillsImplicitly !== false,
@@ -344,7 +335,7 @@ export class ConfigStore {
         this.applyConcurrency();
       },
       reset: (): void => {
-        this.config.concurrency = { ...DEFAULT_CONFIG.concurrency };
+        this.config.concurrency = { ...DEFAULT_CONCURRENCY };
         this.persist();
         this.applyConcurrency();
       },

package/src/spawn/spawn-coordinator.ts

@@ -1,5 +1,5 @@
 import { getStatusNote } from "../status-note.js";
-import { getWidget } from "../shell.js";
+import { getPiInstance, getSessionCtx, getWidget } from "../shell.js";
 /**
  * spawn-coordinator.ts — Spawn-and-track coordination for subagents.
  *
@@ -58,15 +58,15 @@ export class SpawnCoordinator {
   /** Agent IDs spawned as background — only these trigger a nudge on completion. */
   private backgroundAgentIds = new Set<string>();
 
+  /** Captured ExtensionContext per background agent, bound to the spawning session. */
+  private backgroundContexts = new Map<string, ExtensionContext>();
+
   /** Pending nudge agent IDs, batched within the delay window. */
   private pendingNudges = new Set<string>();
 
   /** Active nudge timer. */
   private nudgeTimer: ReturnType<typeof setTimeout> | null = null;
 
-  /** Latest ExtensionAPI reference, refreshed on each spawn() call. */
-  private pi: ExtensionAPI | null = null;
-
   /** Set during dispose to prevent nudge emission after session replacement. */
   private disposed = false;
 
@@ -109,14 +109,12 @@ export class SpawnCoordinator {
       widget.ensureTimer();
     }
 
-    // Track background agents
+    // Track background agents + capture ctx for fallback notification
     if (intent.runInBackground) {
       this.backgroundAgentIds.add(agentId);
+      this.backgroundContexts.set(agentId, ctx);
     }
 
-    // Store latest pi reference for nudge delivery
-    this.pi = pi;
-
     const record = this.manager.getRecord(agentId)!;
 
     if (!intent.runInBackground) {
@@ -184,6 +182,7 @@ export class SpawnCoordinator {
     this.pendingNudges.clear();
     this.liveViews.clear();
     this.backgroundAgentIds.clear();
+    this.backgroundContexts.clear();
     this.disposed = true;
   }
 
@@ -212,11 +211,9 @@ export class SpawnCoordinator {
     // Skip if disposed — prevents stale pi usage after session replacement
     if (this.disposed) return;
 
-    // Skip if no pi instance yet (no spawn has occurred)
-    if (!this.pi) {
-      console.warn(`subagent nudge skipped for ${agentId}: no pi instance available (no spawn has occurred yet)`);
-      return;
-    }
+    // Read pi from shell at call time so we get a fresh reference after reload.
+    const pi = getPiInstance();
+    if (!pi) return;
 
     const record = this.manager.getRecord(agentId);
     if (!record) return;
@@ -227,7 +224,14 @@ export class SpawnCoordinator {
     });
 
     try {
-      this.pi.sendMessage(
+      // Pick delivery mode based on parent session state:
+      // - steer: queues while running, delivers before next LLM call
+      // - followUp: waits for agent to finish, then delivers
+      const ctx = getSessionCtx();
+      const parentIdle = ctx?.isIdle?.() ?? true;
+      const deliverAs = parentIdle ? "followUp" : "steer";
+
+      pi.sendMessage(
         {
           customType: "subagent-result",
           content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""} ${getStatusNote(record.lifecycle.status)}`,
@@ -235,13 +239,26 @@ export class SpawnCoordinator {
           display: true,
         },
         {
-          deliverAs: "steer",
+          deliverAs,
           triggerTurn: true,
         },
       );
     } catch (error) {
-      // Defense-in-depth: pi may be stale after session replacement/reload.
-      console.warn(`subagent nudge failed for ${agentId}:`, error);
+      // sendMessage failed (shared runtime overwritten by subagent bindCore).
+      // Fall back to UI notification using the captured spawning-session context.
+      const spawnCtx = this.backgroundContexts.get(agentId);
+      if (spawnCtx?.ui?.notify) {
+        try {
+          spawnCtx.ui.notify(
+            `[Subagent "${record.display.type}" ${record.lifecycle.status}] Result available`,
+            "info",
+          );
+        } catch {
+          // ctx may also be stale if session was replaced
+        }
+      }
+    } finally {
+      this.backgroundContexts.delete(agentId);
     }
   }
 }

package/src/spawn/worktree-validator.ts

@@ -10,10 +10,7 @@
 
 import * as path from "node:path";
 import { existsSync, statSync, realpathSync } from "node:fs";
-
-/** Timeout for git commands (ms). */
-const GIT_EXEC_TIMEOUT_MS = 5000;
-
+import { GIT_EXEC_TIMEOUT_MS } from "../utils.js";
 /** Specific error messages returned to the LLM for self-correction. */
 export const WORKTREE_VALIDATION_ERRORS = {
   PATH_DOES_NOT_EXIST: "worktree_path does not exist: the specified path was not found on disk",

package/src/ui/agent-widget.ts

@@ -56,7 +56,6 @@ const TOOL_DISPLAY: Record<string, string> = {
   write: "writing",
   grep: "searching",
   find: "finding files",
-  ls: "listing",
 };
 
 // ---- Types ----
@@ -136,6 +135,14 @@ function describeActivity(activeTools: Map<string, string>, responseText?: strin
   return THINKING_TEXT;
 }
 
+/** Build the worktree/output continuation line parts for an agent record. */
+function buildWorktreeOutputParts(a: AgentRecord): string[] {
+  const parts: string[] = [];
+  if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
+  if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+  return parts;
+}
+
 // ---- Widget manager ----
 
 export class AgentWidget {
@@ -375,10 +382,8 @@ export class AgentWidget {
     for (const a of finished) {
       const continuations: string[] = [];
       if (!this.isCompact()) {
-        if (a.display.outputFile || a.display.worktreeLabel) {
-          const parts: string[] = [];
-          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
-          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+        const parts = buildWorktreeOutputParts(a);
+        if (parts.length > 0) {
           continuations.push(truncate(theme.fg("dim", `${VLINE}    ${parts.join("  ")}`)));
         }
       }
@@ -418,10 +423,8 @@ export class AgentWidget {
         const fullDesc = truncateDesc(a.display.description, this.descLengthFull);
         const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${fullDesc}  ${statsLine}`;
         const continuations: string[] = [];
-        if (a.display.outputFile || a.display.worktreeLabel) {
-          const parts: string[] = [];
-          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
-          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+        const parts = buildWorktreeOutputParts(a);
+        if (parts.length > 0) {
           continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `${VLINE} ${parts.join("  ")}`)));
         }
         continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `└ ${activity}`)));
@@ -571,15 +574,14 @@ export class AgentWidget {
     }
 
     // Overflow summary line
-    const overflowLine = hiddenRunning + hiddenFinished > 0
-      ? (() => {
-          const parts: string[] = [];
-          if (hiddenRunning > 0) parts.push(`${hiddenRunning} running`);
-          if (hiddenFinished > 0) parts.push(`${hiddenFinished} finished`);
-          const summary = `+${hiddenRunning + hiddenFinished} more (${parts.join(", ")})`;
-          return `${theme.fg("dim", CORNER)} ${theme.fg("dim", summary)}`;
-        })()
-      : undefined;
+    let overflowLine: string | undefined;
+    if (hiddenRunning + hiddenFinished > 0) {
+      const parts: string[] = [];
+      if (hiddenRunning > 0) parts.push(`${hiddenRunning} running`);
+      if (hiddenFinished > 0) parts.push(`${hiddenFinished} finished`);
+      const summary = `+${hiddenRunning + hiddenFinished} more (${parts.join(", ")})`;
+      overflowLine = `${theme.fg("dim", CORNER)} ${theme.fg("dim", summary)}`;
+    }
 
     return { visible, overflowLine };
   }

package/src/ui/format.ts

@@ -11,7 +11,7 @@
 import { getConfig } from "../agents/agent-types.js";
 import type { SubagentType } from "../agents/types.js";
 import type { Theme } from "./types.js";
-import { formatTokens, formatTokensCompact, formatCost } from "../agents/usage.js";
+import { formatTokens, formatCost } from "../agents/usage.js";
 
 /** Truncate a description string to `maxLen` characters, appending "..." if truncated. */
 export function truncateDesc(text: string, maxLen: number): string {
@@ -44,8 +44,8 @@ function formatSessionTokens(
   compactions = 0,
 ): string {
   const tokenParts: string[] = [];
-  if (inputTokens > 0) tokenParts.push(`↑${formatTokensCompact(inputTokens)}`);
-  if (outputTokens > 0) tokenParts.push(`↓${formatTokensCompact(outputTokens)}`);
+  if (inputTokens > 0) tokenParts.push(`↑${formatTokens(inputTokens, true)}`);
+  if (outputTokens > 0) tokenParts.push(`↓${formatTokens(outputTokens, true)}`);
   const tokenStr = tokenParts.join("");
   const annot: string[] = [];
   if (percent !== null) {

package/src/ui/menu/helpers.ts

@@ -5,9 +5,9 @@
  * searchable pick-list submenu factory.
  */
 import type { Component, SettingsListTheme } from "@earendil-works/pi-tui";
+import type { Theme } from "../types.js";
 import { SearchableSelectDialog, type SelectOption } from "../searchable-select.js";
 import { parseModelKey } from "../../utils.js";
-
 /**
  * Build SelectOption[] from raw "provider/model-id" strings.
  * Includes "(inherits parent)" as the first option.
@@ -103,7 +103,7 @@ export function buildSelectListTheme(theme: { fg(color: string, text: string): s
 export function createSearchableSelect(
   items: SelectOption[],
   callbacks: { onSelect: (value: string) => Component | void; onCancel: () => void },
-  theme: any,
+  theme: Theme,
 ): Component {
   let delegator: ReturnType<typeof createDelegatingComponent>;
   const selector = new SearchableSelectDialog(

package/src/ui/menu/menu-concurrency.ts

@@ -23,13 +23,14 @@ import { createConfirmSubmenu } from "./submenus/confirm.js";
 import { SettingsListWrapper } from "./wrappers/settings-list.js";
 import { getStore } from "../../shell.js";
 import type { SelectOption } from "../searchable-select.js";
+import type { Theme } from "../types.js";
 
 export async function showConcurrencySettingsMenu(
   ctx: ExtensionCommandContext,
   modelOptions: string[],
 ): Promise<void> {
   // Build menu items from current store state.
-  const buildItems = (store: ReturnType<typeof getStore>, theme: any, modelOptions: string[], onRebuild?: () => void): SettingItem[] => {
+  const buildItems = (store: ReturnType<typeof getStore>, theme: Theme, modelOptions: string[], onRebuild?: () => void): SettingItem[] => {
     const providers = [...new Set(modelOptions.map((m) => m.split("/")[0]))].sort();
     const items: SettingItem[] = [];
 

package/src/ui/menu/menu-model-settings.ts

@@ -12,6 +12,7 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { SettingsList, type SettingItem } from "@earendil-works/pi-tui";
 import { getAgentConfig, getAllTypes } from "../../agents/agent-types.js";
+import type { Theme } from "../types.js";
 import { CONFIG_AGENT_NON_MODEL_KEYS } from "../../config/types.js";
 import { buildSettingsListTheme, createSearchableSelect } from "./helpers.js";
 import { createModelSelectSubmenu } from "./submenus/model-select.js";
@@ -24,7 +25,7 @@ export async function showModelSettingsMenu(
   modelOptions: string[],
 ): Promise<void> {
   // Build menu items from current store state.
-  const buildItems = (store: ReturnType<typeof getStore>, theme: any): SettingItem[] => {
+  const buildItems = (store: ReturnType<typeof getStore>, theme: Theme): SettingItem[] => {
     const items: SettingItem[] = [];
     
     // Shared onSelect for model override submenus: applies session/permanent/clear

package/src/ui/menu/menu-running-agents.ts

@@ -22,6 +22,7 @@ import { getDisplayName, truncateDesc } from "../format.js";
 import { buildSnapshotMarkdown } from "../../prompt/context.js";
 import { buildSelectListTheme, createDelegatingComponent } from "./helpers.js";
 import { getManager, getStore } from "../../shell.js";
+import type { Theme } from "../types.js";
 
 /**
  * Show a ResultViewer for an agent's result, error, or snapshot.
@@ -73,7 +74,7 @@ async function showResultViewer(
 export function buildAgentActionsList(
   ctx: ExtensionCommandContext,
   record: AgentRecord,
-  theme: any,
+  theme: Theme,
   done: () => void,
   setActive: (c: import("@earendil-works/pi-tui").Component) => void,
   onClose: () => void,

package/src/ui/menu/menu-spawn-wizard.ts

@@ -11,8 +11,9 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { SettingsList, SelectList, type SettingItem } from "@earendil-works/pi-tui";
 import type { ThinkingLevel } from "../../types.js";
+import type { Theme } from "../types.js";
 import { getAgentConfig, getAvailableTypes, resolveType, discoverNewAgents } from "../../agents/agent-types.js";
-import { findModelInRegistry } from "../../utils.js";
+import { findModelInRegistry, VALID_THINKING_LEVELS } from "../../utils.js";
 import { buildSettingsListTheme, buildSelectListTheme, createSearchableSelect } from "./helpers.js";
 import { DEFAULT_GRACE_TURNS } from "../../config/config-io.js";
 import { createModelSelectSubmenu } from "./submenus/model-select.js";
@@ -120,7 +121,6 @@ async function isInGitRepo(cwd: string): Promise<boolean> {
 // Spawn agent wizard
 // ============================================================================
 
-const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
 
 /**
  * Show the spawn agent flow as a multi-step wizard:
@@ -363,7 +363,7 @@ export async function showSpawnAgentMenu(
         label: "Thinking level",
         currentValue: currentThinking ?? "inherit",
         description: "Set the reasoning effort level",
-        values: [...THINKING_LEVELS, "inherit"],
+        values: [...VALID_THINKING_LEVELS, "inherit"],
       },
       {
         id: "maxTokens",
@@ -406,7 +406,7 @@ export async function showSpawnAgentMenu(
     return items;
   };
 
-  let theme: any;
+  let theme: Theme;
   let doneRef: () => void;
 
   await ctx.ui.custom((_tui, t, _kb, done) => {

package/src/ui/menu/menu-system-prompt.ts

@@ -17,7 +17,7 @@ import { buildSettingsListTheme } from "./helpers.js";
 import { SettingsListWrapper } from "./wrappers/settings-list.js";
 import type { SystemPromptMode } from "../../agents/types.js";
 import { getStore } from "../../shell.js";
-import { CUSTOM_PROMPT_PATH } from "../../agents/agent-runner.js";
+import { CUSTOM_PROMPT_PATH } from "../../config/config-io.js";
 
 export async function showSystemPromptMenu(ctx: ExtensionCommandContext): Promise<void> {
   const store = getStore();

package/src/ui/menu/submenus/confirm.ts

@@ -6,13 +6,14 @@
  */
 
 import { SelectList, type Component } from "@earendil-works/pi-tui";
+import type { Theme } from "../../types.js";
 import { buildSelectListTheme } from "../helpers.js";
 
 export interface ConfirmSubmenuOptions {
   /** Message shown to the user */
   message: string;
   /** Theme from pi-coding-agent (fg, bold, italic) */
-  theme: any;
+  theme: Theme;
   /** Called when user confirms (selects Yes) */
   onConfirm: () => void;
 }

package/src/ui/menu/submenus/model-select.ts

@@ -8,13 +8,14 @@
  */
 
 import { SelectList, type Component } from "@earendil-works/pi-tui";
+import type { Theme } from "../../types.js";
 import { SearchableSelectDialog, type SelectOption } from "../../../ui/searchable-select.js";
 import { buildModelOptions, buildSelectListTheme, createDelegatingComponent } from "../helpers.js";
 
 export interface ModelSelectSubmenuOptions {
   modelOptions: string[];
   showClear: boolean;
-  theme: any; // Theme from pi-coding-agent (fg, bold, italic)
+  theme: Theme;
   onSelect: (mode: "session" | "permanent" | "clear", model: string | null) => void;
 }
 

package/src/ui/result-viewer.ts

@@ -17,7 +17,7 @@ import {
   visibleWidth,
 } from "@earendil-works/pi-tui";
 import { type LifetimeUsage, formatTokens } from "../agents/usage.js";
-import type { Theme } from "./agent-widget.js";
+import type { Theme } from "./types.js";
 import { formatMs } from "./format.js";
 
 /* ------------------------------------------------------------------ */

package/src/ui/searchable-select.ts

@@ -15,7 +15,7 @@ import {
   Text,
 } from "@earendil-works/pi-tui";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
-import type { Theme } from "./agent-widget.js";
+import type { Theme } from "./types.js";
 
 /* ------------------------------------------------------------------ */
 /*  Types                                                              */

package/src/utils.ts

@@ -86,3 +86,5 @@ export function findModelInRegistry(
   if (!parsed) return fallback;
   return registry.find(parsed.provider, parsed.modelId) ?? fallback;
 }
+/** Timeout for git commands (ms). Shared by agent-runner and worktree-validator. */
+export const GIT_EXEC_TIMEOUT_MS = 5000;