cursor-opencode-provider 0.2.6 → 0.2.7

package/README.md

@@ -102,15 +102,23 @@ Choose the **cursor** provider, then one of:
 | **Cursor account (browser login)** | PKCE OAuth — opens cursor.com to sign in |
 | **API key** | Paste a key from [cursor.com/settings](https://cursor.com/settings) (`sk-...`) |
 
-After login, the plugin fetches your available models and writes them to `~/.cache/opencode/cursor-models.json` (or `$XDG_CACHE_HOME/opencode/` when set). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails.
+After login, the plugin fetches your available models and writes them to `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails.
 
-### Paths (XDG)
+### Paths (host cache)
 
-| Kind | Default | Override |
-|------|---------|----------|
-| Model / version **cache** | `~/.cache/opencode/` | `$XDG_CACHE_HOME/opencode/` |
-| OpenCode **auth** (`auth.json`) | `~/.local/share/opencode/` | `$XDG_DATA_HOME/opencode/` |
-| OpenCode **config** (AGENTS, skills, …) | `~/.config/opencode/` | (config dir helper; not the model cache) |
+Model/version caches and Cursor project metadata live under a **host cache root**, resolved in this order:
+
+1. Explicit `createCursor({ cacheDir })` / Effect v2 `Path.cache`
+2. Optional `@opencode-compat/profile` `detect()` when that peer is installed and the host is supported
+3. Local heuristic: `$MIMOCODE_HOME/cache`, then host-named dirs under `$XDG_CACHE_HOME` (Kilo, then MiMo, then OpenCode)
+4. Default `~/.cache/opencode/`
+
+| Kind | Default (OpenCode) | Notes |
+|------|--------------------|-------|
+| Model / version **cache** | `~/.cache/opencode/` | MiMo: `$MIMOCODE_HOME/cache` or `~/.cache/mimocode/`; Kilo: `~/.cache/kilo/` |
+| Cursor **project metadata** (`agent-tools`, terminals, …) | `~/.cache/opencode/projects/<slug>/` | under `<host-cache>/projects/` |
+| OpenCode **auth** (`auth.json`) | `~/.local/share/opencode/` | `$XDG_DATA_HOME/opencode/` when set |
+| OpenCode **config** (AGENTS, skills, …) | `~/.config/opencode/` | still OpenCode-named for rule discovery |
 
 ### Select a model
 
@@ -157,6 +165,7 @@ const cursor = createCursor({
   // apiBaseURL: "https://api2.cursor.sh",
   // agentBaseURL: "https://agentn.us.api5.cursor.sh", // explicit Run host override
   // telemetryEnabled: true, // opt in to GetServerConfig telemetry
+  // cacheDir: "/path/to/host/cache", // optional; else host heuristic / ~/.cache/opencode
   // retry: { maxAttempts: 3, baseDelayMs: 500, maxDelayMs: 8_000 },
   // continuation: { heartbeatMs: 5_000, semanticIdleMs: 120_000, hardCapMs: 600_000 },
 })
@@ -165,7 +174,7 @@ const model = cursor.languageModel("composer-2.5")
 // model implements AI SDK LanguageModelV3 (doStream / doGenerate)
 ```
 
-Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. Transient failures resume from the latest checkpoint produced by that Run, matching Cursor CLI; without an eligible checkpoint, retries remain limited to replay-safe attempts so completed text or tool work is not duplicated. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
+Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `cacheDir`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. `cacheDir` pins the host cache root for model/version caches and Cursor project metadata; when omitted, the provider uses OCP `@opencode-compat/profile` detect (if installed) or the local MiMo/Kilo/OpenCode heuristic described in [Paths](#paths-host-cache). Transient failures resume from the latest checkpoint produced by that Run, matching Cursor CLI; without an eligible checkpoint, retries remain limited to replay-safe attempts so completed text or tool work is not duplicated. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
 
 ## Environment variables
 
@@ -176,7 +185,9 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-
 | `CURSOR_GET_SERVER_CONFIG_TELEMETRY` | Set to `1` or `true` to opt the `GetServerConfig` lookup into telemetry in OpenCode/plugin usage |
 | `CURSOR_PROVIDER_DEBUG` | Set to `1` or `true` to enable wire-level debug logging |
 | `CURSOR_PROVIDER_DEBUG_FILE` | Debug log path (default: `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) |
-| `XDG_CACHE_HOME` | When set, model/version caches go under `$XDG_CACHE_HOME/opencode/` instead of `~/.cache/opencode/` |
+| `XDG_CACHE_HOME` | Base for host cache dirs (`$XDG_CACHE_HOME/opencode/`, `…/mimocode/`, or `…/kilo/`) when no explicit `cacheDir` / OCP detect override |
+| `MIMOCODE_HOME` | When set, host cache is `$MIMOCODE_HOME/cache` (MiMo) |
+| `KILO_CONFIG_DIR` | When set (or `~/.config/kilo` exists), host cache is `$XDG_CACHE_HOME/kilo` |
 | `XDG_DATA_HOME` | When set, OpenCode `auth.json` is read from `$XDG_DATA_HOME/opencode/` instead of `~/.local/share/opencode/` |
 
 `createCursor({ agentBaseURL })` overrides the agent Run host. When unset, the provider resolves the host from Cursor's `GetServerConfig` API (`agentUrlConfig.agentnUrl`, region-specific — e.g. `agentn.us.api5.cursor.sh`, `agent-gcpp-uswest.api5.cursor.sh`) once per process and holds it in memory (never written to disk), so a held-open Run stream is never repointed mid-session. Explicit agent overrides and GetServerConfig results are validated as HTTPS `*.cursor.sh` hosts (Cursor's agent hostnames vary and may change); non-`cursor.sh` hosts are rejected. Shared HTTP/2 connections are rotated before they become server-aged, while existing Runs may finish on their original connection. The lookup sends `{ "telem_enabled": false }` by default; set `telemetryEnabled: true` in provider config, or `CURSOR_GET_SERVER_CONFIG_TELEMETRY=1` for OpenCode/plugin usage, to opt in. If the lookup fails or does not return a valid Cursor agent host, the model call fails clearly instead of falling back to `agentn.global.api5.cursor.sh`.
@@ -213,6 +224,7 @@ OpenCode
 | `src/debug.ts` | Opt-in wire-level debug logging (`CURSOR_PROVIDER_DEBUG`) |
 | `src/auth.ts` | PKCE OAuth, API key exchange, JWT refresh |
 | `src/models.ts` | `AvailableModels` fetch and `cursor-models.json` cache |
+| `src/context/paths.ts` | Host cache root + Cursor project metadata under `<host-cache>/projects/<slug>/` |
 | `src/agent-url.ts` | `GetServerConfig` fetch + in-process memo (region-specific Run host) |
 | `src/transport/connect.ts` | HTTP/2 bidi stream and unary RPC calls |
 | `src/protocol/` | Protobuf encode/decode, checksum/device ids, exec + display tool-call mapping (`tool-call-bridge.ts`) |
@@ -241,7 +253,7 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | No Cursor models in the picker | Confirm Cursor auth (`opencode auth login` → **cursor**). Restart OpenCode — if auth is present and the cache is empty, models are fetched on startup. Confirm `provider.cursor.npm` is the package name (or a built `file://…/dist/index.js`). |
 | Auth / 401 errors mid-session | Re-login. OAuth and exchanged API-key JWTs refresh automatically when near expiry; a revoked refresh token needs a fresh login. |
 | “Too many connections from different devices” | Device IDs are derived from stable OS identifiers (same approach as the Cursor CLI). Avoid running multiple clients that invent different machine fingerprints for the same account. |
-| Empty or stale model list | Delete `~/.cache/opencode/cursor-models.json` (or under `$XDG_CACHE_HOME/opencode/`) and restart OpenCode. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
+| Empty or stale model list | Delete `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`, or MiMo/Kilo host cache) and restart OpenCode. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
 | Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, resumes transient interruptions from the latest eligible Cursor checkpoint, and falls back to a fresh-history rebase only before stateful output when no checkpoint exists. Repeated interruption is surfaced as an error instead of a false successful stop; retry the turn after checking connectivity. With debug logging enabled, look for `Run interrupted`, `resuming … checkpoint`, or `rebasing fresh Run`. Restart OpenCode after rebuilding a local `file://` install. |
 | No response / silent 200 + close | HTTP 200 alone is not a successful agent turn: the provider now requires Cursor's explicit `turn_ended`, captures HTTP/2 trailers/GOAWAY, and recovers once from bare EOF. The Run host still comes from in-memory `GetServerConfig` resolution; set `CURSOR_PROVIDER_DEBUG=1` to confirm the host and termination reason. |
 | Visible `<shell_metadata>` timeout text | Rebuild and restart a local install. Cursor's shell timeout is carried on its exec request; the provider now removes OpenCode's internal timeout envelope before it is rendered or stored, then returns Cursor's typed timeout or background-handoff event instead of treating the text as successful stdout. |
@@ -255,11 +267,11 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 ## Known limitations
 
 - **Personal use / ToS** — this provider speaks Cursor’s private agent protocol (CLI-shaped client identity). Use only with an account you own; Cursor may change or restrict the API without notice.
-- **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
+- **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. `env.workspace_paths` / `process_working_directory` stay on the real git workspace; Cursor's metadata root (`project_folder`, MCP `workspace_project_dir`, terminals/transcripts) is advertised under `<host-cache>/projects/<slug>/` (default `~/.cache/opencode/projects/…`) so dumps like `agent-tools/` do not land in the repo. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
 - **Configured MCP tools keep their upstream server id** — OpenCode builtins and plugin/custom tools are advertised under a synthetic `opencode` MCP server. Tools whose flattened name matches an MCP server in merged `opencode.json` configuration (`github_create_pull_request`, …) are grouped into that server's `mcp_descriptors` / `provider_identifier` (`github`, …). Unknown underscore-containing names stay under `opencode` rather than being guessed incorrectly. Cursor's MCP-state exec probe is answered from the same advertised descriptors before the actual tool request, using the full canonical tool-definition identity required by native `get_mcp_tools`; exec still reconstructs the full OpenCode tool id.
 - **Display completions are notifications, not execution requests** — Cursor `tool_call_*` frames use a typed `ToolCall` oneof. The provider decodes them for diagnostics but only mirrors finalized todo/plan state (`update_todos_tool_call` / `create_plan_tool_call`) into advertised OpenCode `todowrite`; the completed payload already contains the authoritative final list. Interactive, data-returning, and side-effecting completions are never replayed as new tools because their result could not be returned to Cursor. Exec-backed native subagent/Task and Pi read/bash/edit/write/grep/find/ls calls use their typed request/result fields instead. Unknown display variants are logged. All 37 Cursor CLI exec request/result pairs are inventoried by field and name; known-but-unsupported and future unknown exec variants fail explicitly rather than receiving a guessed response that could deadlock the Run.
 - **Tool availability is per OpenCode agent** — Cursor can request native capabilities such as Task even when a child or restricted OpenCode agent did not advertise the corresponding host tool. The provider prompts Cursor with the exact current catalog and checks every decoded host-tool exec request against it. An unavailable request is answered on Cursor's correlated typed result channel and is never emitted as OpenCode's `invalid` tool.
-- **Background shells are non-interactive** — Cursor's native background-shell spawn and soft-background shell-stream timeouts are bridged through OpenCode's foreground-only `bash` tool. The OpenCode UI keeps the original command; wrapping happens via the classic plugin's `shell.env` injectors (`BASH_ENV` / `ZDOTDIR`) so permissions still see the real user command. Spawn/soft-bg wrappers detach with `nohup`, redirect output under `${TMPDIR:-/tmp}/cursor-opencode-{bg,shell}.*`, and return the real PID (or typed timeout/exit) to Cursor. Private markers and OpenCode's `<shell_metadata>` envelope are stripped before storage/render, with a short still-running / started / timed-out status line left for the bash bubble. Requests that require `write_shell_stdin` are rejected explicitly because OpenCode does not expose an interactive background-process lifecycle through its AI SDK tool interface. The POSIX wrap path is not implemented for native Windows PowerShell/`cmd`.
+- **Background shells are non-interactive** — Cursor's native background-shell spawn and soft-background shell-stream timeouts are bridged through OpenCode's foreground-only `bash` tool. With bash/zsh, the classic plugin keeps the original permission/UI command and executes the wrapper through `shell.env` (`BASH_ENV` / `ZDOTDIR`); OpenCode's non-interactive sh/dash argv ignores those startup variables, so the plugin uses a short `exec /bin/sh '<wrapper-file>'` command backed by the same private wrapper. Native background-spawn requests also carry a self-contained marker-producing fallback when the classic hooks are absent. Spawn/soft-bg wrappers detach with `nohup`, redirect output under `${TMPDIR:-/tmp}/cursor-opencode-{bg,shell}.*`, and return the real PID (or typed timeout/exit) to Cursor. Private markers and OpenCode's `<shell_metadata>` envelope are stripped before storage/render, with a short still-running / started / timed-out status line left for the bash bubble. Requests that require `write_shell_stdin` are rejected explicitly because OpenCode does not expose an interactive background-process lifecycle through its AI SDK tool interface. The POSIX wrap path is not implemented for native Windows PowerShell/`cmd`.
 - **Cursor-native interaction queries remain headless** — Cursor UI/approval *queries* (as distinct from display tool calls) still cannot be surfaced through the AI SDK provider interface. The normal system prompt redirects questions, planning, plan-mode transitions, and known-URL fetching to equivalent OpenCode tools only when they are advertised (`question`, `todowrite`, `plan_enter` / `plan_exit`, `webfetch`); native web/PR/MCP/image/SCM requests are declined so they remain behind OpenCode's tools and permissions. Separately from display `create_plan_tool_call` → `todowrite` mirroring, interaction `create_plan_request_query` is auto-acked (CLI headless parity) with success and an empty `plan_uri`, so Cursor may treat the plan as accepted without an OpenCode UI confirm. Compaction prompts are unchanged. Unknown future interaction variants fail the turn explicitly instead of hanging the Run stream.
 - **Compaction resets Cursor conversation state** — the classic plugin marks OpenCode's `compaction` agent explicitly. On those turns the provider mints an isolated Cursor `conversation_id`, drops the prior checkpoint + KV blobs, preserves real tool outputs as OpenCode-host observations in the seed history, and re-advertises the session's last tool catalog while refusing execution during the summary itself. The first normal turn then rebases once more onto a fresh conversation seeded with OpenCode's compacted prompt and normal system instructions, so the summary-agent checkpoint cannot suppress later tool calls. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state.
 - **Conversation bindings and compaction catalogs are bounded** — process-global per-session bindings, prior tool catalogs, and pending post-compaction rebases use a 256-session LRU bound. Evicting a conversation binding also drops its checkpoint and KV blobs.

package/dist/context/build.js

@@ -7,6 +7,8 @@ import { collectPlugins } from "./plugins.js";
 import { collectGit } from "./git.js";
 import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
+import { ensureOpencodeProjectDir } from "./paths.js";
+import { traceRequestContextPaths } from "../debug.js";
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Sourced from OpenCode discovery (and .claude/.agents skill fallbacks).
@@ -27,6 +29,7 @@ export async function buildRequestContext(input) {
     const mcpServerNames = Object.keys(config.mcp ?? {});
     const flat = toolsToDescriptors(tools, providerIdentifier, mcpServerNames);
     const nested = toolsToMcpDescriptors(tools, providerIdentifier, mcpServerNames);
+    const projectDir = ensureOpencodeProjectDir(workspaceRoot);
     const ctx = {
         env: buildEnv(workspaceRoot),
         tools: flat,
@@ -50,7 +53,8 @@ export async function buildRequestContext(input) {
         })),
         mcp_file_system_options: {
             enabled: true,
-            workspace_project_dir: workspaceRoot,
+            // Cursor metadata root (mcps / agent-tools), not the git workspace.
+            workspace_project_dir: projectDir,
             mcp_descriptors: nested,
         },
         mcp_meta_tool_options: {
@@ -73,5 +77,6 @@ export async function buildRequestContext(input) {
             .map((p) => `opencode-plugin:${p.source}:${p.id}`)
             .join("\n");
     }
+    traceRequestContextPaths("buildRequestContext", ctx);
     return ctx;
 }

package/dist/context/env.d.ts

@@ -1 +1,7 @@
 export declare function buildEnv(workspaceRoot: string): Record<string, unknown>;
+/**
+ * Real workspace root for path resolution (edits, reads, …).
+ * Uses `env.workspace_paths[0]` — never `project_folder` /
+ * `mcp_file_system_options.workspace_project_dir` (those are Cursor metadata roots).
+ */
+export declare function workspaceRootFromRequestContext(requestContext: Record<string, unknown> | undefined): string;

package/dist/context/env.js

@@ -1,5 +1,7 @@
 import { homedir } from "node:os";
 import path from "node:path";
+import { trace } from "../debug.js";
+import { ensureOpencodeProjectDir } from "./paths.js";
 export function buildEnv(workspaceRoot) {
     const cwd = path.resolve(workspaceRoot);
     let timeZone = "UTC";
@@ -15,15 +17,45 @@ export function buildEnv(workspaceRoot) {
         const r = process.release?.version;
         return r ? `${p} ${r}` : p;
     })();
-    return {
+    // Cursor's project_folder is a metadata root (agent-tools, terminals, …),
+    // not the git workspace. Keep dumps under OpenCode cache.
+    const projectFolder = ensureOpencodeProjectDir(cwd);
+    const env = {
         os_version: osVersion,
         workspace_paths: [cwd],
         shell: process.env.SHELL || "/bin/bash",
         sandbox_enabled: false,
         sandbox_supported: false,
         time_zone: timeZone,
-        project_folder: cwd,
+        project_folder: projectFolder,
+        terminals_folder: path.join(projectFolder, "terminals"),
+        agent_transcripts_folder: path.join(projectFolder, "agent-transcripts"),
         process_working_directory: process.cwd(),
         is_working_dir_home_dir: path.resolve(process.cwd()) === path.resolve(home),
     };
+    trace(`buildEnv: workspace_paths=${JSON.stringify(env.workspace_paths)} ` +
+        `project_folder=${env.project_folder} ` +
+        `terminals_folder=${env.terminals_folder} ` +
+        `agent_transcripts_folder=${env.agent_transcripts_folder} ` +
+        `process_working_directory=${env.process_working_directory}`);
+    return env;
+}
+/**
+ * Real workspace root for path resolution (edits, reads, …).
+ * Uses `env.workspace_paths[0]` — never `project_folder` /
+ * `mcp_file_system_options.workspace_project_dir` (those are Cursor metadata roots).
+ */
+export function workspaceRootFromRequestContext(requestContext) {
+    const env = requestContext?.env;
+    if (env && typeof env === "object") {
+        const paths = env.workspace_paths;
+        if (Array.isArray(paths) && typeof paths[0] === "string" && paths[0].trim()) {
+            const root = path.resolve(paths[0]);
+            trace(`workspaceRootFromRequestContext: using workspace_paths[0]=${root}`);
+            return root;
+        }
+    }
+    const fallback = process.cwd();
+    trace(`workspaceRootFromRequestContext: workspace_paths missing; fallback cwd=${fallback}`);
+    return fallback;
 }

package/dist/context/index.d.ts

@@ -1,2 +1,2 @@
 export { buildRequestContext, type BuildRequestContextInput } from "./build.js";
-export { opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir } from "./paths.js";
+export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/index.js

@@ -1,2 +1,2 @@
 export { buildRequestContext } from "./build.js";
-export { opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir } from "./paths.js";
+export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/paths.d.ts

@@ -1,8 +1,30 @@
-/** OpenCode global config dir (`~/.config/opencode`). */
+export type HostPathEnv = NodeJS.ProcessEnv;
+/**
+ * Pin the process-wide cache root. Highest precedence for {@link opencodeGlobalCacheDir}.
+ * Use for host-injected `Path.cache` or an explicit `createCursor({ cacheDir })`.
+ */
+export declare function setHostCacheDirOverride(dir: string | undefined): void;
+export declare function getHostCacheDirOverride(): string | undefined;
+/**
+ * Resolve the host cache directory without an override.
+ * Mirrors OCP HostProfile drafts: MiMo (`mimocode` / `$MIMOCODE_HOME`), Kilo (`kilo`),
+ * then OpenCode (`opencode`). Prefer fork config dirs when several exist.
+ */
+export declare function resolveHostCacheDir(env?: HostPathEnv): string;
+/**
+ * Best-effort: if `@opencode-compat/profile` is installed, adopt `detect().profile.paths.cacheDir`
+ * when the host is supported. No-op when OCP is absent or detection fails.
+ */
+export declare function adoptCompatHostCacheDir(): Promise<string | undefined>;
+/** OpenCode / host global config dir (`~/.config/<app>`). Still OpenCode-named for rule discovery. */
 export declare function opencodeGlobalConfigDir(): string;
 /**
- * OpenCode global cache dir (`~/.cache/opencode`).
- * Uses `$XDG_CACHE_HOME/opencode` when set, otherwise `$HOME/.cache/opencode`.
+ * Host global cache dir for Cursor project metadata + model/version caches.
+ *
+ * Precedence:
+ * 1. {@link setHostCacheDirOverride} / `createCursor({ cacheDir })` (host `Path.cache`)
+ * 2. OCP `detect()` when {@link adoptCompatHostCacheDir} ran successfully
+ * 3. Local host heuristic ({@link resolveHostCacheDir})
  */
 export declare function opencodeGlobalCacheDir(): string;
 /**
@@ -11,4 +33,20 @@ export declare function opencodeGlobalCacheDir(): string;
  * Auth credentials live here in `auth.json`.
  */
 export declare function opencodeGlobalDataDir(): string;
+/**
+ * Cursor-compatible path slug (`/Users/a/b` → `Users-a-b`).
+ * Used for per-workspace metadata under the host cache.
+ */
+export declare function slugifyWorkspacePath(workspaceRoot: string): string;
+/**
+ * Cursor-style project metadata root for a workspace.
+ * Lives at `<host-cache>/projects/<slug>/` (OpenCode / MiMo / Kilo cache root).
+ *
+ * This is what Cursor's RequestContextEnv.project_folder / MCP
+ * workspace_project_dir point at — agent-tools, terminals, transcripts, etc.
+ * Must NOT be the git workspace, or those dumps land in the repo.
+ */
+export declare function opencodeProjectDir(workspaceRoot: string): string;
+/** Ensure {@link opencodeProjectDir} exists (mode 0o700) and return it. */
+export declare function ensureOpencodeProjectDir(workspaceRoot: string): string;
 export declare function resolveHomeRelative(p: string): string;

package/dist/context/paths.js

@@ -1,21 +1,92 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-function resolveHome() {
-    return process.env.HOME || process.env.USERPROFILE || homedir();
+import { trace } from "../debug.js";
+/** Explicit host cache root (e.g. Effect v2 `Path.cache`, or `createCursor({ cacheDir })`). */
+let hostCacheDirOverride;
+function resolveHome(env = process.env) {
+    return env.HOME || env.USERPROFILE || homedir();
 }
-/** OpenCode global config dir (`~/.config/opencode`). */
+function xdgCacheHome(env = process.env) {
+    if (env.XDG_CACHE_HOME && env.XDG_CACHE_HOME.length > 0)
+        return env.XDG_CACHE_HOME;
+    return path.join(resolveHome(env), ".cache");
+}
+function xdgConfigHome(env = process.env) {
+    if (env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.length > 0)
+        return env.XDG_CONFIG_HOME;
+    return path.join(resolveHome(env), ".config");
+}
+/**
+ * Pin the process-wide cache root. Highest precedence for {@link opencodeGlobalCacheDir}.
+ * Use for host-injected `Path.cache` or an explicit `createCursor({ cacheDir })`.
+ */
+export function setHostCacheDirOverride(dir) {
+    hostCacheDirOverride = dir && dir.length > 0 ? path.resolve(dir) : undefined;
+}
+export function getHostCacheDirOverride() {
+    return hostCacheDirOverride;
+}
+/**
+ * Resolve the host cache directory without an override.
+ * Mirrors OCP HostProfile drafts: MiMo (`mimocode` / `$MIMOCODE_HOME`), Kilo (`kilo`),
+ * then OpenCode (`opencode`). Prefer fork config dirs when several exist.
+ */
+export function resolveHostCacheDir(env = process.env) {
+    const mimoHome = env.MIMOCODE_HOME;
+    if (mimoHome && mimoHome.length > 0) {
+        return path.join(mimoHome, "cache");
+    }
+    const configHome = xdgConfigHome(env);
+    const cacheHome = xdgCacheHome(env);
+    const kiloConfig = env.KILO_CONFIG_DIR;
+    // Prefer more specific fork dirs before OpenCode (same order as OCP detect).
+    if ((kiloConfig && kiloConfig.length > 0) || existsSync(path.join(configHome, "kilo"))) {
+        return path.join(cacheHome, "kilo");
+    }
+    if (existsSync(path.join(configHome, "mimocode"))) {
+        return path.join(cacheHome, "mimocode");
+    }
+    return path.join(cacheHome, "opencode");
+}
+/**
+ * Best-effort: if `@opencode-compat/profile` is installed, adopt `detect().profile.paths.cacheDir`
+ * when the host is supported. No-op when OCP is absent or detection fails.
+ */
+export async function adoptCompatHostCacheDir() {
+    try {
+        const { detect } = await import("@opencode-compat/profile");
+        const result = detect();
+        if (!result.supported || result.id === "unknown")
+            return undefined;
+        const cacheDir = result.profile.paths.cacheDir;
+        if (!cacheDir || cacheDir.length === 0)
+            return undefined;
+        setHostCacheDirOverride(cacheDir);
+        trace(`host-cache: adopted OCP detect cacheDir=${cacheDir} host=${result.id}`);
+        return cacheDir;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** OpenCode / host global config dir (`~/.config/<app>`). Still OpenCode-named for rule discovery. */
 export function opencodeGlobalConfigDir() {
     return path.join(resolveHome(), ".config", "opencode");
 }
 /**
- * OpenCode global cache dir (`~/.cache/opencode`).
- * Uses `$XDG_CACHE_HOME/opencode` when set, otherwise `$HOME/.cache/opencode`.
+ * Host global cache dir for Cursor project metadata + model/version caches.
+ *
+ * Precedence:
+ * 1. {@link setHostCacheDirOverride} / `createCursor({ cacheDir })` (host `Path.cache`)
+ * 2. OCP `detect()` when {@link adoptCompatHostCacheDir} ran successfully
+ * 3. Local host heuristic ({@link resolveHostCacheDir})
  */
 export function opencodeGlobalCacheDir() {
-    if (process.env.XDG_CACHE_HOME) {
-        return path.join(process.env.XDG_CACHE_HOME, "opencode");
-    }
-    return path.join(resolveHome(), ".cache", "opencode");
+    if (hostCacheDirOverride)
+        return hostCacheDirOverride;
+    return resolveHostCacheDir();
 }
 /**
  * OpenCode global data dir (`~/.local/share/opencode`).
@@ -28,6 +99,47 @@ export function opencodeGlobalDataDir() {
     }
     return path.join(resolveHome(), ".local", "share", "opencode");
 }
+/**
+ * Cursor-compatible path slug (`/Users/a/b` → `Users-a-b`).
+ * Used for per-workspace metadata under the host cache.
+ */
+export function slugifyWorkspacePath(workspaceRoot) {
+    const resolved = path.resolve(workspaceRoot);
+    return resolved
+        .replace(/[^a-zA-Z0-9]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Cursor-style project metadata root for a workspace.
+ * Lives at `<host-cache>/projects/<slug>/` (OpenCode / MiMo / Kilo cache root).
+ *
+ * This is what Cursor's RequestContextEnv.project_folder / MCP
+ * workspace_project_dir point at — agent-tools, terminals, transcripts, etc.
+ * Must NOT be the git workspace, or those dumps land in the repo.
+ */
+export function opencodeProjectDir(workspaceRoot) {
+    const projectsRoot = path.join(opencodeGlobalCacheDir(), "projects");
+    const slug = slugifyWorkspacePath(workspaceRoot);
+    let dir = path.join(projectsRoot, slug);
+    // Mirror Cursor's long-path guard so nested agent-tools paths stay usable.
+    if (dir.length > 92) {
+        const hash = createHash("sha256").update(dir).digest("hex").slice(0, 7);
+        dir = `${dir.slice(0, Math.min(84, dir.length))}-${hash}`;
+    }
+    return dir;
+}
+/** Ensure {@link opencodeProjectDir} exists (mode 0o700) and return it. */
+export function ensureOpencodeProjectDir(workspaceRoot) {
+    const resolved = path.resolve(workspaceRoot);
+    const dir = opencodeProjectDir(resolved);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    trace(`project-dir: workspace=${resolved} slug=${slugifyWorkspacePath(resolved)} ` +
+        `dir=${dir} cache_root=${opencodeGlobalCacheDir()} ` +
+        `override=${hostCacheDirOverride ?? "(none)"} ` +
+        `xdg_cache_home=${process.env.XDG_CACHE_HOME ?? "(unset)"}`);
+    return dir;
+}
 export function resolveHomeRelative(p) {
     if (p.startsWith("~/"))
         return path.join(homedir(), p.slice(2));

package/dist/debug.d.ts

@@ -1,3 +1,5 @@
+/** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
+export declare function isDebugEnabled(): boolean;
 /** Resolve the debug log path (env override or per-uid tmpdir default). */
 export declare function resolveDebugLogPath(): string;
 /**
@@ -8,3 +10,8 @@ export declare function ensureSecureDebugLog(filePath: string, options?: {
     secureParent?: boolean;
 }): void;
 export declare function trace(msg: string): void;
+/**
+ * Compact path-advertising summary for RequestContext troubleshooting.
+ * Safe: no tokens / file contents — only workspace vs metadata roots.
+ */
+export declare function traceRequestContextPaths(label: string, requestContext: Record<string, unknown> | undefined): void;

package/dist/debug.js

@@ -10,6 +10,11 @@ const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
 let _traceInitialized = false;
 let _debugFile;
 let _debugFileUsesManagedDirectory = false;
+let _announcedLogPath = false;
+/** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
+export function isDebugEnabled() {
+    return DEBUG_ENABLED;
+}
 /** Resolve the debug log path (env override or per-uid tmpdir default). */
 export function resolveDebugLogPath() {
     if (process.env.CURSOR_PROVIDER_DEBUG_FILE) {
@@ -41,6 +46,18 @@ export function ensureSecureDebugLog(filePath, options = {}) {
     fs.writeFileSync(filePath, "", { mode: 0o600 });
     fs.chmodSync(filePath, 0o600);
 }
+function announceLogPath(filePath) {
+    if (_announcedLogPath)
+        return;
+    _announcedLogPath = true;
+    try {
+        // Visible in the OpenCode / terminal session so operators know where to look.
+        console.error(`[cursor-provider] CURSOR_PROVIDER_DEBUG logging to ${filePath}`);
+    }
+    catch {
+        /* ignore */
+    }
+}
 export function trace(msg) {
     if (!DEBUG_ENABLED)
         return;
@@ -53,6 +70,10 @@ export function trace(msg) {
             ensureSecureDebugLog(_debugFile, { secureParent: _debugFileUsesManagedDirectory });
             fs.writeFileSync(_debugFile, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`, { mode: 0o600 });
             _traceInitialized = true;
+            announceLogPath(_debugFile);
+            fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] debug: enabled file=${_debugFile} ` +
+                `xdg_cache_home=${process.env.XDG_CACHE_HOME ?? "(unset)"} ` +
+                `cwd=${process.cwd()}\n`);
         }
         fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${msg}\n`);
     }
@@ -60,3 +81,24 @@ export function trace(msg) {
         /* ignore */
     }
 }
+/**
+ * Compact path-advertising summary for RequestContext troubleshooting.
+ * Safe: no tokens / file contents — only workspace vs metadata roots.
+ */
+export function traceRequestContextPaths(label, requestContext) {
+    if (!DEBUG_ENABLED)
+        return;
+    const env = requestContext?.env && typeof requestContext.env === "object"
+        ? requestContext.env
+        : undefined;
+    const mcp = requestContext?.mcp_file_system_options &&
+        typeof requestContext.mcp_file_system_options === "object"
+        ? requestContext.mcp_file_system_options
+        : undefined;
+    trace(`${label}: workspace_paths=${JSON.stringify(env?.workspace_paths ?? null)} ` +
+        `process_working_directory=${JSON.stringify(env?.process_working_directory ?? null)} ` +
+        `project_folder=${JSON.stringify(env?.project_folder ?? null)} ` +
+        `terminals_folder=${JSON.stringify(env?.terminals_folder ?? null)} ` +
+        `agent_transcripts_folder=${JSON.stringify(env?.agent_transcripts_folder ?? null)} ` +
+        `workspace_project_dir=${JSON.stringify(mcp?.workspace_project_dir ?? null)}`);
+}

package/dist/index.d.ts

@@ -23,6 +23,12 @@ export type CreateCursorOptions = {
     telemetryEnabled?: boolean;
     /** OpenCode project / worktree directory for request_context collectors. */
     workspaceRoot?: string;
+    /**
+     * Host cache root for Cursor project metadata + model/version caches.
+     * Prefer the host's Path.cache (Effect v2) when available; otherwise the
+     * provider resolves OpenCode / MiMo / Kilo XDG cache dirs automatically.
+     */
+    cacheDir?: string;
     /** Held-stream policy. Defaults: heartbeat 5s, semantic idle 120s, tool inactivity 10m. */
     continuation?: CursorContinuationOptions;
     /** Fresh-turn retry policy. Defaults: 3 attempts, 500ms base, 8000ms cap. */

package/dist/language-model.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { bidiRunStream, CursorRunInterruptedError, normalizeAgentRunOrigin, } from "./transport/connect.js";
-import { trace } from "./debug.js";
+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";
@@ -18,7 +18,8 @@ import { resolveContinuationPolicy, sessionManager, } from "./session.js";
 import { CursorAuthError, CursorLocalCancellationError, CursorProtocolError, CursorProviderError, CursorRetryExhaustedError, CursorServerError, CursorTransportError, isTransientGrpcStatus, retrySuppressedError, toCursorProviderError, } from "./errors.js";
 import { readCache, cacheFilePath, resolveVariantParameters, paramsImplyMaxMode, extractCursorVariantParameters, resolveCursorWireModelId } from "./models.js";
 import { buildRequestContext } from "./context/build.js";
-import { opencodeGlobalCacheDir } from "./context/paths.js";
+import { workspaceRootFromRequestContext } from "./context/env.js";
+import { opencodeGlobalCacheDir, setHostCacheDirOverride } from "./context/paths.js";
 import { resolveAgentUrl } from "./agent-url.js";
 import { CURSOR_API_HOST, CURSOR_COMPACTION_OPTION } from "./shared.js";
 import { consumeCursorShellResult, registerCursorShellCall, } from "./shell-timeout.js";
@@ -224,6 +225,9 @@ function rememberPostCompactionRebase(sessionKey) {
     }
 }
 export function createCursorLanguageModel(modelId, providerId, options) {
+    // Host Path.cache / explicit override wins over XDG heuristics for this process.
+    if (options.cacheDir)
+        setHostCacheDirOverride(options.cacheDir);
     return {
         specificationVersion: "v3",
         provider: providerId,
@@ -889,9 +893,9 @@ export async function pump(session, controller, ids, abortSignal) {
         const editPath = typeof display.args.path === "string" ? display.args.path : "";
         if (!requestedPath || !editPath)
             return false;
-        const workspaceRoot = typeof session.requestContext.workspace_project_dir === "string"
-            ? session.requestContext.workspace_project_dir
-            : process.cwd();
+        // Prefer env.workspace_paths — project_folder / workspace_project_dir are
+        // Cursor metadata roots under <host-cache>/projects/, not the git tree.
+        const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
         const resolvePath = (value) => path.resolve(workspaceRoot, value);
         const absolutePath = resolvePath(requestedPath);
         if (absolutePath !== resolvePath(editPath) || fs.existsSync(absolutePath))
@@ -1221,6 +1225,7 @@ export async function pump(session, controller, ids, abortSignal) {
                             trace(`exec request_context hooks_additional_context: ${hooks}`);
                     }
                     try {
+                        traceRequestContextPaths(`exec request_context reply id=${esmId}`, session.requestContext);
                         session.stream.write(buildRequestContextResult(esmId, session.requestContext));
                         trace(`exec request_context: replied`);
                     }

package/dist/plugin-v2.js

@@ -1,6 +1,7 @@
 import { define } from "@opencode-ai/plugin/v2/promise";
 import { CURSOR_PROVIDER_ID } from "./shared.js";
 import { createCursorLanguageModel } from "./language-model.js";
+import { adoptCompatHostCacheDir } from "./context/paths.js";
 /**
  * OpenCode Effect / Promise v2 plugin.
  *
@@ -25,6 +26,9 @@ function createSdk(options) {
 export default define({
     id: "cursor.provider",
     setup: async (ctx) => {
+        // Prefer OCP HostProfile.cacheDir when present; else XDG host heuristic.
+        // Explicit createCursor({ cacheDir }) / event.options.cacheDir still wins via LM.
+        await adoptCompatHostCacheDir();
         await ctx.aisdk.sdk((event) => {
             if (event.sdk)
                 return;

package/dist/plugin.js

@@ -1,10 +1,10 @@
 import { CURSOR_COMPACTION_OPTION, CURSOR_PROVIDER_ID, CURSOR_WEBSITE_HOST, CURSOR_API_HOST } from "./shared.js";
 import { pollForTokens, exchangeApiKey, refreshAccessToken, isExpiringSoon, generatePkceParams, generatePkceChallenge, buildLoginUrl, decodeJwtExpiryMs } from "./auth.js";
 import { CURSOR_VARIANT_PARAMETERS_KEY, CURSOR_WIRE_MODEL_ID_KEY, readCache, discoverModels, isCacheFresh, parseCursorContextLimit } from "./models.js";
-import { opencodeGlobalCacheDir } from "./context/paths.js";
+import { adoptCompatHostCacheDir, opencodeGlobalCacheDir } from "./context/paths.js";
 import { readStoredAuth } from "./context/auth-store.js";
 import { resolveAgentUrl } from "./agent-url.js";
-import { captureCursorShellResult, cursorShellEnvForCall, cursorShellOriginalCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, } from "./shell-timeout.js";
+import { captureCursorShellResult, cursorShellEnvForCall, cursorShellOriginalCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, setCursorShellPath, } from "./shell-timeout.js";
 import { sessionActivity } from "./activity.js";
 const MODULE_URL = new URL("./index.js", import.meta.url).href;
 /**
@@ -194,6 +194,8 @@ function cursorGetServerConfigTelemetryEnabled() {
         process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY === "true");
 }
 export async function CursorPlugin(input) {
+    // Prefer OCP HostProfile.cacheDir when the compat package is present; else XDG heuristic.
+    await adoptCompatHostCacheDir();
     const cacheDir = opencodeGlobalCacheDir();
     const apiBaseURL = cursorApiBaseURL();
     // Last access token successfully resolved in this plugin instance. Config's
@@ -336,9 +338,9 @@ export async function CursorPlugin(input) {
         async "tool.execute.before"(hookInput, output) {
             if (hookInput.tool !== "bash")
                 return;
-            // Keep args.command as the original display/permission command. Wrapping
-            // happens via shell.env (BASH_ENV / ZDOTDIR) so OpenCode's bash UI never
-            // stores or renders the private wrapper script.
+            // bash/zsh retain the original display/permission command and wrap via
+            // shell.env. sh/dash need a short wrapper-file command because their
+            // non-interactive `-c` path ignores BASH_ENV / ZDOTDIR.
             prepareCursorShellArgs(hookInput.callID, output.args);
         },
         async "shell.env"(hookInput, output) {
@@ -377,6 +379,7 @@ export async function CursorPlugin(input) {
             }
         },
         async config(cfg) {
+            setCursorShellPath(cfg.shell);
             cfg.provider ??= {};
             const models = await loadModels();
             const existing = cfg.provider[CURSOR_PROVIDER_ID];
@@ -486,6 +489,7 @@ export async function CursorPlugin(input) {
                 return {
                     ...(accessToken ? { accessToken } : {}),
                     workspaceRoot: input.directory,
+                    cacheDir,
                 };
             },
         },

package/dist/protocol/messages.js

@@ -653,8 +653,10 @@ export function createMessageTypes() {
         { id: 2, name: "workspace_paths", type: "string", repeated: true },
         { id: 3, name: "shell", type: "string" },
         { id: 5, name: "sandbox_enabled", type: "bool" },
+        { id: 7, name: "terminals_folder", type: "string" },
         { id: 10, name: "time_zone", type: "string" },
         { id: 11, name: "project_folder", type: "string" },
+        { id: 12, name: "agent_transcripts_folder", type: "string" },
         { id: 14, name: "sandbox_supported", type: "bool" },
         { id: 20, name: "is_working_dir_home_dir", type: "bool" },
         { id: 21, name: "process_working_directory", type: "string" },

package/dist/protocol/tools.js

@@ -1,9 +1,11 @@
 import fs from "node:fs";
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
-import { trace } from "../debug.js";
+import { buildEnv } from "../context/env.js";
+import { ensureOpencodeProjectDir } from "../context/paths.js";
+import { trace, traceRequestContextPaths } from "../debug.js";
 import { cursorExecVariantByRequestName } from "./exec-variants.js";
-import { BACKGROUND_SHELL_MARKER } from "../shell-timeout.js";
+import { BACKGROUND_SHELL_MARKER, buildBackgroundShellCommand, } from "../shell-timeout.js";
 // Exec variant field number whose reply is the server-initiated request_context
 // probe (ExecServerMessage #10 → ExecClientMessage #10). request/result share a
 // field number for every exec variant, so this is also the result field.
@@ -104,19 +106,12 @@ export function buildLiveRequestContext(tools, providerIdentifier = "opencode",
     const flat = toolsToDescriptors(tools, providerIdentifier, knownMcpServers);
     const nested = toolsToMcpDescriptors(tools, providerIdentifier, knownMcpServers);
     const cwd = process.cwd();
-    return {
-        env: {
-            os_version: process.platform,
-            workspace_paths: [cwd],
-            shell: process.env.SHELL || "/bin/bash",
-            time_zone: "UTC",
-            project_folder: cwd,
-            process_working_directory: cwd,
-        },
+    const ctx = {
+        env: buildEnv(cwd),
         tools: flat,
         mcp_file_system_options: {
             enabled: true,
-            workspace_project_dir: cwd,
+            workspace_project_dir: ensureOpencodeProjectDir(cwd),
             mcp_descriptors: nested,
         },
         mcp_meta_tool_options: {
@@ -129,6 +124,8 @@ export function buildLiveRequestContext(tools, providerIdentifier = "opencode",
         mcp_file_system_info_complete: true,
         git_status_info_complete: true,
     };
+    traceRequestContextPaths("buildLiveRequestContext", ctx);
+    return ctx;
 }
 // ── Cursor exec-variant → opencode tool name ──
 // Native ExecServerMessage variants only (agent.v1). There is no edit_args or
@@ -235,16 +232,17 @@ export function parseExecServerMessage(msg) {
     if (!resultField)
         return undefined;
     const execId = msg.exec_id ?? "";
-    // F11: Cursor native background shell → OpenCode bash. Emit the original
-    // command for UI/storage; the classic plugin before-hook wraps with nohup.
-    // Residual: the child can keep running after this tool call completes.
+    // F11: Cursor native background shell → OpenCode bash. Keep the wrapper
+    // self-contained so direct provider / hosts without shell.env still detach
+    // and return a PID. The classic plugin replaces this with its display-safe
+    // env or wrapper-file path before execution.
     if (execVariant === "background_shell_spawn_args") {
         const raw = msg.background_shell_spawn_args ?? {};
         const command = str(raw.command);
         const workingDirectory = str(raw.working_directory) ?? "";
         const args = {};
         if (command)
-            args.command = command;
+            args.command = buildBackgroundShellCommand(command);
         if (workingDirectory)
             args.workdir = workingDirectory;
         return {
@@ -1112,6 +1110,7 @@ export function detectExecVariantField(agentServerPayload) {
  * Encode exec #10 request_context_result from a prebuilt RequestContext payload.
  */
 export function buildRequestContextResult(execId, requestContext) {
+    traceRequestContextPaths(`buildRequestContextResult id=${execId}`, requestContext);
     return encodeMessage("AgentClientMessage", {
         exec_client_message: {
             id: execId,

package/dist/shell-timeout.d.ts

@@ -27,6 +27,13 @@ export type CursorShellOutcome = {
     msToWait: number;
     reason: 1;
 };
+/** Track OpenCode's configured shell from the classic config hook. */
+export declare function setCursorShellPath(shell: string | undefined): void;
+/**
+ * Mirror the relevant part of OpenCode Shell.acceptable(): fish/nu are denied,
+ * then POSIX falls back to bash when installed and `/bin/sh` otherwise.
+ */
+export declare function resolveCursorShellKind(shell?: string | undefined): "bash" | "zsh" | "sh" | "dash" | "other";
 export declare function shellPolicyFromMetadata(metadata: Record<string, unknown> | undefined): CursorShellPolicy | undefined;
 /** Register a Cursor shell request before OpenCode executes its emitted tool call. */
 export declare function registerCursorShellCall(toolCallId: string, metadata: Record<string, unknown> | undefined): void;
@@ -58,15 +65,13 @@ export declare function buildBackgroundShellCommand(command: string): string;
 /**
  * Prepare OpenCode Bash args before execution when Cursor requested wrapping.
  *
- * Important: do **not** replace `args.command` with the wrapper script.
- * OpenCode's bash UI renders `state.input.command`, and `ctx.metadata()`
- * persists the execute-time `args` object into that field. Mutating
- * `args.command` therefore leaks the private wrapper into the TUI/GUI.
+ * bash/zsh source the shell.env injector, so the original command remains in
+ * OpenCode's permission/UI state. sh/dash ignore those startup variables; for
+ * them, use a short `exec wrapper.sh` command that contains no user payload.
  *
- * Wrapping is applied later via {@link cursorShellEnvForCall} (`shell.env`),
- * which uses BASH_ENV / ZDOTDIR injectors so bash/zsh `-c <original>` is
- * replaced with the wrapper while the stored/displayed command stays original.
- * Permissions also keep analyzing the real user command.
+ * background_shell_spawn may already contain the inline non-plugin fallback.
+ * The classic hook replaces it with the original command (bash/zsh) or the
+ * shorter wrapper-file command (sh/dash), avoiding duplicate execution.
  */
 export declare function prepareCursorShellArgs(toolCallId: string, args: Record<string, unknown>): void;
 /** Restore the model-facing command in OpenCode's completed tool title. */
@@ -74,8 +79,8 @@ export declare function cursorShellOriginalCommand(toolCallId: string): string |
 /** Drop injector temp files for a finished/abandoned Cursor shell call. */
 export declare function releaseCursorShellEnv(toolCallId: string): void;
 /**
- * Env vars for OpenCode's `shell.env` hook so bash/zsh execute the Cursor
- * wrapper while `args.command` (and therefore the bash UI) stay original.
+ * Env vars for OpenCode's shell.env hook. bash/zsh execute the injector; the
+ * same materialized wrapper backs the direct-command sh/dash fallback.
  */
 export declare function cursorShellEnvForCall(toolCallId: string | undefined): Record<string, string> | undefined;
 /**

package/dist/shell-timeout.js

@@ -1,6 +1,6 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, delimiter, join } from "node:path";
 /** Cursor agent.v1 TimeoutBehavior enum values. */
 export const CURSOR_TIMEOUT_CANCEL = 1;
 export const CURSOR_TIMEOUT_BACKGROUND = 2;
@@ -14,9 +14,34 @@ const TIMEOUT_MARKER = "__CURSOR_SHELL_TIMEOUT__";
 export const BACKGROUND_SHELL_MARKER = "__CURSOR_BACKGROUND_SHELL__";
 const policies = new Map();
 const outcomes = new Map();
-/** callIDs that need shell.env injectors (so args.command can stay display-original). */
+/** callIDs that need shell.env injectors or a direct-command fallback. */
 const pendingEnvWraps = new Set();
 const activeEnvWraps = new Map();
+let configuredShell;
+/** Track OpenCode's configured shell from the classic config hook. */
+export function setCursorShellPath(shell) {
+    configuredShell = shell?.trim() || undefined;
+}
+function executableOnPath(name) {
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (dir && existsSync(join(dir, name)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Mirror the relevant part of OpenCode Shell.acceptable(): fish/nu are denied,
+ * then POSIX falls back to bash when installed and `/bin/sh` otherwise.
+ */
+export function resolveCursorShellKind(shell = configuredShell ?? process.env.SHELL) {
+    let name = shell ? basename(shell).toLowerCase().replace(/\.exe$/, "") : "";
+    if (name === "fish" || name === "nu" || !name) {
+        name = executableOnPath("bash") ? "bash" : "sh";
+    }
+    if (name === "bash" || name === "zsh" || name === "sh" || name === "dash")
+        return name;
+    return "other";
+}
 function remember(map, key, value, onEvict) {
     map.delete(key);
     map.set(key, value);
@@ -128,37 +153,12 @@ export function buildBackgroundShellCommand(command) {
         `printf '${BACKGROUND_SHELL_MARKER}%s:%s\\n' "$bg_pid" "$bg_log"`,
     ].join("\n");
 }
-/**
- * Prepare OpenCode Bash args before execution when Cursor requested wrapping.
- *
- * Important: do **not** replace `args.command` with the wrapper script.
- * OpenCode's bash UI renders `state.input.command`, and `ctx.metadata()`
- * persists the execute-time `args` object into that field. Mutating
- * `args.command` therefore leaks the private wrapper into the TUI/GUI.
- *
- * Wrapping is applied later via {@link cursorShellEnvForCall} (`shell.env`),
- * which uses BASH_ENV / ZDOTDIR injectors so bash/zsh `-c <original>` is
- * replaced with the wrapper while the stored/displayed command stays original.
- * Permissions also keep analyzing the real user command.
- */
-export function prepareCursorShellArgs(toolCallId, args) {
-    const policy = policies.get(toolCallId);
-    if (!policy)
-        return;
-    if (policy.backgroundSpawn) {
-        pendingEnvWraps.add(toolCallId);
-        return;
-    }
-    if (policy.timeoutBehavior !== CURSOR_TIMEOUT_BACKGROUND)
-        return;
-    pendingEnvWraps.add(toolCallId);
-    // The wrapper returns just after Cursor's foreground window. OpenCode's own
-    // timeout is only an outer safety net and must not win the race.
-    args.timeout = Math.max(OPENCODE_TIMEOUT_GRACE_MS, policy.timeoutMs + OPENCODE_TIMEOUT_GRACE_MS);
-}
-/** Restore the model-facing command in OpenCode's completed tool title. */
-export function cursorShellOriginalCommand(toolCallId) {
-    return policies.get(toolCallId)?.command || undefined;
+function wrapperBodyForPolicy(policy) {
+    if (policy.backgroundSpawn)
+        return buildBackgroundShellCommand(policy.command);
+    if (policy.timeoutBehavior === CURSOR_TIMEOUT_BACKGROUND)
+        return buildSoftBackgroundCommand(policy);
+    return undefined;
 }
 function writeShellEnvInjector(wrapperBody) {
     const dir = mkdtempSync(join(tmpdir(), "cursor-opencode-wrap-"));
@@ -166,13 +166,8 @@ function writeShellEnvInjector(wrapperBody) {
     const bashEnvPath = join(dir, "bashenv.sh");
     const zshenvPath = join(dir, ".zshenv");
     writeFileSync(wrapperPath, `${wrapperBody}\n`, { mode: 0o700 });
-    // Sourced by non-interactive bash (BASH_ENV) or zsh (.zshenv via ZDOTDIR).
-    // `exec` replaces the host shell so OpenCode's `-c <original>` body never runs.
-    //
-    // Do not gate on a sticky env flag: soft-background children inherit the
-    // wrapper environment, and a leftover CURSOR_OPENCODE_WRAP_ACTIVE=1 would
-    // make later injectors no-op (original `-c` runs unwrapped). Unsetting the
-    // injector vars before `exec` is enough to prevent re-entry.
+    // Sourced by bash (BASH_ENV) or zsh (.zshenv via ZDOTDIR). `exec`
+    // replaces the host shell before OpenCode's `-c <original>` body runs.
     const injector = [
         "unset BASH_ENV ZDOTDIR ENV CURSOR_OPENCODE_WRAP_ACTIVE",
         `exec /bin/sh ${shellQuote(wrapperPath)}`,
@@ -181,6 +176,7 @@ function writeShellEnvInjector(wrapperBody) {
     writeFileSync(bashEnvPath, injector, { mode: 0o600 });
     writeFileSync(zshenvPath, injector, { mode: 0o600 });
     return {
+        wrapperPath,
         env: {
             BASH_ENV: bashEnvPath,
             ZDOTDIR: dir,
@@ -195,6 +191,55 @@ function writeShellEnvInjector(wrapperBody) {
         },
     };
 }
+function ensureShellEnvWrap(toolCallId, policy) {
+    const existing = activeEnvWraps.get(toolCallId);
+    if (existing)
+        return existing;
+    const wrapperBody = wrapperBodyForPolicy(policy);
+    if (!wrapperBody)
+        return undefined;
+    const wrap = writeShellEnvInjector(wrapperBody);
+    remember(activeEnvWraps, toolCallId, wrap, (evicted) => evicted.cleanup());
+    return wrap;
+}
+/**
+ * Prepare OpenCode Bash args before execution when Cursor requested wrapping.
+ *
+ * bash/zsh source the shell.env injector, so the original command remains in
+ * OpenCode's permission/UI state. sh/dash ignore those startup variables; for
+ * them, use a short `exec wrapper.sh` command that contains no user payload.
+ *
+ * background_shell_spawn may already contain the inline non-plugin fallback.
+ * The classic hook replaces it with the original command (bash/zsh) or the
+ * shorter wrapper-file command (sh/dash), avoiding duplicate execution.
+ */
+export function prepareCursorShellArgs(toolCallId, args) {
+    const policy = policies.get(toolCallId);
+    if (!policy)
+        return;
+    if (!policy.backgroundSpawn && policy.timeoutBehavior !== CURSOR_TIMEOUT_BACKGROUND)
+        return;
+    pendingEnvWraps.add(toolCallId);
+    if (!policy.backgroundSpawn) {
+        // The wrapper returns just after Cursor's foreground window. OpenCode's own
+        // timeout is only an outer safety net and must not win the race.
+        args.timeout = Math.max(OPENCODE_TIMEOUT_GRACE_MS, policy.timeoutMs + OPENCODE_TIMEOUT_GRACE_MS);
+    }
+    const shellKind = resolveCursorShellKind();
+    if (process.platform === "win32" || shellKind === "bash" || shellKind === "zsh") {
+        // Native Windows PowerShell/cmd wrapping remains unsupported; do not emit
+        // a POSIX /bin/sh command there. Git Bash still uses the env path above.
+        args.command = policy.command;
+        return;
+    }
+    const wrap = ensureShellEnvWrap(toolCallId, policy);
+    if (wrap)
+        args.command = `exec /bin/sh ${shellQuote(wrap.wrapperPath)}`;
+}
+/** Restore the model-facing command in OpenCode's completed tool title. */
+export function cursorShellOriginalCommand(toolCallId) {
+    return policies.get(toolCallId)?.command || undefined;
+}
 /** Drop injector temp files for a finished/abandoned Cursor shell call. */
 export function releaseCursorShellEnv(toolCallId) {
     pendingEnvWraps.delete(toolCallId);
@@ -205,8 +250,8 @@ export function releaseCursorShellEnv(toolCallId) {
     active.cleanup();
 }
 /**
- * Env vars for OpenCode's `shell.env` hook so bash/zsh execute the Cursor
- * wrapper while `args.command` (and therefore the bash UI) stay original.
+ * Env vars for OpenCode's shell.env hook. bash/zsh execute the injector; the
+ * same materialized wrapper backs the direct-command sh/dash fallback.
  */
 export function cursorShellEnvForCall(toolCallId) {
     if (typeof toolCallId !== "string" || !toolCallId || !pendingEnvWraps.has(toolCallId))
@@ -214,18 +259,9 @@ export function cursorShellEnvForCall(toolCallId) {
     const policy = policies.get(toolCallId);
     if (!policy)
         return undefined;
-    const existing = activeEnvWraps.get(toolCallId);
-    if (existing)
-        return existing.env;
-    const wrapperBody = policy.backgroundSpawn
-        ? buildBackgroundShellCommand(policy.command)
-        : policy.timeoutBehavior === CURSOR_TIMEOUT_BACKGROUND
-            ? buildSoftBackgroundCommand(policy)
-            : undefined;
-    if (!wrapperBody)
+    const wrap = ensureShellEnvWrap(toolCallId, policy);
+    if (!wrap)
         return undefined;
-    const wrap = writeShellEnvInjector(wrapperBody);
-    remember(activeEnvWraps, toolCallId, wrap, (evicted) => evicted.cleanup());
     pendingEnvWraps.delete(toolCallId);
     return wrap.env;
 }
@@ -430,4 +466,5 @@ export function resetCursorShellCalls() {
     pendingEnvWraps.clear();
     policies.clear();
     outcomes.clear();
+    configuredShell = undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -61,7 +61,13 @@
     "protobufjs": "^7.4.0"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": "^1.17.13"
+    "@opencode-ai/plugin": "^1.17.13",
+    "@opencode-compat/profile": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-compat/profile": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.13",
@@ -69,4 +75,4 @@
     "@types/node": "^22.15.3",
     "typescript": "^5.8.3"
   }
-}
+}