cursor-opencode-provider 0.7.5 → 0.7.6

package/README.md

@@ -293,7 +293,7 @@ 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)).
+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`).
 

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

@@ -17,27 +17,58 @@ export declare function skillNameFromAgentSkill(skill: AgentSkillLike): string |
 /**
  * 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.
+ * 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;
 /**
- * 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.
+ * 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 buildSkillCatalogNudge(options: {
+export declare function buildSkillCatalogChangeReminder(options: {
     hasSkillTool: boolean;
     skills: readonly AgentSkillLike[];
-    userText?: string;
+    /** 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

@@ -4,41 +4,27 @@ import { resolveToolServerIdentity } from "../protocol/tools.js";
  * 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-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_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.
+ * 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.
  */
-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, " ");
-}
+const admittedSkillIdsByConversation = new Map();
 function listWithOverflow(items, limit) {
     const shown = items.slice(0, limit).map((item) => `\`${item}\``).join(", ");
     const hidden = items.length - limit;
@@ -73,11 +59,32 @@ export function skillNameFromAgentSkill(skill) {
         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
- * are deliberately absent: this line is part of the frozen baseline system
- * context, and per-turn ids go through `buildSkillCatalogNudge` instead.
+ * 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];
@@ -91,93 +98,131 @@ export function buildDynamicCatalogRoutingInstruction(options) {
     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)));
+    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 descriptionMatchesUserText(description, userTokens) {
-    let hits = 0;
-    let distinctive = false;
-    for (const token of wordTokens(description)) {
-        if (!userTokens.has(token))
+function skillEntriesXml(skills, argKey) {
+    const lines = ["<available_skills>"];
+    for (const skill of skills) {
+        const name = skillNameFromAgentSkill(skill);
+        if (!name)
             continue;
-        hits += 1;
-        if (token.length >= 8)
-            distinctive = true;
-        if (hits >= 2)
-            return true;
+        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>");
     }
-    // Single distinctive token (library names, skill ids) is enough.
-    return distinctive;
+    lines.push("</available_skills>");
+    return lines;
 }
-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;
+/**
+ * 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 };
     }
-    return false;
+    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,
+    };
 }
 /**
- * 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.
+ * 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) {
-    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>");
+    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,5 +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 { 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,5 +1,5 @@
 export { buildDynamicRequestContext, buildRequestContext, DYNAMIC_REQUEST_CONTEXT_KEYS, materializeRequestContext, requestContextBase, } from "./build.js";
-export { buildDynamicCatalogRoutingInstruction, buildSkillCatalogNudge, listAdvertisedMcpServers, skillNameFromAgentSkill, } from "./dynamic-catalog.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/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;
 /**

package/dist/language-model.js

@@ -34,7 +34,7 @@ import { readCache, cacheFilePath, resolveVariantParameters, resolveVariantMaxMo
 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 { buildDynamicCatalogRoutingInstruction, takeSkillCatalogChangeReminder, } 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";
@@ -542,19 +542,34 @@ async function doStreamImpl(modelId, options, callOptions) {
             if (historical > 0) {
                 trace(`fresh turn: ignoring ${historical} historical tool result(s) (not trailing)`);
             }
-            // Host may start a new user turn while the prior Run still has pending
-            // tools. Finish that Run on the same conversation (cancel stranded execs,
-            // drain turn_ended) before opening the new Run so the checkpoint prefix
-            // is preserved. registerSession will not close a prior Run that still
-            // has real pending execs; a failed prepare leaves that Run held.
-            try {
-                await preparePriorSessionForFreshTurn(sessionKey);
+            // An in-session helper (title/memory/task child) that reuses the parent
+            // OpenCode session id with a strictly smaller catalog must not cancel or
+            // supersede the held parent Run — that remints (`interrupted-run`) when
+            // the trailing tool result returns. Isolate onto an ephemeral conversation.
+            const busyPrior = sessionManager.findOpenByOpenCodeSessionId(sessionKey);
+            if (busyPrior
+                && !busyPrior.closed
+                && isProperCatalogSubset(extractTools(callOptions), busyPrior.toolCatalog ?? [])) {
+                trace(`fresh turn: isolating in-session helper — incomingTools subset of ` +
+                    `parentTools=${busyPrior.toolCatalog?.length ?? 0} ` +
+                    `priorSession=${busyPrior.sessionId} pending=${busyPrior.pending.size}`);
+                session = await openSession({ isolate: true });
             }
-            catch (error) {
-                trace(`fresh turn: prepare-prior failed — opening the new Run and leaving ` +
-                    `any still-pending prior held — ${error.message}`);
+            else {
+                // Host may start a new user turn while the prior Run still has pending
+                // tools. Finish that Run on the same conversation (cancel stranded execs,
+                // drain turn_ended) before opening the new Run so the checkpoint prefix
+                // is preserved. registerSession will not close a prior Run that still
+                // has real pending execs; a failed prepare leaves that Run held.
+                try {
+                    await preparePriorSessionForFreshTurn(sessionKey);
+                }
+                catch (error) {
+                    trace(`fresh turn: prepare-prior failed — opening the new Run and leaving ` +
+                        `any still-pending prior held — ${error.message}`);
+                }
+                session = await openSession();
             }
-            session = await openSession();
         }
     }
     let activeSession = session;
@@ -756,6 +771,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const prompt = callOptions.prompt;
     const incomingTools = extractTools(callOptions);
     const sessionKey = opencodeSessionKey(callOptions);
+    const isolateHelper = startOptions?.isolate === true;
     const cacheDir = opencodeGlobalCacheDir();
     if (sessionKey) {
         const restored = await hydrateConversationState(cacheDir, sessionKey).catch((error) => {
@@ -807,6 +823,9 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     let resumeRecovery = recovery?.kind === "resume" ? recovery : undefined;
     let resuming = !!resumeRecovery;
     const lifecycle = !allowTools && !isCompaction && !recovery;
+    // Isolated helpers must not share the parent's openCodeSessionId or sticky
+    // conversation: registerSession would otherwise supersede the held parent Run.
+    const ephemeralRun = lifecycle || isolateHelper;
     // 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
@@ -841,9 +860,9 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         ? { conversationId: resumeRecovery.conversationId, reset: false, previousId: undefined }
         : bindConversationId(sessionKey, {
             reset: resetState.reset || recovery?.kind === "rebase",
-            ephemeral: lifecycle,
+            ephemeral: ephemeralRun,
         });
-    let conversationState = lifecycle
+    let conversationState = ephemeralRun
         ? undefined
         : resuming
             ? resumeRecovery.checkpoint
@@ -880,9 +899,6 @@ 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;
@@ -1007,17 +1023,15 @@ 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, 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.
+    // Issue #29: after skills are in RequestContext, admit the catalog. OpenCode
+    // only Mid-Conversation-updates when the available-skills list changes
+    // (SkillGuidance / SkillInstructions) — never per-turn matched-id nudges.
+    // Gate on the host-permitted set, not the epoch-held advertisement.
     if (!isCompaction && !lifecycle) {
         const skillDialect = hostToolDialectFromTools(tools, options.defaultDialect);
-        const skillNudge = buildSkillCatalogNudge({
+        const skillNudge = takeSkillCatalogChangeReminder(conversationId, {
             hasSkillTool: allowTools && incomingTools.some((tool) => tool.name === "skill"),
             skills: getHeldOverlaySkills(conversationId),
-            userText: skillMatchText,
             skillArgKey: skillDialect.skillArgKey,
         });
         userText = appendMidConversationMessage(userText, skillNudge);
@@ -1159,7 +1173,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
             createPlanInTurn: false,
             switchModeInTurn: false,
         },
-        openCodeSessionId: lifecycle ? undefined : sessionKey,
+        openCodeSessionId: ephemeralRun ? undefined : sessionKey,
         hostAgent,
         stableSystemPromptHash: frozenSystemPromptHash,
         postCompactionRebase: isCompaction,
@@ -1172,7 +1186,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         // Seed from the per-OpenCode-session copy: merges in this turn (and after
         // checkpoint resumes/rebases, which rebuild the session here) expand
         // against the last observed host list, not an empty one.
-        mirroredTodos: snapshotMirroredTodosBySession(lifecycle ? undefined : sessionKey),
+        mirroredTodos: snapshotMirroredTodosBySession(ephemeralRun ? undefined : sessionKey),
         nextBridgedExecId: 900_000,
         blobs: new Map(),
         toolDescriptors,
@@ -1276,6 +1290,39 @@ export function findContinuationSession(toolResults) {
     }
     return 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 function isProperCatalogSubset(incoming, parent) {
+    if (incoming.length === 0 || parent.length === 0)
+        return false;
+    if (incoming.length >= parent.length)
+        return false;
+    const parentNames = new Set(parent.map((tool) => tool.name).filter((name) => !!name));
+    if (parentNames.size === 0)
+        return false;
+    let matched = 0;
+    for (const tool of incoming) {
+        const name = tool.name;
+        if (!name || !parentNames.has(name))
+            return false;
+        matched++;
+    }
+    return matched > 0 && matched < parentNames.size;
+}
+/**
+ * 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 function shouldIsolateInSessionHelper(openCodeSessionId, incomingTools) {
+    const prior = sessionManager.findOpenByOpenCodeSessionId(openCodeSessionId);
+    if (!prior || prior.closed)
+        return false;
+    return isProperCatalogSubset(incomingTools, prior.toolCatalog ?? []);
+}
 /** How long a fresh-turn drain may wait for Cursor `turn_ended` after bridged settle. */
 export const FRESH_TURN_DRAIN_TIMEOUT_MS = 8_000;
 /**

package/package.json

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