fix(adapters): decide code mode from tool semantics, not from the name exec

src/adapters/cursor/tool-definitions.ts

@@ -620,7 +620,7 @@ export function buildCursorToolGuidanceSystemNote(
     // Code mode: shell/edit/MCP live inside freeform `exec` as nested helpers. Without this the
     // model probes for a top-level shell tool that is not there.
     codeMode
-      ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description for the exact nested helpers this turn provides. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\`, \`shell_command\`, or \`apply_patch\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}.`
+      ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description and the isolate global \`ALL_TOOLS\` (not \`tools.ALL_TOOLS\`) for helpers this turn provides; absence from the top-level catalog or from \`exec\`'s description is not absence. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\` or \`shell_command\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}.`
       : undefined,
     codeMode
       ? "In code mode the isolate returns nothing on its own: call `text(...)` (or `notify(...)`) on any value you need to see, or the call completes with empty output. There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers."

src/adapters/tool-catalog-nudge.ts

@@ -17,8 +17,27 @@ import {
 // included it either.
 const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
 
+/**
+ * The two halves of the code-mode shape, kept provider-neutral here.
+ *
+ * `./cursor/tool-definitions.ts` owns the Cursor-scoped versions of these
+ * (`isCursorCodeModeExecTool` / `isBareCodexShellBridgeTool`), but those additionally require
+ * the Cursor Responses namespace. This nudge is shared by Anthropic, Google, Kiro,
+ * OpenAI-chat and command-code, so it needs the same semantics without that provider gate.
+ */
+const CODEX_UNIFIED_EXEC_TOOL_NAME = "exec";
+const CODEX_SHELL_BRIDGE_TOOL_NAMES = ["exec_command", "shell_command"] as const;
+
+function isCodexCodeModeExecTool(tool: Pick<OcxTool, "name" | "freeform">): boolean {
+  return tool.name === CODEX_UNIFIED_EXEC_TOOL_NAME && tool.freeform === true;
+}
+
+function isBareShellBridgeTool(tool: Pick<OcxTool, "name">): boolean {
+  return (CODEX_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).includes(tool.name);
+}
+
 function quoteNames(names: readonly string[]): string {
-  return names.map(name => `\`${name}\``).join(", ");
+  return names.map(name => "`" + name + "`").join(", ");
 }
 
 function uniqueNames(names: readonly string[]): string[] {
@@ -40,48 +59,83 @@ export function shouldInjectNonOpenAIToolCatalogNudge(provider: Pick<OcxProvider
   }
 }
 
+/**
+ * Codex code mode is a SEMANTIC property, not a name.
+ *
+ * The tool that carries it is a `freeform` `exec` whose body is JavaScript evaluated in a V8
+ * isolate, advertised alongside no bare shell bridge. A provider is free to advertise an
+ * ordinary structured tool called `exec` that runs a shell string — and a catalog can list
+ * `exec` next to `exec_command`/`shell_command`, which is the flat-bridge shape, not code mode.
+ *
+ * Classifying on the name alone would tell those turns that `exec` takes JavaScript and that
+ * shell is only reachable as a nested `tools.*` helper. Both are false there, and a model that
+ * believes them sends the wrong arguments or avoids a legitimate execution tool entirely.
+ *
+ * So callers that HAVE the tool objects decide with the semantic predicate and pass the verified
+ * wire name in; the name-only entry point cannot decide it and does not try.
+ */
+function codeModeExecWireName(
+  advertised: ReadonlySet<string>,
+  verifiedName: string | undefined,
+): string | undefined {
+  if (!verifiedName) return undefined;
+  return advertised.has(verifiedName) ? verifiedName : undefined;
+}
+
 export function buildNonOpenAIToolCatalogNudgeFromNames(
   wireNames: readonly string[] | undefined,
   toWireName: (name: string) => string = name => name,
+  codeModeExecName?: string,
 ): string | undefined {
   const names = uniqueNames(wireNames ?? []);
   if (names.length === 0) return undefined;
 
   const advertised = new Set(names);
   // Compare in the catalog's own coordinate system. `advertised` holds WIRE names, so a
   // provider that rewrites them (Claude OAuth `custom_`, Anthropic compat `cx_`) would never
-  // match a bare neighbor name and would forbid tools the turn actually advertises — the
+  // match a bare neighbor name and would forbid tools the turn actually advertises -- the
   // catalog would list `custom_apply_patch` while the same sentence banned `apply_patch`.
   const unavailableNeighborNames = NEIGHBOR_AGENT_TOOL_NAMES.filter(
     name => !advertised.has(name) && !advertised.has(toWireName(name)),
   );
+  const verifiedCodeModeExecName = codeModeExecWireName(advertised, codeModeExecName);
 
   return [
     "Tool contract: use the current tool catalog as ground truth.",
-    `Valid tool names for this turn are exactly ${quoteNames(names)}.`,
+    "Valid tool names for this turn are exactly " + quoteNames(names) + ".",
     "These listed names are the complete top-level tool-call surface for this turn.",
     "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
     "Names mentioned only in instructions, tool descriptions, argument descriptions, or nested helper APIs are not additional top-level tools.",
-    "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
+    verifiedCodeModeExecName
+      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names."
+      : "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
     unavailableNeighborNames.length > 0
-      ? `Do not use neighboring-agent tool names ${quoteNames(unavailableNeighborNames)} unless this turn's catalog lists those exact names.`
+      ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."
       : undefined,
     "If you need shell, file search, file read, edit, or discovery behavior, choose the listed tool that provides that capability.",
     "Count a tool call only after its tool result returns; batch independent read-only calls when the runtime supports it.",
   ].filter((line): line is string => typeof line === "string").join(" ");
 }
 
 export function buildNonOpenAIToolCatalogNudgeForTools(
-  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
   toolChoice?: OcxRequestOptions["toolChoice"],
   toWireName: (tool: Pick<OcxTool, "namespace" | "name">) => string = tool => namespacedToolName(tool.namespace, tool.name),
 ): string | undefined {
-  const visibleNames = tools
-    ?.filter(toolChoiceToolPredicate(toolChoice))
-    .map(toWireName);
+  const visible = tools?.filter(toolChoiceToolPredicate(toolChoice));
+  const visibleNames = visible?.map(toWireName);
+  // Decide code mode from the tool OBJECTS, while the `freeform` flag still exists — reducing
+  // to wire names first throws away the only thing that distinguishes Codex's JavaScript
+  // `exec` from an ordinary structured tool that happens to share the name.
+  const codeModeExecTool = visible?.find(isCodexCodeModeExecTool);
+  const codeModeExecName = codeModeExecTool
+    && !visible?.some(isBareShellBridgeTool)
+    ? toWireName(codeModeExecTool)
+    : undefined;
   // Neighbor names are bare and un-namespaced, so probe the same transform with a bare tool.
   return buildNonOpenAIToolCatalogNudgeFromNames(
     visibleNames,
     name => toWireName({ name }),
+    codeModeExecName,
   );
 }

tests/cursor-tool-definitions.test.ts

@@ -454,6 +454,9 @@ describe("Cursor code mode tool guidance", () => {
     expect(note).toContain("await tools.exec_command({cmd: " + "\"" + "ls" + "\"" + "})");
     expect(note).toContain("text(...)");
     expect(note).toContain("There is no `require`");
+    expect(note).toContain("isolate global `ALL_TOOLS`");
+    expect(note).toContain("not `tools.ALL_TOOLS`");
+    expect(note).toContain("absence from the top-level catalog");
 
     // The flat-catalog shell-bridge guidance must NOT appear: naming a top-level
     // `exec_command` in code mode sends the model after a tool that does not exist.
@@ -462,6 +465,21 @@ describe("Cursor code mode tool guidance", () => {
     expect(note).not.toContain("For file read/search/listing, use");
   });
 
+  test("does not forbid a separately listed apply_patch in code mode", () => {
+    const note = buildCursorToolGuidanceSystemNote([
+      codeModeExec(),
+      { name: "apply_patch", description: "Apply a patch", parameters: {}, freeform: true },
+    ]);
+    expect(note).toBeDefined();
+    if (!note) throw new Error("Expected Cursor tool guidance note");
+
+    expect(note).toContain("is Codex code mode");
+    expect(note).toContain("remains callable at the top level as usual");
+    expect(note).toContain("`apply_patch`");
+    expect(note).not.toContain("do not call `exec_command`, `shell_command`, or `apply_patch` at the top level here");
+    expect(note).toContain("do not call `exec_command` or `shell_command` at the top level here");
+  });
+
   test("keeps other visible top-level tools callable in code mode", () => {
     // Code mode is about how `exec` works, not a claim that the rest of the catalog is nested.
     // A turn can advertise freeform `exec` alongside ordinary top-level tools, and describing

tests/tool-catalog-nudge.test.ts

@@ -49,16 +49,90 @@ describe("non-OpenAI tool catalog nudge", () => {
     expect(buildNonOpenAIToolCatalogNudgeForTools(tools)).not.toContain("apply_patch");
   });
 
+  const codeModeExec = (): OcxTool => ({
+    name: "exec",
+    freeform: true,
+    description: "Run JavaScript in a V8 isolate.",
+    parameters: {},
+  } as OcxTool);
+
   test("defines nested helper names as non-callable unless separately listed", () => {
-    const note = buildNonOpenAIToolCatalogNudgeFromNames(["exec", "wait", "request_user_input"]);
+    const note = buildNonOpenAIToolCatalogNudgeForTools([
+      codeModeExec(),
+      { name: "wait", parameters: {} } as OcxTool,
+      { name: "request_user_input", parameters: {} } as OcxTool,
+    ]);
 
     expect(note).toContain("Valid tool names for this turn are exactly `exec`, `wait`, `request_user_input`");
     expect(note).toContain("complete top-level tool-call surface");
     expect(note).toContain("nested helper APIs are not additional top-level tools");
-    expect(note).toContain("call the listed parent tool");
+    expect(note).toContain("`exec` is Codex code mode");
+    expect(note).toContain("await tools.<name>(...)");
+    expect(note).toContain("await tools.codex_app__list_threads({})");
+    expect(note).toContain("isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`");
+    expect(note).toContain("Do not skip an available nested helper");
+    expect(note).not.toContain("call the listed parent tool and use those helpers only inside that tool's input");
     expect(note).not.toContain("apply_patch");
   });
 
+  test("keeps the generic nested-helper parent-tool rule when exec is not listed", () => {
+    const note = buildNonOpenAIToolCatalogNudgeFromNames(["exec_command", "mcp__fs__read_file"]);
+
+    expect(note).toContain("call the listed parent tool and use those helpers only inside that tool's input");
+    expect(note).not.toContain("is Codex code mode");
+    expect(note).not.toContain("tools.ALL_TOOLS");
+  });
+
+  test("detects a wire-renamed exec as code mode", () => {
+    const note = buildNonOpenAIToolCatalogNudgeForTools(
+      [codeModeExec(), { name: "wait", parameters: {} } as OcxTool],
+      undefined,
+      tool => `cx_${tool.name}`,
+    );
+
+    expect(note).toContain("`cx_exec` is Codex code mode");
+    expect(note).toContain("from `cx_exec`'s description is not absence");
+    expect(note).toContain("isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`");
+  });
+
+  // The three cases the #1895 review named. Code mode is a semantic shape, not the name `exec`:
+  // a structured `exec` runs a shell string, and `exec` beside a visible shell bridge is the
+  // flat-catalog shape. Telling either of those turns that `exec` takes JavaScript and that
+  // shell is nested-only is actively wrong — the model then sends the wrong arguments or
+  // avoids a legitimate top-level execution tool.
+  test("a structured tool named exec is NOT code mode", () => {
+    const note = buildNonOpenAIToolCatalogNudgeForTools([
+      { name: "exec", freeform: false, parameters: {} } as OcxTool,
+      { name: "mcp__fs__read_file", parameters: {} } as OcxTool,
+    ]);
+
+    expect(note).not.toContain("is Codex code mode");
+    expect(note).not.toContain("tools.ALL_TOOLS");
+    expect(note).toContain("call the listed parent tool and use those helpers only inside that tool's input");
+  });
+
+  test("freeform exec beside a visible shell bridge is NOT code mode", () => {
+    for (const bridge of ["exec_command", "shell_command"]) {
+      const note = buildNonOpenAIToolCatalogNudgeForTools([
+        codeModeExec(),
+        { name: bridge, parameters: {} } as OcxTool,
+      ]);
+
+      expect(note).not.toContain("is Codex code mode");
+      expect(note).toContain("call the listed parent tool and use those helpers only inside that tool's input");
+    }
+  });
+
+  test("a transformed freeform exec still receives code-mode guidance", () => {
+    const note = buildNonOpenAIToolCatalogNudgeForTools(
+      [codeModeExec()],
+      undefined,
+      tool => `custom_${tool.name}`,
+    );
+
+    expect(note).toContain("`custom_exec` is Codex code mode");
+  });
+
   // `advertised` holds WIRE names. A provider that rewrites them (Claude OAuth `custom_`,
   // Anthropic compat `cx_`) must not have every neighbor name declared unavailable while the
   // catalog plainly lists the prefixed form.