@yansigit/opencodex 2.32.0 → 2.33.1

package/src/adapters/base.ts

@@ -19,6 +19,8 @@ export interface IncomingMeta {
    * anthropic adapter consumes it; others ignore it.
    */
   imageTierBias?: number;
+  /** Provider-scoped structured error observation; never receives ordinary model payloads. */
+  onProviderError?: (error: { code?: string; status?: number; message?: string }) => void;
 }
 
 export interface ProviderAdapter {
@@ -81,7 +83,7 @@ export interface AdapterRequest {
     /** Client tool-search names actually lowered to upstream function calls for this request. */
     convertedRoutedToolSearchNames?: ReadonlySet<string>;
     /** Upstream-only aliases for namespace tools flattened in this request. */
-    convertedRoutedNamespaceToolAliases?: ReadonlyMap<string, { namespace: string; name: string }>;
+    convertedRoutedNamespaceToolAliases?: ReadonlyMap<string, { namespace: string; name: string; kind: "function" | "custom" }>;
     /** Releases observation of a serialized request body after its final fetch attempt settles. */
     releaseBodyObservation?: () => void;
     /** Exact reasoning parameter emitted by the adapter, for request-log diagnostics only. */

package/src/adapters/command-code.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { opendir } from "node:fs/promises";
@@ -12,7 +12,7 @@ import { commandCodeReasoningEfforts, refreshCommandCodeReasoningEfforts } from
 import { identifyRoutedModel } from "./identity";
 import { buildNonOpenAIToolCatalogNudgeForTools } from "./tool-catalog-nudge";
 import { parseDataUrl } from "./image";
-import { EMPTY_COMMAND_CODE_PROJECT_CONTEXT, loadCommandCodeProjectContext } from "./command-code-project-context";
+import { redactSecretString } from "../lib/redact";
 
 // Retain the short ids emitted by the first local integration. New requests use the live catalog's
 // provider-native IDs directly; this map is compatibility-only and is not a model fallback list.
@@ -27,6 +27,23 @@ function canonicalCommandCodeModelId(modelId: string): string {
   return Object.hasOwn(COMMAND_CODE_MODEL_ALIASES, modelId) ? COMMAND_CODE_MODEL_ALIASES[modelId]! : modelId;
 }
 
+/** Surface Command Code's JSON error message to sidecar callers instead of a bare HTTP status. */
+export function formatCommandCodeErrorBody(_status: number, _headers: Headers, payloadText: string): string {
+  try {
+    const payload = JSON.parse(payloadText) as unknown;
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return "";
+    const error = (payload as Record<string, unknown>).error;
+    const message = (error && typeof error === "object" && !Array.isArray(error)
+      ? (error as Record<string, unknown>).message
+      : undefined) ?? (payload as Record<string, unknown>).message;
+    return typeof message === "string" && message.trim()
+      ? redactSecretString(message.trim()).slice(0, 400)
+      : "";
+  } catch {
+    return "";
+  }
+}
+
 /** Flatten tool-result content for the text-only wire output, keeping an `[image]` marker per image part in content order. */
 function toolResultText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
@@ -157,13 +174,17 @@ function visibleTools(parsed: OcxParsedRequest): OcxTool[] {
   if (choice === "none") return [];
   const tools = parsed.context.tools ?? [];
   if (isAllowedToolChoice(choice)) {
-    return tools.filter(toolChoiceToolPredicate(choice, tools));
+    return tools
+      .filter(toolChoiceToolPredicate(choice, tools))
+      .sort((left, right) => namespacedToolName(left.namespace, left.name).localeCompare(namespacedToolName(right.namespace, right.name)));
   }
   if (choice && typeof choice !== "string") {
     const selected = resolveToolChoiceWireName(tools, choice.name);
-    return tools.filter(tool => namespacedToolName(tool.namespace, tool.name) === selected);
+    return tools
+      .filter(tool => namespacedToolName(tool.namespace, tool.name) === selected)
+      .sort((left, right) => namespacedToolName(left.namespace, left.name).localeCompare(namespacedToolName(right.namespace, right.name)));
   }
-  return tools;
+  return [...tools].sort((left, right) => namespacedToolName(left.namespace, left.name).localeCompare(namespacedToolName(right.namespace, right.name)));
 }
 
 function toolChoiceInstruction(parsed: OcxParsedRequest): string | undefined {
@@ -194,6 +215,9 @@ function currentWorkingDirectory(): string | undefined {
 
 /** Cap the workspace listing so a large directory does not ship every entry name upstream. */
 const MAX_WORKSPACE_STRUCTURE_ENTRIES = 64;
+/** Cap directory entries scanned while selecting the stable workspace prefix. */
+export const MAX_WORKSPACE_STRUCTURE_SCAN_ENTRIES = 4096;
+// ponytail: the bounded scan trades complete directory coverage for request latency; raise only with measured need.
 /** Cap how many recent commit subjects the config carries. */
 const MAX_RECENT_COMMITS = 8;
 /** Cap each recent commit entry to keep the request bounded even for long subjects. */
@@ -210,6 +234,46 @@ function projectSlug(cwd: string): string {
   return cwd.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase().slice(0, 64) || "workspace";
 }
 
+function firstUserText(parsed: OcxParsedRequest): string | undefined {
+  for (const msg of parsed.context.messages) {
+    if (msg.role !== "user") continue;
+    if (typeof msg.content === "string") return msg.content;
+    const first = msg.content.find(part => part.type === "text" && typeof part.text === "string");
+    if (first && first.type === "text") return first.text;
+  }
+  return undefined;
+}
+
+export function commandCodeSessionId(parsed: OcxParsedRequest): string {
+  if (parsed._commandCodeSessionId) return parsed._commandCodeSessionId;
+  // Shared prompt-cache cohorts intentionally do not identify one conversation. Keep them out
+  // of upstream session affinity or unrelated conversations can pin to the same worker.
+  const threadId = parsed._clientThreadId?.trim();
+  const replayId = parsed._reasoningReplayScope?.clientThreadId?.trim();
+  const cursorId = parsed._cursorConversationId?.trim();
+  const cacheKey = !parsed._promptCacheKeyIsSharedCohort ? parsed.options.promptCacheKey?.trim() : undefined;
+  const rootText = firstUserText(parsed);
+  const identity = threadId
+    ? ["thread", threadId]
+    : replayId
+      ? ["replay", replayId]
+      : cursorId
+        ? ["cursor", cursorId]
+        : cacheKey
+          ? ["cache", cacheKey]
+          : rootText
+            ? ["root", rootText]
+            : undefined;
+  const sessionId = !identity
+    ? randomUUID()
+    : (() => {
+      const hex = createHash("sha256").update(`command-code:${identity[0]}\0${identity[1]}`).digest("hex");
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+    })();
+  parsed._commandCodeSessionId = sessionId;
+  return sessionId;
+}
+
 interface GitWorkspaceInfo {
   isGitRepo: boolean;
   currentBranch: string;
@@ -219,6 +283,8 @@ interface GitWorkspaceInfo {
 }
 
 export const workspaceMetadataCache = new Map<string, { collectedAt: number; value: GitWorkspaceInfo }>();
+export const workspaceConfigCache = new Map<string, { collectedAt: number; value: Record<string, unknown>; sessionId?: string }>();
+export const SESSION_WORKSPACE_CONFIG_TTL_MS = 60 * 60_000;
 
 /**
  * Evict expired entries first, then the oldest live entry if at capacity.
@@ -245,6 +311,34 @@ export function pruneWorkspaceMetadataCache(now: number): void {
   }
 }
 
+export function pruneWorkspaceConfigCache(now: number): void {
+  for (const [key, entry] of workspaceConfigCache) {
+    if (!entry.sessionId && now - entry.collectedAt >= WORKSPACE_METADATA_TTL_MS) {
+      workspaceConfigCache.delete(key);
+    }
+  }
+  if (workspaceConfigCache.size >= MAX_WORKSPACE_METADATA_ENTRIES) {
+    let oldestKey: string | null = null;
+    let oldestAt = Infinity;
+    for (const [key, entry] of workspaceConfigCache) {
+      if (entry.sessionId) continue;
+      if (entry.collectedAt < oldestAt) {
+        oldestAt = entry.collectedAt;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey === null) {
+      for (const [key, entry] of workspaceConfigCache) {
+        if (entry.collectedAt < oldestAt) {
+          oldestAt = entry.collectedAt;
+          oldestKey = key;
+        }
+      }
+    }
+    if (oldestKey !== null) workspaceConfigCache.delete(oldestKey);
+  }
+}
+
 const execFile = promisify(execFileCallback);
 
 /** Best-effort git metadata for the upstream config contract; every read fails safe and stays off the event loop. */
@@ -281,32 +375,53 @@ async function gitWorkspaceInfo(cwd: string | undefined): Promise<GitWorkspaceIn
   return value;
 }
 
-async function commandCodeConfig(cwd: string | undefined): Promise<Record<string, unknown>> {
+export async function commandCodeConfig(cwd: string | undefined, sessionId?: string): Promise<Record<string, unknown>> {
+  const cacheKey = sessionId ? `${sessionId}:${cwd ?? ""}` : (cwd ?? "");
+  const now = Date.now();
+  const cached = cacheKey ? workspaceConfigCache.get(cacheKey) : undefined;
+  if (cacheKey) {
+    if (cached && (sessionId || now - cached.collectedAt < WORKSPACE_METADATA_TTL_MS)) return cached.value;
+  }
   let structure: string[] = [];
   if (cwd) {
     try {
-      // Iterate and stop after the cap instead of materializing every entry: a directory with a
-      // huge number of names must not stall the request path for 64 metadata rows.
+      // Keep only the lexicographically smallest entries within the bounded scan so filesystem
+      // enumeration order cannot change the selected prefix for the scanned portion.
       const dir = await opendir(cwd);
       try {
-        for await (const entry of dir) {
+        const entries = dir[Symbol.asyncIterator]();
+        for (let scanned = 0; scanned < MAX_WORKSPACE_STRUCTURE_SCAN_ENTRIES; scanned += 1) {
+          const next = await entries.next();
+          if (next.done) break;
+          const entry = next.value;
           if (entry.name.startsWith(".")) continue;
           structure.push(entry.name);
-          if (structure.length >= MAX_WORKSPACE_STRUCTURE_ENTRIES) break;
+          if (structure.length > MAX_WORKSPACE_STRUCTURE_ENTRIES) {
+            structure.sort();
+            structure.pop();
+          }
         }
       } finally {
         await dir.close().catch(() => undefined);
       }
     } catch { /* workspace metadata is optional */ }
   }
+  structure.sort();
   const git = await gitWorkspaceInfo(cwd);
-  return {
+  const value = {
     ...(cwd ? { workingDir: cwd } : {}),
-    date: new Date().toISOString().slice(0, 10),
+    date: sessionId && typeof cached?.value.date === "string"
+      ? cached.value.date
+      : new Date(now).toISOString().slice(0, 10),
     environment: process.platform,
     structure,
     ...git,
   };
+  if (cacheKey) {
+    if (!workspaceConfigCache.has(cacheKey)) pruneWorkspaceConfigCache(now);
+    workspaceConfigCache.set(cacheKey, { collectedAt: now, value, ...(sessionId ? { sessionId } : {}) });
+  }
+  return value;
 }
 
 function usage(value: unknown): OcxUsage | undefined {
@@ -451,9 +566,11 @@ export function createCommandCodeAdapter(provider: OcxProviderConfig): ProviderA
   const executor = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
   return {
     name: "command-code",
+    formatErrorBody: formatCommandCodeErrorBody,
     async buildRequest(parsed: OcxParsedRequest): Promise<AdapterRequest> {
       if (!provider.apiKey) throw new Error("Command Code credential missing — run ocx login command-code");
       const cwd = currentWorkingDirectory();
+      const sessionId = commandCodeSessionId(parsed);
       const tools = visibleTools(parsed);
       const toolNudge = buildNonOpenAIToolCatalogNudgeForTools(tools, parsed.options.toolChoice);
       const choiceInstruction = toolChoiceInstruction(parsed);
@@ -463,11 +580,8 @@ export function createCommandCodeAdapter(provider: OcxProviderConfig): ProviderA
         ...(choiceInstruction ? [choiceInstruction] : []),
       ].join("\n\n"), parsed.modelId);
       const reasoningEffort = supportedCommandCodeEffort(provider, parsed.modelId, parsed.options.reasoning);
-      const projectContext = provider.projectContext === "on"
-        ? await loadCommandCodeProjectContext(cwd)
-        : EMPTY_COMMAND_CODE_PROJECT_CONTEXT;
       const body = {
-        config: await commandCodeConfig(cwd), ...projectContext,
+        config: await commandCodeConfig(cwd, sessionId), memory: "", taste: null, skills: null,
         permissionMode: "standard", mode: "agent",
         params: {
           model: canonicalCommandCodeModelId(parsed.modelId),
@@ -490,7 +604,7 @@ export function createCommandCodeAdapter(provider: OcxProviderConfig): ProviderA
         "x-cli-environment": "production",
         "x-taste-learning": "false",
         "x-co-flag": "false",
-        "x-session-id": randomUUID(),
+        "x-session-id": sessionId,
       };
       if (cwd) headers["x-project-slug"] = projectSlug(cwd);
       return {

package/src/adapters/cursor/envelope-echo.ts

@@ -0,0 +1,162 @@
+/**
+ * External Cursor output quarantine (devlog 260826 gaps 10-11).
+ *
+ * Gap 10: flattened tool-result history can prime an external model to echo the
+ * "[Tool Result]" envelope as its own reply.
+ *
+ * Gap 11: a model can invent a blocked native-tool attempt in visible commentary
+ * even though the only real current-turn tool is the advertised Codex bridge.
+ *
+ * Both failures are observable only at the output boundary. The sniffers below
+ * hold a bounded prefix until it either diverges or proves the failure, allowing
+ * cursor.ts to retry before any invalid text reaches the client.
+ */
+
+const ECHO_MARKERS = ["[Tool Result]", "[Tool Error]", "[tool_result]"] as const;
+const MAX_SNIFF_BYTES = 40;
+const MAX_ROUTING_COMMENTARY_BYTES = 512;
+/** Aggregate quarantine cap: past this, flush and disarm. */
+const MAX_HOLD_BYTES = 8 * 1024;
+const encoder = new TextEncoder();
+
+export class CursorToolResultEchoError extends Error {
+  readonly code = "cursor_tool_result_echo";
+  constructor(marker: string) {
+    super(
+      "Cursor external model echoed the replayed tool-result envelope (\"" + marker
+      + "\") instead of continuing the task.",
+    );
+    this.name = "CursorToolResultEchoError";
+  }
+}
+
+export class CursorRoutingCommentaryError extends Error {
+  readonly code = "cursor_routing_commentary_hallucination";
+  constructor() {
+    super("Cursor external model invented a blocked tool surface before any tool call occurred.");
+    this.name = "CursorRoutingCommentaryError";
+  }
+}
+
+export type EchoSnifferDecision =
+  | { kind: "hold" }
+  | { kind: "flush" }
+  | { kind: "echo"; marker: string };
+
+/**
+ * Incremental envelope-prefix sniffer. Leading whitespace is tolerated so a
+ * marker copied after a newline is still caught.
+ */
+export class CursorEnvelopeEchoSniffer {
+  private buffered = "";
+  private byteCount = 0;
+  private done = false;
+
+  get settled(): boolean {
+    return this.done;
+  }
+
+  feed(textDelta: string): EchoSnifferDecision {
+    if (this.done) return { kind: "flush" };
+    this.buffered += textDelta;
+    this.byteCount += encoder.encode(textDelta).byteLength;
+    const probe = this.buffered.replace(/^\s+/, "");
+    for (const marker of ECHO_MARKERS) {
+      if (probe.startsWith(marker)) {
+        this.done = true;
+        return { kind: "echo", marker };
+      }
+    }
+    const stillPrefix = ECHO_MARKERS.some(marker =>
+      probe.length < marker.length && marker.startsWith(probe),
+    );
+    if (stillPrefix && this.byteCount <= MAX_SNIFF_BYTES && this.buffered.length < MAX_HOLD_BYTES) {
+      return { kind: "hold" };
+    }
+    this.done = true;
+    return { kind: "flush" };
+  }
+
+  finish(): EchoSnifferDecision {
+    if (this.done) return { kind: "flush" };
+    this.done = true;
+    return { kind: "flush" };
+  }
+}
+
+export type RoutingCommentaryDecision =
+  | { kind: "hold" }
+  | { kind: "flush" }
+  | { kind: "hallucination" };
+
+const ROUTING_NATIVE_TOOL_NAME = /\b(shell|read|grep|list|bash|filesystem)\b/giu;
+const ROUTING_TOOL_HINT =
+  /(?:\b(?:shell|read|grep|list|bash|filesystem)\b|exec_command|shell_command|브리지|네이티브\s*(?:셸|쉘))/iu;
+const ROUTING_FAILURE_OR_BRIDGE_CLAIM =
+  /(?:blocked|unavailable|interrupted|bridged|bridge|차단|중단|막혀)/iu;
+const ROUTING_REDIRECT_CLAIM =
+  /(?:exec_command|shell_command|\bexec\b|브리지|bridged|bridge|redirected|fallback|switch(?:ed|ing)?|host shell|전환|우회|통과(?:되|하)|다른\s*(?:도구|경로)|경로로)/iu;
+
+/**
+ * Quarantines the first line of code-mode / bridge output long enough to reject
+ * an impossible routing claim. It requires a failure or bridge claim plus either an
+ * explicit redirect to another execution surface or two distinct unadvertised
+ * native-tool names; a legitimate sentence such as "Shell is unavailable on
+ * this OS" therefore passes.
+ */
+export class CursorRoutingCommentarySniffer {
+  private buffered = "";
+  private byteCount = 0;
+  private done = false;
+
+  get settled(): boolean {
+    return this.done;
+  }
+
+  feed(textDelta: string): RoutingCommentaryDecision {
+    if (this.done) return { kind: "flush" };
+    this.buffered += textDelta;
+    this.byteCount += encoder.encode(textDelta).byteLength;
+    if (this.matchesHallucination()) {
+      this.done = true;
+      return { kind: "hallucination" };
+    }
+    const lineBreakCount = (this.buffered.match(/\n/gu) ?? []).length;
+    const hasRoutingHint = ROUTING_TOOL_HINT.test(this.buffered) || ROUTING_FAILURE_OR_BRIDGE_CLAIM.test(this.buffered);
+    const pendingFailureClaim =
+      ROUTING_TOOL_HINT.test(this.buffered)
+      && ROUTING_FAILURE_OR_BRIDGE_CLAIM.test(this.buffered)
+      && lineBreakCount < 2;
+    if (
+      this.byteCount < MAX_ROUTING_COMMENTARY_BYTES
+      && this.buffered.length < MAX_HOLD_BYTES
+      && (lineBreakCount === 0 || pendingFailureClaim)
+      && (hasRoutingHint || this.byteCount < 64)
+    ) {
+      return { kind: "hold" };
+    }
+    this.done = true;
+    return { kind: "flush" };
+  }
+
+  finish(): RoutingCommentaryDecision {
+    if (this.done) return { kind: "flush" };
+    this.done = true;
+    return this.matchesHallucination() ? { kind: "hallucination" } : { kind: "flush" };
+  }
+
+  private matchesHallucination(): boolean {
+    if (!ROUTING_FAILURE_OR_BRIDGE_CLAIM.test(this.buffered)) return false;
+    const nativeTools = new Set(
+      [...this.buffered.matchAll(ROUTING_NATIVE_TOOL_NAME)].map(match => match[1]?.toLowerCase()),
+    );
+    if (nativeTools.size === 0) return false;
+    return ROUTING_REDIRECT_CLAIM.test(this.buffered) || nativeTools.size >= 2;
+  }
+}
+
+export const CURSOR_ECHO_RETRY_CONTINUATION_TEXT =
+  "Your previous reply copied an internal tool-output record verbatim and was rejected. Continue the original task now: issue the next required tool call, or answer in your own words if no tool is needed.";
+
+export const CURSOR_ROUTING_COMMENTARY_RETRY_TEXT =
+  "Your previous reply claimed an execution-surface failure that did not occur and was rejected. Use the current tool catalog as ground truth. Perform the requested operation through the advertised execution tool now, with no commentary before the tool call.";

package/src/adapters/cursor/live-transport.ts

@@ -75,6 +75,7 @@ import { desktopDepsFromConfig } from "./native-exec-desktop";
 import {
   buildCursorToolDefinitions,
   cursorRequestAdvertisesApplyPatch,
+  cursorRequestUsesCodeMode,
   cursorRequestHasShellAlias,
   cursorToolArgNormalizeSchema,
   cursorToolWireName,
@@ -108,7 +109,7 @@ const CURSOR_STREAM_SILENCE_FAIL_MS = 30_000;
  * for this long is equally stuck — the server is alive but the turn is not progressing.
  * Reset on every decoded frame that is not liveness-only.
  */
-const CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS = 90_000;
+const CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS = 180_000;
 /**
  * After `turnEnded` is decoded, the application turn is complete. A server that keeps
  * HTTP/2 open past this point cannot hold the turn hostage (senpi #1062): we close our side
@@ -646,6 +647,7 @@ class LiveCursorTransport implements CursorTransport {
     this.execContext = {
       ...this.execContext,
       clientToolDefs,
+      codeMode: cursorRequestUsesCodeMode(request.tools, request.toolChoice),
       rejectNativeFileMutations: cursorRequestAdvertisesApplyPatch(request.tools, request.toolChoice),
       structuredEditAvailable: syntheticStructuredEditToolNames.size > 0,
     };
@@ -1509,7 +1511,7 @@ class LiveCursorTransport implements CursorTransport {
     const awaitedNativeArgsBeforeMapping = update?.case === "toolCallCompleted"
       && state.openToolCalls.get(update.value.callId)?.awaitingNativeArgs === true;
     const mapped = mapCursorProtobufServerMessage(message, state);
-    if (mapped.some(event => event.type === "text")) this.sawAssistantText = true;
+    if (mapped.some(event => event.type === "text" || event.type === "thinking" || event.type === "tool_call_start" || event.type === "tool_call_end")) this.sawAssistantText = true;
     const beganAwaitingNativeClientToolArgs = update?.case === "toolCallCompleted"
       && !awaitedNativeArgsBeforeMapping
       && state.openToolCalls.get(update.value.callId)?.awaitingNativeArgs === true;

package/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 { nativeLocalExecDisabledMessage, type CursorNativeExecPolicyContext } from "./native-exec-policy";
 
 const MAX_GREP_FILES = 500;
 const MAX_GREP_RESULTS = 200;
@@ -46,14 +47,14 @@ 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 =
-  "Cursor-native filesystem tools are not executed locally. Use a catalog tool for this work: `shell_command` / `exec_command` (or the listed `mcp_opencodex-responses_*` display alias) with host-shell-safe equivalents: POSIX (`cat`, `head`, `ls`, `rg`, `grep`) or Windows PowerShell (`Get-Content`, `Get-ChildItem`, `Select-String`); use `apply_patch` for file edits.";
+export const NATIVE_LOCAL_EXEC_DISABLED =
+  "Re-issue this operation NOW through the catalog shell tool (`shell_command` / `exec_command`, or the listed `mcp_opencodex-responses_*` display alias) with the host-shell-safe equivalent: POSIX (`cat`, `head`, `ls`, `rg`, `grep`) or Windows PowerShell (`Get-Content`, `Get-ChildItem`, `Select-String`); use `apply_patch` for file edits. Do NOT narrate this redirect, do NOT comment on tool availability, and do NOT re-announce the task — just make the bridge call.";
 
-export function rejectReadExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectReadExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): 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: nativeLocalExecDisabledMessage(opts) }) },
   }));
 }
 
@@ -98,13 +99,13 @@ export function rejectWriteExecForApplyPatch(execMsg: ExecServerMessage, structu
   }));
 }
 
-export function rejectWriteExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectWriteExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): 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: `${nativeLocalExecDisabledMessage(opts)} No file was changed.` }),
     },
   }));
 }
@@ -147,13 +148,13 @@ export function rejectDeleteExecForApplyPatch(execMsg: ExecServerMessage, struct
   }));
 }
 
-export function rejectDeleteExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectDeleteExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): 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: `${nativeLocalExecDisabledMessage(opts)} No file was changed.` }),
     },
   }));
 }
@@ -188,11 +189,11 @@ export function deleteExec(execMsg: ExecServerMessage): Uint8Array {
   }
 }
 
-export function rejectLsExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectLsExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): 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: nativeLocalExecDisabledMessage(opts) }) },
   }));
 }
 
@@ -256,8 +257,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, opts: CursorNativeExecPolicyContext = {}): Uint8Array {
+  return grepError(execMsg, nativeLocalExecDisabledMessage(opts));
 }
 
 export function grepExec(execMsg: ExecServerMessage): Uint8Array {

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

@@ -1,19 +1,17 @@
 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 CursorNativeExecPolicyContext } from "./native-exec-policy";
 
 export interface CursorNativeNetworkDeps {
   fetch?: typeof fetch;
 }
 
-const NATIVE_FETCH_DISABLED =
-  "Cursor-native fetch is not executed locally. Use the Codex shell bridge tool `shell_command` (aliases: `exec_command`, `mcp_opencodex-responses_shell_command`, `mcp_opencodex-responses_exec_command`) with curl or wget.";
-
-export function rejectFetchExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectFetchExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): 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: nativeFetchDisabledMessage(opts) }) },
   }));
 }
 

package/src/adapters/cursor/native-exec-policy.ts

@@ -0,0 +1,47 @@
+export interface CursorNativeExecPolicyContext {
+  codeMode?: boolean;
+}
+
+export function nativeLocalExecDisabledMessage(opts: CursorNativeExecPolicyContext = {}): string {
+  if (opts.codeMode) {
+    return (
+      "Cursor-native local tools are policy-redirected to the Codex bridge for this request; this is not a permissions denial. "
+      + "Use the top-level `exec` tool and call nested helpers inside its JavaScript body as `await tools.<name>(args)` "
+      + "(for example `await tools.exec_command({cmd: \"ls\"})`, `await tools.apply_patch(input)`, or another helper listed in `ALL_TOOLS`). "
+      + "Do not call `shell_command` or `exec_command` at the top level in code mode."
+    );
+  }
+  return (
+    "Re-issue this operation NOW through the catalog shell tool (`shell_command` / `exec_command`, or the listed `mcp_opencodex-responses_*` display alias) with the host-shell-safe equivalent: POSIX (`cat`, `head`, `ls`, `rg`, `grep`) or Windows PowerShell (`Get-Content`, `Get-ChildItem`, `Select-String`); use `apply_patch` for file edits. Do NOT narrate this redirect, do NOT comment on tool availability, and do NOT re-announce the task — just make the bridge call."
+  );
+}
+
+export function nativeFetchDisabledMessage(opts: CursorNativeExecPolicyContext = {}): string {
+  if (opts.codeMode) {
+    return (
+      "Cursor-native fetch is policy-redirected to the Codex bridge for this request; this is not a permissions denial. "
+      + "Use the top-level `exec` tool and call a nested shell helper inside its JavaScript body as `await tools.exec_command({cmd: \"curl ...\"})` "
+      + "(or another helper listed in `ALL_TOOLS`). Do not call `shell_command` or `exec_command` at the top level in code mode."
+    );
+  }
+  return (
+    "Re-issue this fetch NOW through the catalog shell tool `shell_command` (aliases: `exec_command`, `mcp_opencodex-responses_shell_command`, `mcp_opencodex-responses_exec_command`) with curl or wget. Do NOT narrate this redirect or comment on tool availability — just make the bridge call."
+  );
+}
+
+export function nativeShellDisabledMessage(opts: CursorNativeExecPolicyContext = {}): string {
+  if (opts.codeMode) {
+    return (
+      "Cursor-native shell is policy-redirected to the Codex bridge for this request; this is not a permissions denial. "
+      + "Use the top-level `exec` tool and call a nested shell helper inside its JavaScript body as `await tools.exec_command({cmd: \"...\"})` "
+      + "(or another helper listed in `ALL_TOOLS`). Do not call `shell_command` or `exec_command` at the top level in code mode."
+    );
+  }
+  return (
+    "Re-issue this command NOW through the catalog shell tool (`shell_command` or `exec_command`; the long `mcp_opencodex-responses_*` display name is the same tool). "
+    + "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. "
+    + "Do NOT narrate this redirect, do NOT comment on tool availability, and do NOT re-announce the task — just make the bridge call."
+  );
+}