cursor-opencode-provider 0.2.5 → 0.2.7

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,
@@ -288,7 +292,7 @@ async function doStreamImpl(modelId, options, callOptions) {
             // Cursor can continue instead of deadlocking.
             const ids = trailingToolResults.map((r) => `${r.sessionId}:${r.execId}`).join(",");
             trace(`continuation: ${trailingToolResults.length} interrupted trailing tool result(s) [${ids}] — rebasing fresh Run`);
-            session = await openSession({ recovery: true });
+            session = await openSession({ recovery: { kind: "rebase" } });
         }
         else {
             // Fresh turn (prompt ends with user/assistant text). Historical tool
@@ -323,7 +327,7 @@ async function doStreamImpl(modelId, options, callOptions) {
                         abortSignal: callOptions.abortSignal,
                         promptTokens,
                         retryPolicy,
-                        recover: () => openSession({ recovery: true }),
+                        recover: (recovery) => openSession({ recovery }),
                         onSession: (next) => { activeSession = next; },
                     });
                     try {
@@ -361,6 +365,7 @@ export async function pumpWithRecovery(input) {
         maxAttempts: (input.maxRecoveries ?? 1) + 1,
     };
     const maxRecoveries = retryPolicy.maxAttempts - 1;
+    const requestUsage = { outputChars: 0 };
     input.onSession?.(session);
     for (let attempt = 0;; attempt++) {
         const pumpedSession = session;
@@ -371,6 +376,7 @@ export async function pumpWithRecovery(input) {
                 textId: crypto.randomUUID(),
                 reasoningId: crypto.randomUUID(),
                 promptTokens: input.promptTokens ?? 0,
+                requestUsage,
             }, input.abortSignal);
             return session;
         }
@@ -381,19 +387,26 @@ export async function pumpWithRecovery(input) {
             });
             if (!failure.transient)
                 throw failure;
-            if (!failure.replaySafe) {
+            const checkpoint = pumpedSession.resumeCheckpoint;
+            if (!failure.replaySafe && !checkpoint) {
                 throw retrySuppressedError(failure, "after visible output or stateful server activity", attempt + 1, maxRecoveries + 1);
             }
             if (attempt >= maxRecoveries) {
                 throw new CursorRetryExhaustedError(attempt + 1, failure);
             }
             trace(`Run interrupted: sessionId=${pumpedSession.sessionId} attempt=${attempt + 1}/${maxRecoveries} ` +
-                `err=${failure.message} — rebasing fresh Run`);
+                `err=${failure.message} — ${checkpoint ? `resuming ${checkpoint.length}B checkpoint` : "rebasing fresh Run"}`);
             sessionManager.close(pumpedSession, "remote-error", failure);
             const delayMs = retryDelayMs(failure, attempt + 1, retryPolicy);
             trace(`Run retry backoff: attempt=${attempt + 1}/${maxRecoveries} delayMs=${delayMs}`);
             await sleepForRetry(delayMs, input.abortSignal);
-            session = await input.recover();
+            session = await input.recover(checkpoint
+                ? {
+                    kind: "resume",
+                    conversationId: pumpedSession.conversationId,
+                    checkpoint: Uint8Array.from(checkpoint),
+                }
+                : { kind: "rebase" });
             input.onSession?.(session);
         }
         finally {
@@ -419,18 +432,21 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const tools = toolState.advertisedTools;
     const allowTools = toolState.allowTools;
     const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
-    const recovery = startOptions?.recovery === true;
+    const recovery = startOptions?.recovery;
+    const resuming = recovery?.kind === "resume";
     // Compaction must not reuse the prior conversation; its first normal turn
     // must also rebase so the summary-agent checkpoint cannot replace the normal
     // system prompt and OpenCode's newly compacted history.
-    const bound = bindConversationId(sessionKey, { reset: resetState.reset || recovery });
+    const bound = resuming
+        ? { conversationId: recovery.conversationId, reset: false, previousId: undefined }
+        : bindConversationId(sessionKey, { reset: resetState.reset || recovery?.kind === "rebase" });
     const conversationId = bound.conversationId;
     if (bound.reset) {
-        trace(`conversation reset: reason=${recovery ? "interrupted-run" : (resetState.reason ?? "unknown")} ` +
+        trace(`conversation reset: reason=${recovery?.kind === "rebase" ? "interrupted-run" : (resetState.reason ?? "unknown")} ` +
             `sessionKey=${sessionKey ?? "(none)"} ` +
             `previousId=${bound.previousId ?? "-"} → conversationId=${conversationId}`);
     }
-    const userText = recovery
+    const userText = recovery?.kind === "rebase"
         ? "Continue the interrupted turn from the conversation history above. Do not repeat completed work."
         : (extractUserText([...prompt].reverse().find((m) => m.role === "user")) || ".");
     const workspaceRoot = path.resolve(options.workspaceRoot || process.cwd());
@@ -440,8 +456,8 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         ? [baseSystemPrompt, interactionGuidance].filter(Boolean).join("\n\n")
         : baseSystemPrompt;
     const history = extractPromptHistory(prompt, {
-        preserveTrailingUser: recovery,
-        toolResults: isCompaction ? "all" : (recovery ? "trailing" : "omit"),
+        preserveTrailingUser: recovery?.kind === "rebase",
+        toolResults: isCompaction ? "all" : (recovery?.kind === "rebase" ? "trailing" : "omit"),
     });
     await loadAvailableModels();
     // Resolve the region-specific Run stream origin once per process (memoized
@@ -485,7 +501,9 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         : [];
     // CLI parity: echo the last conversation_checkpoint_update as conversation_state.
     // After compaction reset there is no checkpoint — seed from OpenCode history.
-    const conversationState = bound.reset ? undefined : getCheckpoint(conversationId);
+    const conversationState = resuming
+        ? recovery.checkpoint
+        : (bound.reset ? undefined : getCheckpoint(conversationId));
     const reqBytes = buildRunRequest({
         text: userText,
         modelId: cursorModelId,
@@ -498,6 +516,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         tools,
         toolDescriptors,
         requestContext,
+        action: resuming ? "resume" : "user",
     });
     // Content hashes — Cursor content-addresses large payloads; logging these lets
     // us match a server get_blob_args.blob_id to what it wants served.
@@ -523,6 +542,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         `availableModels=${_availableModels?.length ?? 0} userTextLen=${userText.length} ` +
         `historyMsgs=${history.length} historyChars=${historyChars} ` +
         `checkpointLen=${conversationState?.length ?? 0} reset=${bound.reset} ` +
+        `resume=${resuming} ` +
         `usageEstimateIn=${usageEstimate.inputTokens} runRequestBytes=${reqBytes.length}`);
     if (hooksCtx)
         trace(`outbound Run hooks_additional_context: ${hooksCtx}`);
@@ -541,6 +561,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const session = {
         sessionId: crypto.randomUUID(),
         conversationId,
+        resumeCheckpoint: undefined,
         openCodeSessionId: sessionKey,
         stream,
         frames: stream.frames()[Symbol.asyncIterator](),
@@ -646,6 +667,7 @@ export function deliverContinuationResults(session, trailingToolResults) {
         if (!pending.bridged) {
             try {
                 const shellResult = pending.resultField === "shell_stream"
+                    || pending.resultField === "background_shell_spawn_result"
                     ? consumeCursorShellResult(r.toolCallId, r.output)
                     : undefined;
                 frames = buildExecClientMessages({
@@ -795,7 +817,7 @@ export async function pump(session, controller, ids, abortSignal) {
     const advertisedToolNameSet = new Set(advertisedToolNames);
     let textStarted = false;
     let reasoningStarted = false;
-    let emittedOutputChars = 0;
+    const requestUsage = ids.requestUsage ?? { outputChars: 0 };
     let replaySafe = true;
     // OpenCode cancels the ReadableStream between turns (see the cancel handler
     // in doStreamImpl). The frames iterator can still yield a final `done` after
@@ -871,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))
@@ -923,7 +945,7 @@ export async function pump(session, controller, ids, abortSignal) {
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
         if (safeEnqueue({ type: "text-delta", id: textId, delta: text })) {
-            emittedOutputChars += text.length;
+            requestUsage.outputChars += text.length;
         }
     };
     const emitReasoning = (text) => {
@@ -936,7 +958,7 @@ export async function pump(session, controller, ids, abortSignal) {
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
         if (safeEnqueue({ type: "reasoning-delta", id: reasoningId, delta: text })) {
-            emittedOutputChars += text.length;
+            requestUsage.outputChars += text.length;
         }
     };
     const emitFinish = (te, reason) => {
@@ -959,7 +981,7 @@ export async function pump(session, controller, ids, abortSignal) {
                 cacheWrite: 0,
             },
             outputTokens: {
-                total: estimateTokens(emittedOutputChars),
+                total: estimateTokens(requestUsage.outputChars),
                 text: undefined,
                 reasoning: undefined,
             },
@@ -1097,6 +1119,7 @@ export async function pump(session, controller, ids, abortSignal) {
                 const bytes = normalizeCheckpointBytes(checkpointRaw);
                 if (bytes && bytes.length > 0) {
                     setCheckpoint(session.conversationId, bytes);
+                    session.resumeCheckpoint = Uint8Array.from(bytes);
                     trace(`checkpoint: stored ${bytes.length}B for conversationId=${session.conversationId}`);
                 }
             }
@@ -1202,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`);
                     }
@@ -1279,7 +1303,8 @@ export async function pump(session, controller, ids, abortSignal) {
                             trace(`exec: claimed display callId=${displayCallId}`);
                         }
                         const tc = buildToolCallPart(parsed, session.sessionId);
-                        if (parsed.resultField === "shell_stream") {
+                        if (parsed.resultField === "shell_stream"
+                            || parsed.resultField === "background_shell_spawn_result") {
                             registerCursorShellCall(tc.toolCallId, parsed.resultMetadata);
                         }
                         // Keep the stream open; the result arrives on the next doStream call.

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, cursorShellOriginalCommand, prepareCursorShellArgs, } 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,13 +338,35 @@ export async function CursorPlugin(input) {
         async "tool.execute.before"(hookInput, output) {
             if (hookInput.tool !== "bash")
                 return;
+            // 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) {
+            const env = cursorShellEnvForCall(hookInput.callID);
+            if (!env)
+                return;
+            Object.assign(output.env, env);
+        },
         async "tool.execute.after"(hookInput, output) {
             if (hookInput.tool !== "bash")
                 return;
-            output.title = cursorShellOriginalCommand(hookInput.callID) ?? output.title;
-            output.output = captureCursorShellResult(hookInput.callID, output.output, output.metadata);
+            try {
+                output.title = cursorShellOriginalCommand(hookInput.callID) ?? output.title;
+                output.output = captureCursorShellResult(hookInput.callID, output.output, output.metadata);
+                // OpenCode's bash GUI falls back to metadata.output when output is empty
+                // (`props.output || props.metadata.output`), so strip private markers there too.
+                if (output.metadata && typeof output.metadata === "object") {
+                    const metadata = output.metadata;
+                    if (typeof metadata.output === "string") {
+                        metadata.output = sanitizeRegisteredCursorShellOutput(hookInput.callID, metadata.output);
+                    }
+                }
+            }
+            finally {
+                releaseCursorShellEnv(hookInput.callID);
+            }
         },
         async "chat.params"(hookInput, output) {
             if (hookInput.model.providerID !== CURSOR_PROVIDER_ID)
@@ -355,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];
@@ -464,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" },
@@ -903,7 +905,9 @@ export function createMessageTypes() {
         { id: 2, name: "request_context", type: "RequestContext" },
     ]);
     addType(root, "ResumeAction", [
-        { id: 1, name: "conversation_id", type: "string" },
+        // Cursor CLI sends an empty ResumeAction. Field #2 is available for a
+        // refreshed RequestContext; the conversation id belongs to AgentRunRequest.
+        { id: 2, name: "request_context", type: "RequestContext" },
     ]);
     addType(root, "CancelAction", [
         { id: 1, name: "conversation_id", type: "string" },

package/dist/protocol/request.d.ts

@@ -32,6 +32,8 @@ export type RunRequestInput = {
     toolDescriptors?: Array<Record<string, unknown>>;
     /** Prebuilt RequestContext (OpenCode-sourced). */
     requestContext?: Record<string, unknown>;
+    /** Resume the supplied checkpoint instead of submitting another user turn. */
+    action?: "user" | "resume";
 };
 /**
  * Seed ConversationStateStructure for the first turn (no checkpoint yet).

package/dist/protocol/request.js

@@ -54,9 +54,11 @@ export function buildRunRequest(input) {
             message_id: msgId,
         },
     };
-    if (requestContext) {
+    if (requestContext)
         userMessageAction.request_context = requestContext;
-    }
+    const action = input.action === "resume"
+        ? { resume_action: {} }
+        : { user_message_action: userMessageAction };
     const conversationState = input.conversationState && input.conversationState.length > 0
         ? input.conversationState
         : buildSeedConversationState({
@@ -65,9 +67,7 @@ export function buildRunRequest(input) {
         });
     const runRequest = {
         conversation_id: input.conversationId,
-        action: {
-            user_message_action: userMessageAction,
-        },
+        action,
         requested_model: {
             // The provider always selects a concrete model. Cursor's "default"
             // pseudo-model (Auto) is never used here — we send the real id plus the

package/dist/protocol/tools.d.ts

@@ -1,4 +1,4 @@
-import type { CursorShellOutcome } from "../shell-timeout.js";
+import { type CursorShellOutcome } from "../shell-timeout.js";
 export declare const REQUEST_CONTEXT_RESULT_FIELD = 10;
 export type OpencodeToolDef = {
     name: string;
@@ -128,7 +128,7 @@ export declare function unwrapReadOutput(output: string): string;
  * OpenCode returns free-form text; we wrap it in the minimal success shape the
  * server accepts (verified against agent.v1 wire captures).
  */
-export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>): Record<string, unknown>;
+export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>, shellOutcome?: CursorShellOutcome): Record<string, unknown>;
 export declare function buildToolCallPart(execMsg: ParsedExecRequest, sessionId: string): {
     toolCallId: string;
     toolName: string;

package/dist/protocol/tools.js

@@ -1,8 +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, 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.
@@ -103,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: {
@@ -128,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
@@ -137,7 +135,7 @@ export function buildLiveRequestContext(tools, providerIdentifier = "opencode",
 // 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
+//   - background_shell_spawn_args → bash (original command; plugin wraps nohup)
 // 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.
@@ -213,7 +211,6 @@ export function mapExecServerToToolName(execField) {
 export function mapToolNameToExecField(toolName) {
     return opencodeToolToCursor[toolName];
 }
-const BACKGROUND_SHELL_MARKER = "__CURSOR_BACKGROUND_SHELL__";
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -235,9 +232,10 @@ 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.
+    // 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);
@@ -253,7 +251,11 @@ export function parseExecServerMessage(msg) {
             toolName: "bash",
             args,
             resultField,
-            resultMetadata: { command: command ?? "", working_directory: workingDirectory },
+            resultMetadata: {
+                background_shell_spawn: true,
+                command: command ?? "",
+                working_directory: workingDirectory,
+            },
             localError: raw.enable_write_shell_stdin_tool === true
                 ? "Interactive background shells are not available through OpenCode's bash tool."
                 : command
@@ -540,25 +542,6 @@ function mapCursorSubagentTypeToOpenCode(subagentType) {
 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 (`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 [
-        'bg_log="$(mktemp "${TMPDIR:-/tmp}/cursor-opencode-bg.XXXXXX")" || exit 1',
-        `nohup sh -c ${shellQuote(command)} >"$bg_log" 2>&1 </dev/null &`,
-        "bg_pid=$!",
-        `printf '${BACKGROUND_SHELL_MARKER}%s:%s\\n' "$bg_pid" "$bg_log"`,
-    ].join("\n");
-}
 /**
  * Map Cursor McpArgs back to the OpenCode tool id.
  * Prefers provider_identifier + bare tool_name (github + create_pull_request
@@ -669,7 +652,7 @@ export function buildExecClientMessages(input) {
             id: input.execId,
             local_execution_time_ms: input.executionTimeMs ?? 0,
         };
-        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName, input.resultMetadata);
+        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName, input.resultMetadata, input.shellOutcome);
         frames.push(encodeMessage("AgentClientMessage", {
             exec_client_message: clientMsg,
         }));
@@ -756,7 +739,7 @@ export function unwrapReadOutput(output) {
  * OpenCode returns free-form text; we wrap it in the minimal success shape the
  * server accepts (verified against agent.v1 wire captures).
  */
-export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata) {
+export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata, shellOutcome) {
     switch (resultField) {
         case "read_result": {
             const readPath = str(resultMetadata?.path) ?? extractPathTag(output) ?? "";
@@ -841,6 +824,19 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             const workingDirectory = str(resultMetadata?.working_directory) ?? "";
             if (error)
                 return { error: { command, working_directory: workingDirectory, error } };
+            // Prefer the structured outcome captured by the plugin after-hook; markers
+            // are already stripped from the stored/rendered OpenCode output by then.
+            if (shellOutcome?.kind === "backgrounded") {
+                return {
+                    success: {
+                        shell_id: shellOutcome.shellId,
+                        command: shellOutcome.command || command,
+                        working_directory: shellOutcome.workingDirectory || workingDirectory,
+                        pid: shellOutcome.pid,
+                    },
+                };
+            }
+            // Fallback when no plugin hook ran: parse the private spawn marker inline.
             const match = new RegExp(`${BACKGROUND_SHELL_MARKER}(\\d+):([^\\r\\n]+)`).exec(output);
             const pid = match ? Number(match[1]) : 0;
             if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0xffff_ffff) {
@@ -1114,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/session.d.ts

@@ -98,6 +98,8 @@ export type CursorSession = {
      * conversation_checkpoint_update (CLI parity).
     */
     conversationId: string;
+    /** Latest eligible checkpoint emitted by this Run attempt. */
+    resumeCheckpoint?: Uint8Array;
     /** OpenCode session whose own or descendant activity renews tool leases. */
     openCodeSessionId?: string;
     stream: BidiStream;