cursor-opencode-provider 0.7.4 → 0.7.6

package/README.md

@@ -293,6 +293,8 @@ OpenCode
 
 The provider adds OpenCode-specific system guidance to normal tool-capable conversations, including tool availability, canonical workspace-path grounding, preferring OpenCode `todowrite` / `todoread` over Cursor TodoWrite when those tools are advertised without inviting catalog-comparison narration, and preferring `edit` / `write` (or `apply_patch`, when the host advertises that instead) over shell-based file mutation when those tools are available. Compaction keeps its dedicated prompt unchanged.
 
+Cursor keeps OpenCode `skill` and configured MCP tools off its native top-level function list on **both** OpenCode 1.x and OpenCode 2.0 — they appear as MCP descriptors and are reached through GetDynamicTools / CallDynamicTool. When the host advertises `skill` and/or tools of MCP servers configured in `opencode.json`, the provider names those routes in system guidance and mirrors OpenCode's load-when-matches / do-not-reinvoke rules. Mid-Conversation skill reminders fire only when the available-skills catalog changes after baseline admission (same contract as OpenCode `SkillGuidance` / `SkillInstructions`) — not on every user turn that happens to mention a skill id — so models prefer `skill` / MCP over Grep/Shell and do not narrate that those tools are unavailable. OpenCode 2 still moves MCP servers that did not set `"codemode": true` onto the direct AI SDK catalog first; without that placement they never reach Cursor's MCP ads at all (see [OpenCode 2 MCP tools](docs/opencode-2.md#mcp-tools)).
+
 Native Cursor todo display updates (`update_todos_tool_call` / `read_todos_tool_call`) are mirrored into `todowrite` / `todoread` when those host tools are advertised. OpenCode 2 dropped the host builtins; set `CURSOR_OPENCODE2_TODOS=1` (or `true`) to register the same canonical names when the catalog omits them (in-memory per session, cleared on `session.deleted` and process restart). With the flag unset, the plugin registers no todo tools. Enabled plugin tools are **direct** catalog tools (`options.codemode: false` plus an `output` schema), not Code Mode helpers. The provider retains the last known full list per OpenCode session — refreshed by bridged writes, direct host `todowrite` calls, and `todoread` results, surviving Run close, checkpoint resume, and later turns — so `merge: true` updates that omit Cursor's completed list still become a host replace-all snapshot (matched by id, then by content across id spaces). This snapshot is in-memory only and never enters the prompt, RequestContext, or persisted restart state, so Cursor's prompt-cache prefix is unaffected; a provider process restart clears it until the next write/read (intentional — see `tasks/lessons.md`).
 
 If this guidance causes issues, update `buildOpenCodeInteractionGuidance` in [`src/language-model.ts`](src/language-model.ts) and its focused coverage in [`test/prompt-history.test.ts`](test/prompt-history.test.ts).

package/dist/context/build.d.ts

@@ -1,10 +1,16 @@
 import { type OpencodeToolDef } from "../protocol/tools.js";
+import { type OpencodeJson } from "./rules.js";
 export type BuildRequestContextInput = {
     workspaceRoot: string;
     tools?: OpencodeToolDef[];
     providerIdentifier?: string;
     /** When set, skills/subagents/plugins are epoch-held for this conversation. */
     conversationId?: string;
+    /**
+     * Preloaded merged `opencode.json` from the same Run (e.g. for interaction
+     * guidance MCP server ids). Skips a second `loadMergedConfig` disk read.
+     */
+    mergedConfig?: OpencodeJson;
 };
 export declare const DYNAMIC_REQUEST_CONTEXT_KEYS: readonly ["tools", "agent_skills", "custom_subagents", "mcp_file_system_options", "mcp_meta_tool_options", "web_search_enabled", "web_fetch_enabled", "agent_skills_info_complete", "custom_subagents_info_complete", "mcp_file_system_info_complete", "mcp_info_complete", "hooks_additional_context"];
 export type DynamicRequestContextKey = typeof DYNAMIC_REQUEST_CONTEXT_KEYS[number];

package/dist/context/build.js

@@ -67,7 +67,7 @@ function buildAdvertisedSubagentCatalog(hostSubagents, discoveredAgents) {
  */
 export async function buildRequestContext(input) {
     const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());
-    const { rules, config, worktree } = await collectRules(workspaceRoot);
+    const { rules, config, worktree } = await collectRules(workspaceRoot, input.mergedConfig);
     const [dynamic, git, layout] = await Promise.all([
         buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config),
         collectGit(workspaceRoot),
@@ -176,7 +176,9 @@ export async function buildDynamicRequestContext(input) {
     const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());
     const [worktree, config] = await Promise.all([
         findGitWorktree(workspaceRoot),
-        loadMergedConfig(workspaceRoot),
+        input.mergedConfig
+            ? Promise.resolve(input.mergedConfig)
+            : loadMergedConfig(workspaceRoot),
     ]);
     return buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config);
 }

package/dist/context/dynamic-catalog.d.ts

@@ -0,0 +1,74 @@
+export type AgentSkillLike = {
+    /** OpenCode skill id (frontmatter `name`, else directory name). */
+    id?: unknown;
+    full_path?: unknown;
+    description?: unknown;
+    content?: unknown;
+};
+/**
+ * Configured MCP servers that own at least one advertised tool. Uses the same
+ * server resolution as the RequestContext descriptors, so guidance never names
+ * a server Cursor was not given. `toolNames` are OpenCode ids (alias
+ * `sourceName` when present).
+ */
+export declare function listAdvertisedMcpServers(toolNames: Iterable<string>, knownMcpServers?: Iterable<string>): string[];
+/** Skill id OpenCode's `skill` tool expects: the discovered id, else `…/skills/<id>/SKILL.md`. */
+export declare function skillNameFromAgentSkill(skill: AgentSkillLike): string | undefined;
+/**
+ * Shared system-guidance line: name advertised dynamic-catalog tools and prefer
+ * them over Grep/Shell when skills or project rules apply. Concrete skill ids
+ * stay out of the frozen baseline (they live in RequestContext `agent_skills`
+ * and in Mid-Conversation updates when the catalog changes — same split as
+ * OpenCode's SkillGuidance / SkillInstructions).
+ */
+export declare function buildDynamicCatalogRoutingInstruction(options: {
+    toolNames: Iterable<string>;
+    knownMcpServers?: Iterable<string>;
+}): string | undefined;
+/**
+ * OpenCode-shaped Mid-Conversation skill update.
+ *
+ * Pure: compare `previousSkillIds` (null = not yet admitted this conversation)
+ * to the current catalog. First admission returns undefined — baseline
+ * RequestContext + routing instruction already carry the list. Later turns
+ * only speak when the id set changes (agent switch / discovery growth), matching
+ * `SkillGuidance.update` / `SkillInstructions.update`.
+ */
+export declare function buildSkillCatalogChangeReminder(options: {
+    hasSkillTool: boolean;
+    skills: readonly AgentSkillLike[];
+    /** Sorted skill ids already admitted; `null` means first admission this conversation. */
+    previousSkillIds: readonly string[] | null;
+    /**
+     * Host skill parameter key from the advertised schema.
+     * OpenCode 1.x: `name`. OpenCode 2.0: `id`.
+     */
+    skillArgKey?: "name" | "id";
+}): {
+    text: string | undefined;
+    nextSkillIds: string[];
+};
+/**
+ * Admit the current skill catalog for a conversation and return a Mid-Conversation
+ * reminder only when OpenCode would (catalog changed after baseline admission).
+ */
+export declare function takeSkillCatalogChangeReminder(conversationId: string, options: {
+    hasSkillTool: boolean;
+    skills: readonly AgentSkillLike[];
+    skillArgKey?: "name" | "id";
+}): string | undefined;
+export declare function clearSkillCatalogAdmission(conversationId: string): void;
+export declare function transferSkillCatalogAdmission(previousConversationId: string, nextConversationId: string): void;
+export declare function resetSkillCatalogAdmissionsForTests(): void;
+/**
+ * @deprecated Prefer `buildSkillCatalogChangeReminder` / `takeSkillCatalogChangeReminder`.
+ * Kept as a thin alias for callers that still expect the old name; always returns
+ * undefined for userText-based matching (OpenCode never did per-turn id nudges).
+ */
+export declare function buildSkillCatalogNudge(options: {
+    hasSkillTool: boolean;
+    skills: readonly AgentSkillLike[];
+    userText?: string;
+    skillArgKey?: "name" | "id";
+    previousSkillIds?: readonly string[] | null;
+}): string | undefined;

package/dist/context/dynamic-catalog.js

@@ -0,0 +1,228 @@
+import { resolveToolServerIdentity } from "../protocol/tools.js";
+/**
+ * Issue #29: Cursor keeps OpenCode `skill` and MCP tools off its native
+ * top-level function list. Both OpenCode 1.x and OpenCode 2.0 reach the model
+ * as MCP-shaped RequestContext ads, then GetDynamicTools / CallDynamicTool
+ * (exec `mcp_args`). This module builds the shared routing guidance and the
+ * OpenCode-shaped Mid-Conversation skill-catalog update used on both hosts.
+ *
+ * OpenCode itself does **not** per-turn nudge matched skill ids. It:
+ * - Puts name/description guidance in the frozen baseline (`SystemPrompt.skills`
+ *   / `SkillGuidance` / `SkillInstructions`)
+ * - Emits a Mid-Conversation update only when the available-skills list changes
+ * - OpenCode 2: skips re-invoke when `<skill_content>` is already in the turn
+ *
+ * OpenCode 2 still needs `exposeDirectMcpTools` so MCP tools leave Code Mode
+ * and enter the AI SDK catalog; without that step they never reach this
+ * advertisement path at all.
+ */
+const MAX_MCP_SERVERS_IN_GUIDANCE = 8;
+/** Synthetic server builtins and unknown tools are advertised under (`toolsToMcpDescriptors`). */
+const DEFAULT_TOOL_SERVER = "opencode";
+/**
+ * Skill ids already admitted to the model for a conversation (baseline RequestContext
+ * freeze, or the last Mid-Conversation catalog update). First admission is silent —
+ * OpenCode puts that list in the system baseline, not a per-turn reminder.
+ */
+const admittedSkillIdsByConversation = new Map();
+function listWithOverflow(items, limit) {
+    const shown = items.slice(0, limit).map((item) => `\`${item}\``).join(", ");
+    const hidden = items.length - limit;
+    return hidden > 0 ? `${shown} (+${hidden} more)` : shown;
+}
+/**
+ * Configured MCP servers that own at least one advertised tool. Uses the same
+ * server resolution as the RequestContext descriptors, so guidance never names
+ * a server Cursor was not given. `toolNames` are OpenCode ids (alias
+ * `sourceName` when present).
+ */
+export function listAdvertisedMcpServers(toolNames, knownMcpServers = []) {
+    const known = [...knownMcpServers];
+    if (known.length === 0)
+        return [];
+    const servers = new Set();
+    for (const name of toolNames) {
+        const { server } = resolveToolServerIdentity(name, DEFAULT_TOOL_SERVER, known);
+        if (server !== DEFAULT_TOOL_SERVER)
+            servers.add(server);
+    }
+    return [...servers];
+}
+/** Skill id OpenCode's `skill` tool expects: the discovered id, else `…/skills/<id>/SKILL.md`. */
+export function skillNameFromAgentSkill(skill) {
+    const id = typeof skill.id === "string" ? skill.id.trim() : "";
+    if (id)
+        return id;
+    const fullPath = typeof skill.full_path === "string" ? skill.full_path.trim() : "";
+    const parts = fullPath.split(/[\\/]+/).filter(Boolean);
+    if (parts.length < 2 || parts.at(-1).toLowerCase() !== "skill.md")
+        return undefined;
+    return parts.at(-2);
+}
+function skillIds(skills) {
+    const ids = [];
+    const seen = new Set();
+    for (const skill of skills) {
+        const name = skillNameFromAgentSkill(skill);
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        ids.push(name);
+    }
+    return [...ids].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+function sameIdList(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let i = 0; i < left.length; i++)
+        if (left[i] !== right[i])
+            return false;
+    return true;
+}
+/**
+ * Shared system-guidance line: name advertised dynamic-catalog tools and prefer
+ * them over Grep/Shell when skills or project rules apply. Concrete skill ids
+ * stay out of the frozen baseline (they live in RequestContext `agent_skills`
+ * and in Mid-Conversation updates when the catalog changes — same split as
+ * OpenCode's SkillGuidance / SkillInstructions).
+ */
+export function buildDynamicCatalogRoutingInstruction(options) {
+    const names = [...options.toolNames];
+    const hasSkill = names.includes("skill");
+    const mcpServers = listAdvertisedMcpServers(names, options.knownMcpServers);
+    if (!hasSkill && mcpServers.length === 0)
+        return undefined;
+    const extras = [];
+    if (hasSkill)
+        extras.push("`skill`");
+    if (mcpServers.length > 0) {
+        extras.push(`MCP servers such as ${listWithOverflow(mcpServers, MAX_MCP_SERVERS_IN_GUIDANCE)}`);
+    }
+    const lines = [
+        `- OpenCode host tools that are not in Cursor's native top-level list (including ${extras.join(" and ")}) ` +
+            "are reached through GetDynamicTools / CallDynamicTool (or the host's equivalent dynamic catalog). " +
+            "When a skill matches or project rules name an MCP server, discover and call those tools that way " +
+            "before Grep/Shell fallbacks. Do not narrate that they are unavailable.",
+    ];
+    if (hasSkill) {
+        // Mirror OpenCode 1 SystemPrompt.skills / OC2 SkillInstructions.render.
+        lines.push("- Skills provide specialized instructions and workflows for specific tasks. " +
+            "Use the `skill` tool to load a skill when a task matches its description " +
+            "(RequestContext `agent_skills` lists names and descriptions). " +
+            "A skill that is already present in the conversation as a `<skill_content>` block " +
+            "does not need to be invoked again.");
+    }
+    return lines.join("\n");
+}
+function skillEntriesXml(skills, argKey) {
+    const lines = ["<available_skills>"];
+    for (const skill of skills) {
+        const name = skillNameFromAgentSkill(skill);
+        if (!name)
+            continue;
+        const description = typeof skill.description === "string" ? skill.description : "";
+        lines.push("  <skill>");
+        if (argKey === "id")
+            lines.push(`    <id>${name}</id>`);
+        lines.push(`    <name>${name}</name>`);
+        if (description)
+            lines.push(`    <description>${description}</description>`);
+        lines.push("  </skill>");
+    }
+    lines.push("</available_skills>");
+    return lines;
+}
+/**
+ * OpenCode-shaped Mid-Conversation skill update.
+ *
+ * Pure: compare `previousSkillIds` (null = not yet admitted this conversation)
+ * to the current catalog. First admission returns undefined — baseline
+ * RequestContext + routing instruction already carry the list. Later turns
+ * only speak when the id set changes (agent switch / discovery growth), matching
+ * `SkillGuidance.update` / `SkillInstructions.update`.
+ */
+export function buildSkillCatalogChangeReminder(options) {
+    const nextSkillIds = skillIds(options.skills);
+    if (!options.hasSkillTool) {
+        return { text: undefined, nextSkillIds: options.previousSkillIds ? [...options.previousSkillIds] : [] };
+    }
+    if (options.previousSkillIds === null) {
+        return { text: undefined, nextSkillIds };
+    }
+    if (sameIdList(options.previousSkillIds, nextSkillIds)) {
+        return { text: undefined, nextSkillIds };
+    }
+    const argKey = options.skillArgKey === "id" ? "id" : "name";
+    const callHint = argKey === "id"
+        ? "Call `skill` with `{ \"id\": \"<skill-id>\" }` (host schema key is `id`)."
+        : "Call `skill` with `{ \"name\": \"<skill-id>\" }` (host schema key is `name`).";
+    const body = nextSkillIds.length === 0
+        ? ["Skill guidance is no longer available. Do not use any previously listed skill."]
+        : [
+            "The available skills have changed. This list supersedes the previous available skills list.",
+            "Skills provide specialized instructions and workflows for specific tasks.",
+            "Use the skill tool to load a skill when a task matches its description.",
+            "The user may also invoke a skill directly. When that happens, its instructions appear in the conversation as a <skill_content> block, the same shape the skill tool returns. A skill that is already present this way does not need to be invoked again.",
+            `OpenCode skills are invoked with the host \`skill\` tool through GetDynamicTools / CallDynamicTool (MCP server \`${DEFAULT_TOOL_SERVER}\`, tool \`skill\`), not by Grep/Read of SKILL.md. ${callHint}`,
+            ...skillEntriesXml(options.skills, argKey),
+        ];
+    return {
+        text: `<system_reminder>\n${body.join("\n")}\n</system_reminder>`,
+        nextSkillIds,
+    };
+}
+/**
+ * Admit the current skill catalog for a conversation and return a Mid-Conversation
+ * reminder only when OpenCode would (catalog changed after baseline admission).
+ */
+export function takeSkillCatalogChangeReminder(conversationId, options) {
+    const previous = conversationId
+        ? (admittedSkillIdsByConversation.get(conversationId) ?? null)
+        : null;
+    const { text, nextSkillIds } = buildSkillCatalogChangeReminder({
+        ...options,
+        previousSkillIds: previous,
+    });
+    if (!conversationId)
+        return text;
+    if (!options.hasSkillTool && previous === null && nextSkillIds.length === 0) {
+        return text;
+    }
+    admittedSkillIdsByConversation.delete(conversationId);
+    admittedSkillIdsByConversation.set(conversationId, nextSkillIds);
+    while (admittedSkillIdsByConversation.size > 256) {
+        const oldest = admittedSkillIdsByConversation.keys().next().value;
+        if (!oldest)
+            break;
+        admittedSkillIdsByConversation.delete(oldest);
+    }
+    return text;
+}
+export function clearSkillCatalogAdmission(conversationId) {
+    admittedSkillIdsByConversation.delete(conversationId);
+}
+export function transferSkillCatalogAdmission(previousConversationId, nextConversationId) {
+    if (!previousConversationId || !nextConversationId)
+        return;
+    const prior = admittedSkillIdsByConversation.get(previousConversationId);
+    admittedSkillIdsByConversation.delete(previousConversationId);
+    admittedSkillIdsByConversation.delete(nextConversationId);
+    if (prior)
+        admittedSkillIdsByConversation.set(nextConversationId, prior);
+}
+export function resetSkillCatalogAdmissionsForTests() {
+    admittedSkillIdsByConversation.clear();
+}
+/**
+ * @deprecated Prefer `buildSkillCatalogChangeReminder` / `takeSkillCatalogChangeReminder`.
+ * Kept as a thin alias for callers that still expect the old name; always returns
+ * undefined for userText-based matching (OpenCode never did per-turn id nudges).
+ */
+export function buildSkillCatalogNudge(options) {
+    return buildSkillCatalogChangeReminder({
+        hasSkillTool: options.hasSkillTool,
+        skills: options.skills,
+        previousSkillIds: options.previousSkillIds ?? null,
+        skillArgKey: options.skillArgKey,
+    }).text;
+}

package/dist/context/frozen.js

@@ -1,6 +1,7 @@
 import { buildDynamicRequestContext, buildRequestContext, materializeRequestContext, requestContextBase, } from "./build.js";
 import { clearContextEpoch, endContextEpoch, resetContextEpochsForTests } from "./epoch.js";
 import { clearOverlayHold, resetOverlayHoldsForTests, transferOverlayHold, } from "./overlay.js";
+import { clearSkillCatalogAdmission, resetSkillCatalogAdmissionsForTests, transferSkillCatalogAdmission, } from "./dynamic-catalog.js";
 import { trace } from "../debug.js";
 import { encodeMessage } from "../protocol/messages.js";
 /**
@@ -44,6 +45,7 @@ function remember(conversationId, context) {
         byConversationId.delete(oldest);
         materializedByConversationId.delete(oldest);
         clearOverlayHold(oldest);
+        clearSkillCatalogAdmission(oldest);
     }
 }
 /** Frozen stable RequestContext base for this conversation, if any. */
@@ -67,6 +69,7 @@ export function clearFrozenRequestContext(conversationId) {
     byConversationId.delete(conversationId);
     materializedByConversationId.delete(conversationId);
     clearOverlayHold(conversationId);
+    clearSkillCatalogAdmission(conversationId);
     clearContextEpoch(conversationId);
 }
 /**
@@ -89,6 +92,7 @@ export function transferFrozenRequestContext(previousConversationId, nextConvers
     // also drops epoch state for each id.
     endContextEpoch(previousConversationId, nextConversationId);
     transferOverlayHold(previousConversationId, nextConversationId);
+    transferSkillCatalogAdmission(previousConversationId, nextConversationId);
     byConversationId.delete(previousConversationId);
     materializedByConversationId.delete(previousConversationId);
     byConversationId.delete(nextConversationId);
@@ -110,6 +114,7 @@ export function resetFrozenRequestContextsForTests() {
     materializedByConversationId.clear();
     buildsByConversationId.clear();
     resetOverlayHoldsForTests();
+    resetSkillCatalogAdmissionsForTests();
     resetContextEpochsForTests();
 }
 function sameBytes(a, b) {

package/dist/context/index.d.ts

@@ -1,4 +1,5 @@
 export { buildDynamicRequestContext, buildRequestContext, DYNAMIC_REQUEST_CONTEXT_KEYS, materializeRequestContext, requestContextBase, type BuildRequestContextInput, } from "./build.js";
+export { buildDynamicCatalogRoutingInstruction, buildSkillCatalogChangeReminder, buildSkillCatalogNudge, takeSkillCatalogChangeReminder, listAdvertisedMcpServers, skillNameFromAgentSkill, type AgentSkillLike, } from "./dynamic-catalog.js";
 export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestContext, MAX_FROZEN_REQUEST_CONTEXTS, resetFrozenRequestContextsForTests, setFrozenRequestContext, transferFrozenRequestContext, } from "./frozen.js";
 export { MAX_OVERLAY_HOLDS, holdCapabilityOverlay, resetOverlayHoldsForTests, } from "./overlay.js";
 export { admitContextEpoch, appendMidConversationMessage, clearContextEpoch, endContextEpoch, getContextEpoch, MAX_CONTEXT_EPOCHS, resetContextEpochsForTests, type AdmitContextEpochInput, type AdmitContextEpochResult, type ContextEpoch, type ContextSourceSnapshot, } from "./epoch.js";

package/dist/context/index.js

@@ -1,4 +1,5 @@
 export { buildDynamicRequestContext, buildRequestContext, DYNAMIC_REQUEST_CONTEXT_KEYS, materializeRequestContext, requestContextBase, } from "./build.js";
+export { buildDynamicCatalogRoutingInstruction, buildSkillCatalogChangeReminder, buildSkillCatalogNudge, takeSkillCatalogChangeReminder, listAdvertisedMcpServers, skillNameFromAgentSkill, } from "./dynamic-catalog.js";
 export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestContext, MAX_FROZEN_REQUEST_CONTEXTS, resetFrozenRequestContextsForTests, setFrozenRequestContext, transferFrozenRequestContext, } from "./frozen.js";
 export { MAX_OVERLAY_HOLDS, holdCapabilityOverlay, resetOverlayHoldsForTests, } from "./overlay.js";
 export { admitContextEpoch, appendMidConversationMessage, clearContextEpoch, endContextEpoch, getContextEpoch, MAX_CONTEXT_EPOCHS, resetContextEpochsForTests, } from "./epoch.js";

package/dist/context/overlay.d.ts

@@ -39,6 +39,11 @@ export type OverlayWire = {
 };
 /** Merge live discovery into the conversation overlay epoch. */
 export declare function holdCapabilityOverlay(conversationId: string, live: OverlayHold): OverlayWire;
+/**
+ * Epoch-held skills with their OpenCode ids. The wire shape drops `id`
+ * (`AgentSkill` has no name field), but the host `skill` tool needs it.
+ */
+export declare function getHeldOverlaySkills(conversationId: string): OverlaySkill[];
 export declare function clearOverlayHold(conversationId: string): void;
 export declare function transferOverlayHold(previousConversationId: string, nextConversationId: string): void;
 export declare function resetOverlayHoldsForTests(): void;

package/dist/context/overlay.js

@@ -78,6 +78,13 @@ export function holdCapabilityOverlay(conversationId, live) {
     }
     return toWire(remember(conversationId, next));
 }
+/**
+ * Epoch-held skills with their OpenCode ids. The wire shape drops `id`
+ * (`AgentSkill` has no name field), but the host `skill` tool needs it.
+ */
+export function getHeldOverlaySkills(conversationId) {
+    return structuredClone(byConversationId.get(conversationId)?.skills ?? []);
+}
 export function clearOverlayHold(conversationId) {
     byConversationId.delete(conversationId);
 }

package/dist/context/rules.d.ts

@@ -17,8 +17,9 @@ export declare function fetchRemoteInstruction(url: string, timeoutMs?: number):
 export declare function loadMergedConfig(workspaceRoot: string): Promise<OpencodeJson>;
 /**
  * Collect OpenCode instruction files.
+ * `preloadedConfig` reuses a merged config already loaded on this Run.
  */
-export declare function collectRules(workspaceRoot: string): Promise<{
+export declare function collectRules(workspaceRoot: string, preloadedConfig?: OpencodeJson): Promise<{
     rules: CollectedRule[];
     config: OpencodeJson;
     worktree: string;

package/dist/context/rules.js

@@ -178,12 +178,13 @@ export async function loadMergedConfig(workspaceRoot) {
 }
 /**
  * Collect OpenCode instruction files.
+ * `preloadedConfig` reuses a merged config already loaded on this Run.
  */
-export async function collectRules(workspaceRoot) {
+export async function collectRules(workspaceRoot, preloadedConfig) {
     const worktree = await findGitWorktree(workspaceRoot);
     const rules = [];
     const seen = new Set();
-    const config = await loadMergedConfig(workspaceRoot);
+    const config = preloadedConfig ?? await loadMergedConfig(workspaceRoot);
     const add = async (file) => {
         if (!file)
             return;

package/dist/image-save.d.ts

@@ -55,4 +55,4 @@ export declare function resolveContainedImagePath(target: string, allowedRoots:
  */
 export declare function executeCursorImageSave(args: {
     image_id?: unknown;
-}, ctx: ImageSaveToolContext): Promise<ImageSaveResult | string>;
+}, ctx: ImageSaveToolContext): Promise<ImageSaveResult>;

package/dist/image-save.js

@@ -106,18 +106,18 @@ function isInsideProject(target, worktree, directory) {
 export async function executeCursorImageSave(args, ctx) {
     const imageId = typeof args.image_id === "string" ? args.image_id : "";
     if (!imageId)
-        return "No image id was provided, so there is nothing to save.";
+        throw new Error("No image id was provided, so there is nothing to save.");
     const image = takePendingCursorImage(imageId);
     if (!image) {
         // Expired, already committed, or never existed. Identical response for all
         // three: nothing here should confirm whether an id was ever valid.
-        return "No pending Cursor image matches that id. It may have already been saved or expired.";
+        throw new Error("No pending Cursor image matches that id. It may have already been saved or expired.");
     }
     const workspace = ctx.worktree || ctx.directory;
     const contained = resolveContainedImagePath(image.path, [image.projectDir, workspace].filter((root) => !!root));
     if ("error" in contained) {
         trace(`image save: refused path=${JSON.stringify(image.path)} reason=${contained.error}`);
-        return `Refusing to save the generated image: ${contained.error}.`;
+        throw new Error(`Refusing to save the generated image: ${contained.error}.`);
     }
     // Mirror what OpenCode's own `write` tool does, in the same order: an
     // external-directory gate for targets outside the project, then the `edit`

package/dist/image-staging.js

@@ -25,7 +25,12 @@ export const MAX_STAGED_IMAGE_BYTES = 50 * 1024 * 1024;
 export const STAGED_IMAGE_TTL_MS = 10 * 60_000;
 /** Bounds memory if a turn generates several images and none are committed. */
 const MAX_PENDING = 8;
-const pending = new Map();
+// Some hosts load the model and the image-save subpath in separate module
+// graphs. Keep the one-use handles in the process registry so both graphs see
+// the same staged bytes. The UUID handle remains the only tool input.
+const PENDING_IMAGES = Symbol.for("cursor-opencode-provider.pending-images");
+const globals = globalThis;
+const pending = globals[PENDING_IMAGES] ??= new Map();
 export class StagedImageTooLargeError extends Error {
     constructor(bytes) {
         super(`Generated image is ${bytes} bytes, above the ${MAX_STAGED_IMAGE_BYTES} byte limit`);

package/dist/language-model.d.ts

@@ -68,6 +68,24 @@ export declare function findContinuationSession(toolResults: Array<{
     sessionId: string;
     execId: number;
 }>): CursorSession | undefined;
+/**
+ * True when `incoming` is a non-empty proper subset of `parent` by tool name.
+ * Used to spot in-session helpers that reuse the parent OpenCode session id
+ * with a reduced catalog (e.g. stripping `task` / `question` / `plan_exit`).
+ */
+export declare function isProperCatalogSubset(incoming: ReadonlyArray<{
+    name?: string;
+}>, parent: ReadonlyArray<{
+    name?: string;
+}>): boolean;
+/**
+ * An open parent Run for this OpenCode session whose catalog strictly contains
+ * the incoming tools is treated as an in-session helper. Those calls must not
+ * cancel/supersede the parent (that remints on the trailing tool result).
+ */
+export declare function shouldIsolateInSessionHelper(openCodeSessionId: string | undefined, incomingTools: ReadonlyArray<{
+    name?: string;
+}>): boolean;
 /** How long a fresh-turn drain may wait for Cursor `turn_ended` after bridged settle. */
 export declare const FRESH_TURN_DRAIN_TIMEOUT_MS = 8000;
 /**
@@ -133,6 +151,8 @@ type ExtractedToolResult = {
  * are ignored — they are conversation history, not replies for a held-open Run.
  */
 export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOptions["prompt"]): ExtractedToolResult[];
+/** Detect a host-owned canonical plan review, excluding Cursor exec replies. */
+export declare function hasApprovedUncorrelatedPlanStageResult(prompt: LanguageModelV3CallOptions["prompt"]): boolean;
 /**
  * Checkpointed Runs do not resend the system prompt. Keep the workspace root
  * on the live user message, and require absolute `path` arguments when that is
@@ -147,7 +167,9 @@ export declare function groundCheckpointTurnText(userText: string, checkpoint: b
  * Redirect only to OpenCode tools that are genuinely advertised this turn;
  * compaction keeps its dedicated summary prompt unchanged.
  */
-export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean, workspaceRoot: string): string | undefined;
+export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean, workspaceRoot: string, options?: {
+    knownMcpServers?: Iterable<string>;
+}): string | undefined;
 /** Rough char→token estimate for mid-turn usage before TurnEnded arrives. */
 export declare function estimateTokens(chars: number): number;
 /** Preserve exact request-local Cursor counters as diagnostics. */