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

package/src/agent-runner.ts

@@ -14,31 +14,38 @@ import {
   createCodemodeExtension,
   createMcpExtension,
   createToolSearchExtension,
-  DefaultResourceLoader,
+  type DefaultResourceLoader,
   defineTool,
   type ExtensionAPI,
-  getAgentDir,
   type InlineExtension,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
-import { runInChildSessionContext } from "./child-context.js";
+import { bindChildResourceLoader, runInChildSessionContext } from "./child-context.js";
+import { type Clock, realClock } from "./clock.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,
+  hasNestableTypes,
   NESTED_WORKFLOW_ERROR,
   NESTED_WORKFLOW_NO_AGENT_ERROR,
   type NestedAgentManager,
 } from "./nested-tools.js";
+import { type PlanGate, planGateReason } from "./plan-mode-children.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";
@@ -55,6 +62,7 @@ export const SUBAGENT_TOOL_NAMES = {
   WORKFLOW: "SubagentWorkflow",
   GET_RESULT: "get_subagent_result",
   STEER: "steer_subagent",
+  STOP: "stop_subagent",
 } as const;
 
 /**
@@ -187,6 +195,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 +211,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));
@@ -297,11 +306,10 @@ export function installExtensionToolScope(
     /** Receives the scope check the child's nested-call gate extension applies. */
     nestedCallGate: NestedCallGate;
     /** Why workflow tools are refused. */
-    workflowError?: string;
+    workflowError: string;
   },
 ): void {
-  const { loader, toolNames, disallowedSet, extNames, narrowing, readmitToolNames, nestedCallGate } = ctx;
-  const workflowError = ctx.workflowError ?? NESTED_WORKFLOW_ERROR;
+  const { loader, toolNames, disallowedSet, extNames, narrowing, readmitToolNames, nestedCallGate, workflowError } = ctx;
 
   // The names allowed right now. Mirrors the `ext:` opt-in flip: when any `ext:`
   // selector is present, extension tools become an explicit allowlist — a loaded
@@ -389,8 +397,14 @@ export function installExtensionToolScope(
   };
 }
 
-/** Set once the child's tool scope is installed; until then the gate admits everything. */
-type NestedCallGate = { allows?: (name: string) => boolean };
+/**
+ * Set once the child's tool scope (and, while planning, its Plan check) is
+ * installed; until then the gate admits everything.
+ */
+type NestedCallGate = {
+  allows?: (name: string) => boolean;
+  planReason?: (toolName: string, input: unknown, cwd: string) => string | undefined;
+};
 
 /**
  * Inline extension that applies the subagent's tool scope to calls a tool makes
@@ -406,11 +420,13 @@ function scopeGateExtension(gate: NestedCallGate): InlineExtension {
     name: SCOPE_GATE_NAME,
     hidden: true,
     factory: (ext) => {
-      ext.on("tool_call", (event) =>
-        gate.allows?.(event.toolName) === false
-          ? { block: true, reason: `Tool "${event.toolName}" is not available to this subagent.` }
-          : undefined,
-      );
+      ext.on("tool_call", (event, ctx) => {
+        if (gate.allows?.(event.toolName) === false) {
+          return { block: true, reason: `Tool "${event.toolName}" is not available to this subagent.` };
+        }
+        const reason = gate.planReason?.(event.toolName, event.input, ctx.cwd);
+        return reason === undefined ? undefined : { block: true, reason };
+      });
     },
   };
 }
@@ -474,37 +490,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 +504,17 @@ export interface AssistantMessageInfo {
 }
 
 export interface RunOptions {
+  /** Backoff before each stale-ctx re-prompt (#145); defaults to 1s, 3s, 9s. `[]` disables recovery. */
+  staleRetryDelaysMs?: readonly number[];
+  /** Clock that times the stale-ctx backoff; the manager passes its own. Defaults to native timers. */
+  clock?: Clock;
   /** 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 +548,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 +585,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;
   /**
@@ -618,6 +613,11 @@ export interface RunOptions {
    * fails at the call that wrote it rather than inside the child.
    */
   structuredOutput?: CompiledSchema;
+  /**
+   * The Plan restriction for this child's runs (#437). Installed once on the
+   * session and read per call; the manager sets `policy` per run.
+   */
+  planGate?: PlanGate;
   /** Runtime bridge for opt-in child-safe nested delegation. */
   nestedRuntime?: {
     manager: NestedAgentManager;
@@ -664,28 +664,40 @@ export interface RunResult {
  */
 function collectResponseText(session: AgentSession) {
   let text = "";
+  let laterTool = false;
+  let previousText = "";
+  let previousLaterTool = false;
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
     // message_start also fires for user and toolResult messages — resetting on
     // those would wipe assistant text already collected. Reset only when a new
     // ASSISTANT message begins, so getText() is the last assistant message's text.
     if (event.type === "message_start" && event.message.role === "assistant") {
+      if (text.trim()) {
+        previousText = text;
+        previousLaterTool = laterTool;
+      }
       text = "";
+      laterTool = false;
     }
     if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
       text += event.assistantMessageEvent.delta;
     }
+    if (event.type === "tool_execution_end") {
+      if (text.trim()) laterTool = true;
+      else if (previousText.trim()) previousLaterTool = true;
+    }
   });
-  return { getText: () => text, unsubscribe };
+  return { getText: () => text, getPreviousText: () => previousText, hasLaterTool: () => text.trim() ? laterTool : previousLaterTool, unsubscribe };
 }
 
 /**
  * Get the last non-empty assistant text produced during THIS invocation.
  * `startIndex` is the message count captured before the prompt, so the walk-back
  * never crosses into a previous turn: on a resume whose new turn failed empty,
- * this returns "" instead of the prior turn's answer (#144). Defaults to 0 (a
- * fresh spawn, where the whole history belongs to this run).
+ * this returns "" instead of the prior turn's answer (#144). A fresh spawn passes
+ * 0, since the whole history belongs to that run.
  */
-function getLastAssistantText(session: AgentSession, startIndex = 0): string {
+function getLastAssistantText(session: AgentSession, startIndex: number): string {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
@@ -721,7 +733,7 @@ export function forwardModelCall(event: AgentSessionEvent, emit: (event: ModelCa
  * no tool call pending, and a stop that was not an abort, a tool-use handoff or
  * a token-limit cut. Anything else is a teaser or a cut-off report.
  */
-function endedWithReport(session: AgentSession, startIndex = 0): boolean {
+function endedWithReport(session: AgentSession, startIndex: number): boolean {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
@@ -786,7 +798,7 @@ async function forceFinalReport(session: AgentSession, startIndex: number, signa
  * Bounded by `startIndex` (like the text fallback) so a resume that produced no
  * assistant message of its own never inherits a PRIOR turn's stop reason.
  */
-function finalTurnError(session: AgentSession, startIndex = 0): string | undefined {
+function finalTurnError(session: AgentSession, startIndex: number): string | undefined {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
@@ -801,6 +813,111 @@ 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.";
+
+/**
+ * Resolve after `ms`, or as soon as `signal` aborts. Never rejects.
+ */
+function sleep(ms: number, signal: AbortSignal | undefined, clock: Clock): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const done = () => {
+      timer.cancel();
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = clock.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.
+ *
+ * Kept for stale-ctx failures that routing no longer causes itself: core now hands
+ * `route` the requesting session's context (#581), so another session's reload or
+ * disposal cannot invalidate this request, but an extension callback that captured
+ * a dead ctx can still throw, and only this turns that into a bounded retry and a report.
+ */
+export async function retryStaleCtx(
+  session: AgentSession,
+  startIndex: number,
+  signal: AbortSignal | undefined,
+  delays: readonly number[] = STALE_CTX_RETRY_DELAYS_MS,
+  clock: Clock = realClock,
+): Promise<void> {
+  for (const delay of delays) {
+    if (!isStaleCtxError(finalTurnError(session, startIndex))) return;
+    await sleep(delay, signal, clock);
+    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;
+}
+
+/** Bounded activity only: tool arguments, results and unknown names are never copied. */
+function partialProgress(session: AgentSession, startIndex: number): string {
+  const calls: string[] = [];
+  for (let i = session.messages.length - 1; i >= startIndex && calls.length < 5; i--) {
+    const msg = session.messages[i];
+    if (msg.role !== "toolResult") continue;
+    const name = BUILTIN_TOOL_NAMES.includes(msg.toolName) ? msg.toolName : "other tool";
+    calls.unshift(`${name} (${msg.isError ? "failed" : "completed"})`);
+  }
+  return calls.length ? `Latest activity: ${calls.join(", ")}.` : "";
+}
+
+/** Mark prose as earlier progress when subsequent tool results exist. */
+function failureText(session: AgentSession, startIndex: number, text: string, partial: string, laterTool: boolean, streamed: boolean): string {
+  if (!text) return partial;
+  if (streamed) return laterTool ? `Earlier progress:\n${text}\n\n${partial}` : text;
+  let hasLaterResult = false;
+  for (let i = session.messages.length - 1; i >= startIndex; i--) {
+    const msg = session.messages[i];
+    if (msg.role === "assistant" && extractText(msg.content).trim() === text) break;
+    if (msg.role === "toolResult") hasLaterResult = true;
+  }
+  return hasLaterResult ? `Earlier progress:\n${text}\n\n${partial}` : text;
+}
+
+/**
+ * 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: ${error}`,
+    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 +940,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 +990,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 +1005,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);
 }
@@ -914,11 +1031,20 @@ export async function runAgent(
 
   // Get parent system prompt for append-mode agents
   const parentSystemPrompt = ctx.getSystemPrompt();
+  const agentDir = resolveAgentDir(options.homeDir);
+  // The child inherits the parent's project-trust decision. Pi otherwise defaults
+  // SettingsManager to trusted, which could load project MCP configuration; resolve
+  // it before resource loading so untrusted skills cannot shadow trusted resources.
+  const projectTrusted = options.configCwd !== undefined && options.configProjectTrusted !== undefined
+    ? options.configProjectTrusted
+    : ctx.isProjectTrusted();
+  const settingsManager = SettingsManager.create(configCwd, agentDir, { projectTrusted });
 
   // Build prompt extras (memory, skill preloading)
   const extras: PromptExtras = {};
   if (options.worktreeBase) extras.worktreeBase = options.worktreeBase;
   if (options.workflow && !options.structuredOutput) extras.workflowChild = true;
+  if (options.planGate?.policy) extras.planMode = true;
 
   // Resolved here, not by each caller: mention and RPC spawns pass no `isolated`,
   // and the agent file's value must hold on every path.
@@ -932,7 +1058,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 = await preloadSkills(skills, configCwd, { agentDir, settingsManager, homeDir: options.homeDir });
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -952,12 +1078,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);
     }
   }
 
@@ -971,10 +1097,13 @@ export async function runAgent(
     ? options.nestedRuntime
     : undefined;
   // One answer for the prompt and the workflow refusal: does this child end up with `Agent`?
-  const agentAvailable = Boolean(
+  // An allowlist that resolves to no enabled agent leaves Agent nothing to
+  // accept; omit the tools rather than advertise "none" as a type (#331, #333).
+  const nestingPossible = Boolean(
     agentConfig?.allowedSubagents && nestedRuntime && !isolated
-      && !agentConfig.disallowedTools?.includes("Agent"),
+      && hasNestableTypes(agentConfig.allowedSubagents, { homeDir: options.homeDir, configCwd, projectTrusted }),
   );
+  const agentAvailable = nestingPossible && !agentConfig?.disallowedTools?.includes("Agent");
   if (agentConfig?.allowedSubagents && !agentAvailable) extras.nestingDisabled = true;
 
   // Build system prompt from agent config
@@ -993,8 +1122,6 @@ 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();
-
   // Extension loading:
   // - true  → all default-discovered extensions
   // - false → none (noExtensions)
@@ -1018,7 +1145,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.
@@ -1052,14 +1179,6 @@ export async function runAgent(
           };
         };
 
-  // The child inherits the parent's project-trust decision. pi's SettingsManager
-  // defaults to trusted, so without this a subagent in a project the user declined
-  // to trust would load its `.pi` extensions and settings, and pi's built-in MCP
-  // would start the stdio servers in its `.pi/mcp.json`.
-  const projectTrusted = options.configCwd !== undefined && options.configProjectTrusted !== undefined
-    ? options.configProjectTrusted
-    : ctx.isProjectTrusted();
-  const settingsManager = SettingsManager.create(configCwd, agentDir, { projectTrusted });
   // That trust covers the parent's project (`configCwd`), not a directory a spawn
   // was sent into. The session answers `ctx.isProjectTrusted()` for its own cwd,
   // which pi's MCP uses to read `<cwd>/.pi/mcp.json` — so a cross-directory session
@@ -1073,7 +1192,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,8 +1224,8 @@ export async function runAgent(
     noContextFiles: true,
     systemPromptOverride: () => systemPrompt,
     appendSystemPromptOverride: () => [],
-  });
-  await runInChildSessionContext(() => loader.reload());
+  }, options.homeDir);
+  await bindChildResourceLoader(loader).reload();
 
   // Plain entries in `tools:` are expected to be built-in names (extension tools
   // go through `ext:`), so an unknown name there is unambiguously a typo. Previously
@@ -1177,10 +1296,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;
@@ -1193,7 +1310,7 @@ export async function runAgent(
   // set `allowed_subagents` and a nestedRuntime was provided — and never when
   // isolated. Their names collide with EXCLUDED_TOOL_NAMES by design, so the
   // scoping below re-admits them explicitly (registry deny + active-set narrow).
-  const nestedTools = agentConfig?.allowedSubagents && nestedRuntime && !isolated
+  const nestedTools = agentConfig?.allowedSubagents && nestedRuntime && nestingPossible
     ? createNestedSubagentTools({
         manager: nestedRuntime.manager,
         pi: options.pi,
@@ -1201,6 +1318,7 @@ export async function runAgent(
         depth: nestedRuntime.depth,
         maxSubagentDepth: effectiveMaxDepth,
         allowedSubagents: agentConfig.allowedSubagents,
+        homeDir: options.homeDir,
         configCwd,
         projectTrusted,
       })
@@ -1301,8 +1419,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`.
@@ -1392,6 +1519,21 @@ export async function runAgent(
     });
   }
 
+  // Plan mode (#437): outermost, so a call Plan refuses reaches no other hook.
+  // Read per call, because the manager decides the gate per run (spawn, resume).
+  const planGate = options.planGate;
+  if (planGate) {
+    const planReason = (toolName: string, input: unknown, cwd: string) =>
+      planGateReason(planGate, { toolName, input, cwd }, () => session.getAllTools(), readmitToolNames);
+    nestedCallGate.planReason = planReason;
+    const priorBeforeToolCall = session.agent.beforeToolCall;
+    session.agent.beforeToolCall = async (context, signal) => {
+      const reason = planReason(context.toolCall.name, context.args, effectiveCwd);
+      if (reason !== undefined) return { block: true, reason };
+      return priorBeforeToolCall?.(context, signal);
+    };
+  }
+
   options.onSessionCreated?.(session);
 
   const run = observeRun(session, { ...options, maxTurns: resolveEffectiveMaxTurns(type, options.maxTurns) });
@@ -1417,12 +1559,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, options.clock);
 
     // 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 +1579,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 +1589,8 @@ export async function runAgent(
     cleanupAbort();
   }
 
-  const responseText = collector.getText().trim() || getLastAssistantText(session, startLen);
+  const stale = staleCtxOutcome(session, startLen);
+  const text = collector.getText().trim() || getLastAssistantText(session, startLen);
   // 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.
@@ -1455,12 +1599,14 @@ export async function runAgent(
       ? `The agent's StructuredOutput call did not match the required schema: ${structuredCapture.lastError}`
       : "The agent did not report its answer through StructuredOutput."
     : undefined;
+  const failure = stale?.failure ?? finalTurnError(session, startLen) ?? structuredFailure;
+  const streamed = collector.getText().trim() || collector.getPreviousText().trim();
   return {
-    responseText,
+    responseText: failure ? failureText(session, startLen, streamed || text, stale?.partial ?? partialProgress(session, startLen), collector.hasLaterTool(), Boolean(streamed)) : text,
     session,
     aborted: run.aborted,
     steered: run.steered,
-    failure: finalTurnError(session, startLen) ?? structuredFailure,
+    failure,
     ...(structuredCapture?.json !== undefined ? { structuredJson: structuredCapture.json } : {}),
     ...(structuredRetried ? { structuredRetried } : {}),
   };
@@ -1475,7 +1621,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" | "clock" | "maxTurns" | "onTurnEnd" | "onTextDelta" | "onModelCall" | "onToolActivity" | "onAssistantUsage" | "onCompaction" | "signal"> & {
     /** The agent's type, for its own `max_turns`. */
     type: SubagentType;
   },
@@ -1491,7 +1637,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, options.clock);
+    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 +1648,13 @@ export async function resumeAgent(
     cleanupAbort();
   }
 
+  const stale = staleCtxOutcome(session, startLen);
+  const failure = stale?.failure ?? finalTurnError(session, startLen);
+  const text = collector.getText().trim() || getLastAssistantText(session, startLen);
+  const streamed = collector.getText().trim() || collector.getPreviousText().trim();
   return {
-    text: collector.getText().trim() || getLastAssistantText(session, startLen),
-    failure: finalTurnError(session, startLen),
+    text: failure ? failureText(session, startLen, streamed || text, stale?.partial ?? partialProgress(session, startLen), collector.hasLaterTool(), Boolean(streamed)) : text,
+    failure,
     aborted: run.aborted,
     steered: run.steered,
   };