apex-code 0.5.0 → 0.5.2

package/dist/core/agent-session.js

@@ -14,16 +14,18 @@
  */
 import { readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative } from "node:path";
-import { contentText } from "@earendil-works/pi-ai";
+import { contentText, getCurrentSystemMessage, retryDelayMs } from "@earendil-works/pi-ai";
 import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, } from "@earendil-works/pi-ai/compat";
 import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
+import { processImage } from "../utils/image-process.js";
 import { sleep } from "../utils/sleep.js";
 import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { executeBashWithOperations } from "./bash-executor.js";
+import { generateBugReportSummary } from "./bug-report.js";
 import { createSessionCheckpoints } from "./checkpoints/session-checkpoints.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { evictionBudget, installContextPipeline, isDefaultStreamFunction } from "./context/pipeline.js";
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
 import { RESUME_CHILD_PROMPT, runDelegation } from "./delegation/runtime.js";
@@ -33,6 +35,7 @@ import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { runFormatterCommand } from "./formatter-lifecycle.js";
+import { convertToLlm } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { evaluateToolCall } from "./permissions/gate.js";
 import { authorizeConfiguredCommand } from "./permissions/policy-command.js";
@@ -41,10 +44,10 @@ import { resolveEffectiveModeWithOrigin } from "./permissions/startup.js";
 import { loadPolicyConfiguration } from "./policy-loader.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { exportSessionToJsonl } from "./session-export.js";
-import { getLatestCompactionEntry, TODO_CUSTOM_ENTRY_TYPE } from "./session-manager.js";
+import { getLatestCompactionEntry, SessionManager, TODO_CUSTOM_ENTRY_TYPE, } from "./session-manager.js";
 import { slugifySkillCommandName } from "./skills.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
-import { buildSystemPrompt } from "./system-prompt.js";
+import { buildSystemPrompt, buildSystemPromptSections, diffSystemPromptSections, normalizeBuildSystemPromptOptions, } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { buildToolContractSnapshot, isUnclassifiedTool, } from "./tools/contract-snapshot.js";
 import { createAllToolDefinitions } from "./tools/index.js";
@@ -103,6 +106,7 @@ export class AgentSession {
     _unsubscribeAgent;
     _eventListeners = [];
     _isAgentRunActive = false;
+    _agentRunAbortRequested = false;
     _idleWaitPromise;
     _resolveIdleWait;
     /** Tracks pending steering messages for UI display. Removed when delivered. */
@@ -129,6 +133,15 @@ export class AgentSession {
     // Extension system
     _extensionRunner;
     _turnIndex = 0;
+    _entryIdsByMessage = new WeakMap();
+    _boundaryDispatchedMessages = new WeakSet();
+    _lastAssistantMessage;
+    _lastAssistantToolResults = [];
+    _lastActivityOutcome = "completed";
+    _isBeforeSettle = false;
+    _abortDuringBeforeSettle = false;
+    _isEmittingAgentSettled = false;
+    _deferredSettledActions = [];
     _resourceLoader;
     _customTools;
     _baseToolDefinitions = new Map();
@@ -183,16 +196,16 @@ export class AgentSession {
     _extensionErrorListener;
     _extensionErrorUnsubscriber;
     _modelRuntime;
+    _cacheWarmer;
     // Tool registry for extension getTools/setTools
     _toolRegistry = new Map();
     _toolDefinitions = new Map();
     _toolPromptSnippets = new Map();
     _toolPromptGuidelines = new Map();
     _loadedDeferredSchemas = new Set();
-    // Base system prompt (without extension appends) - used to apply fresh appends each turn
-    _baseSystemPrompt = "";
     _baseSystemPromptOptions;
-    _systemPromptOverride;
+    /** Prompt options after before_agent_start mutations for the active run. */
+    _runSystemPromptOptions;
     constructor(config) {
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
@@ -202,6 +215,10 @@ export class AgentSession {
         this._customTools = config.customTools ?? [];
         this._cwd = config.cwd;
         this._modelRuntime = config.modelRuntime;
+        this._cacheWarmer = config.cacheWarmer;
+        if (this._cacheWarmer) {
+            this._cacheWarmer.onWarmed = (entry) => this._emit({ type: "entry_appended", entry });
+        }
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
@@ -245,6 +262,9 @@ export class AgentSession {
         this._installAgentNextTurnRefresh();
         this._installMidRunCompactionHook();
         this._installContextPipeline();
+        this._installAgentRequestProjection();
+        this._installAgentBoundaryHooks();
+        this._installAgentForcedPromptProjection();
         // Declarative hooks: session_start is observe-only and must neither delay
         // nor fail construction, so it fires detached (emitObserve swallows
         // handler failures already).
@@ -258,14 +278,16 @@ export class AgentSession {
             activeToolNames: this._initialActiveToolNames,
             includeAllExtensionTools: true,
         });
+        if (this._initialActiveToolNames === undefined)
+            this._restoreToolsFromTranscript();
     }
     get modelRuntime() {
         return this._modelRuntime;
     }
-    async _getRequiredRequestAuth(model) {
+    async _getRequiredRequestAuth(model, signal) {
         let result;
         try {
-            result = await this._modelRuntime.getAuth(model);
+            result = await this._modelRuntime.getAuth(model, { signal });
         }
         catch (error) {
             const cause = error instanceof Error ? error.cause : undefined;
@@ -291,12 +313,12 @@ export class AgentSession {
         }
         throw new Error(formatNoApiKeyFoundMessage(model.provider));
     }
-    async _getSummarizationRequestAuth(model) {
+    async _getSummarizationRequestAuth(model, signal) {
         if (isDefaultStreamFunction(this.agent.streamFunction)) {
-            return this._getRequiredRequestAuth(model);
+            return this._getRequiredRequestAuth(model, signal);
         }
         try {
-            const result = await this._modelRuntime.getAuth(model);
+            const result = await this._modelRuntime.getAuth(model, { signal });
             if (!result)
                 return { model };
             const requestModel = result.auth.baseUrl ? { ...model, baseUrl: result.auth.baseUrl } : model;
@@ -307,7 +329,9 @@ export class AgentSession {
                 env: result.env,
             };
         }
-        catch {
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
             return { model };
         }
     }
@@ -419,8 +443,10 @@ export class AgentSession {
             }
             const content = hookResult?.content ?? result.content ?? [];
             // Runs after the extension hook so images injected or replaced by extensions are normalized too.
+            const resizeOptions = this.model?.inputLimits?.images?.resize;
             const normalizedContent = await normalizeToolResultImages(content, {
                 autoResizeImages: this.settingsManager.getImageAutoResize(),
+                ...(resizeOptions ? { resizeOptions } : {}),
             });
             if (!hookResult && normalizedContent === content) {
                 return undefined;
@@ -435,16 +461,84 @@ export class AgentSession {
     }
     async _compactBeforeNextAssistantResponse(context) {
         const model = this.model;
-        const settings = this.settingsManager.getCompactionSettings();
+        const settings = this.settingsManager.getCompactionSettings(model);
+        const projection = this.sessionManager.buildSessionProjection();
         if (!model ||
             model.contextWindow <= 0 ||
-            !shouldCompact(estimateContextTokens(context.messages).tokens, model.contextWindow, settings)) {
-            return context;
+            !shouldCompact(estimateProjectedContextTokens(projection, this.sessionManager.getBranch()).tokens, model.contextWindow, settings)) {
+            return { ...context, messages: projection.messages };
         }
         await this._runAutoCompaction("threshold", false);
-        return {
-            ...context,
-            messages: this.agent.state.messages.slice(),
+        return { ...context, messages: this.sessionManager.buildSessionProjection().messages };
+    }
+    _installAgentRequestProjection() {
+        const previousPrepareRequest = this.agent.prepareRequest;
+        this.agent.prepareRequest = async (request, signal) => {
+            const canonicalContext = {
+                ...request.context,
+                messages: this.sessionManager.buildSessionProjection().messages,
+                // Messages declare the provider-visible loadout; context.tools keeps executable implementations.
+                tools: this.agent.state.tools.slice(),
+            };
+            const previous = await previousPrepareRequest?.({
+                ...request,
+                context: canonicalContext,
+                model: this.agent.state.model,
+                thinkingLevel: this.agent.state.thinkingLevel,
+            }, signal);
+            return {
+                ...previous,
+                context: previous?.context ?? canonicalContext,
+                model: previous?.model ?? this.agent.state.model,
+                thinkingLevel: previous?.thinkingLevel ?? this.agent.state.thinkingLevel,
+            };
+        };
+    }
+    async _dispatchTurnEndBoundary(message, toolResults) {
+        this._lastActivityOutcome =
+            message.stopReason === "aborted" ? "aborted" : message.stopReason === "error" ? "error" : "completed";
+        const messageEntryId = this._findPersistedMessageEntryId(message);
+        if (!this._extensionRunner.hasHandlers("turn_end"))
+            return false;
+        if (!messageEntryId) {
+            this._extensionRunner.emitError({
+                extensionPath: "<boundary>",
+                event: "turn_end",
+                error: "turn_end could not resolve the persisted assistant entry ID",
+            });
+            return false;
+        }
+        const toolResultEntryIds = toolResults.flatMap((result) => {
+            const entryId = this._findPersistedMessageEntryId(result);
+            return entryId ? [entryId] : [];
+        });
+        const boundary = await this._extensionRunner.emitBoundary({
+            type: "turn_end",
+            turnIndex: this._turnIndex,
+            message,
+            toolResults,
+            messageEntryId,
+            toolResultEntryIds,
+            outcome: this._lastActivityOutcome,
+        }, (entries) => this._buildBoundaryContext(entries, "turn_end"));
+        this._commitBoundaryDrafts(boundary.entries);
+        if (boundary.continue && !this._buildBoundaryContext([], "turn_end").canContinue) {
+            this._reportInvalidBoundaryContinuation("turn_end");
+            return false;
+        }
+        return boundary.continue;
+    }
+    _installAgentBoundaryHooks() {
+        const previousFinishTurn = this.agent.finishTurn;
+        this.agent.finishTurn = async (turn, signal) => {
+            this._boundaryDispatchedMessages.add(turn.message);
+            const extensionContinue = await this._dispatchTurnEndBoundary(turn.message, turn.toolResults);
+            const previousDecision = await previousFinishTurn?.(turn, signal);
+            if (previousDecision?.action === "end")
+                return previousDecision;
+            if (extensionContinue || previousDecision?.action === "continue")
+                return { action: "continue" };
+            return undefined;
         };
     }
     _installAgentNextTurnRefresh() {
@@ -453,16 +547,31 @@ export class AgentSession {
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
-            const context = await this._compactBeforeNextAssistantResponse(turn.context);
+            const context = await this._compactBeforeNextAssistantResponse({
+                ...turn.context,
+                messages: this.sessionManager.buildSessionProjection().messages,
+            });
             const previousSnapshot = await previousPrepareNextTurnWithContext?.({ ...turn, context }, signal);
             const nextContext = previousSnapshot?.context ?? context;
+            const runOptions = this._runSystemPromptOptions ?? this._baseSystemPromptOptions;
+            const options = normalizeBuildSystemPromptOptions({
+                ...runOptions,
+                selectedTools: this.getActiveToolNames(),
+                toolSnippets: { ...this._baseSystemPromptOptions.toolSnippets, ...runOptions.toolSnippets },
+                toolGuidelines: { ...this._baseSystemPromptOptions.toolGuidelines, ...runOptions.toolGuidelines },
+            });
+            const updateMessage = this._preparePromptAndToolLoadout(options, nextContext.messages);
+            // Keep session.systemPrompt and ctx.getSystemPrompt() in step with what the provider sees.
+            this._runSystemPromptOptions = options;
             return {
                 ...previousSnapshot,
                 context: {
                     ...nextContext,
-                    systemPrompt: this._systemPromptOverride ?? this._baseSystemPrompt,
                     tools: this.agent.state.tools.slice(),
                 },
+                messages: updateMessage
+                    ? [...(previousSnapshot?.messages ?? []), updateMessage]
+                    : previousSnapshot?.messages,
                 model: this.agent.state.model,
                 thinkingLevel: this.agent.state.thinkingLevel,
             };
@@ -540,6 +649,84 @@ export class AgentSession {
     // =========================================================================
     // Event Subscription
     // =========================================================================
+    _refreshFinalizedContext() {
+        const projection = this.sessionManager.buildSessionProjection();
+        for (const entry of projection.entries) {
+            for (const message of entry.messages)
+                this._entryIdsByMessage.set(message, entry.sourceEntry.id);
+        }
+        this.agent.state.messages = projection.messages;
+    }
+    _applyBoundaryDrafts(manager, drafts) {
+        const appended = [];
+        for (const draft of drafts) {
+            let entryId;
+            switch (draft.type) {
+                case "custom":
+                    entryId = manager.appendCustomEntry(draft.customType, draft.data);
+                    break;
+                case "custom_message":
+                    entryId = manager.appendCustomMessageEntry(draft.customType, draft.content, draft.display, draft.details);
+                    break;
+                case "context_edit":
+                    entryId = manager.appendContextEdit(draft.targetId, draft.replacement);
+                    break;
+                case "compaction": {
+                    const tokensBefore = estimateProjectedContextTokens(manager.buildSessionProjection(), manager.getBranch()).tokens;
+                    entryId = manager.appendCompaction(draft.summary, draft.firstKeptEntryId, tokensBefore, draft.details, true, draft.usage);
+                    break;
+                }
+            }
+            const entry = manager.getEntry(entryId);
+            if (entry)
+                appended.push(entry);
+        }
+        return appended;
+    }
+    _createBoundaryPreviewManager(drafts) {
+        const header = this.sessionManager.getHeader();
+        if (!header)
+            throw new Error("Session header is missing");
+        const manager = SessionManager.inMemory(this._cwd, undefined, [header, ...this.sessionManager.getBranch()]);
+        this._applyBoundaryDrafts(manager, drafts);
+        return manager;
+    }
+    _getPendingBoundaryMessages() {
+        return [...this.agent.peekQueuedMessages(), ...this._pendingCustomMessages];
+    }
+    _buildBoundaryContext(drafts, boundary) {
+        const projection = this._createBoundaryPreviewManager(drafts).buildSessionProjection();
+        const pendingMessages = this._getPendingBoundaryMessages();
+        const llmMessages = convertToLlm(projection.messages);
+        const finalRole = llmMessages[llmMessages.length - 1]?.role;
+        const hasNonSystemContext = llmMessages.some((message) => message.role !== "system");
+        const contextCanContinue = hasNonSystemContext && finalRole !== "assistant";
+        const pendingCustomContext = this._pendingCustomMessages.length > 0;
+        return {
+            contextEntries: projection.entries,
+            contextMessages: projection.messages,
+            llmMessages,
+            pendingMessages,
+            canContinue: contextCanContinue ||
+                pendingCustomContext ||
+                (boundary === "turn_end"
+                    ? this.agent.hasQueuedMessages()
+                    : finalRole === "assistant" && this.agent.hasQueuedMessages()),
+        };
+    }
+    _commitBoundaryDrafts(drafts) {
+        const appended = this._applyBoundaryDrafts(this.sessionManager, drafts);
+        this._refreshFinalizedContext();
+        for (const entry of appended)
+            this._emit({ type: "entry_appended", entry });
+    }
+    _reportInvalidBoundaryContinuation(event) {
+        this._extensionRunner.emitError({
+            extensionPath: "<boundary>",
+            event,
+            error: `${event} requested continuation without runnable model context`,
+        });
+    }
     /** Emit an event to all listeners */
     _emit(event) {
         for (const l of this._eventListeners) {
@@ -567,7 +754,7 @@ export class AgentSession {
         return this._idleWaitPromise;
     }
     _resolveIdleWaitIfIdle() {
-        if (this._isAgentRunActive || !this._resolveIdleWait) {
+        if (!this.isIdle || !this._resolveIdleWait) {
             return;
         }
         const resolve = this._resolveIdleWait;
@@ -576,17 +763,29 @@ export class AgentSession {
         resolve();
     }
     async _emitAgentSettled() {
+        this._cacheWarmer?.onAgentSettled();
         this._isAgentRunActive = false;
+        this._isEmittingAgentSettled = true;
         try {
             await this._extensionRunner.emit({ type: "agent_settled" });
             this._emit({ type: "agent_settled" });
         }
         finally {
-            this._resolveIdleWaitIfIdle();
+            this._isEmittingAgentSettled = false;
         }
+        const deferred = this._deferredSettledActions.splice(0);
+        if (deferred.length > 0) {
+            try {
+                for (const action of deferred)
+                    await action();
+            }
+            finally {
+                this._resolveIdleWaitIfIdle();
+            }
+            return;
+        }
+        this._resolveIdleWaitIfIdle();
     }
-    // Track last assistant message for auto-compaction check
-    _lastAssistantMessage = undefined;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     _handleAgentEvent = async (event) => {
         // When a user message starts, check if it's from either queue and remove it BEFORE emitting
@@ -611,28 +810,30 @@ export class AgentSession {
                 }
             }
         }
-        // Emit to extensions first
+        // Emit to extensions first, then notify public listeners.
         await this._emitExtensionEvent(event);
-        // Notify all listeners
         this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
         // Handle session persistence
         if (event.type === "message_end") {
+            let entryId;
             // Check if this is a custom message from extensions
             if (event.message.role === "custom") {
                 // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+                entryId = this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
             }
-            else if (event.message.role === "user" ||
+            else if (event.message.role === "system" ||
+                event.message.role === "user" ||
                 event.message.role === "assistant" ||
                 event.message.role === "toolResult") {
                 // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
+                entryId = this.sessionManager.appendMessage(event.message);
             }
+            if (entryId)
+                this._entryIdsByMessage.set(event.message, entryId);
             // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
-            // Track assistant message for auto-compaction (checked on agent_end)
             if (event.message.role === "assistant") {
-                this._lastAssistantMessage = event.message;
                 const assistantMsg = event.message;
+                this._lastAssistantMessage = assistantMsg;
                 if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "length") {
                     this._overflowRecoveryAttempted = false;
                 }
@@ -654,10 +855,13 @@ export class AgentSession {
         // extension and listener dispatch above also picks up messages that turn_end
         // handlers queued.
         if (event.type === "turn_end") {
+            this._lastAssistantToolResults = event.toolResults;
             this._flushPendingCustomMessages();
         }
     };
     _willRetryAfterAgentEnd(event) {
+        if (this._agentRunAbortRequested)
+            return false;
         const settings = this.settingsManager.getRetrySettings();
         if (!settings.enabled || this._retryAttempt >= settings.maxRetries) {
             return false;
@@ -670,6 +874,47 @@ export class AgentSession {
         }
         return false;
     }
+    _findPersistedMessageEntryId(message) {
+        const mapped = this._entryIdsByMessage.get(message);
+        if (mapped)
+            return mapped;
+        for (const entry of [...this.sessionManager.getBranch()].reverse()) {
+            if (entry.type === "message" && entry.message === message)
+                return entry.id;
+        }
+        const messageIndex = this.agent.state.messages.indexOf(message);
+        if (messageIndex < 0)
+            return undefined;
+        const projection = this.sessionManager.buildSessionProjection();
+        let projectedIndex = 0;
+        for (const entry of projection.entries) {
+            for (let i = 0; i < entry.messages.length; i++) {
+                if (projectedIndex === messageIndex) {
+                    this._entryIdsByMessage.set(message, entry.sourceEntry.id);
+                    return entry.sourceEntry.id;
+                }
+                projectedIndex++;
+            }
+        }
+        return undefined;
+    }
+    _omitRecoveryAttempt(message, toolResults = []) {
+        const targets = [message, ...toolResults];
+        const targetIds = targets.map((target) => this._findPersistedMessageEntryId(target));
+        const unresolvedProjectedTarget = targets.some((target, index) => targetIds[index] === undefined && this.agent.state.messages.includes(target));
+        if (unresolvedProjectedTarget) {
+            throw new Error("Cannot persist recovery omission because a projected message has no source entry");
+        }
+        for (const targetId of targetIds) {
+            if (!targetId)
+                continue;
+            const editId = this.sessionManager.appendContextEdit(targetId, null);
+            const entry = this.sessionManager.getEntry(editId);
+            if (entry)
+                this._emit({ type: "entry_appended", entry });
+        }
+        this._refreshFinalizedContext();
+    }
     /** Find the last assistant message in agent state (including aborted ones) */
     _findLastAssistantMessage() {
         const messages = this.agent.state.messages;
@@ -725,13 +970,9 @@ export class AgentSession {
             await this._extensionRunner.emit(extensionEvent);
         }
         else if (event.type === "turn_end") {
-            const extensionEvent = {
-                type: "turn_end",
-                turnIndex: this._turnIndex,
-                message: event.message,
-                toolResults: event.toolResults,
-            };
-            await this._extensionRunner.emit(extensionEvent);
+            if (event.message.role === "assistant" && !this._boundaryDispatchedMessages.delete(event.message)) {
+                await this._dispatchTurnEndBoundary(event.message, event.toolResults);
+            }
             if (this._hookRuntime?.hasHandlers("turn_end")) {
                 await this._hookRuntime.emitObserve("turn_end", { type: "turn_end" });
             }
@@ -1041,15 +1282,32 @@ export class AgentSession {
         // Every connected MCP server is a child process this session started. Without
         // this, one leaks per server per session, because nothing else owns them.
         this._mcpRuntime?.close().catch(() => undefined);
+        if (this._cacheWarmer) {
+            this._cacheWarmer.onWarmed = undefined;
+            this._cacheWarmer.cancel();
+        }
         cleanupSessionResources(this.sessionId);
     }
     // =========================================================================
     // Read-only State Access
     // =========================================================================
+    /** Refresh the public finalized transcript from the canonical session projection. */
+    refreshContext() {
+        this._refreshFinalizedContext();
+    }
     /** Full agent state */
     get state() {
         return this.agent.state;
     }
+    /** Current cache-warming state and the policy inputs that produced it. */
+    get cacheWarmingStatus() {
+        return this._cacheWarmer?.status;
+    }
+    /** Persist the cache-warming mode and immediately reconcile active warming. */
+    setCacheWarmingMode(mode) {
+        this.settingsManager.setCacheWarmingMode(mode);
+        this._cacheWarmer?.onModeChanged();
+    }
     /** Current model (may be undefined if not yet selected) */
     get model() {
         return this.agent.state.model;
@@ -1062,13 +1320,13 @@ export class AgentSession {
     get isStreaming() {
         return this._isAgentRunActive;
     }
-    /** Whether the session has no active agent run, retry, auto-compaction, or queued continuation. */
+    /** Whether the session has no active agent run, compaction, branch summary, retry, or queued continuation. */
     get isIdle() {
-        return !this._isAgentRunActive;
+        return !this._isAgentRunActive && !this.isCompacting;
     }
-    /** Current effective system prompt (includes any per-turn extension modifications) */
+    /** Current effective system prompt, including changes not yet sent to the model. */
     get systemPrompt() {
-        return this.agent.state.systemPrompt;
+        return buildSystemPrompt(this._runSystemPromptOptions ?? this._baseSystemPromptOptions);
     }
     /** Current retry attempt (0 if not retrying) */
     get retryAttempt() {
@@ -1124,9 +1382,7 @@ export class AgentSession {
             }
         }
         this.agent.state.tools = tools;
-        // Rebuild base system prompt with new tool set
-        this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
-        this.agent.state.systemPrompt = this._systemPromptOverride ?? this._baseSystemPrompt;
+        this._rebuildSystemPrompt(validToolNames);
     }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
@@ -1195,23 +1451,17 @@ export class AgentSession {
     _rebuildSystemPrompt(toolNames) {
         const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
         const toolSnippets = {};
-        const promptGuidelines = [];
-        for (const name of validToolNames) {
+        for (const name of this._toolRegistry.keys()) {
             const snippet = this._toolPromptSnippets.get(name);
-            if (snippet) {
+            if (snippet)
                 toolSnippets[name] = snippet;
-            }
-            const toolGuidelines = this._toolPromptGuidelines.get(name);
-            if (toolGuidelines) {
-                promptGuidelines.push(...toolGuidelines);
-            }
         }
         const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
         const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt();
-        const appendSystemPrompt = loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined;
+        const appendSystemPrompt = loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : "";
         const loadedSkills = this._resourceLoader.getSkills().skills;
         const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
-        this._baseSystemPromptOptions = {
+        this._baseSystemPromptOptions = normalizeBuildSystemPromptOptions({
             cwd: this._cwd,
             skills: loadedSkills,
             contextFiles: loadedContextFiles,
@@ -1219,23 +1469,95 @@ export class AgentSession {
             appendSystemPrompt,
             selectedTools: validToolNames,
             toolSnippets,
-            promptGuidelines,
+            toolGuidelines: Object.fromEntries(this._toolPromptGuidelines),
+        });
+    }
+    /**
+     * Apply a prompt and tool loadout for the next request. Sets the executable tools and
+     * returns a system message patching the prompt sections the model currently has (replayed
+     * from `messages`), or undefined when the prompt is unchanged. Tool changes are declared by
+     * the agent loop before the request.
+     *
+     * A forced prompt does not affect the transcript: the structured sections are still diffed
+     * and persisted, and the forced text is projected onto the request by
+     * {@link _installAgentForcedPromptProjection}.
+     */
+    _preparePromptAndToolLoadout(options, messages = this.agent.state.messages) {
+        options.selectedTools = [...new Set(options.selectedTools)].filter((name) => this._toolRegistry.has(name));
+        this.agent.state.tools = options.selectedTools.flatMap((name) => {
+            const tool = this._toolRegistry.get(name);
+            return tool ? [tool] : [];
+        });
+        const sections = diffSystemPromptSections(getCurrentSystemMessage(messages)?.sections ?? {}, buildSystemPromptSections(options));
+        return sections ? { role: "system", content: "", sections, timestamp: Date.now() } : undefined;
+    }
+    /**
+     * Send a forced prompt as the provider's leading system prompt without recording it.
+     *
+     * A `before_agent_start` handler that returns `systemPrompt` needs that exact text at the
+     * head of the request; a mid-conversation system message would leave the original prompt
+     * in place. The forced text is a rendering of the current prompt, so the transcript keeps
+     * its structured sections and the request is projected instead: the system messages
+     * collapse into one head holding the forced text and the current tools. Runs after the
+     * `context` extension handlers.
+     */
+    _installAgentForcedPromptProjection() {
+        const previousTransformContext = this.agent.transformContext;
+        this.agent.transformContext = async (messages, signal) => {
+            const transformed = previousTransformContext ? await previousTransformContext(messages, signal) : messages;
+            const forced = this._runSystemPromptOptions?.forceSystemPrompt;
+            if (forced === undefined)
+                return transformed;
+            const current = getCurrentSystemMessage(transformed);
+            const head = {
+                role: "system",
+                content: forced,
+                ...(current?.toolsAdded ? { toolsAdded: current.toolsAdded } : {}),
+                timestamp: current?.timestamp ?? Date.now(),
+            };
+            return [head, ...transformed.filter((message) => message.role !== "system")];
         };
-        return buildSystemPrompt(this._baseSystemPromptOptions);
+    }
+    /** Restore the active tool loadout declared by the session transcript, if it declares one. */
+    _restoreToolsFromTranscript() {
+        const current = getCurrentSystemMessage(this.sessionManager.buildSessionContext().messages);
+        if (!current)
+            return;
+        const toolNames = (current.toolsAdded ?? [])
+            .map((tool) => tool.name)
+            .filter((name) => this._toolRegistry.has(name));
+        this.agent.state.tools = toolNames.flatMap((name) => {
+            const registered = this._toolRegistry.get(name);
+            return registered ? [registered] : [];
+        });
+        this._rebuildSystemPrompt(toolNames);
     }
     // =========================================================================
     // Prompting
     // =========================================================================
     async _runAgentPrompt(messages) {
+        this._agentRunAbortRequested = false;
         this._isAgentRunActive = true;
         try {
             await this.agent.prompt(messages);
-            while (await this._handlePostAgentRun()) {
+            while (!this._agentRunAbortRequested) {
+                if (await this._handlePostAgentRun()) {
+                    if (this._agentRunAbortRequested)
+                        break;
+                    await this.agent.continue();
+                    continue;
+                }
+                if (this._agentRunAbortRequested || !(await this._runBeforeSettleBoundary()))
+                    break;
+                if (this._agentRunAbortRequested)
+                    break;
                 await this.agent.continue();
             }
         }
         finally {
-            this._systemPromptOverride = undefined;
+            if (this._agentRunAbortRequested)
+                this._finishCancelledRetry();
+            this._runSystemPromptOptions = undefined;
             this._flushPendingBashMessages();
             this._flushPendingCustomMessages();
             await this._emitAgentSettled();
@@ -1246,29 +1568,96 @@ export class AgentSession {
             this._midRunCompactionNeeded = false;
             return await this._runAutoCompaction("threshold", true);
         }
-        const msg = this._lastAssistantMessage;
+        const message = this._lastAssistantMessage;
+        const toolResults = this._lastAssistantToolResults;
         this._lastAssistantMessage = undefined;
-        if (!msg) {
+        this._lastAssistantToolResults = [];
+        if (this._agentRunAbortRequested) {
+            this._finishCancelledRetry();
             return false;
         }
-        if (this._isRetryableError(msg) && (await this._prepareRetry(msg))) {
-            return true;
+        if (!message)
+            return this.agent.hasQueuedMessages();
+        if (this._isRetryableError(message) && (await this._prepareRetry(message))) {
+            if (this._agentRunAbortRequested)
+                this._finishCancelledRetry();
+            return !this._agentRunAbortRequested;
+        }
+        if (this._agentRunAbortRequested) {
+            this._finishCancelledRetry();
+            return false;
         }
-        if (msg.stopReason === "error" && this._retryAttempt > 0) {
+        if (message.stopReason === "error" && this._retryAttempt > 0) {
             this._emit({
                 type: "auto_retry_end",
                 success: false,
                 attempt: this._retryAttempt,
-                finalError: msg.errorMessage,
+                finalError: message.errorMessage,
             });
             this._retryAttempt = 0;
         }
-        if (await this._checkCompaction(msg)) {
-            return true;
+        if (await this._checkCompaction(message, true, toolResults)) {
+            return !this._agentRunAbortRequested;
+        }
+        // The low-level loop drains both queues before agent_end. Messages queued by
+        // agent_end handlers require a fresh run before pre-settlement handlers fire.
+        return !this._agentRunAbortRequested && this.agent.hasQueuedMessages();
+    }
+    async _runBeforeSettleBoundary() {
+        if (!this._extensionRunner.hasHandlers("agent_before_settle"))
+            return this.agent.hasQueuedMessages();
+        this._isBeforeSettle = true;
+        this._abortDuringBeforeSettle = false;
+        try {
+            const result = await this._extensionRunner.emitBoundary({ type: "agent_before_settle", outcome: this._lastActivityOutcome }, (entries) => this._buildBoundaryContext(entries, "agent_before_settle"));
+            this._commitBoundaryDrafts(result.entries);
+            this._flushPendingCustomMessages();
+            const finalContext = this._buildBoundaryContext([], "agent_before_settle");
+            if (this._abortDuringBeforeSettle)
+                return false;
+            const shouldContinue = result.continue || this.agent.hasQueuedMessages();
+            if (shouldContinue && !finalContext.canContinue) {
+                if (result.continue)
+                    this._reportInvalidBoundaryContinuation("agent_before_settle");
+                return false;
+            }
+            return shouldContinue;
+        }
+        finally {
+            this._isBeforeSettle = false;
+        }
+    }
+    async _runInputHandlers(text, images, source, streamingBehavior) {
+        if (!this._extensionRunner.hasHandlers("input")) {
+            return { text, images };
+        }
+        const inputResult = await this._extensionRunner.emitInput(text, images, source, streamingBehavior);
+        if (inputResult.action === "handled") {
+            return undefined;
+        }
+        if (inputResult.action === "transform") {
+            return { text: inputResult.text, images: inputResult.images ?? images };
+        }
+        return { text, images };
+    }
+    async _normalizePromptImages(images) {
+        if (!images)
+            return { images: [], hints: [] };
+        const normalizedImages = [];
+        const hints = [];
+        for (const image of images) {
+            const processed = await processImage(Buffer.from(image.data, "base64"), image.mimeType, {
+                autoResizeImages: this.settingsManager.getImageAutoResize(),
+                resizeOptions: this.model?.inputLimits?.images?.resize,
+            });
+            if (!processed.ok) {
+                hints.push(processed.message);
+                continue;
+            }
+            normalizedImages.push({ type: "image", data: processed.data, mimeType: processed.mimeType });
+            hints.push(...processed.hints);
         }
-        // The agent loop drains both queues before emitting agent_end. Any messages
-        // here were queued by agent_end extension handlers and need a continuation.
-        return this.agent.hasQueuedMessages();
+        return { images: normalizedImages, hints };
     }
     /**
      * Send a prompt to the agent.
@@ -1280,6 +1669,10 @@ export class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     async prompt(text, options) {
+        if (this._isEmittingAgentSettled) {
+            this._deferredSettledActions.push(async () => await this.prompt(text, options));
+            return;
+        }
         if (this._lifecycle === "closed")
             throw new Error("Session is closed.");
         if (this._activePrompt) {
@@ -1325,19 +1718,12 @@ export class AgentSession {
                 throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
             }
             // Emit input event for extension interception (before skill/template expansion)
-            let currentText = text;
-            let currentImages = options?.images;
-            if (this._extensionRunner.hasHandlers("input")) {
-                const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive", this.isStreaming ? options?.streamingBehavior : undefined);
-                if (inputResult.action === "handled") {
-                    preflightResult?.(true);
-                    return;
-                }
-                if (inputResult.action === "transform") {
-                    currentText = inputResult.text;
-                    currentImages = inputResult.images ?? currentImages;
-                }
+            const processedInput = await this._runInputHandlers(text, options?.images, options?.source ?? "interactive", this.isStreaming ? options?.streamingBehavior : undefined);
+            if (!processedInput) {
+                preflightResult?.(true);
+                return;
             }
+            const { text: currentText, images: currentImages } = processedInput;
             // Expand skill commands (/skill:name args) and prompt templates (/template args)
             let expandedText = currentText;
             if (expandPromptTemplates) {
@@ -1382,13 +1768,23 @@ export class AgentSession {
             if (lastAssistant) {
                 await this._checkCompaction(lastAssistant, false);
             }
-            // Build messages array (custom message if any, then user message)
+            // Emit before_agent_start before normalizing images so extension-driven model
+            // selection determines the resize profile used for the request and history.
+            const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;
+            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPromptOptions);
+            // Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),
+            // which updates the live loadout instead. An explicit edit wins; otherwise the live
+            // loadout is authoritative, so a setActiveTools() call is not undone here.
+            const handlerEditedTools = result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||
+                result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);
+            if (!handlerEditedTools)
+                result.systemPromptOptions.selectedTools = this.getActiveToolNames();
+            const normalized = await this._normalizePromptImages(currentImages);
+            const userText = normalized.hints.length > 0 ? `${expandedText}\n\n${normalized.hints.join("\n")}` : expandedText;
+            // Build messages only after hooks and image normalization have completed.
             messages = [];
-            // Add user message
-            const userContent = [{ type: "text", text: expandedText }];
-            if (currentImages) {
-                userContent.push(...currentImages);
-            }
+            const userContent = [{ type: "text", text: userText }];
+            userContent.push(...normalized.images);
             messages.push({
                 role: "user",
                 content: userContent,
@@ -1399,32 +1795,21 @@ export class AgentSession {
                 messages.push(msg);
             }
             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) {
-                    messages.push({
-                        role: "custom",
-                        customType: msg.customType,
-                        // Untyped extensions can pass null/missing content; normalize at ingestion.
-                        content: msg.content ?? [],
-                        display: msg.display,
-                        details: msg.details,
-                        timestamp: Date.now(),
-                    });
-                }
-            }
-            // Apply extension-modified system prompt, or reset to base
-            if (result?.systemPrompt !== undefined) {
-                this._systemPromptOverride = result.systemPrompt;
-                this.agent.state.systemPrompt = result.systemPrompt;
-            }
-            else {
-                // Ensure we're using the base prompt (in case previous turn had modifications)
-                this._systemPromptOverride = undefined;
-                this.agent.state.systemPrompt = this._baseSystemPrompt;
+            for (const msg of result.messages) {
+                messages.push({
+                    role: "custom",
+                    customType: msg.customType,
+                    // Untyped extensions can pass null/missing content; normalize at ingestion.
+                    content: msg.content ?? [],
+                    display: msg.display,
+                    details: msg.details,
+                    timestamp: Date.now(),
+                });
             }
+            const updateMessage = this._preparePromptAndToolLoadout(result.systemPromptOptions);
+            this._runSystemPromptOptions = result.systemPromptOptions;
+            if (updateMessage)
+                messages.unshift(updateMessage);
         }
         catch (error) {
             preflightResult?.(false);
@@ -1504,40 +1889,44 @@ export class AgentSession {
             return text; // Return original on error
         }
     }
+    async _queueUserInput(text, images, behavior, source) {
+        if (text.startsWith("/")) {
+            this._throwIfExtensionCommand(text);
+        }
+        const processedInput = await this._runInputHandlers(text, images, source, this.isStreaming ? behavior : undefined);
+        if (!processedInput)
+            return;
+        let expandedText = this._expandSkillCommand(processedInput.text);
+        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        if (behavior === "steer") {
+            await this._queueSteer(expandedText, processedInput.images);
+        }
+        else {
+            await this._queueFollowUp(expandedText, processedInput.images);
+        }
+    }
     /**
      * 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
+     * @param options Input source; defaults to interactive
      * @throws Error if text is an extension command
      */
-    async steer(text, images) {
-        // Check for extension commands (cannot be queued)
-        if (text.startsWith("/")) {
-            this._throwIfExtensionCommand(text);
-        }
-        // Expand skill commands and prompt templates
-        let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-        await this._queueSteer(expandedText, images);
+    async steer(text, images, options) {
+        await this._queueUserInput(text, images, "steer", options?.source ?? "interactive");
     }
     /**
      * Queue a follow-up message to be processed after the agent finishes.
      * Delivered only when agent has no more tool calls or steering messages.
      * Expands skill commands and prompt templates. Errors on extension commands.
      * @param images Optional image attachments to include with the message
+     * @param options Input source; defaults to interactive
      * @throws Error if text is an extension command
      */
-    async followUp(text, images) {
-        // Check for extension commands (cannot be queued)
-        if (text.startsWith("/")) {
-            this._throwIfExtensionCommand(text);
-        }
-        // Expand skill commands and prompt templates
-        let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-        await this._queueFollowUp(expandedText, images);
+    async followUp(text, images, options) {
+        await this._queueUserInput(text, images, "followUp", options?.source ?? "interactive");
     }
     /**
      * Internal: Queue a steering message (already expanded, no extension command check).
@@ -1565,11 +1954,7 @@ export class AgentSession {
         if (images) {
             content.push(...images);
         }
-        this.agent.followUp({
-            role: "user",
-            content,
-            timestamp: Date.now(),
-        });
+        this.agent.followUp({ role: "user", content, timestamp: Date.now() });
     }
     /**
      * Throw an error if the text is an extension command.
@@ -1617,6 +2002,10 @@ export class AgentSession {
             }
         }
         else if (options?.triggerTurn) {
+            if (this._isEmittingAgentSettled) {
+                this._deferredSettledActions.push(async () => await this._runAgentPrompt(appMessage));
+                return;
+            }
             await this._runAgentPrompt(appMessage);
         }
         else if (this.isStreaming) {
@@ -1631,8 +2020,8 @@ export class AgentSession {
         }
     }
     _appendCustomMessage(appMessage) {
-        this.agent.state.messages.push(appMessage);
         this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
+        this._refreshFinalizedContext();
         this._emit({ type: "message_start", message: appMessage });
         this._emit({ type: "message_end", message: appMessage });
     }
@@ -1721,7 +2110,14 @@ export class AgentSession {
     async abort() {
         if (this._activePrompt && this._lifecycle !== "closed")
             this._lifecycle = "interrupted";
+        if (this._isAgentRunActive) {
+            this._agentRunAbortRequested = true;
+        }
         this.abortRetry();
+        this.abortCompaction();
+        this.abortBranchSummary();
+        if (this._isBeforeSettle)
+            this._abortDuringBeforeSettle = true;
         this.agent.abort();
         await this.waitForIdle();
     }
@@ -2195,6 +2591,10 @@ export class AgentSession {
         this.agent.recordMaintenanceRequest();
         return compact(preparation, requestModel, apiKey, headers, customInstructions, signal, this.thinkingLevel, this.agent.streamFunction, env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), undefined);
     }
+    _clearManualCompactionState() {
+        this._compactionAbortController = undefined;
+        this._resolveIdleWaitIfIdle();
+    }
     /**
      * Manually compact the session context.
      *
@@ -2215,13 +2615,15 @@ export class AgentSession {
         this._compactionAbortController = new AbortController();
         this._emit({ type: "compaction_start", reason: "manual" });
         let fromExtension = false;
+        let cancelledByExtension = false;
         try {
-            if (!this.model) {
+            const model = this.model;
+            if (!model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
-            const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(this.model);
+            const settings = this.settingsManager.getCompactionSettings(model);
+            const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, this._compactionAbortController.signal);
             const pathEntries = this.sessionManager.getBranch();
-            const settings = this.settingsManager.getCompactionSettings();
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
                 // Check why we can't compact
@@ -2249,6 +2651,7 @@ export class AgentSession {
                     signal: this._compactionAbortController.signal,
                 }));
                 if (result?.cancel) {
+                    cancelledByExtension = true;
                     throw new Error("Compaction cancelled");
                 }
                 if (result?.compaction) {
@@ -2306,9 +2709,8 @@ export class AgentSession {
                 }
             }
             const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
             // Get the saved compaction entry for the extension event
             const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
             if (this._extensionRunner && savedCompactionEntry) {
@@ -2329,7 +2731,7 @@ export class AgentSession {
                 details,
             };
             // compaction_end listeners may submit queued prompts, so expose idle state before notifying them.
-            this._compactionAbortController = undefined;
+            this._clearManualCompactionState();
             this._emit({
                 type: "compaction_end",
                 reason: "manual",
@@ -2341,9 +2743,9 @@ export class AgentSession {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            const aborted = message === "Compaction cancelled" || (error instanceof Error && error.name === "AbortError");
+            const aborted = this._compactionAbortController.signal.aborted || cancelledByExtension;
             const errorMessage = aborted ? undefined : `Compaction failed: ${message}`;
-            this._compactionAbortController = undefined;
+            this._clearManualCompactionState();
             this._emit({
                 type: "compaction_end",
                 reason: "manual",
@@ -2362,7 +2764,7 @@ export class AgentSession {
             throw error;
         }
         finally {
-            this._compactionAbortController = undefined;
+            this._clearManualCompactionState();
         }
     }
     /**
@@ -2399,8 +2801,8 @@ export class AgentSession {
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
      */
-    async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
-        const settings = this.settingsManager.getCompactionSettings();
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true, toolResults = []) {
+        const settings = this.settingsManager.getCompactionSettings(this.model);
         if (!settings.enabled)
             return false;
         // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
@@ -2423,8 +2825,27 @@ export class AgentSession {
         // Automatic cases 1 and 2: context overflow.
         // A length stop is recoverable when output ended below the model's original desired limit,
         // independent of the configured context size or any context-clamped provider request limit.
-        const contextOverflow = sameModel && isContextOverflow(assistantMessage, contextWindow);
-        const recoverableLength = sameModel && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
+        const currentProjection = this.sessionManager.buildSessionProjection();
+        const assistantEntryId = this._findPersistedMessageEntryId(assistantMessage);
+        const assistantIsProjected = assistantEntryId === undefined ||
+            currentProjection.entries.some((entry) => entry.sourceEntry.id === assistantEntryId &&
+                entry.messages.some((message) => message.role === "assistant"));
+        const branch = this.sessionManager.getBranch();
+        const assistantIndex = assistantEntryId ? branch.findIndex((entry) => entry.id === assistantEntryId) : -1;
+        const entriesAfterAssistant = assistantIndex >= 0 ? branch.slice(assistantIndex + 1) : [];
+        const hasPostAssistantContextEdit = entriesAfterAssistant.some((entry) => entry.type === "context_edit");
+        const latestAssistantEdit = entriesAfterAssistant
+            .filter((entry) => entry.type === "context_edit" && entry.targetId === assistantEntryId)
+            .at(-1);
+        const assistantRetainedForExplicitRecovery = assistantEntryId === undefined ||
+            (!entriesAfterAssistant.some((entry) => entry.type === "compaction") &&
+                latestAssistantEdit?.replacement !== null);
+        const assistantUsageMatchesProjection = assistantIsProjected && !hasPostAssistantContextEdit;
+        const explicitOverflow = assistantMessage.stopReason === "error" && isContextOverflow(assistantMessage);
+        const contextOverflow = sameModel &&
+            ((explicitOverflow && assistantRetainedForExplicitRecovery) ||
+                (assistantUsageMatchesProjection && isContextOverflow(assistantMessage, contextWindow)));
+        const recoverableLength = sameModel && assistantIsProjected && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
         if (contextOverflow || recoverableLength) {
             const willRetry = assistantMessage.stopReason !== "stop";
             // Case 2: the response completed successfully. Compact, but do not retry because
@@ -2453,13 +2874,9 @@ export class AgentSession {
                 });
                 return false;
             }
-            // Case 1: remove the failed or truncated message from agent state, compact, and
-            // retry once. The message remains in session history but is excluded from retry context.
+            // Persistently omit the selected final attempt before post-run recovery compaction.
             this._overflowRecoveryAttempted = true;
-            const messages = this.agent.state.messages;
-            if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-                this.agent.state.messages = messages.slice(0, -1);
-            }
+            this._omitRecoveryAttempt(assistantMessage, toolResults);
             return await this._runAutoCompaction("overflow", willRetry);
         }
         // Case 3: threshold compaction without retry.
@@ -2467,8 +2884,13 @@ export class AgentSession {
         // This ensures sessions that hit persistent API errors (e.g. 529) or malformed zero-usage
         // responses can still compact and do not reset context accounting.
         let contextTokens;
+        const projection = currentProjection;
+        const hasContextEdits = projection.entries.some((entry) => entry.sourceEntry.type === "context_edit");
         const directContextTokens = assistantMessage.usage ? calculateContextTokens(assistantMessage.usage) : 0;
-        if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
+        if (hasContextEdits) {
+            contextTokens = estimateProjectedContextTokens(projection, branch).tokens;
+        }
+        else if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
             const messages = this.agent.state.messages;
             const estimate = estimateContextTokens(messages);
             // Without provider usage, estimate.tokens is the pure message-size estimate.
@@ -2505,22 +2927,28 @@ export class AgentSession {
      * @returns Whether the post-run loop should call `agent.continue()`
      */
     async _runAutoCompaction(reason, willRetry) {
-        const settings = this.settingsManager.getCompactionSettings();
+        const model = this.model;
+        const settings = this.settingsManager.getCompactionSettings(model);
+        let abortController;
         let started = false;
         let fromExtension = false;
+        let cancelledByExtension = false;
         try {
-            if (!this.model) {
+            if (!model) {
                 return false;
             }
-            const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(this.model);
             const pathEntries = this.sessionManager.getBranch();
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
                 return false;
             }
-            this._emit({ type: "compaction_start", reason });
-            this._autoCompactionAbortController = new AbortController();
+            abortController = new AbortController();
+            this._autoCompactionAbortController = abortController;
             started = true;
+            this._emit({ type: "compaction_start", reason });
+            abortController.signal.throwIfAborted();
+            const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, abortController.signal);
+            abortController.signal.throwIfAborted();
             let extensionCompaction;
             if (this._hookRuntime?.hasHandlers("session_before_compact")) {
                 await this._hookRuntime.emitObserve("session_before_compact", { type: "session_before_compact", reason });
@@ -2533,29 +2961,18 @@ export class AgentSession {
                     customInstructions: undefined,
                     reason,
                     willRetry,
-                    signal: this._autoCompactionAbortController.signal,
+                    signal: abortController.signal,
                 }));
                 if (extensionResult?.cancel) {
-                    this._emit({
-                        type: "compaction_end",
-                        reason,
-                        result: undefined,
-                        aborted: true,
-                        willRetry: false,
-                    });
-                    await this._emitSessionCompactFailed({
-                        reason,
-                        aborted: true,
-                        willRetry: false,
-                        fromExtension: false,
-                    });
-                    return false;
+                    cancelledByExtension = true;
+                    throw new Error("Compaction cancelled");
                 }
                 if (extensionResult?.compaction) {
                     extensionCompaction = extensionResult.compaction;
                     fromExtension = true;
                 }
             }
+            abortController.signal.throwIfAborted();
             let summary;
             let firstKeptEntryId;
             let tokensBefore;
@@ -2577,7 +2994,7 @@ export class AgentSession {
             }
             else {
                 // Shared default summary generator, also used by manual compaction.
-                const compactResult = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, undefined, this._autoCompactionAbortController.signal, env, reason);
+                const compactResult = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, undefined, abortController.signal, env, reason);
                 summary = compactResult.summary;
                 firstKeptEntryId = compactResult.firstKeptEntryId;
                 tokensBefore = compactResult.tokensBefore;
@@ -2587,22 +3004,7 @@ export class AgentSession {
                     summary += `\n\n${formatWorkspaceProjection(workspaceRecord)}`;
                 }
             }
-            if (this._autoCompactionAbortController.signal.aborted) {
-                this._emit({
-                    type: "compaction_end",
-                    reason,
-                    result: undefined,
-                    aborted: true,
-                    willRetry: false,
-                });
-                await this._emitSessionCompactFailed({
-                    reason,
-                    aborted: true,
-                    willRetry: false,
-                    fromExtension,
-                });
-                return false;
-            }
+            abortController.signal.throwIfAborted();
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
             if (workspaceRecord) {
                 try {
@@ -2619,9 +3021,8 @@ export class AgentSession {
                 }
             }
             const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
             // Get the saved compaction entry for the extension event
             const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
             if (this._extensionRunner && savedCompactionEntry) {
@@ -2642,40 +3043,33 @@ export class AgentSession {
                 details,
             };
             this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-            if (willRetry) {
-                const messages = this.agent.state.messages;
-                const lastMsg = messages[messages.length - 1];
-                // The overflow response was persisted on message_end before _checkCompaction() removed it
-                // from agent state. Rebuilding state from the new compaction can restore that kept entry,
-                // leaving an assistant as the final message. agent.continue() rejects that state, so remove
-                // the retriable error or truncated-length response again before continuing the interrupted turn.
-                if (lastMsg?.role === "assistant" && (lastMsg.stopReason === "error" || lastMsg.stopReason === "length")) {
-                    this.agent.state.messages = messages.slice(0, -1);
-                }
+            if (willRetry)
                 return true;
-            }
             // Auto-compaction can complete while follow-up/steering/custom messages are waiting.
             // Continue once so queued messages are delivered.
             return this.agent.hasQueuedMessages();
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : "compaction failed";
+            const message = error instanceof Error ? error.message : "compaction failed";
+            const aborted = abortController?.signal.aborted === true || cancelledByExtension;
             if (started) {
-                const formattedErrorMessage = reason === "overflow"
-                    ? `Context overflow recovery failed: ${errorMessage}`
-                    : `Auto-compaction failed: ${errorMessage}`;
+                const errorMessage = aborted
+                    ? undefined
+                    : reason === "overflow"
+                        ? `Context overflow recovery failed: ${message}`
+                        : `Auto-compaction failed: ${message}`;
                 this._emit({
                     type: "compaction_end",
                     reason,
                     result: undefined,
-                    aborted: false,
+                    aborted,
                     willRetry: false,
-                    errorMessage: formattedErrorMessage,
+                    errorMessage,
                 });
                 await this._emitSessionCompactFailed({
                     reason,
-                    errorMessage: formattedErrorMessage,
-                    aborted: false,
+                    errorMessage,
+                    aborted,
                     willRetry: false,
                     fromExtension,
                 });
@@ -2683,7 +3077,10 @@ export class AgentSession {
             return false;
         }
         finally {
-            this._autoCompactionAbortController = undefined;
+            if (this._autoCompactionAbortController === abortController) {
+                this._autoCompactionAbortController = undefined;
+            }
+            this._resolveIdleWaitIfIdle();
         }
     }
     /**
@@ -2733,8 +3130,7 @@ export class AgentSession {
             themePaths: this.buildExtensionResourcePaths(themePaths),
         };
         this._resourceLoader.extendResources(extensionPaths);
-        this._baseSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames());
-        this.agent.state.systemPrompt = this._baseSystemPrompt;
+        this._rebuildSystemPrompt(this.getActiveToolNames());
     }
     buildExtensionResourcePaths(entries) {
         return entries.map((entry) => {
@@ -3113,6 +3509,18 @@ export class AgentSession {
             },
         };
     }
+    _finishCancelledRetry() {
+        if (this._retryAttempt === 0)
+            return;
+        const attempt = this._retryAttempt;
+        this._retryAttempt = 0;
+        this._emit({
+            type: "auto_retry_end",
+            success: false,
+            attempt,
+            finalError: "Retry cancelled",
+        });
+    }
     /**
      * Prepare a retryable error for continuation with exponential backoff.
      * @returns true if the caller should continue the agent, false otherwise
@@ -3128,7 +3536,7 @@ export class AgentSession {
             this._retryAttempt--;
             return false;
         }
-        const delayMs = settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        const delayMs = retryDelayMs(settings, this._retryAttempt);
         this._emit({
             type: "auto_retry_start",
             attempt: this._retryAttempt,
@@ -3136,11 +3544,8 @@ export class AgentSession {
             delayMs,
             errorMessage: message.errorMessage || "Unknown error",
         });
-        // Remove error message from agent state (keep in session for history)
-        const messages = this.agent.state.messages;
-        if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-            this.agent.state.messages = messages.slice(0, -1);
-        }
+        // Keep the failed attempt in raw history while durably omitting it from model projection.
+        this._omitRecoveryAttempt(message);
         // Wait with exponential backoff (abortable)
         this._retryAbortController = new AbortController();
         try {
@@ -3148,14 +3553,7 @@ export class AgentSession {
         }
         catch {
             // Aborted during sleep - emit end event so UI can clean up
-            const attempt = this._retryAttempt;
-            this._retryAttempt = 0;
-            this._emit({
-                type: "auto_retry_end",
-                success: false,
-                attempt,
-                finalError: "Retry cancelled",
-            });
+            this._finishCancelledRetry();
             return false;
         }
         finally {
@@ -3239,10 +3637,8 @@ export class AgentSession {
             this._pendingBashMessages.push(bashMessage);
         }
         else {
-            // Add to agent state immediately
-            this.agent.state.messages.push(bashMessage);
-            // Save to session
             this.sessionManager.appendMessage(bashMessage);
+            this._refreshFinalizedContext();
         }
     }
     /**
@@ -3269,12 +3665,10 @@ export class AgentSession {
         if (this._pendingBashMessages.length === 0)
             return;
         for (const bashMessage of this._pendingBashMessages) {
-            // Add to agent state
-            this.agent.state.messages.push(bashMessage);
-            // Save to session
             this.sessionManager.appendMessage(bashMessage);
         }
         this._pendingBashMessages = [];
+        this._refreshFinalizedContext();
     }
     // =========================================================================
     // Session Management
@@ -3306,6 +3700,9 @@ export class AgentSession {
         if (this.isStreaming) {
             throw new Error("Wait for the current response to finish before navigating the session tree.");
         }
+        if (this.isCompacting) {
+            throw new Error("Wait for the current compaction or tree navigation to finish before navigating the session tree.");
+        }
         const oldLeafId = this.sessionManager.getLeafId();
         // No-op if already at target
         if (targetId === oldLeafId) {
@@ -3452,9 +3849,9 @@ export class AgentSession {
             if (label && !summaryText) {
                 this.sessionManager.appendLabelChange(targetId, label);
             }
-            // Update agent state
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
+            // Update finalized context from the canonical session projection.
+            this._refreshFinalizedContext();
+            this._restoreToolsFromTranscript();
             // Emit session_tree event
             await this._extensionRunner.emit({
                 type: "session_tree",
@@ -3468,6 +3865,7 @@ export class AgentSession {
         }
         finally {
             this._branchSummaryAbortController = undefined;
+            this._resolveIdleWaitIfIdle();
         }
     }
     /**
@@ -3566,7 +3964,10 @@ export class AgentSession {
         let toolCalls = 0;
         const usageTotals = createUsageTotals();
         for (const entry of this.sessionManager.getEntries()) {
-            if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+            if (entry.type === "usage") {
+                addUsageToTotals(usageTotals, entry.usage);
+            }
+            else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
                 addUsageToTotals(usageTotals, entry.usage);
             }
             if (entry.type !== "message")
@@ -3620,30 +4021,24 @@ export class AgentSession {
         // After compaction, the last assistant usage reflects pre-compaction context size.
         // We can only trust usage from an assistant that responded after the latest compaction.
         // If no such assistant exists, context token count is unknown until the next LLM response.
-        const branchEntries = this.sessionManager.getBranch();
-        const latestCompaction = getLatestCompactionEntry(branchEntries);
+        const projection = this.sessionManager.buildSessionProjection();
+        const branch = this.sessionManager.getBranch();
+        const latestCompaction = getLatestCompactionEntry(branch);
         if (latestCompaction) {
-            // Check if there's a valid assistant usage after the compaction boundary
-            const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
-            let hasPostCompactionUsage = false;
-            for (let i = branchEntries.length - 1; i > compactionIndex; i--) {
-                const entry = branchEntries[i];
-                if (entry.type === "message" && entry.message.role === "assistant") {
-                    const assistant = entry.message;
-                    if (assistant.stopReason !== "aborted" && assistant.stopReason !== "error") {
-                        const contextTokens = calculateContextTokens(assistant.usage);
-                        if (contextTokens > 0) {
-                            hasPostCompactionUsage = true;
-                            break;
-                        }
-                    }
-                }
-            }
-            if (!hasPostCompactionUsage) {
+            const projectedAssistants = new Set(projection.entries.flatMap((entry) => entry.messages.some((message) => message.role === "assistant" &&
+                message.stopReason !== "aborted" &&
+                message.stopReason !== "error" &&
+                calculateContextTokens(message.usage) > 0)
+                ? [entry.sourceEntry.id]
+                : []));
+            const compactionIndex = branch.findIndex((entry) => entry.id === latestCompaction.id);
+            const hasPostCompactionUsage = branch
+                .slice(compactionIndex + 1)
+                .some((entry) => projectedAssistants.has(entry.id));
+            if (!hasPostCompactionUsage)
                 return { tokens: null, contextWindow, percent: null };
-            }
         }
-        const estimate = estimateContextTokens(this.messages);
+        const estimate = estimateProjectedContextTokens(projection, branch);
         const percent = (estimate.tokens / contextWindow) * 100;
         return {
             tokens: estimate.tokens,
@@ -3680,6 +4075,30 @@ export class AgentSession {
     exportToJsonl(outputPath) {
         return exportSessionToJsonl(this.sessionManager, outputPath);
     }
+    /**
+     * Ask the current model to describe what went wrong in this session for a bug report.
+     * Used when the user declines to share the transcript itself.
+     */
+    async summarizeForBugReport(options) {
+        const model = this.model;
+        if (!model) {
+            throw new Error("No model selected");
+        }
+        const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(model);
+        return generateBugReportSummary({
+            messages: this.messages,
+            hint: options.hint,
+            model: requestModel,
+            apiKey,
+            headers,
+            env,
+            signal: options.signal,
+            thinkingLevel: this.thinkingLevel,
+            streamFn: this.agent.streamFunction,
+            retry: this.settingsManager.getRetrySettings(),
+            sessionId: this.sessionId,
+        });
+    }
     // =========================================================================
     // Utilities
     // =========================================================================