@astralyn/pi 0.87.5 → 0.99.0

package/dist/core/agent-session.js

@@ -1,3 +1,4 @@
+import { createTasksToolDefinition } from "./tools/tasks.js";
 /**
  * AgentSession - Core abstraction for agent lifecycle and session management.
  *
@@ -14,6 +15,7 @@
  */
 import { readFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
+import { runToolCall, } from "@earendil-works/pi-agent-core";
 import { contentText, getCurrentSystemMessage, getSystemMessageText, retryDelayMs } from "@earendil-works/pi-ai";
 import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
 import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
@@ -22,27 +24,28 @@ import { processImage } from "../utils/image-process.js";
 import { sleep } from "../utils/sleep.js";
 import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
-import { BackgroundSession } from "./background/session.js";
 import { executeBashWithOperations } from "./bash-executor.js";
 import { generateBugReportSummary } from "./bug-report.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
-import { ExtensionRunner, STALE_EXTENSION_CONTEXT_MESSAGE, wrapRegisteredTools, } from "./extensions/index.js";
+import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { convertToLlm } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
-import { resolveModelStreamOptions } from "./model-stream-options.js";
+import { NestedToolCallRunner } from "./nested-tool-calls.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { exportSessionToJsonl } from "./session-export.js";
 import { getLatestCompactionEntry, SessionManager, } from "./session-manager.js";
-import { createSyntheticSourceInfo } from "./source-info.js";
+import { BUILTIN_PATH_PREFIX, createSyntheticSourceInfo, isSyntheticPath } from "./source-info.js";
 import { buildSystemPrompt, buildSystemPromptSections, diffSystemPromptSections, normalizeBuildSystemPromptOptions, } from "./system-prompt.js";
+import { TaskSession } from "./tasks/session.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
-import { addUsageToTotals, createUsageTotals, getAccountedUsages } from "./usage-totals.js";
+import { addUsageToTotals, combineUsage, createUsageTotals, getAccountedUsages } from "./usage-totals.js";
+import { findLatestResponse, getBranchSelection, getVirtualModelState, isVirtualModel, VIRTUAL_MODEL_STATE_ENTRY, } from "./virtual-models.js";
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -58,6 +61,9 @@ export function parseSkillBlock(text) {
         userMessage: match[4]?.trim() || undefined,
     };
 }
+// ============================================================================
+// Types
+// ============================================================================
 function withoutDeletedHeaders(headers) {
     return headers
         ? Object.fromEntries(Object.entries(headers).filter((entry) => entry[1] !== null))
@@ -86,8 +92,6 @@ export class AgentSession {
         this._pendingNextTurnMessages = [];
         /** Context-only custom messages queued during a run, flushed once the current turn's tool results are in. */
         this._pendingCustomMessages = [];
-        /** Background completions queued for steering, awaiting the persistence that confirms delivery. */
-        this._queuedBackgroundCompletions = new Map();
         // Compaction state
         this._compactionAbortController = undefined;
         this._autoCompactionAbortController = undefined;
@@ -113,20 +117,30 @@ export class AgentSession {
         this._extensionMode = "print";
         // Tool registry for extension getTools/setTools
         this._toolRegistry = new Map();
+        /** Declared tools whose declarations requests leave out, from `prepareLoadout` hooks. */
+        this._hiddenDeclarations = new Set();
         this._toolDefinitions = new Map();
         this._toolPromptSnippets = new Map();
         this._toolPromptGuidelines = new Map();
         /** Internal handler for agent events - shared by subscribe and reconnect */
         this._handleAgentEvent = async (event) => {
-            // Preserve host delivery identity before extension message_end transforms.
-            // Content/details may be replaced, but a persisted replacement is still an ack.
-            const acknowledgeBackground = event.type === "message_end" ? this._backgroundHost.messageAcknowledgement(event.message) : undefined;
-            // A queued completion is tracked by identity too, for the same reason.
-            const queuedBackgroundCompletion = event.type === "message_start" || event.type === "message_end"
-                ? this._queuedBackgroundCompletions.get(event.message)
-                : undefined;
-            if (event.type === "message_start" && queuedBackgroundCompletion)
-                queuedBackgroundCompletion.drained = true;
+            if (event.type === "message_start")
+                this._tasksHost.delivery.messageStarted(event.message);
+            // Record the calls a tool made through ctx.executeTool() and their usage on its result message.
+            if (this._nestedToolCalls) {
+                if (event.type === "message_start" && event.message.role === "toolResult") {
+                    const message = event.message;
+                    const summary = this._nestedToolCalls.takeRecord(message.toolCallId);
+                    if (summary?.calls)
+                        message.nestedCalls = summary.calls;
+                    if (summary?.usage) {
+                        message.usage = message.usage ? combineUsage(message.usage, summary.usage) : summary.usage;
+                    }
+                }
+                else if (event.type === "agent_end") {
+                    this._nestedToolCalls.clear();
+                }
+            }
             // When a user message starts, check if it's from either queue and remove it BEFORE emitting
             // This ensures the UI sees the updated queue state
             if (event.type === "message_start" && event.message.role === "user") {
@@ -154,10 +168,24 @@ export class AgentSession {
             this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
             // Handle session persistence
             if (event.type === "message_end") {
-                if (this._persistMessage(event.message)) {
-                    acknowledgeBackground?.();
-                    queuedBackgroundCompletion?.resolve();
+                let entryId;
+                // Check if this is a custom message from extensions
+                if (event.message.role === "custom") {
+                    // Persist as CustomMessageEntry
+                    entryId = this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+                }
+                else if (event.message.role === "system" ||
+                    event.message.role === "user" ||
+                    event.message.role === "assistant" ||
+                    event.message.role === "toolResult") {
+                    // Regular LLM message - persist as SessionMessageEntry
+                    entryId = this.sessionManager.appendMessage(event.message);
                 }
+                if (entryId)
+                    this._entryIdsByMessage.set(event.message, entryId);
+                if (entryId)
+                    this._messagePersisted(event.message);
+                // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
                 if (event.message.role === "assistant") {
                     const assistantMsg = event.message;
                     this._lastAssistantMessage = assistantMsg;
@@ -186,14 +214,14 @@ export class AgentSession {
                 this._flushPendingCustomMessages();
             }
             if (event.type === "agent_end")
-                this._failDrainedBackgroundCompletions();
+                this._tasksHost.delivery.agentEnded();
         };
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
-        this._backgroundHost = new BackgroundSession({
+        this._tasksHost = new TaskSession({
             manager: this.sessionManager,
-            role: config.executionRole ?? "main",
+            backgroundAllowed: config.backgroundAllowed,
             canDeliver: () => {
                 if (this.model === undefined || this.isCompacting)
                     return false;
@@ -202,7 +230,14 @@ export class AgentSession {
                 // turn, so it still waits for the queues to drain.
                 return this.isStreaming || (this.pendingMessageCount === 0 && !this.agent.hasQueuedMessages());
             },
-            deliver: (message) => this._deliverBackgroundCompletion(message),
+            deliver: (message, waitForPersistence) => {
+                if (this.isStreaming) {
+                    this.agent.steer(message);
+                    return waitForPersistence();
+                }
+                // Completion turns skip before_agent_start, but consume nextTurn context.
+                return this._runAgentPrompt([message, ...this._pendingNextTurnMessages]);
+            },
             onEntry: (entry) => this._emit({ type: "entry_appended", entry }),
             onError: (event, error) => this._extensionRunner?.emitError({ extensionPath: "<background>", event, error }),
         });
@@ -211,7 +246,7 @@ export class AgentSession {
         this._customTools = config.customTools ?? [];
         this._cwd = config.cwd;
         this._modelRuntime = config.modelRuntime;
-        this._captureModelContext = config.captureModelContext;
+        this._contextSource = config.contextSource;
         this._cacheWarmer = config.cacheWarmer;
         if (this._cacheWarmer) {
             this._cacheWarmer.onWarmed = (entry) => this._emit({ type: "entry_appended", entry });
@@ -229,6 +264,7 @@ export class AgentSession {
         this._installAgentNextTurnRefresh();
         this._installAgentRequestProjection();
         this._installAgentBoundaryHooks();
+        this._installHiddenDeclarationsProjection();
         this._installAgentForcedPromptProjection();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
@@ -237,26 +273,26 @@ export class AgentSession {
         if (this._initialActiveToolNames === undefined)
             this._restoreToolsFromTranscript();
     }
-    get background() {
-        return this._backgroundHost.service;
+    get tasks() {
+        return this._tasksHost.service;
     }
-    get quarantinedBackgroundSettlements() {
-        return this._backgroundHost.quarantinedSettlements;
+    get quarantinedTaskSettlements() {
+        return this._tasksHost.quarantinedSettlements;
     }
     /** Pause delivery across asynchronous lifecycle/preflight gaps. Nestable. */
-    pauseBackgroundNotifications() {
-        return this._backgroundHost.pause();
+    pauseTaskNotifications() {
+        return this._tasksHost.delivery.pause();
     }
     /** Explicit retry after a host delivery failure; never spins on a timer by itself. */
-    retryBackgroundNotifications() {
-        this._backgroundHost.retry();
+    retryTaskNotifications() {
+        this._tasksHost.delivery.retry();
     }
     /**
      * Run a lifecycle operation with delivery paused across its asynchronous gaps.
      * Lifecycle methods are thin shells over upstream bodies so those keep upstream's shape.
      */
-    async _withBackgroundPaused(operation) {
-        const resumeBackground = this.pauseBackgroundNotifications();
+    async _withTasksPaused(operation) {
+        const resumeBackground = this.pauseTaskNotifications();
         try {
             return await operation();
         }
@@ -272,6 +308,14 @@ export class AgentSession {
         const model = this.model;
         if (!model)
             throw new Error("No model selected");
+        const requestOptions = {
+            sessionId: this.agent.sessionId ?? this.sessionManager.getSessionId(),
+            transport: this.agent.transport,
+            thinkingBudgets: structuredClone(this.agent.thinkingBudgets),
+            maxRetryDelayMs: this.agent.maxRetryDelayMs,
+            onPayload: this.agent.onPayload,
+            onResponse: this.agent.onResponse,
+        };
         const snapshot = {
             capturedAt: Date.now(),
             sessionId: this.sessionManager.getSessionId(),
@@ -284,22 +328,15 @@ export class AgentSession {
                 parameters: structuredClone(parameters),
                 ...(constrainedSampling === undefined ? {} : { constrainedSampling: structuredClone(constrainedSampling) }),
             })),
-            streamOptions: resolveModelStreamOptions(model, this.settingsManager, this._extensionRunner, {
-                sessionId: this.agent.sessionId ?? this.sessionManager.getSessionId(),
-                transport: this.agent.transport,
-                thinkingBudgets: structuredClone(this.agent.thinkingBudgets),
-                maxRetryDelayMs: this.agent.maxRetryDelayMs,
-                onPayload: this.agent.onPayload,
-                onResponse: this.agent.onResponse,
-            }),
+            streamOptions: this._contextSource?.resolveStreamOptions(model, requestOptions) ?? requestOptions,
         };
         const currentSystemPrompt = this.systemPrompt;
         // The canonical projection is what the next request converts; the inspection cache may lag it.
         const messages = structuredClone(this.sessionManager.buildSessionProjection().messages);
         const convert = this.agent.convertToLlm;
         const transform = this.agent.transformContext;
-        const prepared = this._captureModelContext
-            ? await this._captureModelContext(messages)
+        const prepared = this._contextSource
+            ? await this._contextSource.prepareMessages(messages)
             : await convert(transform ? await transform(messages) : messages);
         // The prepared transcript declares the prompt the provider received, including a forced
         // prompt projected for the last request; before the first request there is none yet.
@@ -339,28 +376,71 @@ export class AgentSession {
         }
         throw new Error(formatNoApiKeyFoundMessage(model.provider));
     }
-    async _getSummarizationRequestAuth(model, signal) {
+    async _getSummarizationRequestAuth(selectedModel, signal) {
+        // Route a virtual model first: summaries size their input and output from the model they get.
+        const { model, thinkingLevel } = isVirtualModel(selectedModel)
+            ? await this._modelRuntime.resolveModel(selectedModel, convertToLlm(this.messages), {
+                reason: "direct",
+                thinkingLevel: this.thinkingLevel,
+                signal,
+            })
+            : { model: selectedModel, thinkingLevel: this.thinkingLevel };
         if (this.agent.streamFunction === streamSimple) {
-            return this._getRequiredRequestAuth(model, signal);
+            return { ...(await this._getRequiredRequestAuth(model, signal)), thinkingLevel };
         }
         try {
             const result = await this._modelRuntime.getAuth(model, { signal });
             if (!result)
-                return { model };
+                return { model, thinkingLevel };
             const requestModel = result.auth.baseUrl ? { ...model, baseUrl: result.auth.baseUrl } : model;
             return {
                 model: requestModel,
                 apiKey: result.auth.apiKey,
                 headers: withoutDeletedHeaders(result.auth.headers),
                 env: result.env,
+                thinkingLevel,
             };
         }
         catch (error) {
             if (signal?.aborted)
                 throw error;
-            return { model };
+            return { model, thinkingLevel };
         }
     }
+    /**
+     * The model whose limits apply to `message`, or undefined when the message came from another
+     * model. Under a virtual selection, that is the physical model that produced it.
+     */
+    _modelForMessage(message) {
+        const model = this.model;
+        if (model && isVirtualModel(model))
+            return this._modelRuntime.getPhysicalModel(message.provider, message.model);
+        return model?.provider === message.provider && model.id === message.model ? model : undefined;
+    }
+    /**
+     * Record the selection on the current branch when the branch implies another one, so a resume
+     * restores it. Tree navigation can leave the latest `model_change` on another branch; responses
+     * cannot record a virtual selection because they name physical models. Responses do record a
+     * physical selection unless the branch holds a virtual one; checking a physical selection against
+     * responses would record it on every prompt while `prepareRequest` redirects to another model.
+     */
+    _recordSelection() {
+        const model = this.model;
+        if (!model)
+            return;
+        const getModel = (provider, modelId) => this._modelRuntime.getModel(provider, modelId);
+        const recorded = getBranchSelection(this.sessionManager.getBranch(), getModel);
+        if (!recorded || (recorded.provider === model.provider && recorded.modelId === model.id))
+            return;
+        const recordedModel = getModel(recorded.provider, recorded.modelId);
+        if (!isVirtualModel(model) && !(recordedModel && isVirtualModel(recordedModel)))
+            return;
+        this.sessionManager.appendModelChange(model.provider, model.id);
+    }
+    /** The model whose limits apply to the conversation. */
+    _limitsModel() {
+        return this.routedModel?.model ?? this.model;
+    }
     /**
      * Install tool hooks once on the Agent instance.
      *
@@ -370,65 +450,112 @@ export class AgentSession {
      * happens here instead of in wrappers.
      */
     _installAgentToolHooks() {
-        this.agent.beforeToolCall = async ({ toolCall, args }) => {
-            const runner = this._extensionRunner;
-            if (!runner.hasHandlers("tool_call")) {
-                return undefined;
-            }
-            try {
-                return await runner.emitToolCall({
-                    type: "tool_call",
-                    toolName: toolCall.name,
-                    toolCallId: toolCall.id,
-                    input: args,
-                });
-            }
-            catch (err) {
-                if (err instanceof Error) {
-                    throw err;
-                }
-                throw new Error(`Extension failed, blocking execution: ${String(err)}`);
-            }
-        };
-        this.agent.afterToolCall = async ({ toolCall, args, result, isError }) => {
-            const runner = this._extensionRunner;
-            const hookResult = runner.hasHandlers("tool_result")
-                ? await runner.emitToolResult({
-                    type: "tool_result",
-                    toolName: toolCall.name,
-                    toolCallId: toolCall.id,
-                    input: args,
-                    content: result.content,
-                    details: result.details,
-                    isError,
-                    usage: result.usage,
-                })
-                : undefined;
-            const content = hookResult?.content ?? result.content ?? [];
-            // Runs after the extension hook so images injected or replaced by extensions are normalized too.
-            const resizeOptions = this.model?.inputLimits?.images?.resize;
-            const normalizedContent = await normalizeToolResultImages(content, {
-                autoResizeImages: this.settingsManager.getImageAutoResize(),
-                ...(resizeOptions ? { resizeOptions } : {}),
+        this.agent.beforeToolCall = (context) => this._beforeToolCall(context);
+        this.agent.afterToolCall = (context) => this._afterToolCall(context);
+    }
+    /** `tool_call` handlers. `parentToolCallId` is set for calls another tool made. */
+    async _beforeToolCall({ toolCall, args }, parentToolCallId) {
+        const runner = this._extensionRunner;
+        if (!runner.hasHandlers("tool_call")) {
+            return undefined;
+        }
+        try {
+            return await runner.emitToolCall({
+                type: "tool_call",
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                ...(parentToolCallId ? { parentToolCallId } : {}),
+                input: args,
             });
-            if (!hookResult && normalizedContent === content) {
-                return undefined;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw err;
             }
-            return {
-                content: normalizedContent,
-                details: hookResult?.details,
-                isError: hookResult?.isError ?? isError,
-                usage: hookResult?.usage,
-            };
+            throw new Error(`Extension failed, blocking execution: ${String(err)}`);
+        }
+    }
+    /** `tool_result` handlers and image normalization. `parentToolCallId` is set for calls another tool made. */
+    async _afterToolCall({ toolCall, args, result, isError }, parentToolCallId) {
+        const runner = this._extensionRunner;
+        const hookResult = runner.hasHandlers("tool_result")
+            ? await runner.emitToolResult({
+                type: "tool_result",
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                ...(parentToolCallId ? { parentToolCallId } : {}),
+                input: args,
+                content: result.content,
+                details: result.details,
+                ...(result.structuredContent === undefined ? {} : { structuredContent: result.structuredContent }),
+                isError,
+                usage: result.usage,
+            })
+            : undefined;
+        const content = hookResult?.content ?? result.content ?? [];
+        // Runs after the extension hook so images injected or replaced by extensions are normalized too.
+        const resizeOptions = this._limitsModel()?.inputLimits?.images?.resize;
+        const normalizedContent = await normalizeToolResultImages(content, {
+            autoResizeImages: this.settingsManager.getImageAutoResize(),
+            ...(resizeOptions ? { resizeOptions } : {}),
+        });
+        if (!hookResult && normalizedContent === content) {
+            return undefined;
+        }
+        // The hook result already dropped structured content that replaced content no longer matches.
+        return {
+            content: normalizedContent,
+            details: hookResult?.details,
+            structuredContent: hookResult ? hookResult.structuredContent : result.structuredContent,
+            isError: hookResult?.isError ?? isError,
+            usage: hookResult?.usage,
         };
     }
+    /**
+     * Run a call that the tool call `parentToolCallId` made through `ctx.executeTool()`. It goes
+     * through the agent's tool pipeline with the session's hooks, against the callable tools.
+     */
+    async _executeNestedToolCall(parentToolCallId, name, args, options) {
+        this._nestedToolCalls ??= new NestedToolCallRunner({
+            getTools: () => this._getCallableTools(),
+            isSequential: () => this.agent.toolExecution === "sequential",
+            runToolCall: (toolCall, parentId, signal, onUpdate) => {
+                const assistantMessage = this._findLastAssistantMessage();
+                if (!assistantMessage) {
+                    return Promise.resolve({
+                        toolCall,
+                        result: { content: [{ type: "text", text: "No assistant message issued this call" }], details: {} },
+                        isError: true,
+                    });
+                }
+                return runToolCall(toolCall, {
+                    tools: this._getCallableTools(),
+                    assistantMessage,
+                    context: { messages: this.agent.state.messages, tools: this.agent.state.tools },
+                    beforeToolCall: (context) => this._beforeToolCall(context, parentId),
+                    afterToolCall: (context) => this._afterToolCall(context, parentId),
+                    signal,
+                    onUpdate,
+                });
+            },
+            emit: async (event) => {
+                await this._extensionRunner.emit(event);
+                this._emit(event);
+            },
+        });
+        return this._nestedToolCalls.execute(parentToolCallId, name, args, options);
+    }
+    /** Whether `projection`, the current session projection, exceeds the compaction threshold of `model`. */
+    _exceedsCompactionThreshold(model, projection) {
+        if (model.contextWindow <= 0)
+            return false;
+        return shouldCompact(estimateProjectedContextTokens(projection, this.sessionManager.getBranch()).tokens, model.contextWindow, this.settingsManager.getCompactionSettings(model));
+    }
     async _compactBeforeNextAssistantResponse(context) {
-        const model = this.model;
-        const settings = this.settingsManager.getCompactionSettings(model);
         const projection = this.sessionManager.buildSessionProjection();
-        if (!model ||
-            model.contextWindow <= 0 ||
-            !shouldCompact(estimateProjectedContextTokens(projection, this.sessionManager.getBranch()).tokens, model.contextWindow, settings)) {
+        // A virtual selection is checked in prepareRequest, against the model the request is routed to.
+        const model = this.model;
+        if (!model || isVirtualModel(model) || !this._exceedsCompactionThreshold(model, projection)) {
             return { ...context, messages: projection.messages };
         }
         await this._runAutoCompaction("threshold", false);
@@ -437,24 +564,55 @@ export class AgentSession {
     _installAgentRequestProjection() {
         const previousPrepareRequest = this.agent.prepareRequest;
         this.agent.prepareRequest = async (request, signal) => {
-            const canonicalContext = {
-                ...request.context,
-                messages: this.sessionManager.buildSessionProjection().messages,
-                // Messages declare the provider-visible loadout; context.tools keeps executable implementations.
-                tools: this.agent.state.tools.slice(),
-            };
-            const previous = await previousPrepareRequest?.({
-                ...request,
-                context: canonicalContext,
-                model: this.agent.state.model,
-                thinkingLevel: this.agent.state.thinkingLevel,
-            }, signal);
-            return {
-                ...previous,
-                context: previous?.context ?? canonicalContext,
-                model: previous?.model ?? this.agent.state.model,
-                thinkingLevel: previous?.thinkingLevel ?? this.agent.state.thinkingLevel,
+            const failed = this._failedResponse;
+            this._failedResponse = undefined;
+            const prepare = async () => {
+                const projection = this.sessionManager.buildSessionProjection();
+                const canonicalContext = {
+                    ...request.context,
+                    messages: projection.messages,
+                    // Messages declare the provider-visible loadout; context.tools keeps executable implementations.
+                    tools: this.agent.state.tools.slice(),
+                };
+                const previous = await previousPrepareRequest?.({
+                    ...request,
+                    context: canonicalContext,
+                    model: this.agent.state.model,
+                    thinkingLevel: this.agent.state.thinkingLevel,
+                }, signal);
+                return { previous, context: previous?.context ?? canonicalContext, projection };
             };
+            let { previous, context, projection } = await prepare();
+            const model = previous?.model ?? this.agent.state.model;
+            const thinkingLevel = previous?.thinkingLevel ?? this.agent.state.thinkingLevel;
+            if (!isVirtualModel(model))
+                return { ...previous, context, model, thinkingLevel };
+            // The selection stays in agent state; only this request uses the routed model. A routing
+            // failure rejects, which ends the run with an error response. Only messages the user wrote
+            // start a turn; extension messages can follow them, e.g. from before_agent_start.
+            const lastResponse = context.messages.findLastIndex((message) => message.role === "assistant");
+            const userTurn = context.messages.slice(lastResponse + 1).some((message) => message.role === "user");
+            const state = getVirtualModelState(this.sessionManager.getBranch(), model.provider, model.id);
+            const route = await this._modelRuntime.resolveModel(model, convertToLlm(context.messages), {
+                reason: failed ? "retry" : userTurn ? "user" : "continuation",
+                thinkingLevel,
+                signal,
+                failed,
+                state,
+            });
+            if (route.state !== undefined && route.state !== state) {
+                const data = { provider: model.provider, modelId: model.id, state: route.state };
+                const entry = this.sessionManager.getEntry(this.sessionManager.appendCustomEntry(VIRTUAL_MODEL_STATE_ENTRY, data));
+                if (entry)
+                    this._emit({ type: "entry_appended", entry });
+            }
+            // The route stands: the router already decided this request. The state entry does not change
+            // the projection.
+            if (this._exceedsCompactionThreshold(route.model, projection)) {
+                await this._runAutoCompaction("threshold", false);
+                ({ previous, context } = await prepare());
+            }
+            return { ...previous, context, model: route.model, thinkingLevel: route.thinkingLevel };
         };
     }
     async _dispatchTurnEndBoundary(message, toolResults) {
@@ -510,10 +668,7 @@ export class AgentSession {
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
-            const context = await this._compactBeforeNextAssistantResponse({
-                ...turn.context,
-                messages: this.sessionManager.buildSessionProjection().messages,
-            });
+            const context = await this._compactBeforeNextAssistantResponse(turn.context);
             const previousSnapshot = await previousPrepareNextTurnWithContext?.({ ...turn, context }, signal);
             const nextContext = previousSnapshot?.context ?? context;
             const runOptions = this._runSystemPromptOptions ?? this._baseSystemPromptOptions;
@@ -661,7 +816,7 @@ export class AgentSession {
      * so a deferred prompt never races a delivery for the same idle gap.
      */
     async _emitAgentSettled() {
-        return this._withBackgroundPaused(() => this._emitAgentSettledBody());
+        return this._withTasksPaused(() => this._emitAgentSettledBody());
     }
     async _emitAgentSettledBody() {
         this._cacheWarmer?.onAgentSettled();
@@ -688,31 +843,16 @@ export class AgentSession {
         this._resolveIdleWaitIfIdle();
     }
     /**
-     * Persist model/custom messages and consume queued context only after the append succeeds.
-     * Returns the persisted entry ID, which boundary events and recovery omissions resolve later.
+     * Called after a message's session entry is appended. Queued `nextTurn` context is consumed
+     * only here, so a failed append leaves it queued, and Background delivery is acknowledged.
      */
-    _persistMessage(message) {
-        let entryId;
+    _messagePersisted(message) {
         if (message.role === "custom") {
-            entryId = this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
             const pendingIndex = this._pendingNextTurnMessages.indexOf(message);
             if (pendingIndex !== -1)
                 this._pendingNextTurnMessages.splice(pendingIndex, 1);
         }
-        else if (message.role === "system" ||
-            message.role === "user" ||
-            message.role === "assistant" ||
-            message.role === "toolResult") {
-            entryId = this.sessionManager.appendMessage(message);
-        }
-        else {
-            // Bash execution, compaction and branch summaries are persisted by their owners.
-            return undefined;
-        }
-        this._entryIdsByMessage.set(message, entryId);
-        if (message.role === "toolResult")
-            this._backgroundHost.acknowledgeWaitResult(message.details);
-        return entryId;
+        this._tasksHost.delivery.messagePersisted(message);
     }
     _willRetryAfterAgentEnd(event) {
         if (this._agentRunAbortRequested)
@@ -909,10 +1049,7 @@ export class AgentSession {
      * Call this when completely done with the session.
      */
     dispose() {
-        this._backgroundHost.dispose();
-        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
-            queued.reject(new Error("the session was disposed"));
-        }
+        this._tasksHost.dispose();
         try {
             this.abortRetry();
             this.abortCompaction();
@@ -923,7 +1060,7 @@ export class AgentSession {
         catch {
             // Dispose must succeed even if an abort hook throws.
         }
-        this._extensionRunner.invalidate(STALE_EXTENSION_CONTEXT_MESSAGE);
+        this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
         this._disconnectFromAgent();
         this._eventListeners = [];
         if (this._cacheWarmer) {
@@ -960,6 +1097,14 @@ export class AgentSession {
     get thinkingLevel() {
         return this.agent.state.thinkingLevel;
     }
+    /** Under a virtual selection, the physical model and thinking level of the latest successful response. */
+    get routedModel() {
+        if (!this.model || !isVirtualModel(this.model))
+            return undefined;
+        const latest = findLatestResponse(this.agent.state.messages);
+        const model = latest && this._modelRuntime.getPhysicalModel(latest.provider, latest.model);
+        return model && { model, thinkingLevel: latest?.thinkingLevel };
+    }
     /** Whether the session is currently processing an agent run or post-run continuation. */
     get isStreaming() {
         return this._isAgentRunActive;
@@ -977,12 +1122,16 @@ export class AgentSession {
         return this._retryAttempt;
     }
     /**
-     * Get the names of currently active tools.
-     * Returns the names of tools currently set on the agent.
+     * Get the names of currently active tools, which are the tools declared to the model.
+     * Tools with `codemode` or `deferred` exposure are callable from other tools without being active.
      */
     getActiveToolNames() {
         return this.agent.state.tools.map((t) => t.name);
     }
+    /** Get the names of the tools that tools can call through `ctx.executeTool()`. */
+    getCallableToolNames() {
+        return this._getCallableTools().map((t) => t.name);
+    }
     /**
      * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
      */
@@ -992,6 +1141,9 @@ export class AgentSession {
             description: definition.description,
             parameters: definition.parameters,
             promptGuidelines: definition.promptGuidelines,
+            exposure: this._getToolExposure(definition.name),
+            ...(definition.namespace ? { namespace: definition.namespace } : {}),
+            ...(definition.annotations ? { annotations: { ...definition.annotations } } : {}),
             sourceInfo,
         }));
     }
@@ -1000,22 +1152,79 @@ export class AgentSession {
     }
     /**
      * Set active tools by name.
-     * Only tools in the registry can be enabled. Unknown tool names are ignored.
+     * Only tools in the registry can be enabled. Unknown and hidden tool names are ignored.
      * Also rebuilds the system prompt to reflect the new tool set.
      * Changes take effect on the next agent turn.
      */
     setActiveToolsByName(toolNames) {
-        const tools = [];
-        const validToolNames = [];
-        for (const name of toolNames) {
+        const tools = this._applyToolLoadout(toolNames);
+        this._rebuildSystemPrompt(tools.map((tool) => tool.name));
+    }
+    _getToolExposure(name) {
+        return this._toolDefinitions.get(name)?.definition.exposure ?? "direct";
+    }
+    /**
+     * Tools callable through `ctx.executeTool()`: the active `direct` tools and every registered
+     * `codemode` or `deferred` tool.
+     */
+    _getCallableTools(active = new Set(this.getActiveToolNames())) {
+        return [...this._toolRegistry.values()].filter((tool) => {
+            const exposure = this._getToolExposure(tool.name);
+            return exposure === "codemode" || exposure === "deferred" || (exposure === "direct" && active.has(tool.name));
+        });
+    }
+    /**
+     * Set the agent's tools for the given active tool names and return them. The active tools are
+     * the registered, non-hidden ones; they are declared to the model. Active tools with a
+     * `prepareLoadout` hook can change the declared descriptions and hide declarations from
+     * requests (see {@link _installHiddenDeclarationsProjection}).
+     */
+    _applyToolLoadout(toolNames) {
+        const tools = [...new Set(toolNames)].flatMap((name) => {
             const tool = this._toolRegistry.get(name);
-            if (tool) {
-                tools.push(tool);
-                validToolNames.push(name);
+            return tool && this._getToolExposure(name) !== "hidden" ? [tool] : [];
+        });
+        const hooks = tools.flatMap((tool) => {
+            const entry = this._toolDefinitions.get(tool.name);
+            return entry?.definition.prepareLoadout ? [entry] : [];
+        });
+        const hidden = new Set();
+        let declared = tools;
+        if (hooks.length > 0) {
+            const loadout = {
+                declared: tools,
+                callable: this._getCallableTools(new Set(tools.map((tool) => tool.name))),
+                registered: [...this._toolRegistry.values()],
+                getExposure: (name) => this._getToolExposure(name),
+                getNamespace: (name) => this._toolDefinitions.get(name)?.definition.namespace,
+            };
+            const descriptions = new Map();
+            for (const { definition, sourceInfo } of hooks) {
+                try {
+                    const changes = definition.prepareLoadout?.(loadout);
+                    for (const [name, description] of Object.entries(changes?.descriptions ?? {})) {
+                        descriptions.set(name, description);
+                    }
+                    for (const name of changes?.hiddenDeclarations ?? [])
+                        hidden.add(name);
+                }
+                catch (error) {
+                    this._extensionRunner.emitError({
+                        extensionPath: sourceInfo.path,
+                        event: "prepare_loadout",
+                        error: error instanceof Error ? error.message : String(error),
+                        stack: error instanceof Error ? error.stack : undefined,
+                    });
+                }
             }
+            declared = tools.map((tool) => {
+                const description = descriptions.get(tool.name);
+                return description === undefined ? tool : { ...tool, description };
+            });
         }
-        this.agent.state.tools = tools;
-        this._rebuildSystemPrompt(validToolNames);
+        this._hiddenDeclarations = hidden;
+        this.agent.state.tools = declared;
+        return declared;
     }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
@@ -1116,11 +1325,7 @@ export class AgentSession {
      * {@link _installAgentForcedPromptProjection}.
      */
     _preparePromptAndToolLoadout(options, messages = this.agent.state.messages) {
-        options.selectedTools = [...new Set(options.selectedTools)].filter((name) => this._toolRegistry.has(name));
-        this.agent.state.tools = options.selectedTools.flatMap((name) => {
-            const tool = this._toolRegistry.get(name);
-            return tool ? [tool] : [];
-        });
+        options.selectedTools = this._applyToolLoadout(options.selectedTools).map((tool) => tool.name);
         const sections = diffSystemPromptSections(getCurrentSystemMessage(messages)?.sections ?? {}, buildSystemPromptSections(options));
         return sections ? { role: "system", content: "", sections, timestamp: Date.now() } : undefined;
     }
@@ -1134,6 +1339,32 @@ export class AgentSession {
      * collapse into one head holding the forced text and the current tools. Runs after the
      * `context` extension handlers.
      */
+    /**
+     * Remove the declarations that `prepareLoadout` hooks hide from every request. The whole
+     * transcript is filtered with the current set, so the projected declarations stay consistent
+     * across requests and only change when the loadout does.
+     */
+    _installHiddenDeclarationsProjection() {
+        const previousTransformContext = this.agent.transformContext;
+        this.agent.transformContext = async (messages, signal) => {
+            const transformed = previousTransformContext ? await previousTransformContext(messages, signal) : messages;
+            const hidden = this._hiddenDeclarations;
+            if (hidden.size === 0)
+                return transformed;
+            return transformed.map((message) => {
+                if (message.role !== "system" || (!message.toolsAdded && !message.toolsRemoved))
+                    return message;
+                const { toolsAdded, toolsRemoved, ...rest } = message;
+                const added = toolsAdded?.filter((tool) => !hidden.has(tool.name)) ?? [];
+                const removed = toolsRemoved?.filter((tool) => !hidden.has(tool.name)) ?? [];
+                return {
+                    ...rest,
+                    ...(added.length > 0 ? { toolsAdded: added } : {}),
+                    ...(removed.length > 0 ? { toolsRemoved: removed } : {}),
+                };
+            });
+        };
+    }
     _installAgentForcedPromptProjection() {
         const previousTransformContext = this.agent.transformContext;
         this.agent.transformContext = async (messages, signal) => {
@@ -1151,25 +1382,25 @@ export class AgentSession {
             return [head, ...transformed.filter((message) => message.role !== "system")];
         };
     }
-    /** Restore the active tool loadout declared by the session transcript, if it declares one. */
+    /**
+     * Restore the active tool loadout declared by the session transcript, if it declares one.
+     * Tools reachable only from other tools are never declared, but they do not depend on the active
+     * set, so the transcript's declarations are the whole loadout.
+     */
     _restoreToolsFromTranscript() {
         const current = getCurrentSystemMessage(this.sessionManager.buildSessionContext().messages);
         if (!current)
             return;
-        const toolNames = (current.toolsAdded ?? [])
-            .map((tool) => tool.name)
-            .filter((name) => this._toolRegistry.has(name));
-        this.agent.state.tools = toolNames.flatMap((name) => {
-            const registered = this._toolRegistry.get(name);
-            return registered ? [registered] : [];
-        });
-        this._rebuildSystemPrompt(toolNames);
+        this.setActiveToolsByName((current.toolsAdded ?? []).map((tool) => tool.name));
     }
     // =========================================================================
     // Prompting
     // =========================================================================
     async _runAgentPrompt(messages) {
         this._agentRunAbortRequested = false;
+        // Compaction before the prompt may have scheduled a retry; the new prompt replaces it.
+        this._failedResponse = undefined;
+        this._recordSelection();
         this._isAgentRunActive = true;
         try {
             await this.agent.prompt(messages);
@@ -1190,61 +1421,13 @@ export class AgentSession {
         finally {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
+            this._failedResponse = undefined;
             this._runSystemPromptOptions = undefined;
             this._flushPendingBashMessages();
             this._flushPendingCustomMessages();
             await this._emitAgentSettled();
         }
     }
-    /**
-     * Deliver a background completion through the same queueing path as interactive input:
-     * steering into an active run lands the result right after the current tool batch, and an
-     * idle session starts its own turn. The promise settles only once the message is persisted,
-     * or once it can no longer be persisted, so the caller never releases its claim for a
-     * message the transcript does not contain.
-     */
-    _deliverBackgroundCompletion(message) {
-        if (!this.isStreaming) {
-            // Completion turns skip before_agent_start, but consume nextTurn context.
-            const asides = this._pendingNextTurnMessages.slice();
-            return this._runAgentPrompt(asides.length ? [message, ...asides] : message);
-        }
-        return new Promise((resolve, reject) => {
-            const queued = {
-                drained: false,
-                resolve: () => {
-                    if (this._queuedBackgroundCompletions.get(message) !== queued)
-                        return;
-                    this._queuedBackgroundCompletions.delete(message);
-                    resolve();
-                },
-                reject: (reason) => {
-                    if (this._queuedBackgroundCompletions.get(message) !== queued)
-                        return;
-                    this._queuedBackgroundCompletions.delete(message);
-                    reject(reason);
-                },
-            };
-            this._queuedBackgroundCompletions.set(message, queued);
-            try {
-                this.agent.steer(message);
-            }
-            catch (error) {
-                queued.reject(error);
-            }
-        });
-    }
-    /**
-     * Fail deliveries the owning run emitted but never persisted. A completion still sitting in
-     * the steering queue when its run ends stays claimed: the next run delivers it, so failing
-     * it here would persist the same message twice.
-     */
-    _failDrainedBackgroundCompletions() {
-        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
-            if (queued.drained)
-                queued.reject(new Error("the completion message was not persisted"));
-        }
-    }
     async _handlePostAgentRun() {
         const message = this._lastAssistantMessage;
         const toolResults = this._lastAssistantToolResults;
@@ -1259,6 +1442,7 @@ export class AgentSession {
         if (this._isRetryableError(message) && (await this._prepareRetry(message))) {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
+            this._failedResponse = message;
             return !this._agentRunAbortRequested;
         }
         if (this._agentRunAbortRequested) {
@@ -1326,7 +1510,7 @@ export class AgentSession {
         for (const image of images) {
             const processed = await processImage(Buffer.from(image.data, "base64"), image.mimeType, {
                 autoResizeImages: this.settingsManager.getImageAutoResize(),
-                resizeOptions: this.model?.inputLimits?.images?.resize,
+                resizeOptions: this._limitsModel()?.inputLimits?.images?.resize,
             });
             if (!processed.ok) {
                 hints.push(processed.message);
@@ -1352,7 +1536,7 @@ export class AgentSession {
             return;
         }
         // A user-initiated prompt is the recovery point for failed completion deliveries.
-        this.retryBackgroundNotifications();
+        this.retryTaskNotifications();
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let messages;
@@ -1364,20 +1548,20 @@ export class AgentSession {
                 const handled = await this._tryExecuteExtensionCommand(text);
                 if (handled) {
                     // Extension command executed, no prompt to send
-                    preflightResult?.(true);
+                    preflightResult?.("handled");
                     return;
                 }
             }
             // Observer commands above may stay open indefinitely; only real model input owns
             // the preflight pause, released once the user message is established.
-            resumeBackground = this.pauseBackgroundNotifications();
+            resumeBackground = this.pauseTaskNotifications();
             if (this._compactionAbortController !== undefined) {
                 throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
             }
             // Emit input event for extension interception (before skill/template expansion)
             const processedInput = await this._runInputHandlers(text, options?.images, options?.source ?? "interactive", this.isStreaming ? options?.streamingBehavior : undefined);
             if (!processedInput) {
-                preflightResult?.(true);
+                preflightResult?.("handled");
                 return;
             }
             const { text: currentText, images: currentImages } = processedInput;
@@ -1398,7 +1582,7 @@ export class AgentSession {
                 else {
                     await this._queueSteer(expandedText, currentImages);
                 }
-                preflightResult?.(true);
+                preflightResult?.("queued");
                 return;
             }
             // Flush any pending bash and custom messages before the new prompt
@@ -1447,8 +1631,7 @@ export class AgentSession {
                 content: userContent,
                 timestamp: Date.now(),
             });
-            // Inject any pending "nextTurn" messages as context alongside the user message.
-            // They stay queued until _persistMessage() confirms the append.
+            // Inject any pending "nextTurn" messages as context alongside the user message
             for (const msg of this._pendingNextTurnMessages) {
                 messages.push(msg);
             }
@@ -1468,18 +1651,12 @@ export class AgentSession {
             if (updateMessage)
                 messages.unshift(updateMessage);
         }
-        catch (error) {
-            preflightResult?.(false);
-            throw error;
-        }
         finally {
-            // Delivery is timer-scheduled, so a completion cannot start before the run below does.
             resumeBackground?.();
         }
-        if (!messages) {
+        if (!messages)
             return;
-        }
-        preflightResult?.(true);
+        preflightResult?.("started");
         await this._runAgentPrompt(messages);
     }
     /**
@@ -1545,7 +1722,7 @@ export class AgentSession {
         }
         const processedInput = await this._runInputHandlers(text, images, source, this.isStreaming ? behavior : undefined);
         if (!processedInput)
-            return;
+            return "handled";
         let expandedText = this._expandSkillCommand(processedInput.text);
         expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
         if (behavior === "steer") {
@@ -1554,6 +1731,7 @@ export class AgentSession {
         else {
             await this._queueFollowUp(expandedText, processedInput.images);
         }
+        return "queued";
     }
     /**
      * Queue a steering message while the agent is running.
@@ -1565,7 +1743,7 @@ export class AgentSession {
      * @throws Error if text is an extension command
      */
     async steer(text, images, options) {
-        await this._queueUserInput(text, images, "steer", options?.source ?? "interactive");
+        return this._queueUserInput(text, images, "steer", options?.source ?? "interactive");
     }
     /**
      * Queue a follow-up message to be processed after the agent finishes.
@@ -1576,7 +1754,7 @@ export class AgentSession {
      * @throws Error if text is an extension command
      */
     async followUp(text, images, options) {
-        await this._queueUserInput(text, images, "followUp", options?.source ?? "interactive");
+        return this._queueUserInput(text, images, "followUp", options?.source ?? "interactive");
     }
     /**
      * Internal: Queue a steering message (already expanded, no extension command check).
@@ -1670,9 +1848,9 @@ export class AgentSession {
         }
     }
     _appendCustomMessage(appMessage) {
-        this._persistMessage(appMessage);
+        this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
+        this._messagePersisted(appMessage);
         this._refreshFinalizedContext();
-        this._backgroundHost.messageAcknowledgement(appMessage)?.();
         this._emit({ type: "message_start", message: appMessage });
         this._emit({ type: "message_end", message: appMessage });
     }
@@ -1737,10 +1915,7 @@ export class AgentSession {
         this._steeringMessages = [];
         this._followUpMessages = [];
         this.agent.clearAllQueues();
-        // Clearing the queues drops queued completions; fail them so their claims retry.
-        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
-            queued.reject(new Error("the completion message was dequeued before delivery"));
-        }
+        this._tasksHost.delivery.queueCleared();
         this._emitQueueUpdate();
         return { steering, followUp };
     }
@@ -1997,8 +2172,10 @@ export class AgentSession {
     // Compaction
     // =========================================================================
     /** Generate Pi's built-in compaction summary for manual and automatic compaction. */
-    async _runDefaultCompaction(preparation, requestModel, apiKey, headers, customInstructions, signal, env, reason) {
-        return compact(preparation, requestModel, apiKey, headers, customInstructions, signal, this.thinkingLevel, this.agent.streamFunction, env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), undefined);
+    async _runDefaultCompaction(preparation, model, customInstructions, signal, reason) {
+        // Resolve the request only when Pi summarizes itself: routing may call models or fail.
+        const request = await this._getSummarizationRequestAuth(model, signal);
+        return compact(preparation, request.model, request.apiKey, request.headers, customInstructions, signal, request.thinkingLevel, this.agent.streamFunction, request.env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), undefined);
     }
     _clearManualCompactionState() {
         this._compactionAbortController = undefined;
@@ -2020,7 +2197,7 @@ export class AgentSession {
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
-        return this._withBackgroundPaused(() => this._compactBody(customInstructions));
+        return this._withTasksPaused(() => this._compactBody(customInstructions));
     }
     async _compactBody(customInstructions) {
         await this.abort();
@@ -2033,8 +2210,7 @@ export class AgentSession {
             if (!model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
-            const settings = this.settingsManager.getCompactionSettings(model);
-            const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, this._compactionAbortController.signal);
+            const settings = this.settingsManager.getCompactionSettings(this.routedModel?.model ?? model);
             const pathEntries = this.sessionManager.getBranch();
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
@@ -2080,7 +2256,7 @@ export class AgentSession {
             }
             else {
                 // Shared default summary generator, also used by automatic compaction.
-                const result = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, env, "manual");
+                const result = await this._runDefaultCompaction(preparation, model, customInstructions, this._compactionAbortController.signal, "manual");
                 summary = result.summary;
                 firstKeptEntryId = result.firstKeptEntryId;
                 tokensBefore = result.tokensBefore;
@@ -2185,18 +2361,20 @@ export class AgentSession {
      * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
      */
     async _checkCompaction(assistantMessage, skipAbortedCheck = true, toolResults = []) {
-        const settings = this.settingsManager.getCompactionSettings(this.model);
+        const settings = this.settingsManager.getCompactionSettings(this._modelForMessage(assistantMessage) ?? this.model);
         if (!settings.enabled)
             return false;
         // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
         if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
             return false;
-        const contextWindow = this.model?.contextWindow ?? 0;
         // Skip overflow check if the message came from a different model.
         // This handles the case where user switched from a smaller-context model (e.g. opus)
         // to a larger-context model (e.g. codex) - the overflow error from the old model
-        // shouldn't trigger compaction for the new model.
-        const sameModel = this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;
+        // shouldn't trigger compaction for the new model. Under a virtual selection, the
+        // physical model that produced the message supplies the limits.
+        const messageModel = this._modelForMessage(assistantMessage);
+        const sameModel = messageModel !== undefined;
+        const contextWindow = (messageModel ?? this.model)?.contextWindow ?? 0;
         // Skip compaction checks if this assistant message is older than the latest
         // compaction boundary. This prevents a stale pre-compaction usage/error
         // from retriggering compaction on the first prompt after compaction.
@@ -2228,7 +2406,7 @@ export class AgentSession {
         const contextOverflow = sameModel &&
             ((explicitOverflow && assistantRetainedForExplicitRecovery) ||
                 (assistantUsageMatchesProjection && isContextOverflow(assistantMessage, contextWindow)));
-        const recoverableLength = sameModel && assistantIsProjected && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
+        const recoverableLength = sameModel && assistantIsProjected && isRecoverableLength(assistantMessage, messageModel.maxTokens);
         if (contextOverflow || recoverableLength) {
             const willRetry = assistantMessage.stopReason !== "stop";
             // Case 2: the response completed successfully. Compact, but do not retry because
@@ -2260,7 +2438,10 @@ export class AgentSession {
             // Persistently omit the selected final attempt before post-run recovery compaction.
             this._overflowRecoveryAttempted = true;
             this._omitRecoveryAttempt(assistantMessage, toolResults);
-            return await this._runAutoCompaction("overflow", willRetry);
+            const retry = await this._runAutoCompaction("overflow", willRetry);
+            if (retry)
+                this._failedResponse = assistantMessage;
+            return retry;
         }
         // Case 3: threshold compaction without retry.
         // For error messages or all-zero usage messages, estimate from the last valid response.
@@ -2310,11 +2491,11 @@ export class AgentSession {
      * @returns Whether the post-run loop should call `agent.continue()`
      */
     async _runAutoCompaction(reason, willRetry) {
-        return this._withBackgroundPaused(() => this._runAutoCompactionBody(reason, willRetry));
+        return this._withTasksPaused(() => this._runAutoCompactionBody(reason, willRetry));
     }
     async _runAutoCompactionBody(reason, willRetry) {
         const model = this.model;
-        const settings = this.settingsManager.getCompactionSettings(model);
+        const settings = this.settingsManager.getCompactionSettings(this.routedModel?.model ?? model);
         let abortController;
         let started = false;
         let fromExtension = false;
@@ -2333,8 +2514,6 @@ export class AgentSession {
             started = true;
             this._emit({ type: "compaction_start", reason });
             abortController.signal.throwIfAborted();
-            const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, abortController.signal);
-            abortController.signal.throwIfAborted();
             let extensionCompaction;
             if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const extensionResult = (await this._extensionRunner.emit({
@@ -2371,7 +2550,7 @@ export class AgentSession {
             }
             else {
                 // Shared default summary generator, also used by manual compaction.
-                const compactResult = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, undefined, abortController.signal, env, reason);
+                const compactResult = await this._runDefaultCompaction(preparation, model, undefined, abortController.signal, reason);
                 summary = compactResult.summary;
                 firstKeptEntryId = compactResult.firstKeptEntryId;
                 tokensBefore = compactResult.tokensBefore;
@@ -2454,11 +2633,12 @@ export class AgentSession {
         return this.settingsManager.getCompactionEnabled();
     }
     async bindExtensions(bindings) {
-        return this._withBackgroundPaused(() => this._bindExtensionsBody(bindings));
+        return this._withTasksPaused(() => this._bindExtensionsBody(bindings));
     }
     async _bindExtensionsBody(bindings) {
-        if (bindings.backgroundEnabled !== undefined) {
-            this._backgroundHost.setEnabled(bindings.backgroundEnabled);
+        if (bindings.tasksEnabled !== undefined) {
+            this._tasksHost.setEnabled(bindings.tasksEnabled);
+            this._refreshToolRegistry();
         }
         if (bindings.uiContext !== undefined) {
             this._extensionUIContext = bindings.uiContext;
@@ -2480,6 +2660,7 @@ export class AgentSession {
         }
         this._applyExtensionBindings(this._extensionRunner);
         await this._extensionRunner.emit(this._sessionStartEvent);
+        this._extensionRunner.reportUnhandledMcpServers();
         await this.extendResourcesFromExtensions(this._sessionStartEvent.reason === "reload" ? "reload" : "startup");
     }
     async extendResourcesFromExtensions(reason) {
@@ -2501,7 +2682,7 @@ export class AgentSession {
     buildExtensionResourcePaths(entries) {
         return entries.map((entry) => {
             const source = this.getExtensionSourceLabel(entry.extensionPath);
-            const baseDir = entry.extensionPath.startsWith("<") ? undefined : dirname(entry.extensionPath);
+            const baseDir = isSyntheticPath(entry.extensionPath) ? undefined : dirname(entry.extensionPath);
             return {
                 path: entry.path,
                 metadata: {
@@ -2514,7 +2695,7 @@ export class AgentSession {
         });
     }
     getExtensionSourceLabel(extensionPath) {
-        if (extensionPath.startsWith("<")) {
+        if (isSyntheticPath(extensionPath)) {
             return `extension:${extensionPath.replace(/[<>]/g, "")}`;
         }
         const base = basename(extensionPath);
@@ -2599,6 +2780,7 @@ export class AgentSession {
             },
             getActiveTools: () => this.getActiveToolNames(),
             getAllTools: () => this.getAllTools(),
+            getSettings: () => this.settingsManager.getSettings(),
             setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),
             refreshTools: () => this._refreshToolRegistry(),
             getCommands,
@@ -2611,7 +2793,9 @@ export class AgentSession {
             getThinkingLevel: () => this.thinkingLevel,
             setThinkingLevel: (level) => this.setThinkingLevel(level),
         }, {
-            getBackground: () => this.background,
+            getTasks: () => this.tasks,
+            getExtensionSettings: (namespace) => this.settingsManager.getExtensionSettings(namespace),
+            setExtensionSettings: (namespace, value) => this.settingsManager.setExtensionSettings(namespace, value),
             getModel: () => this.model,
             getScopedModels: () => this._scopedModels,
             isIdle: () => this.isIdle,
@@ -2644,6 +2828,8 @@ export class AgentSession {
             },
             getSystemPrompt: () => this.systemPrompt,
             getSystemPromptOptions: () => this._baseSystemPromptOptions,
+            executeTool: (callerId, name, args, options) => this._executeNestedToolCall(callerId, name, args, options),
+            getCallableTools: () => this._getCallableTools(),
         }, {
             registerProvider: (name, config) => {
                 this._modelRuntime.registerProvider(name, config);
@@ -2657,10 +2843,20 @@ export class AgentSession {
                 this._modelRuntime.unregisterProvider(name);
                 this._refreshCurrentModelFromRegistry();
             },
+            registerVirtualModel: (definition) => {
+                this._modelRuntime.registerVirtualModel(definition);
+                this._refreshCurrentModelFromRegistry();
+            },
+            unregisterVirtualModel: (provider, id) => {
+                this._modelRuntime.unregisterVirtualModel(provider, id);
+                this._refreshCurrentModelFromRegistry();
+            },
         });
     }
     _refreshToolRegistry(options) {
-        const previousRegistryNames = new Set(this._toolRegistry.keys());
+        // Tools that were already activated on registration. A tool whose exposure changes to
+        // `direct` or `model-only` (for example from `hidden`) is activated like a new tool.
+        const previousActivatedOnRegistration = new Set([...this._toolRegistry.keys()].filter((name) => this._isActivatedOnRegistration(name)));
         const previousActiveToolNames = this.getActiveToolNames();
         const allowedToolNames = this._allowedToolNames;
         const excludedToolNames = this._excludedToolNames;
@@ -2679,7 +2875,7 @@ export class AgentSession {
             name,
             {
                 definition,
-                sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
+                sourceInfo: createSyntheticSourceInfo(`${BUILTIN_PATH_PREFIX}${name}`, { source: "builtin" }),
             },
         ]));
         for (const tool of allCustomTools) {
@@ -2707,7 +2903,9 @@ export class AgentSession {
             .filter((definition) => isAllowedTool(definition.name))
             .map((definition) => ({
             definition,
-            sourceInfo: createSyntheticSourceInfo(`<builtin:${definition.name}>`, { source: "builtin" }),
+            sourceInfo: createSyntheticSourceInfo(`${BUILTIN_PATH_PREFIX}${definition.name}`, {
+                source: "builtin",
+            }),
         })), runner);
         const toolRegistry = new Map(wrappedBuiltInTools.map((tool) => [tool.name, tool]));
         for (const tool of wrappedExtensionTools) {
@@ -2717,25 +2915,41 @@ export class AgentSession {
         const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => isAllowedTool(name));
         if (allowedToolNames) {
             for (const toolName of this._toolRegistry.keys()) {
-                if (allowedToolNames.has(toolName)) {
+                // Naming a tool activates it even when it is not active by default.
+                if (allowedToolNames.has(toolName) && this._isDeclarable(toolName)) {
                     nextActiveToolNames.push(toolName);
                 }
             }
         }
         else if (options?.includeAllExtensionTools) {
             for (const tool of wrappedExtensionTools) {
-                nextActiveToolNames.push(tool.name);
+                if (this._isActivatedOnRegistration(tool.name))
+                    nextActiveToolNames.push(tool.name);
             }
         }
         else if (!options?.activeToolNames) {
             for (const toolName of this._toolRegistry.keys()) {
-                if (!previousRegistryNames.has(toolName)) {
+                if (!previousActivatedOnRegistration.has(toolName) && this._isActivatedOnRegistration(toolName)) {
                     nextActiveToolNames.push(toolName);
                 }
             }
         }
+        if (this.tasks.enabled &&
+            this._initialActiveToolNames?.length !== 0 &&
+            this._toolRegistry.has("tasks") &&
+            isAllowedTool("tasks"))
+            nextActiveToolNames.push("tasks");
         this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
     }
+    /** Whether activating the tool declares it to the model. */
+    _isDeclarable(name) {
+        const exposure = this._getToolExposure(name);
+        return exposure === "direct" || exposure === "model-only";
+    }
+    /** Whether registering the tool activates it, which declares it to the model. */
+    _isActivatedOnRegistration(name) {
+        return this._isDeclarable(name) && this._toolDefinitions.get(name)?.definition.defaultActive !== false;
+    }
     _buildRuntime(options) {
         const autoResizeImages = this.settingsManager.getImageAutoResize();
         const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
@@ -2750,6 +2964,7 @@ export class AgentSession {
                 bash: { commandPrefix: shellCommandPrefix, shellPath },
             });
         this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
+        this._baseToolDefinitions.set("tasks", createTasksToolDefinition((callId, taskId) => this._tasksHost.delivery.prepareWait(callId, taskId)));
         const extensionsResult = this._resourceLoader.getExtensions();
         if (options.flagValues) {
             for (const [name, value] of options.flagValues) {
@@ -2772,26 +2987,26 @@ export class AgentSession {
         });
     }
     async reload(options) {
-        return this._withBackgroundPaused(() => this._reloadBody(options));
+        return this._withTasksPaused(() => this._reloadBody(options));
     }
     async _reloadBody(options) {
         const oldRunner = this._extensionRunner;
         const previousFlagValues = oldRunner.getFlagValues();
-        this.background.close();
-        await Promise.all([this.background.shutdown(), this.abort()]);
+        this.tasks.close();
+        await Promise.all([this.tasks.shutdown(), this.abort()]);
         await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });
         oldRunner.invalidate();
         await this.settingsManager.reload();
         this.syncQueueModesFromSettings();
         resetApiProviders();
         await this._resourceLoader.reload();
-        this._backgroundHost.replaceService();
+        this._tasksHost.replaceService();
         this._buildRuntime({
             activeToolNames: this.getActiveToolNames(),
             flagValues: previousFlagValues,
             includeAllExtensionTools: true,
         });
-        const hasBindings = this.background.enabled ||
+        const hasBindings = this.tasks.enabled ||
             this._extensionUIContext ||
             this._extensionCommandContextActions ||
             this._extensionShutdownHandler ||
@@ -2799,6 +3014,7 @@ export class AgentSession {
         if (hasBindings) {
             await options?.beforeSessionStart?.();
             await this._extensionRunner.emit({ type: "session_start", reason: "reload" });
+            this._extensionRunner.reportUnhandledMcpServers();
             await this.extendResourcesFromExtensions("reload");
         }
     }
@@ -2811,7 +3027,7 @@ export class AgentSession {
      */
     _isRetryableError(message) {
         // Context overflow is handled by compaction, not retry.
-        if (isContextOverflow(message, this.model?.contextWindow ?? 0))
+        if (isContextOverflow(message, (this._modelForMessage(message) ?? this.model)?.contextWindow ?? 0))
             return false;
         return isRetryableAssistantError(message);
     }
@@ -3066,7 +3282,7 @@ export class AgentSession {
             replaceInstructions,
             label,
         };
-        const resumeBackground = this.pauseBackgroundNotifications();
+        const resumeBackground = this.pauseTaskNotifications();
         // Set up abort controller for summarization
         this._branchSummaryAbortController = new AbortController();
         try {
@@ -3102,15 +3318,11 @@ export class AgentSession {
             let summaryDetails;
             let summaryUsage;
             if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
-                const model = this.model;
-                const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(model);
+                const signal = this._branchSummaryAbortController.signal;
                 const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
                 const result = await generateBranchSummary(entriesToSummarize, {
-                    model: requestModel,
-                    apiKey,
-                    headers,
-                    env,
-                    signal: this._branchSummaryAbortController.signal,
+                    ...(await this._getSummarizationRequestAuth(this.model, signal)),
+                    signal,
                     customInstructions,
                     replaceInstructions,
                     reserveTokens: branchSummarySettings.reserveTokens,
@@ -3153,7 +3365,7 @@ export class AgentSession {
                 // Non-user message: leaf = selected node
                 newLeafId = targetId;
             }
-            await this.background.cancelOutsideBranch(new Set(newLeafId === null ? [] : this.sessionManager.getBranch(newLeafId).map((entry) => entry.id)));
+            await this.tasks.cancelOutsideBranch(new Set(newLeafId === null ? [] : this.sessionManager.getBranch(newLeafId).map((entry) => entry.id)));
             // Switch leaf (with or without summary)
             // Summary is attached at the navigation target position (newLeafId), not the old branch
             let summaryEntry;
@@ -3178,7 +3390,7 @@ export class AgentSession {
             if (label && !summaryText) {
                 this.sessionManager.appendLabelChange(targetId, label);
             }
-            this._backgroundHost.restoreHistory();
+            this._tasksHost.restoreHistory();
             // Update finalized context from the canonical session projection.
             this._refreshFinalizedContext();
             this._restoreToolsFromTranscript();
@@ -3271,7 +3483,7 @@ export class AgentSession {
         };
     }
     getContextUsage() {
-        const model = this.model;
+        const model = this._limitsModel();
         if (!model)
             return undefined;
         const contextWindow = model.contextWindow ?? 0;
@@ -3343,16 +3555,11 @@ export class AgentSession {
         if (!model) {
             throw new Error("No model selected");
         }
-        const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(model);
         return generateBugReportSummary({
+            ...(await this._getSummarizationRequestAuth(model, options.signal)),
             messages: this.messages,
             hint: options.hint,
-            model: requestModel,
-            apiKey,
-            headers,
-            env,
             signal: options.signal,
-            thinkingLevel: this.thinkingLevel,
             streamFn: this.agent.streamFunction,
             retry: this.settingsManager.getRetrySettings(),
             sessionId: this.sessionId,