cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/protocol/conversation-state.d.ts

@@ -6,10 +6,15 @@ export declare function hydrateConversationState(cacheDir: string, sessionKey: s
     toolCatalog: OpencodeToolDef[];
     hostAgent?: string;
     systemPromptHash?: string;
+    hostNote?: string;
 } | undefined>;
 /** Restore only turn provenance when its in-memory entry was evicted. */
 export declare function hydrateTurnProvenance(cacheDir: string, sessionKey: string): Promise<void>;
-/** Persist the complete resumable state only after Cursor confirms TurnEnded. */
+/**
+ * Persist the resumable state at Cursor's TurnEnded, or before it
+ * (`runInProgress`) so a Run the host interrupts, or a restart, resumes from
+ * the latest checkpoint and still recognizes the step in progress.
+ */
 export declare function persistConversationState(cacheDir: string, input: {
     sessionKey: string;
     conversationId: string;
@@ -18,5 +23,7 @@ export declare function persistConversationState(cacheDir: string, input: {
     postCompactionRebase?: boolean;
     hostAgent?: string;
     systemPromptHash?: string;
+    hostNote?: string;
+    runInProgress?: boolean;
 }): Promise<void>;
 export declare function clearPersistedConversationState(cacheDir: string, sessionKey: string, expectedConversationId?: string): Promise<void>;

package/dist/protocol/conversation-state.js

@@ -1,10 +1,13 @@
 import { trace } from "../debug.js";
+import { restoreEarlySteers, serializeEarlySteers } from "../host-steer.js";
+import { restoreLostRequest, serializeLostRequest } from "../lost-request.js";
 import { getFrozenRequestContext, setFrozenRequestContext, } from "../context/frozen.js";
 import { hasConversationBinding, isActiveConversationBinding, restoreConversationBinding, } from "./conversation-bind.js";
 import { compactConversationBlobs, restoreConversationBlobs, } from "./blob-store.js";
 import { getCheckpoint, setCheckpoint } from "./checkpoint.js";
 import { getTurnProvenance, parseTurnProvenance, restoreTurnProvenance, serializeTurnProvenance, } from "./turn-provenance.js";
-import { deletePersistedConversation, loadPersistedConversation, persistConversation, } from "./conversation-persistence.js";
+import { heldHistoryImagesSnapshot, restoreHeldHistoryImages } from "./sent-history-images.js";
+import { deletePersistedConversation, getPersistedTurnProvenance, loadPersistedConversation, persistConversation, } from "./conversation-persistence.js";
 /** Restore one OpenCode session before its conversation binding is resolved. */
 export async function hydrateConversationState(cacheDir, sessionKey) {
     if (hasConversationBinding(sessionKey))
@@ -17,6 +20,8 @@ export async function hydrateConversationState(cacheDir, sessionKey) {
         return undefined;
     }
     restoreConversationBinding(sessionKey, persisted.conversationId);
+    restoreEarlySteers(sessionKey, persisted.earlySteers);
+    restoreLostRequest(sessionKey, persisted.lostRequest);
     if (persisted.checkpoint)
         setCheckpoint(persisted.conversationId, persisted.checkpoint);
     restoreConversationBlobs(persisted.conversationId, persisted.blobs);
@@ -24,29 +29,38 @@ export async function hydrateConversationState(cacheDir, sessionKey) {
     const provenance = persisted.turnProvenance ? parseTurnProvenance(persisted.turnProvenance) : undefined;
     if (provenance?.conversationId === persisted.conversationId)
         restoreTurnProvenance(sessionKey, provenance);
+    restoreHeldHistoryImages(sessionKey, persisted.conversationId, {
+        checkpoint: persisted.sentImagesCheckpoint,
+        hashes: persisted.sentImageHashes,
+    });
     trace(`conversation persistence: restored sessionKey=${sessionKey} ` +
         `conversationId=${persisted.conversationId} checkpoint=${persisted.checkpoint?.length ?? 0}B ` +
-        `blobs=${persisted.blobs.length}`);
+        `blobs=${persisted.blobs.length} heldImages=${persisted.sentImageHashes?.length ?? 0}`);
     return {
         conversationId: persisted.conversationId,
         postCompactionRebase: persisted.postCompactionRebase,
         toolCatalog: structuredClone(persisted.toolCatalog),
         ...(persisted.hostAgent ? { hostAgent: persisted.hostAgent } : {}),
         ...(persisted.systemPromptHash ? { systemPromptHash: persisted.systemPromptHash } : {}),
+        ...(persisted.hostNote ? { hostNote: persisted.hostNote } : {}),
     };
 }
 /** Restore only turn provenance when its in-memory entry was evicted. */
 export async function hydrateTurnProvenance(cacheDir, sessionKey) {
     if (getTurnProvenance(sessionKey))
         return;
-    const persisted = (await loadPersistedConversation(cacheDir, sessionKey)).value;
-    if (!persisted?.turnProvenance)
+    const persisted = await getPersistedTurnProvenance(cacheDir, sessionKey);
+    if (!persisted)
         return;
     const provenance = parseTurnProvenance(persisted.turnProvenance);
     if (provenance?.conversationId === persisted.conversationId)
         restoreTurnProvenance(sessionKey, provenance);
 }
-/** Persist the complete resumable state only after Cursor confirms TurnEnded. */
+/**
+ * Persist the resumable state at Cursor's TurnEnded, or before it
+ * (`runInProgress`) so a Run the host interrupts, or a restart, resumes from
+ * the latest checkpoint and still recognizes the step in progress.
+ */
 export async function persistConversationState(cacheDir, input) {
     // A newer Run may have reset/superseded this conversation while its final
     // frame was still in flight. Never let that late TurnEnded resurrect it.
@@ -56,10 +70,13 @@ export async function persistConversationState(cacheDir, input) {
         return;
     }
     const checkpoint = getCheckpoint(input.conversationId);
-    const blobCompaction = compactConversationBlobs(input.conversationId, checkpoint);
+    const blobCompaction = compactConversationBlobs(input.conversationId, checkpoint, {
+        keepInMemory: input.runInProgress,
+    });
     const blobs = blobCompaction.blobs;
     const requestContext = getFrozenRequestContext(input.conversationId) ?? input.requestContext;
     const provenance = getTurnProvenance(input.sessionKey);
+    const heldImages = heldHistoryImagesSnapshot(input.sessionKey, input.conversationId, checkpoint);
     await persistConversation(cacheDir, {
         sessionKey: input.sessionKey,
         conversationId: input.conversationId,
@@ -70,11 +87,15 @@ export async function persistConversationState(cacheDir, input) {
         postCompactionRebase: input.postCompactionRebase,
         hostAgent: input.hostAgent,
         systemPromptHash: input.systemPromptHash,
+        hostNote: input.hostNote,
+        earlySteers: serializeEarlySteers(input.sessionKey),
+        lostRequest: serializeLostRequest(input.sessionKey),
+        ...(heldImages ? { sentImageHashes: heldImages.hashes, sentImagesCheckpoint: heldImages.checkpoint } : {}),
         ...(provenance?.conversationId === input.conversationId
             ? { turnProvenance: serializeTurnProvenance(provenance) }
             : {}),
     });
-    trace(`conversation persistence: saved sessionKey=${input.sessionKey} ` +
+    trace(`conversation persistence: saved${input.runInProgress ? " in-progress" : ""} sessionKey=${input.sessionKey} ` +
         `conversationId=${input.conversationId} checkpoint=${checkpoint?.length ?? 0}B ` +
         `blobs=${blobCompaction.beforeCount}->${blobCompaction.afterCount} ` +
         `blobBytes=${blobCompaction.beforeBytes}->${blobCompaction.afterBytes}` +

package/dist/protocol/create-plan.d.ts

@@ -7,10 +7,10 @@
  * does **not** — plans must stay host-portable so switching models does not
  * strand users on Cursor-specific paths or frontmatter.
  *
- * Location mirrors OpenCode Session.plan shape, but the project-config segment
- * comes from {@link hostPlansDir} / {@link opencodeProjectConfigDirs}
- * (the active host's project config dir via the path bridge), never a
- * hardcoded OpenCode-only directory name.
+ * Location is the host's own: the session plan file when the host defines one
+ * (`hostPlanFilePath`, OpenCode 1.x `Session.plan`), otherwise a new
+ * `<created>-<slug>.md` under {@link hostPlansDir} (OpenCode 2.0's Plan
+ * directory, OpenCode 1.x `<data>/plans`, or an installed path bridge).
  *
  * Body is plain markdown (the same shape a plan-mode model would write with
  * `write`). Cursor YAML frontmatter is never emitted.
@@ -58,46 +58,66 @@ export type CursorPlanStageInput = {
  *             Its tool result is the approval outcome (success = approved,
  *             error = not approved). The result may name the host's own
  *             follow-up approval call. This provider does not invent that prompt.
- * - `approve` no such tool, but the host advertises `question`: the provider
- *             writes the plan itself and then asks the same thing with upstream
- *             `PlanExitTool`'s own prompt.
- * - `ack`     nothing to ask with (or a lifecycle turn): write, or for a
- *             lifecycle turn skip the write, and acknowledge the CLI way.
+ * - `ack`     nothing to ask with (or a lifecycle turn / CreatePlan outside
+ *             plan mode): write, or for a lifecycle turn skip the write, and
+ *             acknowledge the CLI way.
+ * - `approve` plan mode is active and the host advertises `question` but not
+ *             a plan review tool: write the plan, then ask with upstream
+ *             `PlanExitTool`'s own prompt (OpenCode 1.x / 2.0 without
+ *             `plan_exit`). Explicit "Yes" is execution approval.
+ * - `exit`    the host's `plan` agent is active, advertises `plan_exit`, and
+ *             its own plan file is known: write the plan there and run the
+ *             host `plan_exit` review. The host owns approval and execution;
+ *             the turn that carries the result leaves `plan` only on approval.
+ * - `defer`   the host's `plan` agent owns planning but CreatePlan cannot be
+ *             carried out yet: an approved switch into it is still pending (it
+ *             applies after this Run), or its plan file is unknown. Nothing is
+ *             written; the error tells the model which host workflow follows.
  *
- * The plan is always persisted before any prompt: writing needs no approval,
- * executing does.
+ * The plan is always persisted before any review: writing needs no approval,
+ * executing does, and only the host asks for it.
  */
 export type CreatePlanBridge = {
     kind: "stage";
+} | {
+    kind: "ack";
 } | {
     kind: "approve";
 } | {
-    kind: "ack";
+    kind: "defer";
+    reason: string;
+} | {
+    kind: "exit";
+    planPath: string;
 };
+/** CreatePlan raised before an approved switch into the host plan agent took effect. */
+export declare const CREATE_PLAN_HOST_PLAN_PENDING_REASON: string;
+/** CreatePlan raised while the host's own plan agent owns the plan file and its review. */
+export declare const CREATE_PLAN_HOST_PLAN_WORKFLOW_REASON: string;
+/** Cursor-visible reason when the user wants the plan revised instead of run. */
+export declare const CREATE_PLAN_NOT_APPROVED_REASON: string;
 /** Upstream `PlanExitTool` wording, with the plan the provider just wrote. */
 export declare function createPlanApprovalQuestion(planLabel: string): string;
 export declare const CREATE_PLAN_APPROVAL_HEADER = "Build Agent";
-/** Cursor-visible reason when the user wants the plan revised instead of run. */
-export declare const CREATE_PLAN_NOT_APPROVED_REASON: string;
-/**
- * Resolve how this CreatePlan is satisfied. `planModeActive` is the provider's
- * own record of an approved Cursor plan/spec mode: the approval prompt guards
- * the transition *out of* planning, so a CreatePlan raised outside plan mode is
- * written and acknowledged without one.
- */
+/** Resolve how this CreatePlan is satisfied (see {@link CreatePlanBridge}). */
 export declare function resolveCreatePlanBridge(options: {
     allowTools: boolean;
     canStage?: boolean;
-    planModeActive?: boolean;
     advertised: ReadonlySet<string> | Iterable<string>;
+    /** An approved switch into the host `plan` agent waits for this Run to end. */
+    hostPlanEntryPending?: boolean;
+    /** Host primary agent of this Run, when the host reported it. */
+    hostAgent?: string;
+    /** Provider-recorded Cursor plan/spec mode (the gate out of planning). */
+    planModeActive?: boolean;
+    /** The host's own plan file for this session, when the host defines one. */
+    hostPlanFile?: string;
 }): CreatePlanBridge;
 /** Host `question` input mirroring upstream `PlanExitTool`'s own prompt. */
 export declare function createPlanApprovalQuestionInput(planLabel: string): OpencodeQuestionInput;
 /**
  * True when the emulated approval prompt came back as an explicit "Yes".
- * An unanswered, dismissed, or failed prompt keeps the model planning rather
- * than silently starting execution. OpenCode prose is anchored on the exact
- * prompt text. Every other result shape fails closed.
+ * An unanswered, dismissed, or failed prompt keeps the model planning.
  */
 export declare function createPlanApproved(output: string, isError: boolean, question: string): boolean;
 /** Decode a `create_plan_request_query` body, or undefined when unusable. */
@@ -125,7 +145,9 @@ export declare function renderOpencodePlanMarkdown(args: CursorCreatePlanArgs):
  * Write the plan under {@link hostPlansDir} and return a `file://` URI.
  * Empty / missing content is the caller's responsibility (empty plan_uri ack).
  */
-export declare function writeOpencodePlanFile(args: CursorCreatePlanArgs, workspaceRoot: string, created?: number): CreatePlanWriteResult;
+export declare function writeOpencodePlanFile(args: CursorCreatePlanArgs, workspaceRoot: string, created?: number, 
+/** Exact host-owned plan file; default is a new file under {@link hostPlansDir}. */
+target?: string): CreatePlanWriteResult;
 /**
  * The plan as the user reads it before approving execution.
  *

package/dist/protocol/create-plan.js

@@ -7,10 +7,10 @@
  * does **not** — plans must stay host-portable so switching models does not
  * strand users on Cursor-specific paths or frontmatter.
  *
- * Location mirrors OpenCode Session.plan shape, but the project-config segment
- * comes from {@link hostPlansDir} / {@link opencodeProjectConfigDirs}
- * (the active host's project config dir via the path bridge), never a
- * hardcoded OpenCode-only directory name.
+ * Location is the host's own: the session plan file when the host defines one
+ * (`hostPlanFilePath`, OpenCode 1.x `Session.plan`), otherwise a new
+ * `<created>-<slug>.md` under {@link hostPlansDir} (OpenCode 2.0's Plan
+ * directory, OpenCode 1.x `<data>/plans`, or an installed path bridge).
  *
  * Body is plain markdown (the same shape a plan-mode model would write with
  * `write`). Cursor YAML frontmatter is never emitted.
@@ -19,9 +19,9 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { hostPlansDir } from "../context/paths.js";
-import { parseAnswerSegments, } from "./ask-question.js";
 import { decodeMessageSparse } from "./messages.js";
 import { errorMessage } from "../debug.js";
+import { parseAnswerSegments, } from "./ask-question.js";
 const PLAN_ADJECTIVES = [
     "brave",
     "calm",
@@ -90,6 +90,17 @@ const PLAN_NOUNS = [
 export const CURSOR_PLAN_STAGE_TOOL = "cursor_plan_stage";
 /** Held InteractionQuery continuation field for a native host plan stage. */
 export const CREATE_PLAN_RESULT_FIELD = "create_plan_request_response";
+/** CreatePlan raised before an approved switch into the host plan agent took effect. */
+export const CREATE_PLAN_HOST_PLAN_PENDING_REASON = "Plan mode starts in the host's plan agent after this turn. Do not record the plan " +
+    "now and make no further tool calls: end this turn. Planning continues in the next " +
+    "turn under the host's plan-mode instructions.";
+/** CreatePlan raised while the host's own plan agent owns the plan file and its review. */
+export const CREATE_PLAN_HOST_PLAN_WORKFLOW_REASON = "This host's plan agent owns the plan file and its approval. Write the plan where the " +
+    "plan-mode instructions say, then call `plan_exit` to ask the user to approve it. Do " +
+    "not implement until it is approved.";
+/** Cursor-visible reason when the user wants the plan revised instead of run. */
+export const CREATE_PLAN_NOT_APPROVED_REASON = "The user did not approve executing this plan. Keep planning: refine the plan and "
+    + "propose it again when it is ready.";
 /** Upstream `PlanExitTool` wording, with the plan the provider just wrote. */
 export function createPlanApprovalQuestion(planLabel) {
     const where = planLabel.trim();
@@ -100,28 +111,28 @@ export function createPlanApprovalQuestion(planLabel) {
 export const CREATE_PLAN_APPROVAL_HEADER = "Build Agent";
 const CREATE_PLAN_APPROVAL_YES = "Yes";
 const CREATE_PLAN_APPROVAL_NO = "No";
-/** Cursor-visible reason when the user wants the plan revised instead of run. */
-export const CREATE_PLAN_NOT_APPROVED_REASON = "The user did not approve executing this plan. Keep planning: refine the plan and "
-    + "propose it again when it is ready.";
-/**
- * Resolve how this CreatePlan is satisfied. `planModeActive` is the provider's
- * own record of an approved Cursor plan/spec mode: the approval prompt guards
- * the transition *out of* planning, so a CreatePlan raised outside plan mode is
- * written and acknowledged without one.
- */
+/** Resolve how this CreatePlan is satisfied (see {@link CreatePlanBridge}). */
 export function resolveCreatePlanBridge(options) {
     // A lifecycle turn (title generation, compaction) runs alongside the real one
     // and must not write a second plan file or raise a second prompt.
     if (!options.allowTools)
         return { kind: "ack" };
+    if (options.hostPlanEntryPending) {
+        return { kind: "defer", reason: CREATE_PLAN_HOST_PLAN_PENDING_REASON };
+    }
     if (options.canStage)
         return { kind: "stage" };
     const names = options.advertised instanceof Set ? options.advertised : new Set(options.advertised);
-    if (options.planModeActive && names.has("question"))
+    if (options.hostAgent === "plan" && names.has("plan_exit")) {
+        return options.hostPlanFile
+            ? { kind: "exit", planPath: options.hostPlanFile }
+            : { kind: "defer", reason: CREATE_PLAN_HOST_PLAN_WORKFLOW_REASON };
+    }
+    const planModeActive = options.planModeActive === true || options.hostAgent === "plan";
+    if (planModeActive && names.has("question"))
         return { kind: "approve" };
     return { kind: "ack" };
 }
-/** The synthetic AskQuestion item backing the emulated approval prompt. */
 function createPlanApprovalItem(question) {
     return {
         id: "create_plan_approval",
@@ -156,16 +167,13 @@ export function createPlanApprovalQuestionInput(planLabel) {
 }
 /**
  * True when the emulated approval prompt came back as an explicit "Yes".
- * An unanswered, dismissed, or failed prompt keeps the model planning rather
- * than silently starting execution. OpenCode prose is anchored on the exact
- * prompt text. Every other result shape fails closed.
+ * An unanswered, dismissed, or failed prompt keeps the model planning.
  */
 export function createPlanApproved(output, isError, question) {
     if (isError)
         return false;
     const [segment] = parseAnswerSegments([createPlanApprovalItem(question)], output);
-    const answer = (segment ?? "").trim().toLowerCase();
-    return answer === CREATE_PLAN_APPROVAL_YES.toLowerCase();
+    return (segment ?? "").trim().toLowerCase() === CREATE_PLAN_APPROVAL_YES.toLowerCase();
 }
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -334,12 +342,14 @@ export function renderOpencodePlanMarkdown(args) {
  * Write the plan under {@link hostPlansDir} and return a `file://` URI.
  * Empty / missing content is the caller's responsibility (empty plan_uri ack).
  */
-export function writeOpencodePlanFile(args, workspaceRoot, created = Date.now()) {
+export function writeOpencodePlanFile(args, workspaceRoot, created = Date.now(), 
+/** Exact host-owned plan file; default is a new file under {@link hostPlansDir}. */
+target) {
     const markdown = renderOpencodePlanMarkdown(args);
     if (!markdown.trim()) {
         return { ok: false, error: "CreatePlan produced no plan content to write" };
     }
-    const planPath = resolveHostPlanPath(workspaceRoot, args.name, created);
+    const planPath = target ?? resolveHostPlanPath(workspaceRoot, args.name, created);
     try {
         mkdirSync(path.dirname(planPath), { recursive: true });
         writeFileSync(planPath, markdown, "utf-8");

package/dist/protocol/host-notes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Host notes (OpenCode `<system-update>` and read-tool instructions) in the
+ * shapes Cursor's own clients give model-visible context:
+ * - mid-turn, plain text in a `user_context` injection, as Cursor SDK
+ *   `Run.steer` sends it (no wrapper: wrapped text was refused live);
+ * - on a later user turn, a `<system_reminder>` block in the message text;
+ * - provider notices about one exec result, as postToolUse hook context.
+ */
+/** Cursor CLI rejects a hook additional_context longer than this. */
+export declare const HOOK_ADDITIONAL_CONTEXT_MAX_CHARS = 10000;
+/** Stable delivery order survives asynchronous acknowledgements and Run recovery. */
+export type HostNoteBatch = {
+    notes: string[];
+    order: number;
+};
+export type HookAdditionalContext = {
+    hook_event_name: string;
+    content: string;
+};
+/** Plain note text for one mid-turn injection, in host order. */
+export declare function hostNoteText(notes: readonly string[]): string;
+/**
+ * One postToolUse hook context per note, trimmed like Cursor CLI's carrier.
+ * A note over the CLI limit is split rather than dropped, so no text is lost.
+ */
+export declare function hostNoteHookContexts(notes: readonly string[]): HookAdditionalContext[];
+/** One `<system_reminder>` block per note, for a user turn's text. */
+export declare function wrapHostNoteForCursor(text: string): string;
+export declare function wrapHostNotesForCursor(notes: readonly string[]): string[];
+export declare function encodePersistedHostNotes(notes: readonly string[]): string | undefined;
+export declare function decodePersistedHostNotes(blob: string | undefined): string[];

package/dist/protocol/host-notes.js

@@ -0,0 +1,85 @@
+/**
+ * Host notes (OpenCode `<system-update>` and read-tool instructions) in the
+ * shapes Cursor's own clients give model-visible context:
+ * - mid-turn, plain text in a `user_context` injection, as Cursor SDK
+ *   `Run.steer` sends it (no wrapper: wrapped text was refused live);
+ * - on a later user turn, a `<system_reminder>` block in the message text;
+ * - provider notices about one exec result, as postToolUse hook context.
+ */
+const SYSTEM_UPDATE_BLOCK = /<system-update>([\s\S]*?)<\/system-update>/g;
+const SYSTEM_REMINDER_OPEN = "<system_reminder>";
+const SYSTEM_REMINDER_CLOSE = "</system_reminder>";
+/** Cursor CLI's hook event name for context attached to a tool result. */
+const POST_TOOL_USE_HOOK_EVENT = "postToolUse";
+/** Cursor CLI rejects a hook additional_context longer than this. */
+export const HOOK_ADDITIONAL_CONTEXT_MAX_CHARS = 10_000;
+/** Delimiter for ordered note bodies in the restart-snapshot `hostNote` string. */
+const HOST_NOTE_PERSIST_SEP = "\n\u001e\n";
+/** Plain note text for one mid-turn injection, in host order. */
+export function hostNoteText(notes) {
+    return notes.map(hostNoteBody).filter(Boolean).join("\n\n");
+}
+/**
+ * One postToolUse hook context per note, trimmed like Cursor CLI's carrier.
+ * A note over the CLI limit is split rather than dropped, so no text is lost.
+ */
+export function hostNoteHookContexts(notes) {
+    return notes.flatMap((note) => {
+        const body = hostNoteBody(note);
+        const chunks = [];
+        for (let start = 0; start < body.length;) {
+            let end = Math.min(body.length, start + HOOK_ADDITIONAL_CONTEXT_MAX_CHARS);
+            // Never split a surrogate pair.
+            if (end < body.length && /[\uD800-\uDBFF]/.test(body[end - 1]))
+                end--;
+            chunks.push(body.slice(start, end));
+            start = end;
+        }
+        return chunks.map((content) => ({ hook_event_name: POST_TOOL_USE_HOOK_EVENT, content }));
+    });
+}
+/** One `<system_reminder>` block per note, for a user turn's text. */
+export function wrapHostNoteForCursor(text) {
+    return `${SYSTEM_REMINDER_OPEN}\n${escapeReminderTags(hostNoteBody(text))}\n${SYSTEM_REMINDER_CLOSE}`;
+}
+export function wrapHostNotesForCursor(notes) {
+    return notes.filter((note) => hostNoteBody(note).length > 0).map(wrapHostNoteForCursor);
+}
+export function encodePersistedHostNotes(notes) {
+    const present = notes.filter((note) => note.length > 0);
+    if (present.length === 0)
+        return undefined;
+    return present.join(HOST_NOTE_PERSIST_SEP);
+}
+export function decodePersistedHostNotes(blob) {
+    if (!blob)
+        return [];
+    return blob.split(HOST_NOTE_PERSIST_SEP).filter((note) => note.length > 0);
+}
+/**
+ * Unwrap OpenCode `<system-update>` blocks. One host message may hold several
+ * (joined by `hostTailNote`); text that is not only such blocks stays as is.
+ */
+function hostNoteBody(text) {
+    const trimmed = text.trim();
+    const bodies = [];
+    let rest = trimmed;
+    for (const match of trimmed.matchAll(SYSTEM_UPDATE_BLOCK)) {
+        bodies.push(unescapeSystemUpdateText(match[1].trim()));
+        rest = rest.replace(match[0], "");
+    }
+    return bodies.length > 0 && rest.trim() === ""
+        ? bodies.filter(Boolean).join("\n\n")
+        : trimmed;
+}
+/**
+ * Inverse of OpenCode's `escapeSystemUpdateText` (`packages/llm/src/protocols/
+ * shared.ts`): it escapes `&`, `<`, `>` inside the wrapper. `&amp;` goes last.
+ */
+function unescapeSystemUpdateText(text) {
+    return text.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+}
+/** Same neutralization Cursor CLI applies to text placed inside its reminders. */
+function escapeReminderTags(text) {
+    return text.replace(/system_reminder/gi, "system_reminder_");
+}

package/dist/protocol/interactions.d.ts

@@ -14,6 +14,8 @@ export type HandledInteraction = {
     variantField: number;
     variantName: string;
     outcome: "rejected" | "acknowledged" | "failed" | "bridged" | "approved";
+    /** Decoded model call id, including refusals and lifecycle acknowledgments. */
+    toolCallId?: string;
     /**
      * Immediate reply for this query. Absent for bridged *synchronous* AskQuestion
      * or SwitchMode: Cursor blocks until the host tool returns, exactly as its own
@@ -31,24 +33,29 @@ export type HandledInteraction = {
      */
     switchMode?: DecodedSwitchModeQuery & {
         bridge: SwitchModeBridge;
-        toolName?: SwitchModeHostTool | "question";
+        toolName?: SwitchModeHostTool;
     };
     /**
-     * Present when CreatePlan needs a host tool: either a native plan stage that
-     * owns the write *and* the approval, or the emulated `question` prompt the
-     * provider raises after writing the plan itself. `planUri` is set only for
-     * the emulated path, where the provider already knows the file it wrote.
+     * Present when CreatePlan needs a host tool: a host plan-stage tool that
+     * owns the write *and* the review, the host's `plan_exit` review of the
+     * plan file the provider just wrote (`planUri` / `planPath` set), or the
+     * emulated `question` prompt after that write.
      */
     createPlan?: DecodedCreatePlanQuery & {
         bridge: CreatePlanBridge;
-        toolName: typeof CURSOR_PLAN_STAGE_TOOL | "question";
+        toolName: typeof CURSOR_PLAN_STAGE_TOOL | "plan_exit" | "question";
         planUri?: string;
-        /** Filesystem path of the plan the provider just wrote (emulated path). */
+        /** Filesystem path of the plan the provider just wrote. */
         planPath?: string;
         questionInput?: ReturnType<typeof createPlanApprovalQuestionInput>;
-        /** The plan to show the user before they approve it (emulated path only). */
+        /** The plan to show the user before the host review. */
         planReview?: string;
     };
+    /**
+     * Cursor tool call id of a CreatePlan the host plan agent will record
+     * instead. Nothing was written, so its display must not be mirrored as a plan.
+     */
+    deferredCreatePlanToolCallId?: string;
     /** Present when an image generation was approved: the target to expect. */
     generateImage?: DecodedGenerateImageQuery;
 };
@@ -81,16 +88,18 @@ export type HandleInteractionQueryOptions = {
     workspaceRoot?: string;
     /** True when the advertised host plan-stage tool is available. */
     canBridgeCreatePlan?: boolean;
-    /**
-     * True when the provider has recorded an approved Cursor plan/spec mode for
-     * this session. A written plan then ends with an execution-approval prompt,
-     * which is the transition out of planning; outside plan mode there is none.
-     */
+    /** An approved switch into the host `plan` agent waits for this Run to end. */
+    hostPlanEntryPending?: boolean;
+    /** Host primary agent this Run executes under, when the host reported it. */
+    hostAgent?: string;
+    /** Provider-recorded Cursor plan/spec mode for the CreatePlan execution gate. */
     planModeActive?: boolean;
+    /** The host's own plan file for this session, when the host defines one. */
+    hostPlanFile?: string;
     /**
      * Cursor unified mode currently recorded for this session. A SwitchMode to
      * the mode already in effect needs no approval, matching Cursor's own IDE
-     * handler and keeping the plan-approval prompt from firing twice.
+     * handler and keeping the host's plan review from running twice.
      */
     activeCursorModeId?: string;
 };
@@ -112,9 +121,9 @@ export declare function inspectInteractionQueryWire(agentServerPayload: Uint8Arr
  * Bridged / persisted exceptions:
  * - AskQuestion (#3) → OpenCode `question` tool
  * - SwitchMode (#4) → OpenCode `plan_enter` / `plan_exit` when advertised
- * - CreatePlan (#7) → host-calculated plan file via hostPlansDir (project-config
- *   `plans/` in a git worktree, else host global data/plans); empty args still
- *   get the CLI empty-`plan_uri` success ack
+ * - CreatePlan (#7) → the host's plan file (session `Session.plan` file when
+ *   known, else a new file under hostPlansDir); empty args still get the CLI
+ *   empty-`plan_uri` success ack
  * - GenerateImage (#12) → approve when `cursor_image_save` is advertised
  */
 export declare function handleInteractionQuery(query: Record<string, unknown>, agentServerPayload: Uint8Array, options?: HandleInteractionQueryOptions): HandledInteraction;