apex-code 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/core/agent-session.js

@@ -12,31 +12,42 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { contentText } from "@earendil-works/pi-ai";
-import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
+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 { resolvePath } from "../utils/paths.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 { createSessionCheckpoints } from "./checkpoints/session-checkpoints.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
-import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
+import { evictionBudget, installContextPipeline, isDefaultStreamFunction } from "./context/pipeline.js";
+import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
+import { SessionEvidenceSink } from "./evidence.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 { ModelRegistry } from "./model-registry.js";
+import { evaluateToolCall } from "./permissions/gate.js";
+import { createInteractiveResponder } from "./permissions/responder.js";
+import { resolveEffectiveModeWithOrigin } from "./permissions/startup.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
+import { exportSessionToJsonl } from "./session-export.js";
+import { getLatestCompactionEntry, 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 { createLocalBashOperations } from "./tools/bash.js";
+import { buildToolContractSnapshot, isUnclassifiedTool, } from "./tools/contract-snapshot.js";
 import { createAllToolDefinitions } from "./tools/index.js";
+import { createSkillSearchToolDefinition } from "./tools/skill-search.js";
+import { createTodoWriteToolDefinition } from "./tools/todo-write.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
+import { createToolSchemaToolDefinition } from "./tools/tool-schema.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
 /**
  * Parse a skill block from message text.
@@ -71,8 +82,6 @@ function estimateMessagesTokens(messages) {
 // ============================================================================
 // Constants
 // ============================================================================
-/** Standard thinking levels */
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -97,6 +106,7 @@ export class AgentSession {
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
     _overflowRecoveryAttempted = false;
+    _midRunCompactionNeeded = false;
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     // Retry state
@@ -118,6 +128,21 @@ export class AgentSession {
     _excludedToolNames;
     _baseToolsOverride;
     _sessionStartEvent;
+    _permissionGate;
+    _evidenceSink;
+    _diagnosticsOperations;
+    _lspOperations;
+    _mcpRuntime;
+    /** Configured MCP subsystem, or undefined when no server is configured. */
+    get mcpRuntime() {
+        return this._mcpRuntime;
+    }
+    _checkpoints;
+    /** Worktree checkpoints for this session. Inert unless `checkpoints.enabled` is set. */
+    get checkpoints() {
+        return this._checkpoints;
+    }
+    _webSearchOperations;
     _extensionUIContext;
     _extensionMode = "print";
     _extensionCommandContextActions;
@@ -131,6 +156,7 @@ export class AgentSession {
     _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;
@@ -150,11 +176,24 @@ export class AgentSession {
         this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
         this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
+        this._permissionGate = config.permissionGate;
+        this._evidenceSink = config.evidenceSink ?? new SessionEvidenceSink(this.sessionManager);
+        this._diagnosticsOperations = config.diagnosticsOperations;
+        this._lspOperations = config.lspOperations;
+        this._mcpRuntime = config.mcpRuntime;
+        this._webSearchOperations = config.webSearchOperations;
+        this._checkpoints = createSessionCheckpoints({
+            workspace: this._cwd,
+            sessionId: this.sessionManager.getSessionId(),
+            settings: config.checkpointSettings,
+        });
         // Always subscribe to agent events for internal handling
         // (session persistence, extensions, auto-compaction, retry logic)
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
         this._installAgentNextTurnRefresh();
+        this._installMidRunCompactionHook();
+        this._installContextPipeline();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
             includeAllExtensionTools: true,
@@ -193,7 +232,7 @@ export class AgentSession {
         throw new Error(formatNoApiKeyFoundMessage(model.provider));
     }
     async _getSummarizationRequestAuth(model) {
-        if (this.agent.streamFunction === streamSimple) {
+        if (isDefaultStreamFunction(this.agent.streamFunction)) {
             return this._getRequiredRequestAuth(model);
         }
         try {
@@ -223,25 +262,63 @@ export class AgentSession {
     _installAgentToolHooks() {
         this.agent.beforeToolCall = async ({ toolCall, args }) => {
             const runner = this._extensionRunner;
-            if (!runner.hasHandlers("tool_call")) {
-                return undefined;
-            }
-            try {
-                return await runner.emitToolCall({
-                    type: "tool_call",
-                    toolName: toolCall.name,
-                    toolCallId: toolCall.id,
-                    input: args,
-                });
-            }
-            catch (err) {
-                if (err instanceof Error) {
-                    throw err;
+            if (runner.hasHandlers("tool_call")) {
+                let extensionResult;
+                try {
+                    extensionResult = await runner.emitToolCall({
+                        type: "tool_call",
+                        toolName: toolCall.name,
+                        toolCallId: toolCall.id,
+                        input: args,
+                    });
+                }
+                catch (err) {
+                    if (err instanceof Error) {
+                        throw err;
+                    }
+                    throw new Error(`Extension failed, blocking execution: ${String(err)}`);
                 }
-                throw new Error(`Extension failed, blocking execution: ${String(err)}`);
+                // A blocking extension remains authoritative. A non-blocking result
+                // (including a mutation-only `{}`) must still pass the permission gate,
+                // which evaluates the extension's final input below.
+                if (extensionResult?.block === true)
+                    return extensionResult;
+            }
+            // Permission gate (roadmap Phase 2a, ADR 0004). Off by default — see
+            // AgentSessionConfig.permissionGate. When present, every registered tool
+            // call passes through it (contracts.md invariant 2): this is the seam,
+            // not a per-tool opt-in.
+            if (this._permissionGate) {
+                const decision = await evaluateToolCall(toolCall.name, args, {
+                    ...this._permissionGate,
+                    getContract: (name) => this.getToolDefinition(name)?.contract,
+                    getResponder: () => this._extensionMode === "tui" && this._extensionUIContext
+                        ? createInteractiveResponder(this._extensionUIContext)
+                        : undefined,
+                });
+                if (decision.block)
+                    return { block: true, reason: decision.reason };
             }
+            return undefined;
         };
         this.agent.afterToolCall = async ({ toolCall, args, result, isError }) => {
+            const definition = this.getToolDefinition(toolCall.name);
+            if (this._evidenceSink && definition?.contract) {
+                try {
+                    const records = definition.contract.evidence.capture(args, result);
+                    if (!records.every((record) => definition.contract?.evidence.emits.has(record.kind))) {
+                        throw new Error("Evidence capture emitted a kind not declared by its tool contract");
+                    }
+                    if (records.length > 0)
+                        this._evidenceSink.record({ toolName: toolCall.name, records });
+                }
+                catch (error) {
+                    this._evidenceSink.recordDiagnostic?.({
+                        toolName: toolCall.name,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
             const runner = this._extensionRunner;
             const hookResult = runner.hasHandlers("tool_result")
                 ? await runner.emitToolResult({
@@ -291,6 +368,75 @@ export class AgentSession {
             };
         };
     }
+    /** Stop an over-threshold tool loop before it sends another provider request. */
+    _installMidRunCompactionHook() {
+        const previousShouldStopAfterTurn = this.agent.shouldStopAfterTurn;
+        this.agent.shouldStopAfterTurn = async (turn, signal) => {
+            if (await previousShouldStopAfterTurn?.(turn, signal)) {
+                return true;
+            }
+            return this._shouldStopForMidRunCompaction(turn);
+        };
+    }
+    _shouldStopForMidRunCompaction(turn) {
+        if (!turn.hasMoreToolCalls || turn.toolResults.length === 0) {
+            return false;
+        }
+        const settings = this.settingsManager.getCompactionSettings();
+        if (!settings.enabled) {
+            return false;
+        }
+        const contextWindow = this.model?.contextWindow ?? 0;
+        if (contextWindow <= 0) {
+            return false;
+        }
+        const contextTokens = estimateContextTokens(turn.context.messages).tokens;
+        if (!shouldCompact(contextTokens, contextWindow, settings)) {
+            return false;
+        }
+        this._midRunCompactionNeeded = true;
+        return true;
+    }
+    /**
+     * Installs the context pipeline settled in `docs/architecture/contracts.md` § 2:
+     * deferred-schema resolution → tool-result eviction → compaction. Compaction
+     * already runs reactively from `_checkCompaction`, after a response comes back
+     * over-threshold or overflowed; this method only adds the two stages that run
+     * *ahead of* every LLM request, so that reactive check is reached less often
+     * because the request it is reacting to is smaller. It does not call into
+     * compaction and does not need to.
+     *
+     * The wiring itself — where each stage attaches, and why they land in different
+     * seams (`transformContext` for eviction, `streamFunction` for schema
+     * projection) — lives in `./context/pipeline.ts`'s `installContextPipeline`,
+     * shared with the offline replay harness so there is one implementation, not
+     * two. This method only supplies this session's two dependencies: a contract
+     * lookup backed by `getToolDefinition`, and a budget thunk (never cached — see
+     * `_evictionBudget`, which reads live `this.model` / `this.settingsManager` on
+     * every call, so a model switch or settings edit mid-session takes effect on
+     * the very next request).
+     */
+    _installContextPipeline() {
+        installContextPipeline(this.agent, {
+            contractLookup: (name) => this.getToolDefinition(name)?.contract,
+            loadedSchemaNames: this._loadedDeferredSchemas,
+            evictionBudget: () => this._evictionBudget(),
+        });
+    }
+    /**
+     * Token budget for `evictToolResults`'s outbound pass, derived from the same
+     * quantities compaction already uses for its own threshold
+     * (`getCompactionSettings()`; see `shouldCompact` in
+     * `core/compaction/compaction.ts`). The formula itself is `./context/
+     * pipeline.ts`'s `evictionBudget` — see that function's comment for the "why
+     * half of headroom" reasoning; this method only supplies production's real
+     * `contextWindow` / `reserveTokens` inputs.
+     */
+    _evictionBudget() {
+        const contextWindow = this.model?.contextWindow ?? 0;
+        const { reserveTokens } = this.settingsManager.getCompactionSettings();
+        return evictionBudget(contextWindow, reserveTokens);
+    }
     // =========================================================================
     // Event Subscription
     // =========================================================================
@@ -307,6 +453,11 @@ export class AgentSession {
             followUp: [...this._followUpMessages],
         });
     }
+    async _emitSessionCompactFailed(event) {
+        if (this._extensionRunner.hasHandlers("session_compact_failed")) {
+            await this._extensionRunner.emit({ type: "session_compact_failed", ...event });
+        }
+    }
     _getIdleWaitPromise() {
         if (!this._idleWaitPromise) {
             this._idleWaitPromise = new Promise((resolve) => {
@@ -446,6 +597,18 @@ export class AgentSession {
             await this._extensionRunner.emit({ type: "agent_end", messages: event.messages });
         }
         else if (event.type === "turn_start") {
+            // Snapshot before the model gets to act, keyed to the entry `/tree` and `/fork`
+            // already navigate to, so the two agree about what an entry means.
+            //
+            // Awaited, despite the turn latency. Detached, the snapshot races the turn it is
+            // supposed to precede: a tool call can edit the worktree while `add -A` is still
+            // walking it, and the ref then holds mid-turn state that no `/fork` should ever
+            // restore. "The state before the model acted" is the whole guarantee, so paying
+            // for it here is the point. The engine's own timeout bounds the wait and a failed
+            // capture is never fatal.
+            const leafEntryId = this.sessionManager.getLeafEntry()?.id;
+            if (leafEntryId)
+                await this._checkpoints.capture(leafEntryId);
             const extensionEvent = {
                 type: "turn_start",
                 turnIndex: this._turnIndex,
@@ -567,6 +730,9 @@ export class AgentSession {
         this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
         this._disconnectFromAgent();
         this._eventListeners = [];
+        // 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);
         cleanupSessionResources(this.sessionId);
     }
     // =========================================================================
@@ -610,13 +776,24 @@ export class AgentSession {
     /**
      * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
      */
+    /**
+     * The ADR 0010 projection over this session's registry: the one read every surface
+     * that *describes* the tool set consumes. Never an authorization input.
+     */
+    getToolContractSnapshot() {
+        return buildToolContractSnapshot(Array.from(this._toolDefinitions.values()).map(({ definition }) => definition));
+    }
     getAllTools() {
-        return Array.from(this._toolDefinitions.values()).map(({ definition, sourceInfo }) => ({
+        const schemaToolActive = this.getActiveToolNames().includes("tool_schema");
+        return Array.from(this._toolDefinitions.values())
+            .filter(({ definition }) => definition.name !== "tool_schema" || schemaToolActive)
+            .map(({ definition, sourceInfo }) => ({
             name: definition.name,
             description: definition.description,
             parameters: definition.parameters,
             promptGuidelines: definition.promptGuidelines,
             sourceInfo,
+            unclassified: isUnclassifiedTool(definition),
         }));
     }
     getToolDefinition(name) {
@@ -756,6 +933,10 @@ export class AgentSession {
         }
     }
     async _handlePostAgentRun() {
+        if (this._midRunCompactionNeeded) {
+            this._midRunCompactionNeeded = false;
+            return await this._runAutoCompaction("threshold", true);
+        }
         const msg = this._lastAssistantMessage;
         this._lastAssistantMessage = undefined;
         if (!msg) {
@@ -954,9 +1135,16 @@ export class AgentSession {
         if (!text.startsWith("/skill:"))
             return text;
         const spaceIndex = text.indexOf(" ");
-        const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
+        const commandToken = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
         const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
-        const skill = this.resourceLoader.getSkills().skills.find((s) => s.name === skillName);
+        // Matched against the slugged command token (SKILL.5), not the raw frontmatter
+        // name -- identity for an already command-safe name, so an exactly-typed raw
+        // name still matches too. A skill whose name contains a space or other
+        // slash-command-breaking character (docs/skills.md's lenient loading allows
+        // this) is only reachable through its slugged token.
+        const skill = this.resourceLoader
+            .getSkills()
+            .skills.find((s) => slugifySkillCommandName(s.name) === commandToken);
         if (!skill)
             return text; // Unknown skill, pass through
         try {
@@ -1078,7 +1266,7 @@ export class AgentSession {
         if (options?.deliverAs === "nextTurn") {
             this._pendingNextTurnMessages.push(appMessage);
         }
-        else if (this.isStreaming) {
+        else if (this.isStreaming && options?.triggerTurn !== false) {
             if (options?.deliverAs === "followUp") {
                 this.agent.followUp(appMessage);
             }
@@ -1102,6 +1290,7 @@ export class AgentSession {
      *
      * @param content User message content (string or content array)
      * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
+     * @param options.expandPromptTemplates Whether to dispatch extension commands and expand skill commands and prompt templates. Default: false.
      */
     async sendUserMessage(content, options) {
         // Normalize content to text string + optional images
@@ -1125,9 +1314,8 @@ export class AgentSession {
             if (images.length === 0)
                 images = undefined;
         }
-        // Use prompt() with expandPromptTemplates: false to skip command handling and template expansion
         await this.prompt(text, {
-            expandPromptTemplates: false,
+            expandPromptTemplates: options?.expandPromptTemplates ?? false,
             streamingBehavior: options?.deliverAs,
             images,
             source: "extension",
@@ -1189,21 +1377,53 @@ export class AgentSession {
             source,
         });
     }
+    /** True when this session runs behind a permission gate at all. */
+    get hasPermissionGate() {
+        return this._permissionGate !== undefined;
+    }
+    /**
+     * The mode in force right now, and which source won. `getMode` in the gate
+     * config re-reads the store on every decision, so a mode written here applies
+     * to the next tool call with no restart.
+     */
+    async getPermissionMode() {
+        if (!this._permissionGate)
+            return undefined;
+        const snapshot = await this._permissionGate.store.snapshot();
+        return resolveEffectiveModeWithOrigin(this._permissionGate.flagMode, snapshot.modesBySource);
+    }
+    /**
+     * Persist a permission mode to user scope (`~/.apex-code/agent/permissions.json`).
+     * Returns the resolution that is actually in force afterwards, which is *not*
+     * necessarily `mode`: `flag`, `local`, and `project` all outrank `user`, so the
+     * caller has to be able to tell the user their choice was recorded but shadowed.
+     */
+    async setPermissionMode(mode) {
+        if (!this._permissionGate)
+            return undefined;
+        await this._permissionGate.store.apply({ type: "setMode", destination: "user", mode });
+        return this.getPermissionMode();
+    }
     /**
      * Set model directly.
-     * Validates that auth is configured, saves to session and settings.
+     * Validates that auth is configured and saves to the session transcript.
+     * Persists to global defaults only when options.persist is true.
      * @throws Error if no auth is configured for the model
      */
-    async setModel(model) {
+    async setModel(model, options = {}) {
         if (!(await this._modelRuntime.checkAuth(model.provider))) {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
         const previousModel = this.model;
-        const thinkingLevel = this._getThinkingLevelForModelSwitch();
+        const thinkingLevel = this._getThinkingLevelForModelSwitch(model);
         this.agent.state.model = model;
         this.sessionManager.appendModelChange(model.provider, model.id);
-        this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
-        // Re-clamp thinking level for new model's capabilities
+        if (options.persist) {
+            this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+        }
+        // Apply thinking level for the new model.
+        // Per-model thinking level overrides take priority over the global default.
+        // Model persistence does not implicitly rewrite the global thinking default.
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(model, previousModel, "set");
     }
@@ -1213,13 +1433,13 @@ export class AgentSession {
      * @param direction - "forward" (default) or "backward"
      * @returns The new model info, or undefined if only one model available
      */
-    async cycleModel(direction = "forward") {
+    async cycleModel(direction = "forward", options = {}) {
         if (this._scopedModels.length > 0) {
-            return this._cycleScopedModel(direction);
+            return this._cycleScopedModel(direction, options);
         }
-        return this._cycleAvailableModel(direction);
+        return this._cycleAvailableModel(direction, options);
     }
-    async _cycleScopedModel(direction) {
+    async _cycleScopedModel(direction, options) {
         const availableIds = new Set(this._modelRuntime.getAvailableSnapshot().map((model) => `${model.provider}\0${model.id}`));
         const scopedModels = this._scopedModels.filter((scoped) => availableIds.has(`${scoped.model.provider}\0${scoped.model.id}`));
         if (scopedModels.length <= 1)
@@ -1231,20 +1451,23 @@ export class AgentSession {
         const len = scopedModels.length;
         const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
         const next = scopedModels[nextIndex];
-        const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);
+        const thinkingLevel = this._getThinkingLevelForModelSwitch(next.model, next.thinkingLevel);
         // Apply model
         this.agent.state.model = next.model;
         this.sessionManager.appendModelChange(next.model.provider, next.model.id);
-        this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
-        // Apply thinking level.
-        // - Explicit scoped model thinking level overrides current session level
-        // - Undefined scoped model thinking level inherits the current session preference
+        if (options.persist) {
+            this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+        }
+        // Apply thinking level for the new model.
+        // - Explicit scoped model thinking level overrides defaults
+        // - Per-model thinking level overrides take priority over the global default
         // setThinkingLevel clamps to model capabilities.
+        // Model persistence does not implicitly rewrite the global thinking default.
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(next.model, currentModel, "cycle");
         return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
     }
-    async _cycleAvailableModel(direction) {
+    async _cycleAvailableModel(direction, options) {
         const availableModels = this._modelRuntime.getAvailableSnapshot();
         if (availableModels.length <= 1)
             return undefined;
@@ -1255,11 +1478,14 @@ export class AgentSession {
         const len = availableModels.length;
         const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
         const nextModel = availableModels[nextIndex];
-        const thinkingLevel = this._getThinkingLevelForModelSwitch();
+        const thinkingLevel = this._getThinkingLevelForModelSwitch(nextModel);
         this.agent.state.model = nextModel;
         this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
-        this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
-        // Re-clamp thinking level for new model's capabilities
+        if (options.persist) {
+            this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
+        }
+        // Apply thinking level for the new model.
+        // Model persistence does not implicitly rewrite the global thinking default.
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(nextModel, currentModel, "cycle");
         return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
@@ -1270,20 +1496,21 @@ export class AgentSession {
     /**
      * Set thinking level.
      * Clamps to model capabilities based on available thinking levels.
-     * Saves to session and settings only if the level actually changes.
+     * Saves the clamped level to the session transcript only if the level actually changes.
+     * Persists the requested level to global defaults only when options.persist is true.
      */
-    setThinkingLevel(level) {
+    setThinkingLevel(level, options = {}) {
         const availableLevels = this.getAvailableThinkingLevels();
         const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);
         // Only persist if actually changing
         const previousLevel = this.agent.state.thinkingLevel;
         const isChanging = effectiveLevel !== previousLevel;
         this.agent.state.thinkingLevel = effectiveLevel;
+        if (options.persist) {
+            this.settingsManager.setDefaultThinkingLevel(level);
+        }
         if (isChanging) {
             this.sessionManager.appendThinkingLevelChange(effectiveLevel);
-            if (this.supportsThinking() || effectiveLevel !== "off") {
-                this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
-            }
             this._emit({ type: "thinking_level_changed", level: effectiveLevel });
             void this._extensionRunner.emit({
                 type: "thinking_level_select",
@@ -1296,14 +1523,14 @@ export class AgentSession {
      * Cycle to next thinking level.
      * @returns New level, or undefined if model doesn't support thinking
      */
-    cycleThinkingLevel() {
+    cycleThinkingLevel(options = {}) {
         if (!this.supportsThinking())
             return undefined;
         const levels = this.getAvailableThinkingLevels();
         const currentIndex = levels.indexOf(this.thinkingLevel);
         const nextIndex = (currentIndex + 1) % levels.length;
         const nextLevel = levels[nextIndex];
-        this.setThinkingLevel(nextLevel);
+        this.setThinkingLevel(nextLevel, options);
         return nextLevel;
     }
     /**
@@ -1312,7 +1539,7 @@ export class AgentSession {
      */
     getAvailableThinkingLevels() {
         if (!this.model)
-            return THINKING_LEVELS;
+            return [...THINKING_LEVEL_OPTIONS];
         return getSupportedThinkingLevels(this.model);
     }
     /**
@@ -1321,14 +1548,18 @@ export class AgentSession {
     supportsThinking() {
         return !!this.model?.reasoning;
     }
-    _getThinkingLevelForModelSwitch(explicitLevel) {
+    _getThinkingLevelForModelSwitch(targetModel, explicitLevel) {
         if (explicitLevel !== undefined) {
             return explicitLevel;
         }
-        if (!this.supportsThinking()) {
-            return this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
+        // Per-model default takes priority when switching to a model that has one
+        if (targetModel) {
+            const perModel = this.settingsManager.getModelThinkingLevel(targetModel.provider, targetModel.id);
+            if (perModel !== undefined) {
+                return perModel;
+            }
         }
-        return this.thinkingLevel;
+        return this.settingsManager.getDefaultThinkingLevel() ?? this.thinkingLevel ?? DEFAULT_THINKING_LEVEL;
     }
     _clampThinkingLevel(level, _availableLevels) {
         return this.model ? clampThinkingLevel(this.model, level) : "off";
@@ -1359,15 +1590,30 @@ export class AgentSession {
     // =========================================================================
     // Compaction
     // =========================================================================
+    /** Generate Pi's built-in compaction summary for manual and automatic compaction. */
+    async _runDefaultCompaction(preparation, requestModel, apiKey, headers, customInstructions, signal, env, reason) {
+        return compact(preparation, requestModel, apiKey, headers, customInstructions, signal, this.thinkingLevel, this.agent.streamFunction, env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), undefined);
+    }
     /**
      * Manually compact the session context.
-     * Aborts current agent operation first.
+     *
+     * This is the manual entry point used by `/compact`, RPC, and extensions. It is
+     * separate from automatic threshold/overflow compaction, which enters through
+     * `_checkCompaction()` and `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * Aborts the current agent operation first. Manual compaction never retries or
+     * continues the interrupted agent turn.
+     *
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
         await this.abort();
         this._compactionAbortController = new AbortController();
         this._emit({ type: "compaction_start", reason: "manual" });
+        let fromExtension = false;
         try {
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
@@ -1385,7 +1631,6 @@ export class AgentSession {
                 throw new Error("Nothing to compact (session too small)");
             }
             let extensionCompaction;
-            let fromExtension = false;
             if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const result = (await this._extensionRunner.emit({
                     type: "session_before_compact",
@@ -1418,8 +1663,8 @@ export class AgentSession {
                 details = extensionCompaction.details;
             }
             else {
-                // Generate compaction result
-                const result = await compact(preparation, requestModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel, this.agent.streamFunction, env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason: "manual" }));
+                // Shared default summary generator, also used by automatic compaction.
+                const result = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, env, "manual");
                 summary = result.summary;
                 firstKeptEntryId = result.firstKeptEntryId;
                 tokensBefore = result.tokensBefore;
@@ -1467,6 +1712,7 @@ 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 errorMessage = aborted ? undefined : `Compaction failed: ${message}`;
             this._compactionAbortController = undefined;
             this._emit({
                 type: "compaction_end",
@@ -1474,7 +1720,14 @@ export class AgentSession {
                 result: undefined,
                 aborted,
                 willRetry: false,
-                errorMessage: aborted ? undefined : `Compaction failed: ${message}`,
+                errorMessage,
+            });
+            await this._emitSessionCompactFailed({
+                reason: "manual",
+                errorMessage,
+                aborted,
+                willRetry: false,
+                fromExtension,
             });
             throw error;
         }
@@ -1496,16 +1749,25 @@ export class AgentSession {
         this._branchSummaryAbortController?.abort();
     }
     /**
-     * Check if compaction is needed and run it.
-     * Called after agent_end and before prompt submission.
+     * Dispatch automatic compaction after `agent_end` or before prompt submission.
+     * Manual compaction does not call this method; it enters through `compact()`.
      *
-     * Two cases:
-     * 1. Recoverable failure: LLM returned context overflow or stopped below its desired output limit;
-     *    remove the assistant message, compact, and auto-retry once
-     * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
+     * Automatic cases:
+     * 1. Overflow with retry: a context-overflow error or recoverable length stop;
+     *    remove the failed assistant message, compact, and retry the turn once.
+     * 2. Overflow without retry: a successful response exceeded the configured
+     *    context window; compact but preserve the completed response.
+     * 3. Threshold without retry: valid or estimated context usage crossed the
+     *    configured threshold; compact without retrying the completed response.
+     *
+     * Each case calls `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, that method calls the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
      *
      * @param assistantMessage The assistant message to check
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
      */
     async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
         const settings = this.settingsManager.getCompactionSettings();
@@ -1528,38 +1790,49 @@ export class AgentSession {
         if (assistantIsFromBeforeCompaction) {
             return false;
         }
-        // Case 1: Recoverable failure. Explicit/silent context overflow still uses context metadata.
+        // 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.
-        // A successful response over the configured window should compact but must not retry: the
-        // assistant answer already completed and agent.continue() cannot continue from an assistant.
+        const contextOverflow = sameModel && isContextOverflow(assistantMessage, contextWindow);
         const recoverableLength = sameModel && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
-        if (sameModel && (isContextOverflow(assistantMessage, contextWindow) || recoverableLength)) {
+        if (contextOverflow || recoverableLength) {
             const willRetry = assistantMessage.stopReason !== "stop";
+            // Case 2: the response completed successfully. Compact, but do not retry because
+            // agent.continue() cannot continue from a completed assistant response.
             if (!willRetry) {
                 return await this._runAutoCompaction("overflow", false);
             }
             if (this._overflowRecoveryAttempted) {
+                const errorMessage = contextOverflow
+                    ? "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model."
+                    : "Truncated response recovery failed after one compact-and-retry attempt.";
                 this._emit({
                     type: "compaction_end",
                     reason: "overflow",
                     result: undefined,
                     aborted: false,
                     willRetry: false,
-                    errorMessage: "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.",
+                    errorMessage,
+                });
+                await this._emitSessionCompactFailed({
+                    reason: "overflow",
+                    errorMessage,
+                    aborted: false,
+                    willRetry: false,
+                    fromExtension: false,
                 });
                 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.
             this._overflowRecoveryAttempted = true;
-            // Remove the failed or truncated message from agent state. It remains in session history,
-            // but must not be included in the compact-and-retry context.
             const messages = this.agent.state.messages;
             if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
                 this.agent.state.messages = messages.slice(0, -1);
             }
             return await this._runAutoCompaction("overflow", willRetry);
         }
-        // Case 2: Threshold - context is getting large
+        // Case 3: threshold compaction without retry.
         // For error messages or all-zero usage messages, estimate from the last valid response.
         // This ensures sessions that hit persistent API errors (e.g. 529) or malformed zero-usage
         // responses can still compact and do not reset context accounting.
@@ -1568,16 +1841,18 @@ export class AgentSession {
         if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
             const messages = this.agent.state.messages;
             const estimate = estimateContextTokens(messages);
-            if (estimate.lastUsageIndex === null)
-                return false; // No usage data at all
-            // Verify the usage source is post-compaction. Kept pre-compaction messages
-            // have stale usage reflecting the old (larger) context and would falsely
-            // trigger compaction right after one just finished.
-            const usageMsg = messages[estimate.lastUsageIndex];
-            if (compactionEntry &&
-                usageMsg.role === "assistant" &&
-                usageMsg.timestamp <= new Date(compactionEntry.timestamp).getTime()) {
-                return false;
+            // Without provider usage, estimate.tokens is the pure message-size estimate.
+            // Only usage-backed estimates need the stale pre-compaction check.
+            if (estimate.lastUsageIndex !== null) {
+                // Verify the usage source is post-compaction. Kept pre-compaction messages
+                // have stale usage reflecting the old (larger) context and would falsely
+                // trigger compaction right after one just finished.
+                const usageMsg = messages[estimate.lastUsageIndex];
+                if (compactionEntry &&
+                    usageMsg.role === "assistant" &&
+                    usageMsg.timestamp <= new Date(compactionEntry.timestamp).getTime()) {
+                    return false;
+                }
             }
             contextTokens = estimate.tokens;
         }
@@ -1590,11 +1865,19 @@ export class AgentSession {
         return false;
     }
     /**
-     * Internal: Run auto-compaction with events.
+     * Execute threshold or overflow compaction. Manual compaction uses
+     * `AgentSession.compact()` instead. Both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts` after preparation and extension
+     * interception.
+     *
+     * @param reason Automatic trigger selected by `_checkCompaction()`
+     * @param willRetry Whether to continue the interrupted turn after overflow compaction
+     * @returns Whether the post-run loop should call `agent.continue()`
      */
     async _runAutoCompaction(reason, willRetry) {
         const settings = this.settingsManager.getCompactionSettings();
         let started = false;
+        let fromExtension = false;
         try {
             if (!this.model) {
                 return false;
@@ -1609,7 +1892,6 @@ export class AgentSession {
             this._autoCompactionAbortController = new AbortController();
             started = true;
             let extensionCompaction;
-            let fromExtension = false;
             if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const extensionResult = (await this._extensionRunner.emit({
                     type: "session_before_compact",
@@ -1628,6 +1910,12 @@ export class AgentSession {
                         aborted: true,
                         willRetry: false,
                     });
+                    await this._emitSessionCompactFailed({
+                        reason,
+                        aborted: true,
+                        willRetry: false,
+                        fromExtension: false,
+                    });
                     return false;
                 }
                 if (extensionResult?.compaction) {
@@ -1649,8 +1937,8 @@ export class AgentSession {
                 details = extensionCompaction.details;
             }
             else {
-                // Generate compaction result
-                const compactResult = await compact(preparation, requestModel, apiKey, headers, undefined, this._autoCompactionAbortController.signal, this.thinkingLevel, this.agent.streamFunction, env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }));
+                // Shared default summary generator, also used by manual compaction.
+                const compactResult = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, undefined, this._autoCompactionAbortController.signal, env, reason);
                 summary = compactResult.summary;
                 firstKeptEntryId = compactResult.firstKeptEntryId;
                 tokensBefore = compactResult.tokensBefore;
@@ -1665,6 +1953,12 @@ export class AgentSession {
                     aborted: true,
                     willRetry: false,
                 });
+                await this._emitSessionCompactFailed({
+                    reason,
+                    aborted: true,
+                    willRetry: false,
+                    fromExtension,
+                });
                 return false;
             }
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
@@ -1711,15 +2005,23 @@ export class AgentSession {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : "compaction failed";
             if (started) {
+                const formattedErrorMessage = reason === "overflow"
+                    ? `Context overflow recovery failed: ${errorMessage}`
+                    : `Auto-compaction failed: ${errorMessage}`;
                 this._emit({
                     type: "compaction_end",
                     reason,
                     result: undefined,
                     aborted: false,
                     willRetry: false,
-                    errorMessage: reason === "overflow"
-                        ? `Context overflow recovery failed: ${errorMessage}`
-                        : `Auto-compaction failed: ${errorMessage}`,
+                    errorMessage: formattedErrorMessage,
+                });
+                await this._emitSessionCompactFailed({
+                    reason,
+                    errorMessage: formattedErrorMessage,
+                    aborted: false,
+                    willRetry: false,
+                    fromExtension,
                 });
             }
             return false;
@@ -1835,7 +2137,7 @@ export class AgentSession {
                 sourceInfo: template.sourceInfo,
             }));
             const skills = this._resourceLoader.getSkills().skills.map((skill) => ({
-                name: `skill:${skill.name}`,
+                name: `skill:${slugifySkillCommandName(skill.name)}`,
                 description: skill.description,
                 source: "skill",
                 sourceInfo: skill.sourceInfo,
@@ -2012,6 +2314,14 @@ export class AgentSession {
                 }
             }
         }
+        const hasDeferredActiveTool = nextActiveToolNames.some((name) => {
+            const contract = definitionRegistry.get(name)?.definition
+                ?.contract;
+            return contract?.context.deferSchema === true;
+        });
+        if (hasDeferredActiveTool && this._toolRegistry.has("tool_schema")) {
+            nextActiveToolNames.push("tool_schema");
+        }
         this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
     }
     _buildRuntime(options) {
@@ -2026,7 +2336,34 @@ export class AgentSession {
             : createAllToolDefinitions(this._cwd, {
                 read: { autoResizeImages },
                 bash: { commandPrefix: shellCommandPrefix, shellPath },
+                edit: { diagnosticsOperations: this._diagnosticsOperations },
+                write: { diagnosticsOperations: this._diagnosticsOperations },
+                ...(this._lspOperations ? { lsp: { operations: this._lspOperations } } : {}),
+                ...(this._mcpRuntime ? { mcp: this._mcpRuntime } : {}),
+                ...(this._webSearchOperations ? { web_search: { operations: this._webSearchOperations } } : {}),
             });
+        baseToolDefinitions.tool_schema = createToolSchemaToolDefinition({
+            getTool: (name) => {
+                if (!this.getActiveToolNames().includes(name))
+                    return undefined;
+                const definition = this._toolDefinitions.get(name)?.definition;
+                return definition ? { name: definition.name, parameters: definition.parameters } : undefined;
+            },
+            markLoaded: (name) => {
+                this._loadedDeferredSchemas.add(name);
+            },
+        });
+        baseToolDefinitions.todo_write = createTodoWriteToolDefinition({
+            write: (todos) => {
+                this.sessionManager.appendCustomEntry(TODO_CUSTOM_ENTRY_TYPE, todos);
+            },
+        });
+        // Reads the resource loader live on every call (not a snapshot taken here), so
+        // a project-trust change or a settings reload that alters the loaded skill set
+        // is reflected on the next search without rebuilding the tool registry.
+        baseToolDefinitions.skill_search = createSkillSearchToolDefinition({
+            getSkills: () => this.resourceLoader.getSkills().skills,
+        });
         this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
         const extensionsResult = this._resourceLoader.getExtensions();
         if (options.flagValues) {
@@ -2042,7 +2379,9 @@ export class AgentSession {
         this._applyExtensionBindings(this._extensionRunner);
         const defaultActiveToolNames = this._baseToolsOverride
             ? Object.keys(this._baseToolsOverride)
-            : ["read", "bash", "edit", "write"];
+            : this._lspOperations
+                ? ["read", "bash", "edit", "write", "lsp"]
+                : ["read", "bash", "edit", "write"];
         const baseActiveToolNames = options.activeToolNames ?? defaultActiveToolNames;
         this._refreshToolRegistry({
             activeToolNames: baseActiveToolNames,
@@ -2583,11 +2922,11 @@ export class AgentSession {
     /**
      * Export session to HTML.
      * @param outputPath Optional output path (defaults to session directory)
+     * @param options Optional export presentation settings
      * @returns Path to exported file
      */
-    async exportToHtml(outputPath) {
-        const configuredThemeName = this.settingsManager.getTheme();
-        const themeName = configuredThemeName && getThemeByName(configuredThemeName) ? configuredThemeName : undefined;
+    async exportToHtml(outputPath, options = {}) {
+        const themeName = [options.themeName, this.settingsManager.getTheme()].find((candidate) => candidate !== undefined && getThemeByName(candidate) !== undefined);
         // Create tool renderer if we have an extension runner (for custom tool HTML rendering)
         const toolRenderer = createToolHtmlRenderer({
             getToolDefinition: (name) => this.getToolDefinition(name),
@@ -2607,29 +2946,7 @@ export class AgentSession {
      * @returns The resolved output file path.
      */
     exportToJsonl(outputPath) {
-        const filePath = resolvePath(outputPath ?? `session-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`, process.cwd());
-        const dir = dirname(filePath);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        const header = {
-            type: "session",
-            version: CURRENT_SESSION_VERSION,
-            id: this.sessionManager.getSessionId(),
-            timestamp: new Date().toISOString(),
-            cwd: this.sessionManager.getCwd(),
-        };
-        const branchEntries = this.sessionManager.getBranch();
-        const lines = [JSON.stringify(header)];
-        // Re-chain parentIds to form a linear sequence
-        let prevId = null;
-        for (const entry of branchEntries) {
-            const linear = { ...entry, parentId: prevId };
-            lines.push(JSON.stringify(linear));
-            prevId = entry.id;
-        }
-        writeFileSync(filePath, `${lines.join("\n")}\n`);
-        return filePath;
+        return exportSessionToJsonl(this.sessionManager, outputPath);
     }
     // =========================================================================
     // Utilities