@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/server/messages-native-tool-guard.ts

@@ -0,0 +1,185 @@
+import { anthropicErrorBody } from "../claude/outbound";
+import { redactSecretString } from "../lib/redact";
+import { sseFieldValue } from "../lib/sse-decoder";
+import { TRANSLATOR_MAX_SSE_EVENT_BYTES, type TranslatorBudget } from "../lib/translator-budget";
+import { UNDECLARED_TOOL_CALL_ERROR_CODE, undeclaredToolCallMessage } from "./responses-undeclared-tool-guard";
+import { createSseBlockBuffer, sseDataPayload } from "./sse-payload-rewrite";
+
+type Rec = Record<string, unknown>;
+const isRec = (value: unknown): value is Rec => value !== null && typeof value === "object" && !Array.isArray(value);
+const NO_DECLARED_TOOLS: ReadonlySet<string> = new Set();
+
+/** Inline system-message definitions extend an otherwise empty native catalog. */
+export function nativeMessagesInlineToolNames(body: Rec): ReadonlySet<string> {
+  const definitions = new Set<string>();
+  const active = new Set<string>();
+  if (!Array.isArray(body.messages)) return active;
+  for (const message of body.messages) {
+    if (!isRec(message) || message.role !== "system" || !Array.isArray(message.content)) continue;
+    for (const block of message.content) {
+      if (!isRec(block) || !isRec(block.tool)) continue;
+      const tool = block.tool;
+      if (block.type === "tool_addition" && tool.type === "tool_definition" && isRec(tool.definition)
+        && typeof tool.definition.name === "string" && tool.definition.name.length > 0) {
+        definitions.add(tool.definition.name);
+        active.add(tool.definition.name);
+      } else if (tool.type === "tool_reference" && typeof tool.name === "string") {
+        if (block.type === "tool_addition" && definitions.has(tool.name)) active.add(tool.name);
+        // Like native admission, only a permanent removal withdraws a declaration.
+        if (block.type === "tool_removal" && (message.clear_at === undefined || message.clear_at === "never")) active.delete(tool.name);
+      }
+    }
+  }
+  return active;
+}
+
+/** Inspect only native message content; opaque extension fields do not carry client calls. */
+export function nativeMessagesClientToolName(value: unknown, declared: ReadonlySet<string> = NO_DECLARED_TOOLS): string | undefined {
+  if (!isRec(value)) return undefined;
+  const content = Array.isArray(value.content) ? value.content : [];
+  const block = content.find(item => isRec(item) && item.type === "tool_use"
+    && (typeof item.name !== "string" || !declared.has(item.name)));
+  if (isRec(block)) return typeof block.name === "string" ? block.name : "<unnamed>";
+  return undefined;
+}
+
+/** Used only when the current native request explicitly declares no client tools. */
+export function guardNativeMessagesEmptyToolCatalog(
+  source: ReadableStream<Uint8Array>,
+  budget: TranslatorBudget,
+  onRefusal: (message: string) => void,
+  declared: ReadonlySet<string> = NO_DECLARED_TOOLS,
+): ReadableStream<Uint8Array> {
+  const reader = source.getReader();
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  const scope = { kind: "live_transient" as const };
+  const buffer = createSseBlockBuffer(budget, bytes => {
+    if (bytes > TRANSLATOR_MAX_SSE_EVENT_BYTES) throw new Error("upstream SSE event exceeded the safe limit");
+  });
+  // Hosted tools share input_json_delta with client tools, but cannot grant client authority.
+  const permittedInputBlocks = new Set<number>();
+  let queuedBytes = 0;
+  let settled = false;
+  const releaseQueued = () => {
+    budget.releaseRetained(queuedBytes, scope);
+    queuedBytes = 0;
+  };
+  const clear = () => {
+    buffer.clear();
+    budget.releaseRetained(permittedInputBlocks.size * 32, scope);
+    permittedInputBlocks.clear();
+  };
+  const enqueue = (controller: ReadableStreamDefaultController<Uint8Array>, text: string) => {
+    const bytes = Buffer.byteLength(text);
+    const reservation = budget.reserveTransient(bytes, scope);
+    try {
+      controller.enqueue(encoder.encode(text));
+      reservation.commitRetained();
+      queuedBytes += bytes;
+    } catch (error) {
+      reservation.release();
+      throw error;
+    }
+  };
+  const cancelReader = (reason?: unknown) => {
+    void reader.cancel(reason).catch(() => {});
+  };
+  const process = (controller: ReadableStreamDefaultController<Uint8Array>, block: string, delimiter: string) => {
+    const payload = sseDataPayload(block);
+    let data: unknown;
+    let terminal = false;
+    try { data = payload === null ? undefined : JSON.parse(payload); } catch {
+      // The buffered Messages collector concatenates data lines without separators. Inspect
+      // that representation too, so an invalid SSE split cannot become a valid folded tool call.
+      try { data = payload === null ? undefined : JSON.parse(payload.replace(/\n/g, "")); } catch { /* preserve opaque frames */ }
+    }
+    if (isRec(data)) {
+      const eventName = block.split(/\r\n|\r|\n/).map(line => sseFieldValue(line, "event"))
+        .filter(value => value !== null).at(-1)?.trim();
+      // Stream clients use the payload type; the buffered collector uses the event field.
+      const isEvent = (type: string) => data.type === type || eventName === type;
+      terminal = isEvent("message_stop") || isEvent("error");
+      let name = isEvent("message_start") ? nativeMessagesClientToolName(data.message, declared) : undefined;
+      if (isEvent("content_block_start") && isRec(data.content_block) && data.content_block.type === "tool_use"
+        && (typeof data.content_block.name !== "string" || !declared.has(data.content_block.name))) {
+        name ??= typeof data.content_block.name === "string" ? data.content_block.name : "<unnamed>";
+      }
+      const index = typeof data.index === "number" && Number.isSafeInteger(data.index) ? data.index : undefined;
+      if (isEvent("content_block_delta") && isRec(data.delta) && data.delta.type === "input_json_delta"
+        && (index === undefined || !permittedInputBlocks.has(index))) name ??= "<unnamed>";
+      if (name !== undefined) {
+        clear();
+        const message = redactSecretString(undeclaredToolCallMessage(name));
+        onRefusal(message);
+        enqueue(controller, `event: error\ndata: ${JSON.stringify(anthropicErrorBody(502, message, "api_error", UNDECLARED_TOOL_CALL_ERROR_CODE))}\n\n`);
+        settled = true;
+        cancelReader(new Error(message));
+        controller.close();
+        return;
+      }
+      if (isEvent("content_block_start") && index !== undefined && isRec(data.content_block)) {
+        if (permittedInputBlocks.delete(index)) budget.releaseRetained(32, scope);
+        if (data.content_block.type === "server_tool_use" || data.content_block.type === "mcp_tool_use"
+          || data.content_block.type === "tool_use" && typeof data.content_block.name === "string" && declared.has(data.content_block.name)) {
+          budget.chargeRetained(32, scope);
+          permittedInputBlocks.add(index);
+        }
+      } else if (isEvent("content_block_stop") && index !== undefined && permittedInputBlocks.delete(index)) {
+        budget.releaseRetained(32, scope);
+      }
+    }
+    enqueue(controller, block + delimiter);
+    if (terminal) {
+      settled = true;
+      clear();
+      cancelReader();
+      controller.close();
+    }
+  };
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      releaseQueued();
+      if (settled) return;
+      try {
+        for (;;) {
+          const block = buffer.next();
+          if (block) {
+            buffer.compact();
+            process(controller, block.block, block.delimiter);
+            return;
+          }
+          const { done, value } = await reader.read();
+          if (settled) return;
+          if (!done) {
+            buffer.append(decoder.decode(value, { stream: true }));
+            continue;
+          }
+          buffer.append(decoder.decode());
+          const tail = buffer.tail();
+          if (tail) process(controller, tail, "");
+          if (!settled) {
+            settled = true;
+            clear();
+            controller.close();
+          }
+          return;
+        }
+      } catch (error) {
+        if (settled) return;
+        settled = true;
+        clear();
+        cancelReader(error);
+        controller.error(error);
+      } finally {
+        if (settled) releaseQueued();
+      }
+    },
+    cancel(reason) {
+      settled = true;
+      clear();
+      releaseQueued();
+      return reader.cancel(reason);
+    },
+  });
+}

package/src/server/messages-native.ts

@@ -44,6 +44,7 @@ import { classifyError } from "../lib/errors";
 import { relaySseWithPayloadRewrite } from "./sse-payload-rewrite";
 import { redactSecretString } from "../lib/redact";
 import { resolveClientRetryAfter } from "../lib/retry-after";
+import { enrichOpenCodeZenUpstreamMessage } from "../providers/opencode-zen-rate-limit";
 import { isTranslatorBudgetExceededError, type TranslatorBudget } from "../lib/translator-budget";
 import {
   applyReplayRefusalClientHeaders,
@@ -61,7 +62,9 @@ import {
   type UpstreamSendRecovery,
   UPSTREAM_RESET_REPLAY_REFUSED_CODE,
 } from "../lib/upstream-retry";
+import { distributedKeyPhysicalFetch, distributedKeyResponseOwner, recordDistributedResponseFailure } from "../providers/api-key-response-ownership";
 import { providerApiKeySelectionIsCurrent, resolveCurrentProviderApiKeyTransport } from "../providers/api-key-selection";
+import { RequestPacingQueueOverloadError } from "../providers/request-pacing";
 import {
   hasKeyPoolFailover,
   rateLimitRetryDelayMs,
@@ -91,12 +94,14 @@ import {
   resolvePassthroughBodyGuard,
   sanitizePassthroughToolCallIds,
   tapAnthropicSseForLog,
-} from "./claude-messages";
+} from "./messages-shared";
 import { beginInferenceAttempt } from "./inference/attempt";
 import { createFinalRequestLog, type FinalRequestLogMeta } from "./inference/final-log";
 import { registerTurn, unregisterTurn } from "./lifecycle";
 import { nativeMessagesDeclineReason, type NativeMessagesSelector } from "./messages-native-eligibility";
 import { messagesSecondaryInstanceUnavailable } from "./messages-native-selector";
+import { guardNativeMessagesEmptyToolCatalog, nativeMessagesClientToolName, nativeMessagesInlineToolNames } from "./messages-native-tool-guard";
+import { UNDECLARED_TOOL_CALL_ERROR_CODE, undeclaredToolCallMessage } from "./responses-undeclared-tool-guard";
 import {
   nativeOAuthBindingIsCurrent,
   NativeOAuthSelectionChangedError,
@@ -315,6 +320,8 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
   const { req, config, logCtx, logIds, route, body, requestedModel, translatorBudget } = options;
   const nativeInstance = configuredAnthropicInstance(config, route.providerName);
   const requestedStream = body.stream === true;
+  const clientDeclaredEmptyToolCatalog = Array.isArray(body.tools) && body.tools.length === 0;
+  const declaredInlineTools = clientDeclaredEmptyToolCatalog ? nativeMessagesInlineToolNames(body) : undefined;
   logCtx.inboundProtocol = "messages";
   logCtx.model = route.modelId;
   logCtx.provider = route.providerName;
@@ -436,8 +443,16 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
     }
   } else {
     // Same pre-dispatch key preference every direct send path applies (see chat-native.ts).
-    const proactiveKeyProvider = selectProactiveApiKeyTransport(config, route.providerName, route.provider);
-    if (proactiveKeyProvider) route.provider = proactiveKeyProvider;
+    try {
+      const proactiveKeyProvider = selectProactiveApiKeyTransport(config, route.providerName, route.provider);
+      if (proactiveKeyProvider) route.provider = proactiveKeyProvider;
+    } catch (error) {
+      cleanupAbort(); upstream.abort();
+      if (!(error instanceof RequestPacingQueueOverloadError)) throw error;
+      const refusal = fail(429, error.message, "rate_limit_error");
+      refusal.headers.set("Retry-After", String(error.retryAfterSeconds));
+      return refusal;
+    }
   }
   let activeProvider: OcxProviderConfig = oauthBinding ? oauthProvider(oauthBinding) : route.provider;
   stampApiKeyAccountLabel(logCtx, route.providerName, activeProvider);
@@ -521,6 +536,15 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
       && nativeMessagesDeclineReason({ ...route, provider: routed }, body, config, selector) === undefined;
   };
 
+  // Keep the actual failed wire identity if a later recovery is refused before sending.
+  // A 429 remains eligible for explicit same-key retries until that ladder is finished.
+  let pendingDistributedFailure: (() => void) | undefined;
+  let distributedResponseOwnsKey = true;
+  const settleDistributedFailure = () => {
+    const record = pendingDistributedFailure;
+    pendingDistributedFailure = undefined;
+    record?.();
+  };
   const send = async (recovery?: "rate-limit-429" | "oauth-401" | "oauth-account-403" | "key-429" | "key-401"): Promise<Response> => {
     const remaining = remainingTransientSends();
     if (requestTransientPolicy && remaining <= 0) {
@@ -538,7 +562,7 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
         providerFetch(activeProvider, undefined, {
           providerName: route.providerName,
           modelId: route.modelId,
-          dispatchOverride: async (_input, init, execute) => {
+          dispatchOverride: async (_input, init, execute, reacquirePacing) => {
             if (oauthBinding) {
               if (!nativeOAuthRouteIsCurrent(oauthBinding)) throw new NativeOAuthSelectionChangedError();
               // The OAuth twin of the key check below: re-resolve through the same selection
@@ -555,12 +579,25 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
                 rebuildFor(oauthProvider(oauthBinding));
                 logCtx.provider = formatAnthropicProviderForLog(route.providerName, oauthBinding.snapshot.accountId, config);
               }
-            } else if (!providerApiKeySelectionIsCurrent(config, route.providerName, activeProvider)) {
-              const current = resolveCurrentProviderApiKeyTransport(config, route.providerName, activeProvider);
-              if (!current || nativeMessagesDeclineReason({ ...route, provider: current }, body, config, selector) !== undefined) {
-                throw new Error("Provider key selection is no longer available for native Messages");
+            } else {
+              for (let attempt = 0; !providerApiKeySelectionIsCurrent(config, route.providerName, activeProvider); attempt++) {
+                if (attempt >= 3) throw new Error("Provider key selection changed repeatedly before native Messages dispatch");
+                let current = resolveCurrentProviderApiKeyTransport(config, route.providerName, activeProvider);
+                if (!current && activeProvider.requestPacing?.enabled
+                  && (activeProvider.requestPacing.keys || activeProvider.requestPacing.keySelection === "round-robin")) {
+                  const fresh = resolveCurrentProviderApiKeyTransport(config, route.providerName, { ...activeProvider, _apiKeyAttempt: undefined });
+                  if (fresh) current = selectProactiveApiKeyTransport(config, route.providerName, fresh) ?? fresh;
+                }
+                if (!current || nativeMessagesDeclineReason({ ...route, provider: current }, body, config, selector) !== undefined) {
+                  throw new Error("Provider key selection is no longer available for native Messages");
+                }
+                rebuildFor(current);
+                if (current.requestPacing?.enabled
+                  && (current.requestPacing.keys || current.requestPacing.keySelection === "round-robin")) {
+                  if (!reacquirePacing) throw new Error("Refreshed native Messages dispatch requires pacing readmission");
+                  await reacquirePacing(current, route.modelId);
+                }
               }
-              rebuildFor(current);
             }
             // The retry closure may hold a pre-reselection request: send the current one whole.
             const wire = activeRequest;
@@ -579,6 +616,7 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
             }
             const releaseFamily = snapshot && oauthBinding ? anthropicModelQuotaFor(oauthBinding.instance).claimAnthropicFamilyRevalidation(snapshot.accountId, route.modelId) : () => {};
             if (!releaseFamily) throw new AnthropicAccountCooldownError(1);
+            const selection = activeProvider._apiKeyAttempt;
             let dispatched: Response;
             const spendReport = createPhysicalSendReporter(physicalBudget, () => ({
               poolId: logCtx.spendPoolId ?? route.providerName, identityId: logCtx.accountLogLabel,
@@ -599,7 +637,9 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
               if (snapshot && !sendOwner) throw new NativeOAuthSelectionChangedError();
               physicalSendsUsed++;
               dispatched = await sendWithConnectionPolicy(
-                anthropicBillingPhysicalFetch((activeProvider as OcxProviderTransport).fetch ?? execute, route.providerName, activeProvider),
+                distributedKeyPhysicalFetch(
+                  anthropicBillingPhysicalFetch((activeProvider as OcxProviderTransport).fetch ?? execute, route.providerName, activeProvider),
+                  route.providerName, activeProvider, wire.url, activeProvider.apiKeyTransport === "bearer" ? "authorization" : "x-api-key"),
                 wire.url,
                 applyUpstreamRecoveryInit({ ...init, method: "POST", headers, body: wire.body }, transportRecovery),
                 { providerName: route.providerName, provider: activeProvider },
@@ -623,6 +663,14 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
                 }
               } catch { /* Passive observation must not fail the response. */ }
             }
+            const ownsDistributedKey = !selection?.distributed
+              || distributedKeyResponseOwner(dispatched, config, route.providerName) !== null;
+            distributedResponseOwnsKey = ownsDistributedKey;
+            const failureStatus = dispatched.status;
+            pendingDistributedFailure = selection?.distributed && ownsDistributedKey && (failureStatus === 401 || failureStatus === 429)
+              && !isNonReplayableResponse(dispatched)
+              ? () => { recordDistributedResponseFailure(dispatched, config, route.providerName, req.signal); }
+              : undefined;
             if (!dispatched.ok) await recordKeyAttemptFailure(logCtx, dispatched, init.signal ?? upstream.signal);
             return dispatched;
           },
@@ -647,25 +695,28 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
   let response: Response;
   try {
     response = await send();
-    const retryPolicy = oauthBinding ? undefined : rateLimitRetryPolicyFor(activeProvider);
+    let retryPolicy: ReturnType<typeof rateLimitRetryPolicyFor> | undefined;
     let retries = 0;
     let billingRecoveryActive = false;
     const keySendAvailable = () => transientSendAvailable()
       && (!billingRecoveryActive || Math.max(physicalSendsUsed, physicalBudget.used) < physicalBudget.policy.maxTotalModelSends);
-    for (;;) {
+    const recoveryPasses = activeProvider._apiKeyAttempt?.distributed ? activeProvider.apiKeyPool?.length ?? 1 : 1;
+    for (let pass = 0; ; pass++) {
       const priorResponse = response;
       // A credential-scoped 401 on a static key pool says nothing about the sibling keys.
-      while (response.status === 401 && hasKeyPoolFailover(activeProvider) && keySendAvailable()) {
+      while (response.status === 401 && distributedResponseOwnsKey && hasKeyPoolFailover(activeProvider) && keySendAvailable()) {
         const rotated = rotateProviderTransportOn401(config, route.providerName, activeProvider, {
           now: Date.now(),
           attemptedKey: activeProvider.apiKey,
+          attemptedSelection: activeProvider._apiKeyAttempt,
         });
+        pendingDistributedFailure = undefined; // Rotation already records this physical failure.
         if (!rotated) break;
         discard(response);
         rebuildFor(rotated);
         response = await send("key-401");
       }
-      while ((response.status === 400 || response.status === 402) && hasKeyPoolFailover(activeProvider)) {
+      while ((response.status === 400 || response.status === 402) && distributedResponseOwnsKey && hasKeyPoolFailover(activeProvider)) {
         const rotated = await rotateAnthropicBillingKeyOnResponse(response, config, route.providerName, activeProvider, { signal: upstream.signal });
         if (!rotated) break;
         billingRecoveryActive = true;
@@ -674,9 +725,11 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
         rebuildFor(rotated);
         response = await send("key-401");
       }
+      if (pass === 0) retryPolicy = oauthBinding ? undefined : rateLimitRetryPolicyFor(activeProvider);
       // A refusal this proxy synthesized for a reset replay is not a provider rate limit.
       while (
         response.status === 429
+        && distributedResponseOwnsKey
         && !isNonReplayableResponse(response)
         && retryPolicy
         && retries < retryPolicy.attempts
@@ -691,13 +744,14 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
         if (upstream.signal.aborted) throw upstream.signal.reason;
         response = await send("rate-limit-429");
       }
-      while (response.status === 429 && !isNonReplayableResponse(response) && hasKeyPoolFailover(activeProvider)) {
+      while (response.status === 429 && distributedResponseOwnsKey && !isNonReplayableResponse(response) && hasKeyPoolFailover(activeProvider)) {
         const rotated = rotateProviderTransportOn429(config, route.providerName, activeProvider, {
           retryAfter: response.headers.get("retry-after"),
           now: Date.now(),
           attemptedKey: activeProvider.apiKey,
           attemptedSelection: activeProvider._apiKeyAttempt,
         });
+        pendingDistributedFailure = undefined; // Rotation already records this physical failure.
         if (!rotated) break;
         // Rotation already recorded the cooldown; keep the terminal 429 when no send remains.
         if (!keySendAvailable()) break;
@@ -705,13 +759,17 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
         rebuildFor(rotated);
         response = await send("key-429");
       }
-      // A sibling's next refusal may change class; the same counters survive that transition.
-      if (response !== priorResponse && (
+      if (response === priorResponse || isNonReplayableResponse(response) || !keySendAvailable()) break;
+      // Billing class transitions share the physical-send ceiling; distributed-only
+      // transitions additionally retain their original bounded pool-pass allowance.
+      if (distributedResponseOwnsKey && (
         (billingRecoveryActive && [401, 429].includes(response.status))
         || (activeProvider.adapter === "anthropic" && hasKeyPoolFailover(activeProvider) && [400, 402].includes(response.status))
       )) continue;
-      break;
+      if (!activeProvider._apiKeyAttempt?.distributed || !distributedResponseOwnsKey
+        || (response.status !== 401 && response.status !== 429) || pass + 1 >= recoveryPasses) break;
     }
+    settleDistributedFailure();
     const oauthRetryKey = {};
     const triedAccountIds = new Set<string>();
     let oauthFailovers = 0;
@@ -749,7 +807,13 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
     cleanupAbort();
     upstream.abort();
     if (req.signal.aborted) return fail(499, "Client cancelled request", "api_error");
+    settleDistributedFailure();
     const sendError = error instanceof UpstreamRetryEvidenceError ? error.cause : error;
+    if (sendError instanceof RequestPacingQueueOverloadError) {
+      const refusal = fail(429, sendError.message, "rate_limit_error");
+      refusal.headers.set("Retry-After", String(sendError.retryAfterSeconds));
+      return refusal;
+    }
     if (sendError instanceof SendBudgetExhaustedError) return fail(429, sendError.message, "send_budget_exhausted", "send_budget_exhausted");
     if (sendError instanceof NativeMessagesSpendRefusal) {
       const refusal = workflowRefusalResponse("workflow-spend-exhausted", logCtx);
@@ -782,7 +846,7 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
       upstream.abort();
       return fail(499, "Client cancelled request", "api_error");
     }
-    return retainUpstreamMessagesRequestId(nativeMessagesErrorResponse(response, bodyText, finishLog), response.headers);
+    return retainUpstreamMessagesRequestId(nativeMessagesErrorResponse(response, bodyText, finishLog, route.providerName, activeProvider), response.headers);
   }
 
   const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
@@ -794,15 +858,22 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
     const renamed = activeRequest.oauthToolNames
       ? restoreOAuthToolNamesInSse(observed, activeRequest.oauthToolNames, translatorBudget)
       : observed;
-    const source = echoRequestedModel(renamed, requestedModel);
+    const echoed = echoRequestedModel(renamed, requestedModel);
+    let toolRefusal: string | undefined;
+    const source = clientDeclaredEmptyToolCatalog
+      ? guardNativeMessagesEmptyToolCatalog(echoed, translatorBudget, message => {
+        toolRefusal = message;
+        logCtx.errorCode = UNDECLARED_TOOL_CALL_ERROR_CODE;
+      }, declaredInlineTools)
+      : echoed;
     if (requestedStream) {
       transferTurnToStream();
       const relayed = tapAnthropicSseForLog(source, logCtx, (status, meta) => {
         try {
           cleanupAbort();
           bindUsage(logCtx.usage);
-          finishLog(status, undefined, meta);
-          if (meta.closeReason !== "terminal") upstream.abort();
+          finishLog(toolRefusal ? 502 : status, toolRefusal, toolRefusal ? { ...meta, terminalStatus: "failed" } : meta);
+          if (toolRefusal || meta.closeReason !== "terminal") upstream.abort();
         } finally {
           releaseStreamTurn();
         }
@@ -833,6 +904,11 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
       if (message.type === "error") {
         const error = isRec(message.error) ? message.error : {};
         const text = typeof error.message === "string" ? error.message : "upstream stream failed";
+        if (toolRefusal) {
+          upstream.abort();
+          finishLog(502, toolRefusal, { closeReason: "terminal", terminalStatus: "failed" });
+          return fail(502, toolRefusal, "api_error", UNDECLARED_TOOL_CALL_ERROR_CODE);
+        }
         // The tap's own verdict (a reset, a stall, the byte cap) closes this row with the same meta
         // as the streaming lane's row; a plain upstream error event keeps the non_stream row.
         const tapMeta = tapState.meta;
@@ -884,6 +960,11 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
   const message = activeRequest.oauthToolNames
     ? restoreOAuthToolNamesInMessage(parsedMessage, activeRequest.oauthToolNames)
     : parsedMessage;
+  const undeclaredTool = clientDeclaredEmptyToolCatalog ? nativeMessagesClientToolName(message, declaredInlineTools) : undefined;
+  if (undeclaredTool !== undefined) {
+    logCtx.errorCode = UNDECLARED_TOOL_CALL_ERROR_CODE;
+    return fail(502, undeclaredToolCallMessage(undeclaredTool), "api_error", UNDECLARED_TOOL_CALL_ERROR_CODE);
+  }
   bindUsage(anthropicUsageToOcx(isRec(message.usage) ? message.usage : undefined));
   if (logIds) recordFirstOutput(logCtx, logIds.start);
   try {
@@ -919,7 +1000,7 @@ function isNativeOverflowError(error: Rec, message: string): boolean {
  * Messages path, so a client sees the same contract on either lane: transient 5xx become 529
  * with a retry hint, and a proxy-side replay refusal keeps its no-retry marking.
  */
-function nativeMessagesErrorResponse(response: Response, bodyText: string, finishLog: FinishLog): Response {
+function nativeMessagesErrorResponse(response: Response, bodyText: string, finishLog: FinishLog, providerName: string, provider: OcxProviderConfig): Response {
   let upstreamType: string | undefined;
   let upstreamCode: string | undefined;
   let upstreamMessage: string | undefined;
@@ -933,8 +1014,20 @@ function nativeMessagesErrorResponse(response: Response, bodyText: string, finis
     }
   } catch { /* keep generic classification */ }
   const detail = formatAnthropicErrorBody(response.status, response.headers, bodyText);
-  const message = upstreamMessage
+  const rawMessage = upstreamMessage
     ?? (detail ? `Provider error ${response.status}: ${detail}` : `Provider error ${response.status}`);
+  const message = enrichOpenCodeZenUpstreamMessage(rawMessage, {
+    status: response.status,
+    providerName,
+    baseUrl: provider.baseUrl,
+    adapter: provider.adapter,
+    authMode: provider.authMode,
+    hasApiKey: Boolean(provider.apiKey?.trim()),
+    upstreamRetryAfter: response.headers.get("retry-after"),
+    upstreamErrorType: upstreamType,
+    upstreamErrorCode: upstreamCode,
+    supportsHttpSameKeyRetry: true,
+  });
   const classified = classifyError(
     response.status,
     upstreamType ?? (response.status === 401 ? "authentication_error"