cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/protocol/request.d.ts

@@ -12,16 +12,17 @@ export type RunRequestInput = {
     /** Stable parent group; unlike conversationId, this survives compaction/rebase. */
     conversationGroupId?: string;
     /**
-     * Prior chat turns for a seed ConversationStateStructure (no checkpoint).
-     * Tool outputs, when required for compaction/recovery, are represented as
-     * user-role OpenCode host observations rather than assistant-authored prose.
+     * Prior chat turns for a Run without a checkpoint, carried in the live user
+     * text (see {@link seedHistoryUserText}). Tool outputs, when required for
+     * compaction/recovery, are represented as user-role OpenCode host
+     * observations rather than assistant-authored prose.
      */
     history?: SeedHistoryMessage[];
     /**
      * Opaque ConversationStateStructure bytes from the last
      * conversation_checkpoint_update for this conversation_id. When set, echoed
-     * as AgentRunRequest.conversation_state (CLI parity). When absent, a seed
-     * state carrying only `history` (or empty) is built for turn 1.
+     * as AgentRunRequest.conversation_state (CLI parity). When absent, an empty
+     * seed state is sent and `history` travels in the user text.
      */
     conversationState?: Uint8Array;
     parameterValues?: Array<{
@@ -37,28 +38,39 @@ export type RunRequestInput = {
     requestContext?: Record<string, unknown>;
     /** Resume the supplied checkpoint instead of submitting another user turn. */
     action?: "user" | "resume";
+    /**
+     * Cursor mode of this user turn (`UserMessage.mode`, an `agent.v1.AgentMode`
+     * value). Cursor CLI sends its current mode on every user message.
+     */
+    mode?: number;
 };
 /**
- * Seed ConversationStateStructure for the first turn (no checkpoint yet).
+ * Empty ConversationStateStructure for a Run without a checkpoint (turn 1,
+ * compaction, rebase, reseed). After the first checkpoint arrives we stop
+ * inventing state and echo the server's opaque structure instead (CLI behavior).
  *
- * After the first checkpoint arrives we stop inventing state and echo the
- * server's opaque structure instead (CLI behavior). Compaction resets and
- * rebases also use this seed, with `history` carrying OpenCode's prompt turns
- * so Cursor can continue without the old checkpoint.
- *
- * No `system` entry is seeded: Cursor does not follow a client-authored
- * `system` root message, and neither Cursor client writes
- * `root_prompt_messages_json`. Host system context travels as the
- * system-instructions rule in RequestContext (`systemInstructionsRule`), so
- * `system` history entries are dropped here rather than duplicated.
+ * Nothing goes in `root_prompt_messages_json` (#1). Neither Cursor client
+ * writes it: Cursor checkpoints fill it with references to the conversation's
+ * own rendered root prompt. A client-written entry stands in for that prompt,
+ * so Cursor stops rendering RequestContext rules, skills and subagents — the
+ * host system-instructions rule included. Verified live 2026-10-09
+ * (claude-sonnet-5-5): two seeded history messages there gave checkpoint
+ * categories `rules:0, subagents:0` and a reply that ignored the rule; the same
+ * history in the user text kept both. History therefore travels in the user
+ * text ({@link seedHistoryUserText}).
  *
  * We deliberately do NOT use `AgentRunRequest.custom_system_prompt` (#8): that
  * field is the internal `--system-prompt` CLI override and the server rejects
  * it for normal accounts.
  */
-export declare function buildSeedConversationState(input?: {
-    history?: SeedHistoryMessage[];
-}): Uint8Array;
+export declare function buildSeedConversationState(): Uint8Array;
+/**
+ * Prior turns of a Run without a checkpoint, as a transcript ahead of the live
+ * user text. `system` entries are dropped: host system context travels as the
+ * system-instructions rule in RequestContext. Closing tags inside a message are
+ * escaped so a message cannot end its own block early.
+ */
+export declare function seedHistoryUserText(text: string, history: readonly SeedHistoryMessage[] | undefined): string;
 /**
  * Build an AgentClientMessage{run_request} for a conversation turn.
  *
@@ -70,3 +82,12 @@ export declare function buildRunRequest(input: RunRequestInput): Uint8Array;
  * Build a heartbeat message.
  */
 export declare function buildHeartbeat(): Uint8Array;
+/**
+ * ACM #5 `exec_client_control_message.heartbeat{id}`: Cursor CLI sends it every
+ * 3 s for each exec it is still running, keyed by the exec message id. The CLI
+ * leaves a zero id out, as proto3 does for a default scalar; protobufjs would
+ * write it explicitly, so it is omitted here to send the CLI's exact bytes.
+ */
+export declare function buildExecHeartbeat(execId: number): Uint8Array;
+/** Stops the live Run, as Cursor CLI does on a user Stop before it closes the stream. */
+export declare function buildCancelAction(reason: string): Uint8Array;

package/dist/protocol/request.js

@@ -1,35 +1,42 @@
 import { encodeMessage, getMessageTypes } from "./messages.js";
 /**
- * Seed ConversationStateStructure for the first turn (no checkpoint yet).
+ * Empty ConversationStateStructure for a Run without a checkpoint (turn 1,
+ * compaction, rebase, reseed). After the first checkpoint arrives we stop
+ * inventing state and echo the server's opaque structure instead (CLI behavior).
  *
- * After the first checkpoint arrives we stop inventing state and echo the
- * server's opaque structure instead (CLI behavior). Compaction resets and
- * rebases also use this seed, with `history` carrying OpenCode's prompt turns
- * so Cursor can continue without the old checkpoint.
- *
- * No `system` entry is seeded: Cursor does not follow a client-authored
- * `system` root message, and neither Cursor client writes
- * `root_prompt_messages_json`. Host system context travels as the
- * system-instructions rule in RequestContext (`systemInstructionsRule`), so
- * `system` history entries are dropped here rather than duplicated.
+ * Nothing goes in `root_prompt_messages_json` (#1). Neither Cursor client
+ * writes it: Cursor checkpoints fill it with references to the conversation's
+ * own rendered root prompt. A client-written entry stands in for that prompt,
+ * so Cursor stops rendering RequestContext rules, skills and subagents — the
+ * host system-instructions rule included. Verified live 2026-10-09
+ * (claude-sonnet-5-5): two seeded history messages there gave checkpoint
+ * categories `rules:0, subagents:0` and a reply that ignored the rule; the same
+ * history in the user text kept both. History therefore travels in the user
+ * text ({@link seedHistoryUserText}).
  *
  * We deliberately do NOT use `AgentRunRequest.custom_system_prompt` (#8): that
  * field is the internal `--system-prompt` CLI override and the server rejects
  * it for normal accounts.
  */
-export function buildSeedConversationState(input) {
-    const root = getMessageTypes();
-    const type = root.lookupType("ConversationStateStructure");
-    const messages = [];
-    for (const entry of input?.history ?? []) {
-        if (!entry.content || entry.role === "system")
-            continue;
-        messages.push(JSON.stringify({ role: entry.role, content: entry.content }));
-    }
-    const obj = {};
-    if (messages.length > 0)
-        obj.root_prompt_messages_json = messages;
-    return type.encode(type.fromObject(obj)).finish();
+export function buildSeedConversationState() {
+    const type = getMessageTypes().lookupType("ConversationStateStructure");
+    return type.encode(type.fromObject({})).finish();
+}
+const SEED_HISTORY_TAGS = /<\/(conversation_history|user|assistant)>/gi;
+/**
+ * Prior turns of a Run without a checkpoint, as a transcript ahead of the live
+ * user text. `system` entries are dropped: host system context travels as the
+ * system-instructions rule in RequestContext. Closing tags inside a message are
+ * escaped so a message cannot end its own block early.
+ */
+export function seedHistoryUserText(text, history) {
+    const entries = (history ?? []).filter((entry) => entry.content && entry.role !== "system");
+    if (entries.length === 0)
+        return text;
+    const transcript = entries
+        .map((entry) => `<${entry.role}>\n${entry.content.replace(SEED_HISTORY_TAGS, "<\\/$1>")}\n</${entry.role}>`)
+        .join("\n\n");
+    return `<conversation_history>\n${transcript}\n</conversation_history>\n\n${text}`;
 }
 /**
  * Build an AgentClientMessage{run_request} for a conversation turn.
@@ -43,10 +50,13 @@ export function buildRunRequest(input) {
     // mcp_meta_tool_options. AgentRunRequest.mcp_tools (#4) stays empty on real
     // turns (CLI prewarm-only). Full defs are session.toolDescriptors + exec #36.
     const requestContext = input.requestContext;
+    const seeded = !(input.conversationState && input.conversationState.length > 0);
     const userMessage = {
-        text: input.text,
+        text: seeded ? seedHistoryUserText(input.text, input.history) : input.text,
         message_id: msgId,
     };
+    if (input.mode !== undefined)
+        userMessage.mode = input.mode;
     if (input.images?.length) {
         userMessage.selected_context = {
             selected_images: input.images.map((image) => ({
@@ -63,9 +73,9 @@ export function buildRunRequest(input) {
     const action = input.action === "resume"
         ? { resume_action: {} }
         : { user_message_action: userMessageAction };
-    const conversationState = input.conversationState && input.conversationState.length > 0
-        ? input.conversationState
-        : buildSeedConversationState({ history: input.history });
+    const conversationState = seeded
+        ? buildSeedConversationState()
+        : input.conversationState;
     const runRequest = {
         conversation_id: input.conversationId,
         conversation_group_id: input.conversationGroupId ?? input.conversationId,
@@ -96,3 +106,20 @@ export function buildHeartbeat() {
         client_heartbeat: {},
     });
 }
+/**
+ * ACM #5 `exec_client_control_message.heartbeat{id}`: Cursor CLI sends it every
+ * 3 s for each exec it is still running, keyed by the exec message id. The CLI
+ * leaves a zero id out, as proto3 does for a default scalar; protobufjs would
+ * write it explicitly, so it is omitted here to send the CLI's exact bytes.
+ */
+export function buildExecHeartbeat(execId) {
+    return encodeMessage("AgentClientMessage", {
+        exec_client_control_message: { heartbeat: execId === 0 ? {} : { id: execId } },
+    });
+}
+/** Stops the live Run, as Cursor CLI does on a user Stop before it closes the stream. */
+export function buildCancelAction(reason) {
+    return encodeMessage("AgentClientMessage", {
+        conversation_action: { cancel_action: { reason } },
+    });
+}

package/dist/protocol/sent-history-images.d.ts

@@ -0,0 +1,49 @@
+/** `hashes` is shared between entries and never mutated. */
+type HeldImages = {
+    conversationId: string;
+    checkpoint: string;
+    hashes: readonly string[];
+};
+/**
+ * One Run's view: `held` by the checkpoint it last stood on, `checkpointed` sent
+ * before Cursor's latest checkpoint arrived, `sent` since, each with the last
+ * frame arrival at its send. Only a turn that ends on a checkpoint of its own
+ * moves `checkpointed` into `held`.
+ */
+export type RunHistoryImages = {
+    held: readonly string[];
+    checkpointed: string[];
+    sent: Array<{
+        hash: string;
+        afterArrival: number;
+    }>;
+};
+export declare function checkpointFingerprint(checkpoint: Uint8Array): string;
+/** The images `checkpoint` is known to hold. */
+export declare function heldHistoryImageHashes(sessionKey: string, conversationId: string, checkpoint: Uint8Array): ReadonlySet<string> | undefined;
+export declare function runHistoryImages(held?: ReadonlySet<string>): RunHistoryImages;
+/** `lastArrival`: the last frame arrival once the images are written. */
+export declare function noteHistoryImagesSent(run: RunHistoryImages, hashes: readonly string[], lastArrival?: number): void;
+/**
+ * Cursor's checkpoints extend the one the Run started on, so each holds at least what that one held.
+ * A checkpoint that arrived before images were written (read only after a host tool's result) holds none of them.
+ */
+export declare function noteHistoryImageCheckpoint(run: RunHistoryImages, sessionKey: string, conversationId: string, checkpoint: Uint8Array, arrival?: number): void;
+/**
+ * The turn ended. On a checkpoint of its own, that checkpoint holds what the Run
+ * sent before it; without one, nothing the Run sent counts as held.
+ */
+export declare function confirmHistoryImagesAtTurnEnd(run: RunHistoryImages, sessionKey: string, conversationId: string, checkpoint: Uint8Array | undefined): void;
+/** For the restart snapshot: the set the checkpoint being saved holds. */
+export declare function heldHistoryImagesSnapshot(sessionKey: string, conversationId: string, checkpoint: Uint8Array | undefined): {
+    checkpoint: string;
+    hashes: string[];
+} | undefined;
+export declare function restoreHeldHistoryImages(sessionKey: string, conversationId: string, saved: {
+    checkpoint?: string;
+    hashes?: readonly string[];
+}): void;
+export declare function forgetHeldHistoryImages(sessionKey: string): void;
+export declare function snapshotHeldHistoryImagesForTests(sessionKey: string): HeldImages[];
+export declare function resetHeldHistoryImagesForTests(): void;
+export {};

package/dist/protocol/sent-history-images.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+// Content hashes of the history images a session's Cursor conversation holds, so
+// growing history does not re-upload old screenshots. Each set belongs to one
+// checkpoint: a Run skips an image only when it sends exactly that checkpoint.
+/** Mirrors MAX_TURN_STATE_SESSIONS. */
+const MAX_SESSIONS = 256;
+const MAX_IMAGES_PER_SESSION = 256;
+/** A stopped or failed turn leaves the next Run on one of its intermediate checkpoints. */
+const MAX_CHECKPOINTS_PER_SESSION = 32;
+/** Newest first. */
+const heldBySession = new Map();
+export function checkpointFingerprint(checkpoint) {
+    return createHash("sha256").update(checkpoint).digest("hex");
+}
+function newest(hashes) {
+    const unique = [...new Set([...hashes].reverse())].reverse();
+    return unique.slice(Math.max(0, unique.length - MAX_IMAGES_PER_SESSION));
+}
+function touch(sessionKey, entries) {
+    heldBySession.delete(sessionKey);
+    if (entries.length === 0)
+        return;
+    heldBySession.set(sessionKey, entries.slice(0, MAX_CHECKPOINTS_PER_SESSION));
+    while (heldBySession.size > MAX_SESSIONS) {
+        const oldest = heldBySession.keys().next().value;
+        if (!oldest)
+            break;
+        heldBySession.delete(oldest);
+    }
+}
+function find(sessionKey, conversationId, checkpoint) {
+    const entries = heldBySession.get(sessionKey);
+    if (!entries)
+        return undefined;
+    const fingerprint = checkpointFingerprint(checkpoint);
+    return entries.find((entry) => entry.conversationId === conversationId && entry.checkpoint === fingerprint);
+}
+/** The images `checkpoint` is known to hold. */
+export function heldHistoryImageHashes(sessionKey, conversationId, checkpoint) {
+    const entry = find(sessionKey, conversationId, checkpoint);
+    if (!entry)
+        return undefined;
+    touch(sessionKey, heldBySession.get(sessionKey));
+    return new Set(entry.hashes);
+}
+function recordHeldHistoryImages(sessionKey, conversationId, checkpoint, hashes) {
+    if (hashes.length === 0)
+        return;
+    const entry = { conversationId, checkpoint: checkpointFingerprint(checkpoint), hashes };
+    const others = (heldBySession.get(sessionKey) ?? [])
+        .filter((other) => other.conversationId !== conversationId || other.checkpoint !== entry.checkpoint);
+    touch(sessionKey, [entry, ...others]);
+}
+export function runHistoryImages(held) {
+    return { held: [...(held ?? [])], checkpointed: [], sent: [] };
+}
+/** `lastArrival`: the last frame arrival once the images are written. */
+export function noteHistoryImagesSent(run, hashes, lastArrival = 0) {
+    run.sent.push(...hashes.map((hash) => ({ hash, afterArrival: lastArrival })));
+}
+/**
+ * Cursor's checkpoints extend the one the Run started on, so each holds at least what that one held.
+ * A checkpoint that arrived before images were written (read only after a host tool's result) holds none of them.
+ */
+export function noteHistoryImageCheckpoint(run, sessionKey, conversationId, checkpoint, arrival = Infinity) {
+    const later = run.sent.findIndex((image) => image.afterArrival >= arrival);
+    const earlier = later < 0 ? run.sent.length : later;
+    run.checkpointed.push(...run.sent.slice(0, earlier).map((image) => image.hash));
+    run.sent = run.sent.slice(earlier);
+    recordHeldHistoryImages(sessionKey, conversationId, checkpoint, run.held);
+}
+/**
+ * The turn ended. On a checkpoint of its own, that checkpoint holds what the Run
+ * sent before it; without one, nothing the Run sent counts as held.
+ */
+export function confirmHistoryImagesAtTurnEnd(run, sessionKey, conversationId, checkpoint) {
+    if (checkpoint?.length) {
+        run.held = newest([...run.held, ...run.checkpointed]);
+        recordHeldHistoryImages(sessionKey, conversationId, checkpoint, run.held);
+    }
+    run.checkpointed = [];
+    run.sent = [];
+}
+/** For the restart snapshot: the set the checkpoint being saved holds. */
+export function heldHistoryImagesSnapshot(sessionKey, conversationId, checkpoint) {
+    const entry = checkpoint?.length ? find(sessionKey, conversationId, checkpoint) : undefined;
+    return entry ? { checkpoint: entry.checkpoint, hashes: [...entry.hashes] } : undefined;
+}
+export function restoreHeldHistoryImages(sessionKey, conversationId, saved) {
+    touch(sessionKey, saved.checkpoint && saved.hashes?.length
+        ? [{ conversationId, checkpoint: saved.checkpoint, hashes: newest(saved.hashes) }]
+        : []);
+}
+export function forgetHeldHistoryImages(sessionKey) {
+    heldBySession.delete(sessionKey);
+}
+export function snapshotHeldHistoryImagesForTests(sessionKey) {
+    return (heldBySession.get(sessionKey) ?? []).map((entry) => ({ ...entry, hashes: [...entry.hashes] }));
+}
+export function resetHeldHistoryImagesForTests() {
+    heldBySession.clear();
+}

package/dist/protocol/switch-mode.d.ts

@@ -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,6 @@
  * CLI reject reason for user declines: "Mode switch rejected by user"
  * (chunk-7076/dist/ui.js onSwitchModeReject).
  */
-import { type OpencodeQuestionInput } from "./ask-question.js";
 /**
  * `PendingExec.resultField` for a held-open SwitchMode InteractionQuery.
  * Continuation writes an InteractionResponse, not an ExecClientMessage.
@@ -58,10 +57,16 @@ export declare const MISSING_TARGET_REASON = "Missing targetModeId";
  * even though the next Run will succeed. CreatePlan already soft-acks the same
  * case; SwitchMode must match.
  */
-export declare const PLAN_EXIT_UNAVAILABLE_REASON: string;
-/** Upstream `PlanExitTool` wording, minus a plan path the provider cannot verify. */
-export declare const SWITCH_MODE_EXIT_QUESTION = "Planning is complete. Would you like to switch to the build agent and start implementing?";
-export declare const SWITCH_MODE_EXIT_HEADER = "Build Agent";
+/**
+ * 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 declare const PLAN_EXIT_BY_USER_REASON: string;
+/**
+ * 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 declare const PLAN_EXIT_VIA_CREATE_PLAN_REASON: string;
 export type SwitchModeHostTool = "plan_enter" | "plan_exit";
 /**
  * How a SwitchMode query is satisfied this turn.
@@ -70,7 +75,6 @@ export type SwitchModeHostTool = "plan_enter" | "plan_exit";
  * - `approve`  entering plan mode needs no host tool — approve immediately.
  * - `ack`      lifecycle turn (`allowTools=false`): approve on the wire without
  *              mutating session mode (same soft-ack pattern as CreatePlan).
- * - `question` leaving plan mode falls back to the host `question` prompt.
  * - `reject`   nothing can satisfy it; `reason` names the real cause.
  */
 export type SwitchModeBridge = {
@@ -80,9 +84,6 @@ export type SwitchModeBridge = {
     kind: "approve";
 } | {
     kind: "ack";
-} | {
-    kind: "question";
-    input: OpencodeQuestionInput;
 } | {
     kind: "reject";
     reason: string;
@@ -114,21 +115,22 @@ export declare function normalizeSwitchModeId(targetModeId: string): string;
  * for CLI-shaped behavioral guidance.
  */
 export declare function mapSwitchModeTarget(targetModeId: string): SwitchModeMapping;
-/** Host `question` input mirroring upstream `PlanExitTool`'s own prompt. */
-export declare function switchModeExitQuestionInput(): OpencodeQuestionInput;
 /**
  * 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 declare function resolveSwitchModeBridge(targetModeId: string, options: {
     allowTools: boolean;
     advertised: ReadonlySet<string> | Iterable<string>;
     /** Cursor unified mode currently recorded for this session, if any. */
     activeModeId?: string;
+    /** Host primary agent of this Run, when the host reported it. */
+    hostAgent?: string;
 }): SwitchModeBridge;
 /** Decode a `switch_mode_request_query` body, or undefined when unusable. */
 export declare function decodeSwitchModeQuery(queryBytes: Uint8Array): DecodedSwitchModeQuery | undefined;
@@ -142,12 +144,6 @@ export declare function switchModeRejectedResult(reason: string): Record<string,
  * Question/permission declines and empty failures use the CLI user-reject string.
  */
 export declare function switchModeResultFromToolOutput(output: string, isError: boolean): Record<string, unknown>;
-/**
- * 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 declare function switchModeResultFromQuestionOutput(output: string, isError: boolean): Record<string, unknown>;
 /** Record the approved Cursor mode for later system-reminder injection. */
 export declare function setActiveCursorMode(sessionKey: string | undefined, targetModeId: string, options?: {
     bridgedPlanEntered?: boolean;
@@ -155,8 +151,47 @@ export declare function setActiveCursorMode(sessionKey: string | undefined, targ
 export declare function getActiveCursorMode(sessionKey: string | undefined): string | undefined;
 /** True while the provider has an approved Cursor plan/spec mode for this session. */
 export declare function isCursorPlanModeActive(sessionKey: string | undefined): boolean;
-/** 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 declare function isBridgedCursorPlanModeActive(sessionKey: string | undefined): boolean;
+/**
+ * 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 declare function followHostPlanAgent(sessionKey: string | undefined, previousHostAgent: string | undefined, hostAgent: string | undefined): "entered" | "left" | undefined;
+/**
+ * `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 declare function cursorAgentModeWireValue(modeId: string | undefined): number;
+/**
+ * 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 declare function takeHostPlanAgentNote(sessionKey: string | undefined, conversationId: string, hostAgent: string | undefined, tools: ReadonlyArray<{
+    name: string;
+    inputSchema?: unknown;
+}>, options?: {
+    /** The host's own plan file for this session, when the host defines one. */
+    hostPlanFile?: string;
+    /** MCP server identity the advertised `plan_exit` is called through. */
+    server?: string;
+}): string | undefined;
 export declare function clearActiveCursorMode(sessionKey: string | undefined): void;
 export declare function resetActiveCursorModesForTests(): void;
 /**
@@ -168,6 +203,8 @@ export declare function cursorModeSystemReminder(targetModeId: string, options?:
     firstTurn?: boolean;
     planExitAdvertised?: boolean;
     planStageAdvertised?: boolean;
+    /** The host `question` tool is advertised, so CreatePlan asks to start implementing. */
+    questionAdvertised?: boolean;
 }): string | undefined;
 /**
  * Consume the active-mode reminder for this OpenCode session.
@@ -175,4 +212,6 @@ export declare function cursorModeSystemReminder(targetModeId: string, options?:
  */
 export declare function takeActiveCursorModeReminder(sessionKey: string | undefined, options?: {
     advertisedTools?: ReadonlySet<string> | Iterable<string>;
+    /** Host primary agent of this request; when known it, not the catalog, says whether planning ended. */
+    hostAgent?: string;
 }): string | undefined;