cursor-opencode-provider 0.2.8 → 0.2.9

package/README.md

@@ -18,7 +18,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 - **Authentication** — browser OAuth (PKCE), or API key from [cursor.com/settings](https://cursor.com/settings)
 - **Model discovery** — fetches available models from Cursor's API and caches them locally
 - **Streaming** — bidirectional Connect-RPC Runs with stale-session rotation, health checks, semantic/read-idle deadlines, bounded replay-safe recovery, and activity-aware held tool continuations
-- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts, including native subagent/Task execution (Cursor's `generalPurpose` maps to OpenCode `general`; read-oriented `bugbot` reviews map to `explore`) and the Pi read/bash/edit/write/grep/find/ls request/result field range; enforces the exact current OpenCode agent catalog before emitting any tool call; mirrors finalized display-only todo/plan state into OpenCode; strips OpenCode's `read` XML envelope (`<path>`/`<content>` + `N:` prefixes) before returning content to Cursor so the model cannot echo the wrapper into writes
+- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts, including catalog-aware native subagent execution: exact advertised custom agents win, `unspecified` / `generalPurpose` select `general`, read-oriented `bugbot` / `security-review` select `explore`, and `cursor-guide` selects enabled Kilo `scout` before `explore`; MiMo `actor` is used instead of its work-item `task` tool when advertised. The bridge also covers the Pi read/bash/edit/write/grep/find/ls request/result range, enforces the exact current OpenCode tool catalog, mirrors finalized display-only todo/plan state, and strips OpenCode's `read` XML envelope before returning content to Cursor.
 - **Thinking / reasoning** — surfaces extended-thinking deltas where the model supports it
 
 ## Requirements
@@ -47,7 +47,7 @@ Add the package name to OpenCode config. OpenCode installs npm plugins with Bun
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.2.8"`.
+Pin a version if you want: `"cursor-opencode-provider@0.2.9"`.
 
 ### From a local clone
 
@@ -238,6 +238,18 @@ The provider adds OpenCode-specific system guidance to normal tool-capable conve
 
 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).
 
+### Native subagent routing
+
+The provider reads the permission-filtered subagent catalog from the current host `task` or `actor` definition and advertises those recipients to Cursor as custom subagents. Exact configured names are preserved; unknown future Cursor subtype strings fall back to `general`. If a complete catalog omits every compatible recipient, the request fails on Cursor's typed subagent channel instead of selecting an arbitrary specialist.
+
+| Host | Default recipients | Optional recipients |
+|------|--------------------|---------------------|
+| OpenCode | `general`, `explore` | Add `agent/*.md` or `agents/*.md` with `mode: subagent` or `all` |
+| Kilo | `general`, `explore` | Enable `scout` with `KILO_EXPERIMENTAL_SCOUT=true` (or `KILO_EXPERIMENTAL=true`); add `.kilo/agent/*.md` custom agents with `mode: subagent` or `all` |
+| MiMo | `general`, `explore` | Add `.mimocode/agent/*.md` with `mode: subagent` |
+
+Kilo `scout` is reserved for external documentation, dependency repositories, and upstream source. Local workspace discovery continues to use `explore`. Primary modes and hidden/internal agents are never selected unless the host explicitly exposes them as spawnable.
+
 ## Package exports
 
 | Import path | Export |
@@ -284,4 +296,4 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 
 ## License
 
-MIT
+MIT

package/dist/context/agents.d.ts

@@ -4,5 +4,9 @@ export type CollectedAgent = {
     description: string;
     prompt: string;
 };
-/** Custom OpenCode agents from `.opencode/agents` and global config. */
+/**
+ * Custom agents from the active OpenCode-compatible config roots. OCP may
+ * install a host-neutral bridge before loading this module; without one this
+ * remains the direct OpenCode discovery path.
+ */
 export declare function collectAgents(workspaceRoot: string): Promise<CollectedAgent[]>;

package/dist/context/agents.js

@@ -1,6 +1,6 @@
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import { opencodeGlobalConfigDir } from "./paths.js";
+import { opencodeGlobalConfigDirs, opencodeProjectConfigDirs } from "./paths.js";
 async function exists(p) {
     try {
         await stat(p);
@@ -36,41 +36,101 @@ function parseAgentMarkdown(raw, fallbackName) {
     }
     return { name, description, prompt: body.slice(0, 20_000) };
 }
-async function scanAgentDir(dir, out) {
-    if (!(await exists(dir)))
-        return;
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
+function uniquePaths(paths) {
+    const seen = new Set();
+    return paths.filter((value) => {
+        const normalized = path.resolve(value);
+        if (seen.has(normalized))
+            return false;
+        seen.add(normalized);
+        return true;
+    });
+}
+/**
+ * Read one host config root's `agent/` and `agents/` trees. Host loaders use
+ * both spellings and recurse through nested markdown files. Directory symlinks
+ * are followed with realpath cycle detection, matching host behavior without
+ * allowing a symlink loop to hang context construction.
+ */
+async function scanAgentRoot(root, out) {
+    if (!(await exists(root)))
         return;
-    }
-    for (const name of entries) {
-        if (!name.endsWith(".md"))
-            continue;
-        const full = path.join(dir, name);
+    const visitedDirs = new Set();
+    const scanDir = async (dir, relativePrefix) => {
+        let canonical;
         try {
-            const raw = await readFile(full, "utf-8");
-            const parsed = parseAgentMarkdown(raw, name.replace(/\.md$/, ""));
-            if (!out.has(parsed.name)) {
-                out.set(parsed.name, {
-                    fullPath: path.resolve(full),
-                    name: parsed.name,
-                    description: parsed.description,
-                    prompt: parsed.prompt,
-                });
-            }
+            canonical = await realpath(dir);
         }
         catch {
-            /* skip */
+            return;
         }
-    }
+        if (visitedDirs.has(canonical))
+            return;
+        visitedDirs.add(canonical);
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            const relative = path.join(relativePrefix, entry.name);
+            let isDirectory = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                try {
+                    const target = await stat(full);
+                    isDirectory = target.isDirectory();
+                    isFile = target.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDirectory) {
+                await scanDir(full, relative);
+                continue;
+            }
+            if (!isFile || !entry.name.endsWith(".md"))
+                continue;
+            try {
+                const raw = await readFile(full, "utf-8");
+                const fallbackName = relative.replace(/\\/g, "/").replace(/\.md$/, "");
+                const parsed = parseAgentMarkdown(raw, fallbackName);
+                if (!out.has(parsed.name)) {
+                    out.set(parsed.name, {
+                        fullPath: path.resolve(full),
+                        name: parsed.name,
+                        description: parsed.description,
+                        prompt: parsed.prompt,
+                    });
+                }
+            }
+            catch {
+                /* skip unreadable or malformed files without failing context build */
+            }
+        }
+    };
+    // Scan singular before plural, then let root ordering establish host
+    // precedence. This is deterministic and mirrors the hosts' brace glob.
+    await scanDir(path.join(root, "agent"), "agent");
+    await scanDir(path.join(root, "agents"), "agents");
 }
-/** Custom OpenCode agents from `.opencode/agents` and global config. */
+/**
+ * Custom agents from the active OpenCode-compatible config roots. OCP may
+ * install a host-neutral bridge before loading this module; without one this
+ * remains the direct OpenCode discovery path.
+ */
 export async function collectAgents(workspaceRoot) {
     const out = new Map();
-    await scanAgentDir(path.join(workspaceRoot, ".opencode", "agents"), out);
-    await scanAgentDir(path.join(opencodeGlobalConfigDir(), "agents"), out);
+    const roots = uniquePaths([
+        ...opencodeProjectConfigDirs(workspaceRoot),
+        ...opencodeGlobalConfigDirs(),
+    ]);
+    for (const root of roots)
+        await scanAgentRoot(root, out);
     return [...out.values()];
 }

package/dist/context/build.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { toolsToDescriptors, toolsToMcpDescriptors } from "../protocol/tools.js";
+import { extractHostSubagentCatalog, toolsToDescriptors, toolsToMcpDescriptors, } from "../protocol/tools.js";
 import { collectRules } from "./rules.js";
 import { collectSkills } from "./skills.js";
 import { collectAgents } from "./agents.js";
@@ -9,6 +9,40 @@ import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
 import { ensureOpencodeProjectDir } from "./paths.js";
 import { traceRequestContextPaths } from "../debug.js";
+const DEFAULT_HOST_SUBAGENTS = [
+    {
+        name: "general",
+        description: "General-purpose agent for complex research and multi-step tasks.",
+    },
+    {
+        name: "explore",
+        description: "Read-only agent for searching and understanding the local codebase.",
+    },
+];
+/**
+ * Convert the raw host executor catalog into the exact subagent list advertised
+ * to Cursor. `hostSubagents.complete` answers a narrow question: did the host's
+ * task/actor tool itself expose an exhaustive recipient list (schema enum or
+ * catalog marker)? OpenCode's task tool intentionally uses a plain string, so
+ * that raw flag is false even though we can still advertise a complete Cursor
+ * catalog by adding built-in defaults and discovered agent files.
+ *
+ * `custom_subagents_info_complete` must describe the final advertised list, not
+ * the raw extraction source. If there is no executor, the empty list is
+ * complete. If the host catalog is complete, use it verbatim. Otherwise we make
+ * the advertised set complete by augmenting with default host agents and all
+ * locally discovered agents.
+ */
+function buildAdvertisedSubagentCatalog(hostSubagents, discoveredAgents) {
+    if (!hostSubagents.executor)
+        return { agents: [], complete: true };
+    if (hostSubagents.complete)
+        return { agents: hostSubagents.agents, complete: true };
+    return {
+        agents: [...DEFAULT_HOST_SUBAGENTS, ...hostSubagents.agents, ...discoveredAgents],
+        complete: true,
+    };
+}
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Sourced from OpenCode discovery (and .claude/.agents skill fallbacks).
@@ -30,6 +64,26 @@ export async function buildRequestContext(input) {
     const flat = toolsToDescriptors(tools, providerIdentifier, mcpServerNames);
     const nested = toolsToMcpDescriptors(tools, providerIdentifier, mcpServerNames);
     const projectDir = ensureOpencodeProjectDir(workspaceRoot);
+    const hostSubagents = extractHostSubagentCatalog(tools);
+    const advertisedSubagents = buildAdvertisedSubagentCatalog(hostSubagents, agents);
+    const discoveredByName = new Map(agents.map((agent) => [agent.name, agent]));
+    const advertisedByName = new Map();
+    for (const agent of advertisedSubagents.agents) {
+        if (!advertisedByName.has(agent.name))
+            advertisedByName.set(agent.name, agent);
+    }
+    const customSubagents = [...advertisedByName.values()].map((agent) => {
+        const discovered = discoveredByName.get(agent.name);
+        return {
+            full_path: discovered?.fullPath ?? "",
+            name: agent.name,
+            description: discovered?.description || agent.description || "Host-configured subagent.",
+            // The host applies the real configured prompt when Task/Actor executes.
+            // Cursor only needs enough context to select the recipient intentionally.
+            prompt: discovered?.prompt ||
+                `Delegate to the host-configured ${agent.name} subagent; its host instructions and tools apply.`,
+        };
+    });
     const ctx = {
         env: buildEnv(workspaceRoot),
         tools: flat,
@@ -45,12 +99,7 @@ export async function buildRequestContext(input) {
             content: s.content,
             description: s.description,
         })),
-        custom_subagents: agents.map((a) => ({
-            full_path: a.fullPath,
-            name: a.name,
-            description: a.description,
-            prompt: a.prompt,
-        })),
+        custom_subagents: customSubagents,
         mcp_file_system_options: {
             enabled: true,
             // Cursor metadata root (mcps / agent-tools), not the git workspace.
@@ -74,7 +123,7 @@ export async function buildRequestContext(input) {
         git_repo_info_complete: true,
         git_status_info_complete: true,
         agent_skills_info_complete: true,
-        custom_subagents_info_complete: true,
+        custom_subagents_info_complete: advertisedSubagents.complete,
         mcp_file_system_info_complete: true,
         mcp_info_complete: true,
     };

package/dist/context/paths.d.ts

@@ -1,4 +1,14 @@
 export type HostPathEnv = NodeJS.ProcessEnv;
+/** Host-neutral bridge installed by OCP before an unchanged provider is loaded. */
+export declare const OPENCODE_PATH_BRIDGE: unique symbol;
+export type OpenCodePathBridge = {
+    projectConfigDirs: (workspaceRoot: string) => string[];
+    globalConfigDirs: () => string[];
+    configFileNames?: string[];
+};
+export declare function opencodeProjectConfigDirs(workspaceRoot: string): string[];
+export declare function opencodeGlobalConfigDirs(): string[];
+export declare function opencodeConfigFileNames(): string[];
 type CompatDetectResult = {
     id: string;
     supported: boolean;

package/dist/context/paths.js

@@ -4,6 +4,30 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { trace } from "../debug.js";
+/** Host-neutral bridge installed by OCP before an unchanged provider is loaded. */
+export const OPENCODE_PATH_BRIDGE = Symbol.for("opencode.compat.path-bridge");
+function pathBridge() {
+    const value = globalThis[OPENCODE_PATH_BRIDGE];
+    if (!value || typeof value !== "object")
+        return undefined;
+    const bridge = value;
+    return typeof bridge.projectConfigDirs === "function" && typeof bridge.globalConfigDirs === "function"
+        ? bridge
+        : undefined;
+}
+export function opencodeProjectConfigDirs(workspaceRoot) {
+    return pathBridge()?.projectConfigDirs(path.resolve(workspaceRoot)) ?? [
+        path.join(path.resolve(workspaceRoot), ".opencode"),
+    ];
+}
+export function opencodeGlobalConfigDirs() {
+    return pathBridge()?.globalConfigDirs() ?? [opencodeGlobalConfigDir()];
+}
+export function opencodeConfigFileNames() {
+    return pathBridge()?.configFileNames?.length
+        ? [...pathBridge().configFileNames]
+        : ["opencode.json", "opencode.jsonc"];
+}
 /** Explicit host cache root (e.g. Effect v2 `Path.cache`, or `createCursor({ cacheDir })`). */
 let hostCacheDirOverride;
 function resolveHome(env = process.env) {

package/dist/context/plugins.js

@@ -1,6 +1,6 @@
 import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
-import { opencodeGlobalConfigDir } from "./paths.js";
+import { opencodeGlobalConfigDirs, opencodeProjectConfigDirs } from "./paths.js";
 async function listLocalPlugins(dir) {
     try {
         await stat(dir);
@@ -34,17 +34,21 @@ export async function collectPlugins(workspaceRoot, config) {
         seen.add(id);
         out.push({ id, source: "npm" });
     }
-    for (const p of await listLocalPlugins(path.join(workspaceRoot, ".opencode", "plugins"))) {
-        if (seen.has(p.id))
-            continue;
-        seen.add(p.id);
-        out.push(p);
-    }
-    for (const p of await listLocalPlugins(path.join(opencodeGlobalConfigDir(), "plugins"))) {
-        if (seen.has(p.id))
-            continue;
-        seen.add(p.id);
-        out.push(p);
+    for (const configDir of opencodeProjectConfigDirs(workspaceRoot)) {
+        for (const p of await listLocalPlugins(path.join(configDir, "plugins"))) {
+            if (seen.has(p.id))
+                continue;
+            seen.add(p.id);
+            out.push(p);
+        }
+    }
+    for (const configDir of opencodeGlobalConfigDirs()) {
+        for (const p of await listLocalPlugins(path.join(configDir, "plugins"))) {
+            if (seen.has(p.id))
+                continue;
+            seen.add(p.id);
+            out.push(p);
+        }
     }
     return out;
 }

package/dist/context/rules.js

@@ -1,7 +1,7 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
-import { opencodeGlobalConfigDir, resolveHomeRelative } from "./paths.js";
+import { opencodeConfigFileNames, opencodeGlobalConfigDirs, opencodeProjectConfigDirs, resolveHomeRelative } from "./paths.js";
 async function exists(file) {
     try {
         await stat(file);
@@ -12,7 +12,7 @@ async function exists(file) {
     }
 }
 async function readJsonConfig(dir) {
-    for (const name of ["opencode.json", "opencode.jsonc"]) {
+    for (const name of opencodeConfigFileNames()) {
         const file = path.join(dir, name);
         if (!(await exists(file)))
             continue;
@@ -151,29 +151,30 @@ export async function fetchRemoteInstruction(url, timeoutMs = 5000) {
         clearTimeout(timer);
     }
 }
-export async function loadMergedConfig(workspaceRoot) {
-    const globalConfig = await readJsonConfig(opencodeGlobalConfigDir());
-    if (isProjectConfigDisabled()) {
-        return {
-            ...globalConfig,
-            instructions: [...(globalConfig.instructions ?? [])],
-            plugin: [...(globalConfig.plugin ?? [])],
-            plugins: [...(globalConfig.plugins ?? [])],
-            mcp: { ...(globalConfig.mcp ?? {}) },
-            permission: globalConfig.permission,
-        };
-    }
-    const projectConfig = await readJsonConfig(workspaceRoot);
+function mergeConfig(base, overlay) {
     return {
-        ...globalConfig,
-        ...projectConfig,
-        instructions: [...(globalConfig.instructions ?? []), ...(projectConfig.instructions ?? [])],
-        plugin: [...new Set([...(globalConfig.plugin ?? []), ...(projectConfig.plugin ?? [])])],
-        plugins: [...new Set([...(globalConfig.plugins ?? []), ...(projectConfig.plugins ?? [])])],
-        mcp: { ...(globalConfig.mcp ?? {}), ...(projectConfig.mcp ?? {}) },
-        permission: projectConfig.permission ?? globalConfig.permission,
+        ...base,
+        ...overlay,
+        instructions: [...(base.instructions ?? []), ...(overlay.instructions ?? [])],
+        plugin: [...new Set([...(base.plugin ?? []), ...(overlay.plugin ?? [])])],
+        plugins: [...new Set([...(base.plugins ?? []), ...(overlay.plugins ?? [])])],
+        mcp: { ...(base.mcp ?? {}), ...(overlay.mcp ?? {}) },
+        permission: overlay.permission ?? base.permission,
     };
 }
+export async function loadMergedConfig(workspaceRoot) {
+    const globalConfig = await readJsonConfig(opencodeGlobalConfigDirs()[0] ?? "");
+    if (isProjectConfigDisabled())
+        return mergeConfig({}, globalConfig);
+    // The bridge supplies native project config roots for an unchanged plugin:
+    // .opencode on OpenCode, .mimocode on MiMo, and .kilo/.kilocode on Kilo.
+    // Later roots have higher precedence, matching the host's native ordering.
+    let projectConfig = await readJsonConfig(workspaceRoot);
+    for (const configDir of opencodeProjectConfigDirs(workspaceRoot)) {
+        projectConfig = mergeConfig(projectConfig, await readJsonConfig(configDir));
+    }
+    return mergeConfig(globalConfig, projectConfig);
+}
 /**
  * Collect OpenCode instruction files.
  */
@@ -205,7 +206,9 @@ export async function collectRules(workspaceRoot) {
             }
         }
     }
-    await add(path.join(opencodeGlobalConfigDir(), "AGENTS.md"));
+    for (const globalDir of opencodeGlobalConfigDirs()) {
+        await add(path.join(globalDir, "AGENTS.md"));
+    }
     await add(path.join(homedir(), ".claude", "CLAUDE.md"));
     for (const raw of config.instructions ?? []) {
         if (raw.startsWith("http://") || raw.startsWith("https://")) {

package/dist/context/skills.js

@@ -1,7 +1,7 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { homedir } from "node:os";
-import { opencodeGlobalConfigDir } from "./paths.js";
+import { opencodeGlobalConfigDirs, opencodeProjectConfigDirs } from "./paths.js";
 async function exists(p) {
     try {
         await stat(p);
@@ -94,8 +94,13 @@ async function walkAncestorsFor(dir, rel, stop, out) {
 export async function collectSkills(workspaceRoot, worktree) {
     const out = new Map();
     const home = homedir();
-    await walkAncestorsFor(workspaceRoot, path.join(".opencode", "skills"), worktree, out);
-    await scanSkillsRoot(path.join(opencodeGlobalConfigDir(), "skills"), out);
+    for (const projectDir of opencodeProjectConfigDirs(workspaceRoot)) {
+        const relative = path.relative(workspaceRoot, projectDir);
+        await walkAncestorsFor(workspaceRoot, path.join(relative, "skills"), worktree, out);
+    }
+    for (const globalDir of opencodeGlobalConfigDirs()) {
+        await scanSkillsRoot(path.join(globalDir, "skills"), out);
+    }
     await walkAncestorsFor(workspaceRoot, path.join(".claude", "skills"), worktree, out);
     await scanSkillsRoot(path.join(home, ".claude", "skills"), out);
     await walkAncestorsFor(workspaceRoot, path.join(".agents", "skills"), worktree, out);

package/dist/language-model.js

@@ -6,7 +6,7 @@ import { trace, traceRequestContextPaths } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
 import { decodeMessage } from "./protocol/messages.js";
-import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildCustomWebToolAliases, resolveCustomWebToolAlias, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, } from "./protocol/tools.js";
+import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, } from "./protocol/tools.js";
 import { describeCursorExecVariant } from "./protocol/exec-variants.js";
 import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, } from "./protocol/tool-call-bridge.js";
 import { handleKvServerMessage } from "./protocol/kv.js";
@@ -463,6 +463,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         trace(`web tool alias: ${alias} -> ${original}`);
     }
     const allowTools = toolState.allowTools;
+    const discoveredSubagentCatalog = extractHostSubagentCatalog(cursorTools);
     const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
     const recovery = startOptions?.recovery;
     const resuming = recovery?.kind === "resume";
@@ -526,6 +527,23 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         headers: options.headers,
     });
     const requestContext = await buildRequestContext({ workspaceRoot, tools: cursorTools });
+    const contextSubagents = Array.isArray(requestContext.custom_subagents)
+        ? requestContext.custom_subagents
+            .map((agent) => agent && typeof agent === "object" && typeof agent.name === "string"
+            ? {
+                name: agent.name,
+                description: typeof agent.description === "string"
+                    ? agent.description
+                    : undefined,
+            }
+            : undefined)
+            .filter((agent) => !!agent)
+        : [];
+    const subagentCatalog = {
+        ...discoveredSubagentCatalog,
+        agents: [...new Map([...discoveredSubagentCatalog.agents, ...contextSubagents]
+                .map((agent) => [agent.name, agent])).values()],
+    };
     // Resolve descriptors once from the merged OpenCode config so MCP identity is
     // consistent across AgentRunRequest and both request_context reply paths.
     const toolDescriptors = Array.isArray(requestContext.tools)
@@ -603,6 +621,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         blobs: new Map(),
         toolDescriptors,
         toolAliases: webToolAliases.aliases,
+        subagentCatalog,
         requestContext,
         allowTools,
         usageEstimate,
@@ -961,6 +980,49 @@ export async function pump(session, controller, ids, abortSignal) {
             return true;
         }
     };
+    /**
+     * A read of a path that does not exist would otherwise reach OpenCode as a
+     * real tool call and raise a permission prompt for a file the user never had.
+     * Cursor's own LocalReadExecutor instead resolves the target against the
+     * workspace, stats it, and returns a typed ReadResult (file_not_found /
+     * invalid_file) before execution. Mirror that here: reply on the held-open
+     * exec channel with the exact typed case so the model receives a structured
+     * observation and the host surfaces no prompt.
+     *
+     * Read-only by construction — write/edit targets are never checked, so
+     * legitimate file creation (path resolves, file absent) is never denied. Runs
+     * after recoverMissingEditRead, which has already converted the new-file edit
+     * handshake read into an empty-file success. EACCES/EPERM and other stat
+     * errors fall through to OpenCode so a genuine permission decision stands.
+     */
+    const rejectMissingReadTarget = (parsed) => {
+        if (parsed.toolName !== "read")
+            return false;
+        const requested = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
+        if (!requested)
+            return false;
+        const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
+        const absolutePath = resolveReadTargetPath(requested, workspaceRoot);
+        const readResult = classifyMissingReadTarget(absolutePath);
+        if (!readResult)
+            return false;
+        try {
+            for (const frame of buildReadRejectionMessages(parsed.id, readResult)) {
+                session.stream.write(frame);
+            }
+            const kind = Object.keys(readResult)[0];
+            trace(`exec: rejected missing read target id=${parsed.id} kind=${kind} ` +
+                `path=${JSON.stringify(absolutePath)}`);
+            return true;
+        }
+        catch (e) {
+            const error = new Error(`Failed to reject Cursor read of a missing path: ${e.message}`);
+            trace(`exec: missing read rejection FAILED ${error.message}`);
+            safeError(error);
+            sessionManager.close(session);
+            return true;
+        }
+    };
     /** AI SDK V3 requires text-end / reasoning-end before finish or tool-call. */
     const closeOpenSpans = () => {
         for (const part of spanEndParts({ textStarted, reasoningStarted, textId, reasoningId })) {
@@ -1304,6 +1366,7 @@ export async function pump(session, controller, ids, abortSignal) {
                             trace(`web tool alias resolved: ${parsed.toolName} -> ${executableToolName}`);
                             parsed.toolName = executableToolName;
                         }
+                        remapNativeSubagentForCatalog(parsed, advertisedToolNameSet, session.subagentCatalog);
                     }
                     const displayCallId = extractExecDisplayCallId(esm);
                     trace(`exec: id=${parsed?.id} variant=${parsed ? Object.keys(parsed).join(",") : "none"} toolName=${parsed?.toolName} resultField=${parsed?.resultField}`);
@@ -1344,6 +1407,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         }
                         if (recoverMissingEditRead(parsed, displayCallId))
                             continue;
+                        if (rejectMissingReadTarget(parsed)) {
+                            if (displayCallId)
+                                session.displayToolCalls.delete(displayCallId);
+                            continue;
+                        }
                         if (displayCallId) {
                             session.displayToolCalls.delete(displayCallId);
                             trace(`exec: claimed display callId=${displayCallId}`);
@@ -1550,6 +1618,7 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.size === 0)
         return undefined;
     const instructions = [];
+    const subagents = extractHostSubagentCatalog(tools);
     if (names.has("question")) {
         instructions.push("- When user input is required, call the OpenCode `question` tool; do not use Cursor's native AskQuestion interaction.");
     }
@@ -1568,6 +1637,17 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.has(CUSTOM_WEBFETCH_TOOL)) {
         instructions.push(`- To fetch a known URL, call \`${CUSTOM_WEBFETCH_TOOL}\`; do not use Cursor's native WebFetch interaction.`);
     }
+    if (names.has("task") || names.has("actor")) {
+        const target = names.has("actor") ? "`actor`" : "`task`";
+        const available = subagents.agents.map((agent) => `\`${agent.name}\``).join(", ");
+        instructions.push(`- Native Cursor Task/subagent requests are executed through OpenCode ${target}. ` +
+            "Advertised custom subagent names are used exactly; otherwise `unspecified` and `generalPurpose` select host `general`, " +
+            "`bugbot`, `security-review`, and `explore` select host `explore` (then `general`), and other specialized Cursor types fall back to `general`." +
+            (available ? ` Spawnable host agents this turn: ${available}.` : ""));
+        if (subagents.agents.some((agent) => agent.name === "scout")) {
+            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`.");
+        }
+    }
     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."
@@ -1576,7 +1656,9 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     return [
         `OpenCode exposes exactly these executable tools for this turn: ${[...names].map((name) => `\`${name}\``).join(", ")}.`,
         `Workspace root: ${JSON.stringify(workspaceRoot)}. Resolve workspace paths against exactly this root; never invent an absolute prefix, and verify uncertain paths with an available tool before using them.`,
-        "Call only tools in that exact list. Cursor-native tools that are not listed—including Task/subagents—are unavailable; do not invoke them. If a capability is absent, complete the work directly with the listed tools or explain the limitation.",
+        subagents.executor
+            ? "Call only tools in that exact list. Cursor-native Task/subagent requests are permitted because a compatible host executor is listed; other unlisted Cursor-native tools remain unavailable."
+            : "Call only tools in that exact list. Cursor-native tools that are not listed—including Task/subagents—are unavailable; do not invoke them. If a capability is absent, complete the work directly with the listed tools or explain the limitation.",
         ...(instructions.length > 0
             ? ["Use these OpenCode tools instead of equivalent Cursor-native UI interactions:"]
             : []),

package/dist/protocol/messages.js

@@ -366,10 +366,29 @@ export function createMessageTypes() {
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "error", type: "string" },
     ]);
+    // Cursor's LocalReadExecutor validates the target before execution and, for a
+    // missing / non-regular path, returns one of these typed ReadResult cases
+    // instead of running the tool. Mirroring the exact field ids/shapes lets this
+    // provider reply the same way so the model sees a structured file-not-found
+    // observation and the host never surfaces a permission prompt.
+    addType(root, "ReadFileNotFound", [{ id: 1, name: "path", type: "string" }]);
+    addType(root, "ReadPermissionDenied", [{ id: 1, name: "path", type: "string" }]);
+    addType(root, "ReadInvalidFile", [
+        { id: 1, name: "path", type: "string" },
+        { id: 2, name: "reason", type: "string" },
+    ]);
     addType(root, "ReadResult", [
         { id: 1, name: "success", type: "ReadSuccess" },
         { id: 2, name: "error", type: "ReadError" },
-    ], [{ name: "result", fields: ["success", "error"] }]);
+        { id: 4, name: "file_not_found", type: "ReadFileNotFound" },
+        { id: 5, name: "permission_denied", type: "ReadPermissionDenied" },
+        { id: 6, name: "invalid_file", type: "ReadInvalidFile" },
+    ], [
+        {
+            name: "result",
+            fields: ["success", "error", "file_not_found", "permission_denied", "invalid_file"],
+        },
+    ]);
     addType(root, "GrepArgs", [
         { id: 1, name: "pattern", type: "string" },
         { id: 2, name: "path", type: "string" },

package/dist/protocol/tool-call-bridge.js

@@ -1,4 +1,4 @@
-import { mapCursorArgsToOpencode, mcpRealToolName } from "./tools.js";
+import { mapCursorArgsToOpencode, mapCursorSubagentTypeToOpenCode, mcpRealToolName } from "./tools.js";
 import { decodeStructEntriesToJson } from "./struct.js";
 const TODO_STATUS = {
     0: "pending",
@@ -334,7 +334,27 @@ function openCodeSubagentType(raw) {
     if (typeof custom?.name === "string" && custom.name.length > 0)
         return custom.name;
     if (subtype.explore != null)
-        return "explore";
+        return mapCursorSubagentTypeToOpenCode("explore");
+    if (subtype.cursor_guide != null)
+        return mapCursorSubagentTypeToOpenCode("cursor_guide");
+    if (subtype.bash != null)
+        return mapCursorSubagentTypeToOpenCode("bash");
+    if (subtype.shell != null)
+        return mapCursorSubagentTypeToOpenCode("shell");
+    if (subtype.debug != null)
+        return mapCursorSubagentTypeToOpenCode("debug");
+    if (subtype.computer_use != null)
+        return mapCursorSubagentTypeToOpenCode("computer_use");
+    if (subtype.browser_use != null)
+        return mapCursorSubagentTypeToOpenCode("browser_use");
+    if (subtype.media_review != null)
+        return mapCursorSubagentTypeToOpenCode("media_review");
+    if (subtype.watch_video != null)
+        return mapCursorSubagentTypeToOpenCode("watch_video");
+    if (subtype.vm_setup_helper != null)
+        return mapCursorSubagentTypeToOpenCode("vm_setup_helper");
+    if (subtype.unspecified != null)
+        return mapCursorSubagentTypeToOpenCode("unspecified");
     return undefined;
 }
 /** Advertised OpenCode tool ids from Cursor McpToolDefinition descriptors. */

package/dist/protocol/tools.d.ts

@@ -64,6 +64,29 @@ export declare function toolsToMcpDescriptors(tools: OpencodeToolDef[], provider
 export declare function buildLiveRequestContext(tools: OpencodeToolDef[], providerIdentifier?: string, knownMcpServers?: Iterable<string>): Record<string, unknown>;
 export declare function mapExecServerToToolName(execField: string): string | undefined;
 export declare function mapToolNameToExecField(toolName: string): string | undefined;
+export type HostSubagentDefinition = {
+    name: string;
+    description?: string;
+};
+export type HostSubagentCatalog = {
+    executor?: "task" | "actor";
+    agents: HostSubagentDefinition[];
+    /** True when the host tool supplied its complete, permission-filtered catalog. */
+    complete: boolean;
+};
+/** Extract the current host's permission-filtered Task/Actor recipient catalog. */
+export declare function extractHostSubagentCatalog(tools: OpencodeToolDef[]): HostSubagentCatalog;
+/** Resolve a Cursor subtype against the agents the host can spawn this turn. */
+export declare function resolveCursorSubagentType(subagentType: string, catalog?: HostSubagentCatalog): string | undefined;
+/**
+ * Cursor's native Task/subagent protocol uses Cursor-owned subtype names while
+ * OpenCode-family hosts execute named agents. Map known Cursor built-ins to
+ * the closest host agent and preserve unknown values so user-defined OpenCode
+ * agents can still be called by exact name.
+ */
+export declare function mapCursorSubagentTypeToOpenCode(subagentType: string): string;
+/** Resolve a native Cursor subagent request to this turn's executor and catalog. */
+export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, catalog?: HostSubagentCatalog): void;
 export type ParsedExecRequest = {
     id: number;
     execId: string;
@@ -92,6 +115,32 @@ export declare function mapCursorArgsToOpencode(toolName: string, raw: Record<st
  * → github_create_pull_request). Builtins under the default server stay bare.
  */
 export declare function mcpRealToolName(mcpArgs: Record<string, unknown>, defaultServer?: string): string;
+/**
+ * Resolve a read target the way Cursor's LocalReadExecutor does before it
+ * stats the file: untildify, then resolve a relative path against the workspace
+ * root (`env.workspace_paths[0]`), else resolve as-is. Kept in lockstep with
+ * agent utils `resolvePath(path, workspaceRoot)`.
+ */
+export declare function resolveReadTargetPath(requested: string, workspaceRoot: string): string;
+/**
+ * A typed ReadResult oneof case for a read target that fails Cursor's
+ * pre-execution validation, or undefined when the path is a readable file the
+ * tool should actually read. Mirrors LocalReadExecutor exactly:
+ *  - missing path (ENOENT/ENOTDIR)     → file_not_found
+ *  - directory                         → invalid_file "Path is a directory, not a file"
+ *  - socket/fifo/etc (not a file)      → invalid_file "Path is neither a file nor a directory"
+ * EACCES/EPERM (exists but unreadable) and any other stat error return undefined
+ * so the call proceeds to OpenCode and a genuine permission decision is never
+ * masked. Never rejects a non-existent *write/edit* target — this is read-only.
+ */
+export declare function classifyMissingReadTarget(absolutePath: string): Record<string, unknown> | undefined;
+/**
+ * Encode a pre-execution read rejection as the exact frames Cursor's client
+ * emits: the ExecClientMessage carrying the typed ReadResult oneof case, then
+ * the ACM #5 stream_close for that id. `readResult` is the case object from
+ * classifyMissingReadTarget (e.g. `{ file_not_found: { path } }`).
+ */
+export declare function buildReadRejectionMessages(execId: number, readResult: Record<string, unknown>): Uint8Array[];
 export type ToolResultInput = {
     execId: number;
     /** ExecClientMessage result field (from ParsedExecRequest.resultField). */

package/dist/protocol/tools.js

@@ -1,4 +1,6 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
 import { buildEnv } from "../context/env.js";
@@ -280,6 +282,200 @@ export function mapExecServerToToolName(execField) {
 export function mapToolNameToExecField(toolName) {
     return opencodeToolToCursor[toolName];
 }
+const CURSOR_SUBAGENT_TYPE_TO_OPENCODE = {
+    generalPurpose: "general",
+    "general-purpose": "general",
+    general_purpose: "general",
+    general: "general",
+    unspecified: "general",
+    "cursor-guide": "explore",
+    cursor_guide: "explore",
+    "best-of-n-runner": "general",
+    best_of_n_runner: "general",
+    bash: "general",
+    shell: "general",
+    debug: "general",
+    computer_use: "general",
+    computerUse: "general",
+    browser_use: "general",
+    browserUse: "general",
+    media_review: "general",
+    mediaReview: "general",
+    watch_video: "general",
+    watchVideo: "general",
+    vm_setup_helper: "general",
+    vmSetupHelper: "general",
+    explore: "explore",
+    bugbot: "explore",
+    "security-review": "explore",
+    security_review: "explore",
+};
+const SUBAGENT_CATALOG_MARKER = "Available agent types and the tools they have access to:";
+function parseSubagentDescriptionCatalog(description) {
+    if (!description)
+        return { found: false, agents: [] };
+    const marker = description.indexOf(SUBAGENT_CATALOG_MARKER);
+    if (marker < 0)
+        return { found: false, agents: [] };
+    const agents = [];
+    const lines = description.slice(marker + SUBAGENT_CATALOG_MARKER.length).split(/\r?\n/);
+    let started = false;
+    for (const line of lines) {
+        const match = line.match(/^\s*-\s+([^:]+):\s*(.*)$/);
+        if (!match) {
+            if (started && line.trim())
+                break;
+            continue;
+        }
+        started = true;
+        const name = match[1].trim().replace(/^`|`$/g, "");
+        if (!name)
+            continue;
+        const agentDescription = match[2].trim();
+        agents.push({
+            name,
+            ...(agentDescription ? { description: agentDescription } : {}),
+        });
+    }
+    return { found: true, agents };
+}
+function subagentTypeEnumValues(schema) {
+    const out = new Set();
+    const seen = new Set();
+    const visit = (value, propertyName) => {
+        if (!value || typeof value !== "object")
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, propertyName);
+            return;
+        }
+        const record = value;
+        if (propertyName === "subagent_type" && Array.isArray(record.enum)) {
+            for (const item of record.enum) {
+                if (typeof item === "string" && item)
+                    out.add(item);
+            }
+        }
+        for (const [key, child] of Object.entries(record))
+            visit(child, key);
+    };
+    visit(schema);
+    return [...out];
+}
+/** Extract the current host's permission-filtered Task/Actor recipient catalog. */
+export function extractHostSubagentCatalog(tools) {
+    const executorTool = tools.find((tool) => tool.name === "actor") ??
+        tools.find((tool) => tool.name === "task");
+    if (!executorTool)
+        return { agents: [], complete: true };
+    const described = parseSubagentDescriptionCatalog(executorTool.description);
+    const enumNames = subagentTypeEnumValues(executorTool.inputSchema);
+    const descriptions = new Map(described.agents.map((agent) => [agent.name, agent.description]));
+    // MiMo's Actor enum is stricter than its prose catalog (`mode: subagent`
+    // rather than every non-primary agent), so structured names are authoritative.
+    const names = new Set(enumNames.length > 0 ? enumNames : described.agents.map((agent) => agent.name));
+    return {
+        executor: executorTool.name,
+        agents: [...names].map((name) => ({
+            name,
+            ...(descriptions.get(name) ? { description: descriptions.get(name) } : {}),
+        })),
+        complete: enumNames.length > 0 || described.found,
+    };
+}
+const GENERIC_CURSOR_SUBAGENT_TYPES = new Set([
+    "generalPurpose",
+    "general-purpose",
+    "general_purpose",
+    "general",
+    "unspecified",
+]);
+function cursorSubagentCandidates(subagentType) {
+    if (GENERIC_CURSOR_SUBAGENT_TYPES.has(subagentType))
+        return ["general"];
+    if (subagentType === "cursor-guide" || subagentType === "cursor_guide") {
+        return ["scout", "explore", "general"];
+    }
+    if (subagentType === "explore" ||
+        subagentType === "bugbot" ||
+        subagentType === "security-review" ||
+        subagentType === "security_review") {
+        return ["explore", "general"];
+    }
+    return ["general"];
+}
+/** Resolve a Cursor subtype against the agents the host can spawn this turn. */
+export function resolveCursorSubagentType(subagentType, catalog) {
+    const available = new Set(catalog?.agents.map((agent) => agent.name) ?? []);
+    // Explicit host/custom names win. `unspecified` and general aliases are
+    // intentionally excluded so they always select the host's generic agent.
+    if (!GENERIC_CURSOR_SUBAGENT_TYPES.has(subagentType) && available.has(subagentType)) {
+        return subagentType;
+    }
+    const candidates = cursorSubagentCandidates(subagentType);
+    for (const candidate of candidates) {
+        if (available.has(candidate))
+            return candidate;
+    }
+    if (catalog?.complete)
+        return undefined;
+    return candidates[0];
+}
+/**
+ * Cursor's native Task/subagent protocol uses Cursor-owned subtype names while
+ * OpenCode-family hosts execute named agents. Map known Cursor built-ins to
+ * the closest host agent and preserve unknown values so user-defined OpenCode
+ * agents can still be called by exact name.
+ */
+export function mapCursorSubagentTypeToOpenCode(subagentType) {
+    return CURSOR_SUBAGENT_TYPE_TO_OPENCODE[subagentType] ?? subagentType;
+}
+/** Resolve a native Cursor subagent request to this turn's executor and catalog. */
+export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catalog) {
+    if (parsed.resultField !== "subagent_result" || parsed.toolName !== "task")
+        return;
+    const advertised = new Set(advertisedToolNames);
+    const executor = advertised.has("actor") ? "actor" : advertised.has("task") ? "task" : undefined;
+    if (!executor)
+        return;
+    const description = str(parsed.args.description) ?? "";
+    const prompt = str(parsed.args.prompt) ?? "";
+    const cursorSubagentType = str(parsed.resultMetadata?.cursor_subagent_type) ??
+        str(parsed.args.subagent_type) ?? "";
+    const subagentType = resolveCursorSubagentType(cursorSubagentType, catalog);
+    if (!subagentType) {
+        const available = catalog?.agents.map((agent) => agent.name).join(", ") || "none";
+        parsed.localError =
+            `Cursor subagent '${cursorSubagentType}' has no compatible host agent. ` +
+                `Available subagents: ${available}.`;
+        return;
+    }
+    const resumeAgentId = str(parsed.args.task_id);
+    parsed.toolName = executor;
+    if (executor === "task") {
+        parsed.args = {
+            description,
+            prompt,
+            subagent_type: subagentType,
+            ...(resumeAgentId ? { task_id: resumeAgentId } : {}),
+            ...(parsed.args.background === true ? { background: true } : {}),
+        };
+        return;
+    }
+    parsed.args = {
+        operation: {
+            action: parsed.args.background === true ? "spawn" : "run",
+            description,
+            prompt,
+            subagent_type: subagentType,
+            ...(resumeAgentId ? { actor_id: resumeAgentId } : {}),
+        },
+    };
+}
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -358,6 +554,9 @@ export function parseExecServerMessage(msg) {
             toolName: "task",
             args,
             resultField,
+            resultMetadata: cursorSubagentType
+                ? { cursor_subagent_type: cursorSubagentType }
+                : undefined,
             localError: prompt && cursorSubagentType
                 ? undefined
                 : "Cursor subagent request is missing a required prompt or subagent type.",
@@ -595,19 +794,6 @@ function describeSubagentTask(prompt, subagentType) {
         return words.join(" ");
     return `${subagentType || "Delegated"} task`;
 }
-function mapCursorSubagentTypeToOpenCode(subagentType) {
-    // Cursor's built-in general agent uses a camelCase protocol identifier, and
-    // its native Bugbot reviewer has no OpenCode-specific agent definition.
-    // OpenCode `general` is the general-purpose equivalent; `explore` preserves
-    // Bugbot's review-only/read-oriented semantics while retaining grep/read/bash.
-    // Preserve every other value so `explore` and configured custom agents keep
-    // their exact advertised names.
-    if (subagentType === "generalPurpose")
-        return "general";
-    if (subagentType === "bugbot")
-        return "explore";
-    return subagentType;
-}
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
@@ -667,6 +853,75 @@ function findOneOfVariant(msg, candidates) {
     }
     return undefined;
 }
+// ── Pre-execution read validation (Cursor LocalReadExecutor parity) ──
+/** Expand a leading `~` to the home directory, matching Cursor's untildify. */
+function untildify(input) {
+    return input.replace(/^~(?=$|\/|\\)/, os.homedir());
+}
+/**
+ * Resolve a read target the way Cursor's LocalReadExecutor does before it
+ * stats the file: untildify, then resolve a relative path against the workspace
+ * root (`env.workspace_paths[0]`), else resolve as-is. Kept in lockstep with
+ * agent utils `resolvePath(path, workspaceRoot)`.
+ */
+export function resolveReadTargetPath(requested, workspaceRoot) {
+    const expanded = untildify(requested);
+    if (workspaceRoot && !path.isAbsolute(expanded)) {
+        return path.resolve(workspaceRoot, expanded);
+    }
+    return path.resolve(expanded);
+}
+/**
+ * A typed ReadResult oneof case for a read target that fails Cursor's
+ * pre-execution validation, or undefined when the path is a readable file the
+ * tool should actually read. Mirrors LocalReadExecutor exactly:
+ *  - missing path (ENOENT/ENOTDIR)     → file_not_found
+ *  - directory                         → invalid_file "Path is a directory, not a file"
+ *  - socket/fifo/etc (not a file)      → invalid_file "Path is neither a file nor a directory"
+ * EACCES/EPERM (exists but unreadable) and any other stat error return undefined
+ * so the call proceeds to OpenCode and a genuine permission decision is never
+ * masked. Never rejects a non-existent *write/edit* target — this is read-only.
+ */
+export function classifyMissingReadTarget(absolutePath) {
+    let stat;
+    try {
+        stat = fs.statSync(absolutePath);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            return { file_not_found: { path: absolutePath } };
+        }
+        return undefined;
+    }
+    if (stat.isDirectory()) {
+        return { invalid_file: { path: absolutePath, reason: "Path is a directory, not a file" } };
+    }
+    if (!stat.isFile()) {
+        return {
+            invalid_file: { path: absolutePath, reason: "Path is neither a file nor a directory" },
+        };
+    }
+    return undefined;
+}
+/**
+ * Encode a pre-execution read rejection as the exact frames Cursor's client
+ * emits: the ExecClientMessage carrying the typed ReadResult oneof case, then
+ * the ACM #5 stream_close for that id. `readResult` is the case object from
+ * classifyMissingReadTarget (e.g. `{ file_not_found: { path } }`).
+ */
+export function buildReadRejectionMessages(execId, readResult) {
+    return [
+        encodeMessage("AgentClientMessage", {
+            exec_client_message: {
+                id: execId,
+                local_execution_time_ms: 0,
+                read_result: readResult,
+            },
+        }),
+        buildExecStreamClose(execId),
+    ];
+}
 /**
  * Build one or more ExecClientMessage frames for a tool result.
  * Shell replies are a sequence of ShellStream oneofs under the same id —

package/dist/session.d.ts

@@ -1,7 +1,7 @@
 import type { BidiStream } from "./transport/connect.js";
 import { type CursorProviderError } from "./errors.js";
 import { type SessionActivitySource } from "./activity.js";
-import type { ToolAliasRegistry } from "./protocol/tools.js";
+import type { HostSubagentCatalog, ToolAliasRegistry } from "./protocol/tools.js";
 export type Frame = {
     flags: number;
     payload: Uint8Array;
@@ -120,6 +120,8 @@ export type CursorSession = {
     toolDescriptors: Array<Record<string, unknown>>;
     /** Cursor-facing web alias → exact executable host tool for this Run. */
     toolAliases?: ToolAliasRegistry;
+    /** Spawnable host agents extracted from this turn's Task/Actor definition. */
+    subagentCatalog?: HostSubagentCatalog;
     /** Full RequestContext for exec #10 replies. */
     requestContext: Record<string, unknown>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -75,4 +75,4 @@
     "@types/node": "^22.15.3",
     "typescript": "^5.8.3"
   }
-}
+}