pi-subagents-lite 0.2.0 → 0.3.1

package/src/agent-manager.ts

@@ -17,13 +17,27 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
-import type { AgentInvocation, AgentRecord, SubagentType, ThinkingLevel } from "./types.js";
-import { addUsage, getLifetimeTotal } from "./usage.js";
+import type {
+  AgentInvocation,
+  AgentRecord,
+  CompactionInfo,
+  SubagentType,
+  ThinkingLevel,
+} from "./types.js";
+import { addUsage, getLifetimeTotal, type LifetimeUsage } from "./usage.js";
+import { errorMessage } from "./utils.js";
 
-/** Safely extract a human-readable error message from an unknown exception. */
-function errorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
+/** How often to check for expired agent records (milliseconds). */
+const CLEANUP_INTERVAL_MS = 60_000;
+
+/** Age after which a completed agent record is evicted (milliseconds). */
+const CLEANUP_AGE_CUTOFF_MS = 10 * 60_000;
+
+/** Length of short agent ID (UUID prefix). */
+const AGENT_ID_LENGTH = 17;
+
+/** Default per-model concurrency limit when not specified in config. */
+const DEFAULT_CONCURRENCY_LIMIT = 4;
 
 /**
  * Create a cleanup function for the output file stream.
@@ -35,12 +49,13 @@ function createOutputCleanup(
   path: string,
   record: AgentRecord,
 ): () => void {
-  const outputStats = { turnCount: 0, toolUseCount: 0, totalTokens: 0 };
+  const outputStats = { turnCount: 0, toolUseCount: 0, totalTokens: 0, cost: 0 };
   const cleanup = streamToOutputFile(session, path, outputStats);
   return () => {
     outputStats.turnCount = record.turnCount ?? 0;
     outputStats.toolUseCount = record.toolUses;
     outputStats.totalTokens = getLifetimeTotal(record.lifetimeUsage);
+    outputStats.cost = record.lifetimeUsage.cost;
     cleanup();
   };
 }
@@ -57,7 +72,7 @@ export interface ConcurrencyConfig {
   /** Per-provider concurrency limits keyed by provider name (e.g. "llamacpp"). */
   providers?: Record<string, number>;
   /** Per-model concurrency limits keyed by "provider/modelId". */
-  models: Record<string, number>;
+  models?: Record<string, number>;
 }
 
 type OnAgentComplete = (record: AgentRecord) => void;
@@ -103,9 +118,9 @@ export interface SpawnOptions {
   /** Called at the end of each agentic turn with the cumulative count. */
   onTurnEnd?: (turnCount: number) => void;
   /** Called once per assistant message_end with that message's usage delta. */
-  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  onAssistantUsage?: (usage: LifetimeUsage) => void;
   /** Called when the session successfully compacts. */
-  onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
+  onCompaction?: (info: CompactionInfo) => void;
 }
 
 export class AgentManager {
@@ -133,24 +148,19 @@ export class AgentManager {
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
-    this.defaultConcurrency = concurrency?.default ?? 4;
+    this.defaultConcurrency = concurrency?.default ?? DEFAULT_CONCURRENCY_LIMIT;
 
     // Initialize per-provider slots from config (shared pool)
-    if (concurrency?.providers) {
-      for (const [provider, limit] of Object.entries(concurrency.providers)) {
-        this.providerSlots.set(provider, { limit: Math.max(1, limit), running: 0 });
-      }
+    for (const [provider, limit] of Object.entries(concurrency?.providers ?? {})) {
+      this.applyConcurrencyEntry(this.providerSlots, provider, limit);
     }
 
     // Initialize per-model slots from config
-    if (concurrency?.models) {
-      for (const [modelKey, limit] of Object.entries(concurrency.models)) {
-        this.concurrencySlots.set(modelKey, { limit: Math.max(1, limit), running: 0 });
-      }
+    for (const [modelKey, limit] of Object.entries(concurrency?.models ?? {})) {
+      this.applyConcurrencyEntry(this.concurrencySlots, modelKey, limit);
     }
 
-    // Cleanup completed agents after 10 minutes (but keep sessions for resume)
-    this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    this.cleanupInterval = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
     this.cleanupInterval.unref();
   }
 
@@ -164,50 +174,52 @@ export class AgentManager {
     this.defaultConcurrency = config.default;
 
     // Update per-provider slots (shared pool)
-    if (config.providers) {
-      for (const [provider, limit] of Object.entries(config.providers)) {
-        const existing = this.providerSlots.get(provider);
-        if (existing) {
-          existing.limit = Math.max(1, limit);
-        } else {
-          this.providerSlots.set(provider, { limit: Math.max(1, limit), running: 0 });
-        }
-      }
+    for (const [provider, limit] of Object.entries(config.providers ?? {})) {
+      this.applyConcurrencyEntry(this.providerSlots, provider, limit);
     }
 
     // Update existing slots and create new ones
-    for (const [modelKey, limit] of Object.entries(config.models)) {
-      const existing = this.concurrencySlots.get(modelKey);
-      if (existing) {
-        existing.limit = Math.max(1, limit);
-      } else {
-        this.concurrencySlots.set(modelKey, { limit: Math.max(1, limit), running: 0 });
-      }
+    for (const [modelKey, limit] of Object.entries(config.models ?? {})) {
+      this.applyConcurrencyEntry(this.concurrencySlots, modelKey, limit);
     }
 
     // Start queued agents if the new limits allow
     this.drainQueue();
   }
 
+  /**
+   * Update or create a concurrency slot entry.
+   * If the key already exists in the map, updates its limit.
+   * Otherwise, creates a new slot with the given limit and running=0.
+   */
+  private applyConcurrencyEntry(map: Map<string, ConcurrencySlot>, key: string, limit: number): void {
+    const safeLimit = Math.max(1, limit);
+    const existing = map.get(key);
+    if (existing) {
+      existing.limit = safeLimit;
+    } else {
+      map.set(key, { limit: safeLimit, running: 0 });
+    }
+  }
+
   /**
    * Get or create a concurrency slot for a model key.
    * Precedence: per-model slot > per-provider shared slot > default (per-model).
-   * Returns { slot, isProviderSlot } so caller knows which slot to decrement.
    */
-  private getSlot(modelKey: string): { slot: ConcurrencySlot; isProviderSlot: boolean } {
+  private getSlot(modelKey: string): ConcurrencySlot {
     // 1. Check per-model slot
     let slot = this.concurrencySlots.get(modelKey);
-    if (slot) return { slot, isProviderSlot: false };
+    if (slot) return slot;
 
     // 2. Check per-provider shared slot
     const provider = modelKey.split("/")[0];
     const providerSlot = this.providerSlots.get(provider);
-    if (providerSlot) return { slot: providerSlot, isProviderSlot: true };
+    if (providerSlot) return providerSlot;
 
     // 3. Create per-model slot with default limit
     slot = { limit: Math.max(1, this.defaultConcurrency), running: 0 };
     this.concurrencySlots.set(modelKey, slot);
-    return { slot, isProviderSlot: false };
+    return slot;
   }
 
   /**
@@ -221,7 +233,7 @@ export class AgentManager {
     prompt: string,
     options: SpawnOptions,
   ): string {
-    const id = randomUUID().slice(0, 17);
+    const id = randomUUID().slice(0, AGENT_ID_LENGTH);
     const abortController = new AbortController();
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
 
@@ -229,7 +241,7 @@ export class AgentManager {
     let queued = false;
     let concurrencySlot: ConcurrencySlot | undefined;
     if (options.modelKey) {
-      const { slot } = this.getSlot(options.modelKey);
+      const slot = this.getSlot(options.modelKey);
       if (slot.running >= slot.limit) {
         queued = true;
         this.queue.push({ id, modelKey: options.modelKey, args });
@@ -246,7 +258,7 @@ export class AgentManager {
       toolUses: 0,
       startedAt: Date.now(),
       abortController,
-      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
       compactionCount: 0,
       invocation: options.invocation,
       maxTurns: options.maxTurns,
@@ -300,29 +312,21 @@ export class AgentManager {
       isolated: options.isolated,
       thinkingLevel: options.thinkingLevel,
       signal: record.abortController!.signal,
-      onToolActivity: (activity) => {
-        if (activity.type === "end") record.toolUses++;
-        options.onToolActivity?.(activity);
-      },
+      ...this.createRecordCallbacks(record, options),
       onTurnEnd: (turnCount) => {
         record.turnCount = turnCount;
         options.onTurnEnd?.(turnCount);
       },
       onTextDelta: options.onTextDelta,
-      onAssistantUsage: (usage) => {
-        addUsage(record.lifetimeUsage, usage);
-        options.onAssistantUsage?.(usage);
-      },
-      onCompaction: (info) => {
-        record.compactionCount++;
-        options.onCompaction?.(info);
-      },
       onSessionCreated: (session) => {
         record.session = session;
         // Flush any steers that arrived before the session was ready
         if (record.pendingSteers?.length) {
           for (const msg of record.pendingSteers) {
-            session.steer(msg).catch(() => {});
+            session.steer(msg).catch(() => {
+              // Steer is advisory — a failure here (e.g. session already aborting)
+              // is fine; the user can re-send if needed.
+            });
           }
           record.pendingSteers = undefined;
         }
@@ -364,13 +368,47 @@ export class AgentManager {
         // Decrement per-model concurrency count
         if (concurrencySlot) concurrencySlot.running--;
 
-        try { this.onComplete?.(record); } catch { /* ignore */ }
+        this.safeNotifyComplete(record);
         this.drainQueue();
       });
 
     record.promise = promise;
   }
 
+  /** Notify completion callback, ignoring any errors. */
+  private safeNotifyComplete(record: AgentRecord): void {
+    try { this.onComplete?.(record); } catch { /* ignore */ }
+  }
+
+  /**
+   * Build common record-tracking callbacks shared by startAgent and resume.
+   * Updates the record's toolUses, lifetimeUsage, and compactionCount.
+   * When options are provided, also forwards events to the caller.
+   */
+  private createRecordCallbacks(
+    record: AgentRecord,
+    options?: Pick<SpawnOptions, "onToolActivity" | "onAssistantUsage" | "onCompaction">,
+  ): {
+    onToolActivity: (activity: ToolActivity) => void;
+    onAssistantUsage: (usage: LifetimeUsage) => void;
+    onCompaction: (info: CompactionInfo) => void;
+  } {
+    return {
+      onToolActivity: (activity) => {
+        if (activity.type === "end") record.toolUses++;
+        options?.onToolActivity?.(activity);
+      },
+      onAssistantUsage: (usage) => {
+        addUsage(record.lifetimeUsage, usage);
+        options?.onAssistantUsage?.(usage);
+      },
+      onCompaction: (info) => {
+        record.compactionCount++;
+        options?.onCompaction?.(info);
+      },
+    };
+  }
+
   /** Start queued agents up to the per-model concurrency limits. */
   private drainQueue() {
     const started = new Set<string>();
@@ -390,29 +428,12 @@ export class AgentManager {
         record.error = errorMessage(err);
         record.completedAt = Date.now();
         started.add(entry.id);
-        this.onComplete?.(record);
+        this.safeNotifyComplete(record);
       }
     }
     this.queue = this.queue.filter(e => !started.has(e.id));
   }
 
-  /**
-   * Spawn an agent and wait for completion (foreground use).
-   * Respects per-model concurrency limits — queued if at capacity, awaited on completion.
-   */
-  async spawnAndWait(
-    pi: ExtensionAPI,
-    ctx: ExtensionContext,
-    type: SubagentType,
-    prompt: string,
-    options: Omit<SpawnOptions, "isBackground">,
-  ): Promise<AgentRecord> {
-    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
-    const record = this.agents.get(id)!;
-    await record.promise;
-    return record;
-  }
-
   /**
    * Resume an existing agent session with a new prompt.
    */
@@ -432,15 +453,7 @@ export class AgentManager {
 
     try {
       const responseText = await resumeAgent(record.session, prompt, {
-        onToolActivity: (activity) => {
-          if (activity.type === "end") record.toolUses++;
-        },
-        onAssistantUsage: (usage) => {
-          addUsage(record.lifetimeUsage, usage);
-        },
-        onCompaction: (info) => {
-          record.compactionCount++;
-        },
+        ...this.createRecordCallbacks(record),
         signal,
       });
       record.status = "completed";
@@ -476,6 +489,7 @@ export class AgentManager {
       await record.session.steer(message);
       return true;
     } catch {
+      // steer failures are surfaced to the caller via the boolean return value
       return false;
     }
   }
@@ -526,7 +540,7 @@ export class AgentManager {
   }
 
   private cleanup() {
-    const cutoff = Date.now() - 10 * 60_000;
+    const cutoff = Date.now() - CLEANUP_AGE_CUTOFF_MS;
     for (const [id, record] of this.agents) {
       if (!isTerminalStatus(record.status)) continue;
       if ((record.completedAt ?? 0) >= cutoff) continue;

package/src/agent-runner.ts

@@ -25,10 +25,12 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { getAgentConfig, getConfig, getToolNamesForType } from "./agent-types.js";
 import { extractText } from "./context.js";
+import type { LifetimeUsage } from "./usage.js";
+import { findModelInRegistry } from "./utils.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
-import type { EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
+import type { CompactionInfo, EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 export const EXCLUDED_TOOL_NAMES = ["Agent"];
@@ -36,34 +38,15 @@ export const EXCLUDED_TOOL_NAMES = ["Agent"];
 /** Additional turns allowed after the soft limit steer message. */
 const GRACE_TURNS = 5;
 
+/** Timeout for quick git commands (branch detection, repo check). */
+const GIT_EXEC_TIMEOUT_MS = 5000;
+
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 function normalizeMaxTurns(n: number | undefined): number | undefined {
   if (n == null || n === 0) return undefined;
   return Math.max(1, n);
 }
 
-/**
- * Try to find the right model for an agent type.
- * Priority: explicit option > config.model > parent model.
- */
-function resolveDefaultModel(
-  parentModel: Model<any> | undefined,
-  registry: { find(provider: string, modelId: string): Model<any> | undefined },
-  configModel?: string,
-): Model<any> | undefined {
-  if (configModel) {
-    const slashIdx = configModel.indexOf("/");
-    if (slashIdx !== -1) {
-      const provider = configModel.slice(0, slashIdx);
-      const modelId = configModel.slice(slashIdx + 1);
-      const found = registry.find(provider, modelId);
-      if (found) return found;
-    }
-  }
-
-  return parentModel;
-}
-
 /** Info about a tool event in the subagent. */
 export interface ToolActivity {
   type: "start" | "end";
@@ -95,12 +78,12 @@ interface RunOptions {
    * Lets callers maintain a lifetime accumulator that survives compaction
    * (which replaces session.state.messages and resets stats-derived sums).
    */
-  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  onAssistantUsage?: (usage: LifetimeUsage) => void;
   /**
    * Called when the session successfully compacts. `tokensBefore` is upstream's
    * pre-compaction context size estimate. Aborted compactions don't fire.
    */
-  onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
+  onCompaction?: (info: CompactionInfo) => void;
 }
 
 interface RunResult {
@@ -155,11 +138,28 @@ function forwardAbortSignal(session: AgentSession, signal?: AbortSignal): () =>
   return () => signal.removeEventListener("abort", onAbort);
 }
 
+/**
+ * Extract a LifetimeUsage from a runtime assistant message_end event.
+ * pi-ai attaches `usage: { input, output, cacheWrite, cost: { total } }` to
+ * assistant messages at runtime, but this shape isn't reflected in the
+ * AgentSessionEvent public types.
+ */
+function usageFromAssistantMessage(msg: Record<string, unknown>): LifetimeUsage | undefined {
+  const usage = msg.usage as Record<string, unknown> | undefined;
+  if (!usage) return undefined;
+  return {
+    input: (usage.input as number) ?? 0,
+    output: (usage.output as number) ?? 0,
+    cacheWrite: (usage.cacheWrite as number) ?? 0,
+    cost: ((usage.cost as Record<string, unknown>)?.total as number) ?? 0,
+  };
+}
+
 /**
  * Subscribe to shared session events (tool activity, usage, compaction)
  * used by both runAgent and resumeAgent. Returns an unsubscribe function.
  */
-function subscribeToSessionEvents(
+export function subscribeToSessionEvents(
   session: AgentSession,
   options: Pick<RunOptions, "onToolActivity" | "onAssistantUsage" | "onCompaction">,
 ): () => void {
@@ -174,13 +174,10 @@ function subscribeToSessionEvents(
       options.onToolActivity?.({ type: "end", toolName: event.toolName });
     }
     if (event.type === "message_end" && event.message.role === "assistant") {
-      const u = (event.message as any).usage;
-      if (u) {
-        options.onAssistantUsage?.({
-          input: u.input ?? 0,
-          output: u.output ?? 0,
-          cacheWrite: u.cacheWrite ?? 0,
-        });
+      const msg = event.message as unknown as Record<string, unknown>;
+      const usage = usageFromAssistantMessage(msg);
+      if (usage) {
+        options.onAssistantUsage?.(usage);
       }
     }
     if (event.type === "compaction_end" && !event.aborted && event.result) {
@@ -210,7 +207,7 @@ function filterActiveTools(
   }
 
   const builtinToolNameSet = new Set(builtinToolNames);
-  return activeTools.filter((t) => {
+  const filtered = activeTools.filter((t) => {
     if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
     if (disallowedSet?.has(t)) return false;
     if (builtinToolNameSet.has(t)) return true;
@@ -219,12 +216,13 @@ function filterActiveTools(
     }
     return true;
   });
+  return filtered.length !== activeTools.length ? filtered : null;
 }
 
 /** Run a git command via pi.exec, returning stdout on success or null on failure. */
 async function execGit(pi: ExtensionAPI, args: string[], cwd: string): Promise<string | null> {
   try {
-    const result = await pi.exec("git", args, { cwd, timeout: 5000 });
+    const result = await pi.exec("git", args, { cwd, timeout: GIT_EXEC_TIMEOUT_MS });
     return result.code === 0 ? result.stdout.trim() : null;
   } catch {
     return null;
@@ -262,8 +260,10 @@ export async function runAgent(
   const env = await detectEnv(options.pi, effectiveCwd);
 
   // Resolve extensions/skills: isolated overrides to false
-  const extensions = options.isolated ? false : config.extensions;
-  const skills = options.isolated ? false : config.skills;
+  // Falls back to agent config (frontmatter) when not set via options (tool injection)
+  const effectiveIsolated = options.isolated ?? agentConfig?.isolated;
+  const extensions = effectiveIsolated ? false : config.extensions;
+  const skills = effectiveIsolated ? false : config.skills;
 
   // Build prompt extras (no memoryBlock — skills only).
   // When skills is string[], preload their content into the prompt.
@@ -305,8 +305,8 @@ export async function runAgent(
   await loader.reload();
 
   // Resolve model: explicit option > config.model > parent model
-  const model = options.model ?? resolveDefaultModel(
-    ctx.model, ctx.modelRegistry, agentConfig?.model,
+  const model = options.model ?? findModelInRegistry(
+    agentConfig?.model, ctx.modelRegistry, ctx.model,
   );
 
   // Resolve thinking level: explicit option > agent config > undefined (inherit)
@@ -419,16 +419,7 @@ export async function resumeAgent(
   return collector.getText().trim() || getLastAssistantText(session);
 }
 
-/**
- * Send a steering message to a running subagent.
- * The message will interrupt the agent after its current tool execution.
- */
-export async function steerAgent(
-  session: AgentSession,
-  message: string,
-): Promise<void> {
-  await session.steer(message);
-}
+
 
 
 

package/src/agent-types.ts

@@ -12,7 +12,7 @@ import { DEFAULT_AGENTS } from "./default-agents.js";
 import type { AgentConfig } from "./types.js";
 
 /** All known built-in tool names. */
-export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];
 
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map<string, AgentConfig>();
@@ -36,8 +36,8 @@ export function registerAgents(userAgents: Map<string, AgentConfig>): void {
   }
 }
 
-/** Case-insensitive key resolution, also matches displayName. */
-function resolveKey(name: string): string | undefined {
+/** Resolve a type name case-insensitively. Also matches displayName. Returns the canonical key or undefined. */
+export function resolveType(name: string): string | undefined {
   if (!name) return undefined;
   if (agents.has(name)) return name;
   const lower = name.toLowerCase();
@@ -48,14 +48,9 @@ function resolveKey(name: string): string | undefined {
   return undefined;
 }
 
-/** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
-export function resolveType(name: string): string | undefined {
-  return resolveKey(name);
-}
-
 /** Get the agent config for a type (case-insensitive). */
 export function getAgentConfig(name: string): AgentConfig | undefined {
-  const key = resolveKey(name);
+  const key = resolveType(name);
   return key ? agents.get(key) : undefined;
 }
 
@@ -71,26 +66,6 @@ export function getAllTypes(): string[] {
   return [...agents.keys()];
 }
 
-/** Get names of default agents currently in the registry. */
-export function getDefaultAgentNames(): string[] {
-  return [...agents.entries()]
-    .filter(([_, config]) => config.isDefault === true)
-    .map(([name]) => name);
-}
-
-/** Get names of user-defined agents (non-defaults) currently in the registry. */
-export function getUserAgentNames(): string[] {
-  return [...agents.entries()]
-    .filter(([_, config]) => config.isDefault !== true)
-    .map(([name]) => name);
-}
-
-/** Check if a type is valid and enabled (case-insensitive). */
-export function isValidType(type: string): boolean {
-  const config = getAgentConfig(type);
-  return config !== undefined && config.enabled !== false;
-}
-
 /** Get built-in tool names for a type (case-insensitive). */
 export function getToolNamesForType(type: string): string[] {
   const config = getAgentConfig(type);
@@ -99,14 +74,16 @@ export function getToolNamesForType(type: string): string[] {
     : [...BUILTIN_TOOL_NAMES];
 }
 
-/** Convert an AgentConfig to the SubagentTypeConfig shape used by getConfig. */
-function toSubagentTypeConfig(config: AgentConfig): {
+/** Resolved config shape returned by getConfig. */
+interface ResolvedAgentConfig {
   displayName: string;
   description: string;
   builtinToolNames: string[];
   extensions: true | string[] | false;
   skills: true | string[] | false;
-} {
+}
+
+function toResolved(config: AgentConfig): ResolvedAgentConfig {
   return {
     displayName: config.displayName ?? config.name,
     description: config.description,
@@ -117,16 +94,17 @@ function toSubagentTypeConfig(config: AgentConfig): {
 }
 
 /** Get config for a type (case-insensitive). Falls back to general-purpose. */
-export function getConfig(type: string): ReturnType<typeof toSubagentTypeConfig> {
-  const key = resolveKey(type);
-  const config = key ? agents.get(key) : undefined;
+export function getConfig(type: string): ResolvedAgentConfig {
+  const resolvedKey = resolveType(type);
+  const config = resolvedKey ? agents.get(resolvedKey) : undefined;
 
-  const activeConfig = (config?.enabled !== false)
+  // If config exists and is enabled, use it; otherwise fall back to general-purpose
+  const activeConfig = config?.enabled !== false
     ? config
     : agents.get("general-purpose");
 
   if (activeConfig && activeConfig.enabled !== false) {
-    return toSubagentTypeConfig(activeConfig);
+    return toResolved(activeConfig);
   }
 
   // Absolute fallback — general-purpose was disabled or missing

package/src/config-io.ts

@@ -0,0 +1,40 @@
+/**
+ * config-io.ts — Config persistence (read/write).
+ *
+ * Atomic writes: write to .tmp then rename.
+ * Loaded at session_start; saved on every /agents menu mutation.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { SubagentsConfig } from "./model-precedence.js";
+
+const CONFIG_DIR = path.join(process.env.HOME || "", ".pi", "agent");
+const CONFIG_PATH = path.join(CONFIG_DIR, "subagents-lite.json");
+
+/** Read config from disk. Returns defaults if file doesn't exist or is invalid. */
+export function loadConfig(): SubagentsConfig {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
+    return JSON.parse(raw) as SubagentsConfig;
+  } catch {
+    // File doesn't exist or is invalid — return defaults
+  }
+
+  return {
+    agent: { default: null, forceBackground: false },
+    concurrency: { default: 4 },
+  };
+}
+
+/** Write config to disk with atomic rename. */
+export function saveConfigAtomic(config: SubagentsConfig): void {
+  const tmpPath = CONFIG_PATH + ".tmp";
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+    fs.renameSync(tmpPath, CONFIG_PATH);
+  } catch (err) {
+    console.error(`[subagents] Failed to save config: ${err}`);
+  }
+}