@bitkyc08/opencodex 2.7.39 → 2.7.40-preview.20260725

package/src/adapters/cursor/protobuf-request.ts

@@ -1,4 +1,4 @@
-import { create, toBinary } from "@bufbuild/protobuf";
+import { create, fromBinary, toBinary, toJson } from "@bufbuild/protobuf";
 import { fromJson, type JsonValue } from "@bufbuild/protobuf";
 import { ValueSchema } from "@bufbuild/protobuf/wkt";
 import type { OcxAssistantContentPart, OcxMessage, OcxToolResultMessage } from "../../types";
@@ -7,6 +7,7 @@ import type { CursorRunRequest } from "./types";
 import { isCursorExternalWireModel } from "./discovery";
 import { debugProviderDiagnostic } from "../../lib/debug";
 import { storeCursorBlob } from "./native-exec";
+import { estimateTokens } from "../../lib/token-estimate";
 import {
   AgentClientMessageSchema,
   AgentConversationTurnStructureSchema,
@@ -23,6 +24,7 @@ import {
   McpToolResultContentItemSchema,
   McpToolResultSchema,
   McpToolsSchema,
+  type McpToolDefinition,
   ModelDetailsSchema,
   RequestedModelSchema,
   RequestedModel_ModelParameterbytesSchema,
@@ -76,13 +78,20 @@ function buildRequestContext() {
   });
 }
 
-function jsonBlob(value: unknown): Uint8Array {
-  return encoder.encode(JSON.stringify(value));
+function jsonBlob(value: unknown): { data: Uint8Array; serialized: string } {
+  const serialized = JSON.stringify(value);
+  return { data: encoder.encode(serialized), serialized };
 }
 
 type StoredRootBlob = {
   id: Uint8Array;
   byteLength: number;
+  /**
+   * The exact JSON handed to storeCursorBlob(). Retained so a token estimate can read
+   * what the wire actually carries without re-serializing — and without drifting from
+   * it after pruning or truncation (#373).
+   */
+  serialized: string;
   role: "system" | "user" | "assistant" | "toolResult";
   messageIndex?: number;
   /** Original JSON text payload used when an active tool result must be truncated to fit. */
@@ -94,10 +103,11 @@ function storedRootBlob(
   role: StoredRootBlob["role"],
   opts?: { messageIndex?: number; text?: string },
 ): StoredRootBlob {
-  const data = jsonBlob(value);
+  const { data, serialized } = jsonBlob(value);
   return {
     id: storeCursorBlob(data),
     byteLength: data.byteLength,
+    serialized,
     role,
     ...(opts?.messageIndex !== undefined ? { messageIndex: opts.messageIndex } : {}),
     ...(opts?.text !== undefined ? { text: opts.text } : {}),
@@ -164,6 +174,8 @@ function rootPromptMessages(request: CursorRunRequest): {
   ids: Uint8Array[];
   byteLength: number;
   historyMessageStart: number;
+  /** Serialized text of the roots that survived pruning, in wire order. */
+  serialized: string[];
 } {
   const entries = systemPromptBlobs(request);
   const systemEntryCount = entries.length;
@@ -173,6 +185,7 @@ function rootPromptMessages(request: CursorRunRequest): {
       ids: entries.map(entry => entry.id),
       byteLength: entries.reduce((sum, entry) => sum + entry.byteLength, 0),
       historyMessageStart: 0,
+      serialized: entries.map(entry => entry.serialized),
     };
   }
 
@@ -289,6 +302,7 @@ function rootPromptMessages(request: CursorRunRequest): {
     ids: selected.map(entry => entry.id),
     byteLength: selected.reduce((sum, entry) => sum + entry.byteLength, 0),
     historyMessageStart,
+    serialized: selected.map(entry => entry.serialized),
   };
 }
 
@@ -503,7 +517,46 @@ export function activePromptText(request: CursorRunRequest): string {
   return last?.role === "tool" ? last.content : "";
 }
 
-export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
+/**
+ * The model-visible text of one finalized tool definition. The schema travels as
+ * packed protobuf bytes, so it is decoded back to JSON to be counted the way the
+ * model reads it.
+ */
+function modelVisibleToolText(definition: McpToolDefinition): string {
+  let inputSchema: unknown;
+  try {
+    inputSchema = toJson(ValueSchema, fromBinary(ValueSchema, definition.inputSchema));
+  } catch {
+    inputSchema = undefined;
+  }
+  return JSON.stringify({
+    name: definition.toolName || definition.name,
+    description: definition.description,
+    ...(inputSchema !== undefined ? { inputSchema } : {}),
+  });
+}
+
+export interface PreparedCursorRunRequest {
+  bytes: Uint8Array;
+  /** Only present when the caller asked for it; see prepareCursorRunRequest(). */
+  estimatedInputTokens?: number;
+}
+
+/**
+ * Build the wire payload once, and optionally derive a token estimate from the very
+ * same roots, action text, and tool definitions that produced it.
+ *
+ * Cursor only reports absolute context size in checkpoint frames, which live in a
+ * process-local map — so after a restart a turn with no checkpoint reports
+ * inputTokens=0 and Codex sees an almost-empty context (#373). The estimate fills
+ * that gap. Deriving it here, rather than from the original request, is what keeps
+ * it honest: history the pruner dropped and tools the filter removed are already
+ * gone by this point.
+ */
+export function prepareCursorRunRequest(
+  request: CursorRunRequest,
+  options?: { estimateInputTokens?: boolean },
+): PreparedCursorRunRequest {
   const rawText = activePromptText(request);
   const lastRole = request.messages.at(-1)?.role;
   const text = lastRole === "user" || lastRole === "developer"
@@ -536,6 +589,10 @@ export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
   const rootPromptMessagesState = rootPromptMessages(request);
   const rootPromptMessageIds = rootPromptMessagesState.ids;
   const turnIds = conversationTurns(request, rootPromptMessagesState.historyMessageStart);
+  // Hoisted out of the mcp_tools spread below so the estimate can read the same
+  // filtered definitions the wire carries. Both helpers are pure.
+  const visibleTools = cursorToolsForActivePrompt(request.tools, rawText, request.toolChoice);
+  const mcpToolDefs = buildCursorToolDefinitions(visibleTools, request.toolChoice);
   debugProviderDiagnostic("cursor", "run-request", {
     wireModel: request.modelId,
     action: actionCase,
@@ -598,15 +655,29 @@ export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
     // the event-state `clientToolNames` use (live-transport.ts). Advertising the raw `request.tools`
     // here would let mcp_tools expose a tool that the event state does not recognize for a generic
     // tool-count prompt, so a call to it would be rejected as an unknown Responses tool.
-    ...(() => {
-      const visibleTools = cursorToolsForActivePrompt(request.tools, activePromptText(request), request.toolChoice);
-      const mcpToolDefs = buildCursorToolDefinitions(visibleTools, request.toolChoice);
-      return mcpToolDefs.length > 0 ? { mcpTools: create(McpToolsSchema, { mcpTools: mcpToolDefs }) } : {};
-    })(),
+    ...(mcpToolDefs.length > 0 ? { mcpTools: create(McpToolsSchema, { mcpTools: mcpToolDefs }) } : {}),
   });
 
   const message = create(AgentClientMessageSchema, {
     message: { case: "runRequest", value: runRequest },
   });
-  return toBinary(AgentClientMessageSchema, message);
+  const bytes = toBinary(AgentClientMessageSchema, message);
+  if (!options?.estimateInputTokens) return { bytes };
+
+  // Same instances that produced `bytes`, so the estimate cannot count history or
+  // tools the payload dropped — the defect that blocked PR #376.
+  const modelVisibleParts = [
+    ...rootPromptMessagesState.serialized,
+    ...(actionCase === "userMessageAction" ? [text] : []),
+    ...mcpToolDefs.map(modelVisibleToolText),
+  ];
+  return {
+    bytes,
+    estimatedInputTokens: estimateTokens(modelVisibleParts.join("\n"), request.modelId),
+  };
+}
+
+/** Back-compat wrapper: callers that only need the wire bytes. */
+export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
+  return prepareCursorRunRequest(request).bytes;
 }

package/src/adapters/cursor/request-builder.ts

@@ -15,8 +15,10 @@ import {
   cursorMcpToolEncodedSize,
   cursorMcpToolsEncodedSize,
   cursorToolAllowedByChoice,
+  cursorToolChoiceAliases,
   cursorToolWireName,
   cursorToolsForActivePrompt,
+  isBareCodexShellBridgeTool,
 } from "./tool-definitions";
 import { lookupCursorThreadConversation } from "./thread-continuity";
 
@@ -35,10 +37,18 @@ function explicitlySelectedNames(choice: OcxToolChoice | undefined): Set<string>
 }
 
 function toolPriority(tool: OcxTool, selectedNames: ReadonlySet<string>): number {
-  if (toolChoiceAliases(tool).some(name => selectedNames.has(name))) return 0;
-  if (tool.loadedFromToolSearch) return 1;
-  if (!tool.namespace) return 2;
-  return 3;
+  // Shell bridge and apply_patch outrank unrelated allowed_tools entries so a large
+  // selected filler cannot starve the Codex execution path during truncation (#399).
+  if (isBareCodexShellBridgeTool(tool)) return 0;
+  if (!tool.namespace && tool.name === "apply_patch") return 1;
+  if (cursorToolChoiceAliases(tool).some(name => selectedNames.has(name))) return 2;
+  if (tool.loadedFromToolSearch) return 3;
+  if (!tool.namespace) return 4;
+  return 5;
+}
+
+function isPinnedCursorTool(tool: OcxTool, selectedNames: ReadonlySet<string>): boolean {
+  return toolPriority(tool, selectedNames) <= 2;
 }
 
 /**
@@ -50,7 +60,8 @@ export function applyCursorToolBudget(
   tools: readonly OcxTool[] | undefined,
   toolChoice: OcxToolChoice | undefined,
 ): CursorToolBudgetResult {
-  const eligible = (tools ?? []).filter(tool => cursorToolAllowedByChoice(tool, toolChoice));
+  const catalog = tools ?? [];
+  const eligible = catalog.filter(tool => cursorToolAllowedByChoice(tool, toolChoice, catalog));
   if (
     eligible.length <= CURSOR_TOOL_COUNT_LIMIT
     && cursorMcpToolsEncodedSize(eligible, toolChoice) <= CURSOR_TOOL_BYTES_LIMIT
@@ -64,15 +75,28 @@ export function applyCursorToolBudget(
   const keptSet = new Set<OcxTool>();
   let keptBytes = 0;
 
-  for (const candidate of candidates) {
-    if (kept.length >= CURSOR_TOOL_COUNT_LIMIT) continue;
+  const tryKeep = (tool: OcxTool): boolean => {
+    if (keptSet.has(tool) || kept.length >= CURSOR_TOOL_COUNT_LIMIT) return keptSet.has(tool);
     // Repeated protobuf message fields serialize as concatenated tag/length/value entries,
     // so each one-entry wrapper size is the exact additive contribution to McpTools.
-    const candidateBytes = cursorMcpToolEncodedSize(candidate.tool, toolChoice);
-    if (keptBytes + candidateBytes > CURSOR_TOOL_BYTES_LIMIT) continue;
-    kept.push(candidate.tool);
-    keptSet.add(candidate.tool);
+    const candidateBytes = cursorMcpToolEncodedSize(tool, toolChoice);
+    if (keptBytes + candidateBytes > CURSOR_TOOL_BYTES_LIMIT) return false;
+    kept.push(tool);
+    keptSet.add(tool);
     keptBytes += candidateBytes;
+    return true;
+  };
+
+  // Phase 1: selected tools + shell bridge + apply_patch (priority <= 2).
+  // Pins are admitted before filler so a crowded catalog cannot drop the Codex execution path (#399).
+  for (const candidate of candidates) {
+    if (!isPinnedCursorTool(candidate.tool, selectedNames)) continue;
+    tryKeep(candidate.tool);
+  }
+
+  // Phase 2: remaining tools by priority.
+  for (const candidate of candidates) {
+    tryKeep(candidate.tool);
   }
 
   return {

package/src/adapters/cursor/tool-definitions.ts

@@ -1,27 +1,32 @@
 import { create, fromJson, toBinary, type JsonValue } from "@bufbuild/protobuf";
 import { ValueSchema } from "@bufbuild/protobuf/wkt";
 import type { OcxRequestOptions, OcxTool } from "../../types";
-import { namespacedToolName } from "../../types";
+import { namespacedToolName, toolChoiceAliases } from "../../types";
 import { McpToolDefinitionSchema, McpToolsSchema, type McpToolDefinition } from "./gen/agent_pb";
 
 export const OCX_RESPONSES_TOOL_PROVIDER = "opencodex-responses";
 export const CODEX_EXEC_COMMAND_TOOL = "exec_command";
+export const CODEX_SHELL_COMMAND_TOOL = "shell_command";
 export const CODEX_APPLY_PATCH_TOOL = "apply_patch";
 export const CURSOR_EXEC_COMMAND_TOOL = CODEX_EXEC_COMMAND_TOOL;
-export const CURSOR_SHELL_ALIAS_SYSTEM_NOTE = 'Shell commands use the `exec_command` tool with JSON arguments like {"cmd":"..."}.';
-export const CURSOR_SHELL_ALIAS_USER_HINT = "Use exec_command for this shell command.";
+export const CODEX_SHELL_BRIDGE_TOOL_NAMES = [CODEX_EXEC_COMMAND_TOOL, CODEX_SHELL_COMMAND_TOOL] as const;
+export const CURSOR_SHELL_ALIAS_SYSTEM_NOTE =
+  'Shell commands use the Codex shell bridge tool shown in this turn\'s catalog (`shell_command` or `exec_command`) with JSON arguments like {"cmd":"..."}. The long `mcp_opencodex-responses_*` display name is the same tool. Prefer it over Cursor-native Shell; never say native shell is blocked.';
+export const CURSOR_SHELL_ALIAS_USER_HINT =
+  "Use the Codex shell bridge tool listed this turn (`shell_command` or `exec_command`, including the long `mcp_opencodex-responses_*` name). Prefer that bridge over Cursor-native Shell/Read. Never say phrases like \"Native shell access is blocked\" or \"Shell access is blocked\" — silently use the bridge unless that bridge tool itself fails.";
 const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
 
 export const CURSOR_GENERIC_TOOL_USE_USER_HINT = [
-  "For generic tool-use/count demos, satisfy the request with repeated `exec_command` calls for harmless commands.",
-  "`exec_command` is the Codex Responses bridge exec tool exposed through Cursor's tool protocol; do not describe it as an external MCP server tool.",
+  "For generic tool-use/count demos, satisfy the request with repeated Codex shell bridge calls (`shell_command` or `exec_command`) for harmless commands.",
+  "`shell_command` / `exec_command` are the Codex Responses shell bridge exposed through Cursor's tool protocol; do not describe them as an external MCP server tool.",
   "Do not use `run_shell` unless this turn's tool catalog lists it.",
-  "A request for N tools means N separate `exec_command` invocations/results; never satisfy it with one chained shell command such as `cmd1 && cmd2`.",
-  "For independent read-only or output-only commands, emit all requested `exec_command` calls in the same response before waiting when the runtime supports parallel tool calls.",
+  "A request for N tools means N separate shell-bridge invocations/results; never satisfy it with one chained shell command such as `cmd1 && cmd2`.",
+  "For independent read-only or output-only commands, emit all requested shell-bridge calls in the same response before waiting when the runtime supports parallel tool calls.",
   "The Cursor bridge may suspend after the first returned bridge tool call, so emit sibling calls together before any result is needed.",
-  "If parallel emission is unavailable, continue with separate `exec_command` calls until the requested count has returned.",
+  "If parallel emission is unavailable, continue with separate shell-bridge calls until the requested count has returned.",
   "Do not use `tool_search`, external MCP, or resource discovery just to pad the count unless explicitly asked.",
   "Do not suggest or switch to neighboring-agent tools such as `Grep`, `Read`, `Glob`, `Bash`, or `LS` unless this turn's catalog lists those exact names.",
+  "Never tell the user that shell or read access is blocked, disabled, or denied unless the Codex shell bridge tool itself fails. Do not narrate Cursor-native Shell/Read routing.",
 ].join(" ");
 
 export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
@@ -38,8 +43,91 @@ export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
   additionalProperties: false,
 } as const;
 
+/**
+ * Responses/Codex-side schema used ONLY for arg-key normalization after Cursor returns a call.
+ * Cursor models are trained to emit `cmd`; Codex `shell_command` / `exec_command` validate
+ * `command`. Keeping `cmd` out of this schema lets `normalizeArgKeys` rewrite `cmd` → `command`.
+ */
+export const CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA = {
+  type: "object",
+  properties: {
+    command: { type: "string", description: "Shell command to execute." },
+    workdir: { type: "string", description: "Working directory for the command. Defaults to the turn cwd." },
+    shell: { type: "string", description: "Shell binary to launch. Defaults to the user's default shell." },
+    tty: { type: "boolean", description: "True allocates a PTY for the command; false or omitted uses plain pipes." },
+    yield_time_ms: { type: "number", description: "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms." },
+    max_output_tokens: { type: "number", description: "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy." },
+    max_output_chars: { type: "number", description: "Output character budget when the Responses tool uses chars instead of tokens." },
+  },
+  required: ["command"],
+} as const;
+
+export function isCodexShellBridgeToolName(name: string): boolean {
+  return (CODEX_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).includes(name);
+}
+
+/**
+ * Direct key lookup, then shell_command/exec_command sibling aliases when the key is a bridge name.
+ * Used for catalog admission, schema normalize maps, and Responses name maps (#399).
+ */
+export function resolveShellBridgeAliasKey<T>(
+  key: string,
+  lookup: (name: string) => T | undefined,
+): T | undefined {
+  const direct = lookup(key);
+  if (direct !== undefined) return direct;
+  if (!isCodexShellBridgeToolName(key)) return undefined;
+  for (const alias of CODEX_SHELL_BRIDGE_TOOL_NAMES) {
+    if (alias === key) continue;
+    const hit = lookup(alias);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+
+export function cursorToolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
+  const aliases = new Set(toolChoiceAliases(tool));
+  if (isBareCodexShellBridgeTool(tool)) {
+    for (const alias of CODEX_SHELL_BRIDGE_TOOL_NAMES) aliases.add(alias);
+  }
+  return [...aliases];
+}
+
+function catalogHasBareCodexShellBridge(
+  catalog: readonly Pick<OcxTool, "namespace" | "name">[],
+): boolean {
+  return catalog.some(isBareCodexShellBridgeTool);
+}
+
+/**
+ * Catalog-aware tool_choice matching for Cursor.
+ * When a bare Codex shell bridge is in the catalog, raw `shell_command` / `exec_command`
+ * choices select only that bridge (never a namespaced remote with the same raw name).
+ * When no bare bridge exists, raw bridge names may select a namespaced tool by raw name.
+ * Explicit wire names (`mcp__remote__exec_command`) always match the namespaced tool.
+ */
+function cursorToolChoiceMatches(
+  tool: Pick<OcxTool, "namespace" | "name">,
+  choiceName: string,
+  catalog: readonly Pick<OcxTool, "namespace" | "name">[],
+): boolean {
+  if (isCodexShellBridgeToolName(choiceName)) {
+    if (catalogHasBareCodexShellBridge(catalog)) {
+      return isBareCodexShellBridgeTool(tool);
+    }
+    return tool.name === choiceName || cursorToolWireName(tool) === choiceName;
+  }
+  if (tool.name === choiceName || cursorToolWireName(tool) === choiceName) return true;
+  return cursorToolChoiceAliases(tool).includes(choiceName);
+}
+
+export function isBareCodexShellBridgeTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
+  return !tool.namespace && isCodexShellBridgeToolName(tool.name);
+}
+
+/** @deprecated Prefer isBareCodexShellBridgeTool; kept for older call sites/tests. */
 function isBareCodexExecCommandTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
-  return !tool.namespace && tool.name === CODEX_EXEC_COMMAND_TOOL;
+  return isBareCodexShellBridgeTool(tool);
 }
 
 export function cursorRequestHasShellAlias(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined): boolean {
@@ -50,7 +138,8 @@ export function cursorRequestAdvertisesApplyPatch(
   tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
   toolChoice?: OcxRequestOptions["toolChoice"],
 ): boolean {
-  return tools?.some(tool => !tool.namespace && tool.name === CODEX_APPLY_PATCH_TOOL && tool.freeform === true && cursorToolAllowedByChoice(tool, toolChoice)) ?? false;
+  const catalog = tools ?? [];
+  return catalog.some(tool => !tool.namespace && tool.name === CODEX_APPLY_PATCH_TOOL && tool.freeform === true && cursorToolAllowedByChoice(tool, toolChoice, catalog));
 }
 
 export function cursorToolWireName(tool: Pick<OcxTool, "namespace" | "name">): string {
@@ -60,8 +149,9 @@ export function cursorToolWireName(tool: Pick<OcxTool, "namespace" | "name">): s
 /**
  * Cursor's harness shows MCP tools to the model as `mcp_<providerIdentifier>_<toolName>`; models
  * sometimes call that display name verbatim instead of the advertised short name (live 20:41/21:00
- * sessions: `mcp_opencodex-responses_exec_command`). Fold the display prefix back to the advertised
- * wire name so both spellings resolve to the same client tool instead of "unknown Responses tool".
+ * sessions: `mcp_opencodex-responses_exec_command` / `mcp_opencodex-responses_shell_command`).
+ * Fold the display prefix back to the advertised wire name, and treat `shell_command` /
+ * `exec_command` as the same Codex shell bridge, so alias thrash does not become "tool not found".
  */
 const CURSOR_MCP_DISPLAY_PREFIX = `mcp_${OCX_RESPONSES_TOOL_PROVIDER}_`;
 
@@ -71,15 +161,60 @@ export function normalizeCursorWireName(name: string): string {
 
 export function responsesToolNameFromCursorWire(name: string, cursorToolNameMap?: ReadonlyMap<string, string>): string {
   const normalized = normalizeCursorWireName(name);
-  return cursorToolNameMap?.get(normalized) ?? normalized;
+  if (!cursorToolNameMap) return normalized;
+  return resolveShellBridgeAliasKey(normalized, alias => cursorToolNameMap.get(alias)) ?? normalized;
 }
 
+/** Schema advertised to Cursor for this tool (may use Cursor-preferred field names like `cmd`). */
 export function cursorToolInputSchema(tool: OcxTool): unknown {
   return isBareCodexExecCommandTool(tool) ? CURSOR_EXEC_COMMAND_INPUT_SCHEMA : (tool.parameters ?? {});
 }
 
+/**
+ * Schema used to normalize completed Cursor tool args back to Responses/Codex field names.
+ * Must NOT reuse `cursorToolInputSchema` for the shell bridge: advertising `cmd` while also
+ * treating `cmd` as canonical prevents the `cmd` → `command` rewrite Codex requires (#399).
+ */
+export function cursorToolArgNormalizeSchema(tool: OcxTool): unknown {
+  if (isBareCodexShellBridgeTool(tool)) {
+    return shellBridgeArgNormalizeSchema(tool);
+  }
+  return tool.parameters ?? {};
+}
+
+function shellBridgeArgNormalizeSchema(tool: OcxTool): unknown {
+  const parameters = tool.parameters;
+  if (!parameters || typeof parameters !== "object") return CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA;
+  const base = parameters as Record<string, unknown>;
+  const rawProps = base.properties && typeof base.properties === "object"
+    ? { ...(base.properties as Record<string, unknown>) }
+    : {};
+  const required = Array.isArray(base.required) ? [...base.required as unknown[]] : [];
+  const requiresCommand = required.includes("command") || "command" in rawProps;
+  const requiresCmd = required.includes("cmd") || "cmd" in rawProps;
+  const shouldRewriteCmdToCommand = tool.name === CODEX_SHELL_COMMAND_TOOL || requiresCommand;
+
+  if (!shouldRewriteCmdToCommand && requiresCmd) {
+    return parameters;
+  }
+
+  // Drop Cursor-preferred aliases so normalizeArgKeys can rewrite them to Responses keys.
+  delete rawProps.cmd;
+  const properties = {
+    ...CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA.properties,
+    ...rawProps,
+    command: rawProps.command ?? CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA.properties.command,
+  };
+  return {
+    ...base,
+    type: "object",
+    properties,
+    required: requiresCommand ? required : ["command"],
+  };
+}
+
 function activeTextMentionsExecCommand(text: string): boolean {
-  return /\bexec_command\b/i.test(text);
+  return /\b(?:exec_command|shell_command)\b/i.test(text);
 }
 
 function looksLikeShellCommandRequest(text: string): boolean {
@@ -127,9 +262,9 @@ function cursorGenericToolUseHint(text: string): string {
   const count = requestedCursorToolUseCount(text);
   if (!count) return CURSOR_GENERIC_TOOL_USE_USER_HINT;
   return [
-    `This turn requests ${count} tool uses: emit exactly ${count} separate \`exec_command\` function calls/results.`,
-    `One \`exec_command\` containing chained commands counts as 1 tool call, not ${count}.`,
-    `Prefer one parallel tool-call batch containing all ${count} independent \`exec_command\` calls before waiting for results.`,
+    `This turn requests ${count} tool uses: emit exactly ${count} separate Codex shell bridge function calls/results (\`shell_command\` or \`exec_command\`).`,
+    `One shell-bridge call containing chained commands counts as 1 tool call, not ${count}.`,
+    `Prefer one parallel tool-call batch containing all ${count} independent shell-bridge calls before waiting for results.`,
     CURSOR_GENERIC_TOOL_USE_USER_HINT,
   ].join(" ");
 }
@@ -176,7 +311,8 @@ export function cursorToolsForActivePrompt<T extends Pick<OcxTool, "namespace" |
 ): readonly T[] | undefined {
   if (!shouldUseNativeExecOnlyForGenericToolUse(tools, activeText)) return tools;
   const execTools = tools?.filter(isBareCodexExecCommandTool);
-  if (execTools?.length && !execTools.some(tool => cursorToolAllowedByChoice(tool, toolChoice))) return tools;
+  const catalog = tools ?? [];
+  if (execTools?.length && !execTools.some(tool => cursorToolAllowedByChoice(tool, toolChoice, catalog))) return tools;
   return execTools && execTools.length > 0 ? execTools : tools;
 }
 
@@ -199,13 +335,17 @@ export function appendCursorShellAliasHint(
   return `${text}${text.endsWith("\n") ? "\n" : "\n\n"}${CURSOR_SHELL_ALIAS_USER_HINT}`;
 }
 
-export function cursorToolAllowedByChoice(tool: Pick<OcxTool, "namespace" | "name">, toolChoice: OcxRequestOptions["toolChoice"] | undefined): boolean {
+export function cursorToolAllowedByChoice(
+  tool: Pick<OcxTool, "namespace" | "name">,
+  toolChoice: OcxRequestOptions["toolChoice"] | undefined,
+  catalog: readonly Pick<OcxTool, "namespace" | "name">[] = [tool],
+): boolean {
   if (!toolChoice || toolChoice === "auto" || toolChoice === "required") return true;
   if (toolChoice === "none") return false;
   if ("allowedTools" in toolChoice) {
-    return toolChoice.allowedTools.includes(tool.name) || toolChoice.allowedTools.includes(cursorToolWireName(tool));
+    return toolChoice.allowedTools.some(choiceName => cursorToolChoiceMatches(tool, choiceName, catalog));
   }
-  return tool.name === toolChoice.name || cursorToolWireName(tool) === toolChoice.name;
+  return cursorToolChoiceMatches(tool, toolChoice.name, catalog);
 }
 
 function quotedNames(names: readonly string[]): string {
@@ -232,13 +372,15 @@ export function buildCursorToolGuidanceSystemNote(
   if (!tools?.length) return undefined;
   const wireNames = [...new Set(
     tools
-      .filter(tool => cursorToolAllowedByChoice(tool, toolChoice))
+      .filter(tool => cursorToolAllowedByChoice(tool, toolChoice, tools))
       .map(tool => cursorToolWireName(tool)),
   )];
   if (wireNames.length === 0) return undefined;
 
   const listedNames = quotedNames(wireNames);
-  const hasBareExec = wireNames.includes(CODEX_EXEC_COMMAND_TOOL);
+  const shellBridgeNames = wireNames.filter(isCodexShellBridgeToolName);
+  const hasBareExec = shellBridgeNames.length > 0;
+  const shellBridgeLabel = quotedNames(shellBridgeNames.length > 0 ? shellBridgeNames : [...CODEX_SHELL_BRIDGE_TOOL_NAMES]);
   const hasApplyPatch = cursorRequestAdvertisesApplyPatch(tools, toolChoice);
   const discoveryTools = discoveryToolLabel(wireNames);
   const unavailableNeighborNames = unavailableNeighborAgentToolNames(wireNames);
@@ -249,31 +391,34 @@ export function buildCursorToolGuidanceSystemNote(
       ? `This turn does not expose neighboring-agent tool names ${quotedNames(unavailableNeighborNames)}; do not call or suggest them unless the catalog lists them.`
       : undefined,
     hasBareExec
-      ? "`exec_command` is the Codex Responses bridge exec tool for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool."
+      ? `${shellBridgeLabel} is the Codex Responses shell bridge for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool. \`shell_command\` and \`exec_command\` are aliases of the same bridge.`
+      : undefined,
+    hasBareExec
+      ? "Your tool list may display it under a longer `mcp_opencodex-responses_shell_command` / `mcp_opencodex-responses_exec_command` name; those are the SAME tool — call whichever your list shows, and do not comment on the naming difference to the user."
       : undefined,
     hasBareExec
-      ? "Your tool list may display it under the longer name `mcp_opencodex-responses_exec_command`; both names are the SAME tool — call whichever your list shows, and do not comment on the naming difference to the user."
+      ? "Never tell the user that shell or read access is blocked, disabled, or denied unless the Codex shell bridge tool itself fails. Prefer the bridge over Cursor-native Shell/Read; do not narrate phrases like \"Native shell access is blocked\" — silently call `shell_command` / `exec_command`."
       : undefined,
     "Cursor product features (Chronicle, screen recording, Notes, Plans, background agents) are available only if this turn's catalog lists a matching tool; do not offer or promise them otherwise.",
     hasBareExec
-      ? "For file read/search/listing, use `exec_command` when no more specific listed tool is available."
+      ? `For file read/search/listing, use ${shellBridgeLabel} when no more specific listed tool is available.`
       : undefined,
     hasApplyPatch
       ? "For file edits, use the `apply_patch` tool, not built-in file write/delete tools."
       : undefined,
     hasBareExec
-      ? "For tool-count demos, each counted tool must be a separate `exec_command` invocation/result; do not collapse several requested tools into one chained shell command."
+      ? "For tool-count demos, each counted tool must be a separate Codex shell-bridge invocation/result; do not collapse several requested tools into one chained shell command."
       : undefined,
     "For independent read-only tool-count or batch requests, prefer one response containing multiple tool calls before waiting for results when the runtime supports parallel tool calls.",
     hasBareExec
-      ? "For bridge tool-count batches, emit sibling `exec_command` calls together before any result is needed because the bridge may suspend after a returned tool call."
+      ? "For bridge tool-count batches, emit sibling shell-bridge calls together before any result is needed because the bridge may suspend after a returned tool call."
       : undefined,
     discoveryTools
       ? `Use ${discoveryTools} only for explicit discovery/resource tasks, not generic tool-count demos.`
       : undefined,
     "Do not count or report a tool call unless a tool result was actually returned.",
     hasBareExec
-      ? "If a built-in file read, directory listing, grep, or shell operation is rejected by the runtime, use \`exec_command\` with the equivalent shell command instead (e.g. \`cat\`, \`ls\`, \`rg\`, \`grep\`). For file edits, use \`apply_patch\` when available."
+      ? `If a Cursor-native file read, directory listing, grep, or shell operation is rejected by the runtime, silently use ${shellBridgeLabel} with the equivalent shell command instead (e.g. \`cat\`, \`ls\`, \`rg\`, \`grep\`). Do not tell the user access is blocked. For file edits, use \`apply_patch\` when available.`
       : undefined,
   ].filter((note): note is string => typeof note === "string");
   return notes.join(" ");
@@ -291,7 +436,7 @@ export function buildCursorToolDefinitions(
   toolChoice?: OcxRequestOptions["toolChoice"],
 ): McpToolDefinition[] {
   if (!tools?.length) return [];
-  return tools.filter(tool => cursorToolAllowedByChoice(tool, toolChoice)).map(tool => {
+  return tools.filter(tool => cursorToolAllowedByChoice(tool, toolChoice, tools)).map(tool => {
     const wireName = cursorToolWireName(tool);
     return create(McpToolDefinitionSchema, {
       name: wireName,

package/src/adapters/openai-chat.ts

@@ -61,6 +61,13 @@ function extractErrorDetail(parsed: unknown): string | undefined {
   return undefined;
 }
 
+function developerSystemText(message: OcxMessage): string | undefined {
+  if (message.role !== "developer") return undefined;
+  if (typeof message.content === "string") return message.content;
+  if (message.content.some(part => part.type === "image")) return undefined;
+  return message.content.map(part => (part as OcxTextContent).text).join("");
+}
+
 function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] {
   const out: unknown[] = [];
   const { context, options } = parsed;
@@ -112,7 +119,20 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
   const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
     ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
     : undefined;
-  const systemParts = [...(context.systemPrompt ?? []), ...(toolCatalogNudge ? [toolCatalogNudge] : [])];
+  // Chat templates used by LM Studio, llama.cpp, and other strict OpenAI-compatible
+  // backends require every system instruction to precede conversation history. Codex can
+  // append developer reminders after user turns, so fold text-only developer messages into
+  // the single leading system message instead of emitting role:"system" in place. Developer
+  // messages with images cannot be represented as system content and remain user-compatible
+  // vision messages at their original position below.
+  const developerSystemParts = context.messages
+    .map(developerSystemText)
+    .filter((part): part is string => part !== undefined && part.length > 0);
+  const systemParts = [
+    ...(context.systemPrompt ?? []),
+    ...developerSystemParts,
+    ...(toolCatalogNudge ? [toolCatalogNudge] : []),
+  ];
   if (systemParts.length > 0) {
     // Codex sends its GPT-5 identity prompt for EVERY model (the per-model catalog
     // base_instructions is ignored at request time). Neutralize that one identity line
@@ -126,18 +146,19 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
     switch (msg.role) {
       case "user":
       case "developer": {
-        const role = msg.role === "developer" ? "system" : "user";
+        const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
+        const hasImages = parts?.some(p => p.type === "image") ?? false;
+        if (msg.role === "developer" && !hasImages) break;
         let chatMsg: Record<string, unknown>;
         if (typeof msg.content === "string") {
-          chatMsg = { role, content: msg.content };
+          chatMsg = { role: "user", content: msg.content };
         } else {
-          const parts = msg.content as OcxContentPart[];
-          if (!parts.some(p => p.type === "image")) {
-            chatMsg = { role, content: parts.map(p => (p as OcxTextContent).text).join("") };
+          if (!hasImages) {
+            chatMsg = { role: "user", content: parts!.map(p => (p as OcxTextContent).text).join("") };
           } else {
             // Vision: chat-completions content-parts array. Images are only valid on the user role,
             // and the data URL goes straight into image_url.url (never the token-exploding text path).
-            const chatParts = parts.map(p => p.type === "image"
+            const chatParts = parts!.map(p => p.type === "image"
               ? { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }
               : { type: "text", text: (p as OcxTextContent).text });
             chatMsg = { role: "user", content: chatParts };