cursor-opencode-provider 0.2.5 → 0.2.6

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.5"`.
+Pin a version if you want: `"cursor-opencode-provider@0.2.6"`.
 
 ### From a local clone
 
@@ -165,7 +165,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`. Retries occur only before visible output or stateful server activity; unsafe replay is surfaced instead of risking duplicate text or tool work. 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`, `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`.
 
 ## Environment variables
 
@@ -242,7 +242,7 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | 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. |
-| Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, and transparently rebases once from full OpenCode history if the Run ends before `turn_ended`. 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` and `rebasing fresh Run`. Restart OpenCode after rebuilding a local `file://` install. |
+| 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. |
 | `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. |
@@ -259,11 +259,11 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **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 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.
+- **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`.
 - **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 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.
+- **Interrupted Runs resume from checkpoints** — a remote EOF, Connect end-stream, or trailer error is never emitted as a successful `stop`. When the failed Run produced an eligible checkpoint, the provider opens a new RPC for the same conversation and sends that state with `ResumeAction`, so completed text and tool work are not replayed. Before any stateful output, an interruption without a checkpoint can still rebase from OpenCode history. Stateful interruptions without a checkpoint are surfaced because replay would be ambiguous; retry exhaustion remains explicit. A transport closure after `turn_ended` is treated as successful completion.
 - **No fallback models** — if Cursor’s `AvailableModels` API is unreachable and there is no local cache, the provider exposes no models.
 
 ## License

package/dist/language-model.d.ts

@@ -20,10 +20,17 @@ export declare function pumpWithRecovery(input: {
     abortSignal?: AbortSignal;
     promptTokens?: number;
     retryPolicy?: CursorRetryPolicy;
-    recover: () => Promise<CursorSession>;
+    recover: (recovery: CursorRunRecovery) => Promise<CursorSession>;
     onSession?: (session: CursorSession) => void;
     maxRecoveries?: number;
 }): Promise<CursorSession>;
+export type CursorRunRecovery = {
+    kind: "rebase";
+} | {
+    kind: "resume";
+    conversationId: string;
+    checkpoint: Uint8Array;
+};
 /**
  * OpenCode re-sends the full tool-result history on every continuation. Prefer
  * the newest result that still has a live pending exec on its tagged session.
@@ -50,6 +57,9 @@ export declare function pump(session: CursorSession, controller: ReadableStreamD
     textId: string;
     reasoningId: string;
     promptTokens?: number;
+    requestUsage?: {
+        outputChars: number;
+    };
 }, abortSignal?: AbortSignal): Promise<void>;
 type ExtractedToolResult = {
     toolCallId: string;

package/dist/language-model.js

@@ -288,7 +288,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 +323,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 +361,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 +372,7 @@ export async function pumpWithRecovery(input) {
                 textId: crypto.randomUUID(),
                 reasoningId: crypto.randomUUID(),
                 promptTokens: input.promptTokens ?? 0,
+                requestUsage,
             }, input.abortSignal);
             return session;
         }
@@ -381,19 +383,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 +428,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 +452,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 +497,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 +512,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 +538,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 +557,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 +663,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 +813,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
@@ -923,7 +941,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 +954,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 +977,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 +1115,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}`);
                 }
             }
@@ -1279,7 +1298,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.js

@@ -4,7 +4,7 @@ import { CURSOR_VARIANT_PARAMETERS_KEY, CURSOR_WIRE_MODEL_ID_KEY, readCache, dis
 import { 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, } from "./shell-timeout.js";
 import { sessionActivity } from "./activity.js";
 const MODULE_URL = new URL("./index.js", import.meta.url).href;
 /**
@@ -336,13 +336,35 @@ 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.
             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)

package/dist/protocol/messages.js

@@ -903,7 +903,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

@@ -3,6 +3,7 @@ import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
 import { trace } from "../debug.js";
 import { cursorExecVariantByRequestName } from "./exec-variants.js";
+import { BACKGROUND_SHELL_MARKER } 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.
@@ -137,7 +138,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 +214,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,8 +235,8 @@ 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).
+    // 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.
     if (execVariant === "background_shell_spawn_args") {
         const raw = msg.background_shell_spawn_args ?? {};
@@ -244,7 +244,7 @@ export function parseExecServerMessage(msg) {
         const workingDirectory = str(raw.working_directory) ?? "";
         const args = {};
         if (command)
-            args.command = buildBackgroundShellCommand(command);
+            args.command = command;
         if (workingDirectory)
             args.workdir = workingDirectory;
         return {
@@ -253,7 +253,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 +544,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 +654,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 +741,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 +826,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) {

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;

package/dist/shell-timeout.d.ts

@@ -1,12 +1,16 @@
 /** Cursor agent.v1 TimeoutBehavior enum values. */
 export declare const CURSOR_TIMEOUT_CANCEL = 1;
 export declare const CURSOR_TIMEOUT_BACKGROUND = 2;
+/** Private marker for Cursor `background_shell_spawn_args` detach wrappers. */
+export declare const BACKGROUND_SHELL_MARKER = "__CURSOR_BACKGROUND_SHELL__";
 export type CursorShellPolicy = {
     command: string;
     workingDirectory: string;
     timeoutMs: number;
     timeoutBehavior: number;
     hardTimeoutMs?: number;
+    /** Immediate nohup detach for Cursor `background_shell_spawn_args`. */
+    backgroundSpawn?: boolean;
 };
 export type CursorShellOutcome = {
     kind: "exit";
@@ -39,10 +43,48 @@ export declare function registerCursorShellCall(toolCallId: string, metadata: Re
  * 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. */
+/**
+ * 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.
+ */
+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.
+ *
+ * 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 declare function prepareCursorShellArgs(toolCallId: string, args: Record<string, unknown>): void;
 /** Restore the model-facing command in OpenCode's completed tool title. */
 export declare function cursorShellOriginalCommand(toolCallId: string): string | undefined;
+/** 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.
+ */
+export declare function cursorShellEnvForCall(toolCallId: string | undefined): Record<string, string> | undefined;
+/**
+ * Strip private wrapper sentinels / OpenCode timeout envelopes for display.
+ * Does not record outcomes — use {@link captureCursorShellResult} for that.
+ */
+export declare function sanitizeCursorShellDisplayOutput(output: string, policy?: CursorShellPolicy): string;
+/** Sanitize a secondary display string (e.g. Bash `metadata.output`) for a registered call. */
+export declare function sanitizeRegisteredCursorShellOutput(toolCallId: string, output: string): string;
 /**
  * Capture Bash completion in the classic plugin's after hook. Returns the
  * sanitized output that OpenCode should store and render.

package/dist/shell-timeout.js

@@ -1,3 +1,6 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 /** Cursor agent.v1 TimeoutBehavior enum values. */
 export const CURSOR_TIMEOUT_CANCEL = 1;
 export const CURSOR_TIMEOUT_BACKGROUND = 2;
@@ -7,16 +10,24 @@ const POLL_INTERVAL_MS = 100;
 const BACKGROUND_MARKER = "__CURSOR_SHELL_BACKGROUND__";
 const EXIT_MARKER = "__CURSOR_SHELL_EXIT__";
 const TIMEOUT_MARKER = "__CURSOR_SHELL_TIMEOUT__";
+/** Private marker for Cursor `background_shell_spawn_args` detach wrappers. */
+export const BACKGROUND_SHELL_MARKER = "__CURSOR_BACKGROUND_SHELL__";
 const policies = new Map();
 const outcomes = new Map();
-function remember(map, key, value) {
+/** callIDs that need shell.env injectors (so args.command can stay display-original). */
+const pendingEnvWraps = new Set();
+const activeEnvWraps = new Map();
+function remember(map, key, value, onEvict) {
     map.delete(key);
     map.set(key, value);
     while (map.size > MAX_TRACKED_SHELL_CALLS) {
         const oldest = map.keys().next().value;
         if (!oldest)
             break;
+        const evicted = map.get(oldest);
         map.delete(oldest);
+        if (evicted !== undefined && onEvict)
+            onEvict(evicted);
     }
 }
 function finiteNonNegative(value) {
@@ -26,7 +37,18 @@ function finiteNonNegative(value) {
     return Math.floor(n);
 }
 export function shellPolicyFromMetadata(metadata) {
-    if (!metadata || metadata.shell_stream !== true)
+    if (!metadata)
+        return undefined;
+    if (metadata.background_shell_spawn === true) {
+        return {
+            command: typeof metadata.command === "string" ? metadata.command : "",
+            workingDirectory: typeof metadata.working_directory === "string" ? metadata.working_directory : "",
+            timeoutMs: 0,
+            timeoutBehavior: 0,
+            backgroundSpawn: true,
+        };
+    }
+    if (metadata.shell_stream !== true)
         return undefined;
     const timeoutMs = finiteNonNegative(metadata.timeout_ms) ?? 30_000;
     const timeoutBehavior = finiteNonNegative(metadata.timeout_behavior) ?? 0;
@@ -77,15 +99,59 @@ export function buildSoftBackgroundCommand(policy) {
     else {
         lines.push('cursor_shell_status=""', 'cursor_shell_watchdog_pid=""');
     }
-    lines.push("cursor_shell_poll=0", `while [ "$cursor_shell_poll" -lt ${polls} ] && kill -0 "$cursor_shell_pid" 2>/dev/null; do`, `  sleep ${POLL_INTERVAL_MS / 1000}`, "  cursor_shell_poll=$((cursor_shell_poll + 1))", "done", 'if kill -0 "$cursor_shell_pid" 2>/dev/null; then', '  cat "$cursor_shell_log"', `  printf '\n${BACKGROUND_MARKER}%s:%s\n' "$cursor_shell_pid" "$cursor_shell_log"`, "  exit 0", "fi", 'wait "$cursor_shell_pid"', "cursor_shell_code=$?", 'cat "$cursor_shell_log"', 'if [ -n "$cursor_shell_status" ] && [ "$(cat "$cursor_shell_status" 2>/dev/null)" = timeout ]; then', `  printf '\n${TIMEOUT_MARKER}%s\n' ${policy.hardTimeoutMs ?? policy.timeoutMs}`, "else", '  if [ -n "$cursor_shell_watchdog_pid" ]; then kill "$cursor_shell_watchdog_pid" 2>/dev/null || true; fi', `  printf '\n${EXIT_MARKER}%s\n' "$cursor_shell_code"`, "fi", 'rm -f -- "$cursor_shell_log"', 'if [ -n "$cursor_shell_status" ]; then rm -f -- "$cursor_shell_status"; fi');
+    lines.push(
+    // Avoid interactive job-control noise ("Terminated: 15 …") when we later
+    // reap the watchdog; that text can otherwise land after our private marker
+    // and leak into OpenCode's bash UI.
+    "set +m 2>/dev/null || true", 'if [ -n "$cursor_shell_watchdog_pid" ]; then disown "$cursor_shell_watchdog_pid" 2>/dev/null || true; fi', 'disown "$cursor_shell_pid" 2>/dev/null || true', "cursor_shell_poll=0", `while [ "$cursor_shell_poll" -lt ${polls} ] && kill -0 "$cursor_shell_pid" 2>/dev/null; do`, `  sleep ${POLL_INTERVAL_MS / 1000}`, "  cursor_shell_poll=$((cursor_shell_poll + 1))", "done", 'if kill -0 "$cursor_shell_pid" 2>/dev/null; then', '  cat "$cursor_shell_log"', `  printf '\n${BACKGROUND_MARKER}%s:%s\n' "$cursor_shell_pid" "$cursor_shell_log"`, "  exit 0", "fi", 'wait "$cursor_shell_pid" 2>/dev/null', "cursor_shell_code=$?", 'cat "$cursor_shell_log"', 'if [ -n "$cursor_shell_status" ] && [ "$(cat "$cursor_shell_status" 2>/dev/null)" = timeout ]; then', 
+    // Reap the watchdog before printing the private marker so any residual
+    // shell diagnostics cannot trail the sentinel.
+    '  if [ -n "$cursor_shell_watchdog_pid" ]; then kill "$cursor_shell_watchdog_pid" 2>/dev/null || true; wait "$cursor_shell_watchdog_pid" 2>/dev/null || true; fi', `  printf '\n${TIMEOUT_MARKER}%s\n' ${policy.hardTimeoutMs ?? policy.timeoutMs}`, "else", '  if [ -n "$cursor_shell_watchdog_pid" ]; then kill "$cursor_shell_watchdog_pid" 2>/dev/null || true; wait "$cursor_shell_watchdog_pid" 2>/dev/null || true; fi', `  printf '\n${EXIT_MARKER}%s\n' "$cursor_shell_code"`, "fi", 'rm -f -- "$cursor_shell_log"', 'if [ -n "$cursor_shell_status" ]; then rm -f -- "$cursor_shell_status"; fi');
     return lines.join("\n");
 }
-/** Mutate OpenCode Bash args before execution when Cursor requested soft backgrounding. */
+/**
+ * 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.
+ */
+export 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");
+}
+/**
+ * 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 || policy.timeoutBehavior !== CURSOR_TIMEOUT_BACKGROUND)
+    if (!policy)
+        return;
+    if (policy.backgroundSpawn) {
+        pendingEnvWraps.add(toolCallId);
         return;
-    args.command = buildSoftBackgroundCommand(policy);
+    }
+    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);
@@ -94,12 +160,127 @@ export function prepareCursorShellArgs(toolCallId, args) {
 export function cursorShellOriginalCommand(toolCallId) {
     return policies.get(toolCallId)?.command || undefined;
 }
+function writeShellEnvInjector(wrapperBody) {
+    const dir = mkdtempSync(join(tmpdir(), "cursor-opencode-wrap-"));
+    const wrapperPath = join(dir, "wrapper.sh");
+    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.
+    const injector = [
+        "unset BASH_ENV ZDOTDIR ENV CURSOR_OPENCODE_WRAP_ACTIVE",
+        `exec /bin/sh ${shellQuote(wrapperPath)}`,
+        "",
+    ].join("\n");
+    writeFileSync(bashEnvPath, injector, { mode: 0o600 });
+    writeFileSync(zshenvPath, injector, { mode: 0o600 });
+    return {
+        env: {
+            BASH_ENV: bashEnvPath,
+            ZDOTDIR: dir,
+        },
+        cleanup: () => {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort temp cleanup
+            }
+        },
+    };
+}
+/** Drop injector temp files for a finished/abandoned Cursor shell call. */
+export function releaseCursorShellEnv(toolCallId) {
+    pendingEnvWraps.delete(toolCallId);
+    const active = activeEnvWraps.get(toolCallId);
+    if (!active)
+        return;
+    activeEnvWraps.delete(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.
+ */
+export function cursorShellEnvForCall(toolCallId) {
+    if (typeof toolCallId !== "string" || !toolCallId || !pendingEnvWraps.has(toolCallId))
+        return undefined;
+    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)
+        return undefined;
+    const wrap = writeShellEnvInjector(wrapperBody);
+    remember(activeEnvWraps, toolCallId, wrap, (evicted) => evicted.cleanup());
+    pendingEnvWraps.delete(toolCallId);
+    return wrap.env;
+}
 function withoutMarker(output, index) {
     let clean = output.slice(0, index).replace(/[\t ]+$/gm, "").replace(/\n{2,}$/, "\n");
     if (clean.trim() === "" || clean.trim() === "(no output)")
         clean = "";
     return clean;
 }
+/**
+ * OpenCode only stores/renders text (`output` / `metadata.output`). Private
+ * markers become typed Cursor outcomes, but stripping them alone can leave a
+ * blank or partial bash bubble that looks like success. Append a short
+ * user-facing status so the UI explains background handoff / timeout.
+ */
+function formatShellOutcomeDisplay(clean, outcome) {
+    let notice;
+    if (outcome.kind === "backgrounded") {
+        notice = outcome.msToWait > 0
+            ? `Still running in the background (pid ${outcome.pid}) after ${outcome.msToWait}ms.`
+            : `Started in the background (pid ${outcome.pid}).`;
+    }
+    else if (outcome.kind === "timeout") {
+        notice = `Timed out after ${outcome.timeoutMs}ms.`;
+    }
+    if (!notice)
+        return clean;
+    if (!clean)
+        return `${notice}\n`;
+    return clean.endsWith("\n") ? `${clean}${notice}\n` : `${clean}\n${notice}\n`;
+}
+/**
+ * Find the last private wrapper sentinel.
+ *
+ * Soft-background wrappers print the marker as the final intentional line, but
+ * the host shell can still append job-control diagnostics afterwards (e.g.
+ * "Terminated: 15 … nohup sh -c '…cursor-shell-watchdog…'"). Match the sentinel
+ * on its own line and discard everything from that point to EOF.
+ */
+function lastPrivateMarker(output, marker, valuePattern) {
+    const re = new RegExp(`(?:^|\\r?\\n)(${marker}${valuePattern})`, "g");
+    let match;
+    let last;
+    while ((match = re.exec(output)) !== null) {
+        if (match.index === undefined || match[1] === undefined)
+            continue;
+        const index = match[0].startsWith("\r\n")
+            ? match.index + 2
+            : match[0].startsWith("\n")
+                ? match.index + 1
+                : match.index;
+        last = { index, values: match.slice(2) };
+    }
+    return last;
+}
 function parseOpenCodeTimeout(output) {
     const re = /<shell_metadata>\r?\nshell tool terminated command after exceeding timeout (\d+) ms\.[\s\S]*?<\/shell_metadata>\s*$/;
     const match = re.exec(output);
@@ -107,10 +288,10 @@ function parseOpenCodeTimeout(output) {
         return undefined;
     return { output: withoutMarker(output, match.index), timeoutMs: Number(match[1]) };
 }
-function parseWrapperOutcome(output, policy) {
-    const background = new RegExp(`${BACKGROUND_MARKER}(\\d+):([^\\r\\n]+)\\s*$`).exec(output);
-    if (background?.index !== undefined) {
-        const pid = Number(background[1]);
+function parseSoftBackgroundOutcome(output, policy) {
+    const background = lastPrivateMarker(output, BACKGROUND_MARKER, "(\\d+):([^\\r\\n]+)");
+    if (background) {
+        const pid = Number(background.values[0]);
         if (Number.isSafeInteger(pid) && pid > 0 && pid <= 0xffff_ffff) {
             return {
                 output: withoutMarker(output, background.index),
@@ -126,43 +307,101 @@ function parseWrapperOutcome(output, policy) {
             };
         }
     }
-    const timeout = new RegExp(`${TIMEOUT_MARKER}(\\d+)\\s*$`).exec(output);
-    if (timeout?.index !== undefined) {
+    const timeout = lastPrivateMarker(output, TIMEOUT_MARKER, "(\\d+)");
+    if (timeout) {
         return {
             output: withoutMarker(output, timeout.index),
-            outcome: { kind: "timeout", timeoutMs: Number(timeout[1]) },
+            outcome: { kind: "timeout", timeoutMs: Number(timeout.values[0]) },
         };
     }
-    const exit = new RegExp(`${EXIT_MARKER}(-?\\d+)\\s*$`).exec(output);
-    if (exit?.index !== undefined) {
+    const exit = lastPrivateMarker(output, EXIT_MARKER, "(-?\\d+)");
+    if (exit) {
         return {
             output: withoutMarker(output, exit.index),
-            outcome: { kind: "exit", code: Number(exit[1]) },
+            outcome: { kind: "exit", code: Number(exit.values[0]) },
         };
     }
     return undefined;
 }
+function parseBackgroundSpawnOutcome(output, policy) {
+    const match = lastPrivateMarker(output, BACKGROUND_SHELL_MARKER, "(\\d+):([^\\r\\n]+)");
+    if (!match)
+        return undefined;
+    const pid = Number(match.values[0]);
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0xffff_ffff)
+        return undefined;
+    return {
+        output: withoutMarker(output, match.index),
+        outcome: {
+            kind: "backgrounded",
+            shellId: pid,
+            pid,
+            command: policy?.command ?? "",
+            workingDirectory: policy?.workingDirectory ?? "",
+            msToWait: 0,
+            reason: 1,
+        },
+    };
+}
+/**
+ * Strip private wrapper sentinels / OpenCode timeout envelopes for display.
+ * Does not record outcomes — use {@link captureCursorShellResult} for that.
+ */
+export function sanitizeCursorShellDisplayOutput(output, policy) {
+    if (policy?.backgroundSpawn) {
+        const spawn = parseBackgroundSpawnOutcome(output, policy);
+        if (spawn)
+            return formatShellOutcomeDisplay(spawn.output, spawn.outcome);
+    }
+    if (policy?.timeoutBehavior === CURSOR_TIMEOUT_BACKGROUND) {
+        const wrapper = parseSoftBackgroundOutcome(output, policy);
+        if (wrapper)
+            return formatShellOutcomeDisplay(wrapper.output, wrapper.outcome);
+    }
+    const timeout = parseOpenCodeTimeout(output);
+    if (timeout) {
+        return formatShellOutcomeDisplay(timeout.output, {
+            kind: "timeout",
+            timeoutMs: timeout.timeoutMs,
+        });
+    }
+    return output;
+}
+/** Sanitize a secondary display string (e.g. Bash `metadata.output`) for a registered call. */
+export function sanitizeRegisteredCursorShellOutput(toolCallId, output) {
+    if (typeof toolCallId !== "string" || !toolCallId)
+        return output;
+    return sanitizeCursorShellDisplayOutput(output, policies.get(toolCallId));
+}
 /**
  * Capture Bash completion in the classic plugin's after hook. Returns the
  * sanitized output that OpenCode should store and render.
  */
 export function captureCursorShellResult(toolCallId, output, metadata) {
-    if (!toolCallId.startsWith("cursor_"))
+    if (typeof toolCallId !== "string" || !toolCallId.startsWith("cursor_"))
         return output;
     const policy = policies.get(toolCallId);
+    if (policy?.backgroundSpawn) {
+        const spawn = parseBackgroundSpawnOutcome(output, policy);
+        if (spawn) {
+            remember(outcomes, toolCallId, spawn.outcome);
+            return formatShellOutcomeDisplay(spawn.output, spawn.outcome);
+        }
+    }
     // Private wrapper sentinels are meaningful only for calls we transformed.
     // A normal foreground command is allowed to print the same text verbatim.
     const wrapper = policy?.timeoutBehavior === CURSOR_TIMEOUT_BACKGROUND
-        ? parseWrapperOutcome(output, policy)
+        ? parseSoftBackgroundOutcome(output, policy)
         : undefined;
     if (wrapper) {
         remember(outcomes, toolCallId, wrapper.outcome);
-        return wrapper.output;
+        return formatShellOutcomeDisplay(wrapper.output, wrapper.outcome);
     }
     const timeout = parseOpenCodeTimeout(output);
     if (timeout) {
-        remember(outcomes, toolCallId, { kind: "timeout", timeoutMs: timeout.timeoutMs });
-        return timeout.output;
+        const outcome = { kind: "timeout", timeoutMs: timeout.timeoutMs };
+        remember(outcomes, toolCallId, outcome);
+        return formatShellOutcomeDisplay(timeout.output, outcome);
     }
     const exitCode = finiteNonNegative(metadata?.exit);
     if (exitCode !== undefined)
@@ -171,16 +410,24 @@ export function captureCursorShellResult(toolCallId, output, metadata) {
 }
 /** Consume the structured result, with an inline fallback when no plugin hook ran. */
 export function consumeCursorShellResult(toolCallId, output) {
+    if (typeof toolCallId !== "string" || !toolCallId) {
+        return { output };
+    }
     let clean = output;
     if (!outcomes.has(toolCallId))
         clean = captureCursorShellResult(toolCallId, output);
     const outcome = outcomes.get(toolCallId);
     outcomes.delete(toolCallId);
     policies.delete(toolCallId);
+    releaseCursorShellEnv(toolCallId);
     return { output: clean, outcome };
 }
 /** Test/process cleanup. */
 export function resetCursorShellCalls() {
+    for (const wrap of activeEnvWraps.values())
+        wrap.cleanup();
+    activeEnvWraps.clear();
+    pendingEnvWraps.clear();
     policies.clear();
     outcomes.clear();
 }

package/package.json

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