cursor-opencode-provider 0.6.7 → 0.7.0

package/dist/language-model.js

@@ -6,18 +6,19 @@ 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, buildUnsupportedExecDeny, 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 { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, buildUnsupportedExecDeny, classifyMissingReadTarget, isUriReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildListMcpResourcesFallback, buildReadMcpResourceFallback, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, preferCorrelatedTaskDescription, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, buildCompleteEditReadMessages, rejectPartialReadMutation, binaryWritePayload, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, hostToolDialectFromTools, opencodePathArg, } from "./protocol/tools.js";
 import { buildGitDiffExecMessages } from "./protocol/git-diff.js";
 import { cursorExecVariantByRequestField, describeCursorExecVariant } from "./protocol/exec-variants.js";
 import { appendWorkspaceRootGrounding } from "./protocol/workspace-grounding.js";
 import { progressOnlyContinuationPrompt, shouldContinueProgressOnlyTurn, } from "./protocol/progress-continuation.js";
-import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, } from "./protocol/tool-call-bridge.js";
+import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, snapshotMirroredTodos, snapshotMirroredTodosFromReadOutput, } from "./protocol/tool-call-bridge.js";
 import { handleKvServerMessage } from "./protocol/kv.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 { flushHostAgentModeSwitch, queueHostAgentModeSwitch, } from "./host-agent-mode.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";
@@ -34,7 +35,7 @@ import { getOrBuildRequestContext } from "./context/frozen.js";
 import { workspaceRootFromRequestContext } from "./context/env.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 { CURSOR_API_HOST, CURSOR_COMPACTION_OPTION, CURSOR_HOST_AGENT_OPTION, } from "./shared.js";
 import { isCompactionSession } from "./compaction-marker.js";
 import { getSessionDirectory } from "./session-directory.js";
 import { assertCursorUserImageSupport, extractCursorPromptImages } from "./image-input.js";
@@ -57,6 +58,7 @@ const sentHistoryImageHashesBySession = new Map();
 // suppresses OpenCode's compacted prompt/system seed and makes Cursor narrate
 // tool use instead of emitting exec requests. Rebase once on the next turn.
 const postCompactionRebaseBySession = new Set();
+const promptIdentityBySession = new Map();
 export const MAX_TURN_STATE_SESSIONS = 256;
 const MAX_SENT_HISTORY_IMAGES_PER_SESSION = 256;
 const DEFAULT_RETRY_POLICY = {
@@ -326,6 +328,43 @@ function snapshotToolCatalog(sessionKey) {
         return [];
     return structuredClone(toolCatalogBySession.get(sessionKey) ?? []);
 }
+// Last known full host todo list per OpenCode session. Run-local
+// `session.mirroredTodos` dies with the Run (turn_ended closes the session),
+// but merges in later turns still need a base — same shape of problem as the
+// tool catalog above, same solution. In-memory only: never enters the prompt,
+// RequestContext, or persisted restart state, so the cache prefix is untouched.
+// Refreshed on every todo write/read we observe; replaced wholesale, never
+// merged, so it tracks host truth instead of accumulating guesses.
+const mirroredTodosBySession = new Map();
+/** Record the authoritative host todo list for an OpenCode session. */
+export function rememberMirroredTodos(sessionKey, todos) {
+    if (!sessionKey)
+        return;
+    mirroredTodosBySession.delete(sessionKey);
+    mirroredTodosBySession.set(sessionKey, todos.map((t) => ({ ...t })));
+    while (mirroredTodosBySession.size > MAX_TURN_STATE_SESSIONS) {
+        const oldest = mirroredTodosBySession.keys().next().value;
+        if (!oldest)
+            break;
+        mirroredTodosBySession.delete(oldest);
+    }
+}
+/** Copy of the last known host todo list for an OpenCode session, if any. */
+export function snapshotMirroredTodosBySession(sessionKey) {
+    if (!sessionKey)
+        return undefined;
+    const todos = mirroredTodosBySession.get(sessionKey);
+    return todos ? todos.map((t) => ({ ...t })) : undefined;
+}
+/**
+ * Store a bridged/observed full todo snapshot on both the live Run session
+ * (for merges later this turn) and the per-OpenCode-session copy (for merges
+ * in later turns and across checkpoint resumes).
+ */
+function storeMirroredTodos(session, todos) {
+    session.mirroredTodos = todos.map((t) => ({ ...t }));
+    rememberMirroredTodos(session.openCodeSessionId, session.mirroredTodos);
+}
 function rememberPostCompactionRebase(sessionKey) {
     postCompactionRebaseBySession.delete(sessionKey);
     postCompactionRebaseBySession.add(sessionKey);
@@ -336,6 +375,35 @@ function rememberPostCompactionRebase(sessionKey) {
         postCompactionRebaseBySession.delete(oldest);
     }
 }
+function normalizePromptIdentity(value) {
+    const hostAgent = value.hostAgent?.trim();
+    const systemPromptHash = value.systemPromptHash?.trim();
+    return {
+        ...(hostAgent ? { hostAgent } : {}),
+        ...(systemPromptHash ? { systemPromptHash } : {}),
+    };
+}
+function rememberPromptIdentity(sessionKey, value) {
+    const normalized = normalizePromptIdentity(value);
+    if (!normalized.hostAgent && !normalized.systemPromptHash)
+        return;
+    promptIdentityBySession.delete(sessionKey);
+    promptIdentityBySession.set(sessionKey, normalized);
+    while (promptIdentityBySession.size > MAX_TURN_STATE_SESSIONS) {
+        const oldest = promptIdentityBySession.keys().next().value;
+        if (!oldest)
+            break;
+        promptIdentityBySession.delete(oldest);
+    }
+}
+function promptIdentityChanged(previous, current) {
+    // Compare only facts the current host supplied. This keeps standalone calls
+    // and older compatibility surfaces from invalidating a valid checkpoint just
+    // because they cannot expose an agent id.
+    return ((current.hostAgent !== undefined && previous.hostAgent !== current.hostAgent)
+        || (current.systemPromptHash !== undefined
+            && previous.systemPromptHash !== current.systemPromptHash));
+}
 function sentHistoryImageHashes(sessionKey) {
     if (!sessionKey)
         return undefined;
@@ -501,6 +569,12 @@ async function doStreamImpl(modelId, options, callOptions) {
                             setActiveCursorMode(activeSession.openCodeSessionId, "plan");
                         }
                     }
+                    await flushHostAgentModeSwitch(activeSession.openCodeSessionId, {
+                        cursorSessionID: activeSession.sessionId,
+                        terminal: activeSession.closed,
+                        pumpActive: activeSession.pumpActive || activeSession.pumpOwner != null,
+                        pendingExecs: activeSession.pending.size,
+                    });
                 }
                 catch (e) {
                     activeSession.pumpActive = false;
@@ -573,6 +647,8 @@ export async function pumpWithRecovery(input) {
             if (recovery.kind === "resume") {
                 session.usageEstimate = { ...pumpedSession.usageEstimate };
                 session.editToolCalls = new Map(pumpedSession.editToolCalls);
+                // mirroredTodos rides along via rememberMirroredTodos (per-OpenCode-
+                // session, seeded in startSession) — no handoff needed here.
             }
             input.onSession?.(session);
         }
@@ -654,13 +730,25 @@ async function startSession(modelId, token, callOptions, options, startOptions)
             rememberPostCompactionRebase(sessionKey);
         if (restored?.toolCatalog.length)
             restoreTurnToolCatalog(sessionKey, restored.toolCatalog);
+        if (restored?.hostAgent || restored?.systemPromptHash) {
+            rememberPromptIdentity(sessionKey, {
+                ...(restored.hostAgent ? { hostAgent: restored.hostAgent } : {}),
+                ...(restored.systemPromptHash ? { systemPromptHash: restored.systemPromptHash } : {}),
+            });
+        }
     }
     const providerOptions = callOptions.providerOptions?.cursor;
+    const hostAgent = typeof providerOptions?.[CURSOR_HOST_AGENT_OPTION] === "string"
+        ? String(providerOptions[CURSOR_HOST_AGENT_OPTION]).trim() || undefined
+        : undefined;
     // 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.
+    // OpenCode 2.0 removed that hook, so its plugin writes the same request-local
+    // option from session hooks. The session marker is a fallback only when a
+    // host does not preserve mutable options; explicit false prevents concurrent
+    // title/generate calls from inheriting a compaction marker.
     // Do not infer this from tools/toolChoice: standalone no-tool calls are valid.
-    const isCompaction = providerOptions?.[CURSOR_COMPACTION_OPTION] === true || isCompactionSession(sessionKey);
+    const compactionOption = providerOptions?.[CURSOR_COMPACTION_OPTION];
+    const isCompaction = compactionOption === true || (compactionOption === undefined && isCompactionSession(sessionKey));
     const toolState = await resolveTurnToolState({
         sessionKey,
         incomingTools,
@@ -679,14 +767,31 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     }
     const allowTools = toolState.allowTools;
     const discoveredSubagentCatalog = extractHostSubagentCatalog(cursorTools);
-    const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
     let recovery = startOptions?.recovery;
     let resumeRecovery = recovery?.kind === "resume" ? recovery : undefined;
     let resuming = !!resumeRecovery;
+    const lifecycle = !allowTools && !isCompaction && !recovery;
+    // v1 sets `options.workspaceRoot` correctly per invocation (`input.directory`,
+    // one plugin instance per project). OpenCode 2.0 runs one daemon across many
+    // projects, so its static option is only a fallback for the directory recorded
+    // from `session.hook("context")`.
+    const workspaceRoot = path.resolve(getSessionDirectory(sessionKey) ?? (options.workspaceRoot || process.cwd()));
+    const baseSystemPrompt = extractSystemPrompt(prompt);
+    const interactionGuidance = buildOpenCodeInteractionGuidance(cursorTools, isCompaction, workspaceRoot);
+    const stableSystemPrompt = [baseSystemPrompt, interactionGuidance].filter(Boolean).join("\n\n");
+    const stableSystemPromptHash = stableSystemPrompt
+        ? createHash("sha256").update(stableSystemPrompt).digest("hex")
+        : undefined;
+    const resetState = resolveTurnConversationReset({
+        sessionKey,
+        isCompaction,
+        ...(lifecycle
+            ? {}
+            : { promptIdentity: { hostAgent, systemPromptHash: stableSystemPromptHash } }),
+    });
     // 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, {
@@ -742,18 +847,13 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const userText = recovery?.kind === "rebase"
         ? "Continue the interrupted turn from the conversation history above. Do not repeat completed work."
         : (extractUserText(lastUser) || ".");
-    // v1 sets `options.workspaceRoot` correctly per invocation (`input.directory`,
-    // one plugin instance per project). OpenCode 2.0 runs one daemon across many
-    // projects, so its static `options.workspaceRoot` is only a last-resort
-    // fallback; `getSessionDirectory` carries the real per-session directory
-    // recorded from `session.hook("context")` in `plugin-opencode2.ts`.
-    const workspaceRoot = path.resolve(getSessionDirectory(sessionKey) ?? (options.workspaceRoot || process.cwd()));
-    const baseSystemPrompt = extractSystemPrompt(prompt);
-    const interactionGuidance = buildOpenCodeInteractionGuidance(cursorTools, isCompaction, workspaceRoot);
     // 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
+    const activeMode = getActiveCursorMode(sessionKey);
+    const nativePlanPromptOwnsMode = hostAgent === "plan"
+        && (activeMode === "plan" || activeMode === "spec");
+    const modeReminder = isCompaction || startedWithCheckpoint || lifecycle || nativePlanPromptOwnsMode
         ? undefined
         : takeActiveCursorModeReminder(sessionKey, {
             advertisedTools: cursorTools.map((tool) => tool.name),
@@ -944,6 +1044,9 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         stream.destroy();
         throw error;
     }
+    const hostToolDialect = hostToolDialectFromTools(tools);
+    trace(`host tool dialect: filePathKey=${hostToolDialect.filePathKey} shellTool=${hostToolDialect.shellTool} ` +
+        `tools=[${tools.map((t) => t.name).join(",")}]`);
     const session = {
         sessionId: crypto.randomUUID(),
         conversationId,
@@ -970,6 +1073,8 @@ async function startSession(modelId, token, callOptions, options, startOptions)
             execRequests: 0,
         },
         openCodeSessionId: lifecycle ? undefined : sessionKey,
+        hostAgent,
+        stableSystemPromptHash,
         postCompactionRebase: isCompaction,
         toolCatalog: snapshotToolCatalog(sessionKey),
         stream,
@@ -977,10 +1082,15 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         pending: new Map(),
         displayToolCalls: new Map(),
         editToolCalls: new Map(),
+        // Seed from the per-OpenCode-session copy: merges in this turn (and after
+        // checkpoint resumes/rebases, which rebuild the session here) expand
+        // against the last observed host list, not an empty one.
+        mirroredTodos: snapshotMirroredTodosBySession(lifecycle ? undefined : sessionKey),
         nextBridgedExecId: 900_000,
         blobs: new Map(),
         toolDescriptors,
         toolAliases: webToolAliases.aliases,
+        hostToolDialect,
         subagentCatalog,
         requestContext,
         allowTools,
@@ -1173,7 +1283,7 @@ function buildCreatePlanContinuationFrame(pending, result, sessionKey, cursorSes
         plan_uri: planUri,
     });
 }
-function buildSwitchModeContinuationFrame(pending, result, sessionKey) {
+function buildSwitchModeContinuationFrame(pending, result) {
     const metadata = pending.resultMetadata ?? {};
     const interactionId = metadata.interactionId;
     if (typeof interactionId !== "number") {
@@ -1185,16 +1295,13 @@ function buildSwitchModeContinuationFrame(pending, result, sessionKey) {
     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);
+    const target = "approved" in answer && typeof metadata.switchModeTarget === "string"
+        ? metadata.switchModeTarget.trim()
+        : "";
+    return {
+        frame: buildSwitchModeInteractionReply(interactionId, answer),
+        ...(target ? { approvedTarget: target, bridgeKind: metadata.switchModeBridgeKind } : {}),
+    };
 }
 /**
  * Deliver trailing tool results onto a live continuation session.
@@ -1222,6 +1329,7 @@ export function deliverContinuationResults(session, trailingToolResults) {
         }
         const pending = claim.pending;
         let frames = [];
+        let deliveredSwitchMode;
         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
@@ -1241,7 +1349,14 @@ export function deliverContinuationResults(session, trailingToolResults) {
             // 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)];
+                const built = buildSwitchModeContinuationFrame(pending, r);
+                frames = [built.frame];
+                if (built.approvedTarget) {
+                    deliveredSwitchMode = {
+                        target: built.approvedTarget,
+                        bridgeKind: built.bridgeKind,
+                    };
+                }
             }
             catch (error) {
                 trace(`continuation: switch_mode encode FAILED execId=${r.execId} err=${error.message}`);
@@ -1362,6 +1477,32 @@ export function deliverContinuationResults(session, trailingToolResults) {
                 continue;
             return undefined;
         }
+        if (deliveredSwitchMode) {
+            const normalized = deliveredSwitchMode.target.toLowerCase();
+            setActiveCursorMode(session.openCodeSessionId, deliveredSwitchMode.target, {
+                bridgedPlanEntered: normalized === "plan" || normalized === "spec",
+            });
+            // A question-emulated exit has no native host plan tool to perform the
+            // actual primary-agent switch. Queue only after Cursor received the
+            // approved response; a failed write must not mutate host mode.
+            if (deliveredSwitchMode.bridgeKind === "question" && session.openCodeSessionId) {
+                queueHostAgentModeSwitch({
+                    sessionID: session.openCodeSessionId,
+                    targetModeID: deliveredSwitchMode.target,
+                    cursorSessionID: session.sessionId,
+                });
+            }
+        }
+        // A host `todoread` result is the authoritative list. Refresh the mirrored
+        // snapshot (direct reads and bridged native reads alike) so later merges
+        // apply onto host truth, not a stale write.
+        if (pending.toolName === "todoread" && r.error === undefined) {
+            const snapshot = snapshotMirroredTodosFromReadOutput(r.output);
+            if (snapshot !== undefined) {
+                storeMirroredTodos(session, snapshot);
+                trace(`continuation: mirrored todoread snapshot items=${snapshot.length}`);
+            }
+        }
         session.usageEstimate.inputTokens += estimateTokens(r.output.length);
         if (pending.bridged) {
             trace(`continuation: completed bridged result execId=${r.execId} toolName=${pending.toolName ?? r.toolName} outLen=${r.output.length}`);
@@ -1633,7 +1774,7 @@ export async function pump(session, controller, ids, abortSignal) {
         const display = parseDisplayToolCall(displayCallId, stored);
         if (display?.variant !== "edit_tool_call" || display.bridgeable === false)
             return false;
-        const requestedPath = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
+        const requestedPath = opencodePathArg(parsed.args) ?? "";
         const editPath = typeof display.args.path === "string" ? display.args.path : "";
         if (!requestedPath || !editPath)
             return false;
@@ -1731,7 +1872,7 @@ export async function pump(session, controller, ids, abortSignal) {
     const rejectMissingReadTarget = (parsed) => {
         if (parsed.toolName !== "read")
             return false;
-        const requested = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
+        const requested = opencodePathArg(parsed.args) ?? "";
         if (!requested)
             return false;
         // A scheme-addressed target is the advertised host executor's to resolve,
@@ -2031,6 +2172,8 @@ export async function pump(session, controller, ids, abortSignal) {
                         requestContext: session.requestContext,
                         toolCatalog: session.toolCatalog ?? [],
                         postCompactionRebase: session.postCompactionRebase,
+                        hostAgent: session.hostAgent,
+                        systemPromptHash: session.stableSystemPromptHash,
                     }).catch((error) => {
                         trace(`conversation persistence: TurnEnded save failed ` +
                             `sessionKey=${session.openCodeSessionId}: ${String(error)}`);
@@ -2113,7 +2256,7 @@ export async function pump(session, controller, ids, abortSignal) {
                         trace(`display tool_call_completed: SKIPPED (allowTools=false) callId=${callId}`);
                     }
                     else {
-                        const display = parseDisplayToolCall(callId, toolCall);
+                        const display = parseDisplayToolCall(callId, toolCall, session.mirroredTodos);
                         const advertised = advertisedToolNamesFromDescriptors(session.toolDescriptors);
                         const bridged = display
                             ? resolveBridgedOpenCodeToolCall(display, advertised)
@@ -2134,6 +2277,13 @@ export async function pump(session, controller, ids, abortSignal) {
                                 `advertised=[${advertised.join(",")}]`);
                         }
                         else {
+                            // Snapshot only Cursor todo writes (not create_plan's synthetic
+                            // "plan" prepend) so later merge patches apply onto a real list.
+                            if (bridged.toolName === "todowrite" && bridged.variant === "update_todos_tool_call") {
+                                const snapshot = snapshotMirroredTodos(bridged.args.todos);
+                                if (snapshot !== undefined)
+                                    storeMirroredTodos(session, snapshot);
+                            }
                             const execId = session.nextBridgedExecId++;
                             sessionManager.registerPending(execId, session, "bridged", bridged.toolName, true);
                             const toolCallId = `cursor_${session.sessionId}_${execId}`;
@@ -2252,7 +2402,7 @@ export async function pump(session, controller, ids, abortSignal) {
                 else {
                     replaySafety.markBarrier("non-control-exec");
                     const displayCallId = extractExecDisplayCallId(esm);
-                    const parsed = parseExecServerMessage(esm);
+                    const parsed = parseExecServerMessage(esm, session.hostToolDialect);
                     if (parsed) {
                         const executableToolName = resolveCustomWebToolAlias(parsed.toolName, session.toolAliases);
                         if (executableToolName !== parsed.toolName) {
@@ -2260,6 +2410,20 @@ export async function pump(session, controller, ids, abortSignal) {
                             parsed.toolName = executableToolName;
                         }
                         remapNativeSubagentForCatalog(parsed, advertisedToolNameSet, session.subagentCatalog);
+                        // SubagentArgs has no description; Cursor's real title lives on the
+                        // correlated display TaskToolCall. Prefer that over the 5-word prompt slice.
+                        if (displayCallId && (parsed.toolName === "task" || parsed.toolName === "subagent")) {
+                            const stored = session.displayToolCalls.get(displayCallId);
+                            const display = parseDisplayToolCall(displayCallId, stored);
+                            if (display?.variant === "task_tool_call") {
+                                const description = typeof display.args.description === "string" ? display.args.description : undefined;
+                                preferCorrelatedTaskDescription(parsed, description);
+                                if (description?.trim()) {
+                                    trace(`exec: preferred TaskToolCall description callId=${displayCallId} ` +
+                                        `description=${JSON.stringify(description.trim())}`);
+                                }
+                            }
+                        }
                         const editCall = displayCallId
                             ? session.editToolCalls?.get(displayCallId)
                             : undefined;
@@ -2396,6 +2560,16 @@ export async function pump(session, controller, ids, abortSignal) {
                         }
                         // Keep the stream open; the result arrives on the next doStream call.
                         sessionManager.registerPending(parsed.id, session, parsed.resultField, parsed.toolName, false, parsed.resultMetadata);
+                        // A direct host `todowrite` is a replace-all snapshot: it is the new
+                        // truth for later Cursor merge patches, which otherwise apply onto a
+                        // stale (or empty) mirrored list.
+                        if (parsed.toolName === "todowrite") {
+                            const snapshot = snapshotMirroredTodos(parsed.args.todos);
+                            if (snapshot !== undefined) {
+                                storeMirroredTodos(session, snapshot);
+                                trace(`exec: mirrored todowrite snapshot items=${snapshot.length}`);
+                            }
+                        }
                         // tc.input is already a JSON string (LanguageModelV3ToolCall.input).
                         trace(`exec: EMITTED tool-call toolCallId=${tc.toolCallId} toolName=${tc.toolName} inputLen=${tc.input.length}`);
                         emittedHostTools++;
@@ -2535,9 +2709,17 @@ export async function pump(session, controller, ids, abortSignal) {
                     setActiveCursorMode(session.openCodeSessionId, sw.args.targetModeId, {
                         bridgedPlanEntered: false,
                     });
+                    const hostAgentSwitchQueued = session.openCodeSessionId
+                        ? queueHostAgentModeSwitch({
+                            sessionID: session.openCodeSessionId,
+                            targetModeID: sw.args.targetModeId,
+                            cursorSessionID: session.sessionId,
+                        })
+                        : 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)"}`);
+                        `${hostAgentSwitchQueued ? "native host-agent switch queued" : "provider-owned fallback"}) ` +
+                        `cursorToolCallId=${sw.toolCallId || "(none)"}`);
                     continue;
                 }
                 if (handled.outcome === "bridged" && handled.switchMode) {
@@ -2781,12 +2963,18 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.has("plan_enter")) {
         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 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. 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.");
     }
+    // Prefer host todos whenever advertised. Keep guidance terse — spelling out
+    // Cursor TodoWrite vs TodoRead / MCP alias collisions teaches the model to
+    // inventory catalogs instead of just calling the host tools.
+    if (names.has("todowrite") || names.has("todoread")) {
+        const write = names.has("todowrite") ? "`todowrite`" : undefined;
+        const read = names.has("todoread") ? "`todoread`" : undefined;
+        const tools = write && read ? `${write} / ${read}` : (write ?? read);
+        instructions.push(`- For task-list create/update/complete/cancel${read ? "/read" : ""}, call OpenCode ${tools}; do not use Cursor TodoWrite, and do not narrate Cursor-vs-OpenCode todo-tool differences.`);
+    }
     if (names.has(CUSTOM_WEBSEARCH_TOOL)) {
         instructions.push(`- For web searches, call \`${CUSTOM_WEBSEARCH_TOOL}\`; do not use Cursor's native WebSearch interaction.`);
     }
@@ -2799,8 +2987,14 @@ 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")) {
-        const target = "`task`";
+    if (names.has("execute")) {
+        const shell = names.has("shell") ? "`shell`" : names.has("bash") ? "`bash`" : undefined;
+        instructions.push(shell
+            ? `- OpenCode \`execute\` is Code Mode JavaScript (\`code\`); it is not a shell. For OS commands, call OpenCode ${shell}. Do not pass \`command\` to \`execute\`.`
+            : "- OpenCode `execute` is Code Mode JavaScript (`code`); it is not a shell. Do not pass `command` to `execute`.");
+    }
+    if (names.has("task") || names.has("subagent")) {
+        const target = names.has("task") ? "`task`" : "`subagent`";
         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`, " +
@@ -2828,8 +3022,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 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.",
+            ? "Call only tools in that exact OpenCode 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 OpenCode 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:"]
             : []),
@@ -3067,9 +3261,25 @@ export function resolveTurnConversationReset(input) {
             rememberPostCompactionRebase(sessionKey);
         return { reset: true, reason: "compaction" };
     }
+    let promptChange;
+    if (sessionKey && input.promptIdentity) {
+        const current = normalizePromptIdentity(input.promptIdentity);
+        const previous = promptIdentityBySession.get(sessionKey);
+        if (previous && promptIdentityChanged(previous, current)) {
+            promptChange = current.hostAgent !== undefined && previous.hostAgent !== current.hostAgent
+                ? "agent-change"
+                : "system-prompt-change";
+        }
+        rememberPromptIdentity(sessionKey, {
+            ...previous,
+            ...current,
+        });
+    }
     if (sessionKey && postCompactionRebaseBySession.delete(sessionKey)) {
         return { reset: true, reason: "post-compaction-rebase" };
     }
+    if (promptChange)
+        return { reset: true, reason: promptChange };
     return { reset: false };
 }
 export function resetTurnStateForTests() {
@@ -3080,6 +3290,8 @@ export function resetTurnStateForTests() {
     toolCatalogWaitersBySession.clear();
     toolCatalogBySession.clear();
     postCompactionRebaseBySession.clear();
+    promptIdentityBySession.clear();
+    mirroredTodosBySession.clear();
 }
 function extractUserText(lastUser) {
     if (!lastUser)

package/dist/models.d.ts

@@ -84,9 +84,20 @@ export declare function fetchModels(token: string, options?: {
     headers?: Record<string, string>;
     timeoutMs?: number;
 }): Promise<ModelInfo[]>;
-export declare function refreshModelCache(cacheDir: string, fetcher: () => Promise<ModelInfo[]>): Promise<ModelInfo[]>;
+export declare function refreshModelCache(cacheDir: string, fetcher: () => Promise<ModelInfo[]>, options?: {
+    forceAfterInflight?: boolean;
+}): Promise<ModelInfo[]>;
 export declare function discoverModels(token: string, cacheDir: string, options?: {
     baseURL?: string;
     headers?: Record<string, string>;
     timeoutMs?: number;
+    /**
+     * Bypass even a fresh cache and require an authoritative response.
+     *
+     * Model availability is account-scoped. Callers use this after a
+     * credential switch so a fresh cache produced by the previous account is
+     * never rebound to the new connection. A forced refresh rejects on fetch
+     * failure; the caller can keep the already-published inventory unchanged.
+     */
+    forceRefresh?: boolean;
 }): Promise<ModelInfo[]>;

package/dist/models.js

@@ -396,11 +396,18 @@ export async function fetchModels(token, options = {}) {
     return mapAvailableModelsResponse(raw);
 }
 const refreshesByDirectory = new Map();
-export async function refreshModelCache(cacheDir, fetcher) {
+export async function refreshModelCache(cacheDir, fetcher, options = {}) {
     const key = path.resolve(cacheDir);
     const existing = refreshesByDirectory.get(key);
-    if (existing)
-        return existing;
+    if (existing) {
+        if (!options.forceAfterInflight)
+            return existing;
+        // An account switch must not join a background refresh authenticated as
+        // the previous account. Wait for that write to finish, then run this
+        // caller's fetch so its account inventory is authoritative on disk.
+        await existing.catch(() => { });
+        return refreshModelCache(cacheDir, fetcher, options);
+    }
     const refresh = (async () => {
         const models = await fetcher();
         await writeCache(cacheDir, {
@@ -420,10 +427,11 @@ export async function refreshModelCache(cacheDir, fetcher) {
     }
 }
 export async function discoverModels(token, cacheDir, options = {}) {
+    const { forceRefresh = false, ...fetchOptions } = options;
     const cached = await readCache(cacheDir);
-    const refresh = () => refreshModelCache(cacheDir, () => fetchModels(token, options));
+    const refresh = () => refreshModelCache(cacheDir, () => fetchModels(token, fetchOptions), { forceAfterInflight: forceRefresh });
     // Cache is fresh → return it; refresh in background
-    if (cached && isCacheFresh(cached)) {
+    if (!forceRefresh && cached && isCacheFresh(cached)) {
         // Background refresh (fire and forget)
         void refresh()
             .catch(() => {
@@ -436,7 +444,9 @@ export async function discoverModels(token, cacheDir, options = {}) {
         try {
             return await refresh();
         }
-        catch {
+        catch (error) {
+            if (forceRefresh)
+                throw error;
             return cached.models;
         }
     }