cursor-opencode-provider 0.4.3 → 0.6.0

package/dist/language-model.js

@@ -5,21 +5,31 @@ import { bidiRunStream, CursorRunInterruptedError, normalizeAgentRunOrigin, } fr
 import { trace, traceRequestContextPaths } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
-import { debugWalkTurnEnded, decodeMessage } from "./protocol/messages.js";
-import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, isUriReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildListMcpResourcesFallback, buildReadMcpResourceFallback, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, } from "./protocol/tools.js";
+import { debugWalkTurnEnded, decodeMessage, encodeMessage } from "./protocol/messages.js";
+import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, isUriReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildListMcpResourcesFallback, buildReadMcpResourceFallback, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, buildCompleteEditReadMessages, rejectPartialReadMutation, binaryWritePayload, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, } from "./protocol/tools.js";
 import { describeCursorExecVariant } from "./protocol/exec-variants.js";
 import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, } from "./protocol/tool-call-bridge.js";
 import { handleKvServerMessage } from "./protocol/kv.js";
-import { handleInteractionQuery } from "./protocol/interactions.js";
-import { getCheckpoint, setCheckpoint } from "./protocol/checkpoint.js";
-import { conversationBlobCount } from "./protocol/blob-store.js";
-import { bindConversationId, } from "./protocol/conversation-bind.js";
+import { buildAskQuestionInteractionReply, buildAsyncAskQuestionCompletion, buildCreatePlanInteractionReply, buildSwitchModeInteractionReply, handleInteractionQuery, } from "./protocol/interactions.js";
+import { ASK_QUESTION_RESULT_FIELD, askQuestionResultFromToolOutput, askQuestionToolInput, } from "./protocol/ask-question.js";
+import { SWITCH_MODE_RESULT_FIELD, getActiveCursorMode, isBridgedCursorPlanModeActive, isCursorPlanModeActive, setActiveCursorMode, switchModeResultFromQuestionOutput, switchModeResultFromToolOutput, switchModeToolInput, takeActiveCursorModeReminder, } from "./protocol/switch-mode.js";
+import { CREATE_PLAN_NOT_APPROVED_REASON, CREATE_PLAN_RESULT_FIELD, CURSOR_PLAN_STAGE_TOOL, createPlanApproved, createPlanStageInput, } from "./protocol/create-plan.js";
+import { flushPlanExecutionKickoff, formatPlanKickoffPath, hasPlanExecutionKickoff, planExecutionKickoffState, planPathFromUri, queuePlanExecutionKickoff, takePlanExecutionKickoffWarning, } from "./plan-execution-kickoff.js";
+import { CURSOR_IMAGE_SAVE_TOOL, imageMimeForPath, remapCursorImageWritePath, } from "./protocol/generate-image.js";
+import { stageCursorImage } from "./image-staging.js";
+import { IMAGE_PERMISSION_DENIED_PREFIX } from "./image-save.js";
+import { clearCheckpoint, getCheckpoint, setCheckpoint } from "./protocol/checkpoint.js";
+import { cursorContextUsageMetadata, decodeConversationTokenDetails, } from "./protocol/token-details.js";
+import { clearConversationBlobs, conversationBlobCount, inspectConversationBlobGraph, } from "./protocol/blob-store.js";
+import { bindConversationId, resolveConversationGroupId, } from "./protocol/conversation-bind.js";
+import { clearPersistedConversationState, hydrateConversationState, persistConversationState, } from "./protocol/conversation-state.js";
+import { initializeConversationPersistence } from "./protocol/conversation-persistence.js";
 import { resolveContinuationPolicy, sessionManager, } from "./session.js";
 import { CursorAuthError, CursorLocalCancellationError, CursorProtocolError, CursorProviderError, CursorRetryExhaustedError, CursorServerError, CursorTransportError, isTransientGrpcStatus, retrySuppressedError, toCursorProviderError, } from "./errors.js";
 import { readCache, cacheFilePath, resolveVariantParameters, paramsImplyMaxMode, extractCursorVariantParameters, resolveCursorWireModelId } from "./models.js";
-import { buildRequestContext } from "./context/build.js";
+import { getOrBuildRequestContext } from "./context/frozen.js";
 import { workspaceRootFromRequestContext } from "./context/env.js";
-import { opencodeGlobalCacheDir, setHostCacheDirOverride } from "./context/paths.js";
+import { ensureOpencodeProjectDir, opencodeGlobalCacheDir, setHostCacheDirOverride, } from "./context/paths.js";
 import { resolveAgentUrl } from "./agent-url.js";
 import { CURSOR_API_HOST, CURSOR_COMPACTION_OPTION } from "./shared.js";
 import { isCompactionSession } from "./compaction-marker.js";
@@ -29,7 +39,7 @@ import { resolveCursorModelSupportsImages } from "./model-metadata.js";
 import { consumeCursorShellResult, registerCursorShellCall, } from "./shell-timeout.js";
 import { analyzeReplayFrame, AttemptReplaySafety } from "./replay-safety.js";
 import { readAllFieldsStrict } from "./protocol/struct.js";
-import { buildLanguageModelV3UsageFromEstimate, buildLanguageModelV3UsageFromTurnEnded, exceedsRequestLocalBudget, turnEndedCounter, } from "./usage.js";
+import { buildLanguageModelV3UsageFromCounters, cursorUsageCountersFromTurnEnded, emptyLanguageModelV3Usage, formatCursorCacheDiagnostics, formatCursorTokenCategories, formatTurnUsageValidation, turnEndedCounter, } from "./usage.js";
 let _availableModels;
 // mtime of the cache file the last time we loaded it. Compared on each call
 // so discoverModels' background refresh is picked up without a process restart.
@@ -56,6 +66,11 @@ const MAX_RETRY_DELAY_MS = 30_000;
 const RUN_REQUEST_DECODE_FAILED = "CURSOR_RUN_REQUEST_DECODE_FAILED";
 const RUN_REQUEST_UNSUPPORTED = "CURSOR_RUN_REQUEST_UNSUPPORTED";
 const RUN_REPLY_FAILED = "CURSOR_RUN_REPLY_FAILED";
+/** Cursor's own conversation export path treats state above 100 MiB as large. */
+export const MAX_CHECKPOINT_BLOB_GRAPH_BYTES = 100 * 1024 * 1024;
+export function checkpointBlobGraphRequiresRebase(stats, maxBytes = MAX_CHECKPOINT_BLOB_GRAPH_BYTES) {
+    return !stats.complete || stats.bytes > maxBytes;
+}
 const RESPONSE_REQUIRED_CHANNEL_BY_FIELD = new Map([
     [2, "exec"],
     [4, "kv"],
@@ -235,9 +250,61 @@ export function connectFrameError(payload) {
         return new CursorProtocolError("Cursor returned a malformed Connect error envelope");
     }
 }
+const toolCatalogWaitersBySession = new Map();
+function publishToolCatalogWaiters(sessionKey, tools) {
+    const waiters = toolCatalogWaitersBySession.get(sessionKey);
+    if (!waiters || waiters.size === 0)
+        return;
+    toolCatalogWaitersBySession.delete(sessionKey);
+    for (const waiter of waiters)
+        waiter.resolve(tools);
+}
+function waitForSiblingToolCatalog(sessionKey, signal) {
+    const existing = toolCatalogBySession.get(sessionKey);
+    if (existing && existing.length > 0) {
+        return Promise.resolve(structuredClone(existing));
+    }
+    if (signal?.aborted) {
+        return Promise.reject(new CursorLocalCancellationError("Cursor tool-catalog wait cancelled"));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let set = toolCatalogWaitersBySession.get(sessionKey);
+        const finish = (tools, error) => {
+            if (settled)
+                return;
+            settled = true;
+            set?.delete(waiter);
+            if (set?.size === 0)
+                toolCatalogWaitersBySession.delete(sessionKey);
+            signal?.removeEventListener("abort", onAbort);
+            if (error)
+                reject(error);
+            else
+                resolve(structuredClone(tools));
+        };
+        const onAbort = () => finish(undefined, new CursorLocalCancellationError("Cursor tool-catalog wait cancelled"));
+        const waiter = {
+            resolve: (tools) => finish(tools),
+            cancel: onAbort,
+        };
+        if (!set) {
+            set = new Set();
+            toolCatalogWaitersBySession.set(sessionKey, set);
+        }
+        set.add(waiter);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        // Re-check after enqueue: a sibling may have published between the initial
+        // map lookup and waiter registration.
+        const raced = toolCatalogBySession.get(sessionKey);
+        if (raced && raced.length > 0)
+            finish(raced);
+    });
+}
 function rememberToolCatalog(sessionKey, tools) {
     toolCatalogBySession.delete(sessionKey);
-    toolCatalogBySession.set(sessionKey, tools);
+    toolCatalogBySession.set(sessionKey, structuredClone(tools));
+    publishToolCatalogWaiters(sessionKey, tools);
     while (toolCatalogBySession.size > MAX_TURN_STATE_SESSIONS) {
         const oldest = toolCatalogBySession.keys().next().value;
         if (!oldest)
@@ -245,6 +312,17 @@ function rememberToolCatalog(sessionKey, tools) {
         toolCatalogBySession.delete(oldest);
     }
 }
+/** Restore the last real catalog solely for lifecycle turns such as compaction. */
+export function restoreTurnToolCatalog(sessionKey, tools) {
+    if (!sessionKey || tools.length === 0)
+        return;
+    rememberToolCatalog(sessionKey, tools);
+}
+function snapshotToolCatalog(sessionKey) {
+    if (!sessionKey)
+        return [];
+    return structuredClone(toolCatalogBySession.get(sessionKey) ?? []);
+}
 function rememberPostCompactionRebase(sessionKey) {
     postCompactionRebaseBySession.delete(sessionKey);
     postCompactionRebaseBySession.add(sessionKey);
@@ -292,6 +370,11 @@ export function createCursorLanguageModel(modelId, providerId, options) {
     // Host Path.cache / explicit override wins over XDG heuristics for this process.
     if (options.cacheDir)
         setHostCacheDirOverride(options.cacheDir);
+    // Start loading and pruning restart state as soon as the provider is built.
+    // startSession awaits this same per-cache-root initialization before binding.
+    void initializeConversationPersistence(opencodeGlobalCacheDir()).catch((error) => {
+        trace(`conversation persistence: startup load failed: ${String(error)}`);
+    });
     return {
         specificationVersion: "v3",
         provider: providerId,
@@ -327,7 +410,6 @@ async function doStreamImpl(modelId, options, callOptions) {
         baseUrl: resolveApiBaseURL(options),
     });
     const prompt = callOptions.prompt;
-    const promptTokens = estimatePromptTokens(prompt);
     const retryPolicy = resolveRetryPolicy(options.retry);
     // pumpWithRecovery owns the complete per-turn attempt budget.  Opening a
     // replacement session here must be a single attempt; otherwise setup retry
@@ -389,7 +471,6 @@ async function doStreamImpl(modelId, options, callOptions) {
                         initialSession: activeSession,
                         controller,
                         abortSignal: callOptions.abortSignal,
-                        promptTokens,
                         retryPolicy,
                         recover: (recovery) => openSession({ recovery }),
                         onSession: (next) => { activeSession = next; },
@@ -400,6 +481,23 @@ async function doStreamImpl(modelId, options, callOptions) {
                     catch (e) {
                         trace(`pull: close failed (already closed/cancelled) err=${e.message}`);
                     }
+                    // pumpWithRecovery has returned only after the Run reached terminal
+                    // turn_ended and endPump cleared ownership. This is the first safe
+                    // point to start a second OpenCode generation. A failed prior handoff
+                    // is retried only because this explicit new provider turn reached its
+                    // own terminal boundary — never from a timer or tight loop.
+                    const kickoff = await flushPlanExecutionKickoff(activeSession.openCodeSessionId, {
+                        cursorSessionID: activeSession.sessionId,
+                        terminal: activeSession.closed,
+                        pumpActive: activeSession.pumpActive || activeSession.pumpOwner != null,
+                        pendingExecs: activeSession.pending.size,
+                    });
+                    if (!kickoff) {
+                        const state = planExecutionKickoffState(activeSession.openCodeSessionId);
+                        if (state?.status === "failed") {
+                            setActiveCursorMode(activeSession.openCodeSessionId, "plan");
+                        }
+                    }
                 }
                 catch (e) {
                     activeSession.pumpActive = false;
@@ -429,7 +527,6 @@ export async function pumpWithRecovery(input) {
         maxAttempts: (input.maxRecoveries ?? 1) + 1,
     };
     const maxRecoveries = retryPolicy.maxAttempts - 1;
-    const requestUsage = { outputChars: 0 };
     input.onSession?.(session);
     for (let attempt = 0;; attempt++) {
         const pumpedSession = session;
@@ -439,8 +536,6 @@ export async function pumpWithRecovery(input) {
             await pump(pumpedSession, input.controller, {
                 textId: crypto.randomUUID(),
                 reasoningId: crypto.randomUUID(),
-                promptTokens: input.promptTokens ?? 0,
-                requestUsage,
             }, input.abortSignal);
             return session;
         }
@@ -473,7 +568,6 @@ export async function pumpWithRecovery(input) {
                 : { kind: "rebase" };
             session = await input.recover(recovery);
             if (recovery.kind === "resume") {
-                session.hadToolCallBoundary = pumpedSession.hadToolCallBoundary;
                 session.usageEstimate = { ...pumpedSession.usageEstimate };
                 session.editToolCalls = new Map(pumpedSession.editToolCalls);
             }
@@ -489,17 +583,29 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const prompt = callOptions.prompt;
     const incomingTools = extractTools(callOptions);
     const sessionKey = opencodeSessionKey(callOptions);
+    const cacheDir = opencodeGlobalCacheDir();
+    if (sessionKey) {
+        const restored = await hydrateConversationState(cacheDir, sessionKey).catch((error) => {
+            trace(`conversation persistence: restore failed sessionKey=${sessionKey}: ${String(error)}`);
+            return undefined;
+        });
+        if (restored?.postCompactionRebase)
+            rememberPostCompactionRebase(sessionKey);
+        if (restored?.toolCatalog.length)
+            restoreTurnToolCatalog(sessionKey, restored.toolCatalog);
+    }
     const providerOptions = callOptions.providerOptions?.cursor;
     // The classic plugin marks OpenCode's agent="compaction" through chat.params.
     // OpenCode 2.0 removed that hook, so its plugin records the same fact against
     // the session id from session.hook("context") instead; consult both.
     // Do not infer this from tools/toolChoice: standalone no-tool calls are valid.
     const isCompaction = providerOptions?.[CURSOR_COMPACTION_OPTION] === true || isCompactionSession(sessionKey);
-    const toolState = resolveTurnToolState({
+    const toolState = await resolveTurnToolState({
         sessionKey,
         incomingTools,
         toolChoice: callOptions.toolChoice,
         isCompaction,
+        abortSignal: callOptions.abortSignal,
     });
     const tools = toolState.advertisedTools;
     const webToolAliases = buildCustomWebToolAliases(tools);
@@ -513,17 +619,55 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const allowTools = toolState.allowTools;
     const discoveredSubagentCatalog = extractHostSubagentCatalog(cursorTools);
     const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
-    const recovery = startOptions?.recovery;
-    const resuming = recovery?.kind === "resume";
+    let recovery = startOptions?.recovery;
+    let resumeRecovery = recovery?.kind === "resume" ? recovery : undefined;
+    let resuming = !!resumeRecovery;
     // Compaction must not reuse the prior conversation; its first normal turn
     // must also rebase so the summary-agent checkpoint cannot replace the normal
     // system prompt and OpenCode's newly compacted history.
-    const bound = resuming
-        ? { conversationId: recovery.conversationId, reset: false, previousId: undefined }
+    let bound = resuming
+        ? { conversationId: resumeRecovery.conversationId, reset: false, previousId: undefined }
         : bindConversationId(sessionKey, { reset: resetState.reset || recovery?.kind === "rebase" });
+    let conversationState = resuming
+        ? resumeRecovery.checkpoint
+        : (bound.reset ? undefined : getCheckpoint(bound.conversationId));
+    let checkpointGraph = conversationState
+        ? inspectConversationBlobGraph(bound.conversationId, conversationState)
+        : { count: 0, bytes: 0, complete: true };
+    let forcedResetReason;
+    if (conversationState && checkpointBlobGraphRequiresRebase(checkpointGraph)) {
+        const previousConversationId = bound.conversationId;
+        forcedResetReason = checkpointGraph.complete
+            ? "oversized-checkpoint-graph"
+            : "incomplete-checkpoint-graph";
+        trace(`checkpoint state rejected: reason=${forcedResetReason} ` +
+            `conversationId=${previousConversationId} checkpointBytes=${conversationState.length} ` +
+            `blobCount=${checkpointGraph.count} blobBytes=${checkpointGraph.bytes} ` +
+            `limitBytes=${MAX_CHECKPOINT_BLOB_GRAPH_BYTES} ` +
+            `detail=${checkpointGraph.fallbackReason ?? "-"} action=rebase`);
+        // A recovery resume must become a history rebase so the interrupted user
+        // request remains in the seed. An ordinary turn keeps its normal user text.
+        if (recovery?.kind === "resume")
+            recovery = { kind: "rebase" };
+        resumeRecovery = undefined;
+        resuming = false;
+        if (!sessionKey) {
+            clearCheckpoint(previousConversationId);
+            clearConversationBlobs(previousConversationId);
+        }
+        bound = bindConversationId(sessionKey, { reset: true });
+        conversationState = undefined;
+        checkpointGraph = { count: 0, bytes: 0, complete: true };
+    }
     const conversationId = bound.conversationId;
+    const conversationGroupId = resolveConversationGroupId(sessionKey, conversationId);
     if (bound.reset) {
-        trace(`conversation reset: reason=${recovery?.kind === "rebase" ? "interrupted-run" : (resetState.reason ?? "unknown")} ` +
+        if (sessionKey) {
+            await clearPersistedConversationState(cacheDir, sessionKey, bound.previousId).catch((error) => {
+                trace(`conversation persistence: reset cleanup failed sessionKey=${sessionKey}: ${String(error)}`);
+            });
+        }
+        trace(`conversation reset: reason=${forcedResetReason ?? (recovery?.kind === "rebase" ? "interrupted-run" : (resetState.reason ?? "unknown"))} ` +
             `sessionKey=${sessionKey ?? "(none)"} ` +
             `previousId=${bound.previousId ?? "-"} → conversationId=${conversationId}`);
     }
@@ -539,9 +683,24 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const workspaceRoot = path.resolve(getSessionDirectory(sessionKey) ?? (options.workspaceRoot || process.cwd()));
     const baseSystemPrompt = extractSystemPrompt(prompt);
     const interactionGuidance = buildOpenCodeInteractionGuidance(cursorTools, isCompaction, workspaceRoot);
-    const systemPrompt = interactionGuidance
-        ? [baseSystemPrompt, interactionGuidance].filter(Boolean).join("\n\n")
-        : baseSystemPrompt;
+    // After an approved SwitchMode, inject the Cursor CLI-shaped mode reminder
+    // (same <system_reminder> contract the CLI uses after flipping unifiedMode).
+    const modeReminder = isCompaction
+        ? undefined
+        : takeActiveCursorModeReminder(sessionKey, {
+            advertisedTools: cursorTools.map((tool) => tool.name),
+        });
+    const kickoffWarning = isCompaction
+        ? undefined
+        : takePlanExecutionKickoffWarning(sessionKey);
+    const systemPrompt = [
+        baseSystemPrompt,
+        interactionGuidance,
+        modeReminder,
+        kickoffWarning ? `<system_reminder>${kickoffWarning}</system_reminder>` : undefined,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
     const history = extractPromptHistory(prompt, {
         preserveTrailingUser: recovery?.kind === "rebase",
         toolResults: isCompaction ? "all" : (recovery?.kind === "rebase" ? "trailing" : "omit"),
@@ -604,7 +763,9 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         baseURL: agentBaseUrl,
         headers: options.headers,
     });
-    const requestContext = await buildRequestContext({ workspaceRoot, tools: cursorTools });
+    // Freeze RequestContext per conversation_id (CLI parity). Rebuilding every
+    // Run mutates volatile slices (git porcelain, layout) and breaks prompt cache.
+    const { context: requestContext, reused: requestContextReused } = await getOrBuildRequestContext(conversationId, { workspaceRoot, tools: cursorTools });
     const contextSubagents = Array.isArray(requestContext.custom_subagents)
         ? requestContext.custom_subagents
             .map((agent) => agent && typeof agent === "object" && typeof agent.name === "string"
@@ -628,15 +789,14 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         ? requestContext.tools
         : [];
     // CLI parity: echo the last conversation_checkpoint_update as conversation_state.
-    // After compaction reset there is no checkpoint — seed from OpenCode history.
-    const conversationState = resuming
-        ? recovery.checkpoint
-        : (bound.reset ? undefined : getCheckpoint(conversationId));
+    // After compaction or an unsafe checkpoint reset there is no checkpoint —
+    // seed a new Cursor conversation from OpenCode's authoritative history.
     const reqBytes = buildRunRequest({
         text: userText,
         images,
         modelId: cursorModelId,
         conversationId,
+        conversationGroupId,
         systemPrompt: conversationState ? undefined : systemPrompt,
         history: conversationState ? undefined : history,
         conversationState,
@@ -657,14 +817,31 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         ? requestContext.hooks_additional_context
         : "";
     const historyChars = history.reduce((n, m) => n + m.content.length, 0);
+    const seedChars = conversationState
+        ? 0
+        : (systemPrompt?.length ?? 0) + userText.length + historyChars;
+    const seedEstimateIn = estimateTokens(seedChars);
+    const checkpointEnvelopeEstimateIn = conversationState
+        ? estimateTokens(userText.length + conversationState.length)
+        : 0;
+    const runRequestWireEstimateIn = estimateTokens(reqBytes.length);
+    const encodedRequestContext = encodeMessage("RequestContext", requestContext);
+    const priorTokenDetails = decodeConversationTokenDetails(conversationState);
+    const requestContextHash = sha(encodedRequestContext);
+    const systemPromptHash = systemPrompt ? sha(systemPrompt) : undefined;
     const usageEstimate = {
-        inputTokens: estimateTokens((systemPrompt?.length ?? 0) + userText.length + historyChars + (conversationState?.length ?? 0)),
+        // This is used only before Cursor supplies authoritative TurnEnded usage.
+        // Estimate the actual protobuf request, not history/system text omitted by
+        // checkpoint Runs. The opaque remote interpretation of KV blobs is logged
+        // separately and deliberately is not mislabeled as a token count.
+        inputTokens: runRequestWireEstimateIn,
         outputTokens: 0,
         cacheRead: 0,
         cacheWrite: 0,
         reasoningTokens: 0,
     };
-    trace(`outbound Run: model=${cursorModelId} opencodeModel=${modelId} conversationId=${conversationId} ` +
+    trace(`outbound Run: model=${cursorModelId} opencodeModel=${modelId} ` +
+        `conversationId=${conversationId} conversationGroupId=${conversationGroupId} ` +
         `params=${JSON.stringify(parameterValues ?? [])} ` +
         `maxMode=${maxMode} systemPromptLen=${systemPrompt?.length ?? 0} ` +
         `tools=${tools.length} incomingTools=${incomingTools.length} compaction=${isCompaction} ` +
@@ -672,14 +849,20 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         `availableModels=${_availableModels?.length ?? 0} userTextLen=${userText.length} ` +
         `images=${images.length} imageBytes=${images.reduce((total, image) => total + image.data.length, 0)} ` +
         `historyMsgs=${history.length} historyChars=${historyChars} ` +
-        `checkpointLen=${conversationState?.length ?? 0} reset=${bound.reset} ` +
-        `resume=${resuming} ` +
-        `usageEstimateIn=${usageEstimate.inputTokens} runRequestBytes=${reqBytes.length}`);
+        `checkpointLen=${conversationState?.length ?? 0} checkpointBlobCount=${checkpointGraph.count} ` +
+        `checkpointBlobBytes=${checkpointGraph.bytes} checkpointGraphComplete=${checkpointGraph.complete} ` +
+        `seedChars=${seedChars} seedEstimateIn=${seedEstimateIn} ` +
+        `checkpointEnvelopeEstimateIn=${checkpointEnvelopeEstimateIn} ` +
+        `reset=${bound.reset} ` +
+        `resume=${resuming} requestContextReused=${requestContextReused} ` +
+        `usageEstimateMode=run-request-wire usageEstimateIn=${usageEstimate.inputTokens} ` +
+        `runRequestBytes=${reqBytes.length} requestContextBytes=${encodedRequestContext.length}`);
     if (hooksCtx)
         trace(`outbound Run hooks_additional_context: ${hooksCtx}`);
     trace(`hash run_request sha256=${sha(reqBytes)}`);
     if (systemPrompt)
         trace(`hash systemPrompt sha256=${sha(systemPrompt)}`);
+    trace(`hash requestContext sha256=${requestContextHash}`);
     if (conversationState)
         trace(`hash checkpoint sha256=${sha(conversationState)}`);
     try {
@@ -693,8 +876,31 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const session = {
         sessionId: crypto.randomUUID(),
         conversationId,
+        cacheDir,
         resumeCheckpoint: undefined,
+        tokenDetails: priorTokenDetails,
+        tokenDetailsFresh: false,
+        cacheDiagnostics: {
+            sessionKey,
+            conversationId,
+            conversationGroupId,
+            modelId: cursorModelId,
+            priorTokenDetails,
+            startedWithCheckpoint: !!conversationState,
+            requestContextReused,
+            requestContextHash,
+            systemPromptHash,
+            checkpointUpdates: 0,
+            tokenDetailUpdates: 0,
+            pumpPasses: 0,
+            stepStarts: 0,
+            stepCompletes: 0,
+            displayToolCalls: 0,
+            execRequests: 0,
+        },
         openCodeSessionId: sessionKey,
+        postCompactionRebase: isCompaction,
+        toolCatalog: snapshotToolCatalog(sessionKey),
         stream,
         frames: stream.frames()[Symbol.asyncIterator](),
         pending: new Map(),
@@ -730,11 +936,10 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         if (session.closed)
             return;
         if (heartbeatWritePending) {
-            sessionManager.close(session, "heartbeat-write-failed", new CursorTransportError("Cursor heartbeat write remained backpressured", {
-                transient: false,
-                replaySafe: false,
-                code: "CURSOR_HEARTBEAT_BACKPRESSURE",
-            }));
+            // The pending write has its own bounded drain wait and will close the
+            // session with the actual failing operation. Do not race it with another
+            // heartbeat or misattribute an existing KV backlog to the heartbeat.
+            trace(`heartbeat skipped: prior heartbeat write is still pending sessionId=${session.sessionId}`);
             return;
         }
         heartbeatWritePending = true;
@@ -773,6 +978,124 @@ export function findContinuationSession(toolResults) {
     }
     return undefined;
 }
+/**
+ * Turn an OpenCode `question` tool result into the frame Cursor is waiting for.
+ *
+ * A synchronous AskQuestion still has its InteractionQuery open, so the answer
+ * goes back as the InteractionResponse for that query id. A `run_async` one was
+ * already released with `async{}`, so — exactly as Cursor CLI does — the answer
+ * travels as a ConversationAction keyed by the originating tool call id, with
+ * the server's own AskQuestionArgs bytes echoed back untouched.
+ */
+function buildAskQuestionContinuationFrame(pending, result) {
+    const metadata = pending.resultMetadata ?? {};
+    const args = metadata.askQuestionArgs;
+    if (!args)
+        throw new CursorProtocolError("Bridged AskQuestion lost its decoded arguments");
+    const answer = askQuestionResultFromToolOutput(args, result.output, result.error !== undefined);
+    if (!args.runAsync) {
+        const interactionId = metadata.interactionId;
+        if (typeof interactionId !== "number") {
+            throw new CursorProtocolError("Bridged AskQuestion lost its interaction id");
+        }
+        return buildAskQuestionInteractionReply(interactionId, answer);
+    }
+    const rawArgs = metadata.askQuestionRawArgs;
+    if (!(rawArgs instanceof Uint8Array)) {
+        throw new CursorProtocolError("Bridged async AskQuestion lost its original arguments");
+    }
+    const toolCallId = metadata.askQuestionToolCallId;
+    return buildAsyncAskQuestionCompletion(typeof toolCallId === "string" ? toolCallId : "", rawArgs, answer);
+}
+/**
+ * Turn the host's plan-approval outcome into the CreatePlan reply Cursor is
+ * still blocking on. One contract across every channel: `success` means the
+ * user approved execution, `error` means the plan was written but not accepted,
+ * so the model keeps planning instead of starting work.
+ *
+ * A host plan-stage tool reports that outcome as tool success/failure. The
+ * emulated path asks through `question`, so only an explicit "Yes" approves.
+ * On approval the session leaves plan mode, which arms the agent-mode
+ * `<system_reminder>` for the next Run.
+ */
+function buildCreatePlanContinuationFrame(pending, result, sessionKey, cursorSessionID) {
+    const metadata = pending.resultMetadata ?? {};
+    const interactionId = metadata.interactionId;
+    if (typeof interactionId !== "number") {
+        throw new CursorProtocolError("Bridged CreatePlan lost its interaction id");
+    }
+    const planUri = metadata.planUri;
+    if (typeof planUri !== "string" || !planUri.trim()) {
+        throw new CursorProtocolError("Bridged CreatePlan lost its plan URI");
+    }
+    const approved = metadata.createPlanBridgeKind === "approve"
+        ? createPlanApproved(result.output, result.error !== undefined, typeof metadata.createPlanQuestion === "string" ? metadata.createPlanQuestion : "")
+        : result.error === undefined;
+    if (!approved) {
+        const reason = result.error?.trim();
+        return buildCreatePlanInteractionReply(interactionId, {
+            error: { error: reason || CREATE_PLAN_NOT_APPROVED_REASON },
+            plan_uri: "",
+        });
+    }
+    // The question-emulated path can report execution approval only when a host
+    // kickoff exists. Otherwise keep planning mode active and return an error.
+    if (metadata.createPlanBridgeKind === "approve" && !hasPlanExecutionKickoff()) {
+        return buildCreatePlanInteractionReply(interactionId, {
+            error: { error: "The plan was approved, but this host cannot start its execution turn." },
+            plan_uri: planUri,
+        });
+    }
+    // Approved: planning is over for this plan, so drop the plan-mode reminder
+    // and hand the next Run the agent-mode contract, exactly as an approved
+    // plan_exit does.
+    setActiveCursorMode(sessionKey, "agent");
+    // Only the question-emulated path needs the provider's synthetic build turn.
+    // A host stage tool owns both approval and execution handoff itself.
+    if (metadata.createPlanBridgeKind === "approve" && sessionKey) {
+        const absolute = typeof metadata.planPath === "string" && metadata.planPath.trim()
+            ? metadata.planPath.trim()
+            : planPathFromUri(planUri);
+        const workspaceRoot = typeof metadata.workspaceRoot === "string" ? metadata.workspaceRoot : undefined;
+        if (!queuePlanExecutionKickoff({
+            sessionID: sessionKey,
+            planPath: formatPlanKickoffPath(absolute, workspaceRoot),
+            cursorSessionID,
+        })) {
+            return buildCreatePlanInteractionReply(interactionId, {
+                error: { error: "The plan was approved, but this host cannot start its execution turn." },
+                plan_uri: planUri,
+            });
+        }
+    }
+    return buildCreatePlanInteractionReply(interactionId, {
+        success: {},
+        plan_uri: planUri,
+    });
+}
+function buildSwitchModeContinuationFrame(pending, result, sessionKey) {
+    const metadata = pending.resultMetadata ?? {};
+    const interactionId = metadata.interactionId;
+    if (typeof interactionId !== "number") {
+        throw new CursorProtocolError("Bridged SwitchMode lost its interaction id");
+    }
+    // A question-emulated exit carries the user's Yes/No as prose, not a plan
+    // tool's success/failure, so it needs the answer parser rather than the
+    // error-shaped mapping.
+    const answer = metadata.switchModeBridgeKind === "question"
+        ? switchModeResultFromQuestionOutput(result.output, result.error !== undefined)
+        : switchModeResultFromToolOutput(result.output, result.error !== undefined);
+    if ("approved" in answer) {
+        const target = metadata.switchModeTarget;
+        if (typeof target === "string" && target.trim()) {
+            const normalized = target.trim().toLowerCase();
+            setActiveCursorMode(sessionKey, target, {
+                bridgedPlanEntered: normalized === "plan" || normalized === "spec",
+            });
+        }
+    }
+    return buildSwitchModeInteractionReply(interactionId, answer);
+}
 /**
  * Deliver trailing tool results onto a live continuation session.
  * Returns the same session when writes succeed (or only bridged results were
@@ -799,22 +1122,131 @@ export function deliverContinuationResults(session, trailingToolResults) {
         }
         const pending = claim.pending;
         let frames = [];
-        if (!pending.bridged) {
+        if (pending.resultField === ASK_QUESTION_RESULT_FIELD) {
+            // A bridged Cursor AskQuestion. The host tool result carries the user's
+            // choices; translate them back into the Cursor result the interaction is
+            // waiting for (or into the deferred completion, when Cursor was already
+            // released with `async`).
+            try {
+                frames = [buildAskQuestionContinuationFrame(pending, r)];
+            }
+            catch (error) {
+                trace(`continuation: ask_question encode FAILED execId=${r.execId} err=${error.message}`);
+                sessionManager.close(session, "result-write-failed");
+                return undefined;
+            }
+        }
+        else if (pending.resultField === SWITCH_MODE_RESULT_FIELD) {
+            // Bridged SwitchMode: host plan_enter / plan_exit outcome becomes
+            // approved{} or rejected{reason} on the still-open InteractionQuery.
+            // Approval also arms the CLI-shaped mode reminder for the next Run.
+            try {
+                frames = [buildSwitchModeContinuationFrame(pending, r, session.openCodeSessionId)];
+            }
+            catch (error) {
+                trace(`continuation: switch_mode encode FAILED execId=${r.execId} err=${error.message}`);
+                sessionManager.close(session, "result-write-failed");
+                return undefined;
+            }
+        }
+        else if (pending.resultField === CREATE_PLAN_RESULT_FIELD) {
+            try {
+                frames = [buildCreatePlanContinuationFrame(pending, r, session.openCodeSessionId, session.sessionId)];
+            }
+            catch (error) {
+                trace(`continuation: create_plan encode FAILED execId=${r.execId} err=${error.message}`);
+                sessionManager.close(session, "result-write-failed");
+                return undefined;
+            }
+        }
+        else if (!pending.bridged) {
             try {
                 const shellResult = pending.resultField === "shell_stream"
                     || pending.resultField === "background_shell_spawn_result"
                     ? consumeCursorShellResult(r.toolCallId, r.output)
                     : undefined;
-                frames = buildExecClientMessages({
-                    execId: r.execId,
-                    resultField: pending.resultField,
-                    output: shellResult?.output ?? r.output,
-                    error: r.error,
-                    toolName: pending.toolName ?? r.toolName,
-                    resultMetadata: pending.resultMetadata,
-                    shellOutcome: shellResult?.outcome,
-                    workspaceRoot: workspaceRootFromRequestContext(session.requestContext),
-                });
+                const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
+                const correlatedEditCallId = pending.resultMetadata?.correlatedEditCallId;
+                const requestedPath = pending.resultMetadata?.path;
+                const correlatedEdit = !r.error
+                    && pending.resultField === "read_result"
+                    && pending.toolName === "read"
+                    && typeof correlatedEditCallId === "string"
+                    && typeof requestedPath === "string"
+                    ? session.editToolCalls?.get(correlatedEditCallId)
+                    : undefined;
+                if (correlatedEdit) {
+                    const absolutePath = path.resolve(workspaceRoot, requestedPath);
+                    if (absolutePath === path.resolve(workspaceRoot, correlatedEdit.path)) {
+                        frames = buildCompleteEditReadMessages(r.execId, absolutePath, requestedPath) ?? [];
+                        if (frames.length > 0) {
+                            correlatedEdit.completeRead = true;
+                            trace(`continuation: upgraded authorized correlated edit read execId=${r.execId} ` +
+                                `path=${JSON.stringify(requestedPath)}`);
+                        }
+                    }
+                }
+                // A refused image commit is Cursor's own `permission_denied` variant,
+                // not a generic write error: its agent branches on that case. The
+                // marker is set by this provider's own tool, so matching it is a
+                // contract rather than a guess at someone else's message text.
+                if (pending.toolName === CURSOR_IMAGE_SAVE_TOOL
+                    && pending.resultField === "write_result"
+                    && r.error?.includes(IMAGE_PERMISSION_DENIED_PREFIX)) {
+                    const deniedPath = typeof pending.resultMetadata?.path === "string"
+                        ? pending.resultMetadata.path
+                        : "";
+                    frames = [encodeMessage("AgentClientMessage", {
+                            exec_client_message: {
+                                id: r.execId,
+                                write_result: {
+                                    permission_denied: {
+                                        path: deniedPath,
+                                        directory: deniedPath ? path.dirname(deniedPath) : "",
+                                        operation: "write",
+                                        error: r.error.replace(`${IMAGE_PERMISSION_DENIED_PREFIX} `, ""),
+                                        is_readonly: false,
+                                    },
+                                },
+                            },
+                        })];
+                }
+                // A committed image reports the file Cursor asked about, not the tool's
+                // prose. `buildExecClientMessages` would otherwise put the message's
+                // character count in `WriteSuccess.file_size`.
+                if (frames.length === 0
+                    && !r.error
+                    && pending.toolName === CURSOR_IMAGE_SAVE_TOOL
+                    && pending.resultField === "write_result") {
+                    frames = [encodeMessage("AgentClientMessage", {
+                            exec_client_message: {
+                                id: r.execId,
+                                write_result: {
+                                    success: {
+                                        path: typeof pending.resultMetadata?.path === "string"
+                                            ? pending.resultMetadata.path
+                                            : "",
+                                        lines_created: 0,
+                                        file_size: typeof pending.resultMetadata?.imageByteLength === "number"
+                                            ? pending.resultMetadata.imageByteLength
+                                            : 0,
+                                    },
+                                },
+                            },
+                        })];
+                }
+                if (frames.length === 0) {
+                    frames = buildExecClientMessages({
+                        execId: r.execId,
+                        resultField: pending.resultField,
+                        output: shellResult?.output ?? r.output,
+                        error: r.error,
+                        toolName: pending.toolName ?? r.toolName,
+                        resultMetadata: pending.resultMetadata,
+                        shellOutcome: shellResult?.outcome,
+                        workspaceRoot,
+                    });
+                }
             }
             catch (error) {
                 trace(`continuation: result encode FAILED execId=${r.execId} err=${error.message}`);
@@ -834,7 +1266,14 @@ export function deliverContinuationResults(session, trailingToolResults) {
             trace(`continuation: completed bridged result execId=${r.execId} toolName=${pending.toolName ?? r.toolName} outLen=${r.output.length}`);
             continue;
         }
-        trace(`continuation: wrote exec result execId=${r.execId} field=${pending.resultField} ` +
+        const resultKind = pending.resultField === ASK_QUESTION_RESULT_FIELD
+            ? "ask_question answer"
+            : pending.resultField === SWITCH_MODE_RESULT_FIELD
+                ? "switch_mode answer"
+                : pending.resultField === CREATE_PLAN_RESULT_FIELD
+                    ? "create_plan answer"
+                    : "exec result";
+        trace(`continuation: wrote ${resultKind} execId=${r.execId} field=${pending.resultField} ` +
             `frames=${outcome.framesWritten} outLen=${r.output.length}`);
     }
     return session;
@@ -879,7 +1318,27 @@ function resolveExplicitAgentBaseURL(options) {
 function isTruthyEnv(value) {
     return value === "1" || value === "true";
 }
+const streamWriteChains = new WeakMap();
+/**
+ * Keep awaited protocol writes ordered per Run stream. In particular, a large
+ * KV get_blob reply must drain before another KV reply or heartbeat is queued;
+ * otherwise one heartbeat observes the backlog created by dozens of ignored
+ * false write() results and reports the wrong operation as the failure.
+ */
 async function writeWithBackpressure(stream, message, operation) {
+    const previous = streamWriteChains.get(stream);
+    const current = (previous ? previous.catch(() => undefined) : Promise.resolve())
+        .then(() => writeWithBackpressureNow(stream, message, operation));
+    streamWriteChains.set(stream, current);
+    try {
+        await current;
+    }
+    finally {
+        if (streamWriteChains.get(stream) === current)
+            streamWriteChains.delete(stream);
+    }
+}
+async function writeWithBackpressureNow(stream, message, operation) {
     let accepted;
     try {
         accepted = stream.write(message);
@@ -892,6 +1351,7 @@ async function writeWithBackpressure(stream, message, operation) {
     }
     if (accepted !== false)
         return;
+    trace(`stream write backpressured: operation=${operation} bytes=${message.length}`);
     if (!stream.waitForDrain) {
         throw new CursorTransportError(`Cursor ${operation} write was backpressured`, {
             transient: false,
@@ -901,6 +1361,7 @@ async function writeWithBackpressure(stream, message, operation) {
     }
     try {
         await stream.waitForDrain(5_000);
+        trace(`stream write drained: operation=${operation} bytes=${message.length}`);
     }
     catch (cause) {
         throw toCursorProviderError(cause, {
@@ -947,13 +1408,27 @@ async function nextFrameWithSemanticDeadline(session) {
  */
 export async function pump(session, controller, ids, abortSignal) {
     sessionManager.registerSession(session);
+    const cacheDiagnostics = session.cacheDiagnostics ??= {
+        sessionKey: session.openCodeSessionId,
+        conversationId: session.conversationId,
+        priorTokenDetails: session.tokenDetails,
+        startedWithCheckpoint: !!session.tokenDetails,
+        requestContextReused: false,
+        requestContextHash: "unavailable",
+        checkpointUpdates: 0,
+        tokenDetailUpdates: 0,
+        pumpPasses: 0,
+        stepStarts: 0,
+        stepCompletes: 0,
+        displayToolCalls: 0,
+        execRequests: 0,
+    };
+    cacheDiagnostics.pumpPasses++;
     const { textId, reasoningId } = ids;
-    const promptTokens = ids.promptTokens ?? 0;
     const advertisedToolNames = advertisedToolNamesFromDescriptors(session.toolDescriptors);
     const advertisedToolNameSet = new Set(advertisedToolNames.map((name) => resolveCustomWebToolAlias(name, session.toolAliases)));
     let textStarted = false;
     let reasoningStarted = false;
-    const requestUsage = ids.requestUsage ?? { outputChars: 0 };
     const replaySafety = new AttemptReplaySafety(session.sessionId);
     const failRunProtocol = (message, code) => {
         replaySafety.markBarrier("unknown-or-malformed-frame");
@@ -961,6 +1436,10 @@ export async function pump(session, controller, ids, abortSignal) {
         sessionManager.close(session, "remote-error", error);
         throw error;
     };
+    const rethrowTransportWriteFailure = (error) => {
+        if (error instanceof CursorProviderError && error.origin !== "protocol")
+            throw error;
+    };
     // OpenCode cancels the ReadableStream between turns (see the cancel handler
     // in doStreamImpl). The frames iterator can still yield a final `done` after
     // the cancel lands — controller.enqueue on a cancelled controller throws.
@@ -1016,13 +1495,17 @@ export async function pump(session, controller, ids, abortSignal) {
         }
     };
     /**
-     * Cursor's streamed edit handshake reads the target before it sends the
-     * replacement through write_args. For a new file that read naturally fails,
-     * which makes the model abandon the edit and fall back to a shell heredoc.
-     * Treat only a missing target correlated to an edit_tool_call as an empty
-     * file, allowing Cursor to continue to the ordinary OpenCode write call.
+     * Cursor's streamed edit handshake needs the complete target before it sends
+     * the replacement through write_args. OpenCode's ordinary read tool caps at
+     * 50 KB, so forwarding this private prerequisite read teaches Cursor's editor
+     * that a large file ends at the cap and produces a destructive replacement.
+     *
+     * Answer a correlated workspace-file read directly up to Cursor's own 50 MB
+     * edit limit. Missing targets remain empty-file successes so creation can
+     * continue. External and otherwise ineligible reads retain OpenCode's normal
+     * permission-aware path.
      */
-    const recoverMissingEditRead = (parsed, displayCallId) => {
+    const recoverCorrelatedEditRead = (parsed, displayCallId) => {
         if (!displayCallId ||
             parsed.resultField !== "read_result" ||
             parsed.toolName !== "read" ||
@@ -1043,8 +1526,54 @@ export async function pump(session, controller, ids, abortSignal) {
         const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
         const resolvePath = (value) => path.resolve(workspaceRoot, value);
         const absolutePath = resolvePath(requestedPath);
-        if (absolutePath !== resolvePath(editPath) || fs.existsSync(absolutePath))
+        if (absolutePath !== resolvePath(editPath))
             return false;
+        let exists = true;
+        try {
+            fs.lstatSync(absolutePath);
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? error.code
+                : undefined;
+            if (code !== "ENOENT")
+                return false;
+            exists = false;
+        }
+        if (exists) {
+            // Do not bypass OpenCode's external-directory permission boundary, even
+            // through a symlink rooted in the workspace.
+            try {
+                const realRoot = fs.realpathSync(workspaceRoot);
+                const realTarget = fs.realpathSync(absolutePath);
+                const relative = path.relative(realRoot, realTarget);
+                if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+                    parsed.resultMetadata = {
+                        ...parsed.resultMetadata,
+                        correlatedEditCallId: displayCallId,
+                    };
+                    return false;
+                }
+                const frames = buildCompleteEditReadMessages(parsed.id, absolutePath, requestedPath);
+                if (!frames)
+                    return false;
+                for (const frame of frames)
+                    session.stream.write(frame);
+                const editCall = session.editToolCalls?.get(displayCallId);
+                if (editCall)
+                    editCall.completeRead = true;
+                trace(`exec: correlated edit read completed directly id=${parsed.id} ` +
+                    `path=${JSON.stringify(requestedPath)}; awaiting write_args`);
+                return true;
+            }
+            catch {
+                parsed.resultMetadata = {
+                    ...parsed.resultMetadata,
+                    correlatedEditCallId: displayCallId,
+                };
+                return false;
+            }
+        }
         try {
             for (const frame of buildExecClientMessages({
                 execId: parsed.id,
@@ -1061,7 +1590,7 @@ export async function pump(session, controller, ids, abortSignal) {
             return true;
         }
         catch (e) {
-            const error = new Error(`Failed to recover Cursor edit read for a new file: ${e.message}`);
+            const error = new Error(`Failed to recover Cursor edit read: ${e.message}`);
             trace(`exec: edit read recovery FAILED ${error.message}`);
             safeError(error);
             sessionManager.close(session);
@@ -1079,7 +1608,7 @@ export async function pump(session, controller, ids, abortSignal) {
      *
      * Read-only by construction — write/edit targets are never checked, so
      * legitimate file creation (path resolves, file absent) is never denied. Runs
-     * after recoverMissingEditRead, which has already converted the new-file edit
+     * after recoverCorrelatedEditRead, which has already converted the edit
      * handshake read into an empty-file success. EACCES/EPERM and other stat
      * errors fall through to OpenCode so a genuine permission decision stands.
      */
@@ -1089,10 +1618,9 @@ export async function pump(session, controller, ids, abortSignal) {
         const requested = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
         if (!requested)
             return false;
-        // A scheme-addressed target is the host's to resolve, not a local file to
-        // stat. Rejecting it here makes host-mounted capabilities (oh-my-pi's
-        // `xd://` device URLs, which is how every MCP tool is exposed by default)
-        // permanently unreachable through this provider.
+        // A scheme-addressed target is the advertised host executor's to resolve,
+        // not a local file to stat. Rejecting it here would make any URI-backed
+        // capability permanently unreachable through this provider.
         if (isUriReadTarget(requested)) {
             trace(`exec: forwarding URI read target id=${parsed.id} target=${JSON.stringify(requested)}`);
             return false;
@@ -1141,9 +1669,7 @@ export async function pump(session, controller, ids, abortSignal) {
             textStarted = true;
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
-        if (safeEnqueue({ type: "text-delta", id: textId, delta: text })) {
-            requestUsage.outputChars += text.length;
-        }
+        safeEnqueue({ type: "text-delta", id: textId, delta: text });
     };
     const emitReasoning = (text) => {
         if (!text)
@@ -1154,38 +1680,32 @@ export async function pump(session, controller, ids, abortSignal) {
             reasoningStarted = true;
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
-        if (safeEnqueue({ type: "reasoning-delta", id: reasoningId, delta: text })) {
-            requestUsage.outputChars += text.length;
-        }
+        safeEnqueue({ type: "reasoning-delta", id: reasoningId, delta: text });
     };
-    const emitFinish = (te, reason) => {
+    const emitFinish = (te, reason, settledUsage, settledSource) => {
         closeOpenSpans();
-        // TurnEnded is request-local only when this Run did not previously stop at
-        // a tool boundary. On a held multi-step Run Cursor aggregates every model
-        // invocation into these counters; treating that billed total as the final
-        // request's prompt size makes OpenCode compact after ordinary tasks.
-        const cumulativeByBoundary = !!te && session.hadToolCallBoundary === true;
-        const cumulativeByBudget = !!te && !cumulativeByBoundary && exceedsRequestLocalBudget(te, {
-            inputTokens: session.usageEstimate.inputTokens,
-            outputTokens: session.usageEstimate.outputTokens,
-        });
-        const cumulativeTurnEnded = cumulativeByBoundary || cumulativeByBudget;
-        if (te && !cumulativeTurnEnded) {
-            session.usageEstimate = {
-                inputTokens: turnEndedCounter(te, "input_tokens"),
-                outputTokens: turnEndedCounter(te, "output_tokens"),
-                cacheRead: turnEndedCounter(te, "cache_read"),
-                cacheWrite: turnEndedCounter(te, "cache_write"),
-                reasoningTokens: turnEndedCounter(te, "reasoning_tokens"),
-            };
-        }
         const est = session.usageEstimate;
-        const usage = te && !cumulativeTurnEnded
-            ? buildLanguageModelV3UsageFromTurnEnded(te)
-            : buildLanguageModelV3UsageFromEstimate(est, promptTokens, requestUsage.outputChars, estimateTokens);
-        if (!te)
-            session.hadToolCallBoundary = true;
-        const providerMetadata = te ? cursorTurnEndedProviderMetadata(te) : undefined;
+        // OpenCode persists and sums every AI SDK finish. Cursor does not expose a
+        // final context total at tool boundaries, so charging the growing estimate
+        // there multiplies one held Run across all of its steps. Emit zero at
+        // intermediate boundaries, then prefer checkpoint tokenDetails exactly once
+        // when TurnEnded closes the held Run. Cursor CLI keeps context occupancy in
+        // agentStore tokenDetails; it does not reinterpret TurnEnded as occupancy.
+        const tokenDetails = te ? session.tokenDetails : undefined;
+        const contextSource = tokenDetails
+            ? session.tokenDetailsFresh
+                ? "checkpoint-current-run"
+                : "checkpoint-previous-turn"
+            : undefined;
+        const counters = te ? cursorUsageCountersFromTurnEnded(te) : undefined;
+        const usage = settledUsage ?? (te
+            ? tokenDetails
+                ? buildLanguageModelV3UsageFromCounters(counters, { contextTotalTokens: tokenDetails.usedTokens })
+                : emptyLanguageModelV3Usage()
+            : emptyLanguageModelV3Usage());
+        const providerMetadata = te
+            ? cursorTurnEndedProviderMetadata(te, tokenDetails, contextSource)
+            : undefined;
         const reasonLabel = typeof reason === "object" && reason && "unified" in reason
             ? String(reason.unified ?? "unknown")
             : String(reason);
@@ -1199,8 +1719,13 @@ export async function pump(session, controller, ids, abortSignal) {
             `rawOut=${te ? turnEndedCounter(te, "output_tokens") : est.outputTokens} ` +
             `rawCacheRead=${te ? turnEndedCounter(te, "cache_read") : est.cacheRead} ` +
             `rawCacheWrite=${te ? turnEndedCounter(te, "cache_write") : est.cacheWrite} ` +
-            `guard=${cumulativeByBoundary ? "boundary" : cumulativeByBudget ? "over-budget" : "none"} ` +
-            `source=${te ? (cumulativeTurnEnded ? "estimate-cumulative-turn-ended" : "turn_ended") : "estimate"}`);
+            `source=${te
+                ? settledSource ?? (contextSource ?? "unavailable")
+                : "intermediate-zero"}`);
+        if (counters) {
+            trace(formatTurnUsageValidation(counters, usage, tokenDetails, contextSource));
+            trace(formatCursorCacheDiagnostics(counters, tokenDetails, cacheDiagnostics.priorTokenDetails, cacheDiagnostics));
+        }
         safeEnqueue({
             type: "finish",
             usage,
@@ -1331,9 +1856,20 @@ export async function pump(session, controller, ids, abortSignal) {
             if (checkpointRaw != null) {
                 const bytes = normalizeCheckpointBytes(checkpointRaw);
                 if (bytes && bytes.length > 0) {
+                    cacheDiagnostics.checkpointUpdates++;
                     setCheckpoint(session.conversationId, bytes);
                     session.resumeCheckpoint = Uint8Array.from(bytes);
-                    trace(`checkpoint: stored ${bytes.length}B for conversationId=${session.conversationId}`);
+                    const tokenDetails = decodeConversationTokenDetails(bytes);
+                    if (tokenDetails) {
+                        cacheDiagnostics.tokenDetailUpdates++;
+                        session.tokenDetails = tokenDetails;
+                        session.tokenDetailsFresh = true;
+                    }
+                    const context = tokenDetails
+                        ? ` context=${tokenDetails.usedTokens}/${tokenDetails.maxTokens} ` +
+                            `categories=${formatCursorTokenCategories(tokenDetails)}`
+                        : " context=unavailable";
+                    trace(`checkpoint: stored ${bytes.length}B for conversationId=${session.conversationId}${context}`);
                 }
             }
             if (iu?.text_delta) {
@@ -1344,11 +1880,25 @@ export async function pump(session, controller, ids, abortSignal) {
             }
             else if (iu?.turn_ended) {
                 trace(`turn_ended raw wire fields: ${debugWalkTurnEnded(payload)}`);
-                emitFinish(iu.turn_ended, { unified: "stop", raw: undefined });
+                const turnEnded = iu.turn_ended;
+                if (session.openCodeSessionId) {
+                    await persistConversationState(session.cacheDir ?? opencodeGlobalCacheDir(), {
+                        sessionKey: session.openCodeSessionId,
+                        conversationId: session.conversationId,
+                        requestContext: session.requestContext,
+                        toolCatalog: session.toolCatalog ?? [],
+                        postCompactionRebase: session.postCompactionRebase,
+                    }).catch((error) => {
+                        trace(`conversation persistence: TurnEnded save failed ` +
+                            `sessionKey=${session.openCodeSessionId}: ${String(error)}`);
+                    });
+                }
+                emitFinish(turnEnded, { unified: "stop", raw: undefined });
                 sessionManager.close(session);
                 return;
             }
             else if (iu?.tool_call_started) {
+                cacheDiagnostics.displayToolCalls++;
                 // Stash Cursor display ToolCall until exec claims it, or completed bridges it.
                 const started = iu.tool_call_started;
                 const callId = typeof started.call_id === "string" ? started.call_id : "";
@@ -1435,7 +1985,14 @@ export async function pump(session, controller, ids, abortSignal) {
                     }
                 }
             }
+            else if (iu?.step_started) {
+                cacheDiagnostics.stepStarts++;
+            }
+            else if (iu?.step_completed) {
+                cacheDiagnostics.stepCompletes++;
+            }
             else if (esm) {
+                cacheDiagnostics.execRequests++;
                 const esmId = esm.id ?? 0;
                 if (esm.request_context_args) {
                     // Server turn-setup probe (#10). Reply with full OpenCode-sourced context.
@@ -1451,10 +2008,11 @@ export async function pump(session, controller, ids, abortSignal) {
                     }
                     try {
                         traceRequestContextPaths(`exec request_context reply id=${esmId}`, session.requestContext);
-                        session.stream.write(buildRequestContextResult(esmId, session.requestContext));
+                        await writeWithBackpressure(session.stream, buildRequestContextResult(esmId, session.requestContext), `request-context reply id=${esmId}`);
                         trace(`exec request_context: replied`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor request-context reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1467,10 +2025,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         ? stateArgs.server_identifiers.join(",")
                         : "";
                     try {
-                        session.stream.write(buildMcpStateResult(esmId, stateArgs, session.requestContext));
+                        await writeWithBackpressure(session.stream, buildMcpStateResult(esmId, stateArgs, session.requestContext), `MCP-state reply id=${esmId}`);
                         trace(`exec mcp_state: replied id=${esmId} requested=[${requested}]`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor MCP-state reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1481,10 +2040,11 @@ export async function pump(session, controller, ids, abortSignal) {
                     const args = esm.list_mcp_resources_exec_args;
                     const server = typeof args.server === "string" ? args.server : "";
                     try {
-                        session.stream.write(buildListMcpResourcesFallback(esmId));
+                        await writeWithBackpressure(session.stream, buildListMcpResourcesFallback(esmId), `list-MCP-resources reply id=${esmId}`);
                         trace(`exec list_mcp_resources: replied id=${esmId} server=${server || "(all)"} success{resources:[]}`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor list_mcp_resources reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1494,10 +2054,11 @@ export async function pump(session, controller, ids, abortSignal) {
                     const server = typeof args.server === "string" ? args.server : "";
                     const uri = typeof args.uri === "string" ? args.uri : "";
                     try {
-                        session.stream.write(buildReadMcpResourceFallback(esmId, server, uri));
+                        await writeWithBackpressure(session.stream, buildReadMcpResourceFallback(esmId, server, uri), `read-MCP-resource reply id=${esmId}`);
                         trace(`exec read_mcp_resource: replied id=${esmId} server=${server} uri=${uri} error{server not found}`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor read_mcp_resource reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1515,6 +2076,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         const editCall = displayCallId
                             ? session.editToolCalls?.get(displayCallId)
                             : undefined;
+                        // A complete correlated edit read is trusted provenance: unlike an
+                        // ordinary capped read it cannot have appended our warning marker,
+                        // and the source itself may legitimately contain the marker text.
+                        if (!editCall?.completeRead)
+                            rejectPartialReadMutation(parsed);
                         if (editCall) {
                             const remapped = remapCorrelatedEditWriteForCatalog(parsed, advertisedToolNameSet, editCall.path, workspaceRootFromRequestContext(session.requestContext));
                             if (parsed.resultField === "write_result" && displayCallId) {
@@ -1547,6 +2113,63 @@ export async function pump(session, controller, ids, abortSignal) {
                                 return;
                             continue;
                         }
+                        // Cursor writes a generated image with an ordinary write exec whose
+                        // `file_bytes` are binary (Cursor CLI's agent does exactly this, then
+                        // reads the client's WriteResult back). OpenCode's `write` takes a
+                        // string, so those bytes are staged and committed by the host tool
+                        // that can raise the `edit` permission before anything hits disk.
+                        const binaryWrite = binaryWritePayload(parsed);
+                        if (binaryWrite) {
+                            if (!advertisedToolNameSet.has(CURSOR_IMAGE_SAVE_TOOL)) {
+                                const reason = "This OpenCode agent cannot write binary file content. "
+                                    + "Do not retry this write with the same bytes.";
+                                if (!rejectExec(parsed, reason, "binary write unsupported"))
+                                    return;
+                                continue;
+                            }
+                            const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
+                            const projectDir = ensureOpencodeProjectDir(workspaceRoot);
+                            const target = remapCursorImageWritePath(binaryWrite.path, {
+                                workspaceRoot,
+                                projectDir,
+                            });
+                            let imageId;
+                            try {
+                                imageId = stageCursorImage({
+                                    path: target,
+                                    projectDir,
+                                    mime: imageMimeForPath(target),
+                                    data: binaryWrite.data,
+                                    sessionId: session.openCodeSessionId,
+                                });
+                            }
+                            catch (error) {
+                                if (!rejectExec(parsed, error.message, "binary write too large"))
+                                    return;
+                                continue;
+                            }
+                            if (displayCallId)
+                                session.displayToolCalls.delete(displayCallId);
+                            sessionManager.registerPending(parsed.id, session, parsed.resultField, CURSOR_IMAGE_SAVE_TOOL, false, {
+                                ...parsed.resultMetadata,
+                                path: target,
+                                binaryWriteBytes: undefined,
+                                imageByteLength: binaryWrite.data.length,
+                            });
+                            const toolCallId = `cursor_${session.sessionId}_${parsed.id}`;
+                            trace(`exec: binary write STAGED toolCallId=${toolCallId} ` +
+                                `requested=${JSON.stringify(binaryWrite.path)} target=${JSON.stringify(target)} ` +
+                                `bytes=${binaryWrite.data.length}`);
+                            closeOpenSpans();
+                            safeEnqueue({
+                                type: "tool-call",
+                                toolCallId,
+                                toolName: CURSOR_IMAGE_SAVE_TOOL,
+                                input: JSON.stringify({ image_id: imageId }),
+                            });
+                            emitFinish(undefined, { unified: "tool-calls", raw: undefined });
+                            return;
+                        }
                         // Cursor has native capabilities (Task, filesystem, shell, etc.) in
                         // addition to the MCP descriptors sent by this provider. The model
                         // can request one even when the current OpenCode agent omitted its
@@ -1566,7 +2189,7 @@ export async function pump(session, controller, ids, abortSignal) {
                                 return;
                             continue;
                         }
-                        if (recoverMissingEditRead(parsed, displayCallId))
+                        if (recoverCorrelatedEditRead(parsed, displayCallId))
                             continue;
                         if (rejectMissingReadTarget(parsed)) {
                             if (displayCallId)
@@ -1613,11 +2236,25 @@ export async function pump(session, controller, ids, abortSignal) {
             else if (interactionQuery) {
                 // InteractionQuery is a must-reply channel, just like exec and KV. AI
                 // SDK has no Cursor-specific UI callback, so answer immediately with the
-                // conservative headless policy from protocol/interactions.ts (including
-                // F14 create_plan auto-ack / empty plan_uri for CLI headless parity).
+                // policy from protocol/interactions.ts (AskQuestion bridge, CreatePlan
+                // write under OpenCode defaults, GenerateImage approve when saveable).
                 const handled = (() => {
                     try {
-                        return handleInteractionQuery(interactionQuery, payload);
+                        return handleInteractionQuery(interactionQuery, payload, {
+                            canBridgeAskQuestion: session.allowTools && advertisedToolNameSet.has("question"),
+                            allowTools: session.allowTools,
+                            advertisedTools: advertisedToolNameSet,
+                            canSaveGeneratedImage: session.allowTools && advertisedToolNameSet.has(CURSOR_IMAGE_SAVE_TOOL),
+                            canBridgeCreatePlan: session.allowTools
+                                && isBridgedCursorPlanModeActive(session.openCodeSessionId)
+                                && advertisedToolNameSet.has(CURSOR_PLAN_STAGE_TOOL)
+                                && advertisedToolNameSet.has("write"),
+                            planModeActive: isCursorPlanModeActive(session.openCodeSessionId),
+                            ...(getActiveCursorMode(session.openCodeSessionId)
+                                ? { activeCursorModeId: getActiveCursorMode(session.openCodeSessionId) }
+                                : {}),
+                            workspaceRoot: workspaceRootFromRequestContext(session.requestContext),
+                        });
                     }
                     catch {
                         return failRunProtocol("Cursor interaction request could not be handled", RUN_REQUEST_UNSUPPORTED);
@@ -1627,13 +2264,139 @@ export async function pump(session, controller, ids, abortSignal) {
                     if (handled.outcome === "acknowledged") {
                         replaySafety.markBarrier("stateful-interaction");
                     }
-                    session.stream.write(handled.reply);
+                    if (handled.reply) {
+                        await writeWithBackpressure(session.stream, handled.reply, `interaction reply id=${handled.id}`);
+                    }
                     trace(`interaction_query: replied id=${handled.id} variant=${handled.variantName} ` +
-                        `field=${handled.variantField} outcome=${handled.outcome}`);
+                        `field=${handled.variantField} outcome=${handled.outcome}` +
+                        (handled.reply ? "" : " (deferred to host tool result)"));
+                    if (handled.generateImage) {
+                        trace(`interaction_query: approved generate_image target=` +
+                            `${JSON.stringify(handled.generateImage.filePath || "(unspecified)")} ` +
+                            `refs=${handled.generateImage.referenceImagePaths.length} ` +
+                            `cursorToolCallId=${handled.generateImage.toolCallId || "(none)"}`);
+                    }
                 }
-                catch {
+                catch (error) {
+                    rethrowTransportWriteFailure(error);
                     failRunProtocol("Cursor interaction reply failed", RUN_REPLY_FAILED);
                 }
+                if (handled.outcome === "bridged" && handled.askQuestion) {
+                    // Cursor raised AskQuestion; OpenCode owns the tool loop, so the prompt
+                    // leaves as a `question` tool call and this doStream ends. The Run stays
+                    // open on the pending entry, and the answer is written back on the next
+                    // continuation (InteractionResponse when Cursor is blocking on it,
+                    // ConversationAction when it was already acknowledged with `async`).
+                    const ask = handled.askQuestion;
+                    const execId = session.nextBridgedExecId++;
+                    sessionManager.registerPending(execId, session, ASK_QUESTION_RESULT_FIELD, "question", false, {
+                        interactionId: handled.id,
+                        askQuestionArgs: ask.args,
+                        askQuestionRawArgs: ask.rawArgs,
+                        askQuestionToolCallId: ask.toolCallId,
+                    });
+                    const toolCallId = `cursor_${session.sessionId}_${execId}`;
+                    const input = JSON.stringify(askQuestionToolInput(ask.args));
+                    trace(`interaction_query: BRIDGED ask_question id=${handled.id} toolCallId=${toolCallId} ` +
+                        `questions=${ask.args.questions.length} runAsync=${ask.args.runAsync} ` +
+                        `cursorToolCallId=${ask.toolCallId || "(none)"}`);
+                    closeOpenSpans();
+                    safeEnqueue({
+                        type: "tool-call",
+                        toolCallId,
+                        toolName: "question",
+                        input,
+                    });
+                    emitFinish(undefined, { unified: "tool-calls", raw: undefined });
+                    return;
+                }
+                if (handled.outcome === "approved" && handled.switchMode) {
+                    // Entering plan mode without a host plan tool: Cursor was already
+                    // released with approved{} above, and the behavioural contract travels
+                    // as the <system_reminder> injected on subsequent Runs. Nothing is
+                    // pending, so keep pumping this Run rather than ending doStream.
+                    const sw = handled.switchMode;
+                    setActiveCursorMode(session.openCodeSessionId, sw.args.targetModeId, {
+                        bridgedPlanEntered: false,
+                    });
+                    trace(`interaction_query: APPROVED switch_mode id=${handled.id} ` +
+                        `target=${JSON.stringify(sw.args.targetModeId)} (no host plan tool; ` +
+                        `provider-owned mode) cursorToolCallId=${sw.toolCallId || "(none)"}`);
+                    continue;
+                }
+                if (handled.outcome === "bridged" && handled.switchMode) {
+                    // Cursor raised SwitchMode; the host owns the outcome, so the switch
+                    // leaves as a tool call (native plan_enter / plan_exit, or the emulated
+                    // `question` approval prompt) and this doStream ends. The Run stays open
+                    // on the pending entry; approved/rejected is written back on the next
+                    // continuation while Cursor is still blocking on the query.
+                    const sw = handled.switchMode;
+                    const bridgeKind = sw.bridge.kind;
+                    const toolName = sw.toolName ?? "plan_exit";
+                    const execId = session.nextBridgedExecId++;
+                    sessionManager.registerPending(execId, session, SWITCH_MODE_RESULT_FIELD, toolName, false, {
+                        interactionId: handled.id,
+                        switchModeTarget: sw.args.targetModeId,
+                        switchModeToolCallId: sw.toolCallId,
+                        switchModeBridgeKind: bridgeKind,
+                    });
+                    const toolCallId = `cursor_${session.sessionId}_${execId}`;
+                    const input = JSON.stringify(sw.bridge.kind === "question" ? sw.bridge.input : switchModeToolInput());
+                    trace(`interaction_query: BRIDGED switch_mode id=${handled.id} toolCallId=${toolCallId} ` +
+                        `bridge=${bridgeKind} hostTool=${toolName} ` +
+                        `target=${JSON.stringify(sw.args.targetModeId)} ` +
+                        `cursorToolCallId=${sw.toolCallId || "(none)"}`);
+                    closeOpenSpans();
+                    safeEnqueue({
+                        type: "tool-call",
+                        toolCallId,
+                        toolName,
+                        input,
+                    });
+                    emitFinish(undefined, { unified: "tool-calls", raw: undefined });
+                    return;
+                }
+                if (handled.outcome === "bridged" && handled.createPlan) {
+                    // Either a host plan-stage tool (writes the plan and runs its own
+                    // approval UI) or the emulated prompt after the provider already wrote
+                    // the plan. Both hold Cursor's query open until the user decides.
+                    const plan = handled.createPlan;
+                    const staged = plan.bridge.kind === "stage" ? createPlanStageInput(plan.args) : undefined;
+                    const planUri = staged?.plan_uri ?? plan.planUri ?? "";
+                    const input = staged ?? plan.questionInput ?? {};
+                    const stageExecId = session.nextBridgedExecId++;
+                    sessionManager.registerPending(stageExecId, session, CREATE_PLAN_RESULT_FIELD, plan.toolName, false, {
+                        interactionId: handled.id,
+                        createPlanToolCallId: plan.toolCallId,
+                        createPlanBridgeKind: plan.bridge.kind,
+                        // The host echoes the prompt verbatim; it anchors the answer parse.
+                        createPlanQuestion: plan.questionInput?.questions[0]?.question ?? "",
+                        planUri,
+                        // Absolute path for the post-Yes OpenCode kickoff (plan_exit shape).
+                        ...(typeof plan.planPath === "string" && plan.planPath.trim()
+                            ? { planPath: plan.planPath.trim() }
+                            : {}),
+                        workspaceRoot: workspaceRootFromRequestContext(session.requestContext),
+                    });
+                    const stageToolCallId = `cursor_${session.sessionId}_${stageExecId}`;
+                    trace(`interaction_query: BRIDGED create_plan id=${handled.id} bridge=${plan.bridge.kind} ` +
+                        `hostTool=${plan.toolName} stageToolCallId=${stageToolCallId} ` +
+                        `planUri=${planUri || "(none)"} cursorToolCallId=${plan.toolCallId || "(none)"}`);
+                    // Cursor sends the plan body through the interaction query, not the
+                    // text stream, so nothing has shown it yet. Put it in the transcript
+                    // before asking — approving a plan you cannot read is not approval.
+                    if (plan.planReview)
+                        emitText(plan.planReview);
+                    closeOpenSpans();
+                    safeEnqueue({
+                        type: "tool-call",
+                        toolCallId: stageToolCallId,
+                        toolName: plan.toolName,
+                        input: JSON.stringify(input),
+                    });
+                    emitFinish(undefined, { unified: "tool-calls", raw: undefined });
+                    return;
+                }
             }
             else if (kv) {
                 // KV blob channel: ack set_blob / answer get_blob, then keep pumping.
@@ -1646,12 +2409,14 @@ export async function pump(session, controller, ids, abortSignal) {
                 const handled = handleKvServerMessage(kv, session);
                 if (handled) {
                     try {
-                        session.stream.write(handled.reply);
+                        await writeWithBackpressure(session.stream, handled.reply, `KV ${handled.kind}_blob reply id=${handled.id}`);
                         trace(`kv replied: kind=${handled.kind} id=${handled.id} blobId=${handled.blobIdHex.slice(0, 16)}… ` +
                             `found=${handled.found} echoed=${!!handled.echoed} ` +
+                            `replyBytes=${handled.reply.length} replyBlobBytes=${handled.replyBlobBytes} ` +
                             `sessionBlobs=${session.blobs.size} convBlobs=${conversationBlobCount(session.conversationId)}`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor KV reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1661,7 +2426,7 @@ export async function pump(session, controller, ids, abortSignal) {
             }
         }
         catch (e) {
-            if (e instanceof CursorProtocolError)
+            if (e instanceof CursorProviderError)
                 throw e;
             if (requiredChannel) {
                 failRunProtocol(`Cursor ${requiredChannel} request could not be handled`, RUN_REQUEST_UNSUPPORTED);
@@ -1783,16 +2548,26 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     const instructions = [];
     const subagents = extractHostSubagentCatalog(tools);
     if (names.has("question")) {
-        instructions.push("- When user input is required, call the OpenCode `question` tool; do not use Cursor's native AskQuestion interaction.");
-    }
+        // Cursor-native AskQuestion is translated into this tool (see
+        // protocol/ask-question.ts), so both routes reach the user. Saying so stops
+        // the model from treating a question as impossible when it reaches for its
+        // native interaction first.
+        instructions.push("- When user input is required, call the OpenCode `question` tool. Cursor-native AskQuestion requests are also accepted and answered through it.");
+    }
+    // CreatePlan is a Cursor InteractionQuery (#7), not an OpenCode/MCP catalog
+    // tool. Always say so when we advertise any tools — otherwise the model sees
+    // CreatePlan in Cursor's function definitions, notices it is absent from the
+    // OpenCode list, and narrates "No CreatePlan MCP tool is available" even
+    // though the provider bridges the native interaction.
+    instructions.push("- Cursor-native CreatePlan is accepted as a Cursor interaction (not an OpenCode or MCP catalog tool). Raise it normally; the provider writes the plan under the host's calculated plans directory and handles execution approval. Do not narrate that CreatePlan is missing, unavailable, or not an MCP tool.");
     if (names.has("plan_enter")) {
-        instructions.push("- To enter plan mode, call the OpenCode `plan_enter` tool; do not use Cursor's native SwitchMode or CreatePlan interactions.");
+        instructions.push("- To enter plan mode, call the OpenCode `plan_enter` tool. Cursor-native SwitchMode requests for plan/spec are also accepted and answered through it.");
     }
     else if (names.has("todowrite")) {
-        instructions.push("- For planning, call the OpenCode `todowrite` tool and explain the plan in normal text; do not use Cursor's native SwitchMode or CreatePlan interactions.");
+        instructions.push("- For planning task lists, call the OpenCode `todowrite` tool and/or write the plan as normal markdown.");
     }
     if (names.has("plan_exit")) {
-        instructions.push("- To leave plan mode, call the OpenCode `plan_exit` tool.");
+        instructions.push("- To leave plan mode, call the OpenCode `plan_exit` tool. Cursor-native SwitchMode for any non-plan target (agent, build, chat, debug, edit, background, multitask, triage, project, …) is also accepted and answered through it; the provider then injects the Cursor CLI-shaped mode reminder for that target.");
     }
     if (names.has(CUSTOM_WEBSEARCH_TOOL)) {
         instructions.push(`- For web searches, call \`${CUSTOM_WEBSEARCH_TOOL}\`; do not use Cursor's native WebSearch interaction.`);
@@ -1806,8 +2581,8 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.has(CUSTOM_READ_MCP_RESOURCE_TOOL)) {
         instructions.push(`- To read an MCP resource, call \`${CUSTOM_READ_MCP_RESOURCE_TOOL}\`; do not use Cursor's native resource-reading interaction.`);
     }
-    if (names.has("task") || names.has("actor")) {
-        const target = names.has("actor") ? "`actor`" : "`task`";
+    if (names.has("task")) {
+        const target = "`task`";
         const available = subagents.agents.map((agent) => `\`${agent.name}\``).join(", ");
         instructions.push(`- Native Cursor Task/subagent requests are executed through OpenCode ${target}. ` +
             "Advertised custom subagent names are used exactly; otherwise `unspecified` and `generalPurpose` select host `general`, " +
@@ -1835,8 +2610,8 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
         `OpenCode exposes exactly these executable tools for this turn: ${[...names].map((name) => `\`${name}\``).join(", ")}.`,
         `Workspace root: ${JSON.stringify(workspaceRoot)}. Resolve workspace paths against exactly this root; never invent an absolute prefix, and verify uncertain paths with an available tool before using them.`,
         subagents.executor
-            ? "Call only tools in that exact list. Cursor-native Task/subagent requests are permitted because a compatible host executor is listed; other unlisted Cursor-native tools remain unavailable."
-            : "Call only tools in that exact list. Cursor-native tools that are not listed—including Task/subagents—are unavailable; do not invoke them. If a capability is absent, complete the work directly with the listed tools or explain the limitation.",
+            ? "Call only tools in that exact list for ordinary host execution. Cursor-native Task/subagent requests are permitted because a compatible host executor is listed. Bridged Cursor interactions named below (AskQuestion, SwitchMode, CreatePlan, …) are not OpenCode/MCP catalog tools — raise them normally and do not narrate that they are missing."
+            : "Call only tools in that exact list for ordinary host execution. Bridged Cursor interactions named below (AskQuestion, SwitchMode, CreatePlan, …) are not OpenCode/MCP catalog tools — raise them normally and do not narrate that they are missing. Other unlisted Cursor-native tools are not bridged; complete the work with the listed tools or explain the limitation without claiming a missing MCP tool.",
         ...(instructions.length > 0
             ? ["Use these OpenCode tools instead of equivalent Cursor-native UI interactions:"]
             : []),
@@ -1850,25 +2625,19 @@ export function estimateTokens(chars) {
         return 0;
     return Math.ceil(chars / 4);
 }
-/** Estimate current-request prompt tokens from the complete serialized V3 prompt. */
-export function estimatePromptTokens(prompt) {
-    const serializedContent = prompt
-        .map((message) => typeof message.content === "string"
-        ? message.content
-        : (JSON.stringify(message.content) ?? ""))
-        .join("\n");
-    return estimateTokens(serializedContent.length);
-}
-/** Preserve exact Cursor counters as diagnostics when they are cumulative across a multi-step Run. */
-export function cursorTurnEndedProviderMetadata(te) {
+/** Preserve exact request-local Cursor counters as diagnostics. */
+export function cursorTurnEndedProviderMetadata(te, tokenDetails, contextSource) {
     return {
         cursor: {
-            usageVersion: 2,
+            usageVersion: 3,
             inputTokensRaw: turnEndedCounter(te, "input_tokens"),
             outputTokensRaw: turnEndedCounter(te, "output_tokens"),
             cacheReadRaw: turnEndedCounter(te, "cache_read"),
             cacheWriteRaw: turnEndedCounter(te, "cache_write"),
             reasoningTokensRaw: turnEndedCounter(te, "reasoning_tokens"),
+            ...(tokenDetails
+                ? { context: cursorContextUsageMetadata(tokenDetails, contextSource) }
+                : {}),
         },
     };
 }
@@ -2025,18 +2794,43 @@ export function spanEndParts(opts) {
 export function computeAllowTools(toolCount, toolChoice) {
     return toolCount > 0 && toolChoice?.type !== "none";
 }
-export function resolveTurnToolState(input) {
+export async function resolveTurnToolState(input) {
     const { sessionKey, incomingTools, isCompaction } = input;
     if (sessionKey && incomingTools.length > 0) {
         rememberToolCatalog(sessionKey, incomingTools.map((tool) => ({ ...tool })));
     }
-    const cached = sessionKey ? toolCatalogBySession.get(sessionKey) : undefined;
-    if (sessionKey && cached && incomingTools.length === 0) {
-        rememberToolCatalog(sessionKey, cached);
+    // Advertisement and permission are deliberately independent.
+    //
+    // Advertisement must stay byte-stable across every Run of a conversation or
+    // the RequestContext changes shape and Cursor's prompt cache goes cold. A
+    // zero-tool call is never a smaller catalog — it is a lifecycle turn
+    // (compaction, title generation, summarization) that OpenCode opens alongside
+    // the real one — so it re-advertises the last real catalog rather than
+    // collapsing the context to tools=0. A genuinely restricted turn still sends
+    // a non-empty set and is advertised verbatim.
+    //
+    // On cold start the lifecycle Run may arrive before any catalog exists. For a
+    // valid session key, wait until a sibling doStream publishes the first real
+    // catalog; cancellation is the only escape. Never time out to tools=[] and
+    // never invent or filter the enabled set.
+    //
+    // Permission is computed from what actually arrived, so those lifecycle turns
+    // still refuse execution and cannot duplicate the real turn's side effects.
+    let advertisedTools;
+    if (incomingTools.length > 0) {
+        advertisedTools = incomingTools;
+    }
+    else if (sessionKey) {
+        const cached = toolCatalogBySession.get(sessionKey)
+            ?? await waitForSiblingToolCatalog(sessionKey, input.abortSignal);
+        advertisedTools = cached.map((tool) => ({ ...tool }));
+    }
+    else {
+        // Without a session key there is no safe sibling-correlation key. Preserve
+        // the host's literal no-tool call rather than borrowing another session's
+        // catalog.
+        advertisedTools = [];
     }
-    const advertisedTools = isCompaction && incomingTools.length === 0
-        ? (cached?.map((tool) => ({ ...tool })) ?? [])
-        : incomingTools;
     return {
         advertisedTools,
         allowTools: !isCompaction && computeAllowTools(incomingTools.length, input.toolChoice),
@@ -2055,6 +2849,11 @@ export function resolveTurnConversationReset(input) {
     return { reset: false };
 }
 export function resetTurnStateForTests() {
+    for (const waiters of toolCatalogWaitersBySession.values()) {
+        for (const waiter of waiters)
+            waiter.cancel();
+    }
+    toolCatalogWaitersBySession.clear();
     toolCatalogBySession.clear();
     postCompactionRebaseBySession.clear();
 }
@@ -2081,6 +2880,7 @@ function foldStreamParts(parts) {
     let reasoning = "";
     const content = [];
     let finishReason = { unified: "stop", raw: undefined };
+    let providerMetadata;
     let usage = {
         inputTokens: { total: undefined, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
         outputTokens: { total: undefined, text: undefined, reasoning: undefined },
@@ -2101,11 +2901,18 @@ function foldStreamParts(parts) {
         else if (part.type === "finish") {
             finishReason = part.finishReason;
             usage = part.usage;
+            providerMetadata = part.providerMetadata;
         }
     }
     if (reasoning)
         content.unshift({ type: "reasoning", text: reasoning });
     if (text)
         content.unshift({ type: "text", text });
-    return { content, finishReason, usage, warnings: [] };
+    return {
+        content,
+        finishReason,
+        usage,
+        warnings: [],
+        ...(providerMetadata ? { providerMetadata } : {}),
+    };
 }