@selesai/code 0.13.39 → 0.14.0

package/dist/core/agent-session.js

@@ -12,34 +12,41 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
+import { runToolCall, } from "@earendil-works/pi-agent-core";
 import { contentText, getCurrentSystemMessage, 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";
 import { stripFrontmatter } from "../utils/frontmatter.js";
-import { resolvePath } from "../utils/paths.js";
+import { processImage } from "../utils/image-process.js";
 import { sleep } from "../utils/sleep.js";
 import { normalizeAssistantThinkingTags } from "../utils/thinking-tags.js";
+import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { executeBashWithOperations } from "./bash-executor.js";
 import { generateBugReportSummary } from "./bug-report.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.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 { AUTO_HANDOFF_GOAL } from "./handoff.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
+import { createToolNameMatcher, isMcpToolName } from "./mcp-servers.js";
+import { convertToLlm } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
+import { NestedToolCallRunner } from "./nested-tool-calls.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
-import { createSyntheticSourceInfo } from "./source-info.js";
+import { exportSessionToJsonl } from "./session-export.js";
+import { getLatestCompactionEntry, SessionManager, } from "./session-manager.js";
+import { applyToolModifiers, DEFAULT_TOOL_NAMES, } from "./settings-manager.js";
+import { BUILTIN_PATH_PREFIX, createSyntheticSourceInfo, isSyntheticPath } from "./source-info.js";
 import { buildSystemPrompt, buildSystemPromptSections, diffSystemPromptSections, normalizeBuildSystemPromptOptions, } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
-import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
+import { addUsageToTotals, combineUsage, createUsageTotals } from "./usage-totals.js";
+import { findLatestResponse, getBranchSelection, getVirtualModelState, isVirtualModel, VIRTUAL_MODEL_STATE_ENTRY, } from "./virtual-models.js";
 import { captionImageWithModel } from "./vision-caption.js";
 /** Parse consecutive skill blocks at the start of a user message. */
 export function parseSkillBlocks(text) {
@@ -120,6 +127,11 @@ export class AgentSession {
     // Retry state
     _retryAbortController = undefined;
     _retryAttempt = 0;
+    /**
+     * Failed response that the next request repeats, set by auto-retry and overflow recovery. The
+     * retry is routed with it as `failed`, since the context no longer contains it.
+     */
+    _failedResponse;
     // Length-stop continuation state (consecutive output-token-limit continuations)
     _lengthContinuations = 0;
     // Bash execution state
@@ -128,14 +140,37 @@ export class AgentSession {
     // Extension system
     _extensionRunner;
     _turnIndex = 0;
+    _entryIdsByMessage = new WeakMap();
+    _boundaryDispatchedMessages = new WeakSet();
+    _lastAssistantMessage;
+    _lastAssistantToolResults = [];
+    _lastActivityOutcome = "completed";
+    _isBeforeSettle = false;
+    _abortDuringBeforeSettle = false;
+    _isEmittingAgentSettled = false;
+    _deferredSettledActions = [];
     _resourceLoader;
     _customTools;
     _baseToolDefinitions = new Map();
     _cwd;
     _extensionRunnerRef;
     _initialActiveToolNames;
-    _allowedToolNames;
-    _excludedToolNames;
+    /**
+     * Tools of the restored or reloaded loadout that are not registered yet, such as tools of MCP
+     * servers that are still connecting. They are activated when they are registered, and dropped when
+     * `setActiveToolsByName()` deactivates a tool or the next agent run starts.
+     */
+    _pendingToolNames = new Set();
+    _usesDefaultTools;
+    _defaultToolModifiers;
+    /** Matches the `--tools` entries: tool names or patterns. */
+    _allowedTools;
+    /**
+     * Whether the allowlist filters MCP tools: it is empty (`--no-tools`) or names an MCP tool
+     * (`mcp__*`). Otherwise it keeps MCP tools registered for codemode and tool_search.
+     */
+    _allowlistFiltersMcp = false;
+    _excludedTools;
     _baseToolsOverride;
     _sessionStartEvent;
     _extensionUIContext;
@@ -149,6 +184,10 @@ export class AgentSession {
     _cacheWarmer;
     // Tool registry for extension getTools/setTools
     _toolRegistry = new Map();
+    /** Created on the first `ctx.executeTool()` call. */
+    _nestedToolCalls;
+    /** Declared tools whose declarations requests leave out, from `prepareLoadout` hooks. */
+    _hiddenDeclarations = new Set();
     _toolDefinitions = new Map();
     _toolPromptSnippets = new Map();
     _toolPromptGuidelines = new Map();
@@ -170,8 +209,14 @@ export class AgentSession {
         }
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
-        this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
-        this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
+        this._usesDefaultTools = config.usesDefaultTools ?? false;
+        this._defaultToolModifiers = config.defaultToolModifiers ?? [];
+        if (config.allowedToolNames) {
+            this._allowedTools = createToolNameMatcher(config.allowedToolNames);
+            this._allowlistFiltersMcp =
+                config.allowedToolNames.length === 0 || config.allowedToolNames.some((entry) => entry.startsWith("mcp__"));
+        }
+        this._excludedTools = config.excludedToolNames ? createToolNameMatcher(config.excludedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
         this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
         // Always subscribe to agent events for internal handling
@@ -179,6 +224,9 @@ export class AgentSession {
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
         this._installAgentNextTurnRefresh();
+        this._installAgentRequestProjection();
+        this._installAgentBoundaryHooks();
+        this._installHiddenDeclarationsProjection();
         this._installAgentForcedPromptProjection();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
@@ -219,28 +267,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.
      *
@@ -250,65 +341,217 @@ 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;
-            if (!runner.hasHandlers("tool_result")) {
-                return undefined;
+        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,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw err;
             }
-            const hookResult = await runner.emitToolResult({
+            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,
-            });
-            if (!hookResult) {
-                return undefined;
-            }
-            return {
-                content: hookResult.content,
-                details: hookResult.details,
-                isError: hookResult.isError ?? isError,
-                usage: hookResult.usage,
-                terminate: hookResult.terminate,
-            };
+            })
+            : 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,
+            terminate: hookResult?.terminate,
         };
     }
+    /**
+     * 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(this.model));
+    }
     async _compactBeforeNextAssistantResponse(context) {
+        const projection = this.sessionManager.buildSessionProjection();
+        // A virtual selection is checked in prepareRequest, against the model the request is routed to.
         const model = this.model;
-        const settings = this.settingsManager.getCompactionSettings(model);
-        if (!model ||
-            model.contextWindow <= 0 ||
-            !shouldCompact(estimateContextTokens(context.messages).tokens, model.contextWindow, settings)) {
-            return context;
+        if (!model || isVirtualModel(model) || !this._exceedsCompactionThreshold(model, projection)) {
+            return { ...context, messages: projection.messages };
         }
         await this._runAutoCompaction("threshold", false);
-        return {
-            ...context,
-            messages: this.agent.state.messages.slice(),
+        return { ...context, messages: this.sessionManager.buildSessionProjection().messages };
+    }
+    _installAgentRequestProjection() {
+        const previousPrepareRequest = this.agent.prepareRequest;
+        this.agent.prepareRequest = async (request, signal) => {
+            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) {
+        this._lastActivityOutcome =
+            message.stopReason === "aborted" ? "aborted" : message.stopReason === "error" ? "error" : "completed";
+        const messageEntryId = this._findPersistedMessageEntryId(message);
+        if (!this._extensionRunner.hasHandlers("turn_end"))
+            return false;
+        if (!messageEntryId) {
+            this._extensionRunner.emitError({
+                extensionPath: "<boundary>",
+                event: "turn_end",
+                error: "turn_end could not resolve the persisted assistant entry ID",
+            });
+            return false;
+        }
+        const toolResultEntryIds = toolResults.flatMap((result) => {
+            const entryId = this._findPersistedMessageEntryId(result);
+            return entryId ? [entryId] : [];
+        });
+        const boundary = await this._extensionRunner.emitBoundary({
+            type: "turn_end",
+            turnIndex: this._turnIndex,
+            message,
+            toolResults,
+            messageEntryId,
+            toolResultEntryIds,
+            outcome: this._lastActivityOutcome,
+        }, (entries) => this._buildBoundaryContext(entries, "turn_end"));
+        this._commitBoundaryDrafts(boundary.entries);
+        if (boundary.continue && !this._buildBoundaryContext([], "turn_end").canContinue) {
+            this._reportInvalidBoundaryContinuation("turn_end");
+            return false;
+        }
+        return boundary.continue;
+    }
+    _installAgentBoundaryHooks() {
+        const previousFinishTurn = this.agent.finishTurn;
+        this.agent.finishTurn = async (turn, signal) => {
+            this._boundaryDispatchedMessages.add(turn.message);
+            const extensionContinue = await this._dispatchTurnEndBoundary(turn.message, turn.toolResults);
+            const previousDecision = await previousFinishTurn?.(turn, signal);
+            if (previousDecision?.action === "end")
+                return previousDecision;
+            if (extensionContinue || previousDecision?.action === "continue")
+                return { action: "continue" };
+            return undefined;
         };
     }
     _installAgentNextTurnRefresh() {
@@ -347,6 +590,84 @@ export class AgentSession {
     // =========================================================================
     // Event Subscription
     // =========================================================================
+    _refreshFinalizedContext() {
+        const projection = this.sessionManager.buildSessionProjection();
+        for (const entry of projection.entries) {
+            for (const message of entry.messages)
+                this._entryIdsByMessage.set(message, entry.sourceEntry.id);
+        }
+        this.agent.state.messages = projection.messages;
+    }
+    _applyBoundaryDrafts(manager, drafts) {
+        const appended = [];
+        for (const draft of drafts) {
+            let entryId;
+            switch (draft.type) {
+                case "custom":
+                    entryId = manager.appendCustomEntry(draft.customType, draft.data);
+                    break;
+                case "custom_message":
+                    entryId = manager.appendCustomMessageEntry(draft.customType, draft.content, draft.display, draft.details);
+                    break;
+                case "context_edit":
+                    entryId = manager.appendContextEdit(draft.targetId, draft.replacement);
+                    break;
+                case "compaction": {
+                    const tokensBefore = estimateProjectedContextTokens(manager.buildSessionProjection(), manager.getBranch()).tokens;
+                    entryId = manager.appendCompaction(draft.summary, draft.firstKeptEntryId, tokensBefore, draft.details, true, draft.usage);
+                    break;
+                }
+            }
+            const entry = manager.getEntry(entryId);
+            if (entry)
+                appended.push(entry);
+        }
+        return appended;
+    }
+    _createBoundaryPreviewManager(drafts) {
+        const header = this.sessionManager.getHeader();
+        if (!header)
+            throw new Error("Session header is missing");
+        const manager = SessionManager.inMemory(this._cwd, undefined, [header, ...this.sessionManager.getBranch()]);
+        this._applyBoundaryDrafts(manager, drafts);
+        return manager;
+    }
+    _getPendingBoundaryMessages() {
+        return [...this.agent.peekQueuedMessages(), ...this._pendingCustomMessages];
+    }
+    _buildBoundaryContext(drafts, boundary) {
+        const projection = this._createBoundaryPreviewManager(drafts).buildSessionProjection();
+        const pendingMessages = this._getPendingBoundaryMessages();
+        const llmMessages = convertToLlm(projection.messages);
+        const finalRole = llmMessages[llmMessages.length - 1]?.role;
+        const hasNonSystemContext = llmMessages.some((message) => message.role !== "system");
+        const contextCanContinue = hasNonSystemContext && finalRole !== "assistant";
+        const pendingCustomContext = this._pendingCustomMessages.length > 0;
+        return {
+            contextEntries: projection.entries,
+            contextMessages: projection.messages,
+            llmMessages,
+            pendingMessages,
+            canContinue: contextCanContinue ||
+                pendingCustomContext ||
+                (boundary === "turn_end"
+                    ? this.agent.hasQueuedMessages()
+                    : finalRole === "assistant" && this.agent.hasQueuedMessages()),
+        };
+    }
+    _commitBoundaryDrafts(drafts) {
+        const appended = this._applyBoundaryDrafts(this.sessionManager, drafts);
+        this._refreshFinalizedContext();
+        for (const entry of appended)
+            this._emit({ type: "entry_appended", entry });
+    }
+    _reportInvalidBoundaryContinuation(event) {
+        this._extensionRunner.emitError({
+            extensionPath: "<boundary>",
+            event,
+            error: `${event} requested continuation without runnable model context`,
+        });
+    }
     /** Emit an event to all listeners */
     _emit(event) {
         for (const l of this._eventListeners) {
@@ -385,56 +706,45 @@ export class AgentSession {
     async _emitAgentSettled() {
         this._cacheWarmer?.onAgentSettled();
         this._isAgentRunActive = false;
+        this._isEmittingAgentSettled = true;
         try {
-            await this._extensionRunner.emit({ type: "agent_settled" });
-            this._emit({ type: "agent_settled" });
-            await this._checkAutoHandoff();
+            const aborted = this._agentRunAbortRequested;
+            await this._extensionRunner.emit({ type: "agent_settled", aborted });
+            this._emit({ type: "agent_settled", aborted });
         }
         finally {
-            this._resolveIdleWaitIfIdle();
+            this._isEmittingAgentSettled = false;
         }
-    }
-    _autoHandoffTriggered = false;
-    async _checkAutoHandoff() {
-        if (!this.settingsManager.getAutoHandoffEnabled())
-            return;
-        const usage = this.getContextUsage();
-        if (!usage || usage.tokens === null)
-            return;
-        const threshold = this.settingsManager.getAutoHandoffThresholdTokens();
-        if (usage.tokens < threshold) {
-            this._autoHandoffTriggered = false;
-            return;
-        }
-        if (this._autoHandoffTriggered)
-            return;
-        // Auto-handoff is TUI-only: it runs at agent_settled, and headless/print
-        // modes should not churn sessions on their own. The handoff-new command
-        // itself now also works in non-TUI modes (direct generation, no loader).
-        if (this._extensionMode !== "tui")
-            return;
-        const command = this._extensionRunner.getCommand("handoff-new");
-        if (!command)
+        const deferred = this._deferredSettledActions.splice(0);
+        if (deferred.length > 0) {
+            try {
+                for (const action of deferred)
+                    await action();
+            }
+            finally {
+                this._resolveIdleWaitIfIdle();
+            }
             return;
-        this._autoHandoffTriggered = true;
-        const ctx = this._extensionRunner.createCommandContext();
-        try {
-            await command.handler(AUTO_HANDOFF_GOAL, ctx);
-        }
-        catch (err) {
-            // Retry on the next settled turn while the session remains above the threshold.
-            this._autoHandoffTriggered = false;
-            this._extensionRunner.emitError({
-                extensionPath: "command:handoff-new",
-                event: "auto-handoff",
-                error: err instanceof Error ? err.message : String(err),
-            });
         }
+        this._resolveIdleWaitIfIdle();
     }
-    // Track last assistant message for auto-compaction check
-    _lastAssistantMessage = undefined;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     _handleAgentEvent = async (event) => {
+        // 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") {
@@ -457,29 +767,30 @@ export class AgentSession {
                 }
             }
         }
-        // Emit to extensions first
+        // Emit to extensions first, then notify public listeners.
         await this._emitExtensionEvent(event);
-        // Notify all listeners
         this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
         // Handle session persistence
         if (event.type === "message_end") {
+            let entryId;
             // Check if this is a custom message from extensions
             if (event.message.role === "custom") {
                 // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+                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
-                this.sessionManager.appendMessage(event.message);
+                entryId = this.sessionManager.appendMessage(event.message);
             }
+            if (entryId)
+                this._entryIdsByMessage.set(event.message, entryId);
             // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
-            // Track assistant message for auto-compaction (checked on agent_end)
             if (event.message.role === "assistant") {
-                this._lastAssistantMessage = event.message;
                 const assistantMsg = event.message;
+                this._lastAssistantMessage = assistantMsg;
                 // A length stop is itself a recovery trigger, so it must not clear the
                 // one-shot overflow-recovery guard before the retry has run.
                 if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "length") {
@@ -508,6 +819,7 @@ export class AgentSession {
         // extension and listener dispatch above also picks up messages that turn_end
         // handlers queued.
         if (event.type === "turn_end") {
+            this._lastAssistantToolResults = event.toolResults;
             this._flushPendingCustomMessages();
         }
     };
@@ -526,6 +838,47 @@ export class AgentSession {
         }
         return false;
     }
+    _findPersistedMessageEntryId(message) {
+        const mapped = this._entryIdsByMessage.get(message);
+        if (mapped)
+            return mapped;
+        for (const entry of [...this.sessionManager.getBranch()].reverse()) {
+            if (entry.type === "message" && entry.message === message)
+                return entry.id;
+        }
+        const messageIndex = this.agent.state.messages.indexOf(message);
+        if (messageIndex < 0)
+            return undefined;
+        const projection = this.sessionManager.buildSessionProjection();
+        let projectedIndex = 0;
+        for (const entry of projection.entries) {
+            for (let i = 0; i < entry.messages.length; i++) {
+                if (projectedIndex === messageIndex) {
+                    this._entryIdsByMessage.set(message, entry.sourceEntry.id);
+                    return entry.sourceEntry.id;
+                }
+                projectedIndex++;
+            }
+        }
+        return undefined;
+    }
+    _omitRecoveryAttempt(message, toolResults = []) {
+        const targets = [message, ...toolResults];
+        const targetIds = targets.map((target) => this._findPersistedMessageEntryId(target));
+        const unresolvedProjectedTarget = targets.some((target, index) => targetIds[index] === undefined && this.agent.state.messages.includes(target));
+        if (unresolvedProjectedTarget) {
+            throw new Error("Cannot persist recovery omission because a projected message has no source entry");
+        }
+        for (const targetId of targetIds) {
+            if (!targetId)
+                continue;
+            const editId = this.sessionManager.appendContextEdit(targetId, null);
+            const entry = this.sessionManager.getEntry(editId);
+            if (entry)
+                this._emit({ type: "entry_appended", entry });
+        }
+        this._refreshFinalizedContext();
+    }
     /** Find the last assistant message in agent state (including aborted ones) */
     _findLastAssistantMessage() {
         const messages = this.agent.state.messages;
@@ -575,13 +928,9 @@ export class AgentSession {
             await this._extensionRunner.emit(extensionEvent);
         }
         else if (event.type === "turn_end") {
-            const extensionEvent = {
-                type: "turn_end",
-                turnIndex: this._turnIndex,
-                message: event.message,
-                toolResults: event.toolResults,
-            };
-            await this._extensionRunner.emit(extensionEvent);
+            if (event.message.role === "assistant" && !this._boundaryDispatchedMessages.delete(event.message)) {
+                await this._dispatchTurnEndBoundary(event.message, event.toolResults);
+            }
             this._turnIndex++;
         }
         else if (event.type === "message_start") {
@@ -645,6 +994,7 @@ export class AgentSession {
                 toolName: event.toolName,
                 result: event.result,
                 isError: event.isError,
+                ...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
             };
             await this._extensionRunner.emit(extensionEvent);
         }
@@ -664,26 +1014,13 @@ export class AgentSession {
             }
         };
     }
-    /**
-     * Temporarily disconnect from agent events.
-     * User listeners are preserved and will receive events again after resubscribe().
-     * Used internally during operations that need to pause event processing.
-     */
+    /** Disconnect from agent events during disposal. */
     _disconnectFromAgent() {
         if (this._unsubscribeAgent) {
             this._unsubscribeAgent();
             this._unsubscribeAgent = undefined;
         }
     }
-    /**
-     * Reconnect to agent events after _disconnectFromAgent().
-     * Preserves all existing listeners.
-     */
-    _reconnectToAgent() {
-        if (this._unsubscribeAgent)
-            return; // Already connected
-        this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
-    }
     /**
      * Remove all listeners and disconnect from agent.
      * Call this when completely done with the session.
@@ -711,6 +1048,10 @@ export class AgentSession {
     // =========================================================================
     // Read-only State Access
     // =========================================================================
+    /** Refresh the public finalized transcript from the canonical session projection. */
+    refreshContext() {
+        this._refreshFinalizedContext();
+    }
     /** Full agent state */
     get state() {
         return this.agent.state;
@@ -732,6 +1073,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;
@@ -749,12 +1098,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.
      */
@@ -764,7 +1117,9 @@ export class AgentSession {
             description: definition.description,
             parameters: definition.parameters,
             promptGuidelines: definition.promptGuidelines,
-            discovery: definition.discovery,
+            exposure: this._getToolExposure(definition.name),
+            ...(definition.namespace ? { namespace: definition.namespace } : {}),
+            ...(definition.annotations ? { annotations: { ...definition.annotations } } : {}),
             sourceInfo,
         }));
     }
@@ -773,22 +1128,113 @@ 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 previous = this.getActiveToolNames();
+        this._setActiveTools(toolNames);
+        // A loadout that deactivates a tool replaces the restored one, whose pending tools are dropped.
+        // One that only adds tools, like activating tool_search, keeps them.
+        const active = new Set(this.getActiveToolNames());
+        if (previous.some((name) => !active.has(name)))
+            this._pendingToolNames.clear();
+    }
+    _setActiveTools(toolNames) {
+        const tools = this._applyToolLoadout(toolNames);
+        for (const tool of tools)
+            this._pendingToolNames.delete(tool.name);
+        this._rebuildSystemPrompt(tools.map((tool) => tool.name));
+    }
+    /**
+     * Whether `--tools` and `--exclude-tools` keep the tool registered. MCP tools stay registered
+     * unless the allowlist filters them (see `_allowlistFiltersMcp`).
+     */
+    _isAllowedTool(name) {
+        if (this._excludedTools?.(name))
+            return false;
+        if (!this._allowedTools || this._allowedTools(name))
+            return true;
+        return !this._allowlistFiltersMcp && isMcpToolName(name);
+    }
+    /**
+     * Whether the tool may be active, which declares it to the model. MCP tools the allowlist keeps
+     * without matching them are only for codemode and tool_search: they may be declared only when
+     * tool_search can load them (non-`direct` exposure and tool_search registered). This also applies
+     * to tools restored from the transcript or set by extensions.
+     */
+    _isActivatable(name) {
+        if (!this._allowedTools || this._allowedTools(name) || !isMcpToolName(name))
+            return true;
+        return this._getToolExposure(name) !== "direct" && this._toolRegistry.has("tool_search");
+    }
+    _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" && this._isActivatable(name) ? [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,
+                getPromptGuidelines: (name) => this._toolPromptGuidelines.get(name) ?? [],
+            };
+            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() {
@@ -859,6 +1305,7 @@ export class AgentSession {
         const toolSnippets = {};
         for (const name of this._toolRegistry.keys()) {
             const snippet = this._toolPromptSnippets.get(name);
+            // Tools without a snippet are not listed.
             if (snippet)
                 toolSnippets[name] = snippet;
         }
@@ -876,6 +1323,7 @@ export class AgentSession {
             customPrompt: loaderSystemPrompt,
             appendSystemPrompt,
             selectedTools: validToolNames,
+            hiddenTools: [...this._hiddenDeclarations],
             toolSnippets,
             toolGuidelines: Object.fromEntries(this._toolPromptGuidelines),
         });
@@ -891,11 +1339,9 @@ 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);
+        // The tool list and rules must match the declarations the request carries.
+        options.hiddenTools = [...this._hiddenDeclarations];
         const sections = diffSystemPromptSections(getCurrentSystemMessage(messages)?.sections ?? {}, buildSystemPromptSections(options));
         return sections ? { role: "system", content: "", sections, timestamp: Date.now() } : undefined;
     }
@@ -909,6 +1355,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) => {
@@ -926,29 +1398,43 @@ 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() {
+        this._pendingToolNames.clear();
         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);
+        const names = (current.toolsAdded ?? []).map((tool) => tool.name);
+        this._pendingToolNames = new Set(names.filter((name) => this._isAllowedTool(name)));
+        this._setActiveTools(names);
     }
     // =========================================================================
     // 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();
+        // The run records the loadout in the transcript; restored tools that did not register by now
+        // are dropped, so a tool that never registers does not stay pending.
+        this._pendingToolNames.clear();
         this._isAgentRunActive = true;
         try {
             await this.agent.prompt(messages);
-            while (await this._handlePostAgentRun()) {
+            while (!this._agentRunAbortRequested) {
+                if (await this._handlePostAgentRun()) {
+                    if (this._agentRunAbortRequested)
+                        break;
+                    await this.agent.continue();
+                    continue;
+                }
+                if (this._agentRunAbortRequested || !(await this._runBeforeSettleBoundary()))
+                    break;
                 if (this._agentRunAbortRequested)
                     break;
                 await this.agent.continue();
@@ -957,6 +1443,7 @@ export class AgentSession {
         finally {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
+            this._failedResponse = undefined;
             this._runSystemPromptOptions = undefined;
             this._flushPendingBashMessages();
             this._flushPendingCustomMessages();
@@ -964,43 +1451,52 @@ export class AgentSession {
         }
     }
     async _handlePostAgentRun() {
-        const msg = this._lastAssistantMessage;
+        const message = this._lastAssistantMessage;
+        const toolResults = this._lastAssistantToolResults;
         this._lastAssistantMessage = undefined;
+        this._lastAssistantToolResults = [];
         if (this._agentRunAbortRequested) {
             this._finishCancelledRetry();
             return false;
         }
-        if (!msg) {
-            return false;
-        }
-        if (this._isRetryableError(msg) && (await this._prepareRetry(msg))) {
+        if (!message)
+            return this.agent.hasQueuedMessages();
+        if (this._isRetryableError(message) && (await this._prepareRetry(message))) {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
+            this._failedResponse = message;
             return !this._agentRunAbortRequested;
         }
         if (this._agentRunAbortRequested) {
             this._finishCancelledRetry();
             return false;
         }
-        if (msg.stopReason === "error" && this._retryAttempt > 0) {
+        if (message.stopReason === "error" && this._retryAttempt > 0) {
             this._emit({
                 type: "auto_retry_end",
                 success: false,
                 attempt: this._retryAttempt,
-                finalError: msg.errorMessage,
+                finalError: message.errorMessage,
             });
             this._retryAttempt = 0;
         }
-        if (await this._checkCompaction(msg)) {
+        if (await this._checkCompaction(message, true, toolResults)) {
             return !this._agentRunAbortRequested;
         }
         // A length stop means the model hit the output token limit mid-response.
         // The agent loop already re-prompts when truncated tool calls are present;
         // here the loop stopped on truncated text, so queue a follow-up to continue.
         // Compaction runs first: a length stop caused by context pressure (input
-        // filling the window) should compact instead of blindly continuing.
-        if (msg.stopReason === "length" &&
-            !msg.content.some((c) => c.type === "toolCall") &&
+        // filling the window) should compact instead of blindly continuing. Once
+        // durable recovery omits an attempt, a failed compaction must not fall
+        // through to continuation with that attempt absent from canonical context.
+        const lengthEntryId = message.stopReason === "length" ? this._findPersistedMessageEntryId(message) : undefined;
+        const lengthResponseRetained = lengthEntryId === undefined ||
+            this.sessionManager.buildSessionProjection().entries.some((entry) => entry.sourceEntry.id === lengthEntryId &&
+                entry.messages.some((projected) => projected.role === "assistant"));
+        if (message.stopReason === "length" &&
+            lengthResponseRetained &&
+            !message.content.some((c) => c.type === "toolCall") &&
             this._lengthContinuations < MAX_LENGTH_CONTINUATIONS) {
             this._lengthContinuations++;
             await this._queueFollowUp(LENGTH_CONTINUATION_MESSAGE);
@@ -1010,6 +1506,30 @@ export class AgentSession {
         // here were queued by agent_end extension handlers and need a continuation.
         return !this._agentRunAbortRequested && this.agent.hasQueuedMessages();
     }
+    async _runBeforeSettleBoundary() {
+        if (!this._extensionRunner.hasHandlers("agent_before_settle"))
+            return this.agent.hasQueuedMessages();
+        this._isBeforeSettle = true;
+        this._abortDuringBeforeSettle = false;
+        try {
+            const result = await this._extensionRunner.emitBoundary({ type: "agent_before_settle", outcome: this._lastActivityOutcome }, (entries) => this._buildBoundaryContext(entries, "agent_before_settle"));
+            this._commitBoundaryDrafts(result.entries);
+            this._flushPendingCustomMessages();
+            const finalContext = this._buildBoundaryContext([], "agent_before_settle");
+            if (this._abortDuringBeforeSettle)
+                return false;
+            const shouldContinue = result.continue || this.agent.hasQueuedMessages();
+            if (shouldContinue && !finalContext.canContinue) {
+                if (result.continue)
+                    this._reportInvalidBoundaryContinuation("agent_before_settle");
+                return false;
+            }
+            return shouldContinue;
+        }
+        finally {
+            this._isBeforeSettle = false;
+        }
+    }
     async _runInputHandlers(text, images, source, streamingBehavior) {
         if (!this._extensionRunner.hasHandlers("input")) {
             return { text, images };
@@ -1023,6 +1543,25 @@ export class AgentSession {
         }
         return { text, images };
     }
+    async _normalizePromptImages(images) {
+        if (!images)
+            return { images: [], hints: [] };
+        const normalizedImages = [];
+        const hints = [];
+        for (const image of images) {
+            const processed = await processImage(Buffer.from(image.data, "base64"), image.mimeType, {
+                autoResizeImages: this.settingsManager.getImageAutoResize(),
+                resizeOptions: this._limitsModel()?.inputLimits?.images?.resize,
+            });
+            if (!processed.ok) {
+                hints.push(processed.message);
+                continue;
+            }
+            normalizedImages.push({ type: "image", data: processed.data, mimeType: processed.mimeType });
+            hints.push(...processed.hints);
+        }
+        return { images: normalizedImages, hints };
+    }
     /**
      * Send a prompt to the agent.
      * - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming
@@ -1033,149 +1572,137 @@ export class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     async prompt(text, options) {
+        if (this._isEmittingAgentSettled) {
+            this._deferredSettledActions.push(async () => await this.prompt(text, options));
+            return;
+        }
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
-        let messages;
-        try {
-            // Handle extension commands first (execute immediately, even during streaming)
-            // Extension commands manage their own LLM interaction via pi.sendMessage()
-            if (expandPromptTemplates && text.startsWith("/")) {
-                const handled = await this._tryExecuteExtensionCommand(text);
-                if (handled) {
-                    // Extension command executed, no prompt to send
-                    preflightResult?.(true);
-                    return;
-                }
-            }
-            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);
+        // Handle extension commands first (execute immediately, even during streaming)
+        // Extension commands manage their own LLM interaction via pi.sendMessage()
+        if (expandPromptTemplates && text.startsWith("/")) {
+            const handled = await this._tryExecuteExtensionCommand(text);
+            if (handled) {
+                // Extension command executed, no prompt to send
+                preflightResult?.("handled");
                 return;
             }
-            const { text: currentText, images: currentImages } = processedInput;
-            // Expand skill commands (/skill:name args) and prompt templates (/template args)
-            let expandedText = currentText;
-            if (expandPromptTemplates) {
-                expandedText = this._expandSkillCommand(expandedText);
-                expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-            }
-            // Vision relay: when the active model cannot accept images, describe
-            // attached images with the configured caption model (images.imageCaptionModel)
-            // so the main model can work from the description text.
-            if (currentImages && currentImages.length > 0) {
-                const caption = await this._captionImagesForCurrentModel(currentImages, currentText);
-                if (caption) {
-                    expandedText += `\n\n${caption}`;
-                }
-            }
-            // If streaming, queue via steer() or followUp() based on option
-            if (this.isStreaming) {
-                if (!options?.streamingBehavior) {
-                    throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
-                }
-                if (options.streamingBehavior === "followUp") {
-                    await this._queueFollowUp(expandedText, currentImages);
-                }
-                else {
-                    await this._queueSteer(expandedText, currentImages);
-                }
-                preflightResult?.(true);
-                return;
+        }
+        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?.("handled");
+            return;
+        }
+        const { text: currentText, images: currentImages } = processedInput;
+        // Expand skill commands (/skill:name args) and prompt templates (/template args)
+        let expandedText = currentText;
+        if (expandPromptTemplates) {
+            expandedText = this._expandSkillCommand(expandedText);
+            expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        }
+        // Fork vision relay: non-vision models receive the configured caption as text.
+        if (currentImages && currentImages.length > 0) {
+            const caption = await this._captionImagesForCurrentModel(currentImages, currentText);
+            if (caption)
+                expandedText += `\n\n${caption}`;
+        }
+        // If streaming, queue via steer() or followUp() based on option
+        if (this.isStreaming) {
+            if (!options?.streamingBehavior) {
+                throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
             }
-            // Flush any pending bash and custom messages before the new prompt
-            this._flushPendingBashMessages();
-            this._flushPendingCustomMessages();
-            // Validate model
-            if (!this.model) {
-                throw new Error(formatNoModelSelectedMessage());
+            if (options.streamingBehavior === "followUp") {
+                await this._queueFollowUp(expandedText, currentImages);
             }
-            const hasConfiguredAuth = this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
-                (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;
-            if (!hasConfiguredAuth) {
-                const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
-                if (isOAuth) {
-                    throw new Error(`Authentication failed for "${this.model.provider}". ` +
-                        `Credentials may have expired or network is unavailable. ` +
-                        `Run '/login ${this.model.provider}' to re-authenticate.`);
-                }
-                throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
+            else {
+                await this._queueSteer(expandedText, currentImages);
             }
-            // Check if we need to compact before sending (catches aborted responses).
-            // The user's new prompt is sent below, so do not call agent.continue() here.
-            const lastAssistant = this._findLastAssistantMessage();
-            if (lastAssistant) {
-                await this._checkCompaction(lastAssistant, false);
+            preflightResult?.("queued");
+            return;
+        }
+        // Flush any pending bash and custom messages before the new prompt
+        this._flushPendingBashMessages();
+        this._flushPendingCustomMessages();
+        // Validate model
+        if (!this.model) {
+            throw new Error(formatNoModelSelectedMessage());
+        }
+        const hasConfiguredAuth = this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
+            (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;
+        if (!hasConfiguredAuth) {
+            const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
+            if (isOAuth) {
+                throw new Error(`Authentication failed for "${this.model.provider}". ` +
+                    `Credentials may have expired or network is unavailable. ` +
+                    `Run '/login ${this.model.provider}' to re-authenticate.`);
+            }
+            throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
+        }
+        // Check if we need to compact before sending (catches aborted responses).
+        // The user's new prompt is sent below, so do not call agent.continue() here.
+        const lastAssistant = this._findLastAssistantMessage();
+        if (lastAssistant) {
+            await this._checkCompaction(lastAssistant, false);
+        }
+        // Emit before_agent_start before normalizing images so extension-driven model
+        // selection determines the resize profile used for the request and history.
+        const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;
+        const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPromptOptions);
+        // Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),
+        // which updates the live loadout instead. An explicit edit wins; otherwise the live
+        // loadout is authoritative, so a setActiveTools() call is not undone here.
+        const handlerEditedTools = result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||
+            result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);
+        if (!handlerEditedTools)
+            result.systemPromptOptions.selectedTools = this.getActiveToolNames();
+        const normalized = await this._normalizePromptImages(currentImages);
+        const userText = normalized.hints.length > 0 ? `${expandedText}\n\n${normalized.hints.join("\n")}` : expandedText;
+        // Another prompt can start while input/caption/auth/hooks preflight awaits.
+        // Queue instead of racing it; do not consume pending next-turn messages yet.
+        if (this.isStreaming) {
+            if (options?.streamingBehavior === "steer") {
+                await this._queueSteer(expandedText, currentImages);
             }
-            // Build messages array (custom message if any, then user message)
-            messages = [];
-            // Add user message
-            const userContent = [{ type: "text", text: expandedText }];
-            if (currentImages) {
-                userContent.push(...currentImages);
+            else {
+                await this._queueFollowUp(expandedText, currentImages);
             }
+            preflightResult?.("queued");
+            return;
+        }
+        // Build messages only after hooks and image normalization have completed.
+        const messages = [];
+        const userContent = [{ type: "text", text: userText }];
+        userContent.push(...normalized.images);
+        messages.push({
+            role: "user",
+            content: userContent,
+            timestamp: Date.now(),
+        });
+        // Inject any pending "nextTurn" messages as context alongside the user message
+        for (const msg of this._pendingNextTurnMessages) {
+            messages.push(msg);
+        }
+        this._pendingNextTurnMessages = [];
+        for (const msg of result.messages) {
             messages.push({
-                role: "user",
-                content: userContent,
+                role: "custom",
+                customType: msg.customType,
+                // Untyped extensions can pass null/missing content; normalize at ingestion.
+                content: msg.content ?? [],
+                display: msg.display,
+                details: msg.details,
                 timestamp: Date.now(),
             });
-            // Inject any pending "nextTurn" messages as context alongside the user message
-            for (const msg of this._pendingNextTurnMessages) {
-                messages.push(msg);
-            }
-            this._pendingNextTurnMessages = [];
-            // Emit before_agent_start extension event
-            const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;
-            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPromptOptions);
-            // Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),
-            // which updates the live loadout instead. An explicit edit wins; otherwise the live
-            // loadout is authoritative, so a setActiveTools() call is not undone here.
-            const handlerEditedTools = result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||
-                result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);
-            if (!handlerEditedTools)
-                result.systemPromptOptions.selectedTools = this.getActiveToolNames();
-            for (const msg of result.messages) {
-                messages.push({
-                    role: "custom",
-                    customType: msg.customType,
-                    // Untyped extensions can pass null/missing content; normalize at ingestion.
-                    content: msg.content ?? [],
-                    display: msg.display,
-                    details: msg.details,
-                    timestamp: Date.now(),
-                });
-            }
-            // Another prompt may have started while this one was preflighting (auth
-            // checks, compaction, and extension events can take seconds). The agent is
-            // now streaming, so queue instead of racing the active run: the RPC layer
-            // has already reported preflight success, so throwing here would silently
-            // drop the message. Default to a follow-up so it runs after the current turn.
-            if (this.isStreaming) {
-                if (options?.streamingBehavior === "steer") {
-                    await this._queueSteer(expandedText, currentImages);
-                }
-                else {
-                    await this._queueFollowUp(expandedText, currentImages);
-                }
-                preflightResult?.(true);
-                return;
-            }
-            const updateMessage = this._preparePromptAndToolLoadout(result.systemPromptOptions);
-            this._runSystemPromptOptions = result.systemPromptOptions;
-            if (updateMessage)
-                messages.unshift(updateMessage);
-        }
-        catch (error) {
-            preflightResult?.(false);
-            throw error;
-        }
-        if (!messages) {
-            return;
         }
-        preflightResult?.(true);
+        const updateMessage = this._preparePromptAndToolLoadout(result.systemPromptOptions);
+        this._runSystemPromptOptions = result.systemPromptOptions;
+        if (updateMessage)
+            messages.unshift(updateMessage);
+        preflightResult?.("started");
         await this._runAgentPrompt(messages);
     }
     /**
@@ -1241,7 +1768,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") {
@@ -1250,6 +1777,7 @@ export class AgentSession {
         else {
             await this._queueFollowUp(expandedText, processedInput.images);
         }
+        return "queued";
     }
     /**
      * Queue a steering message while the agent is running.
@@ -1261,7 +1789,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.
@@ -1272,7 +1800,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).
@@ -1300,11 +1828,7 @@ export class AgentSession {
         if (images) {
             content.push(...images);
         }
-        this.agent.followUp({
-            role: "user",
-            content,
-            timestamp: Date.now(),
-        });
+        this.agent.followUp({ role: "user", content, timestamp: Date.now() });
     }
     /**
      * Throw an error if the text is an extension command.
@@ -1352,6 +1876,10 @@ export class AgentSession {
             }
         }
         else if (options?.triggerTurn) {
+            if (this._isEmittingAgentSettled) {
+                this._deferredSettledActions.push(async () => await this._runAgentPrompt(appMessage));
+                return;
+            }
             await this._runAgentPrompt(appMessage);
         }
         else if (this.isStreaming) {
@@ -1366,8 +1894,8 @@ export class AgentSession {
         }
     }
     _appendCustomMessage(appMessage) {
-        this.agent.state.messages.push(appMessage);
         this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
+        this._refreshFinalizedContext();
         this._emit({ type: "message_start", message: appMessage });
         this._emit({ type: "message_end", message: appMessage });
     }
@@ -1541,6 +2069,7 @@ export class AgentSession {
      *
      * @param content User message content (string or content array)
      * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
+     * @param options.expandPromptTemplates Whether to dispatch extension commands and expand skill commands and prompt templates. Default: false.
      */
     async sendUserMessage(content, options) {
         // Normalize content to text string + optional images
@@ -1564,7 +2093,6 @@ export class AgentSession {
             if (images.length === 0)
                 images = undefined;
         }
-        // Use prompt() with expandPromptTemplates to control command handling and template expansion
         await this.prompt(text, {
             expandPromptTemplates: options?.expandPromptTemplates ?? false,
             streamingBehavior: options?.deliverAs,
@@ -1622,6 +2150,8 @@ export class AgentSession {
         this.abortRetry();
         this.abortCompaction();
         this.abortBranchSummary();
+        if (this._isBeforeSettle)
+            this._abortDuringBeforeSettle = true;
         this.agent.abort();
         await this.waitForIdle();
     }
@@ -1646,7 +2176,8 @@ export class AgentSession {
     }
     /**
      * Set model directly.
-     * Validates that auth is configured, saves to session and settings.
+     * Validates that auth is configured and saves to the session transcript.
+     * Persists to global defaults only when options.persist is true.
      * @throws Error if no auth is configured for the model
      */
     async setModel(model, options = {}) {
@@ -1661,6 +2192,9 @@ export class AgentSession {
             this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
             this._addPersistedDefaultToNonEmptyScope(model);
         }
+        // Apply thinking level for the new model.
+        // Per-model thinking level overrides take priority over the global default.
+        // Model persistence does not implicitly rewrite the global thinking default.
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(model, previousModel, "set");
     }
@@ -1691,11 +2225,8 @@ export class AgentSession {
         return this._cycleAvailableModel(direction, options);
     }
     async _cycleScopedModel(direction, options) {
-        const checks = await Promise.all(this._scopedModels.map(async (scoped) => ({
-            scoped,
-            auth: await this._modelRuntime.checkAuth(scoped.model.provider),
-        })));
-        const scopedModels = checks.filter(({ auth }) => auth !== undefined).map(({ scoped }) => scoped);
+        const availableIds = new Set(this._modelRuntime.getAvailableSnapshot().map((model) => `${model.provider}\0${model.id}`));
+        const scopedModels = this._scopedModels.filter((scoped) => availableIds.has(`${scoped.model.provider}\0${scoped.model.id}`));
         if (scopedModels.length <= 1)
             return undefined;
         const currentModel = this.model;
@@ -1713,16 +2244,17 @@ export class AgentSession {
             this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
             this._addPersistedDefaultToNonEmptyScope(next.model);
         }
-        // Apply thinking level.
-        // - Explicit scoped model thinking level overrides current session level
-        // - Undefined scoped model thinking level inherits the current session preference
+        // Apply thinking level for the new model.
+        // - Explicit scoped model thinking level overrides defaults
+        // - Per-model thinking level overrides take priority over the global default
         // setThinkingLevel clamps to model capabilities.
+        // Model persistence does not implicitly rewrite the global thinking default.
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(next.model, currentModel, "cycle");
         return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
     }
     async _cycleAvailableModel(direction, options) {
-        const availableModels = await this._modelRuntime.getAvailable();
+        const availableModels = this._modelRuntime.getAvailableSnapshot();
         if (availableModels.length <= 1)
             return undefined;
         const currentModel = this.model;
@@ -1739,7 +2271,8 @@ export class AgentSession {
             this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
             this._addPersistedDefaultToNonEmptyScope(nextModel);
         }
-        // Re-clamp thinking level for new model's capabilities
+        // Apply thinking level for the new model.
+        // Model persistence does not implicitly rewrite the global thinking default.
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(nextModel, currentModel, "cycle");
         return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
@@ -1750,7 +2283,8 @@ export class AgentSession {
     /**
      * Set thinking level.
      * Clamps to model capabilities based on available thinking levels.
-     * Saves to session and settings only if the level actually changes.
+     * Saves the clamped level to the session transcript only if the level actually changes.
+     * Persists the requested level to global defaults only when options.persist is true.
      */
     setThinkingLevel(level, options = {}) {
         const availableLevels = this.getAvailableThinkingLevels();
@@ -1805,10 +2339,12 @@ export class AgentSession {
         if (explicitLevel !== undefined) {
             return explicitLevel;
         }
+        // Per-model default takes priority when switching to a model that has one
         if (targetModel) {
             const perModel = this.settingsManager.getModelThinkingLevel(targetModel.provider, targetModel.id);
-            if (perModel !== undefined)
+            if (perModel !== undefined) {
                 return perModel;
+            }
         }
         return this.settingsManager.getDefaultThinkingLevel() ?? this.thinkingLevel ?? DEFAULT_THINKING_LEVEL;
     }
@@ -1841,9 +2377,11 @@ export class AgentSession {
     // =========================================================================
     // Compaction
     // =========================================================================
-    /** Generate the 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);
+    /** Generate Pi's built-in compaction summary for manual and automatic compaction. */
+    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;
@@ -1851,11 +2389,20 @@ export class AgentSession {
     }
     /**
      * Manually compact the session context.
-     * Aborts current agent operation first.
+     *
+     * This is the manual entry point used by `/compact`, RPC, and extensions. It is
+     * separate from automatic threshold/overflow compaction, which enters through
+     * `_checkCompaction()` and `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * Aborts the current agent operation first. Manual compaction never retries or
+     * continues the interrupted agent turn.
+     *
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
-        this._disconnectFromAgent();
         await this.abort();
         this._compactionAbortController = new AbortController();
         this._emit({ type: "compaction_start", reason: "manual" });
@@ -1867,7 +2414,6 @@ export class AgentSession {
                 throw new Error(formatNoModelSelectedMessage());
             }
             const settings = this.settingsManager.getCompactionSettings(model);
-            const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, this._compactionAbortController.signal);
             const pathEntries = this.sessionManager.getBranch();
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
@@ -1879,7 +2425,6 @@ export class AgentSession {
                 throw new Error("Nothing to compact (session too small)");
             }
             let extensionCompaction;
-            let fromExtension = false;
             if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const result = (await this._extensionRunner.emit({
                     type: "session_before_compact",
@@ -1914,7 +2459,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;
@@ -1926,9 +2471,8 @@ export class AgentSession {
             }
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
             const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
             // Get the saved compaction entry for the extension event
             const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
             if (this._extensionRunner && savedCompactionEntry) {
@@ -1977,13 +2521,12 @@ export class AgentSession {
                 errorMessage,
                 aborted,
                 willRetry: false,
-                fromExtension: false,
+                fromExtension,
             });
             throw error;
         }
         finally {
             this._clearManualCompactionState();
-            this._reconnectToAgent();
         }
     }
     /**
@@ -2000,29 +2543,41 @@ export class AgentSession {
         this._branchSummaryAbortController?.abort();
     }
     /**
-     * Check if compaction is needed and run it.
-     * Called after agent_end and before prompt submission.
+     * Dispatch automatic compaction after `agent_end` or before prompt submission.
+     * Manual compaction does not call this method; it enters through `compact()`.
+     *
+     * Automatic cases:
+     * 1. Overflow with retry: a context-overflow error or recoverable length stop;
+     *    remove the failed assistant message, compact, and retry the turn once.
+     * 2. Overflow without retry: a successful response exceeded the configured
+     *    context window; compact but preserve the completed response.
+     * 3. Threshold without retry: valid or estimated context usage crossed the
+     *    configured threshold; compact without retrying the completed response.
      *
-     * Two cases:
-     * 1. Overflow: LLM returned context overflow error, remove error message from agent state, compact, auto-retry
-     * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
+     * Each case calls `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, that method calls the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
      *
      * @param assistantMessage The assistant message to check
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
      */
-    async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true, toolResults = []) {
         const settings = this.settingsManager.getCompactionSettings(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.
@@ -2034,54 +2589,89 @@ export class AgentSession {
         // Automatic cases 1 and 2: context overflow.
         // A length stop is recoverable when output ended below the model's original desired limit,
         // independent of the configured context size or any context-clamped provider request limit.
-        const contextOverflow = sameModel && isContextOverflow(assistantMessage, contextWindow);
-        const recoverableLength = sameModel && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
+        const currentProjection = this.sessionManager.buildSessionProjection();
+        const assistantEntryId = this._findPersistedMessageEntryId(assistantMessage);
+        const assistantIsProjected = assistantEntryId === undefined ||
+            currentProjection.entries.some((entry) => entry.sourceEntry.id === assistantEntryId &&
+                entry.messages.some((message) => message.role === "assistant"));
+        const branch = this.sessionManager.getBranch();
+        const assistantIndex = assistantEntryId ? branch.findIndex((entry) => entry.id === assistantEntryId) : -1;
+        const entriesAfterAssistant = assistantIndex >= 0 ? branch.slice(assistantIndex + 1) : [];
+        const hasPostAssistantContextEdit = entriesAfterAssistant.some((entry) => entry.type === "context_edit");
+        const latestAssistantEdit = entriesAfterAssistant
+            .filter((entry) => entry.type === "context_edit" && entry.targetId === assistantEntryId)
+            .at(-1);
+        const assistantRetainedForExplicitRecovery = assistantEntryId === undefined ||
+            (!entriesAfterAssistant.some((entry) => entry.type === "compaction") &&
+                latestAssistantEdit?.replacement !== null);
+        const assistantUsageMatchesProjection = assistantIsProjected && !hasPostAssistantContextEdit;
+        const explicitOverflow = assistantMessage.stopReason === "error" && isContextOverflow(assistantMessage);
+        const contextOverflow = sameModel &&
+            ((explicitOverflow && assistantRetainedForExplicitRecovery) ||
+                (assistantUsageMatchesProjection && isContextOverflow(assistantMessage, contextWindow)));
+        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
+            // agent.continue() cannot continue from a completed assistant response.
             if (!willRetry) {
                 return await this._runAutoCompaction("overflow", false);
             }
             if (this._overflowRecoveryAttempted) {
+                const errorMessage = contextOverflow
+                    ? "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model."
+                    : "Truncated response recovery failed after one compact-and-retry attempt.";
                 this._emit({
                     type: "compaction_end",
                     reason: "overflow",
                     result: undefined,
                     aborted: false,
                     willRetry: false,
-                    errorMessage: contextOverflow
-                        ? "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model."
-                        : "Truncated response recovery failed after one compact-and-retry attempt.",
+                    errorMessage,
+                });
+                await this._emitSessionCompactFailed({
+                    reason: "overflow",
+                    errorMessage,
+                    aborted: false,
+                    willRetry: false,
+                    fromExtension: false,
                 });
                 return false;
             }
+            // Persistently omit the selected final attempt before post-run recovery compaction.
             this._overflowRecoveryAttempted = true;
-            // Remove the error message from agent state (it IS saved to session for history,
-            // but we don't want it in context for the retry)
-            const messages = this.agent.state.messages;
-            if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-                this.agent.state.messages = messages.slice(0, -1);
-            }
-            return await this._runAutoCompaction("overflow", willRetry);
+            this._omitRecoveryAttempt(assistantMessage, toolResults);
+            const retry = await this._runAutoCompaction("overflow", willRetry);
+            if (retry)
+                this._failedResponse = assistantMessage;
+            return retry;
         }
-        // Case 2: Threshold - context is getting large
+        // Case 3: threshold compaction without retry.
         // For error messages or all-zero usage messages, estimate from the last valid response.
         // This ensures sessions that hit persistent API errors (e.g. 529) or malformed zero-usage
         // responses can still compact and do not reset context accounting.
         let contextTokens;
+        const projection = currentProjection;
+        const hasContextEdits = projection.entries.some((entry) => entry.sourceEntry.type === "context_edit");
         const directContextTokens = assistantMessage.usage ? calculateContextTokens(assistantMessage.usage) : 0;
-        if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
+        if (hasContextEdits) {
+            contextTokens = estimateProjectedContextTokens(projection, branch).tokens;
+        }
+        else if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
             const messages = this.agent.state.messages;
             const estimate = estimateContextTokens(messages);
-            if (estimate.lastUsageIndex === null)
-                return false; // No usage data at all
-            // Verify the usage source is post-compaction. Kept pre-compaction messages
-            // have stale usage reflecting the old (larger) context and would falsely
-            // trigger compaction right after one just finished.
-            const usageMsg = messages[estimate.lastUsageIndex];
-            if (compactionEntry &&
-                usageMsg.role === "assistant" &&
-                usageMsg.timestamp <= new Date(compactionEntry.timestamp).getTime()) {
-                return false;
+            // Without provider usage, estimate.tokens is the pure message-size estimate.
+            // Only usage-backed estimates need the stale pre-compaction check.
+            if (estimate.lastUsageIndex !== null) {
+                // Verify the usage source is post-compaction. Kept pre-compaction messages
+                // have stale usage reflecting the old (larger) context and would falsely
+                // trigger compaction right after one just finished.
+                const usageMsg = messages[estimate.lastUsageIndex];
+                if (compactionEntry &&
+                    usageMsg.role === "assistant" &&
+                    usageMsg.timestamp <= new Date(compactionEntry.timestamp).getTime()) {
+                    return false;
+                }
             }
             contextTokens = estimate.tokens;
         }
@@ -2094,7 +2684,14 @@ export class AgentSession {
         return false;
     }
     /**
-     * Internal: Run auto-compaction with events.
+     * Execute threshold or overflow compaction. Manual compaction uses
+     * `AgentSession.compact()` instead. Both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts` after preparation and extension
+     * interception.
+     *
+     * @param reason Automatic trigger selected by `_checkCompaction()`
+     * @param willRetry Whether to continue the interrupted turn after overflow compaction
+     * @returns Whether the post-run loop should call `agent.continue()`
      */
     async _runAutoCompaction(reason, willRetry) {
         const model = this.model;
@@ -2117,8 +2714,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({
@@ -2155,7 +2750,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;
@@ -2165,9 +2760,8 @@ export class AgentSession {
             abortController.signal.throwIfAborted();
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
             const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
             // Get the saved compaction entry for the extension event
             const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
             if (this._extensionRunner && savedCompactionEntry) {
@@ -2188,18 +2782,8 @@ export class AgentSession {
                 details,
             };
             this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-            if (willRetry) {
-                const messages = this.agent.state.messages;
-                const lastMsg = messages[messages.length - 1];
-                // The overflow response was persisted on message_end before _checkCompaction() removed it
-                // from agent state. Rebuilding state from the new compaction can restore that kept entry,
-                // leaving an assistant as the final message. agent.continue() rejects that state, so remove
-                // the retriable error or truncated-length response again before continuing the interrupted turn.
-                if (lastMsg?.role === "assistant" && (lastMsg.stopReason === "error" || lastMsg.stopReason === "length")) {
-                    this.agent.state.messages = messages.slice(0, -1);
-                }
+            if (willRetry)
                 return true;
-            }
             // Auto-compaction can complete while follow-up/steering/custom messages are waiting.
             // Continue once so queued messages are delivered.
             return this.agent.hasQueuedMessages();
@@ -2248,12 +2832,6 @@ export class AgentSession {
     get autoCompactionEnabled() {
         return this.settingsManager.getCompactionEnabled();
     }
-    get autoHandoffEnabled() {
-        return this.settingsManager.getAutoHandoffEnabled();
-    }
-    get autoHandoffThresholdTokens() {
-        return this.settingsManager.getAutoHandoffThresholdTokens();
-    }
     async bindExtensions(bindings) {
         if (bindings.uiContext !== undefined) {
             this._extensionUIContext = bindings.uiContext;
@@ -2275,6 +2853,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) {
@@ -2296,7 +2875,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: {
@@ -2309,7 +2888,7 @@ export class AgentSession {
         });
     }
     getExtensionSourceLabel(extensionPath) {
-        if (extensionPath.startsWith("<")) {
+        if (isSyntheticPath(extensionPath)) {
             return `extension:${extensionPath.replace(/[<>]/g, "")}`;
         }
         const base = basename(extensionPath);
@@ -2394,6 +2973,7 @@ export class AgentSession {
             },
             getActiveTools: () => this.getActiveToolNames(),
             getAllTools: () => this.getAllTools(),
+            getSettings: () => this.settingsManager.getSettings(),
             setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),
             getResolvedSkills: () => this._resourceLoader.getResolvedSkills().map((resource) => {
                 const skill = this._resourceLoader.getSkills().skills.find((s) => s.filePath === resource.path);
@@ -2452,6 +3032,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);
@@ -2465,14 +3047,22 @@ 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;
-        const isAllowedTool = (name) => (!allowedToolNames || allowedToolNames.has(name)) && !excludedToolNames?.has(name);
+        const allowedTools = this._allowedTools;
         const registeredTools = this._extensionRunner.getAllRegisteredTools();
         const allCustomTools = [
             ...registeredTools,
@@ -2480,14 +3070,14 @@ export class AgentSession {
                 definition,
                 sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
             })),
-        ].filter((tool) => isAllowedTool(tool.definition.name));
+        ].filter((tool) => this._isAllowedTool(tool.definition.name));
         const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries())
-            .filter(([name]) => isAllowedTool(name))
+            .filter(([name]) => this._isAllowedTool(name))
             .map(([name, definition]) => [
             name,
             {
                 definition,
-                sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
+                sourceInfo: createSyntheticSourceInfo(`${BUILTIN_PATH_PREFIX}${name}`, { source: "builtin" }),
             },
         ]));
         for (const tool of allCustomTools) {
@@ -2512,37 +3102,53 @@ export class AgentSession {
         const runner = this._extensionRunner;
         const wrappedExtensionTools = wrapRegisteredTools(allCustomTools, runner);
         const wrappedBuiltInTools = wrapRegisteredTools(Array.from(this._baseToolDefinitions.values())
-            .filter((definition) => isAllowedTool(definition.name))
+            .filter((definition) => this._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) {
             toolRegistry.set(tool.name, tool);
         }
         this._toolRegistry = toolRegistry;
-        const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => isAllowedTool(name));
-        if (allowedToolNames) {
+        const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => this._isAllowedTool(name));
+        if (allowedTools) {
             for (const toolName of this._toolRegistry.keys()) {
-                if (allowedToolNames.has(toolName)) {
+                // Naming or matching a tool activates it even when it is not active by default. MCP tools
+                // kept registered without being named stay inactive.
+                if (allowedTools(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);
                 }
             }
         }
-        this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
+        // Pending tools that are registered now become active.
+        nextActiveToolNames.push(...this._pendingToolNames);
+        this._setActiveTools([...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();
@@ -2581,15 +3187,28 @@ export class AgentSession {
         });
     }
     async reload(options) {
-        const previousFlagValues = this._extensionRunner.getFlagValues();
-        await emitSessionShutdownEvent(this._extensionRunner, { type: "session_shutdown", reason: "reload" });
+        const oldRunner = this._extensionRunner;
+        const previousFlagValues = oldRunner.getFlagValues();
+        await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });
+        oldRunner.invalidate();
+        const getDefaultTools = () => this._usesDefaultTools
+            ? applyToolModifiers(this.settingsManager.getDefaultTools() ?? DEFAULT_TOOL_NAMES, this._defaultToolModifiers)
+            : [];
+        const previousDefaultTools = new Set(getDefaultTools());
         await this.settingsManager.reload();
         this.syncQueueModesFromSettings();
         resetApiProviders();
         await this._resourceLoader.reload();
+        // Activate tools newly added to defaultTools. Removed ones stay active, and tools disabled
+        // during the session stay disabled unless the setting newly adds them.
+        const addedDefaultTools = getDefaultTools().filter((name) => !previousDefaultTools.has(name));
+        // Tools the new extensions register later, such as MCP tools, are pending until then.
+        for (const name of this.getActiveToolNames())
+            this._pendingToolNames.add(name);
         this._buildRuntime({
-            activeToolNames: this.getActiveToolNames(),
+            activeToolNames: [...this.getActiveToolNames(), ...addedDefaultTools],
             flagValues: previousFlagValues,
+            includeAllExtensionTools: true,
         });
         const hasBindings = this._extensionUIContext ||
             this._extensionCommandContextActions ||
@@ -2598,6 +3217,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");
         }
     }
@@ -2610,7 +3230,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);
     }
@@ -2677,11 +3297,8 @@ export class AgentSession {
             delayMs,
             errorMessage: message.errorMessage || "Unknown error",
         });
-        // Remove error message from agent state (keep in session for history)
-        const messages = this.agent.state.messages;
-        if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-            this.agent.state.messages = messages.slice(0, -1);
-        }
+        // Keep the failed attempt in raw history while durably omitting it from model projection.
+        this._omitRecoveryAttempt(message);
         // Wait with exponential backoff (abortable)
         this._retryAbortController = new AbortController();
         try {
@@ -2773,10 +3390,8 @@ export class AgentSession {
             this._pendingBashMessages.push(bashMessage);
         }
         else {
-            // Add to agent state immediately
-            this.agent.state.messages.push(bashMessage);
-            // Save to session
             this.sessionManager.appendMessage(bashMessage);
+            this._refreshFinalizedContext();
         }
     }
     /**
@@ -2803,12 +3418,10 @@ export class AgentSession {
         if (this._pendingBashMessages.length === 0)
             return;
         for (const bashMessage of this._pendingBashMessages) {
-            // Add to agent state
-            this.agent.state.messages.push(bashMessage);
-            // Save to session
             this.sessionManager.appendMessage(bashMessage);
         }
         this._pendingBashMessages = [];
+        this._refreshFinalizedContext();
     }
     // =========================================================================
     // Session Management
@@ -2818,9 +3431,9 @@ export class AgentSession {
      */
     setSessionName(name) {
         this.sessionManager.appendSessionInfo(name);
-        const sessionName = this.sessionManager.getSessionName();
-        this._emit({ type: "session_info_changed", name: sessionName });
-        void this._extensionRunner.emit({ type: "session_info_changed", name: sessionName });
+        const event = { type: "session_info_changed", name: this.sessionManager.getSessionName() };
+        this._emit(event);
+        void this._extensionRunner.emit(event);
     }
     // =========================================================================
     // Tree Navigation
@@ -2907,15 +3520,11 @@ export class AgentSession {
             let summaryDetails;
             let summaryUsage;
             if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
-                const model = this.model;
-                const { apiKey, headers, env } = await this._getSummarizationRequestAuth(model);
+                const signal = this._branchSummaryAbortController.signal;
                 const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
                 const result = await generateBranchSummary(entriesToSummarize, {
-                    model,
-                    apiKey,
-                    headers,
-                    env,
-                    signal: this._branchSummaryAbortController.signal,
+                    ...(await this._getSummarizationRequestAuth(this.model, signal)),
+                    signal,
                     customInstructions,
                     replaceInstructions,
                     reserveTokens: branchSummarySettings.reserveTokens,
@@ -2982,9 +3591,8 @@ export class AgentSession {
             if (label && !summaryText) {
                 this.sessionManager.appendLabelChange(targetId, label);
             }
-            // Update agent state
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
+            // Update finalized context from the canonical session projection.
+            this._refreshFinalizedContext();
             this._restoreToolsFromTranscript();
             // Emit session_tree event (extension runners + RPC stdout subscribers)
             const treeEvent = {
@@ -3083,7 +3691,7 @@ export class AgentSession {
         };
     }
     getContextUsage() {
-        const model = this.model;
+        const model = this._limitsModel();
         if (!model)
             return undefined;
         const contextWindow = model.contextWindow ?? 0;
@@ -3092,30 +3700,24 @@ export class AgentSession {
         // After compaction, the last assistant usage reflects pre-compaction context size.
         // We can only trust usage from an assistant that responded after the latest compaction.
         // If no such assistant exists, context token count is unknown until the next LLM response.
-        const branchEntries = this.sessionManager.getBranch();
-        const latestCompaction = getLatestCompactionEntry(branchEntries);
+        const projection = this.sessionManager.buildSessionProjection();
+        const branch = this.sessionManager.getBranch();
+        const latestCompaction = getLatestCompactionEntry(branch);
         if (latestCompaction) {
-            // Check if there's a valid assistant usage after the compaction boundary
-            const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
-            let hasPostCompactionUsage = false;
-            for (let i = branchEntries.length - 1; i > compactionIndex; i--) {
-                const entry = branchEntries[i];
-                if (entry.type === "message" && entry.message.role === "assistant") {
-                    const assistant = entry.message;
-                    if (assistant.stopReason !== "aborted" && assistant.stopReason !== "error") {
-                        const contextTokens = calculateContextTokens(assistant.usage);
-                        if (contextTokens > 0) {
-                            hasPostCompactionUsage = true;
-                            break;
-                        }
-                    }
-                }
-            }
-            if (!hasPostCompactionUsage) {
+            const projectedAssistants = new Set(projection.entries.flatMap((entry) => entry.messages.some((message) => message.role === "assistant" &&
+                message.stopReason !== "aborted" &&
+                message.stopReason !== "error" &&
+                calculateContextTokens(message.usage) > 0)
+                ? [entry.sourceEntry.id]
+                : []));
+            const compactionIndex = branch.findIndex((entry) => entry.id === latestCompaction.id);
+            const hasPostCompactionUsage = branch
+                .slice(compactionIndex + 1)
+                .some((entry) => projectedAssistants.has(entry.id));
+            if (!hasPostCompactionUsage)
                 return { tokens: null, contextWindow, percent: null };
-            }
         }
-        const estimate = estimateContextTokens(this.messages);
+        const estimate = estimateProjectedContextTokens(projection, branch);
         const percent = (estimate.tokens / contextWindow) * 100;
         return {
             tokens: estimate.tokens,
@@ -3126,13 +3728,14 @@ export class AgentSession {
     /**
      * Export session to HTML.
      * @param outputPath Optional output path (defaults to session directory)
+     * @param options Optional export presentation settings
      * @returns Path to exported file
      */
     async exportToHtml(outputPath, options = {}) {
         const themeName = [options.themeName, this.settingsManager.getTheme()].find((candidate) => candidate !== undefined && getThemeByName(candidate) !== undefined);
         // Create tool renderer if we have an extension runner (for custom tool HTML rendering)
         const toolRenderer = createToolHtmlRenderer({
-            getToolDefinition: (name) => this.getToolDefinition(name),
+            getToolRenderers: (name) => this._extensionRunner.resolveToolRenderers(name, () => this.getToolDefinition(name)),
             theme,
             cwd: this.sessionManager.getCwd(),
         });
@@ -3149,29 +3752,7 @@ export class AgentSession {
      * @returns The resolved output file path.
      */
     exportToJsonl(outputPath) {
-        const filePath = resolvePath(outputPath ?? `session-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`, process.cwd());
-        const dir = dirname(filePath);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        const header = {
-            type: "session",
-            version: CURRENT_SESSION_VERSION,
-            id: this.sessionManager.getSessionId(),
-            timestamp: new Date().toISOString(),
-            cwd: this.sessionManager.getCwd(),
-        };
-        const branchEntries = this.sessionManager.getBranch();
-        const lines = [JSON.stringify(header)];
-        // Re-chain parentIds to form a linear sequence
-        let prevId = null;
-        for (const entry of branchEntries) {
-            const linear = { ...entry, parentId: prevId };
-            lines.push(JSON.stringify(linear));
-            prevId = entry.id;
-        }
-        writeFileSync(filePath, `${lines.join("\n")}\n`);
-        return filePath;
+        return exportSessionToJsonl(this.sessionManager, outputPath);
     }
     /**
      * Ask the current model to describe what went wrong in this session for a bug report.
@@ -3182,16 +3763,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,