@bubblebrain-ai/bubble 0.0.58 → 0.0.60

package/dist/agent.js

@@ -1,16 +1,17 @@
+import { toolImageObservation } from "./context/tool-images.js";
 /**
  * Agent - The core decision loop.
  * It maintains message state, calls the LLM, executes tools, and auto-continues.
  */
-import { compactCurrentTurnToolGroups, compactMessages } from "./context/compact.js";
+import { compactCurrentTurnToolGroups, compactMessages, isCompactionSummaryMessage, splitLeadingContext } from "./context/compact.js";
+import { createContextCheckpoint, checkpointMessages, hasCompleteToolGroups } from "./context/checkpoint.js";
 import { randomUUID } from "node:crypto";
-import { compactMessagesWithLLM } from "./context/compact-llm.js";
 import { estimateToolDefinitionsTokens, getContextBudget, getMaxInputTokens, } from "./context/budget.js";
 import { buildContextUsageSnapshot } from "./context/usage.js";
 import { isContextOverflowError } from "./context/overflow.js";
 import { computeRetryDelayMs, isProviderStreamInterruption, providerStreamRetryLimit, sleepBeforeRetry, } from "./network/retry.js";
 import { projectMessages } from "./context/projector.js";
-import { aggressivePruneMessages, markStableCurrentToolResultsForCache, markToolResultCacheStable } from "./context/prune.js";
+import { aggressivePruneMessages, pruneMessages, markStableCurrentToolResultsForCache, markToolResultCacheStable } from "./context/prune.js";
 import { normalizeToolResultForModel, truncateToolOutputForModel } from "./context/tool-output-truncate.js";
 import { buildDeferredToolsReminder, buildToolFreezeReminder, isPermissionModeReminder, reminderForMode } from "./prompt/reminders.js";
 import { HookBus } from "./orchestrator/hooks.js";
@@ -127,6 +128,9 @@ export class Agent {
     _modeVersion = 0;
     onModeUpdate;
     onCompactionApplied;
+    onContextCheckpoint;
+    getContextRevision;
+    lastCompactionId;
     onMessageAppend;
     onProviderError;
     onToolResult;
@@ -139,6 +143,7 @@ export class Agent {
     budgetLedger;
     budgetSource;
     skillSummaries;
+    skillCatalogChars;
     memoryPrompt;
     fileStateTracker;
     agentCategories;
@@ -166,7 +171,8 @@ export class Agent {
     // unanswerable from the outside. `fired` counts successful compaction
     // computations including ones whose rewrite was later rejected — a
     // fired-but-never-written gap is the churn signal.
-    compactionStats = { resident: 0, subturn: 0, llm: 0, overflow: 0, fired: 0, droppedMessages: 0 };
+    compactionStats = { resident: 0, subturn: 0, llm: 0, heuristic: 0, overflow: 0, fired: 0, droppedMessages: 0 };
+    contextEvents = [];
     constructor(options) {
         this.provider = options.provider;
         this.sessionID = options.sessionID;
@@ -180,6 +186,8 @@ export class Agent {
         this.onToolResult = options.onToolResult;
         this.onModeUpdate = options.onModeUpdate;
         this.onCompactionApplied = options.onCompactionApplied;
+        this.onContextCheckpoint = options.onContextCheckpoint;
+        this.getContextRevision = options.getContextRevision;
         this.hookDefinitions = options.hooks ?? [];
         this.externalHooks = options.externalHooks;
         this.agentRole = options.agentRole ?? "parent";
@@ -189,6 +197,7 @@ export class Agent {
         this.budgetLedger = options.budgetLedger;
         this.budgetSource = options.budgetSource ?? { runId: this.sessionID ?? "agent" };
         this.skillSummaries = options.skills ?? [];
+        this.skillCatalogChars = options.skillCatalogChars;
         this.memoryPrompt = options.memoryPrompt;
         this.fileStateTracker = options.fileStateTracker;
         this.agentCategories = options.agentCategories ?? {};
@@ -230,6 +239,8 @@ export class Agent {
                 // must see deferred-but-registered tools (an explicit include in a
                 // profile is the author pre-unlocking them).
                 allTools: () => [...this.tools.values()],
+                getSkillSummaries: () => this.getSkillSummaries(),
+                getSkillCatalogChars: () => this.getSkillCatalogChars(),
                 createChild: (spec) => this.createChildAgent(spec),
                 recordProviderError: (error, context) => this.recordProviderError(error, context),
                 runExternalHook: (input, abortSignal) => this.runExternalHook(input, abortSignal),
@@ -365,6 +376,9 @@ export class Agent {
     }
     getSystemPromptToolOptions() {
         return {
+            // Rebuilt prompts (model switch, /skills changes) keep the Skills catalog.
+            skills: this.skillSummaries,
+            skillCatalogChars: this.skillCatalogChars,
             ...buildToolPromptOptions(this.getActiveToolEntries()),
             // Rendered through the live accessor (design §1.5), so every host-
             // triggered prompt rebuild picks up the current catalog.
@@ -374,7 +388,13 @@ export class Agent {
             memoryPrompt: this.memoryPrompt,
         };
     }
-    /** Refresh the live Skill catalog after /skills reloads or changes enablement. */
+    getSkillSummaries() {
+        return this.skillSummaries.slice();
+    }
+    getSkillCatalogChars() {
+        return this.skillCatalogChars;
+    }
+    /** Refresh the live Skill catalog after /skills reloads or changes enablement; hosts then rebuild the system prompt. */
     setSkillSummaries(skills) {
         this.skillSummaries = skills.slice();
         this.notifyContextChanged();
@@ -840,13 +860,18 @@ export class Agent {
                 // [LLM summary] + [last user msg], and the projector becomes a no-op for
                 // budget. If it fails (network error, etc.), the projector's existing
                 // algorithmic fallback still kicks in.
-                await this.maybeCompactWithLLM(toolDefinitionTokens);
+                for await (const event of this.maybeCompactWithLLM(toolDefinitionTokens, abortSignal))
+                    yield emit(event);
+                for (const event of this.contextEvents.splice(0))
+                    yield emit(event);
                 const bufferedStreamingToolCallIds = new Set();
                 let currentRequestEstimate;
+                let currentContextWindow;
                 try {
                     markStableCurrentToolResultsForCache(this.messages);
                     const projectedMessages = projectMessages(this.messages, {
-                        mode: "budgeted",
+                        // Semantic compaction is committed above; projection only renders/thins.
+                        mode: "pruned",
                         providerId: this.providerId,
                         modelId: this.apiModel,
                         // Projection changes message identity/count (meta rendering, pruning,
@@ -857,6 +882,8 @@ export class Agent {
                     currentRequestMessageCount = projectedMessages.length;
                     const requestBudget = getContextBudget(this.providerId, this.apiModel, projectedMessages, { additionalInputTokens: toolDefinitionTokens });
                     currentRequestEstimate = requestBudget.estimatedTokens;
+                    currentContextWindow = requestBudget.contextWindow;
+                    yield emit({ type: "context_usage", usedTokens: currentRequestEstimate, contextWindow: currentContextWindow, estimated: true });
                     const maxInputTokens = getMaxInputTokens(requestBudget.contextWindow);
                     if (maxInputTokens !== undefined && currentRequestEstimate > maxInputTokens) {
                         throw new LocalContextPreflightError(currentRequestEstimate, maxInputTokens);
@@ -1069,6 +1096,11 @@ export class Agent {
                         // turn_start resets the streaming display, so re-issuing the whole
                         // request is safe.
                         consecutiveStreamInterruptionRetries += 1;
+                        this.persistProviderError(error, {
+                            messageCount: currentRequestMessageCount,
+                            toolCount: toolDefinitions.length,
+                            retry: { attempt: consecutiveStreamInterruptionRetries, maxAttempts: streamRetryLimit },
+                        });
                         yield emit({
                             type: "provider_retry",
                             attempt: consecutiveStreamInterruptionRetries,
@@ -1098,17 +1130,21 @@ export class Agent {
                         throw error;
                     }
                     const messagesBeforeRecovery = this.messages;
-                    const inputTokensBeforeRecovery = this.lastInputTokens;
-                    const anchorBeforeRecovery = this.lastAnchorMessageCount;
+                    const revisionBeforeRecovery = this.getContextRevision?.();
                     const failedRequestEstimate = currentRequestEstimate ?? getContextBudget(this.providerId, this.apiModel, projectMessages(this.messages, {
-                        mode: "budgeted",
+                        mode: "pruned",
                         providerId: this.providerId,
                         modelId: this.apiModel,
                         additionalInputTokens: toolDefinitionTokens,
                     }), { additionalInputTokens: toolDefinitionTokens }).estimatedTokens;
-                    const droppedMessages = await this.recoverFromOverflow(consecutiveOverflowRecoveries, error instanceof LocalContextPreflightError ? 0.999_999 : 0.9);
-                    const recoveredRequestEstimate = getContextBudget(this.providerId, this.apiModel, projectMessages(this.messages, {
-                        mode: "budgeted",
+                    const candidate = await this.recoverFromOverflow(consecutiveOverflowRecoveries, error instanceof LocalContextPreflightError ? 0.999_999 : 0.9, abortSignal);
+                    if (!candidate) {
+                        persistTerminalProviderError(error);
+                        throw error;
+                    }
+                    const droppedMessages = messagesBeforeRecovery.length - candidate.length;
+                    const recoveredRequestEstimate = getContextBudget(this.providerId, this.apiModel, projectMessages(candidate, {
+                        mode: "pruned",
                         providerId: this.providerId,
                         modelId: this.apiModel,
                         additionalInputTokens: toolDefinitionTokens,
@@ -1120,12 +1156,10 @@ export class Agent {
                     const meaningfulProviderProgress = error instanceof LocalContextPreflightError
                         || recoveredRequestEstimate <= Math.floor(failedRequestEstimate * 0.9);
                     if (!madeProgress || !meaningfulProviderProgress) {
-                        this.messages = messagesBeforeRecovery;
-                        this.lastInputTokens = inputTokensBeforeRecovery;
-                        this.lastAnchorMessageCount = anchorBeforeRecovery;
                         persistTerminalProviderError(error);
                         throw error;
                     }
+                    this.applyContextCheckpoint(candidate, "overflow", undefined, revisionBeforeRecovery, abortSignal);
                     consecutiveOverflowRecoveries += 1;
                     this.compactionStats.overflow += 1;
                     this.compactionStats.fired += 1;
@@ -1137,11 +1171,16 @@ export class Agent {
                         afterEstimatedTokens: recoveredRequestEstimate,
                     });
                     yield emit({ type: "context_recovered", droppedMessages, reason: "overflow" });
+                    yield emit({ type: "context_compaction", status: "completed", compactionId: this.lastCompactionId, persisted: !!this.onContextCheckpoint, preTokens: failedRequestEstimate, postTokens: recoveredRequestEstimate, contextWindow: currentContextWindow });
                     continue;
                 }
                 consecutiveOverflowRecoveries = 0;
                 consecutiveEmptyAssistantRecoveries = 0;
                 consecutiveStreamInterruptionRetries = 0;
+                if (turnUsage && Number.isFinite(turnUsage.promptTokens)) {
+                    // Provider prompt usage already includes cached input; never add cache hits twice.
+                    yield emit({ type: "context_usage", usedTokens: turnUsage.promptTokens + (turnUsage.completionTokens || 0), contextWindow: currentContextWindow, estimated: false });
+                }
                 // Execute tools if any
                 if (assistantMsg.toolCalls && assistantMsg.toolCalls.length > 0) {
                     const parsedCalls = [];
@@ -1448,11 +1487,12 @@ export class Agent {
                         // synchronously, so a mark added on a later turn never reaches disk.
                         markToolResultCacheStable(tc.name, toolMessage);
                         this.appendMessage(toolMessage);
-                        this.compactResidentHistory();
                         flushQueuedReminders();
                         this.onToolResult?.(tc.name, result);
                         executedResults.push(result);
                         yield emit({ type: "tool_end", id: tc.id, name: tc.name, result });
+                        for (const event of this.contextEvents.splice(0))
+                            yield emit(event);
                         for (const update of this.subagents.drainToolUpdates())
                             yield emit(update);
                         if (this._modeVersion !== modeVersionBefore) {
@@ -1463,6 +1503,14 @@ export class Agent {
                             throwIfAborted(abortSignal);
                         }
                     }
+                    const imageObservation = toolImageObservation(executedResults);
+                    if (imageObservation)
+                        this.appendMessage(imageObservation);
+                    // A checkpoint must contain the whole batch, never provider repair's
+                    // placeholder for a sibling that has not executed yet.
+                    this.compactResidentHistory();
+                    for (const event of this.contextEvents.splice(0))
+                        yield emit(event);
                     await hookBus.runBeforeContinuation({
                         agent: this,
                         cwd,
@@ -1508,12 +1556,17 @@ export class Agent {
                 }, abortSignal);
                 for (const event of stopHook.events)
                     yield emit(event);
-                const willContinue = !!hookState.forceContinuationReason;
+                const willContinue = !!hookState.forceContinuationReason
+                    || (options.continueOnPendingInput === true && pendingInputCount() > 0);
                 yield emit({ type: "turn_end", usage: turnUsage, systemFingerprint: turnSystemFingerprint, willContinue });
                 if (willContinue) {
                     delete hookState.forceContinuationReason;
                     continue;
                 }
+                // A follow-up can arrive while the consumer handles turn_end. Recheck
+                // synchronously before closing admission so an accepted input is not lost.
+                if (options.continueOnPendingInput && pendingInputCount() > 0)
+                    continue;
                 for (const event of await rejectPendingInputs("no_continuation"))
                     yield emit(event);
                 break;
@@ -1553,25 +1606,15 @@ export class Agent {
             }, traceContext);
         }
     }
-    async recoverFromOverflow(attempt, maximumSizeRatio = 0.999_999) {
-        const before = this.messages.length;
+    async recoverFromOverflow(attempt, maximumSizeRatio = 0.999_999, abortSignal) {
         const originalMessages = this.messages;
         const beforeBytes = serializedMessageBytes(originalMessages);
-        const commitIfSmaller = (candidate, summary) => {
-            if (!candidate
-                || serializedMessageBytes(candidate) > Math.floor(beforeBytes * maximumSizeRatio))
-                return false;
-            this.messages = candidate;
-            this.lastInputTokens = null;
-            this.lastAnchorMessageCount = null;
-            this.fileStateTracker?.invalidateReadHistory();
-            this.persistCompactionSummary(summary);
-            return true;
-        };
+        const smaller = (candidate) => !!candidate && serializedMessageBytes(candidate) <= Math.floor(beforeBytes * maximumSizeRatio);
+        throwIfAborted(abortSignal);
         if (attempt === 0) {
-            if (commitIfSmaller(aggressivePruneMessages(originalMessages))) {
-                return before - this.messages.length;
-            }
+            const pruned = aggressivePruneMessages(originalMessages);
+            if (smaller(pruned))
+                return pruned;
         }
         // Unlike ordinary pruning, overflow recovery is allowed to thin the most
         // recent completed tool batch. Keeping it protected is exactly what made
@@ -1583,67 +1626,42 @@ export class Agent {
             const bounded = truncateToolOutputForModel(message.content, this.providerId, this.apiModel, { hardByteLimit: emergencyToolLimit });
             return bounded.truncated ? { ...message, content: bounded.content } : message;
         });
-        if (commitIfSmaller(thinnedLatestTools)) {
-            return before - this.messages.length;
-        }
+        if (smaller(thinnedLatestTools))
+            return thinnedLatestTools;
         const keepRecentTurns = attempt >= 1 ? 1 : 2;
-        const llmResult = await compactMessagesWithLLM(originalMessages, {
-            provider: this.provider,
-            model: this.apiModel,
-            thinkingLevel: this.thinkingLevel,
-            keepRecentTurns,
-        });
-        if (llmResult.compacted && commitIfSmaller(llmResult.messages, llmResult.summary)) {
-            return before - this.messages.length;
-        }
-        // Single-turn capable LLM compactor. compactMessagesWithLLM above no-ops
-        // when there's only one user turn (the "single huge prompt with many tool
-        // calls" case), so try the turn-internal compactor before giving up.
+        // Use the same budget-aware summarizer for single- and multi-turn history.
         const { compactWithLLM } = await import("./context/llm-compactor.js");
         const singleTurnResult = await compactWithLLM(originalMessages, {
             provider: this.provider,
             modelId: this.apiModel,
+            providerId: this.providerId,
+            abortSignal,
         });
-        if (singleTurnResult.compacted && commitIfSmaller(singleTurnResult.messages, singleTurnResult.summary)) {
-            return before - this.messages.length;
-        }
+        throwIfAborted(abortSignal);
+        if (singleTurnResult.compacted && smaller(singleTurnResult.messages))
+            return singleTurnResult.messages;
         const fallback = compactMessages(originalMessages, { keepRecentTurns });
-        if (fallback.compacted && commitIfSmaller(fallback.messages, fallback.summary)) {
-            return before - this.messages.length;
-        }
+        if (fallback.compacted && smaller(fallback.messages))
+            return fallback.messages;
         const subturn = compactCurrentTurnToolGroups(originalMessages, {
             keepRecentGroups: attempt === 0 ? 1 : 0,
         });
-        if (subturn.compacted && commitIfSmaller(subturn.messages, subturn.summary)) {
-            return before - this.messages.length;
-        }
-        // Codex-style last-resort: drop the single oldest non-protected message
-        // and let the retry loop try again. Cheap, but eventually narrows even an
-        // intractable single-turn overflow.
-        const realUserIndexes = originalMessages
-            .map((message, index) => message.role === "user" ? index : -1)
-            .filter((index) => index >= 0);
-        const oldestIdx = realUserIndexes.length > 1
-            ? realUserIndexes[0]
-            : -1;
-        const removeUntil = realUserIndexes.length > 1
-            ? realUserIndexes[1]
-            : -1;
-        if (oldestIdx >= 0 && removeUntil > oldestIdx && removeUntil < originalMessages.length) {
-            const candidate = [
-                ...originalMessages.slice(0, oldestIdx),
-                ...originalMessages.slice(removeUntil),
-            ];
-            if (!commitIfSmaller(candidate))
-                return 0;
-            return before - this.messages.length;
+        if (subturn.compacted && smaller(subturn.messages))
+            return subturn.messages;
+        // A two-turn text history has nothing to give at keepRecentTurns 2 and no
+        // tool groups; returning undefined on attempt 0 aborts before attempt 1.
+        if (keepRecentTurns > 1) {
+            const lastTurnOnly = compactMessages(originalMessages, { keepRecentTurns: 1 });
+            if (lastTurnOnly.compacted && smaller(lastTurnOnly.messages))
+                return lastTurnOnly.messages;
         }
-        return 0;
+        // Fail explicitly rather than silently deleting the original instruction.
+        return undefined;
     }
     compactResidentHistory() {
         this.maybeCompactResidentHistory();
     }
-    async maybeCompactWithLLM(additionalInputTokens = 0) {
+    async *maybeCompactWithLLM(additionalInputTokens = 0, abortSignal) {
         if (!this.providerId || !this.apiModel)
             return;
         if (this.messages.length === 0)
@@ -1654,24 +1672,67 @@ export class Agent {
         const budget = getContextBudget(this.providerId, this.apiModel, this.messages, {
             usageAnchorTokens: this.lastInputTokens ?? undefined,
             tailMessages: tail,
-            additionalInputTokens,
+            // Usage anchors already include the schemas sent with that request.
+            additionalInputTokens: this.lastInputTokens === null ? additionalInputTokens : 0,
         });
         if (!budget.shouldCompact)
             return;
-        const { compactWithLLM } = await import("./context/llm-compactor.js");
-        const result = await compactWithLLM(this.messages, {
-            provider: this.provider,
-            modelId: this.apiModel,
-        });
-        if (result.compacted && result.messages) {
-            this.messages = result.messages;
-            this.lastInputTokens = null;
-            this.lastAnchorMessageCount = null;
-            this.fileStateTracker?.invalidateReadHistory();
-            this.compactionStats.llm += 1;
-            this.compactionStats.fired += 1;
-            this.persistCompactionSummary(result.summary);
-            traceEvent("compaction_fired", { path: "llm" });
+        yield { type: "context_compaction", status: "started", preTokens: budget.estimatedTokens, contextWindow: budget.contextWindow };
+        let completed = false;
+        const revision = this.getContextRevision?.();
+        try {
+            const { compactWithLLM } = await import("./context/llm-compactor.js");
+            let result = await compactWithLLM(this.messages, {
+                provider: this.provider,
+                providerId: this.providerId,
+                modelId: this.apiModel,
+                abortSignal,
+            });
+            throwIfAborted(abortSignal);
+            let path = "llm";
+            if (!result.compacted) {
+                // The request projection no longer compacts, so this fallback must
+                // escalate as far as the former budgeted passes did (down to one kept
+                // turn / one kept tool group) or a two-turn text history has no way
+                // under the window when the summarizer is unavailable. Take the first
+                // pass that fits the budget, otherwise the smallest one that fired.
+                const passes = [
+                    ["heuristic", () => compactMessages(this.messages, { keepRecentTurns: 2 })],
+                    ["heuristic", () => compactMessages(this.messages, { keepRecentTurns: 1 })],
+                    ["subturn", () => compactCurrentTurnToolGroups(this.messages, { keepRecentGroups: 2 })],
+                    ["subturn", () => compactCurrentTurnToolGroups(this.messages, { keepRecentGroups: 1 })],
+                ];
+                let smallest = Infinity;
+                for (const [passPath, pass] of passes) {
+                    const candidate = pass();
+                    if (!candidate.compacted || !candidate.messages)
+                        continue;
+                    const candidateBudget = getContextBudget(this.providerId, this.apiModel, candidate.messages, { additionalInputTokens });
+                    if (candidateBudget.estimatedTokens < smallest) {
+                        smallest = candidateBudget.estimatedTokens;
+                        result = candidate;
+                        path = passPath;
+                    }
+                    if (!candidateBudget.shouldCompact)
+                        break;
+                }
+            }
+            const beforeEstimate = getContextBudget(this.providerId, this.apiModel, this.messages, { additionalInputTokens }).estimatedTokens;
+            const candidateEstimate = result.messages
+                ? getContextBudget(this.providerId, this.apiModel, result.messages, { additionalInputTokens }).estimatedTokens : beforeEstimate;
+            if (result.compacted && result.messages && candidateEstimate < beforeEstimate) {
+                this.applyContextCheckpoint(result.messages, "auto", result.summary, revision, abortSignal);
+                this.compactionStats[path] += 1;
+                this.compactionStats.fired += 1;
+                traceEvent("compaction_fired", { path });
+                completed = true;
+                const after = getContextBudget(this.providerId, this.apiModel, this.messages, { additionalInputTokens });
+                yield { type: "context_compaction", status: "completed", compactionId: this.lastCompactionId, persisted: !!this.onContextCheckpoint, preTokens: budget.estimatedTokens, postTokens: after.estimatedTokens, contextWindow: budget.contextWindow };
+            }
+        }
+        finally {
+            if (!completed)
+                yield { type: "context_compaction", status: "failed", preTokens: budget.estimatedTokens, contextWindow: budget.contextWindow };
         }
         // If LLM compaction failed for any reason, leave this.messages alone —
         // the projector's algorithmic budgeted-mode passes will still try.
@@ -1895,13 +1956,15 @@ export class Agent {
         return [{ role: "system", content: childSystemPrompt }, ...forked];
     }
     maybeCompactResidentHistory() {
-        if (this.messages.length === 0) {
+        if (this.messages.length === 0 || !hasCompleteToolGroups(this.messages)) {
             return;
         }
         const before = this.messages;
         const beforeChars = estimateResidentChars(before);
         const beforeToolChars = estimateToolPayloadChars(before);
-        let candidate = projectMessages(before, { mode: "pruned" });
+        // Compact canonical history, not the provider projection: projection
+        // renders runtime meta as user text and can synthesize missing tool results.
+        let candidate = pruneMessages(before);
         const budget = this.providerId && this.apiModel
             ? getContextBudget(this.providerId, this.apiModel, candidate)
             : undefined;
@@ -1916,7 +1979,9 @@ export class Agent {
         // now waits for the context-window budget itself; the heap guard stays
         // as process life-support, not policy.
         const shouldAggressivelyPrune = heapUsed >= RESIDENT_HISTORY_HEAP_HARD_LIMIT;
-        const shouldCompact = !!budget?.shouldCompact;
+        // Model summarization runs at the request boundary. Resident compaction is
+        // an emergency heap guard, not a competing token-triggered lossy policy.
+        const shouldCompact = shouldAggressivelyPrune && !!budget?.shouldCompact;
         if (shouldAggressivelyPrune) {
             candidate = aggressivePruneMessages(candidate);
         }
@@ -1937,6 +2002,7 @@ export class Agent {
                 if (subturn.compacted && subturn.messages) {
                     candidate = subturn.messages;
                     compactedPath = "subturn";
+                    residentSummary = subturn.summary;
                     traceEvent("compaction_fired", { path: "subturn", droppedEntries: subturn.droppedEntries });
                 }
             }
@@ -1951,31 +2017,47 @@ export class Agent {
             && (afterChars < beforeChars
                 || afterToolChars < beforeToolChars
                 || candidate.length < before.length)) {
-            this.messages = candidate;
-            this.lastInputTokens = null;
-            this.lastAnchorMessageCount = null;
-            this.fileStateTracker?.invalidateReadHistory();
+            if (!compactedPath) {
+                // Request-only thinning must not mutate durable history. Under heap
+                // pressure below the token threshold, the pruned candidate still has to
+                // replace resident memory or the life-support guard frees nothing; the
+                // session log keeps the full tool output.
+                if (shouldAggressivelyPrune) {
+                    this.messages = candidate;
+                    this.lastInputTokens = null;
+                    this.lastAnchorMessageCount = null;
+                    this.fileStateTracker?.invalidateReadHistory();
+                }
+                return;
+            }
+            this.applyContextCheckpoint(candidate, "resident", residentSummary, this.getContextRevision?.());
             if (compactedPath === "resident") {
                 this.compactionStats.resident += 1;
-                this.persistCompactionSummary(residentSummary);
             }
             if (compactedPath === "subturn")
                 this.compactionStats.subturn += 1;
+            if (compactedPath && budget) {
+                this.contextEvents.push({ type: "context_compaction", status: "completed", compactionId: this.lastCompactionId, persisted: !!this.onContextCheckpoint, preTokens: budget.estimatedTokens,
+                    postTokens: getContextBudget(this.providerId, this.apiModel, candidate).estimatedTokens, contextWindow: budget.contextWindow });
+            }
         }
     }
-    /**
-     * Hand a multi-turn compaction summary to the host for session persistence.
-     * Failure is swallowed: losing persistence must never break the run itself.
-     */
-    persistCompactionSummary(summary) {
-        if (!summary?.trim())
-            return;
-        try {
+    /** Persist conversational context first; keep live reminders outside the durable projection. */
+    applyContextCheckpoint(messages, reason, summary, baseRevision, abortSignal) {
+        throwIfAborted(abortSignal);
+        const checkpoint = createContextCheckpoint(messages, reason, summary, baseRevision);
+        this.onContextCheckpoint?.(checkpoint);
+        if (!this.onContextCheckpoint && summary?.trim())
             this.onCompactionApplied?.(summary);
-        }
-        catch {
-            // ignore — persistence is best-effort
-        }
+        const { leading } = splitLeadingContext(messages);
+        // The compactor may have folded away reminders from its candidate. Their
+        // lifecycle belongs to the live Agent, not the durable summary/checkpoint.
+        const runtimeReminders = splitLeadingContext(this.messages).body.filter(message => message.role === "meta" && message.includeInLlm !== false && !isCompactionSummaryMessage(message));
+        this.messages = [...leading, ...checkpointMessages(checkpoint), ...runtimeReminders];
+        this.lastCompactionId = checkpoint.compactionId;
+        this.lastInputTokens = null;
+        this.lastAnchorMessageCount = null;
+        this.fileStateTracker?.invalidateReadHistory();
     }
     appendMessage(message) {
         if (message.role === "assistant" && message.content) {
@@ -1985,7 +2067,7 @@ export class Agent {
             message.reasoning = sanitizeInternalReasoningText(message.reasoning);
         }
         if (message.role === "assistant" && message.providerMetadata) {
-            message.providerMetadata = sanitizeAssistantProviderMetadata(message.providerMetadata);
+            message.providerMetadata = sanitizeAssistantProviderMetadata(message.providerMetadata, message.modelId ?? message.model);
         }
         this.messages.push(message);
         traceEvent("agent_message_append", {
@@ -2007,6 +2089,7 @@ export class Agent {
             thinkingLevel: this.thinkingLevel,
             messageCount: request.messageCount,
             toolCount: request.toolCount,
+            retry: request.retry,
         });
     }
     recordProviderError(error, context) {
@@ -2058,7 +2141,7 @@ export class Agent {
         if (this._mode === "plan" && !tool.readOnly) {
             return {
                 content: `Error: Tool "${toolCall.name}" is not allowed in plan mode. ` +
-                    `In plan mode you may only use read-only tools (read, glob, grep, web_search, web_fetch, spawn_agent, wait_agent, send_input, skill_search, skill, tool_search, question, exit_plan_mode). ` +
+                    `In plan mode you may only use read-only tools (read, ls, grep, web_search, web_fetch, spawn_agent, wait_agent, send_input, skill_search, skill, tool_search, question, exit_plan_mode). ` +
                     `To modify files or run commands, present your proposal and call exit_plan_mode so the user can review and approve it.`,
                 isError: true,
             };

package/dist/anthropic-thinking.d.ts

@@ -0,0 +1,4 @@
+/** Claude thinking bound to both the model and the exact preceding conversation.
+ * https://platform.claude.com/docs/en/build-with-claude/preserved-thinking
+ */
+export declare function isClaudeWithBoundThinking(model?: string): boolean;

package/dist/anthropic-thinking.js

@@ -0,0 +1,11 @@
+/** Claude thinking bound to both the model and the exact preceding conversation.
+ * https://platform.claude.com/docs/en/build-with-claude/preserved-thinking
+ */
+export function isClaudeWithBoundThinking(model) {
+    const match = model?.match(/(?:^|:)claude-(opus|fable)-(\d+)(?:-(\d{1,2})(?=-|\[|$))?/i);
+    if (!match)
+        return false;
+    const major = Number(match[2]);
+    const minor = Number(match[3] ?? 0);
+    return major > 5 || (major === 5 && minor >= (match[1].toLowerCase() === "opus" ? 5 : 1));
+}

package/dist/approval/controller.d.ts

@@ -1,7 +1,7 @@
 import type { PermissionCheckResult, PermissionQuery, PermissionRuleSet } from "../permissions/types.js";
 import type { PermissionMode } from "../types.js";
 import type { ExternalHookController } from "../hooks/controller.js";
-import type { BashAllowlist } from "./session-cache.js";
+import { type BashAllowlist } from "./session-cache.js";
 import type { ApprovalController, ApprovalDecision, ApprovalRequest } from "./types.js";
 export interface ApprovalControllerOptions {
     /** Reads the live agent mode on each request so mode flips take effect immediately. */
@@ -16,6 +16,11 @@ export interface ApprovalControllerOptions {
     };
     /** Session-scoped bash command prefix allowlist. Optional. */
     bashAllowlist?: BashAllowlist;
+    /**
+     * Session-scoped grants for non-bash requests (MCP tools), keyed by
+     * sessionGrantKey. Optional; without it hosts cannot offer "this session".
+     */
+    sessionGrants?: Set<string>;
     /** Working directory — used to anchor relative path rules. */
     cwd: string;
     /**
@@ -34,11 +39,13 @@ export interface ApprovalControllerOptions {
  *   deny rule match              → reject (applies even under bypassPermissions)
  *   bypassPermissions            → auto-approve, no prompt
  *   default + edit|write         → auto-approve (workspace paths only; a
- *                                  path outside the workspace falls through
- *                                  to allow rules / the interactive prompt)
+ *                                  path outside the workspace, or a protected
+ *                                  one — .git, agent permission settings —
+ *                                  falls through to the interactive prompt)
  *   plan                         → reject with instructions to use exit_plan_mode
- *   allow rule match             → auto-approve
- *   bash in session allowlist    → auto-approve
+ *   allow rule match             → auto-approve (never for protected paths)
+ *   session grant (bash prefix,
+ *     MCP tool)                  → auto-approve
  *   bash / other                 → delegate to UI; if no UI, reject
  *
  * Deny rules sit at the top as a hard ceiling: bypassPermissions is a trust
@@ -49,7 +56,14 @@ export declare class PermissionAwareApprovalController implements ApprovalContro
     private readonly options;
     constructor(options: ApprovalControllerOptions);
     checkRules(query: PermissionQuery): PermissionCheckResult;
-    request(req: ApprovalRequest): Promise<ApprovalDecision>;
+    request(original: ApprovalRequest): Promise<ApprovalDecision>;
+    /**
+     * Facts the host needs to render the prompt correctly: whether a path is
+     * protected (never auto-approve it host-side either) and what scope a
+     * "this session" approval would cover.
+     */
+    private annotate;
+    private rememberForSession;
     private requestToQuery;
     private checkRequestRules;
     private runPermissionRequestHook;