@phi-code-admin/phi-code 0.74.2 → 0.75.0

package/dist/core/agent-session.js

@@ -12,24 +12,27 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import { readFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { isContextOverflow, modelsAreEqual, resetApiProviders, supportsXhigh } from "phi-code-ai";
-import { getDocsPath } from "../config.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, } from "phi-code-ai";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { sleep } from "../utils/sleep.js";
-import { executeBash as executeBashCommand, executeBashWithOperations } from "./bash-executor.js";
+import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
+import { executeBashWithOperations } from "./bash-executor.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
-import { ExtensionRunner, wrapRegisteredTools, wrapToolsWithExtensions, } from "./extensions/index.js";
+import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
+import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { getLatestCompactionEntry } from "./session-manager.js";
-import { BUILTIN_SLASH_COMMANDS } from "./slash-commands.js";
+import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
+import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
-import { createAllTools } from "./tools/index.js";
+import { createLocalBashOperations } from "./tools/bash.js";
+import { createAllToolDefinitions } from "./tools/index.js";
+import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -50,59 +53,66 @@ export function parseSkillBlock(text) {
 // ============================================================================
 /** Standard thinking levels */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
-/** Thinking levels including xhigh (for supported models) */
-const THINKING_LEVELS_WITH_XHIGH = ["off", "minimal", "low", "medium", "high", "xhigh"];
 // ============================================================================
 // AgentSession Class
 // ============================================================================
 export class AgentSession {
+    agent;
+    sessionManager;
+    settingsManager;
+    _scopedModels;
+    // Event subscription state
+    _unsubscribeAgent;
+    _eventListeners = [];
+    _agentEventQueue = Promise.resolve();
+    /** Tracks pending steering messages for UI display. Removed when delivered. */
+    _steeringMessages = [];
+    /** Tracks pending follow-up messages for UI display. Removed when delivered. */
+    _followUpMessages = [];
+    /** Messages queued to be included with the next user prompt as context ("asides"). */
+    _pendingNextTurnMessages = [];
+    // Compaction state
+    _compactionAbortController = undefined;
+    _autoCompactionAbortController = undefined;
+    _overflowRecoveryAttempted = false;
+    // Branch summarization state
+    _branchSummaryAbortController = undefined;
+    // Retry state
+    _retryAbortController = undefined;
+    _retryAttempt = 0;
+    _retryPromise = undefined;
+    _retryResolve = undefined;
+    // Bash execution state
+    _bashAbortController = undefined;
+    _pendingBashMessages = [];
+    // Extension system
+    _extensionRunner;
+    _turnIndex = 0;
+    _resourceLoader;
+    _customTools;
+    _baseToolDefinitions = new Map();
+    _cwd;
+    _extensionRunnerRef;
+    _initialActiveToolNames;
+    _allowedToolNames;
+    _baseToolsOverride;
+    _sessionStartEvent;
+    _extensionUIContext;
+    _extensionCommandContextActions;
+    _extensionShutdownHandler;
+    _extensionErrorListener;
+    _extensionErrorUnsubscriber;
+    // Model registry for API key resolution
+    _modelRegistry;
+    // Tool registry for extension getTools/setTools
+    _toolRegistry = new Map();
+    _toolDefinitions = new Map();
+    _toolPromptSnippets = new Map();
+    _toolPromptGuidelines = new Map();
+    // Base system prompt (without extension appends) - used to apply fresh appends each turn
+    _baseSystemPrompt = "";
+    _baseSystemPromptOptions;
     constructor(config) {
-        this._eventListeners = [];
-        this._agentEventQueue = Promise.resolve();
-        /** Tracks pending steering messages for UI display. Removed when delivered. */
-        this._steeringMessages = [];
-        /** Tracks pending follow-up messages for UI display. Removed when delivered. */
-        this._followUpMessages = [];
-        /** Messages queued to be included with the next user prompt as context ("asides"). */
-        this._pendingNextTurnMessages = [];
-        // Compaction state
-        this._compactionAbortController = undefined;
-        this._autoCompactionAbortController = undefined;
-        this._overflowRecoveryAttempted = false;
-        // Branch summarization state
-        this._branchSummaryAbortController = undefined;
-        // Retry state
-        this._retryAbortController = undefined;
-        this._retryAttempt = 0;
-        this._retryPromise = undefined;
-        this._retryResolve = undefined;
-        // Bash execution state
-        this._bashAbortController = undefined;
-        this._pendingBashMessages = [];
-        // Extension system
-        this._extensionRunner = undefined;
-        this._turnIndex = 0;
-        this._baseToolRegistry = new Map();
-        // Tool registry for extension getTools/setTools
-        this._toolRegistry = new Map();
-        this._toolPromptSnippets = new Map();
-        this._toolPromptGuidelines = new Map();
-        // Base system prompt (without extension appends) - used to apply fresh appends each turn
-        this._baseSystemPrompt = "";
-        // Track last assistant message for auto-compaction check
-        this._lastAssistantMessage = undefined;
-        /** Internal handler for agent events - shared by subscribe and reconnect */
-        this._handleAgentEvent = (event) => {
-            // Create retry promise synchronously before queueing async processing.
-            // Agent.emit() calls this handler synchronously, and prompt() calls waitForRetry()
-            // as soon as agent.prompt() resolves. If _retryPromise is created only inside
-            // _processAgentEvent, slow earlier queued events can delay agent_end processing
-            // and waitForRetry() can miss the in-flight retry.
-            this._createRetryPromiseForAgentEnd(event);
-            this._agentEventQueue = this._agentEventQueue.then(() => this._processAgentEvent(event), () => this._processAgentEvent(event));
-            // Keep queue alive if an event handler fails
-            this._agentEventQueue.catch(() => { });
-        };
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
@@ -113,10 +123,13 @@ export class AgentSession {
         this._modelRegistry = config.modelRegistry;
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
+        this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
+        this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
         // Always subscribe to agent events for internal handling
         // (session persistence, extensions, auto-compaction, retry logic)
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
+        this._installAgentToolHooks();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
             includeAllExtensionTools: true,
@@ -126,6 +139,79 @@ export class AgentSession {
     get modelRegistry() {
         return this._modelRegistry;
     }
+    async _getRequiredRequestAuth(model) {
+        const result = await this._modelRegistry.getApiKeyAndHeaders(model);
+        if (!result.ok) {
+            if (result.error.startsWith("No API key found")) {
+                throw new Error(formatNoApiKeyFoundMessage(model.provider));
+            }
+            throw new Error(result.error);
+        }
+        if (result.apiKey) {
+            return { apiKey: result.apiKey, headers: result.headers };
+        }
+        const isOAuth = this._modelRegistry.isUsingOAuth(model);
+        if (isOAuth) {
+            throw new Error(`Authentication failed for "${model.provider}". ` +
+                `Credentials may have expired or network is unavailable. ` +
+                `Run '/login ${model.provider}' to re-authenticate.`);
+        }
+        throw new Error(formatNoApiKeyFoundMessage(model.provider));
+    }
+    /**
+     * Install tool hooks once on the Agent instance.
+     *
+     * The callbacks read `this._extensionRunner` at execution time, so extension reload swaps in the
+     * new runner without reinstalling hooks. Extension-specific tool wrappers are still used to adapt
+     * registered tool execution to the extension context. Tool call and tool result interception now
+     * happens here instead of in wrappers.
+     */
+    _installAgentToolHooks() {
+        this.agent.beforeToolCall = async ({ toolCall, args }) => {
+            const runner = this._extensionRunner;
+            if (!runner.hasHandlers("tool_call")) {
+                return undefined;
+            }
+            await this._agentEventQueue;
+            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;
+            }
+            const hookResult = await runner.emitToolResult({
+                type: "tool_result",
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                input: args,
+                content: result.content,
+                details: result.details,
+                isError,
+            });
+            if (!hookResult) {
+                return undefined;
+            }
+            return {
+                content: hookResult.content,
+                details: hookResult.details,
+                isError: hookResult.isError ?? isError,
+            };
+        };
+    }
     // =========================================================================
     // Event Subscription
     // =========================================================================
@@ -135,6 +221,27 @@ export class AgentSession {
             l(event);
         }
     }
+    _emitQueueUpdate() {
+        this._emit({
+            type: "queue_update",
+            steering: [...this._steeringMessages],
+            followUp: [...this._followUpMessages],
+        });
+    }
+    // Track last assistant message for auto-compaction check
+    _lastAssistantMessage = undefined;
+    /** Internal handler for agent events - shared by subscribe and reconnect */
+    _handleAgentEvent = (event) => {
+        // Create retry promise synchronously before queueing async processing.
+        // Agent.emit() calls this handler synchronously, and prompt() calls waitForRetry()
+        // as soon as agent.prompt() resolves. If _retryPromise is created only inside
+        // _processAgentEvent, slow earlier queued events can delay agent_end processing
+        // and waitForRetry() can miss the in-flight retry.
+        this._createRetryPromiseForAgentEnd(event);
+        this._agentEventQueue = this._agentEventQueue.then(() => this._processAgentEvent(event), () => this._processAgentEvent(event));
+        // Keep queue alive if an event handler fails
+        this._agentEventQueue.catch(() => { });
+    };
     _createRetryPromiseForAgentEnd(event) {
         if (event.type !== "agent_end" || this._retryPromise) {
             return;
@@ -171,12 +278,14 @@ export class AgentSession {
                 const steeringIndex = this._steeringMessages.indexOf(messageText);
                 if (steeringIndex !== -1) {
                     this._steeringMessages.splice(steeringIndex, 1);
+                    this._emitQueueUpdate();
                 }
                 else {
                     // Check follow-up queue
                     const followUpIndex = this._followUpMessages.indexOf(messageText);
                     if (followUpIndex !== -1) {
                         this._followUpMessages.splice(followUpIndex, 1);
+                        this._emitQueueUpdate();
                     }
                 }
             }
@@ -215,7 +324,6 @@ export class AgentSession {
                         attempt: this._retryAttempt,
                     });
                     this._retryAttempt = 0;
-                    this._resolveRetry();
                 }
             }
         }
@@ -229,6 +337,7 @@ export class AgentSession {
                 if (didRetry)
                     return; // Retry was initiated, don't proceed to compaction
             }
+            this._resolveRetry();
             await this._checkCompaction(msg);
         }
     }
@@ -261,10 +370,22 @@ export class AgentSession {
         }
         return undefined;
     }
+    _replaceMessageInPlace(target, replacement) {
+        // Agent-core stores the finalized message object in its state before emitting message_end.
+        // SessionManager persistence happens later in _processAgentEvent() with event.message.
+        // Mutating this object in place keeps agent state, later turn/agent events, listeners,
+        // and the eventual SessionManager.appendMessage(event.message) persistence in sync.
+        if (target === replacement) {
+            return;
+        }
+        const targetRecord = target;
+        for (const key of Object.keys(targetRecord)) {
+            delete targetRecord[key];
+        }
+        Object.assign(targetRecord, replacement);
+    }
     /** Emit extension events based on agent events */
     async _emitExtensionEvent(event) {
-        if (!this._extensionRunner)
-            return;
         if (event.type === "agent_start") {
             this._turnIndex = 0;
             await this._extensionRunner.emit({ type: "agent_start" });
@@ -310,7 +431,10 @@ export class AgentSession {
                 type: "message_end",
                 message: event.message,
             };
-            await this._extensionRunner.emit(extensionEvent);
+            const replacement = await this._extensionRunner.emitMessageEnd(extensionEvent);
+            if (replacement) {
+                this._replaceMessageInPlace(event.message, replacement);
+            }
         }
         else if (event.type === "tool_execution_start") {
             const extensionEvent = {
@@ -382,8 +506,10 @@ export class AgentSession {
      * Call this when completely done with the session.
      */
     dispose() {
+        this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
         this._disconnectFromAgent();
         this._eventListeners = [];
+        cleanupSessionResources(this.sessionId);
     }
     // =========================================================================
     // Read-only State Access
@@ -420,15 +546,19 @@ export class AgentSession {
         return this.agent.state.tools.map((t) => t.name);
     }
     /**
-     * Get all configured tools with name, description, and parameter schema.
+     * Get all configured tools with name, description, parameter schema, and source metadata.
      */
     getAllTools() {
-        return Array.from(this._toolRegistry.values()).map((t) => ({
-            name: t.name,
-            description: t.description,
-            parameters: t.parameters,
+        return Array.from(this._toolDefinitions.values()).map(({ definition, sourceInfo }) => ({
+            name: definition.name,
+            description: definition.description,
+            parameters: definition.parameters,
+            sourceInfo,
         }));
     }
+    getToolDefinition(name) {
+        return this._toolDefinitions.get(name)?.definition;
+    }
     /**
      * Set active tools by name.
      * Only tools in the registry can be enabled. Unknown tool names are ignored.
@@ -445,10 +575,10 @@ export class AgentSession {
                 validToolNames.push(name);
             }
         }
-        this.agent.setTools(tools);
+        this.agent.state.tools = tools;
         // Rebuild base system prompt with new tool set
         this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
-        this.agent.setSystemPrompt(this._baseSystemPrompt);
+        this.agent.state.systemPrompt = this._baseSystemPrompt;
     }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
@@ -462,11 +592,11 @@ export class AgentSession {
     }
     /** Current steering mode */
     get steeringMode() {
-        return this.agent.getSteeringMode();
+        return this.agent.steeringMode;
     }
     /** Current follow-up mode */
     get followUpMode() {
-        return this.agent.getFollowUpMode();
+        return this.agent.followUpMode;
     }
     /** Current session file path, or undefined if sessions are disabled */
     get sessionFile() {
@@ -533,7 +663,7 @@ export class AgentSession {
         const appendSystemPrompt = loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined;
         const loadedSkills = this._resourceLoader.getSkills().skills;
         const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
-        return buildSystemPrompt({
+        this._baseSystemPromptOptions = {
             cwd: this._cwd,
             skills: loadedSkills,
             contextFiles: loadedContextFiles,
@@ -542,7 +672,8 @@ export class AgentSession {
             selectedTools: validToolNames,
             toolSnippets,
             promptGuidelines,
-        });
+        };
+        return buildSystemPrompt(this._baseSystemPromptOptions);
     }
     // =========================================================================
     // Prompting
@@ -558,92 +689,92 @@ export class AgentSession {
      */
     async prompt(text, options) {
         const expandPromptTemplates = options?.expandPromptTemplates ?? 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
-                return;
-            }
-        }
-        // Emit input event for extension interception (before skill/template expansion)
-        let currentText = text;
-        let currentImages = options?.images;
-        if (this._extensionRunner?.hasHandlers("input")) {
-            const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive");
-            if (inputResult.action === "handled") {
-                return;
+        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 (inputResult.action === "transform") {
-                currentText = inputResult.text;
-                currentImages = inputResult.images ?? currentImages;
+            // Emit input event for extension interception (before skill/template expansion)
+            let currentText = text;
+            let currentImages = options?.images;
+            if (this._extensionRunner.hasHandlers("input")) {
+                const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive");
+                if (inputResult.action === "handled") {
+                    preflightResult?.(true);
+                    return;
+                }
+                if (inputResult.action === "transform") {
+                    currentText = inputResult.text;
+                    currentImages = inputResult.images ?? currentImages;
+                }
             }
-        }
-        // 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]);
-        }
-        // 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.");
+            // 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]);
             }
-            if (options.streamingBehavior === "followUp") {
-                await this._queueFollowUp(expandedText, currentImages);
+            // 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;
             }
-            else {
-                await this._queueSteer(expandedText, currentImages);
+            // Flush any pending bash messages before the new prompt
+            this._flushPendingBashMessages();
+            // Validate model
+            if (!this.model) {
+                throw new Error(formatNoModelSelectedMessage());
+            }
+            if (!this._modelRegistry.hasConfiguredAuth(this.model)) {
+                const isOAuth = this._modelRegistry.isUsingOAuth(this.model);
+                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)
+            const lastAssistant = this._findLastAssistantMessage();
+            if (lastAssistant) {
+                await this._checkCompaction(lastAssistant, false);
+            }
+            // 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);
+            }
+            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);
             }
-            return;
-        }
-        // Flush any pending bash messages before the new prompt
-        this._flushPendingBashMessages();
-        // Validate model
-        if (!this.model) {
-            throw new Error("No model selected.\n\n" +
-                `Use /login or set an API key environment variable. See ${join(getDocsPath(), "providers.md")}\n\n` +
-                "Then use /model to select a model.");
-        }
-        // Validate API key
-        const apiKey = await this._modelRegistry.getApiKey(this.model);
-        if (!apiKey) {
-            const isOAuth = this._modelRegistry.isUsingOAuth(this.model);
-            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(`No API key found for ${this.model.provider}.\n\n` +
-                `Use /login or set an API key environment variable. See ${join(getDocsPath(), "providers.md")}`);
-        }
-        // Check if we need to compact before sending (catches aborted responses)
-        const lastAssistant = this._findLastAssistantMessage();
-        if (lastAssistant) {
-            await this._checkCompaction(lastAssistant, false);
-        }
-        // Build messages array (custom message if any, then user message)
-        const messages = [];
-        // Add user message
-        const userContent = [{ type: "text", text: expandedText }];
-        if (currentImages) {
-            userContent.push(...currentImages);
-        }
-        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 = [];
-        // Emit before_agent_start extension event
-        if (this._extensionRunner) {
-            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPrompt);
+            this._pendingNextTurnMessages = [];
+            // Emit before_agent_start extension event
+            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPrompt, this._baseSystemPromptOptions);
             // Add all custom messages from extensions
             if (result?.messages) {
                 for (const msg of result.messages) {
@@ -659,13 +790,21 @@ export class AgentSession {
             }
             // Apply extension-modified system prompt, or reset to base
             if (result?.systemPrompt) {
-                this.agent.setSystemPrompt(result.systemPrompt);
+                this.agent.state.systemPrompt = result.systemPrompt;
             }
             else {
                 // Ensure we're using the base prompt (in case previous turn had modifications)
-                this.agent.setSystemPrompt(this._baseSystemPrompt);
+                this.agent.state.systemPrompt = this._baseSystemPrompt;
             }
         }
+        catch (error) {
+            preflightResult?.(false);
+            throw error;
+        }
+        if (!messages) {
+            return;
+        }
+        preflightResult?.(true);
         await this.agent.prompt(messages);
         await this.waitForRetry();
     }
@@ -673,8 +812,6 @@ export class AgentSession {
      * Try to execute an extension command. Returns true if command was found and executed.
      */
     async _tryExecuteExtensionCommand(text) {
-        if (!this._extensionRunner)
-            return false;
         // Parse command name and args
         const spaceIndex = text.indexOf(" ");
         const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
@@ -720,7 +857,7 @@ export class AgentSession {
         }
         catch (err) {
             // Emit error like extension commands do
-            this._extensionRunner?.emitError({
+            this._extensionRunner.emitError({
                 extensionPath: skill.filePath,
                 event: "skill_expansion",
                 error: err instanceof Error ? err.message : String(err),
@@ -729,8 +866,9 @@ export class AgentSession {
         }
     }
     /**
-     * Queue a steering message to interrupt the agent mid-run.
-     * Delivered after current tool execution, skips remaining tools.
+     * Queue a steering message while the agent is running.
+     * Delivered after the current assistant turn finishes executing its tool calls,
+     * before the next LLM call.
      * Expands skill commands and prompt templates. Errors on extension commands.
      * @param images Optional image attachments to include with the message
      * @throws Error if text is an extension command
@@ -767,6 +905,7 @@ export class AgentSession {
      */
     async _queueSteer(text, images) {
         this._steeringMessages.push(text);
+        this._emitQueueUpdate();
         const content = [{ type: "text", text }];
         if (images) {
             content.push(...images);
@@ -782,6 +921,7 @@ export class AgentSession {
      */
     async _queueFollowUp(text, images) {
         this._followUpMessages.push(text);
+        this._emitQueueUpdate();
         const content = [{ type: "text", text }];
         if (images) {
             content.push(...images);
@@ -796,8 +936,6 @@ export class AgentSession {
      * Throw an error if the text is an extension command.
      */
     _throwIfExtensionCommand(text) {
-        if (!this._extensionRunner)
-            return;
         const spaceIndex = text.indexOf(" ");
         const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
         const command = this._extensionRunner.getCommand(commandName);
@@ -841,7 +979,7 @@ export class AgentSession {
             await this.agent.prompt(appMessage);
         }
         else {
-            this.agent.appendMessage(appMessage);
+            this.agent.state.messages.push(appMessage);
             this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
             this._emit({ type: "message_start", message: appMessage });
             this._emit({ type: "message_end", message: appMessage });
@@ -895,6 +1033,7 @@ export class AgentSession {
         this._steeringMessages = [];
         this._followUpMessages = [];
         this.agent.clearAllQueues();
+        this._emitQueueUpdate();
         return { steering, followUp };
     }
     /** Number of pending messages (includes both steering and follow-up) */
@@ -920,60 +1059,10 @@ export class AgentSession {
         this.agent.abort();
         await this.agent.waitForIdle();
     }
-    /**
-     * Start a new session, optionally with initial messages and parent tracking.
-     * Clears all messages and starts a new session.
-     * Listeners are preserved and will continue receiving events.
-     * @param options.parentSession - Optional parent session path for tracking
-     * @param options.setup - Optional callback to initialize session (e.g., append messages)
-     * @returns true if completed, false if cancelled by extension
-     */
-    async newSession(options) {
-        const previousSessionFile = this.sessionFile;
-        // Emit session_before_switch event with reason "new" (can be cancelled)
-        if (this._extensionRunner?.hasHandlers("session_before_switch")) {
-            const result = (await this._extensionRunner.emit({
-                type: "session_before_switch",
-                reason: "new",
-            }));
-            if (result?.cancel) {
-                return false;
-            }
-        }
-        this._disconnectFromAgent();
-        await this.abort();
-        this.agent.reset();
-        this.sessionManager.newSession({ parentSession: options?.parentSession });
-        this.agent.sessionId = this.sessionManager.getSessionId();
-        this._steeringMessages = [];
-        this._followUpMessages = [];
-        this._pendingNextTurnMessages = [];
-        this.sessionManager.appendThinkingLevelChange(this.thinkingLevel);
-        // Run setup callback if provided (e.g., to append initial messages)
-        if (options?.setup) {
-            await options.setup(this.sessionManager);
-            // Sync agent state with session manager after setup
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.replaceMessages(sessionContext.messages);
-        }
-        this._reconnectToAgent();
-        // Emit session_switch event with reason "new" to extensions
-        if (this._extensionRunner) {
-            await this._extensionRunner.emit({
-                type: "session_switch",
-                reason: "new",
-                previousSessionFile,
-            });
-        }
-        // Emit session event to custom tools
-        return true;
-    }
     // =========================================================================
     // Model Management
     // =========================================================================
     async _emitModelSelect(nextModel, previousModel, source) {
-        if (!this._extensionRunner)
-            return;
         if (modelsAreEqual(previousModel, nextModel))
             return;
         await this._extensionRunner.emit({
@@ -985,17 +1074,16 @@ export class AgentSession {
     }
     /**
      * Set model directly.
-     * Validates API key, saves to session and settings.
-     * @throws Error if no API key available for the model
+     * Validates that auth is configured, saves to session and settings.
+     * @throws Error if no auth is configured for the model
      */
     async setModel(model) {
-        const apiKey = await this._modelRegistry.getApiKey(model);
-        if (!apiKey) {
+        if (!this._modelRegistry.hasConfiguredAuth(model)) {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
         const previousModel = this.model;
         const thinkingLevel = this._getThinkingLevelForModelSwitch();
-        this.agent.setModel(model);
+        this.agent.state.model = model;
         this.sessionManager.appendModelChange(model.provider, model.id);
         this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
         // Re-clamp thinking level for new model's capabilities
@@ -1014,27 +1102,8 @@ export class AgentSession {
         }
         return this._cycleAvailableModel(direction);
     }
-    async _getScopedModelsWithApiKey() {
-        const apiKeysByProvider = new Map();
-        const result = [];
-        for (const scoped of this._scopedModels) {
-            const provider = scoped.model.provider;
-            let apiKey;
-            if (apiKeysByProvider.has(provider)) {
-                apiKey = apiKeysByProvider.get(provider);
-            }
-            else {
-                apiKey = await this._modelRegistry.getApiKeyForProvider(provider);
-                apiKeysByProvider.set(provider, apiKey);
-            }
-            if (apiKey) {
-                result.push(scoped);
-            }
-        }
-        return result;
-    }
     async _cycleScopedModel(direction) {
-        const scopedModels = await this._getScopedModelsWithApiKey();
+        const scopedModels = this._scopedModels.filter((scoped) => this._modelRegistry.hasConfiguredAuth(scoped.model));
         if (scopedModels.length <= 1)
             return undefined;
         const currentModel = this.model;
@@ -1046,7 +1115,7 @@ export class AgentSession {
         const next = scopedModels[nextIndex];
         const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);
         // Apply model
-        this.agent.setModel(next.model);
+        this.agent.state.model = next.model;
         this.sessionManager.appendModelChange(next.model.provider, next.model.id);
         this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
         // Apply thinking level.
@@ -1068,12 +1137,8 @@ export class AgentSession {
         const len = availableModels.length;
         const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
         const nextModel = availableModels[nextIndex];
-        const apiKey = await this._modelRegistry.getApiKey(nextModel);
-        if (!apiKey) {
-            throw new Error(`No API key for ${nextModel.provider}/${nextModel.id}`);
-        }
         const thinkingLevel = this._getThinkingLevelForModelSwitch();
-        this.agent.setModel(nextModel);
+        this.agent.state.model = nextModel;
         this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
         this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
         // Re-clamp thinking level for new model's capabilities
@@ -1093,13 +1158,20 @@ export class AgentSession {
         const availableLevels = this.getAvailableThinkingLevels();
         const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);
         // Only persist if actually changing
-        const isChanging = effectiveLevel !== this.agent.state.thinkingLevel;
-        this.agent.setThinkingLevel(effectiveLevel);
+        const previousLevel = this.agent.state.thinkingLevel;
+        const isChanging = effectiveLevel !== previousLevel;
+        this.agent.state.thinkingLevel = effectiveLevel;
         if (isChanging) {
             this.sessionManager.appendThinkingLevelChange(effectiveLevel);
             if (this.supportsThinking() || effectiveLevel !== "off") {
                 this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
             }
+            this._emit({ type: "thinking_level_changed", level: effectiveLevel });
+            void this._extensionRunner.emit({
+                type: "thinking_level_select",
+                level: effectiveLevel,
+                previousLevel,
+            });
         }
     }
     /**
@@ -1121,15 +1193,9 @@ export class AgentSession {
      * The provider will clamp to what the specific model supports internally.
      */
     getAvailableThinkingLevels() {
-        if (!this.supportsThinking())
-            return ["off"];
-        return this.supportsXhighThinking() ? THINKING_LEVELS_WITH_XHIGH : THINKING_LEVELS;
-    }
-    /**
-     * Check if current model supports xhigh thinking level.
-     */
-    supportsXhighThinking() {
-        return this.model ? supportsXhigh(this.model) : false;
+        if (!this.model)
+            return THINKING_LEVELS;
+        return getSupportedThinkingLevels(this.model);
     }
     /**
      * Check if current model supports thinking/reasoning.
@@ -1146,24 +1212,8 @@ export class AgentSession {
         }
         return this.thinkingLevel;
     }
-    _clampThinkingLevel(level, availableLevels) {
-        const ordered = THINKING_LEVELS_WITH_XHIGH;
-        const available = new Set(availableLevels);
-        const requestedIndex = ordered.indexOf(level);
-        if (requestedIndex === -1) {
-            return availableLevels[0] ?? "off";
-        }
-        for (let i = requestedIndex; i < ordered.length; i++) {
-            const candidate = ordered[i];
-            if (available.has(candidate))
-                return candidate;
-        }
-        for (let i = requestedIndex - 1; i >= 0; i--) {
-            const candidate = ordered[i];
-            if (available.has(candidate))
-                return candidate;
-        }
-        return availableLevels[0] ?? "off";
+    _clampThinkingLevel(level, _availableLevels) {
+        return this.model ? clampThinkingLevel(this.model, level) : "off";
     }
     // =========================================================================
     // Queue Mode Management
@@ -1173,7 +1223,7 @@ export class AgentSession {
      * Saves to settings.
      */
     setSteeringMode(mode) {
-        this.agent.setSteeringMode(mode);
+        this.agent.steeringMode = mode;
         this.settingsManager.setSteeringMode(mode);
     }
     /**
@@ -1181,7 +1231,7 @@ export class AgentSession {
      * Saves to settings.
      */
     setFollowUpMode(mode) {
-        this.agent.setFollowUpMode(mode);
+        this.agent.followUpMode = mode;
         this.settingsManager.setFollowUpMode(mode);
     }
     // =========================================================================
@@ -1196,14 +1246,12 @@ export class AgentSession {
         this._disconnectFromAgent();
         await this.abort();
         this._compactionAbortController = new AbortController();
+        this._emit({ type: "compaction_start", reason: "manual" });
         try {
             if (!this.model) {
-                throw new Error("No model selected");
-            }
-            const apiKey = await this._modelRegistry.getApiKey(this.model);
-            if (!apiKey) {
-                throw new Error(`No API key for ${this.model.provider}`);
+                throw new Error(formatNoModelSelectedMessage());
             }
+            const { apiKey, headers } = await this._getRequiredRequestAuth(this.model);
             const pathEntries = this.sessionManager.getBranch();
             const settings = this.settingsManager.getCompactionSettings();
             const preparation = prepareCompaction(pathEntries, settings);
@@ -1217,7 +1265,7 @@ export class AgentSession {
             }
             let extensionCompaction;
             let fromExtension = false;
-            if (this._extensionRunner?.hasHandlers("session_before_compact")) {
+            if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const result = (await this._extensionRunner.emit({
                     type: "session_before_compact",
                     preparation,
@@ -1246,7 +1294,7 @@ export class AgentSession {
             }
             else {
                 // Generate compaction result
-                const result = await compact(preparation, this.model, apiKey, customInstructions, this._compactionAbortController.signal);
+                const result = await compact(preparation, this.model, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel);
                 summary = result.summary;
                 firstKeptEntryId = result.firstKeptEntryId;
                 tokensBefore = result.tokensBefore;
@@ -1258,7 +1306,7 @@ export class AgentSession {
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.replaceMessages(sessionContext.messages);
+            this.agent.state.messages = sessionContext.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) {
@@ -1268,12 +1316,33 @@ export class AgentSession {
                     fromExtension,
                 });
             }
-            return {
+            const compactionResult = {
                 summary,
                 firstKeptEntryId,
                 tokensBefore,
                 details,
             };
+            this._emit({
+                type: "compaction_end",
+                reason: "manual",
+                result: compactionResult,
+                aborted: false,
+                willRetry: false,
+            });
+            return compactionResult;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const aborted = message === "Compaction cancelled" || (error instanceof Error && error.name === "AbortError");
+            this._emit({
+                type: "compaction_end",
+                reason: "manual",
+                result: undefined,
+                aborted,
+                willRetry: false,
+                errorMessage: aborted ? undefined : `Compaction failed: ${message}`,
+            });
+            throw error;
         }
         finally {
             this._compactionAbortController = undefined;
@@ -1329,7 +1398,8 @@ export class AgentSession {
         if (sameModel && isContextOverflow(assistantMessage, contextWindow)) {
             if (this._overflowRecoveryAttempted) {
                 this._emit({
-                    type: "auto_compaction_end",
+                    type: "compaction_end",
+                    reason: "overflow",
                     result: undefined,
                     aborted: false,
                     willRetry: false,
@@ -1342,7 +1412,7 @@ export class AgentSession {
             // 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.replaceMessages(messages.slice(0, -1));
+                this.agent.state.messages = messages.slice(0, -1);
             }
             await this._runAutoCompaction("overflow", true);
             return;
@@ -1379,27 +1449,46 @@ export class AgentSession {
      */
     async _runAutoCompaction(reason, willRetry) {
         const settings = this.settingsManager.getCompactionSettings();
-        this._emit({ type: "auto_compaction_start", reason });
+        this._emit({ type: "compaction_start", reason });
         this._autoCompactionAbortController = new AbortController();
         try {
             if (!this.model) {
-                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                this._emit({
+                    type: "compaction_end",
+                    reason,
+                    result: undefined,
+                    aborted: false,
+                    willRetry: false,
+                });
                 return;
             }
-            const apiKey = await this._modelRegistry.getApiKey(this.model);
-            if (!apiKey) {
-                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+            const authResult = await this._modelRegistry.getApiKeyAndHeaders(this.model);
+            if (!authResult.ok || !authResult.apiKey) {
+                this._emit({
+                    type: "compaction_end",
+                    reason,
+                    result: undefined,
+                    aborted: false,
+                    willRetry: false,
+                });
                 return;
             }
+            const { apiKey, headers } = authResult;
             const pathEntries = this.sessionManager.getBranch();
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
-                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                this._emit({
+                    type: "compaction_end",
+                    reason,
+                    result: undefined,
+                    aborted: false,
+                    willRetry: false,
+                });
                 return;
             }
             let extensionCompaction;
             let fromExtension = false;
-            if (this._extensionRunner?.hasHandlers("session_before_compact")) {
+            if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const extensionResult = (await this._extensionRunner.emit({
                     type: "session_before_compact",
                     preparation,
@@ -1408,7 +1497,13 @@ export class AgentSession {
                     signal: this._autoCompactionAbortController.signal,
                 }));
                 if (extensionResult?.cancel) {
-                    this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
+                    this._emit({
+                        type: "compaction_end",
+                        reason,
+                        result: undefined,
+                        aborted: true,
+                        willRetry: false,
+                    });
                     return;
                 }
                 if (extensionResult?.compaction) {
@@ -1429,20 +1524,26 @@ export class AgentSession {
             }
             else {
                 // Generate compaction result
-                const compactResult = await compact(preparation, this.model, apiKey, undefined, this._autoCompactionAbortController.signal);
+                const compactResult = await compact(preparation, this.model, apiKey, headers, undefined, this._autoCompactionAbortController.signal, this.thinkingLevel);
                 summary = compactResult.summary;
                 firstKeptEntryId = compactResult.firstKeptEntryId;
                 tokensBefore = compactResult.tokensBefore;
                 details = compactResult.details;
             }
             if (this._autoCompactionAbortController.signal.aborted) {
-                this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
+                this._emit({
+                    type: "compaction_end",
+                    reason,
+                    result: undefined,
+                    aborted: true,
+                    willRetry: false,
+                });
                 return;
             }
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.replaceMessages(sessionContext.messages);
+            this.agent.state.messages = sessionContext.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) {
@@ -1458,12 +1559,12 @@ export class AgentSession {
                 tokensBefore,
                 details,
             };
-            this._emit({ type: "auto_compaction_end", result, aborted: false, willRetry });
+            this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
             if (willRetry) {
                 const messages = this.agent.state.messages;
                 const lastMsg = messages[messages.length - 1];
                 if (lastMsg?.role === "assistant" && lastMsg.stopReason === "error") {
-                    this.agent.replaceMessages(messages.slice(0, -1));
+                    this.agent.state.messages = messages.slice(0, -1);
                 }
                 setTimeout(() => {
                     this.agent.continue().catch(() => { });
@@ -1480,7 +1581,8 @@ export class AgentSession {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : "compaction failed";
             this._emit({
-                type: "auto_compaction_end",
+                type: "compaction_end",
+                reason,
                 result: undefined,
                 aborted: false,
                 willRetry: false,
@@ -1516,14 +1618,12 @@ export class AgentSession {
         if (bindings.onError !== undefined) {
             this._extensionErrorListener = bindings.onError;
         }
-        if (this._extensionRunner) {
-            this._applyExtensionBindings(this._extensionRunner);
-            await this._extensionRunner.emit({ type: "session_start" });
-            await this.extendResourcesFromExtensions("startup");
-        }
+        this._applyExtensionBindings(this._extensionRunner);
+        await this._extensionRunner.emit(this._sessionStartEvent);
+        await this.extendResourcesFromExtensions(this._sessionStartEvent.reason === "reload" ? "reload" : "startup");
     }
     async extendResourcesFromExtensions(reason) {
-        if (!this._extensionRunner?.hasHandlers("resources_discover")) {
+        if (!this._extensionRunner.hasHandlers("resources_discover")) {
             return;
         }
         const { skillPaths, promptPaths, themePaths } = await this._extensionRunner.emitResourcesDiscover(this._cwd, reason);
@@ -1537,7 +1637,7 @@ export class AgentSession {
         };
         this._resourceLoader.extendResources(extensionPaths);
         this._baseSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames());
-        this.agent.setSystemPrompt(this._baseSystemPrompt);
+        this.agent.state.systemPrompt = this._baseSystemPrompt;
     }
     buildExtensionResourcePaths(entries) {
         return entries.map((entry) => {
@@ -1570,37 +1670,36 @@ export class AgentSession {
             ? runner.onError(this._extensionErrorListener)
             : undefined;
     }
+    _refreshCurrentModelFromRegistry() {
+        const currentModel = this.model;
+        if (!currentModel) {
+            return;
+        }
+        const refreshedModel = this._modelRegistry.find(currentModel.provider, currentModel.id);
+        if (!refreshedModel || refreshedModel === currentModel) {
+            return;
+        }
+        this.agent.state.model = refreshedModel;
+    }
     _bindExtensionCore(runner) {
-        const normalizeLocation = (source) => {
-            if (source === "user" || source === "project" || source === "path") {
-                return source;
-            }
-            return undefined;
-        };
-        const reservedBuiltins = new Set(BUILTIN_SLASH_COMMANDS.map((command) => command.name));
         const getCommands = () => {
-            const extensionCommands = runner
-                .getRegisteredCommandsWithPaths()
-                .filter(({ command }) => !reservedBuiltins.has(command.name))
-                .map(({ command, extensionPath }) => ({
-                name: command.name,
+            const extensionCommands = runner.getRegisteredCommands().map((command) => ({
+                name: command.invocationName,
                 description: command.description,
                 source: "extension",
-                path: extensionPath,
+                sourceInfo: command.sourceInfo,
             }));
             const templates = this.promptTemplates.map((template) => ({
                 name: template.name,
                 description: template.description,
                 source: "prompt",
-                location: normalizeLocation(template.source),
-                path: template.filePath,
+                sourceInfo: template.sourceInfo,
             }));
             const skills = this._resourceLoader.getSkills().skills.map((skill) => ({
                 name: `skill:${skill.name}`,
                 description: skill.description,
                 source: "skill",
-                location: normalizeLocation(skill.source),
-                path: skill.filePath,
+                sourceInfo: skill.sourceInfo,
             }));
             return [...extensionCommands, ...templates, ...skills];
         };
@@ -1627,7 +1726,7 @@ export class AgentSession {
                 this.sessionManager.appendCustomEntry(customType, data);
             },
             setSessionName: (name) => {
-                this.sessionManager.appendSessionInfo(name);
+                this.setSessionName(name);
             },
             getSessionName: () => {
                 return this.sessionManager.getSessionName();
@@ -1641,8 +1740,7 @@ export class AgentSession {
             refreshTools: () => this._refreshToolRegistry(),
             getCommands,
             setModel: async (model) => {
-                const key = await this.modelRegistry.getApiKey(model);
-                if (!key)
+                if (!this.modelRegistry.hasConfiguredAuth(model))
                     return false;
                 await this.setModel(model);
                 return true;
@@ -1652,6 +1750,7 @@ export class AgentSession {
         }, {
             getModel: () => this.model,
             isIdle: () => !this.isStreaming,
+            getSignal: () => this.agent.signal,
             abort: () => this.abort(),
             hasPendingMessages: () => this.pendingMessageCount > 0,
             shutdown: () => {
@@ -1671,46 +1770,80 @@ export class AgentSession {
                 })();
             },
             getSystemPrompt: () => this.systemPrompt,
+        }, {
+            registerProvider: (name, config) => {
+                this._modelRegistry.registerProvider(name, config);
+                this._refreshCurrentModelFromRegistry();
+            },
+            unregisterProvider: (name) => {
+                this._modelRegistry.unregisterProvider(name);
+                this._refreshCurrentModelFromRegistry();
+            },
         });
     }
     _refreshToolRegistry(options) {
         const previousRegistryNames = new Set(this._toolRegistry.keys());
         const previousActiveToolNames = this.getActiveToolNames();
-        const registeredTools = this._extensionRunner?.getAllRegisteredTools() ?? [];
+        const allowedToolNames = this._allowedToolNames;
+        const isAllowedTool = (name) => !allowedToolNames || allowedToolNames.has(name);
+        const registeredTools = this._extensionRunner.getAllRegisteredTools();
         const allCustomTools = [
             ...registeredTools,
-            ...this._customTools.map((def) => ({ definition: def, extensionPath: "<sdk>" })),
-        ];
-        this._toolPromptSnippets = new Map(allCustomTools
-            .map((registeredTool) => {
-            const snippet = this._normalizePromptSnippet(registeredTool.definition.promptSnippet ?? registeredTool.definition.description);
-            return snippet ? [registeredTool.definition.name, snippet] : undefined;
+            ...this._customTools.map((definition) => ({
+                definition,
+                sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
+            })),
+        ].filter((tool) => isAllowedTool(tool.definition.name));
+        const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries())
+            .filter(([name]) => isAllowedTool(name))
+            .map(([name, definition]) => [
+            name,
+            {
+                definition,
+                sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
+            },
+        ]));
+        for (const tool of allCustomTools) {
+            definitionRegistry.set(tool.definition.name, {
+                definition: tool.definition,
+                sourceInfo: tool.sourceInfo,
+            });
+        }
+        this._toolDefinitions = definitionRegistry;
+        this._toolPromptSnippets = new Map(Array.from(definitionRegistry.values())
+            .map(({ definition }) => {
+            const snippet = this._normalizePromptSnippet(definition.promptSnippet);
+            return snippet ? [definition.name, snippet] : undefined;
         })
             .filter((entry) => entry !== undefined));
-        this._toolPromptGuidelines = new Map(allCustomTools
-            .map((registeredTool) => {
-            const guidelines = this._normalizePromptGuidelines(registeredTool.definition.promptGuidelines);
-            return guidelines.length > 0 ? [registeredTool.definition.name, guidelines] : undefined;
+        this._toolPromptGuidelines = new Map(Array.from(definitionRegistry.values())
+            .map(({ definition }) => {
+            const guidelines = this._normalizePromptGuidelines(definition.promptGuidelines);
+            return guidelines.length > 0 ? [definition.name, guidelines] : undefined;
         })
             .filter((entry) => entry !== undefined));
-        const wrappedExtensionTools = this._extensionRunner
-            ? wrapRegisteredTools(allCustomTools, this._extensionRunner)
-            : [];
-        const toolRegistry = new Map(this._baseToolRegistry);
+        const runner = this._extensionRunner;
+        const wrappedExtensionTools = wrapRegisteredTools(allCustomTools, runner);
+        const wrappedBuiltInTools = wrapRegisteredTools(Array.from(this._baseToolDefinitions.values())
+            .filter((definition) => isAllowedTool(definition.name))
+            .map((definition) => ({
+            definition,
+            sourceInfo: createSyntheticSourceInfo(`<builtin:${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);
         }
-        if (this._extensionRunner) {
-            const wrappedAllTools = wrapToolsWithExtensions(Array.from(toolRegistry.values()), this._extensionRunner);
-            this._toolRegistry = new Map(wrappedAllTools.map((tool) => [tool.name, tool]));
-        }
-        else {
-            this._toolRegistry = toolRegistry;
+        this._toolRegistry = toolRegistry;
+        const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => isAllowedTool(name));
+        if (allowedToolNames) {
+            for (const toolName of this._toolRegistry.keys()) {
+                if (allowedToolNames.has(toolName)) {
+                    nextActiveToolNames.push(toolName);
+                }
+            }
         }
-        const nextActiveToolNames = options?.activeToolNames
-            ? [...options.activeToolNames]
-            : [...previousActiveToolNames];
-        if (options?.includeAllExtensionTools) {
+        else if (options?.includeAllExtensionTools) {
             for (const tool of wrappedExtensionTools) {
                 nextActiveToolNames.push(tool.name);
             }
@@ -1727,32 +1860,29 @@ export class AgentSession {
     _buildRuntime(options) {
         const autoResizeImages = this.settingsManager.getImageAutoResize();
         const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
-        const baseTools = this._baseToolsOverride
-            ? this._baseToolsOverride
-            : createAllTools(this._cwd, {
+        const shellPath = this.settingsManager.getShellPath();
+        const baseToolDefinitions = this._baseToolsOverride
+            ? Object.fromEntries(Object.entries(this._baseToolsOverride).map(([name, tool]) => [
+                name,
+                createToolDefinitionFromAgentTool(tool),
+            ]))
+            : createAllToolDefinitions(this._cwd, {
                 read: { autoResizeImages },
-                bash: { commandPrefix: shellCommandPrefix },
+                bash: { commandPrefix: shellCommandPrefix, shellPath },
             });
-        this._baseToolRegistry = new Map(Object.entries(baseTools).map(([name, tool]) => [name, tool]));
+        this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
         const extensionsResult = this._resourceLoader.getExtensions();
         if (options.flagValues) {
             for (const [name, value] of options.flagValues) {
                 extensionsResult.runtime.flagValues.set(name, value);
             }
         }
-        const hasExtensions = extensionsResult.extensions.length > 0;
-        const hasCustomTools = this._customTools.length > 0;
-        this._extensionRunner =
-            hasExtensions || hasCustomTools
-                ? new ExtensionRunner(extensionsResult.extensions, extensionsResult.runtime, this._cwd, this.sessionManager, this._modelRegistry)
-                : undefined;
+        this._extensionRunner = new ExtensionRunner(extensionsResult.extensions, extensionsResult.runtime, this._cwd, this.sessionManager, this._modelRegistry);
         if (this._extensionRunnerRef) {
             this._extensionRunnerRef.current = this._extensionRunner;
         }
-        if (this._extensionRunner) {
-            this._bindExtensionCore(this._extensionRunner);
-            this._applyExtensionBindings(this._extensionRunner);
-        }
+        this._bindExtensionCore(this._extensionRunner);
+        this._applyExtensionBindings(this._extensionRunner);
         const defaultActiveToolNames = this._baseToolsOverride
             ? Object.keys(this._baseToolsOverride)
             : ["read", "bash", "edit", "write"];
@@ -1763,9 +1893,9 @@ export class AgentSession {
         });
     }
     async reload() {
-        const previousFlagValues = this._extensionRunner?.getFlagValues();
-        await this._extensionRunner?.emit({ type: "session_shutdown" });
-        this.settingsManager.reload();
+        const previousFlagValues = this._extensionRunner.getFlagValues();
+        await emitSessionShutdownEvent(this._extensionRunner, { type: "session_shutdown", reason: "reload" });
+        await this.settingsManager.reload();
         resetApiProviders();
         await this._resourceLoader.reload();
         this._buildRuntime({
@@ -1777,8 +1907,8 @@ export class AgentSession {
             this._extensionCommandContextActions ||
             this._extensionShutdownHandler ||
             this._extensionErrorListener;
-        if (this._extensionRunner && hasBindings) {
-            await this._extensionRunner.emit({ type: "session_start" });
+        if (hasBindings) {
+            await this._extensionRunner.emit({ type: "session_start", reason: "reload" });
             await this.extendResourcesFromExtensions("reload");
         }
     }
@@ -1797,8 +1927,8 @@ export class AgentSession {
         if (isContextOverflow(message, contextWindow))
             return false;
         const err = message.errorMessage;
-        // Match: overloaded_error, rate limit, 429, 500, 502, 503, 504, service unavailable, connection errors, fetch failed, terminated, retry delay exceeded
-        return /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server error|internal error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay/i.test(err);
+        // Match: overloaded_error, provider returned error, rate limit, 429, 500, 502, 503, 504, service unavailable, network/connection errors (including connection lost), WebSocket transport closes/errors, fetch failed, request ended without sending chunks, HTTP/2 closed before response, terminated, retry delay exceeded
+        return /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i.test(err);
     }
     /**
      * Handle retryable errors with exponential backoff.
@@ -1841,7 +1971,7 @@ export class AgentSession {
         // 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.replaceMessages(messages.slice(0, -1));
+            this.agent.state.messages = messages.slice(0, -1);
         }
         // Wait with exponential backoff (abortable)
         this._retryAbortController = new AbortController();
@@ -1884,9 +2014,11 @@ export class AgentSession {
      * Returns immediately if no retry is in progress.
      */
     async waitForRetry() {
-        if (this._retryPromise) {
-            await this._retryPromise;
+        if (!this._retryPromise) {
+            return;
         }
+        await this._retryPromise;
+        await this.agent.waitForIdle();
     }
     /** Whether auto-retry is currently in progress */
     get isRetrying() {
@@ -1917,17 +2049,13 @@ export class AgentSession {
         this._bashAbortController = new AbortController();
         // Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
         const prefix = this.settingsManager.getShellCommandPrefix();
+        const shellPath = this.settingsManager.getShellPath();
         const resolvedCommand = prefix ? `${prefix}\n${command}` : command;
         try {
-            const result = options?.operations
-                ? await executeBashWithOperations(resolvedCommand, process.cwd(), options.operations, {
-                    onChunk,
-                    signal: this._bashAbortController.signal,
-                })
-                : await executeBashCommand(resolvedCommand, {
-                    onChunk,
-                    signal: this._bashAbortController.signal,
-                });
+            const result = await executeBashWithOperations(resolvedCommand, this.sessionManager.getCwd(), options?.operations ?? createLocalBashOperations({ shellPath }), {
+                onChunk,
+                signal: this._bashAbortController.signal,
+            });
             this.recordBashResult(command, result, options);
             return result;
         }
@@ -1958,7 +2086,7 @@ export class AgentSession {
         }
         else {
             // Add to agent state immediately
-            this.agent.appendMessage(bashMessage);
+            this.agent.state.messages.push(bashMessage);
             // Save to session
             this.sessionManager.appendMessage(bashMessage);
         }
@@ -1986,7 +2114,7 @@ export class AgentSession {
             return;
         for (const bashMessage of this._pendingBashMessages) {
             // Add to agent state
-            this.agent.appendMessage(bashMessage);
+            this.agent.state.messages.push(bashMessage);
             // Save to session
             this.sessionManager.appendMessage(bashMessage);
         }
@@ -1995,129 +2123,12 @@ export class AgentSession {
     // =========================================================================
     // Session Management
     // =========================================================================
-    /**
-     * Switch to a different session file.
-     * Aborts current operation, loads messages, restores model/thinking.
-     * Listeners are preserved and will continue receiving events.
-     * @returns true if switch completed, false if cancelled by extension
-     */
-    async switchSession(sessionPath) {
-        const previousSessionFile = this.sessionManager.getSessionFile();
-        // Emit session_before_switch event (can be cancelled)
-        if (this._extensionRunner?.hasHandlers("session_before_switch")) {
-            const result = (await this._extensionRunner.emit({
-                type: "session_before_switch",
-                reason: "resume",
-                targetSessionFile: sessionPath,
-            }));
-            if (result?.cancel) {
-                return false;
-            }
-        }
-        this._disconnectFromAgent();
-        await this.abort();
-        this._steeringMessages = [];
-        this._followUpMessages = [];
-        this._pendingNextTurnMessages = [];
-        // Set new session
-        this.sessionManager.setSessionFile(sessionPath);
-        this.agent.sessionId = this.sessionManager.getSessionId();
-        // Reload messages
-        const sessionContext = this.sessionManager.buildSessionContext();
-        // Emit session_switch event to extensions
-        if (this._extensionRunner) {
-            await this._extensionRunner.emit({
-                type: "session_switch",
-                reason: "resume",
-                previousSessionFile,
-            });
-        }
-        // Emit session event to custom tools
-        this.agent.replaceMessages(sessionContext.messages);
-        // Restore model if saved
-        if (sessionContext.model) {
-            const previousModel = this.model;
-            const availableModels = await this._modelRegistry.getAvailable();
-            const match = availableModels.find((m) => m.provider === sessionContext.model.provider && m.id === sessionContext.model.modelId);
-            if (match) {
-                this.agent.setModel(match);
-                await this._emitModelSelect(match, previousModel, "restore");
-            }
-        }
-        const hasThinkingEntry = this.sessionManager.getBranch().some((entry) => entry.type === "thinking_level_change");
-        const defaultThinkingLevel = this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
-        if (hasThinkingEntry) {
-            // Restore thinking level if saved (setThinkingLevel clamps to model capabilities)
-            this.setThinkingLevel(sessionContext.thinkingLevel);
-        }
-        else {
-            const availableLevels = this.getAvailableThinkingLevels();
-            const effectiveLevel = availableLevels.includes(defaultThinkingLevel)
-                ? defaultThinkingLevel
-                : this._clampThinkingLevel(defaultThinkingLevel, availableLevels);
-            this.agent.setThinkingLevel(effectiveLevel);
-            this.sessionManager.appendThinkingLevelChange(effectiveLevel);
-        }
-        this._reconnectToAgent();
-        return true;
-    }
     /**
      * Set a display name for the current session.
      */
     setSessionName(name) {
         this.sessionManager.appendSessionInfo(name);
-    }
-    /**
-     * Create a fork from a specific entry.
-     * Emits before_fork/fork session events to extensions.
-     *
-     * @param entryId ID of the entry to fork from
-     * @returns Object with:
-     *   - selectedText: The text of the selected user message (for editor pre-fill)
-     *   - cancelled: True if an extension cancelled the fork
-     */
-    async fork(entryId) {
-        const previousSessionFile = this.sessionFile;
-        const selectedEntry = this.sessionManager.getEntry(entryId);
-        if (!selectedEntry || selectedEntry.type !== "message" || selectedEntry.message.role !== "user") {
-            throw new Error("Invalid entry ID for forking");
-        }
-        const selectedText = this._extractUserMessageText(selectedEntry.message.content);
-        let skipConversationRestore = false;
-        // Emit session_before_fork event (can be cancelled)
-        if (this._extensionRunner?.hasHandlers("session_before_fork")) {
-            const result = (await this._extensionRunner.emit({
-                type: "session_before_fork",
-                entryId,
-            }));
-            if (result?.cancel) {
-                return { selectedText, cancelled: true };
-            }
-            skipConversationRestore = result?.skipConversationRestore ?? false;
-        }
-        // Clear pending messages (bound to old session state)
-        this._pendingNextTurnMessages = [];
-        if (!selectedEntry.parentId) {
-            this.sessionManager.newSession({ parentSession: previousSessionFile });
-        }
-        else {
-            this.sessionManager.createBranchedSession(selectedEntry.parentId);
-        }
-        this.agent.sessionId = this.sessionManager.getSessionId();
-        // Reload messages from entries (works for both file and in-memory mode)
-        const sessionContext = this.sessionManager.buildSessionContext();
-        // Emit session_fork event to extensions (after fork completes)
-        if (this._extensionRunner) {
-            await this._extensionRunner.emit({
-                type: "session_fork",
-                previousSessionFile,
-            });
-        }
-        // Emit session event to custom tools (with reason "fork")
-        if (!skipConversationRestore) {
-            this.agent.replaceMessages(sessionContext.messages);
-        }
-        return { selectedText, cancelled: false };
+        this._emit({ type: "session_info_changed", name: this.sessionManager.getSessionName() });
     }
     // =========================================================================
     // Tree Navigation
@@ -2165,120 +2176,117 @@ export class AgentSession {
         };
         // Set up abort controller for summarization
         this._branchSummaryAbortController = new AbortController();
-        let extensionSummary;
-        let fromExtension = false;
-        // Emit session_before_tree event
-        if (this._extensionRunner?.hasHandlers("session_before_tree")) {
-            const result = (await this._extensionRunner.emit({
-                type: "session_before_tree",
-                preparation,
-                signal: this._branchSummaryAbortController.signal,
-            }));
-            if (result?.cancel) {
-                return { cancelled: true };
-            }
-            if (result?.summary && options.summarize) {
-                extensionSummary = result.summary;
-                fromExtension = true;
-            }
-            // Allow extensions to override instructions and label
-            if (result?.customInstructions !== undefined) {
-                customInstructions = result.customInstructions;
-            }
-            if (result?.replaceInstructions !== undefined) {
-                replaceInstructions = result.replaceInstructions;
-            }
-            if (result?.label !== undefined) {
-                label = result.label;
-            }
-        }
-        // Run default summarizer if needed
-        let summaryText;
-        let summaryDetails;
-        if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
-            const model = this.model;
-            const apiKey = await this._modelRegistry.getApiKey(model);
-            if (!apiKey) {
-                throw new Error(`No API key for ${model.provider}`);
-            }
-            const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
-            const result = await generateBranchSummary(entriesToSummarize, {
-                model,
-                apiKey,
-                signal: this._branchSummaryAbortController.signal,
-                customInstructions,
-                replaceInstructions,
-                reserveTokens: branchSummarySettings.reserveTokens,
-            });
-            this._branchSummaryAbortController = undefined;
-            if (result.aborted) {
-                return { cancelled: true, aborted: true };
+        try {
+            let extensionSummary;
+            let fromExtension = false;
+            // Emit session_before_tree event
+            if (this._extensionRunner.hasHandlers("session_before_tree")) {
+                const result = (await this._extensionRunner.emit({
+                    type: "session_before_tree",
+                    preparation,
+                    signal: this._branchSummaryAbortController.signal,
+                }));
+                if (result?.cancel) {
+                    return { cancelled: true };
+                }
+                if (result?.summary && options.summarize) {
+                    extensionSummary = result.summary;
+                    fromExtension = true;
+                }
+                // Allow extensions to override instructions and label
+                if (result?.customInstructions !== undefined) {
+                    customInstructions = result.customInstructions;
+                }
+                if (result?.replaceInstructions !== undefined) {
+                    replaceInstructions = result.replaceInstructions;
+                }
+                if (result?.label !== undefined) {
+                    label = result.label;
+                }
             }
-            if (result.error) {
-                throw new Error(result.error);
+            // Run default summarizer if needed
+            let summaryText;
+            let summaryDetails;
+            if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
+                const model = this.model;
+                const { apiKey, headers } = await this._getRequiredRequestAuth(model);
+                const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
+                const result = await generateBranchSummary(entriesToSummarize, {
+                    model,
+                    apiKey,
+                    headers,
+                    signal: this._branchSummaryAbortController.signal,
+                    customInstructions,
+                    replaceInstructions,
+                    reserveTokens: branchSummarySettings.reserveTokens,
+                });
+                if (result.aborted) {
+                    return { cancelled: true, aborted: true };
+                }
+                if (result.error) {
+                    throw new Error(result.error);
+                }
+                summaryText = result.summary;
+                summaryDetails = {
+                    readFiles: result.readFiles || [],
+                    modifiedFiles: result.modifiedFiles || [],
+                };
+            }
+            else if (extensionSummary) {
+                summaryText = extensionSummary.summary;
+                summaryDetails = extensionSummary.details;
+            }
+            // Determine the new leaf position based on target type
+            let newLeafId;
+            let editorText;
+            if (targetEntry.type === "message" && targetEntry.message.role === "user") {
+                // User message: leaf = parent (null if root), text goes to editor
+                newLeafId = targetEntry.parentId;
+                editorText = this._extractUserMessageText(targetEntry.message.content);
+            }
+            else if (targetEntry.type === "custom_message") {
+                // Custom message: leaf = parent (null if root), text goes to editor
+                newLeafId = targetEntry.parentId;
+                editorText =
+                    typeof targetEntry.content === "string"
+                        ? targetEntry.content
+                        : targetEntry.content
+                            .filter((c) => c.type === "text")
+                            .map((c) => c.text)
+                            .join("");
             }
-            summaryText = result.summary;
-            summaryDetails = {
-                readFiles: result.readFiles || [],
-                modifiedFiles: result.modifiedFiles || [],
-            };
-        }
-        else if (extensionSummary) {
-            summaryText = extensionSummary.summary;
-            summaryDetails = extensionSummary.details;
-        }
-        // Determine the new leaf position based on target type
-        let newLeafId;
-        let editorText;
-        if (targetEntry.type === "message" && targetEntry.message.role === "user") {
-            // User message: leaf = parent (null if root), text goes to editor
-            newLeafId = targetEntry.parentId;
-            editorText = this._extractUserMessageText(targetEntry.message.content);
-        }
-        else if (targetEntry.type === "custom_message") {
-            // Custom message: leaf = parent (null if root), text goes to editor
-            newLeafId = targetEntry.parentId;
-            editorText =
-                typeof targetEntry.content === "string"
-                    ? targetEntry.content
-                    : targetEntry.content
-                        .filter((c) => c.type === "text")
-                        .map((c) => c.text)
-                        .join("");
-        }
-        else {
-            // Non-user message: leaf = selected node
-            newLeafId = targetId;
-        }
-        // Switch leaf (with or without summary)
-        // Summary is attached at the navigation target position (newLeafId), not the old branch
-        let summaryEntry;
-        if (summaryText) {
-            // Create summary at target position (can be null for root)
-            const summaryId = this.sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension);
-            summaryEntry = this.sessionManager.getEntry(summaryId);
-            // Attach label to the summary entry
-            if (label) {
-                this.sessionManager.appendLabelChange(summaryId, label);
+            else {
+                // Non-user message: leaf = selected node
+                newLeafId = targetId;
+            }
+            // Switch leaf (with or without summary)
+            // Summary is attached at the navigation target position (newLeafId), not the old branch
+            let summaryEntry;
+            if (summaryText) {
+                // Create summary at target position (can be null for root)
+                const summaryId = this.sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension);
+                summaryEntry = this.sessionManager.getEntry(summaryId);
+                // Attach label to the summary entry
+                if (label) {
+                    this.sessionManager.appendLabelChange(summaryId, label);
+                }
             }
-        }
-        else if (newLeafId === null) {
-            // No summary, navigating to root - reset leaf
-            this.sessionManager.resetLeaf();
-        }
-        else {
-            // No summary, navigating to non-root
-            this.sessionManager.branch(newLeafId);
-        }
-        // Attach label to target entry when not summarizing (no summary entry to label)
-        if (label && !summaryText) {
-            this.sessionManager.appendLabelChange(targetId, label);
-        }
-        // Update agent state
-        const sessionContext = this.sessionManager.buildSessionContext();
-        this.agent.replaceMessages(sessionContext.messages);
-        // Emit session_tree event
-        if (this._extensionRunner) {
+            else if (newLeafId === null) {
+                // No summary, navigating to root - reset leaf
+                this.sessionManager.resetLeaf();
+            }
+            else {
+                // No summary, navigating to non-root
+                this.sessionManager.branch(newLeafId);
+            }
+            // Attach label to target entry when not summarizing (no summary entry to label)
+            if (label && !summaryText) {
+                this.sessionManager.appendLabelChange(targetId, label);
+            }
+            // Update agent state
+            const sessionContext = this.sessionManager.buildSessionContext();
+            this.agent.state.messages = sessionContext.messages;
+            // Emit session_tree event
             await this._extensionRunner.emit({
                 type: "session_tree",
                 newLeafId: this.sessionManager.getLeafId(),
@@ -2286,10 +2294,12 @@ export class AgentSession {
                 summaryEntry,
                 fromExtension: summaryText ? fromExtension : undefined,
             });
+            // Emit to custom tools
+            return { editorText, cancelled: false, summaryEntry };
+        }
+        finally {
+            this._branchSummaryAbortController = undefined;
         }
-        // Emit to custom tools
-        this._branchSummaryAbortController = undefined;
-        return { editorText, cancelled: false, summaryEntry };
     }
     /**
      * Get all user messages from session for fork selector.
@@ -2361,6 +2371,7 @@ export class AgentSession {
                 total: totalInput + totalOutput + totalCacheRead + totalCacheWrite,
             },
             cost: totalCost,
+            contextUsage: this.getContextUsage(),
         };
     }
     getContextUsage() {
@@ -2412,19 +2423,48 @@ export class AgentSession {
     async exportToHtml(outputPath) {
         const themeName = this.settingsManager.getTheme();
         // Create tool renderer if we have an extension runner (for custom tool HTML rendering)
-        let toolRenderer;
-        if (this._extensionRunner) {
-            toolRenderer = createToolHtmlRenderer({
-                getToolDefinition: (name) => this._extensionRunner.getToolDefinition(name),
-                theme,
-            });
-        }
+        const toolRenderer = createToolHtmlRenderer({
+            getToolDefinition: (name) => this.getToolDefinition(name),
+            theme,
+            cwd: this.sessionManager.getCwd(),
+        });
         return await exportSessionToHtml(this.sessionManager, this.state, {
             outputPath,
             themeName,
             toolRenderer,
         });
     }
+    /**
+     * Export the current session branch to a JSONL file.
+     * Writes the session header followed by all entries on the current branch path.
+     * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.
+     * @returns The resolved output file path.
+     */
+    exportToJsonl(outputPath) {
+        const filePath = resolve(outputPath ?? `session-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`);
+        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;
+    }
     // =========================================================================
     // Utilities
     // =========================================================================
@@ -2459,11 +2499,17 @@ export class AgentSession {
     // =========================================================================
     // Extension System
     // =========================================================================
+    createReplacedSessionContext() {
+        const context = Object.defineProperties({}, Object.getOwnPropertyDescriptors(this._extensionRunner.createCommandContext()));
+        context.sendMessage = (message, options) => this.sendCustomMessage(message, options);
+        context.sendUserMessage = (content, options) => this.sendUserMessage(content, options);
+        return context;
+    }
     /**
      * Check if extensions have handlers for a specific event type.
      */
     hasExtensionHandlers(eventType) {
-        return this._extensionRunner?.hasHandlers(eventType) ?? false;
+        return this._extensionRunner.hasHandlers(eventType);
     }
     /**
      * Get the extension runner (for setting UI context and error handlers).