@cad0p/pi-subagents-tintinweb 0.14.2 → 0.22.0

package/src/agent-runner.ts

@@ -5,26 +5,34 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import type { Model } from "@earendil-works/pi-ai";
-import type { ExtensionContext, LoadExtensionsResult } from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage, Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext, LoadExtensionsResult, ScopedModel, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import {
   type AgentSession,
   type AgentSessionEvent,
   createAgentSession,
+  createCodemodeExtension,
+  createMcpExtension,
+  createToolSearchExtension,
   DefaultResourceLoader,
   type ExtensionAPI,
   getAgentDir,
+  type InlineExtension,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getBuiltinToolSnippets, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
+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 { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
-import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
+import { type ModelRegistry as ModelLookupRegistry, resolveModel } from "./model-resolver.js";
+import { createNestedSubagentTools, getMaxSubagentDepth, type NestedAgentManager } from "./nested-tools.js";
+import { buildAgentPrompt, type PromptExtras, retargetToolsSection } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
-import type { SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentConfig, SubagentType, ThinkingLevel } from "./types.js";
+import type { LifetimeUsage } from "./usage.js";
 
 /**
  * Tool names registered by THIS extension. Single source of truth so the
@@ -76,6 +84,8 @@ export function extensionCanonicalName(extPath: string): string {
  * every co-located file to `pi-subagents-tintinweb`.
  */
 function extensionPackageName(extPath: string): string | undefined {
+  // `builtin:<name>` names no file; climbing from it would read the process cwd's manifest.
+  if (extPath.startsWith("builtin:")) return undefined;
   const entry = resolve(extPath);
   let dir = dirname(extPath);
   for (;;) {
@@ -197,6 +207,51 @@ export function parseExtSelectors(entries: string[]): {
   return { extNames, narrowing };
 }
 
+/**
+ * Mirror of pi's `createToolNameMatcher` (mcp-servers.js): exact names plus `*`
+ * globs. `disallowed_tools` is handed to pi verbatim, so pi removes a wildcard
+ * match from the registry — this side has to agree, or the prompt advertises a
+ * tool pi already dropped and the scope gate would let it through.
+ */
+function toolNameMatcher(entries: readonly string[]): (name: string) => boolean {
+  const exact = new Set(entries.filter((entry) => !entry.includes("*")));
+  const patterns = entries
+    .filter((entry) => entry.includes("*"))
+    .map((entry) => new RegExp(`^${entry.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`));
+  return (name) => exact.has(name) || patterns.some((pattern) => pattern.test(name));
+}
+
+/** Set once the child's tool scope is known; until then the gate admits everything. */
+type NestedCallGate = { allows?: (name: string) => boolean };
+
+/** Name of the inline scope-gate extension; its loader path is `<inline:${SCOPE_GATE_NAME}>`. */
+const SCOPE_GATE_NAME = "pi-subagents-scope";
+
+/**
+ * Inline extension that applies the subagent's tool scope to every tool call, wherever
+ * it comes from.
+ *
+ * pi gates registration by the session's `tools:` allowlist, but keeps a registered
+ * MCP tool callable through `ctx.executeTool()` whether or not the agent selected it —
+ * so a codemode script could reach a tool outside its scope. Those nested calls run
+ * past extensions' `tool_call` handlers only, never `agent.beforeToolCall`, and a
+ * `tool_search`-activated tool reaches the model the same way. One `tool_call` handler
+ * covers both.
+ */
+function scopeGateExtension(gate: NestedCallGate): InlineExtension {
+  return {
+    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,
+      );
+    },
+  };
+}
+
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined;
 
@@ -250,6 +305,43 @@ function resolveDefaultModel(
   return parentModel;
 }
 
+/**
+ * Resolve the child session's model scope from `scoped_models` frontmatter.
+ *
+ * undefined/true → inherit the parent session's resolved scope, so in-session
+ * extensions that read `ctx.scopedModels` — notably pi-fallback-provider's
+ * settle-boundary fallback — work inside subagents too. false → no scope;
+ * string[] → an explicit replacement list resolved like `model:` (exact, then
+ * fuzzy, then the same model under another provider). Unresolved entries are
+ * skipped with a warning; they never fail the spawn.
+ */
+export function resolveScopedModels(
+  configured: true | string[] | false | undefined,
+  parentScoped: readonly ScopedModel[] | undefined,
+  registry: ModelLookupRegistry,
+  warn: (message: string) => void = () => {},
+): ScopedModel[] {
+  if (configured === undefined || configured === true) {
+    return parentScoped ? [...parentScoped] : [];
+  }
+  if (configured === false) return [];
+
+  const resolved: ScopedModel[] = [];
+  const seen = new Set<string>();
+  for (const entry of configured) {
+    const model = resolveModel(entry, registry);
+    if (typeof model === "string") {
+      warn(`scoped_models: "${entry}" did not resolve — skipping`);
+      continue;
+    }
+    const key = `${model.provider}/${model.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    resolved.push({ model });
+  }
+  return resolved;
+}
+
 /** Info about a tool event in the subagent. */
 export interface ToolActivity {
   type: "start" | "end";
@@ -289,6 +381,14 @@ export interface RunOptions {
    * parent's repo, so config resolving inside it is correct.)
    */
   configCwd?: string;
+  /**
+   * The agent config to run, when the caller already resolved it from its own
+   * registry. A nested spawn resolves agents from its branch's config root,
+   * which is not necessarily what the process-global registry holds — passing
+   * the resolved config keeps the run from silently falling back to the
+   * unknown-type default (general-purpose, every tool).
+   */
+  agentConfig?: AgentConfig;
   /** Called on tool start/end with activity info. */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -300,13 +400,30 @@ export interface RunOptions {
    * Called once per assistant message_end with that message's usage delta.
    * Lets callers maintain a lifetime accumulator that survives compaction
    * (which replaces session.state.messages and resets stats-derived sums).
+   *
+   * `cost` is pi's own `usage.cost.total` for that message — priced from the
+   * model's rates, so it is 0 (not missing) for a model pi has no pricing for.
+   * We never price anything ourselves; every dollar figure this extension shows
+   * or reports traces back to this field.
    */
-  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;
+  /**
+   * Runtime bridge for opt-in nested delegation. Present only for agents the
+   * manager spawned (a top-level run has no parent to scope children to).
+   */
+  nestedRuntime?: {
+    manager: NestedAgentManager;
+    parentAgentId: string;
+    /** This agent's own depth; its children spawn at depth + 1. */
+    depth: number;
+    /** Branch cap inherited from the spawn, else the project setting. */
+    maxSubagentDepth?: number;
+  };
 }
 
 export interface RunResult {
@@ -329,11 +446,13 @@ export interface RunResult {
 }
 
 /**
- * Subscribe to a session and collect the last assistant message text.
- * Returns an object with a `getText()` getter and an `unsubscribe` function.
+ * Subscribe to a session and collect the last assistant message text, plus the
+ * last assistant message itself as reported by its `message_end` event.
+ * Returns `getText()` and `getLastAssistant()` getters and an `unsubscribe` function.
  */
 function collectResponseText(session: AgentSession) {
   let text = "";
+  let lastAssistant: AssistantMessage | undefined;
   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
@@ -344,8 +463,11 @@ function collectResponseText(session: AgentSession) {
     if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
       text += event.assistantMessageEvent.delta;
     }
+    if (event.type === "message_end" && event.message.role === "assistant") {
+      lastAssistant = event.message;
+    }
   });
-  return { getText: () => text, unsubscribe };
+  return { getText: () => text, getLastAssistant: () => lastAssistant, unsubscribe };
 }
 
 /**
@@ -376,20 +498,31 @@ function getLastAssistantText(session: AgentSession, startIndex = 0): string {
  * Everything else completes: a clean "stop"/"toolUse" final, and — crucially — a
  * "length" stop that DID produce text (a legitimate truncated-but-useful answer).
  * "aborted" is handled by the manager's abort flag / "stopped" guard, not here.
- * 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.
+ * `observed` is the final assistant message seen via `message_end` during this
+ * invocation, and it is authoritative: a context_edit can hide the failed turn
+ * from session.messages, and a walk-back would then report an older turn's
+ * success. The session.messages walk is only a fallback for runs that emitted no
+ * assistant message_end. Bounded by `startIndex` (like the text fallback) so a
+ * resume with no assistant message of its own never inherits a PRIOR turn's stop
+ * reason.
  */
-function finalTurnError(session: AgentSession, startIndex = 0): string | undefined {
-  for (let i = session.messages.length - 1; i >= startIndex; i--) {
-    const msg = session.messages[i];
-    if (msg.role !== "assistant") continue;
-    if (msg.stopReason === "error") {
-      return (msg as { errorMessage?: string }).errorMessage?.trim() || "provider error with no output";
-    }
-    if (msg.stopReason === "length" && !extractText(msg.content).trim()) {
-      return "run hit the output token limit before producing any text";
+function finalTurnError(session: AgentSession, startIndex = 0, observed?: AssistantMessage): string | undefined {
+  let final = observed;
+  if (!final) {
+    for (let i = session.messages.length - 1; i >= startIndex; i--) {
+      const msg = session.messages[i];
+      if (msg.role === "assistant") {
+        final = msg;
+        break;
+      }
     }
-    return undefined;
+  }
+  if (!final) return undefined;
+  if (final.stopReason === "error") {
+    return final.errorMessage?.trim() || "provider error with no output";
+  }
+  if (final.stopReason === "length" && !extractText(final.content).trim()) {
+    return "run hit the output token limit before producing any text";
   }
   return undefined;
 }
@@ -401,6 +534,12 @@ function finalTurnError(session: AgentSession, startIndex = 0): string | undefin
 function forwardAbortSignal(session: AgentSession, signal?: AbortSignal): () => void {
   if (!signal) return () => {};
   const onAbort = () => session.abort();
+  // An already-aborted signal never fires its event, so abort now instead of
+  // letting the child run on with a signal its owner believes is dead.
+  if (signal.aborted) {
+    onAbort();
+    return () => {};
+  }
   signal.addEventListener("abort", onAbort, { once: true });
   return () => signal.removeEventListener("abort", onAbort);
 }
@@ -418,8 +557,23 @@ export async function runAgent(
   prompt: string,
   options: RunOptions,
 ): Promise<RunResult> {
-  const config = getConfig(type);
-  const agentConfig = getAgentConfig(type);
+  const resolvedConfig = options.agentConfig;
+  const agentConfig = resolvedConfig ?? getAgentConfig(type);
+  // Every derived field comes from the same config: a nested spawn resolves the
+  // agent from its branch's config root, and re-deriving tools or extension
+  // policy from the process-global registry would run a different agent than the
+  // one the caller validated (all built-ins, general-purpose's extensions).
+  const config = resolvedConfig
+    ? {
+        displayName: resolvedConfig.displayName ?? resolvedConfig.name,
+        description: resolvedConfig.description,
+        builtinToolNames: resolvedConfig.builtinToolNames ?? [...BUILTIN_TOOL_NAMES],
+        extensions: resolvedConfig.extensions,
+        excludeExtensions: resolvedConfig.excludeExtensions,
+        skills: resolvedConfig.skills,
+        promptMode: resolvedConfig.promptMode,
+      }
+    : getConfig(type);
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
@@ -450,7 +604,7 @@ export async function runAgent(
     }
   }
 
-  let toolNames = getToolNamesForType(type);
+  let toolNames = resolvedConfig ? [...config.builtinToolNames] : getToolNamesForType(type);
 
   // Persistent memory: detect write capability and branch accordingly.
   // Account for disallowedTools — a tool in the base set but on the denylist is not truly available.
@@ -512,6 +666,9 @@ export async function runAgent(
     options.isolated ? [] : (agentConfig?.extSelectors ?? []),
   );
   const noExtensions = extensions === false;
+  const disallowed = agentConfig?.disallowedTools?.length
+    ? toolNameMatcher(agentConfig.disallowedTools)
+    : undefined;
 
   const extensionsSpec = Array.isArray(extensions)
     ? parseExtensionsSpec(extensions, configCwd)
@@ -540,6 +697,7 @@ export async function runAgent(
           return {
             ...base,
             extensions: base.extensions.filter((e) => {
+              if (e.path === `<inline:${SCOPE_GATE_NAME}>`) return true; // ours, not the agent's
               const canons = extensionCanonicalNames(e.path);
               if (canons.some((n) => excludeNames.has(n))) return false; // exclude wins
               return loadAll || canons.some((n) => keepNames.has(n));
@@ -547,7 +705,169 @@ export async function runAgent(
           };
         };
 
-  const loader = new DefaultResourceLoader({
+  // 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 = 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 keeps the
+  // parent project's settings but reports its cwd as untrusted. The loader keeps the
+  // trusted manager: it loads the parent project's extensions.
+  const sessionSettingsManager =
+    resolve(effectiveCwd) === resolve(configCwd)
+      ? settingsManager
+      : Object.assign(SettingsManager.create(configCwd, agentDir, { projectTrusted }), {
+          isProjectTrusted: () => false,
+        });
+  const nestedCallGate: NestedCallGate = {};
+
+  // Nested delegation tools (opt-in, ownership-scoped). Empty unless the agent
+  // set `allowed_subagents`, the manager handed down a nestedRuntime, and this
+  // agent sits below the branch cap. Their names collide with EXCLUDED_TOOL_NAMES
+  // by design, so the scoping below re-admits them explicitly.
+  const inheritedMaxDepth = options.nestedRuntime?.maxSubagentDepth ?? getMaxSubagentDepth();
+  // A per-agent cap may only tighten the inherited one — an agent can never
+  // grant itself more nesting room than the project allows.
+  const effectiveMaxDepth = agentConfig?.maxSubagentDepth === undefined
+    ? inheritedMaxDepth
+    : Math.min(inheritedMaxDepth, agentConfig.maxSubagentDepth);
+  // At (or past) the cap this agent can never spawn, so it can never own a child
+  // to fetch from or steer either — inject nothing rather than four tools whose
+  // every call is an error. This is also what makes maxSubagentDepth 0/1 mean
+  // "nesting off" instead of "nesting always fails".
+  const nestedRuntime = options.nestedRuntime && options.nestedRuntime.depth < effectiveMaxDepth
+    ? options.nestedRuntime
+    : undefined;
+  const nestedTools = agentConfig?.allowedSubagents && nestedRuntime && !options.isolated
+    ? createNestedSubagentTools({
+        manager: nestedRuntime.manager,
+        pi: options.pi,
+        parentAgentId: nestedRuntime.parentAgentId,
+        depth: nestedRuntime.depth,
+        maxSubagentDepth: effectiveMaxDepth,
+        allowedSubagents: agentConfig.allowedSubagents,
+        configCwd,
+      })
+    : [];
+  const nestedToolNames = new Set(nestedTools.map((tool) => tool.name));
+
+  // Extension-registered tools the subagent may use, keyed by name, read from the
+  // loader's LIVE extension tool maps: extensions register tools long after load
+  // (pi's MCP registers a server's tools once it connects) and `registerTool` writes
+  // into the very maps this reads. The prompt override and the allowlist below take a
+  // snapshot; the scope gate re-derives it per call, so a late tool is in scope from
+  // the moment it exists.
+  //
+  // Opt-in flip: when any `ext:` selector is present, extension tools become an
+  // explicit allowlist — a loaded extension not named by a selector contributes
+  // no tools (its handlers still ran), and `ext:foo/bar` narrows `foo` to `bar`.
+  // Tools the parent session currently declares. A `defaultActive: false` tool —
+  // pi's `codemode` and `tool_search`, and anything an extension registers dormant —
+  // is activated in the child only when the parent has it active or this agent names
+  // its extension. Otherwise every subagent would carry codemode's tool spec, and the
+  // capability that comes with it, for a user who never turned it on: "as in the main
+  // session" has to mean the main session's actual tool set, not every tool that
+  // happens to be loaded. Read per run: the parent's set changes with `--tools` and
+  // with whatever `tool_search` activated.
+  const parentActiveTools = new Set(options.pi.getActiveTools?.() ?? []);
+  // Tools an `ext:` selector names explicitly. Naming an extension is the agent
+  // saying it wants its tools, which is the same consent `--tools` gives pi.
+  const explicitlySelected = new Set<string>();
+  const scopedExtensionTools = (loaded: LoadExtensionsResult): Map<string, ToolDefinition> => {
+    const tools = new Map<string, ToolDefinition>();
+    if (noExtensions) return tools;
+    const optInActive = extNames.size > 0;
+    for (const extension of loaded.extensions) {
+      const canons = extensionCanonicalNames(extension.path);
+      if (optInActive && !canons.some((c) => extNames.has(c))) continue;
+      // First alias that carries a narrowing set — a user won't narrow one
+      // extension under two different names, so first-match is correct.
+      const narrowed = canons.map((c) => narrowing.get(c)).find(Boolean);
+      for (const [toolName, tool] of extension.tools) {
+        if (narrowed && !narrowed.has(toolName)) continue;
+        tools.set(toolName, tool.definition);
+        // Every tool reaching this line belongs to an extension the agent named,
+        // so it is selected on purpose rather than merely loaded.
+        if (optInActive) explicitlySelected.add(toolName);
+      }
+    }
+    return tools;
+  };
+
+  // The master tool allowlist applied at session construction. pi-mono's
+  // `allowedToolNames` gates registration and activates what it names, so listing the
+  // exact final set here means the session is correctly scoped from the first instant.
+  // Naming a tool is also how pi activates one registered `defaultActive: false` (its
+  // `codemode` and `tool_search` among them), which is what a subagent wants for its
+  // own scope.
+  const scopedToolNames = (tools: Map<string, ToolDefinition>): string[] =>
+    [...toolNames, ...tools.keys(), ...nestedToolNames].filter((t) => {
+      // The orchestration tools stay stripped from every subagent — except the
+      // nested ones this agent opted into, which carry the same names on purpose.
+      if ((EXCLUDED_TOOL_NAMES.includes(t) && !nestedToolNames.has(t)) || disallowed?.(t)) return false;
+      // Built-ins carry no definition here and are always declared; the rule is
+      // about extension tools pi would leave dormant.
+      if (tools.get(t)?.defaultActive !== false) return true;
+      return explicitlySelected.has(t) || parentActiveTools.has(t);
+    });
+
+  // Names pi would DECLARE to the model: `direct`/`model-only` exposure only. A
+  // `codemode`/`deferred` tool (pi's MCP server tools by default) stays reachable
+  // through codemode and `tool_search` without being advertised.
+  const declarableTools = (tools: Map<string, ToolDefinition>): string[] =>
+    scopedToolNames(tools).filter((name) => {
+      const exposure = tools.get(name)?.exposure ?? "direct";
+      return exposure === "direct" || exposure === "model-only";
+    });
+
+  /**
+   * The child's prompt, with the `<tools>` block it inherits from the parent
+   * retargeted at the tools it actually declares — see `retargetToolsSection`.
+   */
+  const childPrompt = (loaded: LoadExtensionsResult): string => {
+    const tools = scopedExtensionTools(loaded);
+    // Built-ins first: the inherited block only describes the parent's *active*
+    // tools, so an agent whose `tools:` reaches beyond that set would otherwise
+    // be advertised fewer tools than it declares. Child definitions win on a
+    // name both have.
+    const snippets: Record<string, string> = { ...getBuiltinToolSnippets() };
+    for (const [name, definition] of tools) {
+      if (definition.promptSnippet) snippets[name] = definition.promptSnippet;
+    }
+    // Injected nested tools are not extension tools, so their snippets have to
+    // be added here — otherwise the child is handed Agent/get_subagent_result
+    // and told nothing about them.
+    for (const definition of nestedTools) {
+      if (definition.promptSnippet) snippets[definition.name] = definition.promptSnippet;
+    }
+    return retargetToolsSection(systemPrompt, declarableTools(tools), snippets);
+  };
+
+  const loader: DefaultResourceLoader = new DefaultResourceLoader({
+    settingsManager,
+    // pi's CLI hands its built-in extensions to the loader it builds; this one started
+    // with none, so a `builtin:<name>` entry in `extensions:` resolved to nothing and
+    // pi's MCP, codemode, and tool search were out of reach for every subagent. As
+    // `builtin:` resources they load as in the main session — on by default, disabled by
+    // `-builtin:<name>` in settings — and the per-agent allowlist filters them like any
+    // other extension. Fresh factories per spawn: MCP state lives in the closure.
+    extensionFactories: [
+      { name: "codemode", factory: createCodemodeExtension(), builtin: true, replaceable: true },
+      { name: "tool-search", factory: createToolSearchExtension(), builtin: true, replaceable: true },
+      { name: "mcp", factory: createMcpExtension(), builtin: true, replaceable: true },
+      // Under `noExtensions` the static allowlist gates the registry itself.
+      ...(noExtensions ? [] : [scopeGateExtension(nestedCallGate)]),
+    ],
+    // Mirrors pi's CLI: `--no-mcp` keeps MCP out of subagents too, and `--no-extensions`
+    // keeps all the built-ins out. Discovered extensions still follow `extensions:`.
+    disabledBuiltinExtensions: process.argv.some((a) => a === "--no-extensions" || a === "-ne")
+      ? ["codemode", "tool-search", "mcp"]
+      : process.argv.includes("--no-mcp")
+        ? ["mcp"]
+        : undefined,
     cwd: configCwd,
     agentDir,
     noExtensions,
@@ -557,10 +877,15 @@ export async function runAgent(
     noPromptTemplates: true,
     noThemes: true,
     noContextFiles: true,
-    systemPromptOverride: () => systemPrompt,
+    // pi reads this once, at the end of `reload()`, with the extension set already
+    // filtered — so the prompt is retargeted at what the child really loads.
+    systemPromptOverride: () => childPrompt(loader.getExtensions()),
     appendSystemPromptOverride: () => [],
   });
-  await loader.reload();
+  // Marked as a child session: the extension factory runs inside reload(), and a
+  // subagent activation must not register the parent-facing tools (see
+  // child-context.ts).
+  await runInChildSessionContext(() => 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
@@ -639,78 +964,98 @@ export async function runAgent(
   // Resolve thinking level: explicit option > agent config > undefined (inherit)
   const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
 
-  const disallowedSet = agentConfig?.disallowedTools
-    ? new Set(agentConfig.disallowedTools)
-    : undefined;
-
-  // Enumerate extension-registered tool names from the loaded resource loader.
-  // Extensions populate `extension.tools` during `loader.reload()` and the set
-  // is stable afterwards — `bindExtensions` does not register new tools.
-  //
-  // Opt-in flip: when any `ext:` selector is present, extension tools become an
-  // explicit allowlist — a loaded extension not named by a selector contributes
-  // no tools (its handlers still ran), and `ext:foo/bar` narrows `foo` to `bar`.
-  const extensionToolNames: string[] = [];
-  if (!noExtensions) {
-    const optInActive = extNames.size > 0;
-    for (const extension of loader.getExtensions().extensions) {
-      const canons = extensionCanonicalNames(extension.path);
-      if (optInActive && !canons.some((c) => extNames.has(c))) continue;
-      // First alias that carries a narrowing set — a user won't narrow one
-      // extension under two different names, so first-match is correct.
-      const narrowed = canons.map((c) => narrowing.get(c)).find(Boolean);
-      for (const toolName of extension.tools.keys()) {
-        if (narrowed && !narrowed.has(toolName)) continue;
-        extensionToolNames.push(toolName);
-      }
-    }
+  // Child-session model scope: agent frontmatter override, else inherit the
+  // parent's resolved scope. Isolated agents load no extensions, so the
+  // fallback consumer can never bind — an empty scope is the honest value.
+  const scopedModels = resolveScopedModels(
+    options.isolated ? false : agentConfig?.scopedModels,
+    ctx.scopedModels,
+    ctx.modelRegistry,
+    (message) => options.onToolActivity?.({ type: "end", toolName: `scoped-models-error:${message}` }),
+  );
+  // An explicit list under isolation is silently unreachable — flag it the
+  // same way the loader flags contradictory extensions:/exclude_extensions:.
+  if (options.isolated && Array.isArray(agentConfig?.scopedModels)) {
+    options.onToolActivity?.({
+      type: "end",
+      toolName: `scoped-models-error:scoped_models has no effect for agent "${type}" — isolated agents load no extensions`,
+    });
   }
 
-  // Build the master tool allowlist applied at session construction.
-  // pi-mono's `allowedToolNames` gates BOTH registration and the initial active
-  // set, so listing the exact final set here means the session is correctly
-  // scoped from the first instant — no post-construction narrowing required.
-  const builtinToolNameSet = new Set(toolNames);
-  const allowedTools = [...toolNames, ...extensionToolNames].filter((t) => {
-    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-    if (disallowedSet?.has(t)) return false;
-    if (builtinToolNameSet.has(t)) return true;
-    // Reached only for extension tools. The extension set was already filtered
-    // at the loader (extensionsOverride / noExtensions) and at enumeration
-    // (`ext:` opt-in flip), so any extension tool in `extensionToolNames` is allowed.
-    return !noExtensions;
-  });
+  const extensionTools = scopedExtensionTools(loader.getExtensions());
+  const allowedTools = scopedToolNames(extensionTools);
+  const declaredTools = declarableTools(extensionTools);
+  // The same scope, for calls that skip the allowlist: pi keeps a registered MCP tool
+  // callable through `ctx.executeTool()` (a codemode script) and through `tool_search`
+  // even when the agent never selected it.
+  nestedCallGate.allows = (name) =>
+    ((!EXCLUDED_TOOL_NAMES.includes(name) || nestedToolNames.has(name)) &&
+      !disallowed?.(name) &&
+      (toolNames.includes(name) || nestedToolNames.has(name) || scopedExtensionTools(loader.getExtensions()).has(name)));
 
-  const settingsManager = SettingsManager.create(configCwd, agentDir);
   const configuredSessionDir = resolveConfiguredSessionDir(agentConfig?.sessionDir, effectiveCwd);
   const defaultSessionDir = process.env.PI_CODING_AGENT_SESSION_DIR ?? settingsManager.getSessionDir?.();
-  const sessionManager = agentConfig?.persistSession
-    ? SessionManager.create(effectiveCwd, configuredSessionDir ?? defaultSessionDir)
-    : SessionManager.inMemory(effectiveCwd);
-
-  // Pi 0.80.8 replaced createAgentSession's modelRegistry option with
-  // modelRuntime, but ExtensionContext still exposes only the registry facade.
-  // Pass both so the full supported Pi range retains the parent's providers.
-  const parentModelRuntime = (ctx.modelRegistry as unknown as { runtime?: unknown }).runtime;
-  const sessionOpts: Parameters<typeof createAgentSession>[0] & {
-    modelRegistry: ExtensionContext["modelRegistry"];
-    modelRuntime?: unknown;
-  } = {
+  // A subagent session is ALWAYS written to disk while it runs: a crashed or
+  // killed run must leave a transcript pi's /resume can recover. Retention
+  // after the run settles is the manager's decision (`persist_session`), never a
+  // creation-time one.
+  //
+  // The exception is a host session that is itself in-memory: pi's own
+  // `--no-session`, or any SDK host that built `SessionManager.inMemory`. Its
+  // absence of a session file is the exact signal — an argv scan would miss the
+  // SDK host and let an ephemeral session leave children on disk.
+  // The same path is `parentSession`, which nests the child under its spawner.
+  const parentSession = ctx.sessionManager.getSessionFile();
+  const sessionManager = parentSession === undefined
+    ? SessionManager.inMemory(effectiveCwd)
+    : SessionManager.create(
+        effectiveCwd,
+        configuredSessionDir ?? defaultSessionDir,
+        { parentSession },
+      );
+
+  type AgentSessionOptions = NonNullable<Parameters<typeof createAgentSession>[0]>;
+  // ExtensionContext exposes only the ModelRegistry facade; the runtime it wraps
+  // is what createAgentSession needs to keep extension-registered providers
+  // (test/e2e/isolated-provider.e2e.test.ts guards the private `.runtime` reach).
+  const parentModelRuntime = (
+    ctx.modelRegistry as unknown as { runtime?: AgentSessionOptions["modelRuntime"] }
+  ).runtime;
+  const sessionOpts: AgentSessionOptions = {
     cwd: effectiveCwd,
     agentDir,
     sessionManager,
-    settingsManager,
-    modelRegistry: ctx.modelRegistry,
+    settingsManager: sessionSettingsManager,
     ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime }),
     model,
+    scopedModels,
     tools: allowedTools,
+    // The denylist has to reach pi as well as the allowlist math: MCP tools are
+    // kept registered even when the allowlist does not name them (pi only filters
+    // MCP when the allowlist mentions `mcp__`), so a `disallowed_tools: mcp__…`
+    // entry would otherwise stay registered, listable by `tool_search`, and merely
+    // blocked at call time by the scope gate. Excluding it here removes it from the
+    // registry instead.
+    ...(disallowed && { excludeTools: agentConfig?.disallowedTools }),
+    ...(nestedTools.length > 0 && { customTools: nestedTools }),
     resourceLoader: loader,
   };
   if (thinkingLevel) {
     sessionOpts.thinkingLevel = thinkingLevel;
   }
 
-  const { session } = await createAgentSession(sessionOpts);
+  const { session } = await runInChildSessionContext(() => createAgentSession(sessionOpts));
+
+  // pi activates every tool its allowlist names, `codemode`/`deferred` exposure
+  // included. Those must stay undeclared, as in the main session, so take back the
+  // ones pi would not declare. They stay registered and re-activatable: codemode and
+  // `tool_search` reach them, and the scope gate above still applies.
+  const undeclared = allowedTools.filter((name) => !declaredTools.includes(name));
+  if (undeclared.length > 0) {
+    const keep = new Set(session.getActiveToolNames());
+    for (const name of undeclared) keep.delete(name);
+    session.setActiveToolsByName([...keep]);
+  }
 
   const baseSessionName = agentConfig?.name ?? type;
   session.setSessionName(
@@ -772,6 +1117,8 @@ export async function runAgent(
         input: u.input ?? 0,
         output: u.output ?? 0,
         cacheWrite: u.cacheWrite ?? 0,
+        cacheRead: u.cacheRead ?? 0,
+        cost: u.cost?.total ?? 0,
       });
     }
     if (event.type === "compaction_end" && !event.aborted && event.result) {
@@ -779,9 +1126,6 @@ export async function runAgent(
     }
   });
 
-  const collector = collectResponseText(session);
-  const cleanupAbort = forwardAbortSignal(session, options.signal);
-
   // Build the effective prompt: optionally prepend parent context
   let effectivePrompt = prompt;
   if (options.inheritContext) {
@@ -794,6 +1138,9 @@ export async function runAgent(
   // Boundary for the history fallback: only assistant text produced from here
   // on counts as this run's output (a fresh session, so usually 0).
   const startLen = session.messages.length;
+  // Subscribed after the parent-context build so a throw there cannot leak them.
+  const collector = collectResponseText(session);
+  const cleanupAbort = forwardAbortSignal(session, options.signal);
   try {
     await session.prompt(effectivePrompt);
   } finally {
@@ -803,7 +1150,13 @@ export async function runAgent(
   }
 
   const responseText = collector.getText().trim() || getLastAssistantText(session, startLen);
-  return { responseText, session, aborted, steered: softLimitReached, failure: finalTurnError(session, startLen) };
+  return {
+    responseText,
+    session,
+    aborted,
+    steered: softLimitReached,
+    failure: finalTurnError(session, startLen, collector.getLastAssistant()),
+  };
 }
 
 /**
@@ -814,7 +1167,9 @@ export async function resumeAgent(
   prompt: string,
   options: {
     onToolActivity?: (activity: ToolActivity) => void;
-    onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+    onTextDelta?: (delta: string, fullText: string) => void;
+    onTurnEnd?: (turnCount: number) => void;
+    onAssistantUsage?: (usage: LifetimeUsage) => void;
     onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
     signal?: AbortSignal;
   } = {},
@@ -826,8 +1181,24 @@ export async function resumeAgent(
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);
 
-  const unsubEvents = (options.onToolActivity || options.onAssistantUsage || options.onCompaction)
+  // Per-message bookkeeping mirrors runAgent: reset the accumulated text on
+  // each new message_start and count completed turns, so the resumed run's
+  // streaming/stat readouts are not stale.
+  let currentMessageText = "";
+  let turnCount = 0;
+  const unsubEvents = (options.onToolActivity || options.onTextDelta || options.onTurnEnd || options.onAssistantUsage || options.onCompaction)
     ? session.subscribe((event: AgentSessionEvent) => {
+        if (event.type === "turn_end") {
+          turnCount++;
+          options.onTurnEnd?.(turnCount);
+        }
+        if (event.type === "message_start") {
+          currentMessageText = "";
+        }
+        if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+          currentMessageText += event.assistantMessageEvent.delta;
+          options.onTextDelta?.(event.assistantMessageEvent.delta, currentMessageText);
+        }
         if (event.type === "tool_execution_start") options.onToolActivity?.({ type: "start", toolName: event.toolName });
         if (event.type === "tool_execution_end") options.onToolActivity?.({ type: "end", toolName: event.toolName });
         if (event.type === "message_end" && event.message.role === "assistant") {
@@ -836,6 +1207,8 @@ export async function resumeAgent(
             input: u.input ?? 0,
             output: u.output ?? 0,
             cacheWrite: u.cacheWrite ?? 0,
+            cacheRead: u.cacheRead ?? 0,
+            cost: u.cost?.total ?? 0,
           });
         }
         if (event.type === "compaction_end" && !event.aborted && event.result) {
@@ -854,7 +1227,7 @@ export async function resumeAgent(
 
   return {
     text: collector.getText().trim() || getLastAssistantText(session, startLen),
-    failure: finalTurnError(session, startLen),
+    failure: finalTurnError(session, startLen, collector.getLastAssistant()),
   };
 }