@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/responses/apply-patch-envelope.ts

@@ -8,6 +8,15 @@
 //
 // This is the same intent boundary as `src/lib/tool-argument-integers.ts`:
 // repair the one faithful reading, leave genuine patch content alone.
+//
+// One accepted exception, added 2026-09-05: a body that is ITSELF one complete
+// operation-bearing envelope, submitted as the `exec` body. That shape is never valid
+// JavaScript — `*** Begin Patch` fails to parse at the leading `**` — so it has zero
+// executable readings and exactly one faithful one. `isCompletePatchEnvelope` recognizes
+// it and the CALLERS retarget it to the apply_patch helper; the repair functions here are
+// unchanged and still return every exec body byte-identical. JavaScript that merely
+// mentions an envelope keeps a real executable reading and is left alone.
+// See devlog/_plan/260905_apply_patch_envelope_gap.
 
 const PATCH_BEGIN = "*** Begin Patch";
 const PATCH_END = "*** End Patch";
@@ -43,6 +52,43 @@ export function normalizeApplyPatchDelimiters(text: string): string {
   return `${PATCH_BEGIN}${beginBreak}${body}${endBreak}${PATCH_END}${trailingBreak}`;
 }
 
+/**
+ * True when a body is one COMPLETE top-level patch envelope carrying a real file
+ * operation.
+ *
+ * A code-mode `exec` body is JavaScript, and this shape is never valid JavaScript: a
+ * leading `*** Begin Patch` fails to parse at the `**`. So a body satisfying this
+ * predicate cannot be a program the caller meant to run, which is what makes reading it
+ * as an apply_patch call the one faithful reading rather than a guess.
+ *
+ * Deliberately strict, and reusing the same two checks `normalizeApplyPatchDelimiters`
+ * uses: a second, looser notion of "looks like a patch" is how a repair boundary drifts.
+ * JavaScript that merely CONTAINS an envelope in a string, template, or comment fails the
+ * anchored match and is left alone.
+ */
+export function isCompletePatchEnvelope(text: string): boolean {
+  const match = TOP_LEVEL_PATCH_ENVELOPE.exec(text);
+  if (!match) return false;
+  return PATCH_OPERATION_LINE.test(match[3] ?? "");
+}
+
+/**
+ * True when a PARTIAL buffer could still grow into a complete patch envelope.
+ *
+ * Streaming decides per delta, before the body is complete, while
+ * `isCompletePatchEnvelope` can only answer once it is. Without this the bridge would
+ * stream raw envelope bytes and then replace them with compiled helper JavaScript at
+ * completion — the rewind that path explicitly refuses to perform.
+ *
+ * Deliberately one-sided: it holds a buffer that MIGHT become an envelope and never
+ * claims one will. A held buffer that turns out to be something else still reaches the
+ * client in the authoritative completed item; only the live preview is skipped.
+ */
+export function mayBecomePatchEnvelope(text: string): boolean {
+  if (text === "") return false;
+  return text.startsWith(PATCH_BEGIN) || PATCH_BEGIN.startsWith(text);
+}
+
 /**
  * Repair freeform input before Codex sees it.
  *

package/src/responses/code-mode-helper-compat.ts

@@ -1,4 +1,9 @@
-import { normalizeApplyPatchDelimiters } from "./apply-patch-envelope";
+import {
+  isCompletePatchEnvelope,
+  normalizeApplyPatchDelimiters,
+  unwrapFreeformToolInput,
+} from "./apply-patch-envelope";
+import { declaresCodeModeExec } from "../types/tools";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -51,3 +56,36 @@ export function compileCodeModeHelperInput(argumentsText: unknown, toolName: str
   }
   return `const result = await tools.exec_command(${JSON.stringify(args)});\ntext(result);`;
 }
+
+/**
+ * Resolve the effective code-mode helper for one freeform call.
+ *
+ * `codeModeHelperName` already covers the NAME-based case: a provider emitted
+ * `apply_patch` under a declared `exec` catalog, so `normalizeDeclaredToolName` rewrote
+ * the name and recorded the original. That decision happens at tool-call start, before
+ * any arguments exist, so it cannot see a provider that got the NAME right and the BODY
+ * wrong.
+ *
+ * This adds that second case: the name is already `exec` so nothing was rewritten, but
+ * the body is a complete patch envelope and therefore cannot be the JavaScript that
+ * `exec` runs. Same inference the name-based path makes, drawn from the payload.
+ *
+ * Returns undefined for everything else, including JavaScript that merely mentions a
+ * patch envelope — that body is a real program and is forwarded byte-identical.
+ */
+export function resolveCodeModeHelperName(
+  codeModeHelperName: string | undefined,
+  toolName: string,
+  argumentsText: unknown,
+  namespace?: string,
+  declaredNames?: ReadonlySet<string>,
+): string | undefined {
+  if (codeModeHelperName) return codeModeHelperName;
+  if (toolName !== "exec" || namespace !== undefined) return undefined;
+  // `exec` is a name, not a guarantee. Without a catalog that is genuinely code mode, a
+  // caller-defined `exec` could legitimately take patch text, and handing it generated
+  // `tools.apply_patch(...)` JavaScript would be the mis-route this repair exists to avoid.
+  if (!declaresCodeModeExec(declaredNames)) return undefined;
+  if (typeof argumentsText !== "string" || argumentsText === "") return undefined;
+  return isCompletePatchEnvelope(unwrapFreeformToolInput(argumentsText)) ? "apply_patch" : undefined;
+}

package/src/responses/custom-tool-compat.ts

@@ -4,7 +4,7 @@ import {
   repairFreeformToolInput,
   unwrapFreeformToolInput,
 } from "./apply-patch-envelope";
-import { compileCodeModeHelperInput } from "./code-mode-helper-compat";
+import { compileCodeModeHelperInput, resolveCodeModeHelperName } from "./code-mode-helper-compat";
 import { collectResponsesToolGroups } from "./tool-groups";
 
 const ROUTED_CUSTOM_TOOL_PASSTHROUGH = new Set(["apply_patch"]);
@@ -281,17 +281,23 @@ export function restoreRoutedCustomCalls(
     ) {
       const sourceInput = item.type === "function_call" ? item.arguments : item.input;
       const aliased = targetName !== wireName;
+      const itemNamespace = typeof item.namespace === "string" ? item.namespace : undefined;
+      // Name-based alias first; otherwise let a raw patch envelope submitted as the `exec`
+      // body resolve to the same apply_patch helper (devlog/_plan/260905_apply_patch_envelope_gap).
+      const helper = aliased && sourceInput !== ""
+        ? item.name
+        : resolveCodeModeHelperName(undefined, targetName, sourceInput, itemNamespace, declaredNames);
       const restored: Record<string, unknown> = {
         ...item,
         type: "custom_tool_call",
         id: customToolItemId(item.id),
         name: aliased ? targetName : item.name,
-        input: aliased && sourceInput !== ""
-          ? compileCodeModeHelperInput(sourceInput, item.name)
+        input: helper
+          ? compileCodeModeHelperInput(sourceInput, helper)
           : repairFreeformToolInput(
             sourceInput,
             targetName,
-            typeof item.namespace === "string" ? item.namespace : undefined,
+            itemNamespace,
           ),
       };
       delete restored.arguments;

package/src/responses/hosted-tool-policy.ts

@@ -1,9 +1,17 @@
-/** Hosted tools rejected by specific native model slugs. */
-const UNSUPPORTED_HOSTED_TOOLS: ReadonlyArray<{ match: (model: string) => boolean; tools: ReadonlySet<string> }> = [
+/** Hosted tools rejected by specific native model slugs or exact provider destinations. */
+const UNSUPPORTED_HOSTED_TOOLS: ReadonlyArray<{
+  match: (model: string, baseUrl?: string) => boolean;
+  tools: ReadonlySet<string>;
+}> = [
   { match: model => model.includes("codex-spark"), tools: new Set(["image_generation", "tool_search"]) },
+  {
+    match: (model, baseUrl) => model === "grok-4.6"
+      && baseUrl?.replace(/\/+$/, "") === "https://opencode.ai/zen/go/v1",
+    tools: new Set(["web_search", "web_search_preview"]),
+  },
 ];
 
 /** True when forwarding this hosted tool to the model would be rejected upstream. */
-export function isHostedToolUnsupportedForModel(modelId: string, tool: string): boolean {
-  return UNSUPPORTED_HOSTED_TOOLS.some(entry => entry.match(modelId) && entry.tools.has(tool));
+export function isHostedToolUnsupportedForModel(modelId: string, tool: string, baseUrl?: string): boolean {
+  return UNSUPPORTED_HOSTED_TOOLS.some(entry => entry.match(modelId, baseUrl) && entry.tools.has(tool));
 }

package/src/responses/parser-content.ts

@@ -0,0 +1,133 @@
+import type { OcxContentPart, OcxTextContent } from "../types";
+
+export function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+type InputBlock =
+  | { type: "input_text"; text: string }
+  | { type: "text"; text: string }
+  | { type: "input_image"; image_url?: string; file_id?: string; detail?: string }
+  | { type: "input_video"; video_url?: string }
+  | { type: "input_file"; file_id?: string; filename?: string; file_data?: string };
+
+/** A usable reference string, or undefined. Empty strings and non-strings are not references. */
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export function inputContentParts(blocks: unknown): string | OcxContentPart[] {
+  if (typeof blocks === "string") return blocks;
+  // The catch-all can also hand back a non-array `content` (an object, a number), which would
+  // throw at the loop below before any per-block guard runs.
+  if (!Array.isArray(blocks)) return [];
+  const parts: OcxContentPart[] = [];
+  for (const raw of blocks) {
+    // A malformed message item fails its strict schema and falls through to inputItemSchema's
+    // permissive catch-all, so blocks reaching here are NOT guaranteed to match the declared
+    // shape. Validate each field before use, as outputToToolResultContent already does.
+    if (!isObj(raw)) continue;
+    const block = raw as InputBlock;
+    if (block.type === "input_text" || block.type === "text") {
+      if (typeof raw.text === "string") parts.push({ type: "text", text: raw.text });
+    } else if (block.type === "input_image") {
+      const b = block as { image_url?: string; file_id?: string; detail?: string };
+      const imageUrl = nonEmptyString(b.image_url);
+      const fileId = nonEmptyString(b.file_id);
+      const detail = nonEmptyString(b.detail);
+      if (imageUrl) {
+        // Preserve the image as a structured part — adapters send it as a native image block.
+        // NEVER inline the (often base64 data-URL) image_url as text: that explodes the token count.
+        parts.push({ type: "image", imageUrl, ...(detail ? { detail: normalizeImageDetail(detail) } : {}) });
+      } else if (fileId) {
+        parts.push({ type: "text", text: `[image: ${fileId}]` }); // file_id ref → no inline data
+      }
+      // No usable reference: omit the block. A "[image: ?]" marker would claim an attachment
+      // the request never carried, which is worse than dropping malformed input.
+    } else if (block.type === "input_video") {
+      const videoUrl = nonEmptyString(block.video_url);
+      if (videoUrl) parts.push({ type: "video", videoUrl });
+    } else if (block.type === "input_file") {
+      const b = block as { file_id?: string; filename?: string; file_data?: string };
+      const fileId = nonEmptyString(b.file_id);
+      const fileData = nonEmptyString(b.file_data);
+      const filename = nonEmptyString(b.filename);
+      if (fileId) {
+        parts.push({ type: "text", text: `[file: ${fileId}]` });
+      } else if (fileData) {
+        // Inline file_data is often large base64. Preserve only its presence and name, never bytes.
+        parts.push({ type: "text", text: filename ? `[file: ${filename}]` : "[file: inline data]" });
+      }
+      // A bare filename is not a file resource in the Responses schema, so omit it rather than
+      // fabricating a "[file: ...]" marker for an attachment that was never sent.
+    }
+  }
+  // Collapse to a plain string only for a single TEXT part; images must stay structured.
+  if (parts.length === 1 && parts[0].type === "text") return parts[0].text;
+  return parts;
+}
+
+type OutputBlock = { type: "output_text"; text: string } | { type: "text"; text: string } | { type: "refusal"; refusal: string };
+
+export function outputTextOf(blocks: unknown): OcxTextContent[] {
+  if (typeof blocks === "string") return blocks.length > 0 ? [{ type: "text", text: blocks }] : [];
+  if (!Array.isArray(blocks)) return [];
+  const out: OcxTextContent[] = [];
+  for (const raw of blocks) {
+    // Same catch-all caveat as inputContentParts: validate before use.
+    if (!isObj(raw)) continue;
+    const b = raw as OutputBlock;
+    if (b.type === "output_text" || b.type === "text") {
+      if (typeof raw.text === "string") out.push({ type: "text", text: raw.text });
+    } else if (b.type === "refusal") {
+      if (typeof raw.refusal === "string") out.push({ type: "text", text: `[refusal: ${raw.refusal}]` });
+    }
+  }
+  return out;
+}
+
+/**
+ * Tool-call output content. Preserves images (e.g. Codex `view_image` returns
+ * `input_image` items): returns content parts when any image is present, else a plain joined string.
+ * Never inlines an image_url as text (that would explode the token count).
+ */
+export function outputToToolResultContent(output: string | unknown[] | undefined): string | OcxContentPart[] {
+  if (typeof output === "string") return output;
+  if (!Array.isArray(output)) return "";
+  const parts: OcxContentPart[] = [];
+  let hasImage = false;
+  for (const raw of output) {
+    if (!isObj(raw)) continue;
+    if (raw.type === "output_text" || raw.type === "text" || raw.type === "input_text") {
+      if (typeof raw.text === "string") parts.push({ type: "text", text: raw.text });
+    } else if (raw.type === "refusal" && typeof raw.refusal === "string") {
+      parts.push({ type: "text", text: `[refusal: ${raw.refusal}]` });
+    } else if (raw.type === "input_image") {
+      const imageUrl = nonEmptyString(raw.image_url);
+      const fileId = nonEmptyString(raw.file_id);
+      if (imageUrl) {
+        parts.push({ type: "image", imageUrl, ...(typeof raw.detail === "string" ? { detail: normalizeImageDetail(raw.detail) } : {}) });
+        hasImage = true;
+      } else if (fileId) {
+        parts.push({ type: "text", text: `[image: ${fileId}]` });
+      }
+    } else if (raw.type === "encrypted_content") {
+      // codex-rs FunctionCallOutputContentItem::EncryptedContent — opaque to routed models.
+      parts.push({ type: "text", text: "[encrypted content omitted]" });
+    }
+  }
+  if (!hasImage) return parts.map(p => (p.type === "text" ? p.text : "")).join("");
+  return parts;
+}
+
+export function toolOutputContainsEncryptedContent(output: string | unknown[] | undefined): boolean {
+  return Array.isArray(output) && output.some(raw => isObj(raw) && raw.type === "encrypted_content");
+}
+
+/**
+ * codex-rs ImageDetail allows "original", but chat-completions providers only accept
+ * auto|low|high on image_url.detail — degrade "original" to "high" (the codex default).
+ */
+function normalizeImageDetail(detail: string): string {
+  return detail === "original" ? "high" : detail;
+}

package/src/responses/parser-text-format.ts

@@ -0,0 +1,24 @@
+import type { OcxRequestOptions } from "../types";
+import { isObj } from "./parser-content";
+
+/**
+ * The Responses `text.format` object when it requests structured output (json_schema or
+ * json_object), undefined otherwise. Acceptance is identical to the boolean detector this
+ * replaces; unknown or malformed formats are ignored, never rejected, so the native
+ * passthrough keeps forwarding whatever the caller sent via `_rawBody`.
+ */
+export function parseTextFormat(text: unknown): OcxRequestOptions["textFormat"] {
+  if (!isObj(text)) return undefined;
+  const format = (text as { format?: unknown }).format;
+  if (!isObj(format)) return undefined;
+  const f = format as { type?: unknown; name?: unknown; description?: unknown; schema?: unknown; strict?: unknown };
+  if (f.type === "json_object") return { type: "json_object" };
+  if (f.type !== "json_schema") return undefined;
+  return {
+    type: "json_schema",
+    ...(typeof f.name === "string" ? { name: f.name } : {}),
+    ...(typeof f.description === "string" ? { description: f.description } : {}),
+    ...(isObj(f.schema) ? { schema: f.schema as Record<string, unknown> } : {}),
+    ...(typeof f.strict === "boolean" ? { strict: f.strict } : {}),
+  };
+}

package/src/responses/parser-tools.ts

@@ -0,0 +1,188 @@
+import type { OcxRequestOptions, OcxTool } from "../types";
+import { isObj } from "./parser-content";
+import { WEB_SEARCH_TOOL_NAME } from "../web-search/synthetic-tool";
+import { buildImageTool, IMAGE_GEN_TOOL_NAME } from "../images/synthetic-tool";
+import { toolSearchDescription, toolSearchParameters } from "./tool-search-compat";
+
+export function mapToolChoice(value: unknown): OcxRequestOptions["toolChoice"] {
+  if (value === undefined || value === null) return undefined;
+  if (value === "auto" || value === "none" || value === "required") return value;
+  if (isObj(value) && "type" in value) {
+    const t = (value as { type: string }).type;
+    if ((t === "function" || t === "custom") && "name" in value) {
+      return { name: (value as { name: string }).name };
+    }
+    // Hosted image tool types (with or without a name) map to the synthetic image_gen wire name.
+    if (t === "image_generation" || t === "image_gen") {
+      return { name: IMAGE_GEN_TOOL_NAME };
+    }
+    if (t === "allowed_tools" && Array.isArray(value.tools)) {
+      const names = value.tools
+        .map(allowedToolName)
+        .filter((name): name is string => Boolean(name));
+      return names.length > 0
+        ? { allowedTools: [...new Set(names)], mode: value.mode === "required" ? "required" : "auto" }
+        : "none";
+    }
+    return "auto";
+  }
+  return undefined;
+}
+
+function allowedToolName(tool: unknown): string | undefined {
+  if (!isObj(tool)) return undefined;
+  if (typeof tool.name === "string" && tool.name.length > 0) return tool.name;
+  if (tool.type === "web_search" || tool.type === "web_search_preview") return WEB_SEARCH_TOOL_NAME;
+  if (tool.type === "image_generation" || tool.type === "image_gen") return IMAGE_GEN_TOOL_NAME;
+  if (tool.type === "tool_search") return "tool_search";
+  return undefined;
+}
+
+export function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
+  if (!tools) return undefined;
+  const out: OcxTool[] = [];
+  const normalizeParameters = (raw: unknown): Record<string, unknown> => {
+    if (isObj(raw) && raw.type === "object") return raw;
+    return { ...(isObj(raw) ? raw : {}), type: "object" };
+  };
+  const pushFn = (t: Record<string, unknown>, namespace?: string) => {
+    // Hosted image_generation already installed the synthetic root tool. A later
+    // ordinary root `image_gen` must not create a second un-namespaced identity.
+    if (
+      !namespace
+      && t.name === IMAGE_GEN_TOOL_NAME
+      && out.some(tool => tool.name === IMAGE_GEN_TOOL_NAME && !tool.namespace && tool.imageGeneration)
+    ) {
+      return;
+    }
+    const tool: OcxTool = {
+      name: t.name as string,
+      description: (t.description as string) ?? "",
+      parameters: normalizeParameters(t.parameters),
+    };
+    if (t.strict !== undefined) tool.strict = t.strict as boolean;
+    if (namespace) tool.namespace = namespace;
+    out.push(tool);
+  };
+  const pushCustom = (t: Record<string, unknown>, namespace?: string) => {
+    // Hosted image_generation already installed the synthetic root tool. A later
+    // root custom `image_gen` would collide on the same wire name with a different
+    // `freeform` flag and throw `ambiguous tool catalog`.
+    if (
+      !namespace
+      && t.name === IMAGE_GEN_TOOL_NAME
+      && out.some(tool => tool.name === IMAGE_GEN_TOOL_NAME && !tool.namespace && tool.imageGeneration)
+    ) {
+      return;
+    }
+    // Freeform custom tools are lowered to a single string `input` because chat models cannot
+    // emit Responses grammar payloads directly. Keep tool-specific input guidance scoped to the
+    // tool that owns it: leaking apply_patch syntax into `exec` or another freeform tool teaches
+    // routed models that the nested helper name is itself a callable top-level tool.
+    const inputDescription = t.name === "apply_patch"
+      ? "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope."
+      : "Raw freeform input for this tool.";
+    const tool: OcxTool = {
+      name: t.name as string,
+      description: (t.description as string) ?? "",
+      parameters: { type: "object", properties: { input: { type: "string", description: inputDescription } }, required: ["input"] },
+      freeform: true,
+    };
+    if (namespace) tool.namespace = namespace;
+    out.push(tool);
+  };
+  for (const t of tools) {
+    if (!isObj(t)) continue;
+    if (t.type === "function" && isObj(t.function) && typeof t.function.name === "string" && t.function.name.length > 0) {
+      pushFn(t.function as Record<string, unknown>);
+      continue;
+    }
+    if (t.type === "function" && typeof t.name === "string") {
+      pushFn(t);
+    } else if (t.type === "namespace" && Array.isArray(t.tools)) {
+      // Codex 0.147 groups its ordinary client tools under the reserved `functions` namespace,
+      // including freeform custom tools such as code-mode `exec`. Those children are still
+      // top-level Responses tools, so flatten them without a namespace. Other namespace groups
+      // are MCP-style and keep their namespace for round-trip routing.
+      const builtinFunctions = t.name === "functions";
+      const ns = typeof t.name === "string" && !builtinFunctions ? t.name : undefined;
+      for (const inner of t.tools as unknown[]) {
+        if (isObj(inner) && inner.type === "function" && typeof inner.name === "string") pushFn(inner, ns);
+        else if (isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner, ns);
+      }
+    }
+    else if (t.type === "custom" && typeof t.name === "string") {
+      pushCustom(t);
+    }
+    else if (t.type === "tool_search") {
+      // Client-executed tool discovery — the gateway to deferred tools (subagents, extra MCP tools).
+      // Expose as a function so chat models can call it; the bridge relays it as a tool_search_call.
+      out.push({
+        name: "tool_search",
+        description: toolSearchDescription(t),
+        parameters: normalizeParameters(toolSearchParameters(t)),
+        toolSearch: true,
+      });
+    }
+    else if (t.type === "image_generation" || t.type === "image_gen") {
+      // Keep Codex's image_gen visible to routed chat models. The hosted OpenAI tool
+      // cannot execute on Grok; the model still has to see a callable image_gen so
+      // Codex's client-side /v1/images request can fire and be relayed to xAI.
+      // Identity is the un-namespaced synthetic root (`imageGeneration: true`), not
+      // the bare name: a namespaced ordinary `image_gen` must not suppress it.
+      const synthetic = buildImageTool();
+      // Every un-namespaced `image_gen` collides on one wire name, so removing only
+      // the first leaves a second root behind and the catalog stays ambiguous.
+      // Drop all root collisions, keep namespaced entries, then insert exactly one
+      // synthetic root — at the earliest colliding position so declaration order is
+      // preserved for models that read the catalog positionally.
+      let insertAt = -1;
+      for (let i = out.length - 1; i >= 0; i -= 1) {
+        const tool = out[i]!;
+        if (tool.name !== IMAGE_GEN_TOOL_NAME || tool.namespace) continue;
+        out.splice(i, 1);
+        insertAt = i;
+      }
+      if (insertAt >= 0) out.splice(insertAt, 0, synthetic);
+      else out.push(synthetic);
+    }
+    else if (typeof t.name === "string" && t.type !== "web_search" && t.type !== "image_generation") {
+      // Any OTHER named tool (e.g. a native/computer-use tool type opencodex doesn't explicitly
+      // model) is client-executed — pass it through as a function so the routed model can read and
+      // call it naturally; the bridge relays its call as a function_call. Previously such tools were
+      // silently dropped, so the model never saw them.
+      pushFn(t);
+    }
+    // Hosted web_search is still dropped here — the web-search sidecar re-injects it.
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+/**
+ * Namespace a custom tool was declared under, by its bare name.
+ *
+ * A `custom_tool_call` echoed back by the client carries only the bare name — the bridge
+ * emits `{"type":"custom_tool_call","name":"exec"}` even when the tool was declared as
+ * `mcp__functions__exec`. Without this lookup the namespace is lost on the return trip,
+ * and the adapters replay history through `namespacedToolName(namespace, name)`, which
+ * then produces a bare `exec` the provider may not have. Ordinary `function_call` items
+ * do not need this: they carry `namespace` on the wire.
+ */
+export function customToolNamespaces(tools: unknown): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!Array.isArray(tools)) return out;
+  for (const spec of tools) {
+    if (!isObj(spec) || spec.type !== "namespace" || !Array.isArray(spec.tools)) continue;
+    const namespace = typeof spec.name === "string" ? spec.name : undefined;
+    // Codex 0.147 groups ordinary client tools under the reserved `functions` namespace and
+    // buildTools deliberately flattens those without a namespace. Mirror that here, or the
+    // reconstruction would invent a namespace the request never advertised.
+    if (!namespace || namespace === "functions") continue;
+    for (const inner of spec.tools) {
+      if (!isObj(inner) || inner.type !== "custom" || typeof inner.name !== "string") continue;
+      // Ambiguous bare names are already rejected upstream, so first declaration wins.
+      if (!out.has(inner.name)) out.set(inner.name, namespace);
+    }
+  }
+  return out;
+}