cursor-opencode-provider 0.7.3 → 0.7.5

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. When the host permits `skill` this turn and the user message names a discovered skill id, matches its description, or asks which skills are available, it also appends a Mid-Conversation reminder with those skill ids, 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,43 @@
+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
+ * are deliberately absent: this line is part of the frozen baseline system
+ * context, and per-turn ids go through `buildSkillCatalogNudge` instead.
+ */
+export declare function buildDynamicCatalogRoutingInstruction(options: {
+    toolNames: Iterable<string>;
+    knownMcpServers?: Iterable<string>;
+}): string | undefined;
+/**
+ * Mid-Conversation nudge after RequestContext skills are known. Prefer skills
+ * that match the user turn; otherwise stay quiet unless the user asked about
+ * skills explicitly (avoids dumping dozens of firecrawl-* ids every turn).
+ * `hasSkillTool` must reflect what the host permits this turn, not the
+ * epoch-held advertisement.
+ */
+export declare function buildSkillCatalogNudge(options: {
+    hasSkillTool: boolean;
+    skills: readonly AgentSkillLike[];
+    userText?: string;
+    /**
+     * Host skill parameter key from the advertised schema.
+     * OpenCode 1.x: `name`. OpenCode 2.0: `id`.
+     */
+    skillArgKey?: "name" | "id";
+}): string | undefined;

package/dist/context/dynamic-catalog.js

@@ -0,0 +1,183 @@
+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
+ * skill-aware Mid-Conversation nudge used on both hosts.
+ *
+ * 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_NAMED_SKILLS = 8;
+const MAX_MCP_SERVERS_IN_GUIDANCE = 8;
+/** Synthetic server builtins and unknown tools are advertised under (`toolsToMcpDescriptors`). */
+const DEFAULT_TOOL_SERVER = "opencode";
+/** Common words that carry no skill-matching signal. */
+const STOPWORDS = new Set([
+    "about", "all", "and", "any", "are", "but", "can", "for", "from", "has", "have",
+    "how", "into", "its", "not", "one", "only", "that", "the", "their", "them",
+    "then", "there", "these", "this", "use", "used", "uses", "using", "via", "was",
+    "what", "when", "which", "who", "why", "will", "with", "you", "your",
+    // Host/MCP instruction boilerplate — otherwise a server-instruction dump
+    // matches every firecrawl/search skill on "search"/"tools"/"server".
+    "tool", "tools", "server", "servers", "call", "calls", "fetch", "search",
+    "documentation", "library", "framework", "query", "please", "through",
+]);
+/** An explicit question/request about skills, not incidental prose ("has the skills to"). */
+const SKILL_INQUIRY = /\b(?:which|what|list|show|available|any|use|using|call|invoke|load|run)\b[^.?!\n]{0,40}\bskills?\b|\bskills?\b[^.?!\n]{0,40}\b(?:available|installed|loaded|exist|do you have|can you)\b/i;
+/** Description-only hits above this look like instruction-dump false positives. */
+const MAX_DESCRIPTION_ONLY_MATCHES = 2;
+/**
+ * Match against the live user utterance only. Mid-conversation / MCP instruction
+ * injections and prior reminders must not re-trigger skill dumps.
+ */
+function skillMatchCorpus(userText) {
+    return userText
+        .replace(/<system_reminder\b[^>]*>[\s\S]*?<\/system_reminder>/gi, " ")
+        .replace(/<system-update\b[^>]*>[\s\S]*?<\/system-update>/gi, " ")
+        .replace(/New MCP server instructions[\s\S]*?(?=\n[A-Z]|\n\n|$)/gi, " ");
+}
+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);
+}
+/**
+ * Shared system-guidance line: name advertised dynamic-catalog tools and prefer
+ * them over Grep/Shell when skills or project rules apply. Concrete skill ids
+ * are deliberately absent: this line is part of the frozen baseline system
+ * context, and per-turn ids go through `buildSkillCatalogNudge` instead.
+ */
+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)}`);
+    }
+    return (`- 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.");
+}
+function wordTokens(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length >= 3 && !STOPWORDS.has(token)));
+}
+function descriptionMatchesUserText(description, userTokens) {
+    let hits = 0;
+    let distinctive = false;
+    for (const token of wordTokens(description)) {
+        if (!userTokens.has(token))
+            continue;
+        hits += 1;
+        if (token.length >= 8)
+            distinctive = true;
+        if (hits >= 2)
+            return true;
+    }
+    // Single distinctive token (library names, skill ids) is enough.
+    return distinctive;
+}
+function nameMatchesUserText(name, userText) {
+    const haystack = userText.toLowerCase();
+    const candidates = [name.toLowerCase(), ...name.toLowerCase().split(/[-_]+/).filter((part) => part.length >= 5)];
+    for (const candidate of [...new Set(candidates)]) {
+        const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        if (new RegExp(`(?<![a-z0-9_-])${escaped}(?![a-z0-9_-])`).test(haystack))
+            return true;
+    }
+    return false;
+}
+/**
+ * Mid-Conversation nudge after RequestContext skills are known. Prefer skills
+ * that match the user turn; otherwise stay quiet unless the user asked about
+ * skills explicitly (avoids dumping dozens of firecrawl-* ids every turn).
+ * `hasSkillTool` must reflect what the host permits this turn, not the
+ * epoch-held advertisement.
+ */
+export function buildSkillCatalogNudge(options) {
+    if (!options.hasSkillTool || options.skills.length === 0)
+        return undefined;
+    const userText = skillMatchCorpus(options.userText ?? "");
+    const userTokens = wordTokens(userText);
+    const skillInquiry = SKILL_INQUIRY.test(userText);
+    const named = options.skills
+        .map((skill) => {
+        const name = skillNameFromAgentSkill(skill);
+        if (!name)
+            return undefined;
+        const description = typeof skill.description === "string" ? skill.description : "";
+        const nameHit = nameMatchesUserText(name, userText);
+        const descHit = !!description && descriptionMatchesUserText(description, userTokens);
+        return { name, nameHit, descHit };
+    })
+        .filter((row) => !!row);
+    if (named.length === 0)
+        return undefined;
+    const nameMatched = named.filter((row) => row.nameHit);
+    const descOnly = named.filter((row) => row.descHit && !row.nameHit);
+    // Mass description-only hits are almost always instruction-dump noise
+    // (MCP server blurbs sharing "search"/"tools" with firecrawl skills).
+    const descMatched = descOnly.length <= MAX_DESCRIPTION_ONLY_MATCHES ? descOnly : [];
+    const selected = nameMatched.length > 0
+        ? [...nameMatched, ...descMatched]
+        : skillInquiry
+            ? named
+            : descMatched;
+    if (selected.length === 0)
+        return undefined;
+    const ids = [...new Set(selected.map((row) => row.name))];
+    // Prefer the advertised schema key; fall back to naming both so a stale
+    // Mid-Conversation hint cannot contradict GetDynamicTools on either host.
+    const argKey = options.skillArgKey;
+    const callHint = argKey
+        ? `Call \`skill\` with \`{ "${argKey}": "<skill-id>" }\` (host schema key is \`${argKey}\`) `
+        : "Call `skill` with the skill identifier using the parameter key from GetDynamicTools " +
+            "(`name` on OpenCode 1.x, `id` on OpenCode 2.0) ";
+    return ("<system_reminder>\n" +
+        "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. ` +
+        `Relevant skill id(s) this turn: ${listWithOverflow(ids, MAX_NAMED_SKILLS)}. ` +
+        callHint +
+        "before answering from memory or falling back to shell/search tools.\n" +
+        "</system_reminder>");
+}

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, buildSkillCatalogNudge, 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, buildSkillCatalogNudge, 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

@@ -133,6 +133,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 +149,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. */

package/dist/language-model.js

@@ -32,6 +32,9 @@ import { resolveContinuationPolicy, sessionManager, } from "./session.js";
 import { CursorAuthError, CursorLocalCancellationError, CursorProtocolError, CursorProviderError, CursorRetryExhaustedError, CursorServerError, CursorTransportError, isTransientGrpcStatus, retrySuppressedError, toCursorProviderError, } from "./errors.js";
 import { readCache, cacheFilePath, resolveVariantParameters, resolveVariantMaxMode, extractCursorVariantParameters, resolveCursorWireModelId } from "./models.js";
 import { getOrBuildRequestContext } from "./context/frozen.js";
+import { getHeldOverlaySkills } from "./context/overlay.js";
+import { loadMergedConfig } from "./context/rules.js";
+import { buildDynamicCatalogRoutingInstruction, buildSkillCatalogNudge, } from "./context/dynamic-catalog.js";
 import { admitContextEpoch, appendMidConversationMessage, resetContextEpochsForTests, } from "./context/epoch.js";
 import { workspaceRootFromRequestContext } from "./context/env.js";
 import { ensureOpencodeProjectDir, opencodeGlobalCacheDir, setHostCacheDirOverride, } from "./context/paths.js";
@@ -507,6 +510,12 @@ async function doStreamImpl(modelId, options, callOptions) {
     // false "orphaned tool results" errors after Cursor turn_ended and OpenCode
     // started the next step with old tools still in the prompt body.
     const trailingToolResults = extractTrailingToolResults(prompt);
+    // A host may submit an already rendered plan through its canonical stage
+    // tool after the Cursor Run has ended. The next call carries that tool result
+    // without a Cursor exec id; reconcile the approved mode before a fresh Run.
+    if (hasApprovedUncorrelatedPlanStageResult(prompt)) {
+        setActiveCursorMode(opencodeSessionKey(callOptions), "agent");
+    }
     let session = findContinuationSession(trailingToolResults);
     if (session) {
         // Write pending results onto the held-open Run. A dead stream closes the
@@ -801,15 +810,22 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     // v1 sets `options.workspaceRoot` correctly per invocation (`input.directory`,
     // one plugin instance per project). OpenCode 2.0 runs one daemon across many
     // projects, so its static option is only a last-resort fallback. Prefer the
-    // per-request `x-opencode-directory` header, then the session mark recorded
-    // from `session.hook("context")` via `getSessionDirectory`.
+    // per-request `x-opencode-directory` header (set by the 2.0 plugin's
+    // `session.hook("model.request")`), then the session mark recorded from the
+    // session hooks via `getSessionDirectory`.
     const workspaceRoot = resolveSessionWorkspaceRoot({
         sessionKey,
         headers: callOptions.headers,
         workspaceRoot: options.workspaceRoot,
     });
     const baseSystemPrompt = extractSystemPrompt(prompt);
-    const interactionGuidance = buildOpenCodeInteractionGuidance(cursorTools, isCompaction, workspaceRoot);
+    // One merged-config load per Run: guidance MCP ids and RequestContext
+    // descriptors must agree, and warm turns must not pay for a second disk read.
+    const mergedConfig = isCompaction ? undefined : await loadMergedConfig(workspaceRoot);
+    const knownMcpServers = Object.keys(mergedConfig?.mcp ?? {});
+    const interactionGuidance = buildOpenCodeInteractionGuidance(cursorTools, isCompaction, workspaceRoot, {
+        knownMcpServers,
+    });
     // Prompt-identity diagnostics are filled after Context Epoch admission below
     // (baseline hash is the epoch baseline, not a per-turn host hash).
     let frozenSystemPromptHash;
@@ -864,6 +880,9 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     let userText = recovery?.kind === "rebase"
         ? "Continue the interrupted turn from the conversation history above. Do not repeat completed work."
         : (extractUserText(lastUser) || ".");
+    // Skill matching must see the live user utterance only — not Mid-Conversation
+    // MCP/system injections appended below (those false-trigger firecrawl dumps).
+    const skillMatchText = userText;
     // After an approved SwitchMode, inject the Cursor CLI-shaped mode reminder
     // (same <system_reminder> contract the CLI uses after flipping unifiedMode).
     const startedWithCheckpoint = !!conversationState;
@@ -987,7 +1006,22 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     });
     // Freeze RequestContext per conversation_id (CLI parity). Rebuilding every
     // Run mutates volatile slices (git porcelain, layout) and breaks prompt cache.
-    const { context: requestContext, reused: requestContextReused } = await getOrBuildRequestContext(conversationId, { workspaceRoot, tools: cursorTools });
+    const { context: requestContext, reused: requestContextReused } = await getOrBuildRequestContext(conversationId, { workspaceRoot, tools: cursorTools, mergedConfig });
+    // Issue #29: after skills are in RequestContext, nudge matched skill ids onto
+    // the Mid-Conversation channel so models CallDynamicTool(`skill`) instead of
+    // Grep/Read SKILL.md. Shared by OpenCode 1.x and 2.0 catalogs. Gate on the
+    // host-permitted set, not the epoch-held advertisement: a turn that withheld
+    // `skill` would refuse the call this nudge asks for.
+    if (!isCompaction && !lifecycle) {
+        const skillDialect = hostToolDialectFromTools(tools, options.defaultDialect);
+        const skillNudge = buildSkillCatalogNudge({
+            hasSkillTool: allowTools && incomingTools.some((tool) => tool.name === "skill"),
+            skills: getHeldOverlaySkills(conversationId),
+            userText: skillMatchText,
+            skillArgKey: skillDialect.skillArgKey,
+        });
+        userText = appendMidConversationMessage(userText, skillNudge);
+    }
     const contextSubagents = Array.isArray(requestContext.custom_subagents)
         ? requestContext.custom_subagents
             .map((agent) => agent && typeof agent === "object" && typeof agent.name === "string"
@@ -1097,7 +1131,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     }
     const hostToolDialect = hostToolDialectFromTools(tools, options.defaultDialect);
     trace(`host tool dialect: filePathKey=${hostToolDialect.filePathKey} shellTool=${hostToolDialect.shellTool} ` +
-        `tools=[${tools.map((t) => t.name).join(",")}]`);
+        `skillArgKey=${hostToolDialect.skillArgKey} tools=[${tools.map((t) => t.name).join(",")}]`);
     const session = {
         sessionId: crypto.randomUUID(),
         conversationId,
@@ -1836,6 +1870,14 @@ export function deliverContinuationResults(session, trailingToolResults) {
                 });
             }
         }
+        // A directly called advertised plan-stage tool can own the same review
+        // gate as a bridged CreatePlan. Its successful result means execution was
+        // approved, so the next Run must carry agent-mode guidance.
+        if (!pending.bridged
+            && pending.toolName === CURSOR_PLAN_STAGE_TOOL
+            && r.error === undefined) {
+            setActiveCursorMode(session.openCodeSessionId, "agent");
+        }
         // A host `todoread` result is the authoritative list. Refresh the mirrored
         // snapshot (direct reads and bridged native reads alike) so later merges
         // apply onto host truth, not a stale write.
@@ -2864,7 +2906,7 @@ export async function pump(session, controller, ids, abortSignal) {
                                 imageId = stageCursorImage({
                                     path: target,
                                     projectDir,
-                                    mime: imageMimeForPath(target),
+                                    mime: imageMimeForPath(target, binaryWrite.data),
                                     data: binaryWrite.data,
                                     sessionId: session.openCodeSessionId,
                                 });
@@ -3299,6 +3341,25 @@ export function extractTrailingToolResults(prompt) {
         return [];
     return extractToolResults(prompt.slice(i + 1));
 }
+/** Detect a host-owned canonical plan review, excluding Cursor exec replies. */
+export function hasApprovedUncorrelatedPlanStageResult(prompt) {
+    if (prompt.length === 0 || prompt[prompt.length - 1].role !== "tool")
+        return false;
+    for (let i = prompt.length - 1; i >= 0 && prompt[i].role === "tool"; i--) {
+        const message = prompt[i];
+        if (!Array.isArray(message.content))
+            continue;
+        for (const part of message.content) {
+            if (part.type !== "tool-result" || part.toolName !== CURSOR_PLAN_STAGE_TOOL)
+                continue;
+            if (parseExecIdFromToolCallId(part.toolCallId))
+                continue;
+            const result = toolResultOutputToText(part.output);
+            return !result.isError;
+        }
+    }
+    return false;
+}
 function toolResultOutputToText(output) {
     if (output == null)
         return { text: "", isError: false };
@@ -3351,7 +3412,7 @@ export function groundCheckpointTurnText(userText, checkpoint, workspaceRoot, to
  * Redirect only to OpenCode tools that are genuinely advertised this turn;
  * compaction keeps its dedicated summary prompt unchanged.
  */
-export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceRoot) {
+export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceRoot, options = {}) {
     if (isCompaction)
         return undefined;
     const names = new Set(tools.map((tool) => tool.name));
@@ -3406,7 +3467,7 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
         instructions.push(shell
             ? `- OpenCode \`execute\` is Code Mode JavaScript (\`code\`); it is not a shell. For OS commands, call OpenCode ${shell}. Do not pass \`command\` to \`execute\`.`
             : "- OpenCode `execute` is Code Mode JavaScript (`code`); it is not a shell. Do not pass `command` to `execute`.");
-        instructions.push("- When the host's Code Mode catalog lists additional tools, including MCP server tools, call them inside `execute` through `tools`. Use only the exact paths and signatures in that catalog or returned by its `search` function. Call `execute` with `{ code }` to run them; do not request a Code Mode tool as a direct OpenCode tool call.");
+        instructions.push("- Call tools named in the direct list by their own names, even when a server instruction says to reach them through `execute`. Use `execute` only for tools that appear in the host Code Mode catalog and are absent from that list. Use the exact paths and signatures from that catalog or its `search` function, and call `execute` with `{ code }`.");
     }
     if (names.has("task") || names.has("subagent")) {
         const target = names.has("task") ? "`task`" : "`subagent`";
@@ -3419,6 +3480,16 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
             instructions.push("- Host `scout` is available for external documentation and dependency-source research. Use Cursor `cursor-guide` for that use case; local repository discovery still uses `bugbot`/`explore`.");
         }
     }
+    // Issue #29: skill/MCP stay off Cursor's native top-level list on both
+    // OpenCode 1.x and 2.0 — route them through the dynamic catalog instead.
+    {
+        const dynamicCatalog = buildDynamicCatalogRoutingInstruction({
+            toolNames: tools.map((tool) => tool.sourceName ?? tool.name),
+            knownMcpServers: options.knownMcpServers,
+        });
+        if (dynamicCatalog)
+            instructions.push(dynamicCatalog);
+    }
     if (names.has("write")) {
         instructions.push(names.has("edit")
             ? "- For file changes, use OpenCode `edit` for targeted changes to existing files and `write` to create files or intentionally replace complete contents; do not use shell, Python, or heredocs to change file content while these tools are available."

package/dist/opencode2/mcp-direct.d.ts

@@ -0,0 +1,31 @@
+import type { ToolDraft } from "./types.js";
+/**
+ * OpenCode 2 puts an MCP server's tools in Code Mode unless that server's
+ * config sets `codemode: false` (`packages/schema/src/mcp.ts`, applied in
+ * `packages/core/src/tool/mcp.ts`). Only `options.codemode === false` joins
+ * the AI SDK catalog (`packages/core/src/tool.ts`). This provider can advertise
+ * a tool to Cursor only when it is in that catalog.
+ *
+ * That AI SDK placement is necessary but not sufficient for Cursor models:
+ * non-native tools are still invoked through GetDynamicTools / CallDynamicTool
+ * (see `src/context/dynamic-catalog.ts`, issue #29). Classic OpenCode 1.x already
+ * puts MCP tools in the AI SDK catalog; this module is the OpenCode 2 equivalent.
+ *
+ * `config.codemode` is also the remote-connection switch: while it is not
+ * false, OpenCode appends `?codemode=false` so servers that bundle their own
+ * Code Mode return individual tools (`packages/core/src/mcp/client.ts`).
+ * This module therefore leaves server config alone and clears the tool option
+ * instead. An explicit server `codemode: true` stays in Code Mode. OpenCode's
+ * own namespaced tools (the `opencode` namespace) are not MCP servers and are
+ * left alone.
+ *
+ * The tool registry is location-scoped, so this placement is shared by every
+ * provider in the process. `"codemode": true` on a server is the per-server
+ * way to keep that server inside `execute`.
+ */
+export declare function mcpServerNamespace(server: string): string;
+export declare function rememberDirectMcpNamespaces(target: Set<string>, servers: readonly (readonly [string, {
+    readonly codemode?: boolean;
+}])[]): void;
+/** Move tools from the recorded MCP namespaces onto the direct catalog. */
+export declare function exposeDirectMcpTools(editor: ToolDraft, namespaces: ReadonlySet<string>): void;

package/dist/opencode2/mcp-direct.js

@@ -0,0 +1,65 @@
+/**
+ * OpenCode 2 puts an MCP server's tools in Code Mode unless that server's
+ * config sets `codemode: false` (`packages/schema/src/mcp.ts`, applied in
+ * `packages/core/src/tool/mcp.ts`). Only `options.codemode === false` joins
+ * the AI SDK catalog (`packages/core/src/tool.ts`). This provider can advertise
+ * a tool to Cursor only when it is in that catalog.
+ *
+ * That AI SDK placement is necessary but not sufficient for Cursor models:
+ * non-native tools are still invoked through GetDynamicTools / CallDynamicTool
+ * (see `src/context/dynamic-catalog.ts`, issue #29). Classic OpenCode 1.x already
+ * puts MCP tools in the AI SDK catalog; this module is the OpenCode 2 equivalent.
+ *
+ * `config.codemode` is also the remote-connection switch: while it is not
+ * false, OpenCode appends `?codemode=false` so servers that bundle their own
+ * Code Mode return individual tools (`packages/core/src/mcp/client.ts`).
+ * This module therefore leaves server config alone and clears the tool option
+ * instead. An explicit server `codemode: true` stays in Code Mode. OpenCode's
+ * own namespaced tools (the `opencode` namespace) are not MCP servers and are
+ * left alone.
+ *
+ * The tool registry is location-scoped, so this placement is shared by every
+ * provider in the process. `"codemode": true` on a server is the per-server
+ * way to keep that server inside `execute`.
+ */
+export function mcpServerNamespace(server) {
+    return server.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+export function rememberDirectMcpNamespaces(target, servers) {
+    target.clear();
+    // The editor exposes normalized namespaces, not server ownership. Keep
+    // ambiguous namespaces in their host-selected placement: otherwise a server
+    // named `opencode` moves builtins too, or `my.docs` overrides an explicit
+    // Code Mode choice on `my_docs`. Exclusions must win regardless of order.
+    const excluded = new Set(["opencode"]);
+    for (const [name, config] of servers) {
+        const namespace = mcpServerNamespace(name);
+        if (config.codemode === true)
+            excluded.add(namespace);
+        else
+            target.add(namespace);
+    }
+    for (const namespace of excluded)
+        target.delete(namespace);
+}
+/** Move tools from the recorded MCP namespaces onto the direct catalog. */
+export function exposeDirectMcpTools(editor, namespaces) {
+    if (namespaces.size === 0 || !editor.list || !editor.update)
+        return;
+    for (const tool of editor.list()) {
+        const namespace = tool.options?.namespace;
+        if (!namespace || !namespaces.has(namespace))
+            continue;
+        if (tool.options?.codemode === false)
+            continue;
+        editor.update(tool.id, (draft) => {
+            const options = {};
+            if (draft.options?.namespace !== undefined)
+                options.namespace = draft.options.namespace;
+            if (draft.options?.permission !== undefined)
+                options.permission = draft.options.permission;
+            options.codemode = false;
+            draft.options = options;
+        });
+    }
+}

package/dist/opencode2/types.d.ts

@@ -17,6 +17,13 @@ export type Registration = {
     readonly dispose: () => Promise<void>;
 };
 export type Hooks<Spec> = <Name extends keyof Spec>(name: Name, callback: (input: Spec[Name]) => Promise<void> | void) => Promise<Registration>;
+export type ModelHookOptions = {
+    /** Limits the hook to one provider; the host skips events for any other. */
+    readonly providerID?: string;
+};
+export type ModelHooks<Spec> = <Name extends keyof Spec>(name: Name, callback: (input: Spec[Name]) => Promise<void> | void, options?: Spec[Name] extends {
+    readonly model: unknown;
+} ? ModelHookOptions : never) => Promise<Registration>;
 export type Transform<Input> = (callback: (input: Input) => void) => Promise<Registration>;
 export type ProviderInfo = {
     id: string;
@@ -223,6 +230,15 @@ export type ToolDraft = {
     list?(): readonly (ToolDefinition & {
         readonly id: string;
     })[];
+    /** Host ToolEditor.update — missing ids are ignored. */
+    update?(id: string, update: (tool: {
+        options?: {
+            namespace?: string;
+            permission?: string;
+            codemode?: boolean;
+            pinned?: boolean;
+        };
+    }) => void): void;
 };
 export type ToolHookBaseFields = {
     readonly tool: string;
@@ -295,11 +311,28 @@ export type SessionTitle = {
     options?: Record<string, unknown>;
     result?: string;
 };
+/**
+ * Outbound request headers / route overrides for one model call.
+ * Headers reach the AI SDK as `callOptions.headers`.
+ */
+export type SessionModelRequest = {
+    readonly sessionID: string;
+    readonly agent: string;
+    readonly model: {
+        providerID: string;
+        id: string;
+        variant?: string;
+    };
+    readonly kind: "primary" | "compaction" | "title" | "generate";
+    baseURL?: string;
+    headers: Record<string, string>;
+};
 export type SessionHooks = {
     readonly context: SessionContext;
     readonly compaction: SessionCompaction;
     readonly generate: SessionGenerate;
     readonly title: SessionTitle;
+    readonly "model.request": SessionModelRequest;
 };
 /** Only the `location.directory` field we actually read. */
 export type SessionInfo = {
@@ -309,7 +342,7 @@ export type SessionInfo = {
     };
 };
 export type SessionDomain = {
-    readonly hook: Hooks<SessionHooks>;
+    readonly hook: ModelHooks<SessionHooks>;
     readonly get: (input: {
         sessionID: string;
     }) => Promise<SessionInfo>;
@@ -368,6 +401,20 @@ export type WebSearchDomain = {
     readonly transform: Transform<WebSearchEditor>;
     readonly reload: () => Promise<void>;
 };
+/**
+ * MCP config reader this plugin uses. Server `codemode` is observed and not
+ * written: writing it also changes the remote raw-tool URL. The host
+ * `MCPEditor` is a superset.
+ */
+export type McpServerConfig = {
+    readonly codemode?: boolean;
+};
+export type McpEditor = {
+    list(): readonly (readonly [string, McpServerConfig])[];
+};
+export type McpDomain = {
+    readonly transform: Transform<McpEditor>;
+};
 export type PluginLocation = {
     readonly directory: string;
 };
@@ -381,6 +428,7 @@ export type PluginContext = {
     readonly location?: PluginLocation;
     readonly shell?: ShellDomain;
     readonly websearch?: WebSearchDomain;
+    readonly mcp?: McpDomain;
 };
 export type Cleanup = () => Promise<void> | void;
 export type Plugin2 = {

package/dist/plugin-opencode2.js

@@ -8,11 +8,13 @@ import { fetchOpenCodeWebSearchText, parseExaWebSearchResults, } from "./web-too
 import { captureCursorShellResult, cursorShellEnvForCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, } from "./shell-timeout.js";
 import { applyCursorProviderInventory, CURSOR_INTEGRATION_ID } from "./opencode2/catalog.js";
 import { applyCursorIntegration, resolveCursorAccessToken } from "./opencode2/integration.js";
+import { exposeDirectMcpTools, rememberDirectMcpNamespaces } from "./opencode2/mcp-direct.js";
 import { registerTodoTools } from "./opencode2/todo-tools.js";
 import { OPENCODE_2_TOOL_DIALECT } from "./protocol/tools.js";
 import { clearSessionTodos } from "./todo-store.js";
 import { markCompactionSession } from "./compaction-marker.js";
-import { markSessionDirectory } from "./session-directory.js";
+import { getSessionDirectory, markSessionDirectory } from "./session-directory.js";
+import { trace } from "./debug.js";
 import { cancelPlanExecutionKickoff, createPlanExecutionKickoffText, setPlanExecutionKickoff, } from "./plan-execution-kickoff.js";
 import { cancelHostAgentModeSwitch, setHostAgentModeSwitch, } from "./host-agent-mode.js";
 import { clearActiveCursorMode, getActiveCursorMode, normalizeSwitchModeId, setActiveCursorMode, } from "./protocol/switch-mode.js";
@@ -214,8 +216,8 @@ const plugin = {
                 ...(token ? { accessToken: token } : {}),
                 // Static fallback only. This hook fires once per model/package, not
                 // per session, and 2.0 runs one daemon across many projects — the
-                // real per-request directory comes from `x-opencode-directory` and
-                // the session.context hook below via `getSessionDirectory`.
+                // real per-request directory comes from `x-opencode-directory`
+                // (set on `session.model.request`) and the session-directory mark.
                 workspaceRoot,
                 cacheDir,
                 ...event.options,
@@ -250,12 +252,26 @@ const plugin = {
                 });
             }));
         }
+        // Namespaces whose tools belong on the direct catalog. Filled by the MCP
+        // transform (config is not written) and read when tool transforms replay,
+        // including after a later MCP discovery reload.
+        const directMcpNamespaces = new Set();
+        if (ctx.mcp) {
+            await track(ctx.mcp.transform((editor) => {
+                rememberDirectMcpNamespaces(directMcpNamespaces, editor.list());
+            }));
+        }
         await track(ctx.tool.transform((draft) => {
             // OpenCode 2 dropped host todowrite/todoread. Off by default
             // (`CURSOR_OPENCODE2_TODOS=1`/`true` force-enables). When on, register
             // them as direct catalog tools (`codemode: false` + output schema) if
             // the host does not already own those names. When off, register none.
             registerTodoTools(draft);
+            // MCP tools default into Code Mode. Move every server that did not
+            // explicitly opt in onto the direct catalog so this provider can
+            // advertise them to Cursor (issue #29 still routes via CallDynamicTool).
+            // See `opencode2/mcp-direct.ts`.
+            exposeDirectMcpTools(draft, directMcpNamespaces);
         }));
         // ── Shell timeout wrapper ────────────────────────────────
         await track(ctx.tool.hook("execute.before", (event) => {
@@ -328,13 +344,12 @@ const plugin = {
         }
         const rememberSessionDirectory = async (sessionID) => {
             try {
-                const info = (await ctx.session.get({ sessionID }));
-                // OpenCode 2.0 stable exposes a flat `directory`; older shapes nest it
-                // under `location.directory`. Prefer the flat field when both exist.
-                markSessionDirectory(sessionID, info.directory ?? info.location?.directory);
+                const info = await ctx.session.get({ sessionID });
+                markSessionDirectory(sessionID, info.location.directory);
             }
-            catch {
+            catch (error) {
                 // Best effort — falls back to the static workspaceRoot above.
+                trace(`session directory: session.get failed sessionID=${sessionID}: ${String(error)}`);
             }
         };
         await track(ctx.session.hook("context", async (event) => {
@@ -357,6 +372,31 @@ const plugin = {
             }
             await rememberSessionDirectory(event.sessionID);
         }));
+        // The session mark lives in module state, and OpenCode re-evaluates a local
+        // plugin's module graph per Location, so the copy running the model may not
+        // hold it. The header travels with the request (AI SDK
+        // `callOptions.headers` → `resolveSessionWorkspaceRoot`) and never reaches
+        // Cursor. Only a successful lookup updates the mark; on failure keep the
+        // last known session directory ahead of this Location's static root.
+        // Scoped by the host to this provider: other providers' requests never
+        // reach the callback, so the header cannot leak to their endpoints.
+        await track(ctx.session.hook("model.request", async (event) => {
+            const current = await ctx.session
+                .get({ sessionID: event.sessionID })
+                .then((info) => info.location.directory)
+                .catch((error) => {
+                trace(`model.request: session.get failed sessionID=${event.sessionID}: ${String(error)}`);
+                return undefined;
+            });
+            markSessionDirectory(event.sessionID, current);
+            const directory = current ?? getSessionDirectory(event.sessionID) ?? ctx.location?.directory;
+            if (!directory)
+                return;
+            event.headers = {
+                ...event.headers,
+                "x-opencode-directory": encodeURIComponent(directory),
+            };
+        }, { providerID: CURSOR_PROVIDER_ID }));
         await track(ctx.session.hook("compaction", async (event) => {
             markCompactionAndOptions(event, true);
             await rememberSessionDirectory(event.sessionID);

package/dist/pricing-data.d.ts

@@ -91,6 +91,12 @@ export declare const CURSOR_MODEL_COSTS: {
         readonly cache_read: 0.2;
         readonly cache_write: 2.5;
     };
+    readonly "claude-sonnet-5-5": {
+        readonly input: 2;
+        readonly output: 10;
+        readonly cache_read: 0.2;
+        readonly cache_write: 2.5;
+    };
     readonly "composer-2.5": {
         readonly input: 0.5;
         readonly output: 2.5;
@@ -141,6 +147,16 @@ export declare const CURSOR_MODEL_COSTS: {
         readonly output: 4.4;
         readonly cache_read: 0.26;
     };
+    readonly "glm-5.3": {
+        readonly input: 1.4;
+        readonly output: 4.4;
+        readonly cache_read: 0.26;
+    };
+    readonly "glm-5.3-flash": {
+        readonly input: 0.15;
+        readonly output: 0.5;
+        readonly cache_read: 0.029;
+    };
     readonly "gpt-5-mini": {
         readonly input: 0.25;
         readonly output: 2;
@@ -335,6 +351,10 @@ export declare const CURSOR_MODEL_CONTEXTS: {
         readonly maxContext: 200000;
         readonly maxContextForMaxMode: 1000000;
     };
+    readonly "claude-sonnet-5-5": {
+        readonly maxContext: 200000;
+        readonly maxContextForMaxMode: 1000000;
+    };
     readonly "composer-2.5": {
         readonly maxContext: 200000;
     };
@@ -369,6 +389,12 @@ export declare const CURSOR_MODEL_CONTEXTS: {
     readonly "glm-5.2": {
         readonly maxContext: 200000;
     };
+    readonly "glm-5.3": {
+        readonly maxContext: 1000000;
+    };
+    readonly "glm-5.3-flash": {
+        readonly maxContext: 1000000;
+    };
     readonly "gpt-5-mini": {
         readonly maxContext: 272000;
     };
@@ -469,6 +495,9 @@ export declare const CURSOR_MODEL_CAPABILITIES: {
     readonly "claude-sonnet-5": {
         readonly supportsImages: true;
     };
+    readonly "claude-sonnet-5-5": {
+        readonly supportsImages: true;
+    };
     readonly "composer-2.5": {
         readonly supportsImages: true;
     };
@@ -496,6 +525,12 @@ export declare const CURSOR_MODEL_CAPABILITIES: {
     readonly "glm-5.2": {
         readonly supportsImages: false;
     };
+    readonly "glm-5.3": {
+        readonly supportsImages: false;
+    };
+    readonly "glm-5.3-flash": {
+        readonly supportsImages: true;
+    };
     readonly "gpt-5-mini": {
         readonly supportsImages: true;
     };

package/dist/pricing-data.js

@@ -91,6 +91,12 @@ export const CURSOR_MODEL_COSTS = {
         "cache_read": 0.2,
         "cache_write": 2.5
     },
+    "claude-sonnet-5-5": {
+        "input": 2,
+        "output": 10,
+        "cache_read": 0.2,
+        "cache_write": 2.5
+    },
     "composer-2.5": {
         "input": 0.5,
         "output": 2.5,
@@ -141,6 +147,16 @@ export const CURSOR_MODEL_COSTS = {
         "output": 4.4,
         "cache_read": 0.26
     },
+    "glm-5.3": {
+        "input": 1.4,
+        "output": 4.4,
+        "cache_read": 0.26
+    },
+    "glm-5.3-flash": {
+        "input": 0.15,
+        "output": 0.5,
+        "cache_read": 0.029
+    },
     "gpt-5-mini": {
         "input": 0.25,
         "output": 2,
@@ -335,6 +351,10 @@ export const CURSOR_MODEL_CONTEXTS = {
         "maxContext": 200000,
         "maxContextForMaxMode": 1000000
     },
+    "claude-sonnet-5-5": {
+        "maxContext": 200000,
+        "maxContextForMaxMode": 1000000
+    },
     "composer-2.5": {
         "maxContext": 200000
     },
@@ -369,6 +389,12 @@ export const CURSOR_MODEL_CONTEXTS = {
     "glm-5.2": {
         "maxContext": 200000
     },
+    "glm-5.3": {
+        "maxContext": 1000000
+    },
+    "glm-5.3-flash": {
+        "maxContext": 1000000
+    },
     "gpt-5-mini": {
         "maxContext": 272000
     },
@@ -469,6 +495,9 @@ export const CURSOR_MODEL_CAPABILITIES = {
     "claude-sonnet-5": {
         "supportsImages": true
     },
+    "claude-sonnet-5-5": {
+        "supportsImages": true
+    },
     "composer-2.5": {
         "supportsImages": true
     },
@@ -496,6 +525,12 @@ export const CURSOR_MODEL_CAPABILITIES = {
     "glm-5.2": {
         "supportsImages": false
     },
+    "glm-5.3": {
+        "supportsImages": false
+    },
+    "glm-5.3-flash": {
+        "supportsImages": true
+    },
     "gpt-5-mini": {
         "supportsImages": true
     },

package/dist/protocol/generate-image.d.ts

@@ -30,8 +30,8 @@ export type DecodedGenerateImageQuery = {
     referenceImagePaths: string[];
     toolCallId: string;
 };
-/** Cursor names the target file; its extension is the only mime signal sent. */
-export declare function imageMimeForPath(filePath: string): string;
+/** Prefer encoded bytes: Cursor can send JPEG data with a .png target name. */
+export declare function imageMimeForPath(filePath: string, data?: Uint8Array): string;
 /** Decode a `generate_image_request_query` body, or undefined when unusable. */
 export declare function decodeGenerateImageQuery(queryBytes: Uint8Array): DecodedGenerateImageQuery | undefined;
 export type ImageWriteRoots = {

package/dist/protocol/generate-image.js

@@ -32,8 +32,20 @@ const IMAGE_MIME_BY_EXTENSION = {
     ".gif": "image/gif",
     ".webp": "image/webp",
 };
-/** Cursor names the target file; its extension is the only mime signal sent. */
-export function imageMimeForPath(filePath) {
+/** Prefer encoded bytes: Cursor can send JPEG data with a .png target name. */
+export function imageMimeForPath(filePath, data) {
+    if (data) {
+        const matches = (signature, offset = 0) => signature.every((byte, index) => data[offset + index] === byte);
+        if (matches([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+            return "image/png";
+        if (matches([0xff, 0xd8, 0xff]))
+            return "image/jpeg";
+        if (matches([0x47, 0x49, 0x46, 0x38]) && (data[4] === 0x37 || data[4] === 0x39) && data[5] === 0x61) {
+            return "image/gif";
+        }
+        if (matches([0x52, 0x49, 0x46, 0x46]) && matches([0x57, 0x45, 0x42, 0x50], 8))
+            return "image/webp";
+    }
     const dot = path.basename(filePath).lastIndexOf(".");
     if (dot <= 0)
         return "image/png";

package/dist/protocol/tools.d.ts

@@ -12,9 +12,12 @@ export type OpencodeToolDef = {
 export type HostFilePathKey = "path" | "filePath";
 /** Host shell tool id. OpenCode 1.x uses `bash`; 2.0 uses `shell`. */
 export type HostShellTool = "bash" | "shell";
+/** OpenCode 1.x skill params use `name`; OpenCode 2.0 uses `id`. */
+export type HostSkillArgKey = "name" | "id";
 export type HostToolDialect = {
     filePathKey: HostFilePathKey;
     shellTool: HostShellTool;
+    skillArgKey: HostSkillArgKey;
 };
 export declare const OPENCODE_1_TOOL_DIALECT: HostToolDialect;
 export declare const OPENCODE_2_TOOL_DIALECT: HostToolDialect;
@@ -23,6 +26,7 @@ export declare function opencodePathArg(args: Record<string, unknown> | undefine
 /**
  * Infer the host tool dialect from advertised AI SDK schemas.
  * OpenCode 2.0 read/edit/write require `path` and rename bash → `shell`.
+ * Skill: OpenCode 1.x requires `name`; OpenCode 2.0 requires `id`.
  */
 export declare function hostToolDialectFromTools(tools: readonly {
     name?: string;

package/dist/protocol/tools.js

@@ -16,10 +16,12 @@ export const REQUEST_CONTEXT_RESULT_FIELD = 10;
 export const OPENCODE_1_TOOL_DIALECT = {
     filePathKey: "filePath",
     shellTool: "bash",
+    skillArgKey: "name",
 };
 export const OPENCODE_2_TOOL_DIALECT = {
     filePathKey: "path",
     shellTool: "shell",
+    skillArgKey: "id",
 };
 function jsonSchemaProperties(schema) {
     if (!schema || typeof schema !== "object" || Array.isArray(schema))
@@ -46,6 +48,7 @@ export function opencodePathArg(args) {
 /**
  * Infer the host tool dialect from advertised AI SDK schemas.
  * OpenCode 2.0 read/edit/write require `path` and rename bash → `shell`.
+ * Skill: OpenCode 1.x requires `name`; OpenCode 2.0 requires `id`.
  */
 export function hostToolDialectFromTools(tools, defaultDialect = OPENCODE_1_TOOL_DIALECT) {
     let filePathKey;
@@ -71,7 +74,21 @@ export function hostToolDialectFromTools(tools, defaultDialect = OPENCODE_1_TOOL
         // OpenCode 2 hosts advertise `shell` and `path` together; use that when schemas are opaque.
         filePathKey = shellTool === "shell" ? "path" : defaultDialect.filePathKey;
     }
-    return { filePathKey, shellTool };
+    const skillProps = jsonSchemaProperties(tools.find((tool) => tool.name === "skill")?.inputSchema);
+    let skillArgKey;
+    if (skillProps) {
+        if ("id" in skillProps && !("name" in skillProps))
+            skillArgKey = "id";
+        else if ("name" in skillProps)
+            skillArgKey = "name";
+    }
+    if (!skillArgKey) {
+        // Opaque skill schema: OpenCode 2 pairs `shell`+`path` with skill `id`.
+        skillArgKey = shellTool === "shell" && filePathKey === "path"
+            ? "id"
+            : defaultDialect.skillArgKey;
+    }
+    return { filePathKey, shellTool, skillArgKey };
 }
 function assignHostFilePath(args, filePath, dialect) {
     delete args.filePath;
@@ -1257,6 +1274,18 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant, dialect = OP
                 args.path = path;
             return { toolName: "glob", args };
         }
+        case "skill": {
+            // OpenCode 1.x skill requires `name`; OpenCode 2.0 requires `id`. Both
+            // reject the other key (`additionalProperties: false`). Accept either
+            // model/Cursor shape and emit only the dialect key.
+            const value = str(cleaned[dialect.skillArgKey]) ?? str(cleaned.id) ?? str(cleaned.name);
+            const args = { ...cleaned };
+            delete args.id;
+            delete args.name;
+            if (value)
+                args[dialect.skillArgKey] = value;
+            return { toolName: "skill", args };
+        }
         default:
             return { toolName, args: cleaned };
     }

package/dist/session-directory.d.ts

@@ -7,9 +7,12 @@
  * time is wrong for any session but the one open when the daemon started.
  *
  * The 2.0 runtime names a session directory in two places:
- * - request header `x-opencode-directory` (per-request; preferred in the LM)
- * - `ctx.session.get()` → flat `info.directory`, or legacy
- *   `info.location.directory`, reachable from `session.hook("context")`
+ * - request header `x-opencode-directory` (per-request; preferred in the LM).
+ *   The host does not set it on model requests; the opencode2 plugin adds it
+ *   from `session.hook("model.request")`, so it travels with the request
+ *   instead of depending on this module's in-memory state.
+ * - `ctx.session.get()` → `info.location.directory`, reachable from session
+ *   hooks
  *
  * This module records the session-get value by id so the language model can
  * fall back when the header is absent, same mechanism as `compaction-marker.ts`.

package/dist/session-directory.js

@@ -7,9 +7,12 @@
  * time is wrong for any session but the one open when the daemon started.
  *
  * The 2.0 runtime names a session directory in two places:
- * - request header `x-opencode-directory` (per-request; preferred in the LM)
- * - `ctx.session.get()` → flat `info.directory`, or legacy
- *   `info.location.directory`, reachable from `session.hook("context")`
+ * - request header `x-opencode-directory` (per-request; preferred in the LM).
+ *   The host does not set it on model requests; the opencode2 plugin adds it
+ *   from `session.hook("model.request")`, so it travels with the request
+ *   instead of depending on this module's in-memory state.
+ * - `ctx.session.get()` → `info.location.directory`, reachable from session
+ *   hooks
  *
  * This module records the session-get value by id so the language model can
  * fall back when the header is absent, same mechanism as `compaction-marker.ts`.
@@ -17,6 +20,7 @@
  * Bounded so a long-lived server cannot accumulate ids for dead sessions.
  */
 import path from "node:path";
+import { trace } from "./debug.js";
 const MAX_TRACKED_SESSIONS = 256;
 const sessionDirectories = new Map();
 export function markSessionDirectory(sessionID, directory) {
@@ -61,7 +65,10 @@ export function opencodeDirectoryHeader(headers) {
  * Prefer the per-request header, then the session mark, then static options/cwd.
  */
 export function resolveSessionWorkspaceRoot(input) {
-    return path.resolve(opencodeDirectoryHeader(input.headers) ??
-        getSessionDirectory(input.sessionKey) ??
-        (input.workspaceRoot || input.cwd || process.cwd()));
+    const resolved = opencodeDirectoryHeader(input.headers) ?? getSessionDirectory(input.sessionKey);
+    if (resolved)
+        return path.resolve(resolved);
+    const fallback = input.workspaceRoot || input.cwd || process.cwd();
+    trace(`session directory: no header or session mark sessionKey=${input.sessionKey ?? "-"}; fallback=${fallback}`);
+    return path.resolve(fallback);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",