cursor-opencode-provider 0.2.4 → 0.2.5

package/README.md

@@ -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.4"`.
+Pin a version if you want: `"cursor-opencode-provider@0.2.5"`.
 
 ### From a local clone
 
@@ -175,7 +175,7 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-
 | `CURSOR_API_BASE_URL` | Override API base for auth, model discovery, and `GetServerConfig` agent URL resolution (default `https://api2.cursor.sh`) |
 | `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 `/tmp/cursor-provider-debug.log`) |
+| `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_DATA_HOME` | When set, OpenCode `auth.json` is read from `$XDG_DATA_HOME/opencode/` instead of `~/.local/share/opencode/` |
 
@@ -219,7 +219,7 @@ OpenCode
 
 ### Injected system guidance
 
-The provider adds OpenCode-specific system guidance to normal tool-capable conversations, including tool availability and canonical workspace-path grounding. Compaction keeps its dedicated prompt unchanged.
+The provider adds OpenCode-specific system guidance to normal tool-capable conversations, including tool availability, canonical workspace-path grounding, and preferring `edit` / `write` over shell-based file mutation when those tools are available. Compaction keeps its dedicated prompt unchanged.
 
 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).
 
@@ -246,7 +246,11 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | 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. |
 | `Unsupported Cursor exec variant …` | The error names the canonical Cursor CLI request field, its expected result field, and this provider's handling classification. `handling=unsupported` is a known Cursor-native capability without a safe OpenCode AI SDK bridge; `unknown request field` indicates new protocol drift; `handling=opencode-tool` or `provider-control` indicates a provider decoder/dispatch regression. Enable the debug log and report the full named error. |
-| Need wire-level logs | Set `CURSOR_PROVIDER_DEBUG=1` (optional `CURSOR_PROVIDER_DEBUG_FILE`, default `/tmp/cursor-provider-debug.log`) and reproduce the issue. |
+| Need wire-level logs | Set `CURSOR_PROVIDER_DEBUG=1` (optional `CURSOR_PROVIDER_DEBUG_FILE`; the default is `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) and reproduce the issue. |
+
+## Security
+
+Project `instructions` may reference absolute or `~/` paths (OpenCode parity). See [SECURITY.md](./SECURITY.md) for the trust model and `OPENCODE_DISABLE_PROJECT_CONFIG`.
 
 ## Known limitations
 
@@ -256,12 +260,12 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 - **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 is bridged through OpenCode's foreground-only `bash` tool by detaching the requested command, redirecting its output to `${TMPDIR:-/tmp}/cursor-opencode-bg.*`, and returning the real PID in Cursor's typed field-16 result. Shell-stream requests also preserve Cursor's foreground timeout, `timeout_behavior`, and `hard_timeout`: cancellation becomes a typed aborted exit, while a soft timeout requested with background behavior becomes a typed background handoff. OpenCode's internal `<shell_metadata>` envelope and the bridge's private markers are stripped before the result reaches the UI. 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.
-- **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. 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-result text 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.
+- **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.
-- **Interrupted Runs rebase once** — a remote EOF, Connect end-stream, trailer error, failed continuation write, or closed pending-tool session is never emitted as a successful `stop`. The provider starts one fresh Cursor conversation seeded from the complete OpenCode prompt (including trailing tool results and the live user request), re-advertises the same tools, and preserves compaction's no-execution behavior. A second interruption is returned as an explicit error. Recovery cannot see tokens already streamed to the UI on the interrupted attempt, so mid-generation recovery may briefly duplicate visible text/reasoning even though the rebase prompt asks the model not to repeat completed work.
+- **Interrupted Runs rebase once** — a remote EOF, Connect end-stream, trailer error, failed continuation write, or closed pending-tool session is never emitted as a successful `stop`. The provider starts one fresh Cursor conversation seeded from the OpenCode prompt, retaining the live user request and trailing tool results as host observations without replaying stale historical tool output, re-advertises the same tools, and preserves compaction's no-execution behavior. A second interruption is returned as an explicit error. Recovery cannot see tokens already streamed to the UI on the interrupted attempt, so mid-generation recovery may briefly duplicate visible text/reasoning even though the rebase prompt asks the model not to repeat completed work.
 - **No fallback models** — if Cursor’s `AvailableModels` API is unreachable and there is no local cache, the provider exposes no models.
 
 ## License
 
-MIT
+MIT

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security notes
+
+This provider mirrors OpenCode’s trust model for project configuration. That has implications for what ends up in Cursor context.
+
+## Project `instructions` can include arbitrary local paths
+
+OpenCode’s `opencode.json` / `opencode.jsonc` `instructions` array may list:
+
+- relative paths / globs (e.g. `.cursor/rules/*.md`)
+- absolute paths
+- home-relative paths (`~/…`)
+- remote URLs (`https://…`; this provider fetches HTTPS only)
+
+OpenCode itself expands `~/`, accepts absolute paths, and injects those file contents into the model prompt for **every** provider. This package does the same discovery when building Cursor `RequestContext.rules`.
+
+So a project config like:
+
+```json
+{
+  "instructions": ["~/.ssh/id_rsa", "/etc/passwd"]
+}
+```
+
+can cause those files to be read and sent to the model provider (OpenCode prompt path and/or this provider’s Cursor `RequestContext`). That is intentional OpenCode parity, not a Cursor-only hole. There is no path allowlist that rejects absolute/`~/` instruction paths (matching OpenCode; OpenCode has not treated this as a defect).
+
+Treat project `opencode.json` as **trusted**. Do not open untrusted repositories with project config enabled if that is unacceptable.
+
+## Mitigation: disable project config
+
+To ignore project-level OpenCode config (including project `instructions` and project `AGENTS.md` / `CLAUDE.md` / `CONTEXT.md` discovery), set:
+
+```bash
+export OPENCODE_DISABLE_PROJECT_CONFIG=1
+```
+
+OpenCode honors this flag when loading config and assembling prompts. This provider honors the same flag when collecting rules for Cursor `RequestContext`, so project `instructions` are not merged and project instruction files are not auto-discovered. Global config under `~/.config/opencode` (and `~/.claude/CLAUDE.md` when applicable) still applies.
+
+Truthy values: `1` or `true` (case-insensitive), same as OpenCode.
+
+## Related hardening in this provider
+
+- Remote `instructions` URLs are **HTTPS-only** (`http://` is skipped). Redirects (including to a local proxy) are intentional and not blocked.

package/dist/auth.d.ts

@@ -15,6 +15,8 @@ export declare class AuthTimeoutError extends Error {
 }
 export declare function isExpiringSoon(jwt: string, thresholdS?: number): boolean;
 export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | null;
+/** JWT `exp` claim as epoch milliseconds, or null if missing/malformed. */
+export declare function decodeJwtExpiryMs(jwt: string): number | null;
 export declare function useAuthToken(token: string): {
     accessToken: string;
 };
@@ -45,4 +47,3 @@ export declare function generatePkceParams(): PkceParams;
 export declare function generatePkceChallenge(verifier: string): Promise<string>;
 export declare function buildLoginUrl(challenge: string, uuid: string, websiteUrl?: string): string;
 export declare function pollForTokens(uuid: string, verifier: string, baseUrl?: string, signal?: AbortSignal, maxAttempts?: number): Promise<TokenPair>;
-export declare function loginWithBrowser(websiteUrl?: string, apiBaseUrl?: string, signal?: AbortSignal): Promise<TokenPair>;

package/dist/auth.js

@@ -32,22 +32,35 @@ export class AuthTimeoutError extends Error {
 }
 // ── Helpers ──
 export function isExpiringSoon(jwt, thresholdS = 300) {
-    try {
-        const payload = JSON.parse(atob(jwt.split(".")[1]));
-        return (payload.exp * 1000 - Date.now()) < thresholdS * 1000;
-    }
-    catch {
+    const payload = decodeJwtPayload(jwt);
+    if (!payload || typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
         return true;
     }
+    return payload.exp * 1000 - Date.now() < thresholdS * 1000;
 }
 export function decodeJwtPayload(jwt) {
     try {
-        return JSON.parse(atob(jwt.split(".")[1]));
+        const segment = jwt.split(".")[1];
+        if (!segment)
+            return null;
+        const json = Buffer.from(segment, "base64url").toString("utf8");
+        const payload = JSON.parse(json);
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            return null;
+        return payload;
     }
     catch {
         return null;
     }
 }
+/** JWT `exp` claim as epoch milliseconds, or null if missing/malformed. */
+export function decodeJwtExpiryMs(jwt) {
+    const payload = decodeJwtPayload(jwt);
+    if (!payload || typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
+        return null;
+    }
+    return payload.exp * 1000;
+}
 function base64url(bytes) {
     return btoa(String.fromCharCode(...bytes))
         .replace(/\+/g, "-")
@@ -191,10 +204,3 @@ export async function pollForTokens(uuid, verifier, baseUrl = API_BASE, signal,
     }
     throw new AuthTimeoutError(`Poll timed out after ${maxAttempts} attempts (~5 min)`);
 }
-// ── Combined login (Mode C, one-shot) ──
-export async function loginWithBrowser(websiteUrl, apiBaseUrl, signal) {
-    const params = generatePkceParams();
-    const challenge = await generatePkceChallenge(params.verifier);
-    const loginUrl = buildLoginUrl(challenge, params.uuid, websiteUrl);
-    return await pollForTokens(params.uuid, params.verifier, apiBaseUrl, signal);
-}

package/dist/context/rules.d.ts

@@ -9,6 +9,10 @@ export type OpencodeJson = {
     plugins?: string[];
     mcp?: Record<string, unknown>;
 };
+/** Same truthy rule as OpenCode's Flag.OPENCODE_DISABLE_PROJECT_CONFIG. */
+export declare function isProjectConfigDisabled(): boolean;
+/** Fetch a remote instruction with one deadline covering headers and body. */
+export declare function fetchRemoteInstruction(url: string, timeoutMs?: number): Promise<string | undefined>;
 export declare function loadMergedConfig(workspaceRoot: string): Promise<OpencodeJson>;
 /**
  * Collect OpenCode instruction files.

package/dist/context/rules.js

@@ -129,8 +129,40 @@ async function expandGlob(pattern, workspaceRoot) {
     await walk(startDir, 0);
     return out;
 }
+/** Same truthy rule as OpenCode's Flag.OPENCODE_DISABLE_PROJECT_CONFIG. */
+export function isProjectConfigDisabled() {
+    const value = process.env.OPENCODE_DISABLE_PROJECT_CONFIG?.toLowerCase();
+    return value === "true" || value === "1";
+}
+/** Fetch a remote instruction with one deadline covering headers and body. */
+export async function fetchRemoteInstruction(url, timeoutMs = 5000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), Math.max(1, timeoutMs));
+    try {
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return undefined;
+        return await res.text();
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        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);
     return {
         ...globalConfig,
@@ -162,33 +194,37 @@ export async function collectRules(workspaceRoot) {
         seen.add(resolved);
         rules.push(rule);
     };
-    for (const name of ["AGENTS.md", "CLAUDE.md", "CONTEXT.md"]) {
-        const hit = await findUp(name, workspaceRoot, worktree);
-        if (hit) {
-            await add(hit);
-            break;
+    // Match OpenCode: OPENCODE_DISABLE_PROJECT_CONFIG skips project AGENTS/CLAUDE/CONTEXT
+    // discovery and project opencode.json (see loadMergedConfig).
+    if (!isProjectConfigDisabled()) {
+        for (const name of ["AGENTS.md", "CLAUDE.md", "CONTEXT.md"]) {
+            const hit = await findUp(name, workspaceRoot, worktree);
+            if (hit) {
+                await add(hit);
+                break;
+            }
         }
     }
     await add(path.join(opencodeGlobalConfigDir(), "AGENTS.md"));
     await add(path.join(homedir(), ".claude", "CLAUDE.md"));
     for (const raw of config.instructions ?? []) {
         if (raw.startsWith("http://") || raw.startsWith("https://")) {
+            // HTTPS-only. Redirects (incl. to a local proxy) are intentional — do not
+            // disable follow-redirects or reject localhost/private/metadata hosts.
+            let remoteUrl;
             try {
-                const ctrl = new AbortController();
-                const t = setTimeout(() => ctrl.abort(), 5000);
-                const res = await fetch(raw, { signal: ctrl.signal });
-                clearTimeout(t);
-                if (!res.ok)
-                    continue;
-                const content = await res.text();
-                if (!content.trim() || seen.has(raw))
-                    continue;
-                seen.add(raw);
-                rules.push({ fullPath: raw, content });
+                remoteUrl = new URL(raw);
             }
             catch {
-                /* ignore */
+                continue;
             }
+            if (remoteUrl.protocol !== "https:")
+                continue;
+            const content = await fetchRemoteInstruction(remoteUrl.href);
+            if (!content?.trim() || seen.has(raw))
+                continue;
+            seen.add(raw);
+            rules.push({ fullPath: raw, content });
             continue;
         }
         const expanded = resolveHomeRelative(raw);

package/dist/debug.d.ts

@@ -1 +1,10 @@
+/** Resolve the debug log path (env override or per-uid tmpdir default). */
+export declare function resolveDebugLogPath(): string;
+/**
+ * Ensure the log directory is 0o700 and create/truncate the log file as 0o600.
+ * Exported for tests; callers normally go through `trace`.
+ */
+export declare function ensureSecureDebugLog(filePath: string, options?: {
+    secureParent?: boolean;
+}): void;
 export declare function trace(msg: string): void;

package/dist/debug.js

@@ -1,20 +1,60 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 // Wire-level diagnostics. Opt in with CURSOR_PROVIDER_DEBUG=1 (or "true").
-// Writes to CURSOR_PROVIDER_DEBUG_FILE (default /tmp/cursor-provider-debug.log).
+// Default path mirrors Cursor CLI: $TMPDIR/cursor-provider-logs-<uid>/debug-<pid>.log
+// with directory mode 0o700 and file mode 0o600. Override with CURSOR_PROVIDER_DEBUG_FILE.
 // Truncated once per process. Tokens / checksums should be redacted by callers.
 const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
     process.env.CURSOR_PROVIDER_DEBUG === "true";
-const DEBUG_FILE = process.env.CURSOR_PROVIDER_DEBUG_FILE || "/tmp/cursor-provider-debug.log";
 let _traceInitialized = false;
+let _debugFile;
+let _debugFileUsesManagedDirectory = false;
+/** Resolve the debug log path (env override or per-uid tmpdir default). */
+export function resolveDebugLogPath() {
+    if (process.env.CURSOR_PROVIDER_DEBUG_FILE) {
+        return process.env.CURSOR_PROVIDER_DEBUG_FILE;
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : process.pid;
+    return path.join(os.tmpdir(), `cursor-provider-logs-${uid}`, `debug-${process.pid}.log`);
+}
+/**
+ * Ensure the log directory is 0o700 and create/truncate the log file as 0o600.
+ * Exported for tests; callers normally go through `trace`.
+ */
+export function ensureSecureDebugLog(filePath, options = {}) {
+    const dir = path.dirname(filePath);
+    const secureParent = options.secureParent ?? true;
+    fs.mkdirSync(dir, secureParent
+        ? { recursive: true, mode: 0o700 }
+        : { recursive: true });
+    if (secureParent) {
+        const stat = fs.lstatSync(dir);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`Debug log directory is not a real directory: ${dir}`);
+        }
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+            throw new Error(`Debug log directory is not owned by the current user: ${dir}`);
+        }
+        fs.chmodSync(dir, 0o700);
+    }
+    fs.writeFileSync(filePath, "", { mode: 0o600 });
+    fs.chmodSync(filePath, 0o600);
+}
 export function trace(msg) {
     if (!DEBUG_ENABLED)
         return;
     try {
+        if (!_debugFile) {
+            _debugFileUsesManagedDirectory = !process.env.CURSOR_PROVIDER_DEBUG_FILE;
+            _debugFile = resolveDebugLogPath();
+        }
         if (!_traceInitialized) {
+            ensureSecureDebugLog(_debugFile, { secureParent: _debugFileUsesManagedDirectory });
+            fs.writeFileSync(_debugFile, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`, { mode: 0o600 });
             _traceInitialized = true;
-            fs.writeFileSync(DEBUG_FILE, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`);
         }
-        fs.appendFileSync(DEBUG_FILE, `[${new Date().toISOString()}] ${msg}\n`);
+        fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${msg}\n`);
     }
     catch {
         /* ignore */

package/dist/language-model.d.ts

@@ -87,12 +87,16 @@ export declare function cursorTurnEndedProviderMetadata(te: Record<string, unkno
     };
 };
 /**
- * Prior prompt turns for a seed ConversationStateStructure after compaction
- * reset. Drops the trailing user message (live action), but preserves tool
- * result payloads as labeled assistant observations for Cursor's text history.
+ * Prior prompt turns for a seed ConversationStateStructure. Tool results must
+ * never be replayed as assistant-authored prose: that teaches the model to
+ * counterfeit `Tool result (...)` text instead of emitting a real tool call.
+ * Normal rebases omit old results; compaction can retain all results and
+ * interrupted continuations retain only the trailing live result suffix as
+ * explicit OpenCode-host observations.
  */
 export declare function extractPromptHistory(prompt: LanguageModelV3CallOptions["prompt"], options?: {
     preserveTrailingUser?: boolean;
+    toolResults?: "omit" | "all" | "trailing";
 }): SeedHistoryMessage[];
 /** OpenCode session id header, if present. */
 export declare function opencodeSessionKey(callOptions: LanguageModelV3CallOptions): string | undefined;

package/dist/language-model.js

@@ -439,7 +439,10 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const systemPrompt = interactionGuidance
         ? [baseSystemPrompt, interactionGuidance].filter(Boolean).join("\n\n")
         : baseSystemPrompt;
-    const history = extractPromptHistory(prompt, { preserveTrailingUser: recovery });
+    const history = extractPromptHistory(prompt, {
+        preserveTrailingUser: recovery,
+        toolResults: isCompaction ? "all" : (recovery ? "trailing" : "omit"),
+    });
     await loadAvailableModels();
     // Resolve the region-specific Run stream origin once per process (memoized
     // in agent-url.ts). Explicit agent host overrides skip GetServerConfig but
@@ -847,6 +850,56 @@ export async function pump(session, controller, ids, abortSignal) {
             return false;
         }
     };
+    /**
+     * Cursor's streamed edit handshake reads the target before it sends the
+     * replacement through write_args. For a new file that read naturally fails,
+     * which makes the model abandon the edit and fall back to a shell heredoc.
+     * Treat only a missing target correlated to an edit_tool_call as an empty
+     * file, allowing Cursor to continue to the ordinary OpenCode write call.
+     */
+    const recoverMissingEditRead = (parsed, displayCallId) => {
+        if (!displayCallId ||
+            parsed.resultField !== "read_result" ||
+            parsed.toolName !== "read" ||
+            !advertisedToolNameSet.has("write"))
+            return false;
+        const stored = session.displayToolCalls.get(displayCallId);
+        const display = parseDisplayToolCall(displayCallId, stored);
+        if (display?.variant !== "edit_tool_call" || display.bridgeable === false)
+            return false;
+        const requestedPath = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
+        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();
+        const resolvePath = (value) => path.resolve(workspaceRoot, value);
+        const absolutePath = resolvePath(requestedPath);
+        if (absolutePath !== resolvePath(editPath) || fs.existsSync(absolutePath))
+            return false;
+        try {
+            for (const frame of buildExecClientMessages({
+                execId: parsed.id,
+                resultField: parsed.resultField,
+                output: "",
+                toolName: parsed.toolName,
+                resultMetadata: { path: requestedPath },
+            })) {
+                session.stream.write(frame);
+            }
+            trace(`exec: missing edit target treated as empty file id=${parsed.id} ` +
+                `path=${JSON.stringify(requestedPath)}; awaiting write_args`);
+            return true;
+        }
+        catch (e) {
+            const error = new Error(`Failed to recover Cursor edit read for a new file: ${e.message}`);
+            trace(`exec: edit read recovery 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 })) {
@@ -1153,7 +1206,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         trace(`exec request_context: replied`);
                     }
                     catch (e) {
-                        trace(`exec request_context: write FAILED ${e.message}`);
+                        const error = new Error(`Failed to answer Cursor request_context probe: ${e.message}`);
+                        trace(`exec request_context: write FAILED ${error.message}`);
+                        safeError(error);
+                        sessionManager.close(session);
+                        return;
                     }
                 }
                 else if (esm.mcp_state_exec_args) {
@@ -1179,10 +1236,6 @@ export async function pump(session, controller, ids, abortSignal) {
                 else {
                     const parsed = parseExecServerMessage(esm);
                     const displayCallId = extractExecDisplayCallId(esm);
-                    if (displayCallId) {
-                        session.displayToolCalls.delete(displayCallId);
-                        trace(`exec: claimed display callId=${displayCallId}`);
-                    }
                     trace(`exec: id=${parsed?.id} variant=${parsed ? Object.keys(parsed).join(",") : "none"} toolName=${parsed?.toolName} resultField=${parsed?.resultField}`);
                     if (parsed) {
                         if (parsed.localError) {
@@ -1219,6 +1272,12 @@ export async function pump(session, controller, ids, abortSignal) {
                                 return;
                             continue;
                         }
+                        if (recoverMissingEditRead(parsed, displayCallId))
+                            continue;
+                        if (displayCallId) {
+                            session.displayToolCalls.delete(displayCallId);
+                            trace(`exec: claimed display callId=${displayCallId}`);
+                        }
                         const tc = buildToolCallPart(parsed, session.sessionId);
                         if (parsed.resultField === "shell_stream") {
                             registerCursorShellCall(tc.toolCallId, parsed.resultMetadata);
@@ -1257,7 +1316,8 @@ export async function pump(session, controller, ids, abortSignal) {
             else if (interactionQuery) {
                 // InteractionQuery is a must-reply channel, just like exec and KV. AI
                 // SDK has no Cursor-specific UI callback, so answer immediately with the
-                // conservative headless policy from protocol/interactions.ts.
+                // conservative headless policy from protocol/interactions.ts (including
+                // F14 create_plan auto-ack / empty plan_uri for CLI headless parity).
                 try {
                     const handled = handleInteractionQuery(interactionQuery, payload);
                     session.stream.write(handled.reply);
@@ -1290,7 +1350,13 @@ export async function pump(session, controller, ids, abortSignal) {
                             `found=${handled.found} echoed=${!!handled.echoed} ` +
                             `sessionBlobs=${session.blobs.size} convBlobs=${conversationBlobCount(session.conversationId)}`);
                     }
-                    catch { /* stream closed; pump will surface end */ }
+                    catch (e) {
+                        const error = new Error(`Failed to answer Cursor KV blob request: ${e.message}`);
+                        trace(`kv: write FAILED ${error.message}`);
+                        safeError(error);
+                        sessionManager.close(session);
+                        return;
+                    }
                 }
             }
         }
@@ -1423,6 +1489,11 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.has("webfetch")) {
         instructions.push("- To fetch a known URL, call the OpenCode `webfetch` tool; do not use Cursor's native WebFetch interaction.");
     }
+    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."
+            : "- Use OpenCode `write` for file-content changes; do not use shell, Python, or heredocs to change file content while it is available.");
+    }
     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.`,
@@ -1469,13 +1540,24 @@ export function cursorTurnEndedProviderMetadata(te) {
     };
 }
 /**
- * Prior prompt turns for a seed ConversationStateStructure after compaction
- * reset. Drops the trailing user message (live action), but preserves tool
- * result payloads as labeled assistant observations for Cursor's text history.
+ * Prior prompt turns for a seed ConversationStateStructure. Tool results must
+ * never be replayed as assistant-authored prose: that teaches the model to
+ * counterfeit `Tool result (...)` text instead of emitting a real tool call.
+ * Normal rebases omit old results; compaction can retain all results and
+ * interrupted continuations retain only the trailing live result suffix as
+ * explicit OpenCode-host observations.
  */
 export function extractPromptHistory(prompt, options) {
     const out = [];
-    for (const m of prompt) {
+    const toolResults = options?.toolResults ?? "omit";
+    let trailingToolStart = prompt.length;
+    if (toolResults === "trailing") {
+        while (trailingToolStart > 0 && prompt[trailingToolStart - 1]?.role === "tool") {
+            trailingToolStart--;
+        }
+    }
+    for (let messageIndex = 0; messageIndex < prompt.length; messageIndex++) {
+        const m = prompt[messageIndex];
         if (m.role === "system") {
             if (typeof m.content === "string" && m.content.length > 0) {
                 out.push({ role: "system", content: m.content });
@@ -1495,18 +1577,26 @@ export function extractPromptHistory(prompt, options) {
             continue;
         }
         if (m.role === "tool" && Array.isArray(m.content)) {
+            if (toolResults === "omit" ||
+                (toolResults === "trailing" && messageIndex < trailingToolStart))
+                continue;
             const results = [];
             for (const part of m.content) {
                 const p = part;
                 if (p.type !== "tool-result")
                     continue;
                 const toolName = typeof p.toolName === "string" && p.toolName ? p.toolName : "tool";
+                const toolCallId = typeof p.toolCallId === "string" ? p.toolCallId : "";
                 const result = toolResultOutputToText(p.output);
-                const label = result.isError ? "Tool error" : "Tool result";
-                results.push(`${label} (${toolName}):\n${result.text}`);
+                results.push(formatSeedToolObservation({
+                    toolName,
+                    toolCallId,
+                    output: result.text,
+                    isError: result.isError,
+                }));
             }
             if (results.length > 0)
-                appendSeedHistory(out, "assistant", results.join("\n\n"));
+                appendSeedHistory(out, "user", results.join("\n\n"));
         }
     }
     // Live user message is the Run action, not seed history.
@@ -1515,6 +1605,15 @@ export function extractPromptHistory(prompt, options) {
     }
     return out;
 }
+function formatSeedToolObservation(input) {
+    const metadata = JSON.stringify({
+        source: "opencode-tool",
+        tool: input.toolName,
+        callId: input.toolCallId,
+        status: input.isError ? "error" : "completed",
+    });
+    return `OpenCode host observation ${metadata}:\n${input.output}`;
+}
 function extractAssistantHistoryText(msg) {
     const content = msg.content;
     if (typeof content === "string")

package/dist/plugin.js

@@ -1,5 +1,5 @@
 import { CURSOR_COMPACTION_OPTION, CURSOR_PROVIDER_ID, CURSOR_WEBSITE_HOST, CURSOR_API_HOST } from "./shared.js";
-import { pollForTokens, exchangeApiKey, refreshAccessToken, isExpiringSoon, generatePkceParams, generatePkceChallenge, buildLoginUrl, decodeJwtPayload } from "./auth.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 { readStoredAuth } from "./context/auth-store.js";
@@ -275,7 +275,7 @@ export async function CursorPlugin(input) {
                     type: "oauth",
                     access: newTokens.accessToken,
                     refresh: newTokens.refreshToken,
-                    expires: decodeExpFromJwt(newTokens.accessToken),
+                    expires: decodeJwtExpiryMs(newTokens.accessToken) ?? Date.now(),
                     ...(extras.accountId !== undefined ? { accountId: extras.accountId } : {}),
                     ...(extras.enterpriseUrl !== undefined ? { enterpriseUrl: extras.enterpriseUrl } : {}),
                 });
@@ -397,7 +397,7 @@ export async function CursorPlugin(input) {
                                     provider: CURSOR_PROVIDER_ID,
                                     access: result.accessToken,
                                     refresh: result.refreshToken,
-                                    expires: decodeExpFromJwt(result.accessToken),
+                                    expires: decodeJwtExpiryMs(result.accessToken) ?? Date.now(),
                                 };
                             },
                         };
@@ -469,9 +469,3 @@ export async function CursorPlugin(input) {
         },
     };
 }
-function decodeExpFromJwt(jwt) {
-    const payload = decodeJwtPayload(jwt);
-    if (payload && typeof payload.exp === "number")
-        return payload.exp * 1000;
-    return Date.now() + 3600_000;
-}

package/dist/protocol/interactions.d.ts

@@ -19,5 +19,12 @@ export declare class UnsupportedInteractionQueryError extends Error {
  * instead of accidentally restoring the heartbeat-only deadlock.
  */
 export declare function inspectInteractionQueryWire(agentServerPayload: Uint8Array): InteractionQueryWireInfo;
-/** Build the immediate typed response required by Cursor's Run RPC. */
+/**
+ * Build the immediate typed response required by Cursor's Run RPC.
+ *
+ * OpenCode has no Cursor UI callbacks, so every InteractionQuery is answered
+ * here with a conservative headless policy (reject UI-bound prompts; ack a few
+ * no-UI cases). See case 7 / F14 for create_plan auto-ack parity with Cursor
+ * CLI headless mode.
+ */
 export declare function handleInteractionQuery(query: Record<string, unknown>, agentServerPayload: Uint8Array): HandledInteraction;

package/dist/protocol/interactions.js

@@ -51,7 +51,14 @@ export function inspectInteractionQueryWire(agentServerPayload) {
         variantName: variantField === undefined ? undefined : variantNames[variantField],
     };
 }
-/** Build the immediate typed response required by Cursor's Run RPC. */
+/**
+ * Build the immediate typed response required by Cursor's Run RPC.
+ *
+ * OpenCode has no Cursor UI callbacks, so every InteractionQuery is answered
+ * here with a conservative headless policy (reject UI-bound prompts; ack a few
+ * no-UI cases). See case 7 / F14 for create_plan auto-ack parity with Cursor
+ * CLI headless mode.
+ */
 export function handleInteractionQuery(query, agentServerPayload) {
     const info = inspectInteractionQueryWire(agentServerPayload);
     if (info.id === undefined || info.variantField === undefined || !info.variantName) {
@@ -80,8 +87,14 @@ export function handleInteractionQuery(query, agentServerPayload) {
             outcome = "rejected";
             break;
         case 7:
+            // F14: create_plan_request_query auto-ack (Cursor CLI headless parity).
             // Cursor CLI's headless fallback acknowledges plan creation without a
-            // client-side URI; the plan remains in conversation state/checkpoints.
+            // client-side URI (`success` + empty `plan_uri`); the plan remains in
+            // conversation state / checkpoints. This provider mirrors that reply so
+            // the Run RPC does not deadlock waiting for UI approval. Impact: Cursor
+            // may treat the plan as accepted without an OpenCode UI confirm; local
+            // tool execution is still gated by OpenCode permissions. Do not change
+            // this to reject/prompt without CLI parity evidence.
             response = { create_plan_request_response: { result: { success: {}, plan_uri: "" } } };
             outcome = "acknowledged";
             break;

package/dist/protocol/messages.js

@@ -357,8 +357,11 @@ export function createMessageTypes() {
         { id: 2, name: "content", type: "string" },
         { id: 3, name: "total_lines", type: "int32" },
         { id: 4, name: "file_size", type: "int64" },
+        { id: 5, name: "data", type: "bytes" },
         { id: 6, name: "truncated", type: "bool" },
-    ]);
+        { id: 7, name: "output_blob_id", type: "bytes" },
+        { id: 8, name: "range_applied", type: "bool" },
+    ], [{ name: "output", fields: ["content", "data"] }]);
     addType(root, "ReadError", [
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "error", type: "string" },

package/dist/protocol/request.d.ts

@@ -10,8 +10,8 @@ export type RunRequestInput = {
     systemPrompt?: string;
     /**
      * Prior chat turns for a seed ConversationStateStructure (no checkpoint).
-     * Used after compaction reset so Cursor sees OpenCode's compacted history
-     * instead of an empty conversation.
+     * Tool outputs, when required for compaction/recovery, are represented as
+     * user-role OpenCode host observations rather than assistant-authored prose.
      */
     history?: SeedHistoryMessage[];
     /**

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

@@ -7,7 +7,12 @@ const TODO_STATUS = {
     3: "completed",
     4: "cancelled",
 };
-/** Cursor ToolCall oneof field → default OpenCode tool id. */
+/**
+ * Cursor ToolCall oneof field → default OpenCode tool id.
+ *
+ * F11: `delete_tool_call` has no OpenCode builtin; it remaps to bash (see the
+ * delete_tool_call branch below for `rm -f -- <path>`).
+ */
 const VARIANT_TO_OPENCODE = {
     shell_tool_call: "bash",
     delete_tool_call: "bash",
@@ -121,6 +126,10 @@ export function parseDisplayToolCall(callId, toolCall) {
             args: mcpArgs,
         };
     }
+    // create_plan_tool_call here is display-state mirroring into todowrite.
+    // Separately, InteractionQuery create_plan_request_query is auto-acked in
+    // protocol/interactions.ts (F14 / CLI headless parity) — that ack is not an
+    // execution of this display payload.
     if (variant === "update_todos_tool_call" || variant === "create_plan_tool_call") {
         const result = asRecord(payload.result);
         const success = asRecord(result?.success);
@@ -238,6 +247,7 @@ export function parseDisplayToolCall(callId, toolCall) {
             args: {},
         };
     }
+    // F11: display-path delete → bash `rm -f` (OpenCode has no delete tool).
     if (variant === "delete_tool_call") {
         const path = typeof args.path === "string" ? args.path : "";
         return {

package/dist/protocol/tools.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
 import { trace } from "../debug.js";
@@ -133,8 +134,13 @@ export function buildLiveRequestContext(tools, providerIdentifier = "opencode",
 // glob_args on the exec channel — Cursor's EditToolCall is display-only, and
 // glob/edit from opencode are advertised as MCP tools and arrive as mcp_args.
 //
-// OpenCode has no `ls` / `delete` builtins: ls → read (dirs are readable),
-// delete → bash `rm`. Arg key remapping happens in mapCursorArgsToOpencode.
+// Design note (F11): Cursor has native delete / background-shell tools; OpenCode
+// does not. This provider intentionally remaps:
+//   - delete_args → bash `rm -f -- <quoted-path>`
+//   - background_shell_spawn_args → bash + nohup detach wrapper
+// Permissions still flow through OpenCode's advertised `bash` tool. Soft-
+// background / detached children can outlive the OpenCode tool call; leftover
+// process cleanup is left to the user / OS. Arg key remapping happens below.
 const cursorToolToOpencode = {
     read_args: "read",
     write_args: "write",
@@ -229,6 +235,9 @@ export function parseExecServerMessage(msg) {
     if (!resultField)
         return undefined;
     const execId = msg.exec_id ?? "";
+    // F11: Cursor native background shell → OpenCode bash. The wrapper detaches
+    // via nohup immediately; OpenCode only sees the spawn marker (pid + log path).
+    // Residual: the child can keep running after this tool call completes.
     if (execVariant === "background_shell_spawn_args") {
         const raw = msg.background_shell_spawn_args ?? {};
         const command = str(raw.command);
@@ -328,9 +337,16 @@ export function parseExecServerMessage(msg) {
     if (!toolName)
         return undefined;
     const mapped = mapCursorArgsToOpencode(toolName, msg[execVariant] ?? {}, execVariant);
+    const rawArgs = msg[execVariant] ?? {};
     const resultMetadata = execVariant === "shell_stream_args"
-        ? shellStreamResultMetadata(msg[execVariant] ?? {})
-        : undefined;
+        ? shellStreamResultMetadata(rawArgs)
+        : execVariant === "read_args"
+            ? {
+                path: str(rawArgs.path) ?? str(rawArgs.file_path) ?? "",
+                ...(typeof mapped.args.offset === "number" ? { offset: mapped.args.offset } : {}),
+                ...(typeof mapped.args.limit === "number" ? { limit: mapped.args.limit } : {}),
+            }
+            : undefined;
     if (resultMetadata
         && resultMetadata.timeout_behavior !== 2
         && typeof resultMetadata.timeout_ms === "number") {
@@ -390,7 +406,9 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant) {
         const filePath = str(cleaned.path) ?? str(cleaned.filePath);
         return { toolName: "read", args: filePath ? { filePath } : {} };
     }
-    // Native delete_args → bash rm (OpenCode has no delete builtin).
+    // F11: Cursor native delete_args → OpenCode bash. No delete builtin exists, so
+    // we emulate with `rm -f -- <path>` (shell-quoted). Same permission boundary
+    // as any other bash tool call.
     if (execVariant === "delete_args") {
         const target = str(cleaned.path) ?? str(cleaned.filePath);
         return {
@@ -523,10 +541,15 @@ function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 /**
+ * F11 / background_shell_spawn_args helper.
+ *
  * OpenCode's bash tool is foreground-only. Detach the requested command inside
- * that one foreground call and print a private marker containing the spawned
- * PID and log path. With stdin and all output redirected, the host shell can
- * return immediately instead of retaining OpenCode's tool pipe.
+ * that one foreground call (`nohup … &`) and print a private marker containing
+ * the spawned PID and log path. With stdin and all output redirected, the host
+ * shell can return immediately instead of retaining OpenCode's tool pipe.
+ *
+ * Residual: the detached child is not reaped by this provider after OpenCode
+ * completes the tool call; cleanup is left to the user / OS.
  */
 function buildBackgroundShellCommand(command) {
     return [
@@ -735,20 +758,29 @@ export function unwrapReadOutput(output) {
  */
 export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata) {
     switch (resultField) {
-        case "read_result":
+        case "read_result": {
+            const readPath = str(resultMetadata?.path) ?? extractPathTag(output) ?? "";
             if (error)
-                return { error: { path: "", error } };
+                return { error: { path: readPath, error } };
             // Strip opencode's <path>/<content> envelope so Cursor's model receives
             // raw file content and can't echo the wrapper into subsequent writes.
             // reads route here only for native read_args; most arrive via mcp_result.
             const content = unwrapReadOutput(output);
+            const statPath = extractPathTag(output) ?? readPath;
+            const outputMetadata = parseOpenCodeReadMetadata(output);
+            const totalLines = outputMetadata.totalLines ?? readFileLineCount(statPath) ?? countLines(content);
+            const rangeApplied = readRangeApplied(resultMetadata, totalLines);
             return {
                 success: {
-                    path: extractPathTag(output) ?? "",
+                    path: readPath,
                     content,
-                    total_lines: countLines(content),
+                    total_lines: totalLines,
+                    file_size: readFileSize(statPath),
+                    truncated: readOutputTruncated(resultMetadata, outputMetadata, totalLines),
+                    range_applied: rangeApplied,
                 },
             };
+        }
         case "grep_result": {
             if (error)
                 return { error: { error } };
@@ -913,6 +945,93 @@ function extractPathTag(output) {
     const m = output.match(/<path>([^<]+)<\/path>/);
     return m?.[1];
 }
+/** Recover full-file metadata before unwrapReadOutput removes OpenCode's footer. */
+function parseOpenCodeReadMetadata(output) {
+    const showing = /Showing lines (\d+)-(\d+)(?: of (\d+))?\./.exec(output);
+    if (showing) {
+        return {
+            startLine: Number(showing[1]),
+            endLine: Number(showing[2]),
+            ...(showing[3] ? { totalLines: Number(showing[3]) } : {}),
+            outputCapped: output.includes("(Output capped at "),
+        };
+    }
+    const complete = /\(End of file - total (\d+) lines?\)/.exec(output);
+    if (complete)
+        return { totalLines: Number(complete[1]) };
+    return {};
+}
+function readRangeApplied(resultMetadata, totalLines) {
+    const offset = num(resultMetadata?.offset);
+    const limit = num(resultMetadata?.limit);
+    if (offset === undefined && limit === undefined)
+        return false;
+    if (totalLines === 0)
+        return false;
+    const startLine = offset ?? 1;
+    return startLine < 0 || startLine <= totalLines;
+}
+function readOutputTruncated(resultMetadata, outputMetadata, totalLines) {
+    if (outputMetadata.outputCapped)
+        return true;
+    const returnedEnd = outputMetadata.endLine;
+    if (returnedEnd === undefined || totalLines === 0)
+        return false;
+    const offset = num(resultMetadata?.offset);
+    const limit = num(resultMetadata?.limit);
+    const startLine = offset ?? 1;
+    if (startLine < 0)
+        return false;
+    const expectedEnd = limit === undefined
+        ? totalLines
+        : Math.min(totalLines, Math.max(1, startLine) + limit - 1);
+    return returnedEnd < expectedEnd;
+}
+function readFileSize(filePath) {
+    if (!filePath)
+        return 0;
+    try {
+        return fs.statSync(filePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function readFileLineCount(filePath) {
+    if (!filePath)
+        return undefined;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let totalBytes = 0;
+        let lines = 1;
+        while (true) {
+            const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            totalBytes += bytesRead;
+            for (let index = 0; index < bytesRead; index++) {
+                if (buffer[index] === 0x0a)
+                    lines++;
+            }
+        }
+        return totalBytes === 0 ? 0 : lines;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+}
 function extractPathLines(output) {
     const lines = output.split("\n").map((l) => l.trim()).filter(Boolean);
     // Prefer absolute / relative path-looking lines; fall back to all non-empty.

package/dist/shell-timeout.d.ts

@@ -27,9 +27,16 @@ export declare function shellPolicyFromMetadata(metadata: Record<string, unknown
 /** Register a Cursor shell request before OpenCode executes its emitted tool call. */
 export declare function registerCursorShellCall(toolCallId: string, metadata: Record<string, unknown> | undefined): void;
 /**
+ * F11 / soft-background helper.
+ *
  * Run a Cursor soft-background command for its foreground window, then leave
- * it detached if still alive. The sentinel is removed by the after hook before
- * OpenCode stores/renders the result.
+ * it detached (`nohup`) if still alive. The sentinel is removed by the after
+ * hook before OpenCode stores/renders the result.
+ *
+ * This approximates Cursor's TIMEOUT_BACKGROUND semantics through OpenCode's
+ * foreground-only bash tool. Residual: after OpenCode returns, the child (and
+ * optional hard-timeout watchdog) may still be running; this provider does not
+ * reap leftover processes — cleanup is left to the user / OS.
  */
 export declare function buildSoftBackgroundCommand(policy: CursorShellPolicy): string;
 /** Mutate OpenCode Bash args before execution when Cursor requested soft backgrounding. */

package/dist/shell-timeout.js

@@ -50,9 +50,16 @@ function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 /**
+ * F11 / soft-background helper.
+ *
  * Run a Cursor soft-background command for its foreground window, then leave
- * it detached if still alive. The sentinel is removed by the after hook before
- * OpenCode stores/renders the result.
+ * it detached (`nohup`) if still alive. The sentinel is removed by the after
+ * hook before OpenCode stores/renders the result.
+ *
+ * This approximates Cursor's TIMEOUT_BACKGROUND semantics through OpenCode's
+ * foreground-only bash tool. Residual: after OpenCode returns, the child (and
+ * optional hard-timeout watchdog) may still be running; this provider does not
+ * reap leftover processes — cleanup is left to the user / OS.
  */
 export function buildSoftBackgroundCommand(policy) {
     const polls = Math.ceil(policy.timeoutMs / POLL_INTERVAL_MS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,7 @@
     "dist",
     "LICENSE",
     "DISCLAIMER.md",
+    "SECURITY.md",
     "README.md"
   ],
   "scripts": {
@@ -68,4 +69,4 @@
     "@types/node": "^22.15.3",
     "typescript": "^5.8.3"
   }
-}
+}