fix(bridge): end the turn on a terminal upstream refusal instead of a retryable incomplete

docs-site/src/content/docs/reference/proxy-formats.md

@@ -302,7 +302,20 @@ returns an error instead of partial JSON with HTTP 200. Streaming callers are un
 When a provider filters or truncates a response, an unfinished tool call remains `incomplete`
 in both JSON and SSE. Partial output is preserved, and the bridge does not emit an argument
 completion event for that open call. Calls already completed keep their status. This preserves
-the provider outcome; client retry behavior for incomplete responses is unchanged.
+the provider outcome.
+
+On the Responses streaming wire, an explicit non-retryable content-filter stop from
+Anthropic (`refusal` / `content_filter`) or Kiro (`CONTENT_FILTERED` /
+`GUARDRAIL_INTERVENED`) ends with `response.failed`, `error.code: "invalid_prompt"`,
+and `retryable: false`. This prevents clients that retry incomplete streams from
+resending the refused context. Usage and partial output are preserved. Web-search
+and image sidecars stop without executing calls from that refused iteration or
+asking the model again, on every inbound wire.
+
+Buffered Responses JSON retains `status: "incomplete"`; Chat Completions retains
+`finish_reason: "content_filter"`, and Messages retains `stop_reason: "refusal"`.
+A content filter without an explicit non-retryable verdict, token limits, stalls,
+and EOFs keep their existing incomplete behavior.
 
 On the pending `dev` implementation for #4112, a final upstream HTTP 413 on this surface
 is classified as `invalid_request_error` / `context_length_exceeded`. Non-streaming callers

scripts/test-layout/layout.json

@@ -3,6 +3,11 @@
   "root": "tests",
   "explicitShards": ["layout-clients.json"],
   "explicit": { "service-log.test.ts": "service", "messages-native-empty-inline.test.ts": "claude-integration",
+    "bridge-terminal-refusal.test.ts": "adapters",
+    "loop-terminal-refusal.test.ts": "images",
+    "web-search-terminal-refusal.test.ts": "web-search",
+    "combo-terminal-refusal.test.ts": "routing",
+    "server-terminal-refusal-wiring.test.ts": "server",
     "owner-registry-isolation.test.ts": "config",
     "codex-history-pending-wal.test.ts": "codex-integration", "responses-anthropic-billing-send-budget.test.ts": "responses", "anthropic-billing-ownership.test.ts": "adapters/anthropic", "server-anthropic-billing.test.ts": "server", "server-anthropic-billing-boundaries.test.ts": "server", "router-anthropic-billing-failover.test.ts": "routing", "anthropic-billing-refusal.test.ts": "adapters/anthropic", "messages-request-id-headers.test.ts": "claude-integration", "bounded-file-read.test.ts": "lib", "responses-undeclared-tool-guard-inbound.test.ts": "responses", "explicit-empty-tool-catalog.test.ts": "responses", "explicit-empty-tool-catalog-history.test.ts": "responses",
     "messages-request-id-endpoint.test.ts": "claude-integration",

src/adapters/anthropic.ts

@@ -312,11 +312,12 @@ function isAnthropicContentFilterStopReason(
 }
 
 /**
- * Anthropic `refusal` / `content_filter` is a permanent sampling decision, not a disconnect.
- * Emitting `done` with that stopReason used to surface as `response.incomplete` without
- * `retryable`, which Codex treats as a dropped stream and retries five times (#4312).
- * The explicit incomplete event is what the bridge already forwards into
- * `incomplete_details.retryable`. Usage is preserved: a filtered turn still consumed tokens.
+ * Anthropic `refusal` / `content_filter` is a permanent sampling decision, not a disconnect
+ * (#4312). Codex does not read `incomplete_details.retryable`: it retries every
+ * `response.incomplete`. The explicit `retryable: false` verdict here is the marker the bridge
+ * uses to deliver the turn to a Responses client as a terminal `response.failed` instead
+ * (`src/bridge/terminal-refusal.ts`); a `done` with that stopReason carries no verdict and
+ * stays a plain incomplete. Usage is preserved: a filtered turn still consumed tokens.
  * `max_tokens` stays a `done` so the client can continue from a legitimate truncation.
  */
 function anthropicContentFilterIncomplete(
@@ -1222,8 +1223,8 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
           return;
         }
         // Refusal / content_filter must not look like a dropped stream. `done` with that
-        // stopReason becomes `response.incomplete` without `retryable`, and Codex retries
-        // the same refusal five times (#4312).
+        // stopReason carries no verdict, so the bridge could not tell it from a retryable
+        // incomplete and Codex would re-send the same refusal (#4312).
         if (isAnthropicContentFilterStopReason(pendingStopReason)) {
           yield anthropicContentFilterIncomplete(pendingStopReason, usageFromAnthropic(pendingUsage));
           return;
@@ -1418,7 +1419,7 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
           }
           // Same rule as emitDone: refusal / content_filter is a permanent decision, not a
           // disconnect. This branch bypasses emitDone, so the check has to be repeated here
-          // or the EOF route still emits `done` and Codex retries the refusal (#4312).
+          // or the EOF route emits a verdict-less `done` the bridge cannot make terminal (#4312).
           if (isAnthropicContentFilterStopReason(pendingStopReason)) {
             emittedDone = true;
             yield anthropicContentFilterIncomplete(pendingStopReason, usageFromAnthropic(pendingUsage));

src/bridge/sse.ts

@@ -12,7 +12,7 @@ import {
   classifyError,
   cyberPolicyErrorType,
   CYBER_POLICY_ERROR_CODE,
-  isCyberPolicyCode,
+  isTerminalRefusalCode,
   type OcxErrorPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
@@ -50,6 +50,7 @@ import {
 } from "../lib/translator-budget";
 import { adapterFailureFromEvent, emptyChunks, joinChunks, ownedBudgetAbandonedMs, responsesUsage, toolCallArgumentsCouldBeJson, toolCallArgumentsUsable, uuid, webSearchAction } from "./internal";
 import type { OutputItem, StringChunks } from "./internal";
+import { terminalRefusalFailure } from "./terminal-refusal";
 
 function sseEvent(name: string, data: Record<string, unknown>): string {
   return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
@@ -120,6 +121,12 @@ export function bridgeToResponsesSSE(
      * would reach the client under the invented name instead of the normalized one.
      */
     enforceDeclaredToolNames?: boolean;
+    /**
+     * Deliver a non-retryable upstream refusal as `response.failed` with a terminal-refusal code
+     * instead of `response.incomplete` (see `./terminal-refusal`). Set only for the Responses
+     * inbound wire: the chat and Anthropic encoders read the incomplete to report a filter stop.
+     */
+    terminalRefusalAsFailed?: boolean;
     /** Declared parameter schema per tool name; repairs integral-float integer args (#1611). */
     toolParameterSchemas?: ReadonlyMap<string, Record<string, unknown>>;
     /**
@@ -1287,6 +1294,19 @@ export function bridgeToResponsesSSE(
               flushHiddenReasoningEnvelope();
               options?.onUsage?.(event.usage);
               await awaitThoughtSignatureDurability();
+              const refusal = options?.terminalRefusalAsFailed ? terminalRefusalFailure(event) : undefined;
+              if (refusal) {
+                emit("response.failed", {
+                  response: {
+                    ...responseSnapshot("failed", finishedItems, event.endTurn),
+                    usage: responsesUsage(event.usage),
+                    ...refusal,
+                  },
+                });
+                reportTerminal("failed");
+                terminalEvent = true;
+                break;
+              }
               emit("response.incomplete", {
                 response: {
                   ...responseSnapshot("incomplete", finishedItems, event.endTurn),
@@ -1325,7 +1345,7 @@ export function bridgeToResponsesSSE(
                   ...(event.usage ? { usage: responsesUsage(event.usage) } : {}),
                   error: failure.error,
                   last_error: failure.error,
-                  ...(isCyberPolicyCode(failure.error.code)
+                  ...(isTerminalRefusalCode(failure.error.code)
                     ? { retryable: false }
                     : event.retryable !== undefined ? { retryable: event.retryable } : {}),
                 },
@@ -1366,7 +1386,7 @@ export function bridgeToResponsesSSE(
               ...responseSnapshot("failed", finishedItems),
               error: failure,
               last_error: failure,
-              ...(isCyberPolicyCode(failure.code) ? { retryable: false } : {}),
+              ...(isTerminalRefusalCode(failure.code) ? { retryable: false } : {}),
             },
           });
           reportTerminal("failed");

src/bridge/terminal-refusal.ts

@@ -0,0 +1,59 @@
+import type { AdapterEvent } from "../types";
+import type { OcxErrorPayload } from "../lib/errors";
+import { redactSecretString } from "../lib/redact";
+
+/**
+ * The terminal-refusal code Codex ends a turn on. It is a member of `TERMINAL_REFUSAL_CODES`
+ * in `src/lib/errors.ts`, and the one that says "this prompt, as sent, is refused" without
+ * claiming a specific policy family the upstream never named.
+ */
+const TERMINAL_REFUSAL_FAILED_CODE = "invalid_prompt";
+
+interface TerminalRefusalFailure {
+  error: OcxErrorPayload;
+  last_error: OcxErrorPayload;
+  retryable: false;
+}
+
+/**
+ * Client-visible copy: what happened, and that resending the same context cannot help. It points
+ * at a new conversation rather than a new turn, because a later turn replays the refused context.
+ */
+function terminalRefusalMessage(detail: string | undefined): string {
+  const reason = detail?.trim() ? ` (${redactSecretString(detail.trim())})` : "";
+  return `The upstream model refused this request${reason}. `
+    + "Retrying with the same conversation context will not succeed; change the request or start a new conversation.";
+}
+
+/**
+ * An adapter `incomplete` that is a non-retryable upstream refusal: a content filter carrying an
+ * explicit `retryable: false` verdict. A filter without the verdict, an output cap, a stall and an
+ * adapter EOF do not qualify. The sidecar loops read this too: a refused iteration ends the turn,
+ * so a sidecar call it carried is neither run nor answered with another model request.
+ */
+export function isTerminalRefusalIncomplete(event: AdapterEvent | undefined): boolean {
+  return event?.type === "incomplete" && event.reason === "content_filter" && event.retryable === false;
+}
+
+/**
+ * `response.failed` fields for an adapter `incomplete` that is a non-retryable upstream refusal
+ * (#4312), or `undefined` when the event is anything else. The Anthropic and Kiro adapters are
+ * the ones that emit it today.
+ *
+ * codex-rs maps every `response.incomplete` to a retryable stream error and never reads
+ * `incomplete_details.retryable`, so a refusal delivered that way is re-sent through the whole
+ * stream retry budget. It only ends the turn on `response.failed` carrying a terminal-refusal
+ * `error.code`. Only an explicit `retryable: false` content filter qualifies: a filter without
+ * the verdict, an output cap, a stall and an adapter EOF stay `response.incomplete`.
+ */
+export function terminalRefusalFailure(
+  event: Extract<AdapterEvent, { type: "incomplete" }>,
+): TerminalRefusalFailure | undefined {
+  if (!isTerminalRefusalIncomplete(event)) return undefined;
+  const error: OcxErrorPayload = {
+    type: "invalid_request_error",
+    code: TERMINAL_REFUSAL_FAILED_CODE,
+    message: terminalRefusalMessage(event.message),
+  };
+  return { error, last_error: error, retryable: false };
+}

src/images/loop.ts

@@ -20,6 +20,7 @@ import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
 import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaque-metadata";
 import type { AttemptRecoveryKind } from "../usage/log";
 import { bridgeToResponsesSSE } from "../bridge";
+import { isTerminalRefusalIncomplete } from "../bridge/terminal-refusal";
 import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { applyUpstreamRecoveryInit, fetchWithResetRetry, prepareSameTarget429Wait } from "../lib/upstream-retry";
@@ -355,6 +356,8 @@ export interface ImageBridgeDeps {
   onCompletedResponse?: (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => void;
   /** WebSocket Responses path only — leave response id empty for protocol compatibility. */
   forceEmptyResponseId?: boolean;
+  /** Responses inbound only: deliver a non-retryable upstream refusal as `response.failed`. */
+  terminalRefusalAsFailed?: boolean;
 }
 
 /**
@@ -865,7 +868,10 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           // Loop (fulfill + re-ask) ONLY when the model's actionable output is purely image_gen. A
           // real tool call means this turn is terminal for Codex — finalize so those calls reach
           // Codex. forceFinal also finalizes.
-          const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall && !forceFinal;
+          // A refused iteration also finalizes: fulfilling its media call would re-ask the model
+          // with the refused context (#7148).
+          const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall && !forceFinal
+            && !split.passthrough.some(isTerminalRefusalIncomplete);
           if (!shouldLoop) {
             if (hiddenUsage) {
               for (let i = split.passthrough.length - 1; i >= 0; i--) {
@@ -1089,6 +1095,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       replayCacheScope: parsed._reasoningReplayScope,
       ...(deps.clientToolCatalogRestriction ? { ...deps.clientToolCatalogRestriction, enforceDeclaredToolNames: false } : {}),
       ...(deps.forceEmptyResponseId ? { responseId: "" } : {}),
+      ...(deps.terminalRefusalAsFailed ? { terminalRefusalAsFailed: true } : {}),
       hideThinkingSummary: parsed.options.hideThinkingSummary,
       hideRawReasoning: parsed.options.hideRawReasoning,
       stallTimeoutSec: deps.stallTimeoutSec,

src/server/responses/adapter-delivery.ts

@@ -205,6 +205,7 @@ export async function deliverAdapterResponse(
         declaredToolNames,
         bareCustomToolNames,
         enforceDeclaredToolNames: options.inboundWire !== "chat" && options.inboundWire !== "anthropic",
+        terminalRefusalAsFailed: options.inboundWire !== "chat" && options.inboundWire !== "anthropic",
         toolParameterSchemas,
         ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
         ...(routedCompaction ? { compaction: true } : {}),

src/server/responses/run-turn-execution.ts

@@ -851,6 +851,8 @@ export async function executeResponsesRunTurn(
           declaredToolNames,
           bareCustomToolNames,
           enforceDeclaredToolNames,
+          // Same wire split: only a Responses client (Codex) needs the refusal as a failure.
+          terminalRefusalAsFailed: enforceDeclaredToolNames,
           toolParameterSchemas,
           ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
           ...(routedCompaction ? { compaction: true } : {}),

src/server/responses/sidecar-execution.ts

@@ -555,6 +555,7 @@ export async function executeResponsesSidecars(
         ? null : rateLimitRetryPolicyFor(route.provider),
       onFirstOutput: noteSidecarOutput,
       ...(options.forceEmptyResponseId ? { forceEmptyResponseId: true } : {}),
+      terminalRefusalAsFailed: inboundWire !== "chat" && inboundWire !== "anthropic",
       onCompletedResponse: (response, providerState) => {
         const served = transportState.replayOAuthCredentialSnapshot;
         if (route.providerName === "kiro" && response.status === "completed" && served
@@ -636,6 +637,7 @@ export async function executeResponsesSidecars(
       settings: wsPlan.settings,
       maxSearches: wsPlan.maxSearches,
       forceEmptyResponseId: true,
+      terminalRefusalAsFailed: inboundWire !== "chat" && inboundWire !== "anthropic",
       abortSignal: options.abortSignal,
       onFirstOutput: noteSidecarOutput,
       onRequestBuilt: request => {

src/web-search/loop.ts

@@ -6,6 +6,7 @@ import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaqu
 import type { AttemptRecoveryKind } from "../usage/log";
 import { isTruncatedStopReason } from "../responses/truncated-stop-reason";
 import { bridgeToResponsesSSE } from "../bridge";
+import { isTerminalRefusalIncomplete } from "../bridge/terminal-refusal";
 import { guardEmptyToolCatalogStream, type ClientToolCatalogRestriction } from "../lib/empty-tool-catalog";
 import { runWebSearch, type SidecarOutcome, type SidecarOutcomeRecorder, type SidecarSettings } from "./executor";
 import { runAnthropicWebSearch } from "./anthropic-executor";
@@ -299,6 +300,8 @@ export interface WebSearchLoopDeps {
   settings: SidecarSettings;
   maxSearches: number;
   forceEmptyResponseId?: boolean;
+  /** Responses inbound only: deliver a non-retryable upstream refusal as `response.failed`. */
+  terminalRefusalAsFailed?: boolean;
   abortSignal?: AbortSignal;
   recordSidecarOutcome?: SidecarOutcomeRecorder;
   beforeSidecarDispatch?: () => void;
@@ -916,7 +919,10 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
           // limit-reached result instead of failing the turn (#6464: stripping
           // the declaration makes some models emit the raw call as visible
           // text).
-          const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall;
+          // A refused iteration ends the turn even when it carried a search call: running the
+          // search would send the refused context back to the model (#7148).
+          const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall
+            && !split.passthrough.some(isTerminalRefusalIncomplete);
           if (!shouldLoop) {
             // #1001: a forced-answer pass that ends `done` must have produced
             // usable output — never a malformed tool call, and never silence.
@@ -1008,6 +1014,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       replayCacheScope: parsed._reasoningReplayScope,
       ...(deps.clientToolCatalogRestriction ? { ...deps.clientToolCatalogRestriction, enforceDeclaredToolNames: false } : {}),
       ...(deps.forceEmptyResponseId ? { responseId: "" } : {}),
+      ...(deps.terminalRefusalAsFailed ? { terminalRefusalAsFailed: true } : {}),
       hideThinkingSummary: parsed.options.hideThinkingSummary,
       hideRawReasoning: parsed.options.hideRawReasoning,
       ...(deps.stallTimeoutSec !== undefined ? { stallTimeoutSec: deps.stallTimeoutSec } : {}),