@bitkyc08/opencodex 2.26.0 → 2.28.0

package/src/providers/registry.ts

@@ -17,6 +17,7 @@ import {
   cursorModelReasoningEfforts,
 } from "../adapters/cursor/discovery";
 import { COMMAND_CODE_MODEL_REASONING_EFFORTS } from "./command-code-efforts";
+import { isCanonicalOpenRouterTarget } from "./openrouter-routing";
 
 export type ProviderAuthKind = "forward" | "oauth" | "key" | "local";
 export type MetadataModelIdNormalize = "case-insensitive";
@@ -30,9 +31,15 @@ export type InboundWire = "responses" | "chat" | "anthropic";
 
 /**
  * A per-model wire default: a bare string applies to every inbound, while the object
- * form applies only to the listed inbound protocols.
+ * form may scope the default to listed inbound protocols and authentication modes.
  */
-export type ModelWireDefault = string | { wire: string; inbound: readonly InboundWire[] };
+export type ModelWireDefault = string | {
+  wire: string;
+  inbound: readonly InboundWire[];
+  authModes?: readonly ProviderAuthKind[];
+  /** Whether this registry-selected route may relay a caller-owned service_tier. */
+  forwardCallerServiceTier?: boolean;
+};
 
 export interface ResponsesTerminalRepairPolicy {
   /** Quiet time after a structurally complete output graph before synthesizing completion. */
@@ -217,6 +224,11 @@ export interface ProviderRegistryEntry {
   supportsServiceTier?: boolean;
   /** Registry default for exact model service-tier capability; explicit config keys win. */
   modelSupportsServiceTier?: Record<string, boolean>;
+  /**
+   * Registry-only destination guard for `modelSupportsServiceTier`. This scopes vendor evidence
+   * without changing provider ownership, routing, authentication, or config validation.
+   */
+  modelServiceTierCapabilityBaseUrlGuard?: (baseUrl: string) => boolean;
   /** Registry default for plaintext reasoning replay; see `OcxProviderConfig.preserveResponsesReasoningContent`. Registry-only like `supportsServiceTier`. */
   preserveResponsesReasoningContent?: boolean;
   /** Registry defaults for per-model Codex reasoning propagation; explicit user keys win during enrichment. */
@@ -1011,6 +1023,24 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // grok-4.5; the reasoning ladder does not — 4.6 adds the documented xhigh rung.
     models: ["grok-4.6", "grok-4.5", "grok-4.3", "grok-4.20-0309-reasoning", "grok-4.20-0309-non-reasoning", "grok-build-0.1", "grok-composer-2.5-fast"],
     defaultModel: "grok-4.5",
+    // The current Grok CLI catalog declares both subscription models as native Responses
+    // backends. Keep API-key and translated Chat/Anthropic callers on their existing wire;
+    // Codex Responses traffic can relay xAI's SSE as it arrives instead of waiting for the
+    // Chat Completions compatibility stream to flush at the end of a reasoning turn.
+    modelWireDefaults: {
+      "grok-4.6": {
+        wire: "openai-responses",
+        inbound: ["responses"],
+        authModes: ["oauth"],
+        forwardCallerServiceTier: false,
+      },
+      "grok-4.5": {
+        wire: "openai-responses",
+        inbound: ["responses"],
+        authModes: ["oauth"],
+        forwardCallerServiceTier: false,
+      },
+    },
     // Vision lineup per docs.x.ai model-capabilities/images/understanding: the grok-4.x chat
     // models accept image input (JPEG/PNG, URL or base64). Without this the catalog leaves
     // inputModalities undefined, and deriveComboCatalogModel defaults an undefined member to
@@ -1077,6 +1107,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     adapter: "anthropic",
     baseUrl: "https://api.anthropic.com",
     authKind: "oauth",
+    allowBaseUrlOverride: true,
     featured: true,
     oauthId: "anthropic",
     jawcodeBundle: "anthropic",
@@ -1349,7 +1380,33 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     autoToolChoiceOnlyModels: ["kimi-k2.7-code"],
     preserveReasoningContentModels: NEURALWATT_REASONING_HISTORY_MODELS,
   },
-  { id: "openrouter", label: "OpenRouter", adapter: "openai-chat", baseUrl: "https://openrouter.ai/api/v1", authKind: "key", featured: true, dashboardUrl: "https://openrouter.ai/keys", jawcodeBundle: "openrouter", models: ["anthropic/claude-sonnet-5", ...OPENROUTER_GPT56_MODELS], modelContextWindows: { "anthropic/claude-sonnet-5": 1_000_000, ...OPENROUTER_GPT56_CONTEXT_WINDOWS } },
+  {
+    id: "openrouter",
+    label: "OpenRouter",
+    adapter: "openai-chat",
+    baseUrl: "https://openrouter.ai/api/v1",
+    authKind: "key",
+    featured: true,
+    dashboardUrl: "https://openrouter.ai/keys",
+    jawcodeBundle: "openrouter",
+    models: ["anthropic/claude-sonnet-5", ...OPENROUTER_GPT56_MODELS],
+    modelContextWindows: {
+      "anthropic/claude-sonnet-5": 1_000_000,
+      ...OPENROUTER_GPT56_CONTEXT_WINDOWS,
+    },
+    // OpenRouter documents priority support for OpenAI endpoints, but not Anthropic. Keep the
+    // provider unclassified and opt in only the exact OpenAI-backed slugs we ship. These facts
+    // belong only to the canonical destination; a same-named custom gateway is unknown to us.
+    modelServiceTierCapabilityBaseUrlGuard: isCanonicalOpenRouterTarget,
+    modelSupportsServiceTier: {
+      "openai/gpt-5.6-sol": true,
+      "openai/gpt-5.6-terra": true,
+      "openai/gpt-5.6-luna": true,
+    },
+    // Deliberately no OpenRouter route pin: it bills the endpoint actually used and reports the
+    // actual service_tier. B0 confirmation therefore owns downgrade safety. Forcing `only` plus
+    // `allow_fallbacks:false` would turn a graceful priority-capacity fallback into a hard failure.
+  },
   {
     // Primary sources checked 2026-08-02:
     // - docs.cline.bot/getting-started/clinepass publishes this exact catalog and explicitly
@@ -1464,7 +1521,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   // 2026-07-10: defaultModel is frozen pending Vertex-specific Tier-2 evidence; Gemini API
   // evidence from ai.google.dev does not establish Vertex publisher availability.
   { id: "google-vertex", label: "Google Vertex AI", adapter: "google", baseUrl: "https://aiplatform.googleapis.com", authKind: "key", dashboardUrl: "https://console.cloud.google.com/vertex-ai", defaultModel: "gemini-3-pro", googleMode: "vertex", jawcodeBundle: "google", extraMetadataAliases: ["gemini-vertex"] },
-  { id: "google-antigravity", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.7-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"] },
+  { id: "google-antigravity", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", allowBaseUrlOverride: true, dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.7-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"] },
   { id: "azure-openai", label: "Azure OpenAI", adapter: "azure-openai", baseUrl: "https://{resource}.openai.azure.com/openai", authKind: "key", featured: true, dashboardUrl: "https://portal.azure.com" },
   { id: "ollama", label: "Ollama (local)", adapter: "openai-chat", baseUrl: "http://localhost:11434/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },
   { id: "vllm", label: "vLLM (local)", adapter: "openai-chat", baseUrl: "http://localhost:8000/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },
@@ -2403,6 +2460,16 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     note: "No key needed — public desktop tier. OpenCode currently advertises about 200 Big Pickle/free-model requests per 5 hours. The same Zen gateway can also short-window rate-limit free models at roughly 15-20 requests/minute, and may return generic 429s without Retry-After (opencodex synthesizes backoff only when that header is omitted). Free models are discovered live from Zen. Data use: per OpenCode's Zen docs (https://opencode.ai/docs/zen/), prompts sent to free models may be retained and used for training/improvement — do not send confidential material through this provider.",
     dashboardUrl: "https://opencode.ai",
     staticHeaders: {
+      // Zen answers a bare runtime User-Agent (Bun/x.y.z) more aggressively than a client
+      // that identifies itself, which is what the 429 in #2067 traced to. The value is
+      // deliberately unversioned: a pinned "opencode-cli/<version>" is a claim about an
+      // install we do not have and goes stale on the vendor's schedule, not ours.
+      // Corroboration, not authority: OmniRoute — an independent open-source broker against
+      // the same Zen upstream — defaults to exactly this pair (userAgent "opencode", client
+      // "desktop") in open-sse/executors/opencode.ts, and got there by RETREATING from its
+      // own earlier "opencode-cli/1.0.0" pin. An operator can still override either value
+      // through the provider headers API; user headers win case-insensitively at route time.
+      "User-Agent": "opencode",
       "x-opencode-client": "desktop",
     },
     modelReasoningEfforts: Object.fromEntries(OPENCODE_FREE_DEEPSEEK_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)])),
@@ -2470,6 +2537,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // The gateway validates the ladder strictly and rejects anything above `high`.
     reasoningEfforts: ["low", "medium", "high"],
     reasoningEffortMap: { xhigh: "high", max: "high", ultra: "high" },
+    // Live token-plan verification (#1927): the Pro route rejects image input while
+    // mimo-v2.5 accepts it natively. Keep this provider-scoped so a hand-rolled
+    // provider with the same id but another destination does not inherit the claim.
+    noVisionModels: ["mimo-v2.5-pro"],
     // A user may already have hand-rolled a provider under this id against a different host;
     // without this, routedProviderConfig() would canonicalize their base URL onto ours and send
     // their key somewhere they did not choose.
@@ -2555,6 +2626,45 @@ export function getProviderRegistryEntry(id: string): ProviderRegistryEntry | un
   return PROVIDER_REGISTRY.find(entry => entry.id === id);
 }
 
+/**
+ * Merge a registry row's `staticHeaders` beneath a provider's own headers.
+ *
+ * The field is documented as "merged into every upstream request for this provider", but that
+ * was only ever true for a freshly seeded config: `providerConfigSeed` copies the block once
+ * (`derive.ts`), `enrichProviderFromCatalog` fills it only when the whole block is absent, and
+ * nothing merged it at request time. So an install that predates a header — or that saved any
+ * header of its own — never received the new one, which is exactly what #2067 would have
+ * shipped for every existing opencode-free user.
+ *
+ * The comparison is case-insensitive on purpose. HTTP header names are case-insensitive, but a
+ * plain object spread is not: merging a registry `User-Agent` over a user's `user-agent`
+ * produces two entries that `Headers` serializes as one comma-joined value
+ * ("opencode, custom-agent"), which is a corrupted request rather than an override. The user's
+ * spelling and value both win; the registry only fills names the user has not spoken for.
+ */
+export function mergeRegistryStaticHeaders(
+  staticHeaders: Record<string, string> | undefined,
+  userHeaders: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!staticHeaders) return userHeaders;
+  if (!userHeaders) return { ...staticHeaders };
+  const claimed = new Set(Object.keys(userHeaders).map(name => name.toLowerCase()));
+  const merged: Record<string, string> = { ...userHeaders };
+  for (const [name, value] of Object.entries(staticHeaders)) {
+    if (!claimed.has(name.toLowerCase())) merged[name] = value;
+  }
+  return merged;
+}
+
+/** Whether this registry row's per-model service-tier evidence applies to one configured target. */
+export function registryModelServiceTierCapabilityApplies(
+  entry: Pick<ProviderRegistryEntry, "modelServiceTierCapabilityBaseUrlGuard">,
+  provider: Pick<OcxProviderConfig, "baseUrl">,
+): boolean {
+  const guard = entry.modelServiceTierCapabilityBaseUrlGuard;
+  return guard === undefined || guard(provider.baseUrl);
+}
+
 function normalizedProviderEndpoint(value: string): string {
   const trimmed = value.trim();
   try {
@@ -2634,8 +2744,12 @@ export function providerModelWireDefault(
   if (!entry?.modelWireDefaults || !providerMatchesRegistryTransport(id, provider)) return undefined;
   const declared = entry.modelWireDefaults[modelId.trim().toLowerCase()];
   if (declared === undefined) return undefined;
-  // A bare string applies to every inbound; the object form only to the listed ones.
-  if (typeof declared !== "string" && !declared.inbound.includes(inbound)) return undefined;
+  // A bare string applies to every inbound/auth mode; the object form may narrow either.
+  if (typeof declared !== "string") {
+    if (!declared.inbound.includes(inbound)) return undefined;
+    const authMode = provider.authMode ?? entry.authKind;
+    if (declared.authModes && !declared.authModes.includes(authMode)) return undefined;
+  }
   const wire = typeof declared === "string" ? declared : declared.wire;
   return wire !== undefined && allowedWires.has(wire) ? wire : undefined;
 }

package/src/providers/service-tier.ts

@@ -4,6 +4,7 @@ import { isCanonicalOpenAiForwardProvider } from "./openai-tiers";
 import {
   getProviderRegistryEntry,
   providerMatchesRegistryTransport,
+  registryModelServiceTierCapabilityApplies,
   type InboundWire,
   type ModelWireDefault,
 } from "./registry";
@@ -44,7 +45,16 @@ function cloneRegistryWireDefaults(
   for (const [modelId, declaration] of Object.entries(defaults)) {
     clone[modelId.trim().toLowerCase()] = typeof declaration === "string"
       ? declaration
-      : Object.freeze({ wire: declaration.wire, inbound: Object.freeze([...declaration.inbound]) });
+      : Object.freeze({
+          wire: declaration.wire,
+          inbound: Object.freeze([...declaration.inbound]),
+          ...(declaration.authModes
+            ? { authModes: Object.freeze([...declaration.authModes]) }
+            : {}),
+          ...(declaration.forwardCallerServiceTier !== undefined
+            ? { forwardCallerServiceTier: declaration.forwardCallerServiceTier }
+            : {}),
+        });
   }
   return Object.freeze(clone);
 }
@@ -57,10 +67,17 @@ function buildFastPolicyAuthority(
   providerName: string,
   provider: ServiceTierCapabilityProvider,
   registryTransportMatch: boolean,
+  capabilityProvider: ServiceTierCapabilityProvider = provider,
 ): FastPolicyAuthority {
   const registry = registryTransportMatch ? getProviderRegistryEntry(providerName) : undefined;
+  const registryModelCapabilities = registry
+    && registryModelServiceTierCapabilityApplies(registry, capabilityProvider)
+    ? registry.modelSupportsServiceTier
+    : undefined;
+  const providerCapability = capabilityProvider.supportsServiceTier ?? registry?.supportsServiceTier;
   const authority: FastPolicyAuthority = Object.freeze({
     providerAdapter: provider.adapter,
+    providerAuthMode: provider.authMode ?? registry?.authKind ?? "key",
     fastWireDeclaration: cloneFastWire(
       provider.fastWire !== undefined ? provider.fastWire : registry?.fastWire,
       { freeze: true },
@@ -72,8 +89,11 @@ function buildFastPolicyAuthority(
       provider.apiKeyTransport,
     ),
     capability: Object.freeze({
-      ...(provider.supportsServiceTier !== undefined ? { provider: provider.supportsServiceTier } : {}),
-      models: Object.freeze({ ...(provider.modelSupportsServiceTier ?? {}) }),
+      ...(providerCapability !== undefined ? { provider: providerCapability } : {}),
+      models: Object.freeze({
+        ...(registryModelCapabilities ?? {}),
+        ...(capabilityProvider.modelSupportsServiceTier ?? {}),
+      }),
       ...(provider.chatServiceTier !== undefined ? { chatServiceTier: provider.chatServiceTier } : {}),
     }),
     modelAdapters: Object.freeze({ ...(provider.modelAdapters ?? {}) }),
@@ -87,8 +107,14 @@ export function captureFastPolicyAuthority(
   providerName: string,
   provider: ServiceTierCapabilityProvider,
   registryTransportMatch: boolean,
+  capabilityProvider: ServiceTierCapabilityProvider = provider,
 ): FastPolicyAuthority {
-  const authority = buildFastPolicyAuthority(providerName, provider, registryTransportMatch);
+  const authority = buildFastPolicyAuthority(
+    providerName,
+    provider,
+    registryTransportMatch,
+    capabilityProvider,
+  );
   if (Object.isFrozen(provider)) capturedFastPolicyAuthorities.set(provider, authority);
   return authority;
 }
@@ -106,12 +132,13 @@ export function captureServiceTierAdapterAuthority(
 function authorityForProvider(
   provider: ServiceTierCapabilityProvider,
   providerName?: string,
+  capabilityProvider?: ServiceTierCapabilityProvider,
 ): FastPolicyAuthority {
   // Preserve the legacy no-name short circuit: serviceTierSupportForModel() used the
   // provider adapter directly when no provider identity was available, so no configured
   // override, hard pin, or registry default may participate on this path in A1.
   if (providerName === undefined) {
-    const authority = buildFastPolicyAuthority("", provider, false);
+    const authority = buildFastPolicyAuthority("", provider, false, capabilityProvider ?? provider);
     return Object.freeze({
       ...authority,
       modelAdapters: Object.freeze({}),
@@ -119,12 +146,17 @@ function authorityForProvider(
       registryWireDefaults: Object.freeze({}),
     });
   }
-  const captured = Object.isFrozen(provider)
+  const captured = capabilityProvider === undefined && Object.isFrozen(provider)
     ? capturedFastPolicyAuthorities.get(provider)
     : undefined;
   if (captured) return captured;
   const registryTransportMatch = providerMatchesRegistryTransport(providerName, provider);
-  const authority = buildFastPolicyAuthority(providerName, provider, registryTransportMatch);
+  const authority = buildFastPolicyAuthority(
+    providerName,
+    provider,
+    registryTransportMatch,
+    capabilityProvider ?? provider,
+  );
   // Frozen provider snapshots cannot drift, so repeated catalog/runtime projections may safely
   // reuse the registry lookup and detached declaration maps. Mutable configs still rebuild.
   if (Object.isFrozen(provider)) capturedFastPolicyAuthorities.set(provider, authority);
@@ -137,8 +169,13 @@ export function fastPolicyForModel(
   modelId: string,
   providerName?: string,
   inbound: InboundWire = "responses",
+  capabilityProvider?: ServiceTierCapabilityProvider,
 ): ResolvedFastPolicy {
-  return resolveFastPolicy(authorityForProvider(provider, providerName), modelId, inbound);
+  return resolveFastPolicy(
+    authorityForProvider(provider, providerName, capabilityProvider),
+    modelId,
+    inbound,
+  );
 }
 
 /**
@@ -214,13 +251,11 @@ export function serviceTierSupportFromPolicy(
 ): boolean | undefined {
   if (policy.eligibility === "eligible") return true;
   if (policy.eligibility === "unclassified") {
-    // B1 regression guard: an unclassified chat-wire route whose final adapter will not
-    // forward any tier cannot serialize service_tier, so projecting "unknown" would let
-    // require.serviceTier: "unsupported" routing stop matching groq/ollama-class providers
-    // that main projected as false. Chat + no forwarding stays a definitive false; a
-    // chat route with chatServiceTier: true (forwarding allowed) keeps the historical
-    // unknown, as does every unclassified Responses-wire route.
-    if (policy.adapter === "openai-chat" && !policy.forwardCallerTier) return false;
+    // An unclassified route that cannot forward a caller tier has definitive negative
+    // evidence even when its adapter can normally serialize service_tier. This covers both
+    // Chat routes without chatServiceTier and a registry default that explicitly closes a
+    // subscription gateway. Generic unclassified Responses routes still project unknown.
+    if (!policy.forwardCallerTier) return false;
     return undefined;
   }
   return false;

package/src/responses/parser.ts

@@ -11,7 +11,7 @@ import type {
   OcxToolCall,
   OcxReasoningReplayScopeRef,
 } from "../types";
-import { namespacedToolName } from "../types";
+import { namespacedToolName, toolChoiceCandidates } from "../types";
 import { responsesRequestSchema } from "./schema";
 import { providerMetadataFromResponsesFunctionCall } from "./provider-opaque-metadata";
 import { lookupReplayThoughtSignature } from "./thought-signature-replay";
@@ -20,6 +20,7 @@ import { previousResponseReplayPrefixLength } from "./state";
 import { decodeReasoningEnvelope } from "./reasoning-envelope";
 import { extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "../web-search/synthetic-tool";
 import { extractHostedImageGeneration, IMAGE_GEN_TOOL_NAME } from "../images/synthetic-tool";
+import { toolSearchDescription, toolSearchParameters } from "./tool-search-compat";
 
 function isObj(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -203,7 +204,7 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
       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 (builtinFunctions && isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner);
+        else if (isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner, ns);
       }
     }
     else if (t.type === "custom" && typeof t.name === "string") {
@@ -214,15 +215,8 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
       // 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: (t.description as string) ?? "Search for additional tools to load for the next turn.",
-        parameters: (isObj(t.parameters) ? t.parameters : {
-          type: "object",
-          properties: {
-            query: { type: "string", description: "Search query for tools to load." },
-            limit: { type: "number", description: "Maximum number of tools to return." },
-          },
-          required: ["query"],
-        }) as Record<string, unknown>,
+        description: toolSearchDescription(t),
+        parameters: normalizeParameters(toolSearchParameters(t)),
         toolSearch: true,
       });
     }
@@ -328,6 +322,35 @@ function attachPendingReasoningToCallOwner(
 
 const REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
+/**
+ * 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.
+ */
+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;
+}
+
 export function parseRequest(
   body: unknown,
   parseOptions?: { replayCacheScope?: OcxReasoningReplayScopeRef },
@@ -341,6 +364,9 @@ export function parseRequest(
   const data = parsed.data;
   const now = Date.now();
   const messages: OcxMessage[] = [];
+  // Built before the item loop: a custom_tool_call echoed back in `input` needs the
+  // namespace from the request's own tool catalog to survive the round trip.
+  const customToolNamespacesByName = customToolNamespaces(data.tools);
   const systemPrompt: string[] = [];
   // Responses reasoning siblings belong to the following assistant, including across call items.
   // Keep them off the message list until that assistant arrives; turn boundaries clear the array.
@@ -574,10 +600,15 @@ export function parseRequest(
       if (effectiveType === "custom_tool_call") {
         const call = item as { id?: string; call_id: string; name: string; input: string };
         const remembered = typeof call.call_id === "string" ? replayThoughtSignatureMetadata(call.call_id, replayCacheScope) : undefined;
+        // Reconstruct the namespace the request declared this tool under. The wire item
+        // carries only the bare name, so without this the round trip loses it and adapters
+        // replay the call as an unnamespaced tool the provider may not expose.
+        const customNamespace = customToolNamespacesByName.get(call.name);
         const toolCall: OcxToolCall = {
           type: "toolCall", id: call.call_id, name: call.name,
           arguments: { input: call.input ?? "" },
           customWireName: call.name,
+          ...(customNamespace ? { namespace: customNamespace } : {}),
           ...(remembered ? { providerMetadata: remembered } : {}),
         };
         assistantHolderWithReasoning().content.push(toolCall);
@@ -691,6 +722,15 @@ export function parseRequest(
   const declaredTools = buildTools(data.tools as unknown[] | undefined) ?? [];
   const loadedTools = buildTools(loadedToolSpecs) ?? [];
   const loadedToolNames = new Set(loadedTools.map(t => namespacedToolName(t.namespace, t.name)));
+  const wireOwners = new Map<string, OcxTool>();
+  for (const tool of [...declaredTools, ...loadedTools]) {
+    const wireName = namespacedToolName(tool.namespace, tool.name);
+    const previous = wireOwners.get(wireName);
+    if (previous && (previous.namespace !== tool.namespace || previous.name !== tool.name || previous.freeform !== tool.freeform || previous.toolSearch !== tool.toolSearch)) {
+      throw new Error(`ambiguous tool catalog: multiple logical tools map to wire name ${wireName}`);
+    }
+    wireOwners.set(wireName, tool);
+  }
   const seenTools = new Set<string>();
   const mergedTools = [...declaredTools, ...loadedTools]
     .filter(t => {
@@ -716,6 +756,14 @@ export function parseRequest(
     options.stopSequences = typeof data.stop === "string" ? [data.stop] : data.stop;
   }
   const tc = mapToolChoice(data.tool_choice);
+  if (tc && typeof tc === "object") {
+    const selectors = "allowedTools" in tc ? tc.allowedTools : [tc.name];
+    for (const selector of selectors) {
+      if (toolChoiceCandidates(mergedTools, selector).length > 1) {
+        throw new Error(`ambiguous tool_choice name: ${selector}`);
+      }
+    }
+  }
   if (tc !== undefined) options.toolChoice = tc;
   if (data.parallel_tool_calls !== undefined) options.parallelToolCalls = data.parallel_tool_calls;
   // Upstream codex-rs converts "ultra" to "max" at the inference boundary (core/src/client.rs