cursor-opencode-provider 0.8.0 → 0.8.1

package/dist/protocol/switch-mode.js

@@ -17,18 +17,18 @@
  * through the Question service and, on "Yes", injects a synthetic user message
  * carrying `agent: "plan" | "build"`, which `createUserMessage` turns into a
  * `setAgentModel` primary-agent switch (opencode `tool/plan.ts`,
- * `session/prompt.ts`). A provider cannot reach `setAgentModel`, but the two
- * observable halves — the approval gate and the behavioural contract — are both
- * reachable, so the protocol bridge degrades instead of refusing when the host
- * tool is missing. OpenCode 2 additionally exposes `session.switchAgent`; its
+ * `session/prompt.ts`). OpenCode 2 exposes `session.switchAgent`; its
  * entrypoint installs a structural callback that selects the native `plan` or
  * `build` primary agent after the owning Cursor Run becomes terminal:
  *
  * - entering plan/spec needs no host tool at all — approve immediately and let
  *   the injected <system_reminder> carry the contract, exactly as Cursor CLI's
  *   own plan mode is prompt-enforced.
- * - leaving plan mode is the gate the user must actually see, so it falls back
- *   to the host `question` tool and only rejects when that is absent too.
+ * - leaving the host's own `plan` agent without its `plan_exit` goes through
+ *   CreatePlan, whose `question` prompt is the execution approval, so the
+ *   request is rejected with a pointer there (or, with no `question`, to the
+ *   user's agent switch); a Cursor-only plan mode has nothing on the host to
+ *   leave and is approved.
  *
  * Resolution is keyed solely on the advertised catalog under canonical
  * OpenCode tool names — never on any external identity or model id.
@@ -36,7 +36,7 @@
  * CLI reject reason for user declines: "Mode switch rejected by user"
  * (chunk-7076/dist/ui.js onSwitchModeReject).
  */
-import { parseAnswerSegments, } from "./ask-question.js";
+import { CURSOR_PLAN_STAGE_TOOL } from "./create-plan.js";
 import { decodeMessageSparse } from "./messages.js";
 /**
  * `PendingExec.resultField` for a held-open SwitchMode InteractionQuery.
@@ -59,13 +59,18 @@ export const MISSING_TARGET_REASON = "Missing targetModeId";
  * even though the next Run will succeed. CreatePlan already soft-acks the same
  * case; SwitchMode must match.
  */
-export const PLAN_EXIT_UNAVAILABLE_REASON = "Neither the OpenCode `plan_exit` tool nor the `question` tool is available to the " +
-    "current agent, so leaving plan mode cannot be approved this turn.";
-/** Upstream `PlanExitTool` wording, minus a plan path the provider cannot verify. */
-export const SWITCH_MODE_EXIT_QUESTION = "Planning is complete. Would you like to switch to the build agent and start implementing?";
-export const SWITCH_MODE_EXIT_HEADER = "Build Agent";
-const SWITCH_MODE_EXIT_YES = "Yes";
-const SWITCH_MODE_EXIT_NO = "No";
+/**
+ * The host's plan agent is active and offers no `plan_exit`: on such a host
+ * the user ends plan mode by switching agents, so the model cannot.
+ */
+export const PLAN_EXIT_BY_USER_REASON = "This host leaves plan mode when the user switches from the plan agent to the build " +
+    "agent. Ask the user to switch agents when the plan is ready; do not implement before then.";
+/**
+ * The host's plan agent is active, offers no `plan_exit`, but can ask: leaving
+ * plan mode goes through CreatePlan, whose `question` prompt is the approval.
+ */
+export const PLAN_EXIT_VIA_CREATE_PLAN_REASON = "Leave plan mode by recording the finished plan with Cursor CreatePlan: the user is then " +
+    "asked whether to switch to the build agent and start implementing. Do not implement before they approve.";
 const activeCursorModeBySession = new Map();
 const MAX_ACTIVE_CURSOR_MODES = 256;
 function asRecord(value) {
@@ -97,46 +102,14 @@ export function mapSwitchModeTarget(targetModeId) {
     }
     return { ok: true, toolName: "plan_exit" };
 }
-/** The synthetic AskQuestion item backing a question-emulated plan exit. */
-function switchModeExitQuestionItem() {
-    return {
-        id: "switch_mode_exit",
-        prompt: SWITCH_MODE_EXIT_QUESTION,
-        options: [
-            { id: "yes", label: SWITCH_MODE_EXIT_YES },
-            { id: "no", label: SWITCH_MODE_EXIT_NO },
-        ],
-        allowMultiple: false,
-    };
-}
-/** Host `question` input mirroring upstream `PlanExitTool`'s own prompt. */
-export function switchModeExitQuestionInput() {
-    return {
-        questions: [
-            {
-                question: SWITCH_MODE_EXIT_QUESTION,
-                header: SWITCH_MODE_EXIT_HEADER,
-                options: [
-                    {
-                        label: SWITCH_MODE_EXIT_YES,
-                        description: "Switch to build agent and start implementing the plan",
-                    },
-                    {
-                        label: SWITCH_MODE_EXIT_NO,
-                        description: "Stay with plan agent to continue refining the plan",
-                    },
-                ],
-            },
-        ],
-    };
-}
 /**
  * Resolve how this SwitchMode target is satisfied, keyed only on the advertised
  * catalog under canonical tool names.
  *
- * A missing plan tool is not a refusal: entering plan mode needs no host tool,
- * and leaving it degrades to the `question` prompt so the user still approves
- * before any execution starts.
+ * A missing plan tool is not a refusal: entering plan mode needs no host tool.
+ * Leaving the host's own plan agent without `plan_exit` is approved through
+ * CreatePlan (or the user's agent switch when nothing can ask), and a
+ * Cursor-only plan mode (no host plan agent) has nothing on the host to leave.
  */
 export function resolveSwitchModeBridge(targetModeId, options) {
     const mapped = mapSwitchModeTarget(targetModeId);
@@ -162,11 +135,13 @@ export function resolveSwitchModeBridge(targetModeId, options) {
     // whole contract, exactly as Cursor CLI's own plan mode is prompt-enforced.
     if (mapped.toolName === "plan_enter")
         return { kind: "approve" };
-    // Leaving plan mode starts real work, so it keeps a user-visible gate.
-    if (names.has("question")) {
-        return { kind: "question", input: switchModeExitQuestionInput() };
+    if (options.hostAgent === "plan") {
+        return {
+            kind: "reject",
+            reason: names.has("question") ? PLAN_EXIT_VIA_CREATE_PLAN_REASON : PLAN_EXIT_BY_USER_REASON,
+        };
     }
-    return { kind: "reject", reason: PLAN_EXIT_UNAVAILABLE_REASON };
+    return { kind: "approve" };
 }
 /** Decode a `switch_mode_request_query` body, or undefined when unusable. */
 export function decodeSwitchModeQuery(queryBytes) {
@@ -222,20 +197,6 @@ export function switchModeResultFromToolOutput(output, isError) {
     }
     return switchModeRejectedResult(trimmed);
 }
-/**
- * Host `question` outcome → Cursor SwitchModeRequestResponse, for the emulated
- * plan exit. Only an explicit "Yes" approves; an unanswered or dismissed prompt
- * keeps the model in plan mode rather than silently starting execution.
- */
-export function switchModeResultFromQuestionOutput(output, isError) {
-    if (isError)
-        return switchModeResultFromToolOutput(output, true);
-    const [segment] = parseAnswerSegments([switchModeExitQuestionItem()], output);
-    const answer = (segment ?? "").trim().toLowerCase();
-    if (answer === SWITCH_MODE_EXIT_YES.toLowerCase())
-        return switchModeApprovedResult();
-    return switchModeRejectedResult(USER_REJECTED_REASON);
-}
 /** Record the approved Cursor mode for later system-reminder injection. */
 export function setActiveCursorMode(sessionKey, targetModeId, options = {}) {
     if (!sessionKey)
@@ -265,13 +226,121 @@ export function isCursorPlanModeActive(sessionKey) {
     const mode = getActiveCursorMode(sessionKey);
     return mode === "plan" || mode === "spec";
 }
-/** True after a bridged plan/spec Run has observed plan_enter removed by the host. */
+/** True while Cursor plan/spec mode is one the host enforces (see `bridgedPlanEntered`). */
 export function isBridgedCursorPlanModeActive(sessionKey) {
     if (!sessionKey)
         return false;
     const state = activeCursorModeBySession.get(sessionKey);
     return (state?.modeId === "plan" || state?.modeId === "spec") && state.bridgedPlanEntered;
 }
+/**
+ * Cursor plan mode follows the host's `plan` primary agent, as Cursor CLI's
+ * mode follows its own mode switch (Shift+Tab, `/plan`).
+ *
+ * - A turn under the host plan agent puts Cursor in plan mode, however the
+ *   host got there (its agent picker, a plan_enter approval).
+ * - The host's own exit from that agent (a plan_exit approval, or an agent
+ *   switch in its UI) ends Cursor plan mode. Only an observed `plan` → other
+ *   transition counts, so Cursor-only modes (debug, ask, …) under the host's
+ *   ordinary agent are kept; the next Run then carries the agent-mode
+ *   reminder instead of a stale "plan mode is still active" one.
+ */
+export function followHostPlanAgent(sessionKey, previousHostAgent, hostAgent) {
+    if (!sessionKey || !hostAgent)
+        return undefined;
+    if (hostAgent === "plan") {
+        if (isBridgedCursorPlanModeActive(sessionKey))
+            return undefined;
+        // The host runs its own plan agent, so it enforces this plan mode.
+        setActiveCursorMode(sessionKey, "plan", { bridgedPlanEntered: true });
+        return "entered";
+    }
+    if (previousHostAgent !== "plan" || !isCursorPlanModeActive(sessionKey))
+        return undefined;
+    setActiveCursorMode(sessionKey, "agent");
+    return "left";
+}
+/**
+ * `agent.v1.AgentMode` for a Cursor mode id, as Cursor CLI derives
+ * `UserMessage.mode` from its current mode: plan, ask, and debug are their own
+ * modes; every other mode (agent, spec, triage, …) runs as agent.
+ */
+export function cursorAgentModeWireValue(modeId) {
+    switch (normalizeSwitchModeId(modeId ?? "")) {
+        case "plan":
+            return 3;
+        case "chat":
+        case "ask":
+        case "search":
+            return 2;
+        case "debug":
+            return 4;
+        default:
+            return 1;
+    }
+}
+/** Conversation that already received the host plan-exit call shape, per session. */
+const hostPlanExitNoteBySession = new Map();
+function describeToolArguments(schema) {
+    const record = asRecord(schema);
+    const properties = asRecord(record?.properties);
+    const names = properties ? Object.keys(properties) : [];
+    if (names.length === 0)
+        return "It takes no arguments: call it with `{}`.";
+    const required = new Set(Array.isArray(record?.required) ? record.required.filter((name) => typeof name === "string") : []);
+    const lines = names.map((name) => {
+        const property = asRecord(properties[name]);
+        const type = str(property?.type) || "value";
+        const description = str(property?.description).trim();
+        return `- \`${name}\` (${type}, ${required.has(name) ? "required" : "optional"})` +
+            (description ? `: ${description}` : "");
+    });
+    return `Its arguments (use exactly these names):\n${lines.join("\n")}`;
+}
+/**
+ * One-shot translation of the host plan agent's workflow into Cursor terms,
+ * delivered once per Cursor conversation while that agent owns the turn.
+ *
+ * With the host's plan file known, Cursor's native CreatePlan carries out the
+ * host instruction "write the plan file, then call plan_exit" (see the `exit`
+ * CreatePlan bridge), so the model needs no host tool at all. Without it, the
+ * model is given `plan_exit`'s exact call shape from the live schema: the
+ * RequestContext overlay is names-only, and otherwise it must look the tool up
+ * (or guess its arguments) before it can submit the plan.
+ */
+export function takeHostPlanAgentNote(sessionKey, conversationId, hostAgent, tools, options = {}) {
+    if (!sessionKey)
+        return undefined;
+    if (hostAgent !== "plan") {
+        hostPlanExitNoteBySession.delete(sessionKey);
+        return undefined;
+    }
+    const planExit = tools.find((tool) => tool.name === "plan_exit");
+    // A host plan-stage tool carries the plan to the host review itself.
+    if (tools.some((tool) => tool.name === CURSOR_PLAN_STAGE_TOOL))
+        return undefined;
+    if (!planExit || hostPlanExitNoteBySession.get(sessionKey) === conversationId)
+        return undefined;
+    hostPlanExitNoteBySession.delete(sessionKey);
+    hostPlanExitNoteBySession.set(sessionKey, conversationId);
+    while (hostPlanExitNoteBySession.size > MAX_ACTIVE_CURSOR_MODES) {
+        const oldest = hostPlanExitNoteBySession.keys().next().value;
+        if (!oldest)
+            break;
+        hostPlanExitNoteBySession.delete(oldest);
+    }
+    if (options.hostPlanFile) {
+        return wrapReminder("The host plan agent is active. When the plan is ready, record it with CreatePlan. " +
+            `CreatePlan saves it as the host's plan file (${options.hostPlanFile}) and submits it ` +
+            "to the host's plan review, which asks the user; this carries out the host " +
+            "instructions to write the plan file and call plan_exit, so do neither yourself. " +
+            "Do not implement until the user approves.");
+    }
+    return wrapReminder("The host plan agent is active. When the plan file is written and ready for review, " +
+        `submit it by calling MCP tool \`plan_exit\` on server \`${options.server ?? "opencode"}\` directly. ` +
+        "Its full definition is below, so do not look it up with GetMcpTools first. " +
+        describeToolArguments(planExit.inputSchema));
+}
 export function clearActiveCursorMode(sessionKey) {
     if (!sessionKey)
         return;
@@ -279,6 +348,7 @@ export function clearActiveCursorMode(sessionKey) {
 }
 export function resetActiveCursorModesForTests() {
     activeCursorModeBySession.clear();
+    hostPlanExitNoteBySession.clear();
 }
 function wrapReminder(body) {
     return `<system_reminder>\n${body.trim()}\n</system_reminder>`;
@@ -295,12 +365,15 @@ export function cursorModeSystemReminder(targetModeId, options = {}) {
     const first = options.firstTurn !== false;
     // A host plan-stage tool writes the artifact and its result names the
     // follow-up that requests approval. plan_exit only leaves plan mode.
-    // Without either tool, recording the plan is the gate and the provider asks
-    // whether to start implementing. Naming an unavailable tool would strand the model.
+    // Without either, CreatePlan asks through `question` whether to implement;
+    // with no `question` either, the user leaves plan mode by switching agents.
+    // Naming an unavailable tool would strand the model.
     const leavePlan = options.planStageAdvertised
         ? "record the finished plan with Cursor CreatePlan. The host stage tool waits for the host plan review and does not return until the user accepts or declines. Do not call `plan_exit` to submit or skip that review, and do not implement until the tool returns success"
         : options.planExitAdvertised === false
-            ? "record the finished plan (Cursor CreatePlan). Writing it needs no approval, and the user is then asked whether to start implementing; if they decline, refine the plan and record it again"
+            ? options.questionAdvertised
+                ? "record the finished plan with Cursor CreatePlan. Writing it needs no approval; the user is then asked whether to switch to the build agent and start implementing. If they decline, refine the plan and record it again"
+                : "record the finished plan (Cursor CreatePlan), then tell the user it is ready: they switch to the build agent to have it implemented"
             : "record the finished plan, then call OpenCode `plan_exit` so the user can approve leaving plan mode";
     if (id === "plan" || id === "spec") {
         return wrapReminder(first
@@ -413,7 +486,7 @@ export function takeActiveCursorModeReminder(sessionKey, options = {}) {
             : new Set(options.advertisedTools)
         : undefined;
     const isPlanMode = state.modeId === "plan" || state.modeId === "spec";
-    if (isPlanMode && state.bridgedPlanEntered && advertised) {
+    if (isPlanMode && state.bridgedPlanEntered && advertised && !options.hostAgent) {
         if (advertised.has("plan_enter")) {
             activeCursorModeBySession.delete(sessionKey);
             return cursorModeSystemReminder("agent", { firstTurn: true });
@@ -425,6 +498,7 @@ export function takeActiveCursorModeReminder(sessionKey, options = {}) {
             ? {
                 planExitAdvertised: advertised.has("plan_exit"),
                 planStageAdvertised: advertised.has("cursor_plan_stage"),
+                questionAdvertised: advertised.has("question"),
             }
             : {}),
     });

package/dist/protocol/token-details.d.ts

@@ -15,6 +15,8 @@ export type CursorConversationTokenDetails = {
     breakdown?: CursorPromptTokenBreakdown;
 };
 export type CursorContextUsageSource = "checkpoint-current-run" | "checkpoint-previous-turn";
+/** Cursor can update occupancy while retaining categories from an older checkpoint. */
+export declare function currentCursorTokenBreakdown(details: CursorConversationTokenDetails | undefined): CursorPromptTokenBreakdown | undefined;
 /**
  * Read field #5 (`ConversationTokenDetails`) from Cursor's opaque
  * `ConversationStateStructure` checkpoint without decoding or re-encoding the

package/dist/protocol/token-details.js

@@ -1,4 +1,13 @@
 import protobuf from "protobufjs";
+/** Cursor can update occupancy while retaining categories from an older checkpoint. */
+export function currentCursorTokenBreakdown(details) {
+    const breakdown = details?.breakdown;
+    return breakdown
+        && breakdown.totalUsedTokens === details.usedTokens
+        && breakdown.maxTokens === details.maxTokens
+        ? breakdown
+        : undefined;
+}
 const MAX_BREAKDOWN_CATEGORIES = 128;
 function requireWireType(actual, expected, field) {
     if (actual !== expected)
@@ -142,6 +151,7 @@ export function cursorContextUsageMetadata(details, source = "checkpoint-current
     const usedPercent = details.maxTokens > 0
         ? Math.max(0, Math.min(100, Math.round(details.usedTokens / details.maxTokens * 1_000) / 10))
         : undefined;
+    const breakdown = currentCursorTokenBreakdown(details);
     return {
         contextUsageVersion: 2,
         source,
@@ -150,6 +160,6 @@ export function cursorContextUsageMetadata(details, source = "checkpoint-current
         maxTokens: details.maxTokens,
         remainingTokens: Math.max(0, details.maxTokens - details.usedTokens),
         ...(usedPercent === undefined ? {} : { usedPercent }),
-        ...(details.breakdown ? { breakdown: details.breakdown } : {}),
+        ...(breakdown ? { breakdown } : {}),
     };
 }

package/dist/protocol/tool-call-bridge.d.ts

@@ -22,6 +22,10 @@ export type BridgedOpenCodeToolCall = {
 };
 /** Display variants Cursor executes itself (mcp_state + optional write spill). */
 export declare function isNativeDisplayToolCall(variant: string): boolean;
+/** Server-side dynamic-call failures may complete without a started/exec frame. */
+export declare function displayMcpToolError(toolCall: Record<string, unknown> | undefined): string | undefined;
+/** Native discovery errors are server-side results, never host execution. */
+export declare function displayNativeDiscoveryError(toolCall: Record<string, unknown> | undefined): string | undefined;
 /**
  * Normalize a full todo snapshot for `mirroredTodos` storage. Returns
  * undefined when the input is not a todo array (nothing to learn). Drops the

package/dist/protocol/tool-call-bridge.js

@@ -69,6 +69,20 @@ export function isNativeDisplayToolCall(variant) {
 function asRecord(v) {
     return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
 }
+/** Server-side dynamic-call failures may complete without a started/exec frame. */
+export function displayMcpToolError(toolCall) {
+    const call = asRecord(toolCall?.mcp_tool_call);
+    const result = asRecord(call?.result);
+    const error = asRecord(result?.error);
+    const parts = [error?.error, error?.detail].filter((value) => typeof value === "string" && value.length > 0);
+    return parts.length > 0 ? parts.join(": ") : undefined;
+}
+/** Native discovery errors are server-side results, never host execution. */
+export function displayNativeDiscoveryError(toolCall) {
+    const call = asRecord(toolCall?.get_mcp_tools_tool_call);
+    const error = asRecord(asRecord(call?.result)?.error)?.error;
+    return typeof error === "string" && error.length > 0 ? error : undefined;
+}
 function findToolVariant(toolCall) {
     for (const key of TOOL_CALL_VARIANTS) {
         if (toolCall[key] != null)

package/dist/protocol/tools.d.ts

@@ -1,3 +1,4 @@
+import type { CursorImageInput } from "../image-input.js";
 import { type CursorExecVariant } from "./exec-variants.js";
 import { type CursorShellOutcome } from "../shell-timeout.js";
 export declare const REQUEST_CONTEXT_RESULT_FIELD = 10;
@@ -8,6 +9,10 @@ export type OpencodeToolDef = {
     /** Original flattened identity when `name` is a Cursor-facing alias. */
     sourceName?: string;
 };
+/** Check explicit required keys after normalization, before host execution. */
+export declare function missingRequiredToolArguments(tool: OpencodeToolDef | undefined, args: Record<string, unknown>): string[];
+/** Canonical file/search tools must not silently ignore a misplaced shell command. */
+export declare function misplacedShellCommand(tool: OpencodeToolDef | undefined, args: Record<string, unknown>): boolean;
 /** Host file-tool argument key. OpenCode 1.x uses `filePath`; 2.0 uses `path`. */
 export type HostFilePathKey = "path" | "filePath";
 /** Host shell tool id. OpenCode 1.x uses `bash`; 2.0 uses `shell`. */
@@ -18,6 +23,7 @@ export type HostToolDialect = {
     filePathKey: HostFilePathKey;
     shellTool: HostShellTool;
     skillArgKey: HostSkillArgKey;
+    shellDescription?: "optional" | "required";
 };
 export declare const OPENCODE_1_TOOL_DIALECT: HostToolDialect;
 export declare const OPENCODE_2_TOOL_DIALECT: HostToolDialect;
@@ -280,7 +286,16 @@ export type ToolResultInput = {
      * often $HOME and would re-advertise the wrong folder to the model.
      */
     workspaceRoot?: string;
+    /** Images the host tool returned; see `execResultImages` for which results carry them. */
+    images?: readonly CursorImageInput[];
 };
+/**
+ * The leading tool-result images an exec result can carry on a held Run.
+ * Cursor's own read executor answers an image file with its bytes in
+ * `ReadSuccess.data` (#5) and no text; its MCP executor appends each MCP image
+ * as an `McpImageContent` item (#2). Other result shapes have no image field.
+ */
+export declare function execResultImages(resultField: string, images: readonly CursorImageInput[] | undefined): CursorImageInput[];
 /**
  * Build one or more ExecClientMessage frames for a tool result.
  * Shell replies are a sequence of ShellStream oneofs under the same id —
@@ -321,7 +336,7 @@ export declare function unwrapReadOutput(output: string): string;
  * OpenCode returns free-form text; we wrap it in the minimal success shape the
  * server accepts (verified against agent.v1 wire captures).
  */
-export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>, shellOutcome?: CursorShellOutcome, workspaceRoot?: string): Record<string, unknown>;
+export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>, shellOutcome?: CursorShellOutcome, workspaceRoot?: string, images?: readonly CursorImageInput[]): Record<string, unknown>;
 export declare function buildToolCallPart(execMsg: ParsedExecRequest, sessionId: string): {
     toolCallId: string;
     toolName: string;

package/dist/protocol/tools.js

@@ -9,10 +9,36 @@ import { trace, traceRequestContextPaths } from "../debug.js";
 import { cursorExecVariantByRequestName, FORCE_BACKGROUND_STATUS_ERROR, } from "./exec-variants.js";
 import { APPLY_PATCH_TOOL, buildAddFilePatch, buildUpdateFilePatch, planSubstringEdit, } from "./apply-patch.js";
 import { BACKGROUND_SHELL_MARKER, buildBackgroundShellCommand, } from "../shell-timeout.js";
+import { normalizeOpencodeQuestionArgs } from "./ask-question.js";
+import { normalizeOpencodeTodoArgs } from "../todo-store.js";
 // Exec variant field number whose reply is the server-initiated request_context
 // probe (ExecServerMessage #10 → ExecClientMessage #10). request/result share a
 // field number for every exec variant, so this is also the result field.
 export const REQUEST_CONTEXT_RESULT_FIELD = 10;
+/** Check explicit required keys after normalization, before host execution. */
+export function missingRequiredToolArguments(tool, args) {
+    const schema = tool?.inputSchema;
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return [];
+    const required = schema.required;
+    if (!Array.isArray(required))
+        return [];
+    return required.filter((key) => typeof key === "string" && (!Object.hasOwn(args, key) || args[key] === undefined));
+}
+/** Canonical file/search tools must not silently ignore a misplaced shell command. */
+export function misplacedShellCommand(tool, args) {
+    if (!tool || args.command === undefined)
+        return false;
+    if (!["read", "write", "edit", "grep", "glob", "ls"].includes(tool.name))
+        return false;
+    const schema = tool.inputSchema;
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return false;
+    const properties = schema.properties;
+    if (!properties || typeof properties !== "object" || Array.isArray(properties))
+        return false;
+    return !Object.hasOwn(properties, "command");
+}
 export const OPENCODE_1_TOOL_DIALECT = {
     filePathKey: "filePath",
     shellTool: "bash",
@@ -88,7 +114,20 @@ export function hostToolDialectFromTools(tools, defaultDialect = OPENCODE_1_TOOL
             ? "id"
             : defaultDialect.skillArgKey;
     }
-    return { filePathKey, shellTool, skillArgKey };
+    const shellSchema = tools.find((tool) => tool.name === shellTool)?.inputSchema;
+    const shellProps = jsonSchemaProperties(shellSchema);
+    const description = shellProps?.description;
+    const required = shellSchema && typeof shellSchema === "object" && !Array.isArray(shellSchema)
+        ? shellSchema.required
+        : undefined;
+    return {
+        filePathKey, shellTool, skillArgKey,
+        ...(description && typeof description === "object"
+            && description.type === "string"
+            ? { shellDescription: Array.isArray(required) && required.includes("description")
+                    ? "required" : "optional" }
+            : {}),
+    };
 }
 function assignHostFilePath(args, filePath, dialect) {
     delete args.filePath;
@@ -1163,10 +1202,9 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant, dialect = OP
     // as any other bash tool call.
     if (execVariant === "delete_args") {
         const target = str(cleaned.path) ?? str(cleaned.filePath);
-        return {
-            toolName: dialect.shellTool,
-            args: target ? { command: `rm -f -- ${shellQuote(target)}` } : { command: "true" },
-        };
+        return mapCursorArgsToOpencode(dialect.shellTool, {
+            command: target ? `rm -f -- ${shellQuote(target)}` : "true",
+        }, undefined, dialect);
     }
     switch (toolName) {
         case "read": {
@@ -1237,6 +1275,14 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant, dialect = OP
             const command = str(cleaned.command);
             if (command)
                 args.command = command;
+            if (dialect.shellDescription) {
+                const description = str(cleaned.description)
+                    ?? (dialect.shellDescription === "required" && command
+                        ? `Run: ${command.length > 60 ? `${command.slice(0, 57)}...` : command}`
+                        : undefined);
+                if (description)
+                    args.description = description;
+            }
             const workdir = str(cleaned.workdir) ?? str(cleaned.working_directory);
             if (workdir)
                 args.workdir = workdir;
@@ -1288,6 +1334,22 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant, dialect = OP
                 args[dialect.skillArgKey] = value;
             return { toolName: "skill", args };
         }
+        case "todowrite": {
+            // OpenCode requires `priority` on every todo item. Cursor TodoWrite /
+            // model MCP calls often omit it; fill host defaults before validation.
+            return {
+                toolName: "todowrite",
+                args: normalizeOpencodeTodoArgs(cleaned),
+            };
+        }
+        case "question": {
+            // OpenCode requires `header` on every question. Model MCP calls often
+            // omit it (AskQuestion bridge already fills it); default before validation.
+            return {
+                toolName: "question",
+                args: normalizeOpencodeQuestionArgs(cleaned),
+            };
+        }
         default:
             return { toolName, args: cleaned };
     }
@@ -1539,6 +1601,24 @@ export function buildReadRejectionMessages(execId, readResult) {
         buildExecStreamClose(execId),
     ];
 }
+/**
+ * The leading tool-result images an exec result can carry on a held Run.
+ * Cursor's own read executor answers an image file with its bytes in
+ * `ReadSuccess.data` (#5) and no text; its MCP executor appends each MCP image
+ * as an `McpImageContent` item (#2). Other result shapes have no image field.
+ */
+export function execResultImages(resultField, images) {
+    if (!images?.length)
+        return [];
+    if (resultField === "read_result")
+        return [images[0]];
+    if (resultField === "mcp_result")
+        return [...images];
+    return [];
+}
+function mcpImageItems(images) {
+    return images.map((image) => ({ image: { data: image.data, mime_type: image.mimeType } }));
+}
 /**
  * Build one or more ExecClientMessage frames for a tool result.
  * Shell replies are a sequence of ShellStream oneofs under the same id —
@@ -1594,7 +1674,7 @@ export function buildExecClientMessages(input) {
             id: input.execId,
             local_execution_time_ms: input.executionTimeMs ?? 0,
         };
-        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName, input.resultMetadata, input.shellOutcome, input.workspaceRoot);
+        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName, input.resultMetadata, input.shellOutcome, input.workspaceRoot, execResultImages(resultField, input.images));
         frames.push(encodeMessage("AgentClientMessage", {
             exec_client_message: clientMsg,
         }));
@@ -2463,7 +2543,7 @@ export function unwrapReadOutput(output) {
  * OpenCode returns free-form text; we wrap it in the minimal success shape the
  * server accepts (verified against agent.v1 wire captures).
  */
-export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata, shellOutcome, workspaceRoot) {
+export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata, shellOutcome, workspaceRoot, images = []) {
     // Prefer the session workspace; never advertise the host process cwd (daemon
     // often starts in $HOME) as the path Cursor shows the model for glob/ls.
     const trimmedRoot = typeof workspaceRoot === "string" ? workspaceRoot.trim() : "";
@@ -2483,6 +2563,18 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             const readPath = resolveToolPath(rawPath, resultRoot);
             if (error)
                 return { error: { path: readPath, error } };
+            const image = images[0];
+            if (image) {
+                return {
+                    success: {
+                        path: readPath,
+                        data: image.data,
+                        total_lines: 0,
+                        file_size: readFileSize(readPath) || image.data.length,
+                        truncated: false,
+                    },
+                };
+            }
             // The host may have resolved an alternate spelling after the request
             // (for example a Unicode-space filename). Use the result's own path for
             // local stat/newline recovery while preserving the requested path in the
@@ -2750,18 +2842,20 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             if (toolName === "grep" || toolName === "glob") {
                 return {
                     success: {
-                        content: [{ text: { text: groundSearchOutput(output, resultRoot) } }],
+                        content: [{ text: { text: groundSearchOutput(output, resultRoot) } }, ...mcpImageItems(images)],
                         is_error: false,
                     },
                 };
             }
             if (toolName !== "read") {
-                return { success: { content: [{ text: { text: output } }], is_error: false } };
+                return {
+                    success: { content: [{ text: { text: output } }, ...mcpImageItems(images)], is_error: false },
+                };
             }
             const listing = parseOpenCode2DirectoryListing(output, resultRoot);
             if (listing) {
                 return {
-                    success: { content: [{ text: { text: listing.text } }], is_error: false },
+                    success: { content: [{ text: { text: listing.text } }, ...mcpImageItems(images)], is_error: false },
                 };
             }
             // Carry the truncation notice as its own content item: the file content
@@ -2775,6 +2869,7 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
                     content: [
                         { text: { text: unwrapReadOutput(output) } },
                         ...notices.map((notice) => ({ text: { text: notice } })),
+                        ...mcpImageItems(images),
                     ],
                     is_error: false,
                 },
@@ -3226,7 +3321,14 @@ export function buildMcpStateResult(execId, args, toolDescriptors) {
         }
         list.push({
             name: stringValue(tool.name) ?? `${server}-${toolName}`,
-            description: stringValue(tool.description) ?? "",
+            // GetDynamicTools exposes the inner schema without the outer call identity.
+            // Keep the exact identity in the definition, including truncated searches.
+            description: `CallDynamicTool identity: ${JSON.stringify({ namespace: server, toolName })}. `
+                + `Complete outer envelope: ${JSON.stringify({ namespace: server, toolName, arguments: {} })}. `
+                + "Replace arguments with this inputSchema's object; keep both identity fields outside it. "
+                + "Write namespace and toolName FIRST, then arguments containing this inputSchema's object. "
+                + "All three outer fields are required on every invocation.\n\n"
+                + (stringValue(tool.description) ?? ""),
             input_schema: tool.input_schema,
             provider_identifier: server,
             tool_name: toolName,