cursor-opencode-provider 0.5.0 → 0.6.1

package/dist/language-model.js

@@ -6,11 +6,18 @@ import { trace, traceRequestContextPaths } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.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, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, } from "./protocol/tools.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 { 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";
@@ -22,7 +29,7 @@ import { CursorAuthError, CursorLocalCancellationError, CursorProtocolError, Cur
 import { readCache, cacheFilePath, resolveVariantParameters, paramsImplyMaxMode, extractCursorVariantParameters, resolveCursorWireModelId } from "./models.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";
@@ -243,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, structuredClone(tools));
+    publishToolCatalogWaiters(sessionKey, tools);
     while (toolCatalogBySession.size > MAX_TURN_STATE_SESSIONS) {
         const oldest = toolCatalogBySession.keys().next().value;
         if (!oldest)
@@ -422,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;
@@ -524,11 +600,12 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     // 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);
@@ -548,12 +625,18 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     // 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 lifecycle = !allowTools && !isCompaction && !recovery;
     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));
+        : bindConversationId(sessionKey, {
+            reset: resetState.reset || recovery?.kind === "rebase",
+            ephemeral: lifecycle,
+        });
+    let conversationState = lifecycle
+        ? undefined
+        : resuming
+            ? resumeRecovery.checkpoint
+            : (bound.reset ? undefined : getCheckpoint(bound.conversationId));
     let checkpointGraph = conversationState
         ? inspectConversationBlobGraph(bound.conversationId, conversationState)
         : { count: 0, bytes: 0, complete: true };
@@ -606,9 +689,25 @@ 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 startedWithCheckpoint = !!conversationState;
+    const modeReminder = isCompaction || startedWithCheckpoint || lifecycle
+        ? undefined
+        : takeActiveCursorModeReminder(sessionKey, {
+            advertisedTools: cursorTools.map((tool) => tool.name),
+        });
+    const kickoffWarning = isCompaction || startedWithCheckpoint || lifecycle
+        ? 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"),
@@ -806,7 +905,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
             displayToolCalls: 0,
             execRequests: 0,
         },
-        openCodeSessionId: sessionKey,
+        openCodeSessionId: lifecycle ? undefined : sessionKey,
         postCompactionRebase: isCompaction,
         toolCatalog: snapshotToolCatalog(sessionKey),
         stream,
@@ -886,6 +985,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
@@ -912,7 +1129,44 @@ 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"
@@ -939,6 +1193,55 @@ export function deliverContinuationResults(session, trailingToolResults) {
                         }
                     }
                 }
+                // 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,
@@ -970,7 +1273,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;
@@ -1315,10 +1625,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;
@@ -1811,6 +2120,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
@@ -1877,11 +2243,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);
@@ -1891,14 +2271,139 @@ export async function pump(session, controller, ids, abortSignal) {
                     if (handled.outcome === "acknowledged") {
                         replaySafety.markBarrier("stateful-interaction");
                     }
-                    await writeWithBackpressure(session.stream, handled.reply, `interaction reply id=${handled.id}`);
+                    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 (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.
@@ -2050,16 +2555,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.`);
@@ -2073,8 +2588,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`, " +
@@ -2102,8 +2617,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:"]
             : []),
@@ -2282,22 +2797,50 @@ export function spanEndParts(opts) {
         out.push({ type: "text-end", id: opts.textId });
     return out;
 }
+function toolsInFixedOrder(tools) {
+    return tools.map((tool) => ({ ...tool })).sort((left, right) => (left.name ?? "").localeCompare(right.name ?? ""));
+}
 /** Exported for tests — false for compaction/summary (no tools) and toolChoice none. */
 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 })));
+        rememberToolCatalog(sessionKey, toolsInFixedOrder(incomingTools));
+    }
+    // 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 = toolsInFixedOrder(incomingTools);
+    }
+    else if (sessionKey) {
+        const cached = toolCatalogBySession.get(sessionKey)
+            ?? await waitForSiblingToolCatalog(sessionKey, input.abortSignal);
+        advertisedTools = toolsInFixedOrder(cached);
+    }
+    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 cached = sessionKey ? toolCatalogBySession.get(sessionKey) : undefined;
-    if (sessionKey && cached && incomingTools.length === 0) {
-        rememberToolCatalog(sessionKey, cached);
-    }
-    const advertisedTools = isCompaction && incomingTools.length === 0
-        ? (cached?.map((tool) => ({ ...tool })) ?? [])
-        : incomingTools;
     return {
         advertisedTools,
         allowTools: !isCompaction && computeAllowTools(incomingTools.length, input.toolChoice),
@@ -2316,6 +2859,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();
 }