@earendil-works/pi-coding-agent 0.86.1 → 0.87.0

package/dist/core/agent-session.js

@@ -18,21 +18,23 @@ import { contentText, getCurrentSystemMessage, retryDelayMs } from "@earendil-wo
 import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
 import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
+import { 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 { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
+import { convertToLlm } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { exportSessionToJsonl } from "./session-export.js";
-import { getLatestCompactionEntry } from "./session-manager.js";
+import { getLatestCompactionEntry, SessionManager, } from "./session-manager.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt, buildSystemPromptSections, diffSystemPromptSections, normalizeBuildSystemPromptOptions, } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
@@ -107,6 +109,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();
@@ -158,6 +169,8 @@ export class AgentSession {
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
         this._installAgentNextTurnRefresh();
+        this._installAgentRequestProjection();
+        this._installAgentBoundaryHooks();
         this._installAgentForcedPromptProjection();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
@@ -265,8 +278,10 @@ export class AgentSession {
                 : undefined;
             const content = hookResult?.content ?? result.content ?? [];
             // Runs after the extension hook so images injected or replaced by extensions are normalized too.
+            const resizeOptions = this.model?.inputLimits?.images?.resize;
             const normalizedContent = await normalizeToolResultImages(content, {
                 autoResizeImages: this.settingsManager.getImageAutoResize(),
+                ...(resizeOptions ? { resizeOptions } : {}),
             });
             if (!hookResult && normalizedContent === content) {
                 return undefined;
@@ -282,15 +297,83 @@ export class AgentSession {
     async _compactBeforeNextAssistantResponse(context) {
         const model = this.model;
         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() {
@@ -299,7 +382,10 @@ 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;
@@ -329,6 +415,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) {
@@ -367,16 +531,27 @@ export class AgentSession {
     async _emitAgentSettled() {
         this._cacheWarmer?.onAgentSettled();
         this._isAgentRunActive = false;
+        this._isEmittingAgentSettled = true;
         try {
             await this._extensionRunner.emit({ type: "agent_settled" });
             this._emit({ type: "agent_settled" });
         }
         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
@@ -401,29 +576,30 @@ export class AgentSession {
                 }
             }
         }
-        // Emit to extensions first
+        // Emit to extensions first, then notify public listeners.
         await this._emitExtensionEvent(event);
-        // Notify all listeners
         this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
         // Handle session persistence
         if (event.type === "message_end") {
+            let entryId;
             // Check if this is a custom message from extensions
             if (event.message.role === "custom") {
                 // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+                entryId = this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
             }
             else if (event.message.role === "system" ||
                 event.message.role === "user" ||
                 event.message.role === "assistant" ||
                 event.message.role === "toolResult") {
                 // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
+                entryId = this.sessionManager.appendMessage(event.message);
             }
+            if (entryId)
+                this._entryIdsByMessage.set(event.message, entryId);
             // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
-            // Track assistant message for auto-compaction (checked on agent_end)
             if (event.message.role === "assistant") {
-                this._lastAssistantMessage = event.message;
                 const assistantMsg = event.message;
+                this._lastAssistantMessage = assistantMsg;
                 if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "length") {
                     this._overflowRecoveryAttempted = false;
                 }
@@ -445,6 +621,7 @@ export class AgentSession {
         // extension and listener dispatch above also picks up messages that turn_end
         // handlers queued.
         if (event.type === "turn_end") {
+            this._lastAssistantToolResults = event.toolResults;
             this._flushPendingCustomMessages();
         }
     };
@@ -463,6 +640,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;
@@ -506,13 +724,9 @@ export class AgentSession {
             await this._extensionRunner.emit(extensionEvent);
         }
         else if (event.type === "turn_end") {
-            const extensionEvent = {
-                type: "turn_end",
-                turnIndex: this._turnIndex,
-                message: event.message,
-                toolResults: event.toolResults,
-            };
-            await this._extensionRunner.emit(extensionEvent);
+            if (event.message.role === "assistant" && !this._boundaryDispatchedMessages.delete(event.message)) {
+                await this._dispatchTurnEndBoundary(event.message, event.toolResults);
+            }
             this._turnIndex++;
         }
         else if (event.type === "message_start") {
@@ -628,6 +842,10 @@ export class AgentSession {
     // =========================================================================
     // Read-only State Access
     // =========================================================================
+    /** Refresh the public finalized transcript from the canonical session projection. */
+    refreshContext() {
+        this._refreshFinalizedContext();
+    }
     /** Full agent state */
     get state() {
         return this.agent.state;
@@ -862,7 +1080,15 @@ export class AgentSession {
         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();
@@ -878,16 +1104,17 @@ export class AgentSession {
         }
     }
     async _handlePostAgentRun() {
-        const msg = this._lastAssistantMessage;
+        const message = this._lastAssistantMessage;
+        const toolResults = this._lastAssistantToolResults;
         this._lastAssistantMessage = undefined;
+        this._lastAssistantToolResults = [];
         if (this._agentRunAbortRequested) {
             this._finishCancelledRetry();
             return false;
         }
-        if (!msg) {
-            return false;
-        }
-        if (this._isRetryableError(msg) && (await this._prepareRetry(msg))) {
+        if (!message)
+            return this.agent.hasQueuedMessages();
+        if (this._isRetryableError(message) && (await this._prepareRetry(message))) {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
             return !this._agentRunAbortRequested;
@@ -896,22 +1123,46 @@ export class AgentSession {
             this._finishCancelledRetry();
             return false;
         }
-        if (msg.stopReason === "error" && this._retryAttempt > 0) {
+        if (message.stopReason === "error" && this._retryAttempt > 0) {
             this._emit({
                 type: "auto_retry_end",
                 success: false,
                 attempt: this._retryAttempt,
-                finalError: msg.errorMessage,
+                finalError: message.errorMessage,
             });
             this._retryAttempt = 0;
         }
-        if (await this._checkCompaction(msg)) {
+        if (await this._checkCompaction(message, true, toolResults)) {
             return !this._agentRunAbortRequested;
         }
-        // The agent loop drains both queues before emitting agent_end. Any messages
-        // here were queued by agent_end extension handlers and need a continuation.
+        // 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 };
@@ -925,6 +1176,25 @@ export class AgentSession {
         }
         return { text, images };
     }
+    async _normalizePromptImages(images) {
+        if (!images)
+            return { images: [], hints: [] };
+        const normalizedImages = [];
+        const hints = [];
+        for (const image of images) {
+            const processed = await processImage(Buffer.from(image.data, "base64"), image.mimeType, {
+                autoResizeImages: this.settingsManager.getImageAutoResize(),
+                resizeOptions: this.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);
+        }
+        return { images: normalizedImages, hints };
+    }
     /**
      * Send a prompt to the agent.
      * - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming
@@ -935,6 +1205,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;
+        }
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let messages;
@@ -1003,13 +1277,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,
@@ -1020,16 +1304,6 @@ export class AgentSession {
                 messages.push(msg);
             }
             this._pendingNextTurnMessages = [];
-            // Emit before_agent_start extension event
-            const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;
-            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPromptOptions);
-            // Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),
-            // which updates the live loadout instead. An explicit edit wins; otherwise the live
-            // loadout is authoritative, so a setActiveTools() call is not undone here.
-            const handlerEditedTools = result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||
-                result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);
-            if (!handlerEditedTools)
-                result.systemPromptOptions.selectedTools = this.getActiveToolNames();
             for (const msg of result.messages) {
                 messages.push({
                     role: "custom",
@@ -1178,11 +1452,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.
@@ -1230,6 +1500,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) {
@@ -1244,8 +1518,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 });
     }
@@ -1338,6 +1612,8 @@ export class AgentSession {
         this.abortRetry();
         this.abortCompaction();
         this.abortBranchSummary();
+        if (this._isBeforeSettle)
+            this._abortDuringBeforeSettle = true;
         this.agent.abort();
         await this.waitForIdle();
     }
@@ -1656,9 +1932,8 @@ export class AgentSession {
             }
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
             const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
             // Get the saved compaction entry for the extension event
             const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
             if (this._extensionRunner && savedCompactionEntry) {
@@ -1749,7 +2024,7 @@ 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) {
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true, toolResults = []) {
         const settings = this.settingsManager.getCompactionSettings(this.model);
         if (!settings.enabled)
             return false;
@@ -1773,8 +2048,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
@@ -1803,13 +2097,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.
@@ -1817,8 +2107,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.
@@ -1923,9 +2218,8 @@ export class AgentSession {
             abortController.signal.throwIfAborted();
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
             const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
             // Get the saved compaction entry for the extension event
             const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
             if (this._extensionRunner && savedCompactionEntry) {
@@ -1946,18 +2240,8 @@ export class AgentSession {
                 details,
             };
             this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-            if (willRetry) {
-                const messages = this.agent.state.messages;
-                const lastMsg = messages[messages.length - 1];
-                // The overflow response was persisted on message_end before _checkCompaction() removed it
-                // from agent state. Rebuilding state from the new compaction can restore that kept entry,
-                // leaving an assistant as the final message. agent.continue() rejects that state, so remove
-                // the retriable error or truncated-length response again before continuing the interrupted turn.
-                if (lastMsg?.role === "assistant" && (lastMsg.stopReason === "error" || lastMsg.stopReason === "length")) {
-                    this.agent.state.messages = messages.slice(0, -1);
-                }
+            if (willRetry)
                 return true;
-            }
             // Auto-compaction can complete while follow-up/steering/custom messages are waiting.
             // Continue once so queued messages are delivered.
             return this.agent.hasQueuedMessages();
@@ -2416,11 +2700,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 {
@@ -2512,10 +2793,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();
         }
     }
     /**
@@ -2542,12 +2821,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
@@ -2721,9 +2998,8 @@ export class AgentSession {
             if (label && !summaryText) {
                 this.sessionManager.appendLabelChange(targetId, label);
             }
-            // Update agent state
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
+            // Update finalized context from the canonical session projection.
+            this._refreshFinalizedContext();
             this._restoreToolsFromTranscript();
             // Emit session_tree event
             await this._extensionRunner.emit({
@@ -2829,30 +3105,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,