fix(cursor): route denied native tools through advertised Codex exec

docs-site/src/content/docs/guides/providers.md

@@ -519,7 +519,7 @@ and `fast=true` `requested_model` parameters; flattened `cursor-grok-{version}-{
 are discovery and picker identities only. Cursor serves Kimi K3 only as effort-suffixed wire ids, so
 `cursor/kimi-k3` exposes a `low` / `high` / `max` ladder and defaults to `max`, matching the
 model's documented API default. Cursor server-driven native read/write/delete/ls/grep/shell/fetch execution
-is disabled by default because it bypasses Codex's approval and sandbox path; set
+is disabled by default because it bypasses Codex's approval and sandbox path. Denied native calls are rerouted to the Codex tools advertised on that turn — a flat `exec_command` / `shell_command` bridge, or nested `await tools.exec_command(...)` helpers inside Desktop code-mode `exec`. Set
 `unsafeAllowNativeLocalExec: true` on the `providers.cursor` object in `~/.opencodex/config.json`
 only for trusted local experiments (or via **Providers → Cursor → Edit JSON** in the dashboard).
 See the [Configuration reference](/reference/configuration/#cursor-provider-adapter-cursor)

docs-site/src/content/docs/reference/configuration/providers.md

@@ -286,7 +286,7 @@ Explicit variants send Cursor's `default` model with its `optimization` paramete
 selection on every request. They remain available when live discovery omits `default`.
 
 Cursor server-driven local tools are disabled by default. Codex continues using its own tools such as
-`apply_patch` and `exec_command` with its own approval and sandbox policy:
+`apply_patch`, `exec_command`, and Desktop code-mode `exec` (nested `await tools.exec_command(...)` helpers) with its own approval and sandbox policy:
 
 - `"off"` (default) rejects Cursor-native `read`, `write`, `delete`, `ls`, `grep`, `shell`, and
   `fetch` execution.

src/adapters/cursor/live-transport.ts

@@ -59,6 +59,7 @@ import {
   type CursorNativeExecContext,
 } from "./native-exec";
 import { effectiveCursorNativeExecAllow } from "./exec-policy";
+import { rewriteNativeExecToCodexBridge, type NativeExecRewrite } from "./native-exec-bridge";
 import { resolveMcpServers } from "./mcp-config";
 import { CursorMcpManager } from "./mcp-manager";
 import { buildMcpToolDefinitions, mcpDepsFromManager } from "./native-exec-mcp";
@@ -256,6 +257,42 @@ export function planMcpArgsHandling(
   };
 }
 
+/**
+ * Decide how to surface a rewritten native Shell/Read/… exec as a Codex `exec` client tool.
+ *
+ * Same Responses-bridge contract as `planMcpArgsHandling`: emit the tool call, then end turn 1
+ * through the grace timer (`done` + cancel). Immediate `cancelCursorRun()` is wrong here — it sets
+ * `expectedClose` and makes `scheduleClientToolFinalize` a no-op, so turn 1 never emits `done`,
+ * the conversation id is dropped, and the rewritten exec result never returns on the next request.
+ *
+ * Pure (no I/O) so the decision is unit-testable. `handleServerMessage` performs the side effects.
+ */
+export interface NativeExecRewritePlan {
+  handled: boolean;
+  events: CursorServerMessage[];
+  cancelCursorRun: boolean;
+  finalizeWhenDrained: boolean;
+}
+
+export function planNativeExecRewrite(
+  rewrite: NativeExecRewrite,
+  state: ReturnType<typeof createCursorProtobufEventState>,
+): NativeExecRewritePlan {
+  if (rewrite.kind !== "exec") {
+    return { handled: false, events: [], cancelCursorRun: false, finalizeWhenDrained: false };
+  }
+  return {
+    handled: true,
+    events: [
+      { type: "tool_call_start", id: rewrite.callId, name: "exec" },
+      { type: "tool_call_delta", arguments: JSON.stringify({ input: rewrite.js }) },
+      { type: "tool_call_end", id: rewrite.callId },
+    ],
+    cancelCursorRun: false,
+    finalizeWhenDrained: state.openToolCalls.size === 0,
+  };
+}
+
 /**
  * Build the `interactionResponse` reply for a server `interactionQuery`. Cursor's server-side agent
  * BLOCKS on these queries until the client answers (matching `id`); an unanswered query is the
@@ -1069,6 +1106,19 @@ class LiveCursorTransport implements CursorTransport {
           return;
         }
       }
+      const rewrite = rewriteNativeExecToCodexBridge(
+        execMsg.message.case,
+        nativeExecRewriteArgs(execMsg),
+        { clientToolNames: this.execContext.clientToolDefs?.map(tool => tool.toolName || tool.name) ?? [] },
+      );
+      const rewritePlan = planNativeExecRewrite(rewrite, state);
+      if (rewritePlan.handled) {
+        this.noteClientToolActivity();
+        for (const event of rewritePlan.events) push(event);
+        if (rewritePlan.cancelCursorRun) this.cancelCursorRun();
+        else if (rewritePlan.finalizeWhenDrained) this.scheduleClientToolFinalize(state, push);
+        return;
+      }
       // Native exec/MCP is handled inside this transport and can mutate files/process state
       // without emitting a Responses tool event. Mark the turn replay-unsafe before executing so
       // an eventual invalid_argument cannot cause the adapter's fresh-conversation fallback to
@@ -1214,6 +1264,22 @@ function isCursorProgressFrame(message: AgentServerMessage): boolean {
  * count: Cursor-native tool frames (readToolCall/editToolCall/...) are display-plane and must not
  * revoke a pending client-tool finalize. Exported for unit testing.
  */
+
+function nativeExecRewriteArgs(execMsg: { message: { case?: string; value?: unknown }; execId?: string }) {
+  const value = execMsg.message.value;
+  const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  const text = (key: string): string | undefined => {
+    const found = record[key];
+    return typeof found === "string" ? found : undefined;
+  };
+  return {
+    command: text("command"),
+    path: text("path"),
+    url: text("url"),
+    pattern: text("pattern"),
+    toolCallId: text("toolCallId") ?? execMsg.execId,
+  };
+}
 export function isClientToolFrame(message: AgentServerMessage): boolean {
   if (message.message.case !== "interactionUpdate") return false;
   const update = message.message.value.message;

src/adapters/cursor/native-exec-bridge.ts

@@ -0,0 +1,151 @@
+import {
+  CODEX_APPLY_PATCH_TOOL,
+  CODEX_EXEC_COMMAND_TOOL,
+  CODEX_SHELL_COMMAND_TOOL,
+  CODEX_UNIFIED_EXEC_TOOL,
+  isCodexShellBridgeToolName,
+  OCX_RESPONSES_TOOL_PROVIDER,
+} from "./tool-definitions";
+
+export interface CursorNativeExecBridgeCatalog {
+  clientToolNames?: readonly string[];
+}
+
+const CODE_MODE_DISPLAY_NAME = `mcp_${OCX_RESPONSES_TOOL_PROVIDER}_${CODEX_UNIFIED_EXEC_TOOL}`;
+
+const CODE_MODE_SHELL_HINT =
+  `the Codex code-mode tool \`${CODEX_UNIFIED_EXEC_TOOL}\` (Cursor may list it as \`${CODE_MODE_DISPLAY_NAME}\`) and call a nested helper INSIDE its JavaScript body, for example \`await tools.${CODEX_EXEC_COMMAND_TOOL}({cmd: "pwd"})\`. If the catalog shows \`${CODE_MODE_DISPLAY_NAME}\`, call that name. Do not invent a top-level \`${CODEX_SHELL_COMMAND_TOOL}\` / \`${CODEX_EXEC_COMMAND_TOOL}\` call`;
+
+const FLAT_SHELL_HINT =
+  `the Codex bridge shell tool from the current catalog (\`${CODEX_SHELL_COMMAND_TOOL}\` or \`${CODEX_EXEC_COMMAND_TOOL}\`, including the long \`mcp_${OCX_RESPONSES_TOOL_PROVIDER}_*\` display name if listed)`;
+
+function advertisedNames(catalog?: CursorNativeExecBridgeCatalog): string[] {
+  return (catalog?.clientToolNames ?? [])
+    .map(name => name.trim())
+    .filter(name => name.length > 0);
+}
+
+function hasAdvertisedName(names: readonly string[], expected: string): boolean {
+  return names.some(name => name === expected || name.endsWith(`_${expected}`) || name.endsWith(`__${expected}`));
+}
+
+/** True when this turn advertised freeform/code-mode exec and no flat shell bridge. */
+export function cursorNativeExecUsesCodeModeBridge(catalog?: CursorNativeExecBridgeCatalog): boolean {
+  const names = advertisedNames(catalog);
+  if (names.length === 0) return false;
+  const hasExec = hasAdvertisedName(names, CODEX_UNIFIED_EXEC_TOOL);
+  const hasFlatShell = names.some(name =>
+    isCodexShellBridgeToolName(name)
+    || name.endsWith(`_${CODEX_EXEC_COMMAND_TOOL}`)
+    || name.endsWith(`_${CODEX_SHELL_COMMAND_TOOL}`)
+    || name.endsWith(`__${CODEX_EXEC_COMMAND_TOOL}`)
+    || name.endsWith(`__${CODEX_SHELL_COMMAND_TOOL}`),
+  );
+  return hasExec && !hasFlatShell;
+}
+
+function bridgeTarget(catalog?: CursorNativeExecBridgeCatalog): string {
+  return cursorNativeExecUsesCodeModeBridge(catalog) ? CODE_MODE_SHELL_HINT : FLAT_SHELL_HINT;
+}
+
+function silenceClause(kind: "shell" | "filesystem" | "network"): string {
+  if (kind === "filesystem") {
+    return "Do not tell the user shell or read access is blocked, disabled, or denied — silently call that bridge tool.";
+  }
+  if (kind === "network") {
+    return "Do not tell the user network or shell access is blocked, disabled, or denied — silently call that bridge tool.";
+  }
+  return "Do not tell the user shell access is blocked, disabled, or denied — silently call that bridge tool.";
+}
+
+export function nativeShellDisabledMessage(catalog?: CursorNativeExecBridgeCatalog): string {
+  // Do not insist on "the same command" — that steers models into replaying bash/CMD
+  // idioms through the Codex bridge on Windows PowerShell 5.1 and looping (#604).
+  // Keep this host-shell-neutral: OpenCodex may run on a different OS than the Codex
+  // client that executes the bridge (LAN/SSH remote-proxy).
+  return (
+    `Route this through ${bridgeTarget(catalog)}. `
+    + `${silenceClause("shell")} `
+    + "Adapt the command for the Codex client host shell before calling the bridge "
+    + "(Windows PowerShell 5.1: no CMD `cd /d`, no bash heredocs; `&&`/`||` are unsupported parser errors — prefer the bridge working-directory argument for directory changes, and use `if ($?) { ... }` for success-gated follow-up steps; do not treat `;` as a substitute for `&&`). "
+    + "Make at most one corrected bridge attempt after a failure, then report the error and stop — do not repeat equivalent failing commands."
+  );
+}
+
+export function nativeFilesystemDisabledMessage(catalog?: CursorNativeExecBridgeCatalog): string {
+  const editHint = cursorNativeExecUsesCodeModeBridge(catalog)
+    ? `or a nested \`await tools.${CODEX_APPLY_PATCH_TOOL}(...)\` helper inside \`${CODEX_UNIFIED_EXEC_TOOL}\` for file edits`
+    : "or `apply_patch` for file edits";
+  return (
+    `Route filesystem work through ${bridgeTarget(catalog)} with equivalent shell commands (cat, head, ls, rg, grep), ${editHint}. `
+    + silenceClause("filesystem")
+  );
+}
+
+export function nativeFetchDisabledMessage(catalog?: CursorNativeExecBridgeCatalog): string {
+  if (cursorNativeExecUsesCodeModeBridge(catalog)) {
+    return (
+      `Route this through ${CODE_MODE_SHELL_HINT} with a nested \`await tools.${CODEX_EXEC_COMMAND_TOOL}({cmd: "curl ..."})\` helper. `
+      + silenceClause("network")
+    );
+  }
+  return (
+    "Route this through the Codex shell bridge tool `shell_command` (aliases: `exec_command`, `mcp_opencodex-responses_shell_command`, `mcp_opencodex-responses_exec_command`) with curl or wget. "
+    + silenceClause("network")
+  );
+}
+
+export type NativeExecRewrite =
+  | { kind: "none" }
+  | { kind: "exec"; callId: string; source: string; js: string }
+  | { kind: "unsupported"; reason: string };
+
+function quotedShell(value: string): string {
+  return JSON.stringify(value);
+}
+
+function shellCommand(parts: readonly string[]): string {
+  return parts.map(part => /[\s"'`$]/.test(part) ? quotedShell(part) : part).join(" ");
+}
+
+export function rewriteNativeExecToCodexBridge(
+  execCase: string | undefined,
+  args: { command?: string; path?: string; url?: string; pattern?: string; toolCallId?: string },
+  catalog?: CursorNativeExecBridgeCatalog,
+): NativeExecRewrite {
+  if (!cursorNativeExecUsesCodeModeBridge(catalog)) return { kind: "none" };
+  const callId = args.toolCallId?.trim() || `cursor_native_${execCase || "exec"}`;
+  const wrap = (cmd: string): NativeExecRewrite => ({
+    kind: "exec",
+    callId,
+    source: execCase ?? "unknown",
+    js: `const result = await tools.exec_command({cmd: ${quotedShell(cmd)}}); text(typeof result === "string" ? result : (result?.output ?? JSON.stringify(result)));`,
+  });
+  if (execCase === "shellArgs" || execCase === "shellStreamArgs" || execCase === "backgroundShellSpawnArgs") {
+    const command = args.command?.trim();
+    if (!command) return { kind: "unsupported", reason: "empty shell command" };
+    return wrap(command);
+  }
+  if (execCase === "readArgs") {
+    const path = args.path?.trim();
+    if (!path) return { kind: "unsupported", reason: "empty path" };
+    return wrap(shellCommand(["cat", "--", path]));
+  }
+  if (execCase === "lsArgs") {
+    const path = args.path?.trim();
+    if (!path) return { kind: "unsupported", reason: "empty path" };
+    return wrap(shellCommand(["ls", "--", path]));
+  }
+  if (execCase === "grepArgs") {
+    const pattern = args.pattern?.trim();
+    const path = args.path?.trim() || ".";
+    if (!pattern) return { kind: "unsupported", reason: "empty grep pattern" };
+    return wrap(shellCommand(["rg", "--", pattern, path]));
+  }
+  if (execCase === "fetchArgs") {
+    const url = args.url?.trim();
+    if (!url) return { kind: "unsupported", reason: "empty url" };
+    return wrap(shellCommand(["curl", "-fsSL", "--", url]));
+  }
+  return { kind: "none" };
+}

src/adapters/cursor/native-exec-fs.ts

@@ -34,6 +34,7 @@ import {
   type GrepArgs,
 } from "./gen/agent_pb";
 import { errorText, execBytes, lineCount, textDecoder, textEncoder } from "./native-exec-common";
+import { nativeFilesystemDisabledMessage, type CursorNativeExecBridgeCatalog } from "./native-exec-bridge";
 
 const MAX_GREP_FILES = 500;
 const MAX_GREP_RESULTS = 200;
@@ -46,14 +47,15 @@ function codexNativeMutationRefusal(operation: "write" | "delete", structuredEdi
   return `Cursor-native ${operation} is disabled for this Codex request because apply_patch is available.${structuredHint} No file was changed.`;
 }
 
-const NATIVE_LOCAL_EXEC_DISABLED =
-  "Route filesystem work through the Codex Responses bridge shell tool (`shell_command` / `exec_command`, or the listed `mcp_opencodex-responses_*` display alias) with equivalent shell commands (cat, head, ls, rg, grep), or `apply_patch` for file edits. Do not tell the user shell or read access is blocked, disabled, or denied — silently call that bridge tool.";
+function nativeLocalExecDisabled(catalog?: CursorNativeExecBridgeCatalog): string {
+  return nativeFilesystemDisabledMessage(catalog);
+}
 
-export function rejectReadExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectReadExecForPolicy(execMsg: ExecServerMessage, catalog?: CursorNativeExecBridgeCatalog): Uint8Array {
   if (execMsg.message.case !== "readArgs") throw new Error("invalid read exec");
   const path = resolve(execMsg.message.value.path);
   return execBytes(execMsg, "readResult", create(ReadResultSchema, {
-    result: { case: "error", value: create(ReadErrorSchema, { path, error: NATIVE_LOCAL_EXEC_DISABLED }) },
+    result: { case: "error", value: create(ReadErrorSchema, { path, error: nativeLocalExecDisabled(catalog) }) },
   }));
 }
 
@@ -98,13 +100,13 @@ export function rejectWriteExecForApplyPatch(execMsg: ExecServerMessage, structu
   }));
 }
 
-export function rejectWriteExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectWriteExecForPolicy(execMsg: ExecServerMessage, catalog?: CursorNativeExecBridgeCatalog): Uint8Array {
   if (execMsg.message.case !== "writeArgs") throw new Error("invalid write exec");
   const path = resolve(execMsg.message.value.path);
   return execBytes(execMsg, "writeResult", create(WriteResultSchema, {
     result: {
       case: "rejected",
-      value: create(WriteRejectedSchema, { path, reason: `${NATIVE_LOCAL_EXEC_DISABLED} No file was changed.` }),
+      value: create(WriteRejectedSchema, { path, reason: `${nativeLocalExecDisabled(catalog)} No file was changed.` }),
     },
   }));
 }
@@ -147,13 +149,13 @@ export function rejectDeleteExecForApplyPatch(execMsg: ExecServerMessage, struct
   }));
 }
 
-export function rejectDeleteExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectDeleteExecForPolicy(execMsg: ExecServerMessage, catalog?: CursorNativeExecBridgeCatalog): Uint8Array {
   if (execMsg.message.case !== "deleteArgs") throw new Error("invalid delete exec");
   const path = resolve(execMsg.message.value.path);
   return execBytes(execMsg, "deleteResult", create(DeleteResultSchema, {
     result: {
       case: "rejected",
-      value: create(DeleteRejectedSchema, { path, reason: `${NATIVE_LOCAL_EXEC_DISABLED} No file was changed.` }),
+      value: create(DeleteRejectedSchema, { path, reason: `${nativeLocalExecDisabled(catalog)} No file was changed.` }),
     },
   }));
 }
@@ -188,11 +190,11 @@ export function deleteExec(execMsg: ExecServerMessage): Uint8Array {
   }
 }
 
-export function rejectLsExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectLsExecForPolicy(execMsg: ExecServerMessage, catalog?: CursorNativeExecBridgeCatalog): Uint8Array {
   if (execMsg.message.case !== "lsArgs") throw new Error("invalid ls exec");
   const path = resolve(execMsg.message.value.path);
   return execBytes(execMsg, "lsResult", create(LsResultSchema, {
-    result: { case: "error", value: create(LsErrorSchema, { path, error: NATIVE_LOCAL_EXEC_DISABLED }) },
+    result: { case: "error", value: create(LsErrorSchema, { path, error: nativeLocalExecDisabled(catalog) }) },
   }));
 }
 
@@ -256,8 +258,8 @@ function grepError(execMsg: ExecServerMessage, error: string): Uint8Array {
   }));
 }
 
-export function rejectGrepExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
-  return grepError(execMsg, NATIVE_LOCAL_EXEC_DISABLED);
+export function rejectGrepExecForPolicy(execMsg: ExecServerMessage, catalog?: CursorNativeExecBridgeCatalog): Uint8Array {
+  return grepError(execMsg, nativeLocalExecDisabled(catalog));
 }
 
 export function grepExec(execMsg: ExecServerMessage): Uint8Array {

src/adapters/cursor/native-exec-network.ts

@@ -1,19 +1,21 @@
 import { create } from "@bufbuild/protobuf";
 import { FetchErrorSchema, FetchResultSchema, FetchSuccessSchema, type ExecServerMessage } from "./gen/agent_pb";
 import { errorText, execBytes } from "./native-exec-common";
+import { nativeFetchDisabledMessage, type CursorNativeExecBridgeCatalog } from "./native-exec-bridge";
 
 export interface CursorNativeNetworkDeps {
   fetch?: typeof fetch;
 }
 
-const NATIVE_FETCH_DISABLED =
-  "Route this through the Codex shell bridge tool `shell_command` (aliases: `exec_command`, `mcp_opencodex-responses_shell_command`, `mcp_opencodex-responses_exec_command`) with curl or wget. Do not tell the user network or shell access is blocked, disabled, or denied — silently call that bridge tool.";
+function nativeFetchDisabled(catalog?: CursorNativeExecBridgeCatalog): string {
+  return nativeFetchDisabledMessage(catalog);
+}
 
-export function rejectFetchExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectFetchExecForPolicy(execMsg: ExecServerMessage, catalog?: CursorNativeExecBridgeCatalog): Uint8Array {
   if (execMsg.message.case !== "fetchArgs") throw new Error("invalid fetch exec");
   const args = execMsg.message.value;
   return execBytes(execMsg, "fetchResult", create(FetchResultSchema, {
-    result: { case: "error", value: create(FetchErrorSchema, { url: args.url, error: NATIVE_FETCH_DISABLED }) },
+    result: { case: "error", value: create(FetchErrorSchema, { url: args.url, error: nativeFetchDisabled(catalog) }) },
   }));
 }