@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.8

package/src/agent-runner.ts

@@ -14,10 +14,9 @@ import {
   createCodemodeExtension,
   createMcpExtension,
   createToolSearchExtension,
-  DefaultResourceLoader,
+  type DefaultResourceLoader,
   defineTool,
   type ExtensionAPI,
-  getAgentDir,
   type InlineExtension,
   SessionManager,
   SettingsManager,
@@ -28,8 +27,11 @@ import { runInChildSessionContext } from "./child-context.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
+import { normalizeHomePath, resolveAgentDir } from "./home-paths.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import type { ModelCallEvent } from "./model-call.js";
+import type { ModelFallback } from "./model-resolver.js";
+import type { ModelSelection } from "./model-selection.js";
 import {
   createNestedSubagentTools,
   getMaxSubagentDepth,
@@ -38,7 +40,9 @@ import {
   type NestedAgentManager,
 } from "./nested-tools.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
+import { createHomeResourceLoader } from "./resource-loader.js";
 import { preloadSkills } from "./skill-loader.js";
+import { isStaleCtxError } from "./stale-ctx.js";
 import { createStructuredCapture, createStructuredOutputTool, structuredRetryPrompt } from "./structured-output.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 import type { LifetimeUsage } from "./usage.js";
@@ -187,6 +191,7 @@ export function extensionCanonicalNames(extPath: string): string[] {
 export function parseExtensionsSpec(
   entries: string[],
   cwd: string,
+  homeDir = homedir(),
 ): { names: Set<string>; paths: string[]; wildcard: boolean } {
   const names = new Set<string>();
   const paths: string[] = [];
@@ -202,10 +207,10 @@ export function parseExtensionsSpec(
       names.add(entry.toLowerCase());
       continue;
     }
+    // This frontmatter caller historically expands both slash forms on every
+    // platform, without interpreting file URLs or Windows shell drive forms.
     let p = entry;
-    if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) {
-      p = homedir() + p.slice(1);
-    }
+    if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) p = homeDir + p.slice(1);
     const abs = isAbsolute(p) ? p : resolve(cwd, p);
     paths.push(abs);
     names.add(extensionCanonicalName(abs));
@@ -474,37 +479,6 @@ const FINAL_REPORT_PROMPT =
   + "Write your complete final report now: everything you found, concrete file paths and line numbers, "
   + "what you changed or concluded, and anything unfinished or unverified.";
 
-/**
- * Try to find the right model for an agent type.
- * Priority: explicit option > config.model > parent model.
- */
-export function resolveDefaultModel(
-  parentModel: Model<any> | undefined,
-  registry: { find(provider: string, modelId: string): Model<any> | undefined; getAvailable?(): Model<any>[] },
-  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);
-
-      // Build a set of available model keys for fast lookup
-      const available = registry.getAvailable?.();
-      const availableKeys = available
-        ? new Set(available.map((m: any) => `${m.provider}/${m.id}`))
-        : undefined;
-      const isAvailable = (p: string, id: string) =>
-        !availableKeys || availableKeys.has(`${p}/${id}`);
-
-      const found = registry.find(provider, modelId);
-      if (found && isAvailable(provider, modelId)) return found;
-    }
-  }
-
-  return parentModel;
-}
-
 /** Info about a tool event in the subagent. */
 export interface ToolActivity {
   type: "start" | "end";
@@ -519,11 +493,15 @@ export interface AssistantMessageInfo {
 }
 
 export interface RunOptions {
+  /** Backoff before each stale-ctx re-prompt (#145); defaults to 1s, 3s, 9s. `[]` disables recovery. */
+  staleRetryDelaysMs?: readonly number[];
   /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
   pi: ExtensionAPI;
   /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
   agentId?: string;
   model?: Model<any>;
+  /** Required admitted spawn outcome. The runner never resolves or admits models. */
+  modelSelection: ModelSelection;
   maxTurns?: number;
   signal?: AbortSignal;
   /** Applies only when the agent file leaves `isolated:` unset — frontmatter is authoritative. */
@@ -557,6 +535,8 @@ export interface RunOptions {
   workflow?: boolean;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
+  /** Home directory for tilde expansion and user-scoped storage. Defaults at run time. */
+  homeDir?: string;
   /**
    * Directory the worktree copy was created from. Set only when `cwd` points
    * into a worktree — the prompt then tells the agent to stay in the copy
@@ -592,6 +572,8 @@ export interface RunOptions {
   /** Called for every streaming event of each model call, so a UI can say what an in-flight call is doing. */
   onModelCall?: (event: ModelCallEvent) => void;
   onSessionCreated?: (session: AgentSession) => void;
+  /** Direct runner callers can observe the same configured fallback as the shared spawn. */
+  onModelFallback?: (fallback: ModelFallback) => void;
   /** Called at the end of each agentic turn with the cumulative count. */
   onTurnEnd?: (turnCount: number) => void;
   /**
@@ -801,6 +783,105 @@ function finalTurnError(session: AgentSession, startIndex = 0): string | undefin
   return undefined;
 }
 
+/** Waits before each re-prompt of a step lost to a stale ctx: a reload re-registers within seconds. */
+const STALE_CTX_RETRY_DELAYS_MS: readonly number[] = [1_000, 3_000, 9_000];
+
+/** Sent when the session's last step died on a stale ctx; the transcript already holds the work so far. */
+const STALE_CTX_RETRY_PROMPT = "Your previous step was interrupted by a session reload before it produced output. Continue the task from where you left off.";
+
+/** Longest tool output echoed into a partial result. */
+const PARTIAL_TOOL_OUTPUT_CHARS = 1_500;
+
+/**
+ * Resolve after `ms`, or as soon as `signal` aborts. Never rejects.
+ */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+/**
+ * Re-prompt a session whose final step died on a stale extension ctx, backing
+ * off between attempts so a reload in progress can re-register its routes.
+ * Returns once the final step no longer fails that way, retries are spent, or
+ * `signal` aborts. A permanently dead runtime (the parent session was replaced)
+ * exhausts the retries and is reported by `staleCtxOutcome`.
+ *
+ * Why appending a continue prompt is safe, and re-sending the task is not: the
+ * failed step died in model routing or an observer, before the model produced
+ * anything, so the transcript already holds every tool call and result the run
+ * made. Re-sending the task would show the model the same work twice and invite
+ * it to repeat side effects (a push, a PR). The continue prompt adds one user
+ * turn and nothing else, so the tool batch is never replayed; a tool that did
+ * run is in context as a result.
+ */
+export async function retryStaleCtx(
+  session: AgentSession,
+  startIndex: number,
+  signal: AbortSignal | undefined,
+  delays: readonly number[] = STALE_CTX_RETRY_DELAYS_MS,
+): Promise<void> {
+  for (const delay of delays) {
+    if (!isStaleCtxError(finalTurnError(session, startIndex))) return;
+    await sleep(delay, signal);
+    if (signal?.aborted) return;
+    await session.prompt(STALE_CTX_RETRY_PROMPT);
+  }
+}
+
+/**
+ * Whether a follow-up prompt (the structured-output retry, the forced final
+ * report) may still be sent. Not once the run was stopped, and not while the
+ * final step is still a stale ctx: the runtime is dead, so the prompt would
+ * fail the same way and mask the real outcome behind a doomed turn.
+ */
+function mayFollowUp(session: AgentSession, startIndex: number, signal: AbortSignal | undefined): boolean {
+  return !signal?.aborted && staleCtxOutcome(session, startIndex) === undefined;
+}
+
+/**
+ * What a run that died on a stale ctx had done: the last tool calls with the
+ * last tool output, so the parent can see side effects (a pushed branch, an
+ * opened PR) instead of "No output". Empty when the run did nothing.
+ */
+function partialProgress(session: AgentSession, startIndex: number): string {
+  const calls: string[] = [];
+  let lastOutput = "";
+  for (let i = session.messages.length - 1; i >= startIndex && calls.length < 5; i--) {
+    const msg = session.messages[i];
+    if (msg.role === "toolResult" && !lastOutput) lastOutput = extractText(msg.content).trim();
+    if (msg.role === "assistant") {
+      for (const part of [...msg.content].reverse()) {
+        if (part.type === "toolCall" && calls.length < 5) calls.unshift(part.name);
+      }
+    }
+  }
+  if (calls.length === 0) return "";
+  const clipped = lastOutput.length > PARTIAL_TOOL_OUTPUT_CHARS ? `${lastOutput.slice(0, PARTIAL_TOOL_OUTPUT_CHARS)}...` : lastOutput;
+  return `Last tool calls: ${calls.join(", ")}.${clipped ? `\nLast tool output:\n${clipped}` : ""}`;
+}
+
+/**
+ * The failure and partial result for a run whose final step is still a stale
+ * ctx after retries; undefined for any other outcome.
+ */
+export function staleCtxOutcome(session: AgentSession, startIndex: number): { failure: string; partial: string } | undefined {
+  const error = finalTurnError(session, startIndex);
+  if (!isStaleCtxError(error)) return undefined;
+  return {
+    failure: "interrupted by a session reload or replacement; the agent's model runtime went stale and retries did not recover it",
+    partial: partialProgress(session, startIndex),
+  };
+}
+
 /** The per-run callbacks a spawn and a resume share, plus the resolved turn limit. */
 type RunObserverOptions = Pick<RunOptions, "onTurnEnd" | "onTextDelta" | "onModelCall" | "onToolActivity" | "onAssistantUsage" | "onCompaction"> & {
   /** Already resolved: undefined = unlimited. */
@@ -823,9 +904,8 @@ function observeRun(session: AgentSession, options: RunObserverOptions) {
     steered: false,
     aborted: false,
     finalizing: false,
-    unsubscribe: () => {},
   };
-  run.unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
     if (event.type === "turn_end") {
       turnCount++;
       options.onTurnEnd?.(turnCount);
@@ -874,7 +954,8 @@ function observeRun(session: AgentSession, options: RunObserverOptions) {
       options.onCompaction?.({ reason: event.reason, tokensBefore: event.result.tokensBefore });
     }
   });
-  return run;
+  // Keep the live state object captured by the listener, adding only the real cleanup.
+  return Object.assign(run, { unsubscribe });
 }
 
 /**
@@ -888,9 +969,9 @@ function forwardAbortSignal(session: AgentSession, signal?: AbortSignal): () =>
   return () => signal.removeEventListener("abort", onAbort);
 }
 
-function resolveConfiguredSessionDir(sessionDir: string | undefined, cwd: string): string | undefined {
+function resolveConfiguredSessionDir(sessionDir: string | undefined, cwd: string, homeDir = homedir()): string | undefined {
   if (!sessionDir) return undefined;
-  if (sessionDir === "~" || sessionDir.startsWith("~/")) return resolve(homedir(), sessionDir.slice(2));
+  if (sessionDir === "~" || sessionDir.startsWith("~/")) return resolve(homeDir, sessionDir.slice(2));
   if (isAbsolute(sessionDir)) return sessionDir;
   return resolve(cwd, sessionDir);
 }
@@ -932,7 +1013,7 @@ export async function runAgent(
 
   // Skill preloading: when skills is string[], preload their content into prompt
   if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, configCwd);
+    const loaded = preloadSkills(skills, configCwd, options.homeDir);
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -952,12 +1033,12 @@ export async function runAgent(
       // Read-write memory: add any missing memory tool names (read/write/edit)
       const extraNames = getMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
+      extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, configCwd, options.homeDir);
     } else {
       // Read-only memory: only add read tool name, use read-only prompt
       const extraNames = getReadOnlyMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
+      extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, configCwd, options.homeDir);
     }
   }
 
@@ -993,7 +1074,7 @@ export async function runAgent(
   // Still pass noSkills: true since we don't need the skill loader to load them again.
   const noSkills = skills === false || Array.isArray(skills);
 
-  const agentDir = getAgentDir();
+  const agentDir = resolveAgentDir(options.homeDir);
 
   // Extension loading:
   // - true  → all default-discovered extensions
@@ -1018,7 +1099,7 @@ export async function runAgent(
   const noExtensions = extensions === false;
 
   const extensionsSpec = Array.isArray(extensions)
-    ? parseExtensionsSpec(extensions, configCwd)
+    ? parseExtensionsSpec(extensions, configCwd, options.homeDir)
     : undefined;
   const keepNames = extensionsSpec?.names ?? new Set<string>();
   // `exclude_extensions:` is a denylist applied AFTER the include set — exclude wins.
@@ -1073,7 +1154,7 @@ export async function runAgent(
         });
   const nestedCallGate: NestedCallGate = {};
 
-  const loader = new DefaultResourceLoader({
+  const loader = createHomeResourceLoader({
     settingsManager,
     // pi's CLI hands its built-in extensions to the loader it builds; this one starts
     // with none. Forwarded as `builtin:` resources they load as in the main session —
@@ -1105,7 +1186,7 @@ export async function runAgent(
     noContextFiles: true,
     systemPromptOverride: () => systemPrompt,
     appendSystemPromptOverride: () => [],
-  });
+  }, options.homeDir);
   await runInChildSessionContext(() => loader.reload());
 
   // Plain entries in `tools:` are expected to be built-in names (extension tools
@@ -1177,10 +1258,8 @@ export async function runAgent(
     }
   }
 
-  // Resolve model: explicit option > config.model > parent model
-  const model = options.model ?? resolveDefaultModel(
-    ctx.model, ctx.modelRegistry, agentConfig?.model,
-  );
+  const model = options.modelSelection.model;
+  if (options.modelSelection.fallback) options.onModelFallback?.(options.modelSelection.fallback);
 
   // Resolve thinking level: explicit option > agent config > undefined (inherit)
   const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
@@ -1201,6 +1280,7 @@ export async function runAgent(
         depth: nestedRuntime.depth,
         maxSubagentDepth: effectiveMaxDepth,
         allowedSubagents: agentConfig.allowedSubagents,
+        homeDir: options.homeDir,
         configCwd,
         projectTrusted,
       })
@@ -1301,8 +1381,17 @@ export async function runAgent(
     sessionExcludeTools = [...denyTools];
   }
 
-  const configuredSessionDir = resolveConfiguredSessionDir(agentConfig?.sessionDir, effectiveCwd);
-  const defaultSessionDir = process.env.PI_CODING_AGENT_SESSION_DIR ?? settingsManager.getSessionDir?.();
+  const configuredSessionDir = resolveConfiguredSessionDir(agentConfig?.sessionDir, effectiveCwd, options.homeDir);
+  const sessionDirSetting = process.env.PI_CODING_AGENT_SESSION_DIR ?? settingsManager.getSessionDir?.();
+  // SessionManager's implicit default consults the host home again. Pin the
+  // same cwd encoding under our injected agentDir instead when isolating a run.
+  // SDK settings go straight through SessionManager's native normalization;
+  // unlike frontmatter, file URLs expand and relative settings stay relative.
+  const defaultSessionDir = options.homeDir === undefined
+    ? sessionDirSetting
+    : sessionDirSetting
+      ? normalizeHomePath(sessionDirSetting, options.homeDir)
+      : join(resolve(agentDir), "sessions", `--${resolve(effectiveCwd).replace(/^[/\\\\]/, "").replace(/[/\\\\:]/g, "-")}--`);
   // Frontmatter wins when it says anything; otherwise the project default,
   // which `rememberAgents` supplies for top-level agents only. Same precedence
   // as `outputTranscript`.
@@ -1417,12 +1506,13 @@ export async function runAgent(
     // pi's `session.abort()` is a no-op until a run is active — so a child whose
     // parent is already gone is not prompted at all.
     if (options.signal?.aborted !== true) await session.prompt(effectivePrompt);
+    await retryStaleCtx(session, startLen, options.signal, options.staleRetryDelaysMs);
 
     // A cap fired. The wrap-up steer is only a request: a model deep in a tool
     // loop keeps calling tools through the grace turns and is then aborted
     // mid-turn, leaving its last narration as the "result". Demand the report
     // in a turn that cannot call tools.
-    if (run.steered && options.signal?.aborted !== true && !endedWithReport(session, startLen)) {
+    if (run.steered && mayFollowUp(session, startLen, options.signal) && !endedWithReport(session, startLen)) {
       run.finalizing = true;
       const reported = await forceFinalReport(session, startLen, options.signal);
       // A delivered report is a wrap-up, not a failure: the agent did hand back
@@ -1436,7 +1526,7 @@ export async function runAgent(
     // the abort forwarding are still live: torn down first, a retry would be
     // unkillable.
     if (structuredCapture !== undefined && structuredCapture.json === undefined
-      && !run.aborted && options.signal?.aborted !== true) {
+      && !run.aborted && mayFollowUp(session, startLen, options.signal)) {
       structuredRetried = true;
       await session.prompt(structuredRetryPrompt(structuredCapture));
     }
@@ -1446,7 +1536,8 @@ export async function runAgent(
     cleanupAbort();
   }
 
-  const responseText = collector.getText().trim() || getLastAssistantText(session, startLen);
+  const stale = staleCtxOutcome(session, startLen);
+  const responseText = collector.getText().trim() || getLastAssistantText(session, startLen) || stale?.partial || "";
   // A child asked for structured output that never gave any has failed, however
   // articulate its prose was. Reported through `failure` so it travels the same
   // path as a provider error rather than arriving as a successful empty answer.
@@ -1460,7 +1551,7 @@ export async function runAgent(
     session,
     aborted: run.aborted,
     steered: run.steered,
-    failure: finalTurnError(session, startLen) ?? structuredFailure,
+    failure: stale?.failure ?? finalTurnError(session, startLen) ?? structuredFailure,
     ...(structuredCapture?.json !== undefined ? { structuredJson: structuredCapture.json } : {}),
     ...(structuredRetried ? { structuredRetried } : {}),
   };
@@ -1475,7 +1566,7 @@ export async function runAgent(
 export async function resumeAgent(
   session: AgentSession,
   prompt: string,
-  options: Pick<RunOptions, "maxTurns" | "onTurnEnd" | "onTextDelta" | "onModelCall" | "onToolActivity" | "onAssistantUsage" | "onCompaction" | "signal"> & {
+  options: Pick<RunOptions, "staleRetryDelaysMs" | "maxTurns" | "onTurnEnd" | "onTextDelta" | "onModelCall" | "onToolActivity" | "onAssistantUsage" | "onCompaction" | "signal"> & {
     /** The agent's type, for its own `max_turns`. */
     type: SubagentType;
   },
@@ -1491,7 +1582,8 @@ export async function resumeAgent(
   try {
     // Already aborted: not prompted, as in `runAgent`.
     if (options.signal?.aborted !== true) await session.prompt(prompt);
-    if (run.steered && options.signal?.aborted !== true && !endedWithReport(session, startLen)) {
+    await retryStaleCtx(session, startLen, options.signal, options.staleRetryDelaysMs);
+    if (run.steered && mayFollowUp(session, startLen, options.signal) && !endedWithReport(session, startLen)) {
       run.finalizing = true;
       if (await forceFinalReport(session, startLen, options.signal)) run.aborted = false;
     }
@@ -1501,9 +1593,10 @@ export async function resumeAgent(
     cleanupAbort();
   }
 
+  const stale = staleCtxOutcome(session, startLen);
   return {
-    text: collector.getText().trim() || getLastAssistantText(session, startLen),
-    failure: finalTurnError(session, startLen),
+    text: collector.getText().trim() || getLastAssistantText(session, startLen) || stale?.partial || "",
+    failure: stale?.failure ?? finalTurnError(session, startLen),
     aborted: run.aborted,
     steered: run.steered,
   };

package/src/cross-extension-rpc.ts

@@ -14,8 +14,8 @@
  */
 
 import { isTopLevelAgent } from "./agent-manager.js";
-import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { checkModelScope } from "./model-scope.js";
+import type { ModelRegistry } from "./model-resolver.js";
+import { selectModel } from "./model-selection.js";
 import type { AgentRecord } from "./types.js";
 
 /** Minimal event bus interface needed by the RPC handlers. */
@@ -58,6 +58,7 @@ export interface SpawnCapable {
 }
 
 export interface RpcDeps {
+  homeDir?: string;
   events: EventBus;
   pi: unknown;                    // passed through to manager.spawn
   getCtx: () => unknown | undefined;  // returns current ExtensionContext
@@ -112,13 +113,9 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
       const ctx = getCtx();
       if (!ctx) throw new Error("No active session");
 
-      // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
-      // forward serializable values, so options.model can be a string like
-      // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
-      // — same pattern the scheduler path already uses — so the spawned
-      // agent's auth lookup doesn't crash with "No API key found for
-      // undefined".
-      let normalizedOptions = options ?? {};
+      // Validate serializable overrides through the shared selector. Preserve
+      // the raw request for spawn, which records its source and outcome.
+      const normalizedOptions = options ?? {};
       // `!= null` on purpose: a JSON-forwarding caller can serialize an unset
       // field as null, and the runner reads `options.model ?? default`, so null
       // means "inherit" — not an override to resolve or scope-check.
@@ -131,34 +128,12 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
         if (!modelRegistry) {
           throw new Error(`Model override "${label}" provided but ctx.modelRegistry is unavailable`);
         }
-        let model = override;
-        if (typeof override === "string") {
-          const resolved = resolveModel(override, modelRegistry);
-          if (typeof resolved === "string") {
-            // resolveModel returns a human-readable error string when the
-            // input doesn't match any available model. Surface it instead of
-            // silently falling back so the caller sees the auth/typo issue.
-            throw new Error(resolved);
-          }
-          model = resolved;
-          normalizedOptions = { ...normalizedOptions, model: resolved };
-        }
-
-        // A model on the RPC payload is an orchestrator-level choice, exactly
-        // like Agent({ model }) — so it gets the Agent tool's hard error, never
-        // the frontmatter warn (#240). The check reads the RESOLVED model:
-        // resolveModel is fuzzy, so a bare "sonnet" can land on a provider the
-        // caller never named. Frontmatter-pinned and parent-inherited models are
-        // resolved later, in agent-runner, and keep warn-and-proceed.
-        const verdict = checkModelScope({
-          model,
-          cwd: cwd ?? process.cwd(),
-          modelRegistry,
-          callerSupplied: true,
-          agentLabel: type,
-          modelInput: label,
+        const selection = selectModel({
+          homeDir: deps.homeDir,
+          agentType: type, paramModel: override, parentModel: undefined,
+          registry: modelRegistry, cwd: cwd ?? process.cwd(),
         });
-        if (verdict.kind === "error") throw new Error(verdict.message);
+        if (typeof selection === "string") throw new Error(selection);
       }
 
       const id = manager.spawn(pi, ctx, type, prompt, normalizedOptions);

package/src/custom-agents.ts

@@ -4,8 +4,9 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
-import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { resolveAgentDir } from "./home-paths.js";
 import {
   isPackageResourceExcluded,
   isProjectTrusted,
@@ -55,6 +56,8 @@ export interface LoadCustomAgentsOptions {
    * answer is recorded.
    */
   projectTrusted?: boolean;
+  /** Home directory for the default global agent directory. Defaults at call time. */
+  homeDir?: string;
 }
 
 /**
@@ -94,16 +97,17 @@ export function loadCustomAgents(
   strict = false,
   opts: LoadCustomAgentsOptions = {},
 ): Map<string, AgentConfig> {
-  const globalDir = join(getAgentDir(), "agents");
+  const globalDir = join(resolveAgentDir(opts.homeDir), "agents");
   const workspaceProjectDir = join(cwd, ".agents", "agents");
   const projectDir = join(cwd, ".pi", "agents");
 
   const projectTrusted = opts.projectTrusted ?? isProjectTrusted();
-  const pkgDirs = opts.packageDirs ?? packageAgentDirs(cwd, { projectTrusted });
-  const pkgFiles = opts.packageFiles ?? packageAgentFiles(cwd, { projectTrusted });
+  const discovery = { projectTrusted, homeDir: opts.homeDir };
+  const pkgDirs = opts.packageDirs ?? packageAgentDirs(cwd, discovery);
+  const pkgFiles = opts.packageFiles ?? packageAgentFiles(cwd, discovery);
   // `!./agents/wip.md` alongside `./agents` excludes one file out of a directory
   // that is only enumerated here, so the check has to run per file.
-  const excluded: Excluder = opts.packageExcluded ?? (path => isPackageResourceExcluded(path, cwd, "agents", { projectTrusted }));
+  const excluded: Excluder = opts.packageExcluded ?? (path => isPackageResourceExcluded(path, cwd, "agents", discovery));
 
   const agents = new Map<string, AgentConfig>();
   for (const dir of pkgDirs) loadFromDir(dir, agents, "package", strict, excluded); // lowest priority

package/src/default-agents.ts

@@ -34,10 +34,8 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       builtinToolNames: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,
-      // Fast/cheap portable default for read-only search. A target-local alias
-      // can select its canonical provider; otherwise fuzzy resolution finds a
-      // matching enabled model under any provider.
-      model: "claude-haiku-4-5",
+      // Bind the role per machine, not to a provider or model generation.
+      model: "@cheap",
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
 Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.

package/src/enabled-models.ts

@@ -28,7 +28,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveAgentDir } from "./home-paths.js";
 import type { ModelEntry } from "./model-resolver.js";
 
 /** Minimal registry shape — only the methods resolveEnabledModels actually calls. */
@@ -38,10 +38,10 @@ export interface ModelRegistryRef {
 }
 
 /** Paths to pi's settings.json files: [project, global] (project takes precedence). */
-function settingsPaths(cwd: string): [project: string, global: string] {
+function settingsPaths(cwd: string, homeDir?: string): [project: string, global: string] {
   return [
     join(cwd, ".pi", "settings.json"),
-    join(getAgentDir(), "settings.json"),
+    join(resolveAgentDir(homeDir), "settings.json"),
   ];
 }
 
@@ -63,8 +63,8 @@ function readField(path: string): string[] | undefined {
  * (and matches our own loadSettings precedence in src/settings.ts).
  * Returns undefined when neither file has the field.
  */
-export function readEnabledModels(cwd: string): string[] | undefined {
-  const [project, global] = settingsPaths(cwd);
+export function readEnabledModels(cwd: string, homeDir?: string): string[] | undefined {
+  const [project, global] = settingsPaths(cwd, homeDir);
   return readField(project) ?? readField(global);
 }
 
@@ -102,11 +102,12 @@ export function resolveEnabledModels(
   patterns: string[] | undefined,
   registry: ModelRegistryRef,
   cwd: string = process.cwd(),
+  homeDir?: string,
 ): Set<string> | undefined {
   // Fast path: check cache (stat both project and global settings.json files)
   const patternsKey = JSON.stringify(patterns);
-  const [project, global] = settingsPaths(cwd);
-  const fileHash = `${hashOf(project)};${hashOf(global)}`;
+  const [project, global] = settingsPaths(cwd, homeDir);
+  const fileHash = `${project}:${hashOf(project)};${global}:${hashOf(global)}`;
 
   if (fileHash === cachedHash && patternsKey === cachedPatternsKey) {
     return cachedAllowed;

package/src/enterprise-local.ts

@@ -8,7 +8,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveAgentDir } from "./home-paths.js";
 
 const MANIFEST_VERSION = 1;
 const MANIFEST_NAME = "enterprise.local.json";
@@ -21,16 +21,16 @@ export interface EnterpriseLocalManifest {
 }
 
 /** Return the target-local manifest path without reading it. */
-export function enterpriseLocalPath(): string {
-  return join(getAgentDir(), MANIFEST_NAME);
+export function enterpriseLocalPath(homeDir?: string): string {
+  return join(resolveAgentDir(homeDir), MANIFEST_NAME);
 }
 
 /**
  * Read and minimally validate the machine-local manifest. It never exposes its
  * contents in diagnostics: providers can include command-backed credentials.
  */
-export function readEnterpriseLocalManifest(): EnterpriseLocalManifest | undefined {
-  const path = enterpriseLocalPath();
+export function readEnterpriseLocalManifest(homeDir?: string): EnterpriseLocalManifest | undefined {
+  const path = enterpriseLocalPath(homeDir);
   if (!existsSync(path)) return undefined;
 
   try {