cursor-opencode-provider 0.8.0 → 0.8.3

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
@@ -73,3 +77,5 @@ export declare function extractProtobufSubmessage(buf: Uint8Array, path: number[
  * can correlate display tool_call_started with the authoritative exec path.
  */
 export declare function extractExecDisplayCallId(execMsg: Record<string, unknown>): string | undefined;
+/** File paths a display TaskToolCall attaches; Cursor reads each one before its subagent request. */
+export declare function taskToolCallAttachments(toolCall: Record<string, unknown> | undefined): string[];

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)
@@ -717,3 +731,13 @@ export function extractExecDisplayCallId(execMsg) {
     }
     return undefined;
 }
+/** File paths a display TaskToolCall attaches; Cursor reads each one before its subagent request. */
+export function taskToolCallAttachments(toolCall) {
+    if (!toolCall || findToolVariant(toolCall) !== "task_tool_call")
+        return [];
+    const payload = asRecord(toolCall.task_tool_call);
+    const attachments = payload ? unwrapArgs(payload).attachments : undefined;
+    if (!Array.isArray(attachments))
+        return [];
+    return attachments.filter((item) => typeof item === "string" && item.trim().length > 0);
+}

package/dist/protocol/tools.d.ts

@@ -1,3 +1,5 @@
+import type { HookAdditionalContext } from "./host-notes.js";
+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 +10,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 +24,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;
@@ -118,6 +125,30 @@ export declare function resolveCursorSubagentType(subagentType: string, catalog?
 export declare function mapCursorSubagentTypeToOpenCode(subagentType: string): string;
 /** Resolve a native Cursor subagent request to this turn's executor and catalog. */
 export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, catalog?: HostSubagentCatalog): void;
+/**
+ * Who answers the private read Cursor sends under an edit's call id. Both the
+ * exec handler and the early tool row decide from this, so a row never opens
+ * for an edit whose read becomes its own host call.
+ *
+ * - `empty`: no target. The provider answers an empty file; creation continues.
+ * - `complete`: a readable regular file within Cursor's edit limit whose real
+ *   path is inside the workspace. The provider answers its complete content.
+ * - `external`: an existing target not proven inside the workspace by real
+ *   path, including through a symlink rooted in it. OpenCode's
+ *   permission-aware `read` answers; once authorized, the continuation
+ *   upgrades the result to the complete content.
+ * - `host`: any other existing target (not a regular file, too large,
+ *   unreadable, or not stat-able). OpenCode's `read` answers as is.
+ */
+export type CursorEditReadAnswer = "empty" | "complete" | "external" | "host";
+export declare function cursorEditReadAnswer(absolutePath: string, workspaceRoot: string): CursorEditReadAnswer;
+/**
+ * The edit's private read becomes its own host `read` call. A read the edit
+ * handshake leaves to the host can still be answered by the provider's
+ * missing-target validation (a dangling symlink, a directory); that read
+ * never reaches the host.
+ */
+export declare function cursorEditReadReachesHost(absolutePath: string, workspaceRoot: string): boolean;
 /**
  * Complete the private read inside Cursor's legacy edit transaction without
  * routing it through OpenCode's user-facing `read` tool. The latter caps every
@@ -128,6 +159,28 @@ export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest,
  * file named by an active `edit_tool_call` and is contained by the workspace.
  */
 export declare function buildCompleteEditReadMessages(execId: number, sourcePath: string, resultPath?: string): Uint8Array[] | undefined;
+/**
+ * Answer Cursor's read of a Task attachment without the file's bytes. Cursor
+ * puts them only in SubagentArgs.selected_context, which OpenCode's subagent
+ * tools cannot take, yet refuses the Task unless the read returns binary data.
+ * The path reaches the subagent prompt instead ({@link appendTaskAttachments})
+ * and the child reads it under its own permissions. A missing or non-regular
+ * target gets the same typed rejection as any native read.
+ */
+export declare function buildTaskAttachmentReadMessages(execId: number, sourcePath: string, resultPath?: string): Uint8Array[];
+/** List Cursor's Task attachments at the end of the subagent prompt as absolute paths. */
+export declare function appendTaskAttachments(parsed: ParsedExecRequest, attachments: readonly string[], workspaceRoot: string): void;
+/**
+ * Host tool a Cursor edit announcement will become, using the same file facts
+ * as `remapCorrelatedEditWriteForCatalog` and `remapEditToolsForCatalog`. An
+ * existing file becomes `edit`, else the patch tool. A missing file is a
+ * creation, which stays `write`, else becomes the patch tool's Add File; so
+ * does an empty file, which has no text for an `edit` to replace. A name is
+ * withheld when those remaps would refuse the file or not produce that tool:
+ * no workspace for a relative path, not a regular file, too large,
+ * unreadable, or `patch` with carriage returns.
+ */
+export declare function hostToolForCursorEdit(filePath: string, catalog: ReadonlySet<string>, workspaceRoot?: string): string | undefined;
 /**
  * Preserve a legacy Cursor edit's intent when its internal executor follows
  * `edit_tool_call` with a whole-file `write_args` request.
@@ -137,19 +190,19 @@ export declare function buildCompleteEditReadMessages(execId: number, sourcePath
  */
 export declare function remapCorrelatedEditWriteForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, editPath: string, workspaceRoot?: string): boolean;
 /**
- * Express a native Cursor write/edit as `apply_patch` when the host swapped the
+ * Express a native Cursor write/edit as a patch call when the host swapped the
  * edit-tool family out from under us.
  *
- * OpenCode 1.x removes `edit` and `write` from the catalog for GPT models and
- * advertises `apply_patch` in their place — see the module comment in
- * `./apply-patch.ts` for the upstream reasoning and citations. Cursor keeps
- * using its native write/edit exec channel regardless, so without this the
- * request is refused as an unavailable tool and the model loses the ability to
- * change files at all.
+ * Both OpenCode majors remove `edit` and `write` from the catalog for GPT
+ * models and advertise a patch tool in their place (`apply_patch` on 1.x,
+ * `patch` on 2.0) — see the module comment in `./apply-patch.ts` for the
+ * upstream reasoning and citations. Cursor keeps using its native write/edit
+ * exec channel regardless, so without this the request is refused as an
+ * unavailable tool.
  *
  * Keyed purely off the advertised set: this is inert whenever the host offers
  * `write`/`edit` normally, and equally inert when it offers neither those nor
- * `apply_patch` (the caller's unavailable-tool rejection still applies).
+ * a patch tool (the caller's unavailable-tool rejection still applies).
  */
 export declare function remapEditToolsForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, workspaceRoot?: string): void;
 export type ParsedExecRequest = {
@@ -262,6 +315,8 @@ export type ToolResultInput = {
     resultField: string;
     output: string;
     error?: string;
+    refusal?: "permission_denied" | "rejected";
+    interrupted?: boolean;
     executionTimeMs?: number;
     /**
      * Resolved opencode tool name (read/write/grep/…). Gates read-envelope
@@ -280,7 +335,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 —
@@ -289,6 +353,16 @@ export type ToolResultInput = {
  * shell execs hang on heartbeats forever).
  */
 export declare function buildExecClientMessages(input: ToolResultInput): Uint8Array[];
+/**
+ * Attach host notes to an exec result as Cursor CLI postToolUse hook context:
+ * `ExecClientMessage.hook_additional_contexts` (#45) on a unary result, or a
+ * `ShellStream.hook_context` (#8) event after the stream's own events and
+ * before `stream_close` (CLI agent-exec hook wrapper). Cursor renders it as a
+ * system reminder on that tool result, so it never mixes into file content.
+ * Returns undefined when the frames carry no exec result (bridged
+ * interaction replies have no such field).
+ */
+export declare function attachHookAdditionalContexts(frames: readonly Uint8Array[], contexts: readonly HookAdditionalContext[]): Uint8Array[] | undefined;
 /** ACM #5 exec_client_control_message { stream_close { id } }. */
 export declare function buildExecStreamClose(execId: number): Uint8Array;
 export declare function buildUnsupportedExecDeny(input: {
@@ -316,12 +390,19 @@ export declare function buildUnsupportedExecDeny(input: {
  * alone is not a tool-identity check.
  */
 export declare function unwrapReadOutput(output: string): string;
+/**
+ * OpenCode's read tool appends newly discovered instructions after the
+ * envelope's unnumbered `</content>`, in one `<system-reminder>` block.
+ * The numbered-body parser stops before that block, so callers must lift it
+ * out before the file text is encoded.
+ */
+export declare function extractOpenCodeReadInstruction(output: string): string | undefined;
 /**
  * Map OpenCode tool text into the agent.v1 result oneof for each exec variant.
  * 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;