@code-yeongyu/senpi 2026.8.29 → 2026.8.30-3

package/dist/core/agent-session.js

@@ -14,10 +14,11 @@
  */
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { basename, dirname } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { ProviderRetryWatchdogAbortError, prepareAgentToolCall } from "@earendil-works/pi-agent-core";
-import { contentText, SERVER_FALLBACK_ABORTED_DIAGNOSTIC } from "@earendil-works/pi-ai";
+import { contentText, measureCursorHistorySerializedBytes, SERVER_FALLBACK_ABORTED_DIAGNOSTIC, } from "@earendil-works/pi-ai";
 import { cleanupSessionResources, cursorOverflowCompactionSettings, isClassifierRefusal, isContextOverflow, isCursorPayloadResourceExhausted, isCursorQuotaResourceExhausted, isCursorZeroTokenResourceExhausted, isProviderStreamStallError, isProviderTimeoutError, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, shouldRetryOverflowWithoutCompact, streamSimple, } from "@earendil-works/pi-ai/compat";
 import { extract429RetryAfterMs, parseRetryAfterMsMarker } from "@earendil-works/pi-ai/utils/retry-hint";
 import { retryBackoffDelayMs } from "@earendil-works/pi-ai/utils/retry-profile/backoff";
@@ -40,6 +41,8 @@ import { buildDynamicSystemPrompt } from "./dynamic-prompt/index.js";
 import { areExperimentalFeaturesEnabled } from "./experimental.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
+import { ModelUsabilityBudgetError, projectModelUsabilityBudget, } from "./extensions/builtin/compaction/model-usability-budget.js";
+import { resolveReserveTokens } from "./extensions/builtin/compaction/policy.js";
 import { CODEX_RESPONSES_API } from "./extensions/builtin/service-tier.js";
 import { deriveExtensionRegistrationId } from "./extensions/builtin/tool-search/engine/marker.js";
 import { getToolSearchService } from "./extensions/builtin/tool-search/service.js";
@@ -47,7 +50,7 @@ import { ExecuteToolError, ExtensionRunner, wrapRegisteredTools, } from "./exten
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { normalizeToolExposure, RUNTIME_EXTENSION_PATH } from "./extensions/types.js";
 import { shouldWarnHighReasoning } from "./high-reasoning-warning.js";
-import { filterContextExcludedMessages } from "./messages.js";
+import { convertToLlm, filterContextExcludedMessages, } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { getModelNarrowingPatterns, resolveModelScope } from "./model-resolver.js";
 import { PROMPT_CACHE_SAFE_WAIT_ENV, resolvePromptCacheSafeWaitSeconds } from "./prompt-cache-budget.js";
@@ -70,9 +73,21 @@ import { getSupportedThinkingLevels, supportsMax, supportsXhigh } from "./thinki
 import { resetTimings, time } from "./timings.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { composeFilesystemPolicies } from "./tools/filesystem-policy.js";
-import { createAllToolDefinitions } from "./tools/index.js";
+import { createAllToolDefinitions, temporarilyDisabledToolNames } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
+/** Built-in shell tools routed exclusively through eval when experimental.bashEvalOnly is enabled. */
+const EVAL_ONLY_SHELL_TOOL_NAMES = ["bash", "powershell"];
+/** Workflow tool routed exclusively through eval when experimental.workflowEvalOnly is enabled. */
+const EVAL_ONLY_WORKFLOW_TOOL_NAMES = ["workflow"];
+/** Sample eval-cell call for an eval-only tool, using the argument name that tool actually takes. */
+function evalHelperCall(name) {
+    if (EVAL_ONLY_SHELL_TOOL_NAMES.includes(name))
+        return `tool.${name}({ command: "..." })`;
+    if (EVAL_ONLY_WORKFLOW_TOOL_NAMES.includes(name))
+        return `tool.${name}({ action: "..." })`;
+    return `tool.${name}({ ... })`;
+}
 const TURN_RETRY_SUPPRESSION_PREFIX = "senpi:no-turn-retry:";
 const DEFERRED_RETRY_QUEUE_OWNERS = new WeakSet();
 /** Format the user-attributed payload for one or more explicit skill invocations. */
@@ -310,6 +325,121 @@ function isSameOverflowSource(message, model, upstreamModelId) {
 const THINKING_LEVELS_WITH_MAX = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 /** Caps explicit skill expansion so one prompt cannot consume unbounded context. */
 export const MAX_SKILL_EXPANSIONS_PER_PROMPT = 5;
+/** Cursor ingest rejects large verbatim tool payloads. The bound is UTF-8 bytes. */
+export const CURSOR_TOOL_RESULT_MAX_CHARS = 2000;
+export const CURSOR_TOOL_RESULT_MAX_BYTES = 50_000;
+const CURSOR_TRUNCATION_MARKER = "\n...[truncated]";
+export function truncateToolResultBodies(messages, maxChars = CURSOR_TOOL_RESULT_MAX_CHARS, maxBytes = CURSOR_TOOL_RESULT_MAX_BYTES, convert = (candidate) => convertToLlm(candidate)) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return { messages, changed: false };
+    const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+    const markerChars = [...segmenter.segment(CURSOR_TRUNCATION_MARKER)].length;
+    const result = messages.slice();
+    let changed = false;
+    // Apply the per-result character cap first, independent of the aggregate wire cap.
+    for (let messageIndex = result.length - 1; messageIndex >= 0; messageIndex--) {
+        const message = result[messageIndex];
+        if (message.role !== "toolResult" || !Array.isArray(message.content))
+            continue;
+        let content = message.content;
+        for (let partIndex = content.length - 1; partIndex >= 0; partIndex--) {
+            const part = content[partIndex];
+            if (part.type === "image" && typeof part.data === "string")
+                continue;
+            if (part.type !== "text" || typeof part.text !== "string")
+                continue;
+            const graphemes = [...segmenter.segment(part.text)].map((item) => item.segment);
+            if (graphemes.length <= maxChars)
+                continue;
+            const kept = graphemes.slice(0, Math.max(0, maxChars - markerChars)).join("");
+            const nextText = kept + CURSOR_TRUNCATION_MARKER;
+            content = content === message.content ? content.slice() : content;
+            content[partIndex] = { ...part, text: nextText };
+            result[messageIndex] = { ...message, content };
+            changed = true;
+        }
+    }
+    const measure = (candidate) => {
+        const converted = convert(candidate);
+        const activeUserMessageIndex = converted.at(-1)?.role === "user" ? converted.length - 1 : -1;
+        return measureCursorHistorySerializedBytes(converted, activeUserMessageIndex);
+    };
+    const fits = (candidate = result) => measure(candidate) <= maxBytes;
+    if (fits())
+        return { messages: changed ? result : messages, changed };
+    // Empty the oldest result bodies. Search the monotonic prefix of candidates
+    // rather than serializing once for every result (admission must stay bounded).
+    const emptyToolResult = (message) => {
+        if (message.role !== "toolResult" || !Array.isArray(message.content))
+            return message;
+        const emptiedContent = message.content.map((part) => part.type === "text" ? { ...part, text: "" } : part.type === "image" ? { ...part, data: "" } : part);
+        const content = emptiedContent.filter((part, index) => {
+            if (index === 0)
+                return true;
+            const previous = emptiedContent[index - 1];
+            const empty = part.type === "text" ? part.text === "" : part.type === "image" && part.data === "";
+            const previousEmpty = previous.type === "text" ? previous.text === "" : previous.type === "image" && previous.data === "";
+            return !empty || !previousEmpty;
+        });
+        return { ...message, content };
+    };
+    const toolResultIndexes = result.flatMap((message, index) => message.role === "toolResult" && Array.isArray(message.content) ? [index] : []);
+    const withEmptyPrefix = (count) => {
+        const candidate = result.slice();
+        for (let i = 0; i < count; i++)
+            candidate[toolResultIndexes[i]] = emptyToolResult(candidate[toolResultIndexes[i]]);
+        return candidate;
+    };
+    let low = 0;
+    let high = toolResultIndexes.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (fits(withEmptyPrefix(middle + 1)))
+            high = middle;
+        else
+            low = middle + 1;
+    }
+    const emptyCount = Math.min(low + 1, toolResultIndexes.length);
+    if (emptyCount > 0) {
+        result.splice(0, result.length, ...withEmptyPrefix(emptyCount));
+        changed = true;
+    }
+    if (fits())
+        return { messages: changed ? result : messages, changed };
+    // If metadata alone exceeds the cap, discard the oldest complete turns. This
+    // search is also monotonic and avoids quadratic whole-history reserialization.
+    const turnRanges = [];
+    const isConvertedUser = (message) => convert([message])[0]?.role === "user";
+    for (let index = 0; index < result.length; index++) {
+        if (!isConvertedUser(result[index]))
+            continue;
+        const nextUser = result.findIndex((message, nextIndex) => nextIndex > index && isConvertedUser(message));
+        turnRanges.push([index, nextUser < 0 ? result.length : nextUser]);
+    }
+    const withoutTurns = (count) => {
+        if (count === 0)
+            return result;
+        const start = turnRanges[0]?.[0] ?? 0;
+        const end = turnRanges[count - 1]?.[1] ?? start;
+        return [...result.slice(0, start), ...result.slice(end)];
+    };
+    low = 0;
+    high = turnRanges.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (fits(withoutTurns(middle + 1)))
+            high = middle;
+        else
+            low = middle + 1;
+    }
+    const turnCount = Math.min(low + 1, turnRanges.length);
+    if (turnCount > 0) {
+        const next = withoutTurns(turnCount);
+        result.splice(0, result.length, ...next);
+        changed = true;
+    }
+    return { messages: changed ? result : messages, changed };
+}
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -395,6 +525,10 @@ export class AgentSession {
         this._pendingBashMessages = [];
         this._turnIndex = 0;
         this._baseToolDefinitions = new Map();
+        /** Policy tools withheld from the model, retained so disarming can restore direct access. */
+        this._withheldEvalOnlyToolNames = new Set();
+        /** Eval-only hint names this session published, so a disarm can withdraw exactly those. */
+        this._publishedEvalOnlyHintNames = new Set();
         this._extensionMode = "print";
         // Tool registry for extension getTools/setTools
         this._toolRegistry = new Map();
@@ -516,6 +650,8 @@ export class AgentSession {
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
         this._defaultToolNames = config.defaultToolNames ? new Set(config.defaultToolNames) : undefined;
+        this._evalOnlyToolNamesOverride = config.evalOnlyToolNames ? new Set(config.evalOnlyToolNames) : undefined;
+        this._evalOnlyToolNames = this._resolveEvalOnlyToolNames();
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
         this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
@@ -727,6 +863,14 @@ export class AgentSession {
             (this.agent.prepareNextTurn
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
+        const previousTransformContext = this.agent.transformContext;
+        this.agent.transformContext = async (messages, signal) => {
+            const transformed = previousTransformContext ? await previousTransformContext(messages, signal) : messages;
+            if (this.model?.provider === "cursor" || this.model?.provider === "cursor-cli-oauth") {
+                return ((await truncateToolResultBodies(transformed, CURSOR_TOOL_RESULT_MAX_CHARS, CURSOR_TOOL_RESULT_MAX_BYTES, (candidate) => this.agent.convertToLlm(candidate))).messages ?? transformed);
+            }
+            return transformed;
+        };
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
             // Enforce compaction only when this prepare precedes an actual provider
             // admission: a tool continuation or queued steer/follow-up messages. A
@@ -735,7 +879,8 @@ export class AgentSession {
             const compactBeforeNextAdmission = async () => {
                 const provider = this.model?.provider;
                 // Cursor rebuilds the full conversation each hop. Compacting here
-                // mutates rootPrompt mid-run and poisons conversationId.
+                // mutates rootPrompt mid-run and poisons conversationId (#984).
+                // Still truncate verbatim toolResult bodies so the skip cannot send MB-scale payloads (#1043).
                 if (provider === "cursor" || provider === "cursor-cli-oauth") {
                     return false;
                 }
@@ -816,6 +961,19 @@ export class AgentSession {
     // Event Subscription
     // =========================================================================
     /** Emit an event to all listeners */
+    _emitEntryAppended(entryId) {
+        if (this._extensionMode !== "rpc")
+            return;
+        const entry = this.sessionManager.getEntry(entryId);
+        if (entry)
+            this._emit({ type: "entry_appended", entry });
+    }
+    /** Append a transport-provided entry and publish it on the RPC event stream. */
+    appendSessionEntry(entry) {
+        this.sessionManager.appendEntry(entry);
+        this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
+        this._emitEntryAppended(entry.id);
+    }
     _emit(event) {
         this._logSessionEvent(event);
         for (const l of this._eventListeners) {
@@ -976,6 +1134,7 @@ export class AgentSession {
     _invalidateCompactionForModelSelection() {
         this.abortCompaction();
         this.abortBranchSummary();
+        this._delegatedCompactionKey = undefined;
         this._incrementMessageRevision();
     }
     _getIdleWaitPromise() {
@@ -1367,7 +1526,7 @@ export class AgentSession {
                 event.message.role === "assistant" ||
                 event.message.role === "toolResult") {
                 // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
+                this._emitEntryAppended(this.sessionManager.appendMessage(event.message));
                 this._incrementMessageRevision();
             }
             // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
@@ -2001,6 +2160,9 @@ export class AgentSession {
     async executeTool(toolName, params, options) {
         let activeTools = this.getActiveToolNames();
         let tool = this.agent.state.tools.find((candidate) => candidate.name === toolName);
+        if (!tool && this._isEvalOnlyPolicyArmed() && this._evalOnlyToolNames?.has(toolName)) {
+            tool = this._toolRegistry.get(toolName);
+        }
         if (!tool &&
             options?.activateInactiveTool === true &&
             this._toolDefinitions.has(toolName) &&
@@ -2075,6 +2237,45 @@ export class AgentSession {
             return false;
         return this._lazyToolActivators.some((activate) => activate(toolName));
     }
+    _isEvalOnlyPolicyArmed() {
+        return this._evalOnlyToolNames !== undefined && this._toolRegistry.has("eval");
+    }
+    /**
+     * Resolve the eval-only policy from settings so a reload picks up a flag change.
+     * An explicitly configured set stays authoritative for SDK embedders and tests.
+     */
+    _resolveEvalOnlyToolNames() {
+        if (this._evalOnlyToolNamesOverride !== undefined)
+            return this._evalOnlyToolNamesOverride;
+        const names = [
+            ...(this.settingsManager.getExperimentalBashEvalOnly() ? EVAL_ONLY_SHELL_TOOL_NAMES : []),
+            ...(this.settingsManager.getExperimentalWorkflowEvalOnly() ? EVAL_ONLY_WORKFLOW_TOOL_NAMES : []),
+        ];
+        return names.length > 0 ? new Set(names) : undefined;
+    }
+    /**
+     * Publish per-tool eval-only redirect hints so a direct call names its own eval helper.
+     *
+     * Hints published here are tracked so a disarm - or a shrinking armed set, e.g. bash+workflow
+     * down to workflow only - withdraws the stale ones. Only tracked names are ever deleted, so
+     * hints owned by other publishers survive.
+     */
+    _publishEvalOnlyToolHints() {
+        const armed = this._isEvalOnlyPolicyArmed() ? (this._evalOnlyToolNames ?? new Set()) : undefined;
+        for (const name of this._publishedEvalOnlyHintNames) {
+            if (armed?.has(name))
+                continue;
+            delete this.agent.removedToolHints[name];
+        }
+        this._publishedEvalOnlyHintNames.clear();
+        if (!armed)
+            return;
+        for (const name of armed) {
+            this.agent.removedToolHints[name] =
+                `Run ${name} inside an eval cell via ${evalHelperCall(name)}; hooks and permissions still apply.`;
+            this._publishedEvalOnlyHintNames.add(name);
+        }
+    }
     /**
      * Set active tools by name.
      * Only tools in the registry can be enabled. Unknown tool names are ignored.
@@ -2102,7 +2303,23 @@ export class AgentSession {
     setActiveToolsByName(toolNames) {
         const tools = [];
         const validToolNames = [];
-        for (const name of toolNames) {
+        const policyArmed = this._isEvalOnlyPolicyArmed();
+        this._publishEvalOnlyToolHints();
+        const policyNames = this._evalOnlyToolNames;
+        let filteredToolNames = toolNames;
+        if (policyArmed && policyNames) {
+            for (const name of toolNames) {
+                if (policyNames.has(name))
+                    this._withheldEvalOnlyToolNames.add(name);
+            }
+            filteredToolNames = toolNames.filter((name) => !policyNames.has(name));
+        }
+        else {
+            this._withheldEvalOnlyToolNames.clear();
+        }
+        // Remember the unfiltered request so a later disarm can restore withheld shell tools.
+        this._requestedActiveToolNames = [...new Set([...toolNames, ...this._withheldEvalOnlyToolNames])];
+        for (const name of filteredToolNames) {
             const tool = this._toolRegistry.get(name);
             if (tool) {
                 tools.push(tool);
@@ -2116,8 +2333,14 @@ export class AgentSession {
         this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
         this.agent.state.systemPrompt = this._systemPromptOverride ?? this._baseSystemPrompt;
         if (activeToolNamesChanged) {
-            this.abortCompaction();
-            this._incrementMessageRevision();
+            // A tool change emitted while extensions are still binding belongs to the
+            // binding itself, not to a mid-session change. The session was already
+            // committed to the client, so cancelling or invalidating work it started
+            // against that session would be spurious.
+            if (this._extensionBindingPromptReadiness === undefined) {
+                this.abortCompaction();
+                this._incrementMessageRevision();
+            }
         }
     }
     /** Whether compaction or branch summarization is currently running */
@@ -2259,9 +2482,26 @@ export class AgentSession {
             appendSystemPrompt: loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined,
         };
         const basePrompt = loaderSystemPrompt ?? buildDynamicSystemPrompt(this._baseSystemPromptOptions);
-        return loaderAppendSystemPrompt.length > 0
-            ? `${basePrompt}\n\n${loaderAppendSystemPrompt.join("\n\n")}`
-            : basePrompt;
+        const prompt = loaderAppendSystemPrompt.length > 0 ? `${basePrompt}\n\n${loaderAppendSystemPrompt.join("\n\n")}` : basePrompt;
+        if (!this._isEvalOnlyPolicyArmed())
+            return prompt;
+        const armed = this._evalOnlyToolNames ?? new Set();
+        const sentences = [];
+        const shellHelpers = EVAL_ONLY_SHELL_TOOL_NAMES.filter((name) => armed.has(name)).map(evalHelperCall);
+        if (shellHelpers.length > 0) {
+            sentences.push(`Shell commands run ONLY inside eval cells via ${shellHelpers.join(" or ")}; hooks and permissions still apply.`);
+        }
+        if (armed.has("workflow")) {
+            sentences.push(`The workflow tool runs ONLY inside eval cells via ${evalHelperCall("workflow")}; hooks and permissions still apply.`);
+        }
+        // SDK embedders can arm names outside the built-in groups; they still need eval guidance.
+        const otherHelpers = [...armed]
+            .filter((name) => !EVAL_ONLY_SHELL_TOOL_NAMES.includes(name) && name !== "workflow")
+            .map(evalHelperCall);
+        if (otherHelpers.length > 0) {
+            sentences.push(`These tools run ONLY inside eval cells via ${otherHelpers.join(" or ")}; hooks and permissions still apply.`);
+        }
+        return sentences.length > 0 ? `${prompt}\n\n${sentences.join("\n\n")}` : prompt;
     }
     /**
      * Send a prompt to the agent.
@@ -3053,7 +3293,7 @@ export class AgentSession {
     }
     _appendCustomMessage(appMessage) {
         this.agent.state.messages.push(appMessage);
-        this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
+        this._emitEntryAppended(this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details));
         this._incrementMessageRevision();
         this._emit({ type: "message_start", message: appMessage });
         this._emit({ type: "message_end", message: appMessage });
@@ -3298,6 +3538,43 @@ export class AgentSession {
     async setModel(model) {
         return this._setModel(model, true);
     }
+    assertModelUsable(model = this.model, liveContextTokens = 0) {
+        if (!model || model.contextWindow <= 0)
+            return;
+        const projection = projectModelUsabilityBudget({
+            model,
+            systemPrompt: this.agent.state.systemPrompt,
+            tools: this.agent.state.tools,
+            liveContextTokens,
+            compaction: this.settingsManager.getCompactionSettings(),
+        });
+        if (!projection.usable)
+            throw new ModelUsabilityBudgetError(projection);
+    }
+    _getDownswitchLiveContextTokens(model) {
+        const currentModel = this.model;
+        if (!currentModel)
+            return 0;
+        const compaction = this.settingsManager.getCompactionSettings();
+        const currentBudget = projectModelUsabilityBudget({
+            model: currentModel,
+            systemPrompt: this.agent.state.systemPrompt,
+            tools: this.agent.state.tools,
+            compaction,
+        });
+        const targetBudget = projectModelUsabilityBudget({
+            model,
+            systemPrompt: this.agent.state.systemPrompt,
+            tools: this.agent.state.tools,
+            compaction,
+        });
+        const currentUsableContext = currentBudget.contextWindow - currentBudget.requiredTokens;
+        const targetUsableContext = targetBudget.contextWindow - targetBudget.requiredTokens;
+        if (targetUsableContext >= currentUsableContext)
+            return 0;
+        const fixedPrefixTokens = currentBudget.systemPromptTokens + currentBudget.activeToolSchemaTokens;
+        return Math.max(0, (this.getContextUsage()?.tokens ?? 0) - fixedPrefixTokens);
+    }
     /**
      * Set the model for this session without changing the global model defaults.
      * The selection is still persisted in this session's history.
@@ -3306,6 +3583,7 @@ export class AgentSession {
         return this._setModel(model, false);
     }
     async _setModel(model, updateGlobalDefaults) {
+        this.assertModelUsable(model, this._getDownswitchLiveContextTokens(model));
         if (!(await this._modelRuntime.checkAuth(model.provider))) {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
@@ -3336,10 +3614,14 @@ export class AgentSession {
     }
     async _switchActiveModel(model, opts) {
         const previousModel = this.model;
-        if (opts.invalidateCompaction && this._modelSelectionChangesContext(previousModel, model)) {
+        if (opts.invalidateCompaction &&
+            (this._modelSelectionChangesContext(previousModel, model) ||
+                previousModel?.provider !== model.provider ||
+                previousModel?.id !== model.id)) {
             this._invalidateCompactionForModelSelection();
         }
         const thinking = this._getThinkingForModelSwitch(model, opts.ephemeralThinkingLevel);
+        const liveContextTokens = this._getDownswitchLiveContextTokens(model);
         this.agent.state.model = model;
         this.agent.abortServerSideFallback =
             this.settingsManager.getAbortServerSideFallback() && this._retryFallback.hasConfiguredChain();
@@ -3371,7 +3653,20 @@ export class AgentSession {
         this._emitServiceTierChangeIfNeeded(previousTier, previousFastMode);
         if (!opts.emitModelSelect)
             return undefined;
-        return await this._emitModelSelect(model, previousModel, opts.modelSelectSource);
+        const previousSystemPrompt = this.agent.state.systemPrompt;
+        try {
+            const systemPromptChange = await this._emitModelSelect(model, previousModel, opts.modelSelectSource);
+            this.assertModelUsable(model, liveContextTokens);
+            return systemPromptChange;
+        }
+        catch (error) {
+            if (previousModel)
+                this.agent.state.model = previousModel;
+            else
+                delete this.agent.state.model;
+            this.agent.state.systemPrompt = previousSystemPrompt;
+            throw error;
+        }
     }
     _applyEphemeralThinkingLevel(level) {
         const previousLevel = this.agent.state.thinkingLevel;
@@ -3408,7 +3703,11 @@ export class AgentSession {
             nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
         }
         const next = favoriteModels[nextIndex];
-        const invalidatesCompaction = this._modelSelectionChangesContext(currentModel, next.model);
+        const liveContextTokens = this._getDownswitchLiveContextTokens(next.model);
+        this.assertModelUsable(next.model, liveContextTokens);
+        const invalidatesCompaction = this._modelSelectionChangesContext(currentModel, next.model) ||
+            currentModel?.provider !== next.model.provider ||
+            currentModel?.id !== next.model.id;
         if (invalidatesCompaction) {
             this._invalidateCompactionForModelSelection();
         }
@@ -3431,16 +3730,28 @@ export class AgentSession {
             source: "cycle",
         });
         this._emitServiceTierChangeIfNeeded(previousTier, previousFastMode);
-        const systemPromptChange = await this._emitModelSelect(next.model, currentModel, "cycle");
-        const cycleResult = {
-            model: next.model,
-            thinkingLevel: this.thinkingLevel,
-            isScoped: true,
-        };
-        if (systemPromptChange) {
-            cycleResult.systemPromptChange = systemPromptChange;
+        const previousSystemPrompt = this.agent.state.systemPrompt;
+        try {
+            const systemPromptChange = await this._emitModelSelect(next.model, currentModel, "cycle");
+            this.assertModelUsable(next.model, liveContextTokens);
+            const cycleResult = {
+                model: next.model,
+                thinkingLevel: this.thinkingLevel,
+                isScoped: true,
+            };
+            if (systemPromptChange) {
+                cycleResult.systemPromptChange = systemPromptChange;
+            }
+            return cycleResult;
+        }
+        catch (error) {
+            if (currentModel)
+                this.agent.state.model = currentModel;
+            else
+                delete this.agent.state.model;
+            this.agent.state.systemPrompt = previousSystemPrompt;
+            throw error;
         }
-        return cycleResult;
     }
     // =========================================================================
     // Thinking Level Management
@@ -3610,6 +3921,7 @@ export class AgentSession {
     setSteeringMode(mode) {
         this.agent.steeringMode = mode;
         this.settingsManager.setSteeringMode(mode);
+        this._emitSessionSettingsChanged();
     }
     /**
      * Set follow-up message mode.
@@ -3618,6 +3930,7 @@ export class AgentSession {
     setFollowUpMode(mode) {
         this.agent.followUpMode = mode;
         this.settingsManager.setFollowUpMode(mode);
+        this._emitSessionSettingsChanged();
     }
     // =========================================================================
     // Compaction
@@ -4100,7 +4413,7 @@ export class AgentSession {
             if (sourceChanged) {
                 return await this._rejectCompaction(request, requestId, operationId, "stale-revision", false);
             }
-            if (this._wouldCompactionOverflow(pathEntries, compactionResult, fromExtension, model)) {
+            if (await this._wouldCompactionOverflow(pathEntries, compactionResult, fromExtension, model)) {
                 return await this._rejectCompaction(request, requestId, operationId, "would-overflow", false);
             }
             const compactionEntryId = this.sessionManager.appendCompaction(compactionResult.summary, compactionResult.firstKeptEntryId, compactionResult.tokensBefore, compactionResult.details, fromExtension, compactionResult.usage);
@@ -4141,6 +4454,7 @@ export class AgentSession {
             })) {
                 throw new CompactionCancelledError();
             }
+            this._delegatedCompactionKey = undefined;
             if (request.owner === "compaction" && this._compactionAbortController === request.controller) {
                 this._compactionAbortController = undefined;
             }
@@ -4191,7 +4505,7 @@ export class AgentSession {
             finishCompactionWork();
         }
     }
-    _wouldCompactionOverflow(pathEntries, compactionResult, fromExtension, model) {
+    async _wouldCompactionOverflow(pathEntries, compactionResult, fromExtension, model) {
         const currentLeaf = pathEntries[pathEntries.length - 1];
         if (!currentLeaf)
             return false;
@@ -4206,10 +4520,18 @@ export class AgentSession {
             details: compactionResult.details,
             fromHook: fromExtension,
         };
-        const simulatedMessages = buildSessionContext([...pathEntries, simulatedCompactionEntry], simulatedCompactionEntry.id).messages;
+        let simulatedMessages = buildSessionContext([...pathEntries, simulatedCompactionEntry], simulatedCompactionEntry.id).messages;
+        // Size the same retained context that will be admitted to Cursor. Persisted JSONL
+        // remains verbatim, but the in-memory request representation is bounded first.
+        if (model.provider === "cursor" || model.provider === "cursor-cli-oauth") {
+            simulatedMessages = truncateToolResultBodies(simulatedMessages).messages ?? simulatedMessages;
+        }
         const contextTokens = estimateMessagesTokens(filterContextExcludedMessages(simulatedMessages));
         const settings = this.settingsManager.getCompactionSettings();
-        return contextTokens > model.contextWindow - settings.reserveTokens;
+        const reserveTokens = settings.reserveScalingEnabled === false
+            ? settings.reserveTokens
+            : resolveReserveTokens(model.contextWindow, settings.reserveTokens);
+        return contextTokens > model.contextWindow - reserveTokens;
     }
     /**
      * Replaces agent state with the canonical session context while keeping exact
@@ -4237,6 +4559,9 @@ export class AgentSession {
         // also emitted with accepted:false so the compaction extension's circuit-breaker
         // bookkeeping stops being dead code; other builtin session_compact handlers guard
         // on event.accepted.
+        if (rejectionCause === "external-owner" && this.model) {
+            this._delegatedCompactionKey = { provider: this.model.provider, id: this.model.id };
+        }
         const trimmedExtensionReason = extensionReason?.trim();
         const detailedMessage = trimmedExtensionReason
             ? `Compaction rejected: ${trimmedExtensionReason}`
@@ -4370,6 +4695,9 @@ export class AgentSession {
         if (!model)
             return;
         const settings = this.settingsManager.getCompactionSettings();
+        const reserveTokens = settings.reserveScalingEnabled === false
+            ? settings.reserveTokens
+            : resolveReserveTokens(model.contextWindow, settings.reserveTokens);
         const isOversized = () => {
             const providerMessages = filterContextExcludedMessages([...this.agent.state.messages, ...messages]);
             const estimate = estimateContextTokens(providerMessages);
@@ -4380,7 +4708,7 @@ export class AgentSession {
             const contextTokens = usageMessage?.role === "assistant" && this._isAssistantFromBeforeLatestCompaction(usageMessage)
                 ? estimateMessagesTokens(providerMessages)
                 : estimate.tokens;
-            return contextTokens > model.contextWindow - settings.reserveTokens;
+            return contextTokens > model.contextWindow - reserveTokens;
         };
         if (!settings.enabled || !isOversized())
             return;
@@ -4573,15 +4901,15 @@ export class AgentSession {
         return claimant !== undefined && !claimant.signal.aborted;
     }
     _isCompactionDelegated() {
-        const state = this._compactionLifecycle.state;
         const model = this.model;
-        return (state.status === "failed" &&
-            state.rejectionCause === "external-owner" &&
-            state.model !== undefined &&
+        return (this._delegatedCompactionKey !== undefined &&
             model !== undefined &&
-            state.model.provider === model.provider);
+            this._delegatedCompactionKey.provider === model.provider &&
+            this._delegatedCompactionKey.id === model.id);
     }
     async _runPrePromptCompaction(lastAssistantMessage, skipAbortedCheck, reason = "pre_prompt", willRetry = false, allowSummaryOnly = false) {
+        if (this._isCompactionDelegated())
+            return false;
         const controller = new AbortController();
         const requestId = randomUUID();
         this._claimCompactionController(controller, "compaction");
@@ -4754,6 +5082,8 @@ export class AgentSession {
      * @returns Whether the post-run loop should call `agent.continue()`
      */
     async _runAutoCompaction(reason, willRetry) {
+        if (this._isCompactionDelegated())
+            return false;
         const finishCompactionWork = this._sessionWorkBarrier.begin();
         const agentMessagesAtStart = this.agent.state.messages.slice();
         const autoCompactionController = new AbortController();
@@ -4887,6 +5217,15 @@ export class AgentSession {
      */
     setAutoCompactionEnabled(enabled) {
         this.settingsManager.setCompactionEnabled(enabled);
+        this._emitSessionSettingsChanged();
+    }
+    _emitSessionSettingsChanged() {
+        this._emit({
+            type: "session_settings_changed",
+            steeringMode: this.steeringMode,
+            followUpMode: this.followUpMode,
+            autoCompactionEnabled: this.autoCompactionEnabled,
+        });
     }
     /** Whether auto-compaction is enabled */
     get autoCompactionEnabled() {
@@ -4984,6 +5323,7 @@ export class AgentSession {
             : undefined;
     }
     _refreshCurrentModelFromRegistry() {
+        this._delegatedCompactionKey = undefined;
         const currentModel = this.model;
         if (!currentModel) {
             return;
@@ -5308,8 +5648,11 @@ export class AgentSession {
                 }),
             })),
         ].filter((tool) => isAllowedTool(tool.definition.name));
+        // Withheld tools stay in _baseToolDefinitions (and therefore in _toolRegistry, which
+        // getRegisteredTool serves to the Cursor exec bridge) but are dropped from the model-facing
+        // definitions so they never reach the prompt. See temporarilyDisabledToolNames.
         const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries())
-            .filter(([name]) => isAllowedTool(name))
+            .filter(([name]) => isAllowedTool(name) && !temporarilyDisabledToolNames.has(name))
             .map(([name, definition]) => [
             name,
             {
@@ -5351,13 +5694,22 @@ export class AgentSession {
             toolRegistry.set(tool.name, tool);
         }
         this._toolRegistry = toolRegistry;
+        this._publishEvalOnlyToolHints();
         const isDirectlyExposed = (name) => {
             const entry = this._toolDefinitions.get(name);
             return entry !== undefined && normalizeToolExposure(entry.definition).exposure === "direct";
         };
-        const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => {
+        // A withheld tool is dropped from the DEFAULT selection only. An explicit activeToolNames
+        // request names the tool deliberately, and callers that do so (tests, SDK embedders,
+        // filesystem-policy wiring) still expect it to activate.
+        const hasExplicitActiveToolNames = options?.activeToolNames !== undefined;
+        const nextActiveToolNames = (options?.activeToolNames
+            ? [...options.activeToolNames]
+            : [...(this._requestedActiveToolNames ?? previousActiveToolNames)]).filter((name) => {
             if (!isAllowedTool(name))
                 return false;
+            if (!hasExplicitActiveToolNames && temporarilyDisabledToolNames.has(name))
+                return false;
             const previousRegistrationIds = options?.previousActiveToolRegistrationIds;
             if (!previousRegistrationIds)
                 return true;
@@ -5388,6 +5740,7 @@ export class AgentSession {
         this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
     }
     _buildRuntime(options) {
+        this._delegatedCompactionKey = undefined;
         const autoResizeImages = this.settingsManager.getImageAutoResize();
         const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
         const shellPath = this.settingsManager.getShellPath();
@@ -5439,7 +5792,9 @@ export class AgentSession {
         const oldExtensionIdentities = oldExtensionRunner.getExtensionIdentities();
         const previousFlagValues = oldExtensionRunner.getFlagValues();
         const previousActiveToolRegistrationIds = new Map();
-        for (const name of this.getActiveToolNames()) {
+        // Cover withheld eval-only tools too: the rebuild drops any seeded name missing from this
+        // map, which would strand shell tools when the policy disarms during this reload.
+        for (const name of this._requestedActiveToolNames ?? this.getActiveToolNames()) {
             const entry = this._toolDefinitions.get(name);
             if (entry)
                 previousActiveToolRegistrationIds.set(name, deriveExtensionRegistrationId(entry.sourceInfo, name));
@@ -5450,6 +5805,12 @@ export class AgentSession {
         });
         time("shutdown", "reload");
         await this.settingsManager.reload();
+        this._delegatedCompactionKey = undefined;
+        // Capture the unfiltered request BEFORE the rebuild reassigns it, so a policy that
+        // disarms during this reload can still restore its withheld shell tools.
+        const requestedActiveToolNamesBeforeRebuild = [...(this._requestedActiveToolNames ?? this.getActiveToolNames())];
+        // A flag change must take effect on reload, matching documented settings hot-reload behavior.
+        this._evalOnlyToolNames = this._resolveEvalOnlyToolNames();
         this.syncQueueModesFromSettings();
         resetApiProviders();
         time("settings", "reload");
@@ -5474,7 +5835,7 @@ export class AgentSession {
         time("resources", "reload");
         try {
             this._buildRuntime({
-                activeToolNames: this.getActiveToolNames(),
+                activeToolNames: requestedActiveToolNamesBeforeRebuild,
                 flagValues: previousFlagValues,
                 includeAllExtensionTools: true,
                 previousActiveToolRegistrationIds,
@@ -6179,12 +6540,13 @@ export class AgentSession {
         try {
             const result = await executeBashWithOperations(resolvedCommand, this.sessionManager.getCwd(), options?.operations ?? createLocalBashOperations({ shellPath }), {
                 onChunk: (delta) => {
-                    onChunk?.(delta);
+                    const callbackResult = onChunk?.(delta);
                     this._emit({
                         type: "bash_execution_update",
                         id: options?.id,
                         delta,
                     });
+                    return callbackResult;
                 },
                 signal: abortController.signal,
             });
@@ -6232,6 +6594,10 @@ export class AgentSession {
             abortController.abort();
         }
     }
+    /** Remove a host-owned full-output spill after a remote observer failed. */
+    async cleanupBashOutput(path) {
+        await rm(path, { force: true });
+    }
     /** Whether a bash command is currently running */
     get isBashRunning() {
         return this._bashAbortControllers.size > 0;
@@ -6433,6 +6799,7 @@ export class AgentSession {
             }
             // Update agent state (preserving exact messages still awaiting persistence)
             this._restoreAgentMessagesFromSession();
+            this._delegatedCompactionKey = undefined;
             this._incrementMessageRevision();
             // Emit session_tree event
             await this._extensionRunner.emit({