UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,826 lines • 104 kB
import { selectResponseReplayOwner } from "./replay-owner";
import { isPlaintextV2AgentMessagesEnabled } from "../../config/multi-agent-surface";
import { projectLocalModelRefusalLog } from "../request-log-failure-detail";
import { attributePhysicalAttempt } from "../request-log-failure-attribution";
import { failLinkTurnExpansion, markLinkTurnMissing, observeLinkTurnExpansion } from "../link-turn";
import { inputAdmissionRefusalMessage } from "./input-admission";
import { clientFacingModelLabel, clientFacingModelText } from "../../lib/error-destination";
import { markProxyError } from "../../lib/client-error-body";
import { completeClaudeBridgePoolIdentity } from "../claude-bridge-pool-session";
import type { HandleResponsesOptions, ResponsesRequestContext, ResponsesAdmissionState, ResponsesDispatchers } from "./core-options";
import type { PolicyRequestEvidence } from "../../routing/evaluator";
import type { RequestLogContext } from "../request-log";
import { addProtocolEntryReason, markProtocolEntry, protocolMarkFeatures } from "../../protocols/trace";
import { admitsHostedAdvisor, scopedAnthropicServerTools } from "../messages-native-scope";
import { advisorServerToolDestination } from "../../adapters/anthropic/advisor-tool";
import { isAntigravityRoute } from "../antigravity-direct-eligibility";
import { capturePolicyRequestRoute, assertPolicyNormalizedRoute, recordPolicyPreparedDestination, policyCandidateRefusalResponse, markPolicyCandidateRefusal, MandatoryToolChoiceUnavailableError, mandatoryToolChoiceUnavailableResponse } from "./policy-request-scope";
import {
  agentTaskRecoveryConfig,
  restoreCachedEncryptedAgentTasks,
  recoverEncryptedAgentTaskWithResult,
} from "./agent-task-recovery";
import { admitParsedJsonRequestBody, readJsonRequestBody, resolveInboundBodyLimitBytes, takeParsedRequestBody } from "../request-decompress";
import {
  clientCancelledResponse,
  decodeRequestErrorResponse,
  comboUnavailable,
  unreadableEncryptedAgentTaskResponse,
} from "./core-errors";
import { parseSyntheticRowId } from "../fast-row";
import { resolveComboId, comboIdFromRawBody, comboExclusion, NoAvailableComboTargetsError, pickComboTarget } from "../../combos";
import { INTERCEPT_TARGET_UNAVAILABLE_CODE, interceptTargetUnavailableResponse, resolveChosenTarget, resolveShadowCallTarget } from "./shadow-target-availability";
import {
  MEMORY_MODEL_TARGET_UNAVAILABLE_CODE,
  configuredMemoryModel,
  detectMemoryModelPhase,
  memoryModelRouteReason,
  memoryModelTargetUnavailableResponse,
} from "./memory-models";
import { recallComboForLane } from "./combo-session-recall";
import {
  sessionLaneIdFromRequest,
  conversationIdFromResponsesRequest,
  assignNativeLogConversationId,
  fillHermesLogConversationFallback,
  nativeLogConversationIdFromHeaders,
  sessionIdHeaderFromRequest,
  reasoningReplayConversationIdFromResponsesRequest,
} from "../request-log-conversation";
import { contextPrincipalIdOf, resolveContextPrincipal } from "../auth-cors";
import { responseTurnMembership } from "./turn-membership";
import { resolveSkillsSnapshotScopeKey, snapshotSkillsCatalogInBody } from "./skills-snapshot";
import {
  isShadowSourceModel,
  shadowCallPreservesSelectedModel,
  shadowSourceModelPrefix,
  shouldInterceptShadowCall,
} from "../../lib/shadow-call";
import { sanitizeLogMetadataString } from "../../lib/redact";
import {
  hasUnreadableEncryptedAgentTask,
  sanitizeEncryptedContentInPlace,
  stripAgentMessageCiphertextInPlace,
} from "./encrypted-payload";
import {
  codexPoolAffinityKey,
  codexRequestAffinityKey,
  previewCodexPoolLineage,
  applyCodexAuthContextToProvider,
  releaseCodexAuthContextProbeLease,
  hasCallerCodexBearer,
  requestOwnedMainPinState,
  requestOwnedMainCredentialIsLive,
} from "../../codex/auth-context";
import {
  copyPreviousResponseReplayProvenance,
  expandPreviousResponseInput,
  previousResponseRestoredPrefixLength,
  previousResponseReplayFailure,
  markBodyNonPersistable,
  previousResponseProviderState,
} from "../../responses/state";
import { formatErrorResponse } from "../../bridge";
import { chatCanPreserveMandatoryToolChoice } from "./combo-required-tool-contract";
import { mapCodexAuthContextErrorToResponse } from "./codex-auth-error";
import type { OcxParsedRequest } from "../../types";
import { buildToolBridgeMaps } from "./collaboration";
import { parseRequest } from "../../responses/parser";
import { responsesHasFileImage, responsesHasInstructionImage } from "../../adapters/claude-cli/instruction-images";
import { anthropicSessionKeyFromParts } from "../../oauth/anthropic-routing";
import { configuredAnthropicInstance } from "../../providers/anthropic-instance";
import { isTranslatorBudgetExceededError } from "../../lib/translator-budget";
import { bindTurnTerminationScope, rememberDeliveredFinalAnswer } from "../../responses/turn-termination";
import { beginRequestAttempt, finishRequestAttempt, markLocalRequestLogRefusal, noteAttemptSend, noteCodexSelectionAffinity, observeCacheDiagnosticInbound, rebindCacheDiagnosticBody, requestLogSpeedLabel, readConfiguredCodexServiceTier, usageFromResponsesPayload } from "../request-log";
import type { PersistedUsageAttempt } from "../../usage/log";
import type { RouteResult } from "../../router";
import {
  captureRouteStaticPolicy,
  previewRouteModel,
  routeConcreteModel,
  routeCompactionModel,
  routeModel,
  NoEligiblePolicyCandidateError,
  AnthropicSecondaryInstanceUnavailableError,
} from "../../router";
import { evidenceFromBody } from "../../routing/request-evidence";
import { resolvePolicyProfileId } from "../../routing/profile";
import { OPENAI_CODEX_PROVIDER_ID, isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
import { resolveNativeReasoningRetention } from "../../config/schema/native-reasoning-retention";
import { isThreadSpawnRequest } from "../effort-policy";
import {
  resolveSubagentFallbackChain,
  maybePrimeSubagentQuota,
  applySubagentModelFallback,
} from "../../codex/subagent-model-fallback";
import { codexAccountSelectionForTurn } from "../lifecycle";
import { isNativeMainTrafficBlocked } from "../../codex/native-profile-startup";
import type {
  SubagentPoolAccountPreview,
  SubagentModelEligibleAccountIds,
} from "../../codex/subagent-model-fallback";
import {
  codexRouteCredentialDomainHeaders,
  codexRouteCredentialOwnership,
  mainHardLockFallbackCallerCheck,
  resolveResponsesCodexAuth,
  withClaudeNativeSession,
} from "./core-auth";
import {
  resolveSubagentFallbackModelEligibility,
  canPassThroughEncryptedV2AgentTask,
  applyFinalRouteRequestNormalization,
  previewXaiOauthWireModel,
} from "./core-normalize";
import {
  cachedDeniedCodexAccountIdsForModel,
  resolveCodexModelEntitlements,
} from "../../codex/model-entitlements";
import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/main-account";
import {
  previewCodexAccountForRequest,
  codexQuotaScopeForModel,
  formatCodexProviderForLog,
} from "../../codex/routing";
import { isInjectionDebugEnabled } from "../../lib/debug-settings";
import { injectionDebugLog } from "../../lib/injection-debug-log";
import { slugsEquivalent } from "../../providers/slug-codec";
import type { AgentTaskRecoveryFailureReason } from "./agent-task-recovery";
import { resolveWireProtocolOverride } from "../adapter-resolve";
import { hasUnmappedRoutedCustomToolOutput } from "../../responses/custom-tool-compat";
import { PROVIDER_OWNED_CONTINUATION_WIRES, resolvedAdapterWire } from "../../responses/continuation-ownership";
import {
  isCodexReserveHelperUnsupported,
  isCodexReserveOptInMissing,
  CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE,
  CODEX_RESERVE_OPT_IN_REQUIRED_MESSAGE,
} from "../../codex/loopback-target";
import { checkComboTargetInputAdmission, checkInputAdmission } from "./input-admission";
import {
  admissionMayUseMeteredComboTargets,
  admissionModelDeniedResponse, projectAdmissionModelDeniedLog,
  AdmissionModelDeniedError,
  assertRouteAllowedByScope,
  resolveAdmissionModelScope,
  routeAllowedByScope,
} from "../admission-model-scope";
import { nativeContextLimits } from "../../codex/catalog";
import type { ClientToolCatalogRestriction } from "../../lib/empty-tool-catalog";
import {
  currentTurnWireToolCatalogBody,
  hasExplicitEmptyToolCatalog,
  collectDeclaredWireToolNames,
  collectTranslatedHostedToolNames,
  collectDeclaredBareCustomWireToolNames,
} from "../responses-undeclared-tool-guard";
import { streamingContextOverflowResponse } from "./context-overflow";
import {
  preAuthUpstreamHostCircuitKey,
  upstreamHostCircuitOpenResponse,
  applyCodexAccountGatedWireNormalization,
  codexLogAccountId,
} from "./core-codex-account";
import { acquireUpstreamHostAdmission } from "../../codex/upstream-host-health";
import { applyCompactionRoutingOverride, compactionRoutingKeepsProviderIdentity } from "./compaction-routing";
import { applyMainHardLockFallbackOverride } from "./main-hard-lock-routing";
import { FallbackRefusedError, guardFallbackHop } from "../../routing/fallback-policy";
import { codexAuthContextLogLabel } from "../../codex/account-label";
import {
  conversationStateBindingFromAuth,
  applyAccountChangeConversationStateScrub,
  accountChangeFileReferenceRefusal,
  conversationCarriesUploadedFiles,
} from "./account-change-state";

import { redactHostedImageDisplayPaths } from "../responses-hosted-image-display";
import { eagerCodexToolCatalogSurface, warnEagerCodexToolCatalog } from "./codex-tool-catalog";
import { codexTurnStartsNewHistory } from "../../adapters/anthropic/per-message-effort";

/** Policy-routing evidence. The direct lane's settings-only body has no conversation to scan. */
function routeEvidence(options: Pick<HandleResponsesOptions, "directRequest">, parsed: OcxParsedRequest): PolicyRequestEvidence {
  return options.directRequest?.evidence ?? evidenceFromBody(parsed._rawBody);
}

/**
 * Leave the Antigravity direct lane for this request: put the bridge conversation back on the
 * Responses body so every `_rawBody` reader sees what the bridge would have sent, and trace the
 * request as the bridge. The IR conversation already decoded stays: it equals what
 * `parseRequest` builds from the restored body (`tests/protocols/chat-ir-parity.test.ts`).
 */
function restoreDirectRequestConversation(options: HandleResponsesOptions, body: unknown, logCtx: RequestLogContext): void {
  const direct = options.directRequest;
  if (!direct) return;
  options.directRequest = undefined;
  if (body && typeof body === "object" && !Array.isArray(body)) Object.assign(body, direct.bridgeConversation());
  if (options.clientEncoder) options.clientEncoder = { ...options.clientEncoder, requestLane: "bridge" };
  markProtocolEntry(logCtx, {
    inbound: direct.protocol,
    lane: "bridge",
    reasonCodes: ["not-migrated"],
    features: protocolMarkFeatures(logCtx) ?? [],
  });
}

/**
 * Leave the direct lane as soon as the route stops being the Antigravity route it was decided
 * for. Called after every route assignment, so readers that run between a reroute and dispatch
 * (canonical sanitization, ciphertext stripping, final normalization) see the bridge body.
 */
function leaveDirectLaneIfRerouted(
  options: HandleResponsesOptions,
  route: Pick<RouteResult, "providerName" | "modelId" | "provider">,
  parsed: OcxParsedRequest,
  logCtx: RequestLogContext,
): void {
  const direct = options.directRequest;
  if (!direct) return;
  if (route.providerName === direct.providerName && route.modelId === direct.modelId && isAntigravityRoute(route)) return;
  restoreDirectRequestConversation(options, parsed._rawBody, logCtx);
}

/** Parses, selects, and admits one request without changing the dispatch policy. */
export async function prepareResponsesRequest(
  requestContext: Pick<ResponsesRequestContext, "options" | "config" | "req" | "logCtx">,
  admissionState: ResponsesAdmissionState,
  requestDispatchers: ResponsesDispatchers,
) {
  const { options, config, req, logCtx } = requestContext;
  const policyScope = options.policyRequestScope ?? { triedDestinations: new Set<string>() };
  const concreteSelection = options.comboAttempt || options.policyFallbackCandidate !== undefined;

  // The Chat and Anthropic surfaces replay through here with a Responses-shaped body,
  // so an omitted value means a genuine Responses inbound.
  const inboundWire = options.inboundWire ?? "responses";
  const translatorBudget = options.translatorBudget;
  const agentTaskRecovery = agentTaskRecoveryConfig(config);
  let body: unknown;
  try {
    const limit = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
    const attached = takeParsedRequestBody(req);
    body = attached ? admitParsedJsonRequestBody(attached.body, limit, translatorBudget) : await readJsonRequestBody(req, translatorBudget, limit);
  } catch (err) {
    if (options.abortSignal?.aborted || req.signal.aborted) {
      return clientCancelledResponse();
    }
    return decodeRequestErrorResponse(err, "responses");
  }
  options.responsesInstructionImage ||= responsesHasInstructionImage(body);
  options.responsesFileImage ||= responsesHasFileImage(body);
  // Remove display-only artifact paths before helpers, combo dispatch and upstream replay.
  const originalSelector = options.mainHardLockFallbackOverride?.sourceModel ?? options.compactionRoutingOverride?.sourceModel
    ?? (options.comboAttempt || options.policyFallbackCandidate || options.internalDecisionCall || options.memoryModelPhase
      || options.visionDescribeTerminal || options.shadowCallIntercepted ? undefined
      : body && typeof body === "object" ? (body as { model?: unknown }).model : undefined);
  options.clientModelLabel ??= clientFacingModelLabel(originalSelector);
  redactHostedImageDisplayPaths(body);
  observeCacheDiagnosticInbound(
    logCtx,
    body,
    req.headers,
    options.promptCacheKeyIsSharedCohort === true
      ? "system-derived"
      : options.promptCacheKeyIsSharedCohort === false ? "metadata-derived" : "caller",
    contextPrincipalIdOf(options.admission),
  );
  if (!concreteSelection && !options.compactionRoutingOverride && inboundWire === "responses") {
    options.compactionRoutingOverride = applyCompactionRoutingOverride(body, req.headers, config, {
      endpoint: "responses",
      transport: options.inboundTransport,
    });
  }
  // Codex's memory pipeline names a destination per phase. The phase is read from Codex's own turn
  // metadata, never from the model id: Phase 1 shares `gpt-5.6-luna` with the app's title/commit
  // helper calls. Read here, ahead of the shadow intercept below, because the phase decision is the
  // more specific of the two settings and must be the one that survives when both match one request.
  // A JEV decision-model call is the router's own auxiliary turn, never a Codex memory phase.
  const memoryModelPhase = options.internalDecisionCall ? undefined : options.memoryModelPhase
    ?? ((config.memoryModels?.extract || config.memoryModels?.consolidation)
      && !concreteSelection && !options.compactionRoutingOverride && inboundWire === "responses"
      ? detectMemoryModelPhase(body, req.headers, { transport: options.inboundTransport }) ?? undefined
      : undefined);
  const memoryModelTarget = memoryModelPhase ? configuredMemoryModel(config, memoryModelPhase) : undefined;
  // A combo child is a synthetic replay of the parent's decision: its model is already the target's
  // concrete provider/model, so neither site below may rewrite or re-resolve it. It keeps the phase
  // through `options.memoryModelPhase` instead, which is what applies the phase effort.
  const memoryModelApplies = memoryModelTarget !== undefined && !concreteSelection;
  options.onRequestBodyParsed?.(body);
  // An effort row naming a table-less combo (`combo/x--high`) must reach the combo dispatcher
  // as its base id, so the selector is normalized here, before comboIdFromRawBody reads model.
  const comboRows = !concreteSelection && body && typeof body === "object" && !Array.isArray(body)
    && typeof (body as { model?: unknown }).model === "string"
    // One parse for both grammars, from the selector as the client sent it. Parsing them
    // separately made the outcome depend on which ran first.
    ? parseSyntheticRowId((body as { model: string }).model, config)
    : { fastRow: null, effortRow: null };
  const comboEffortRow = comboRows.effortRow;
  if (comboRows.fastRow) {
    // Same reason as the effort row above: the combo dispatcher reads `model` next, so the
    // selector has to be normalized before it, or a combo child is built from a synthetic id.
    const raw = body as Record<string, unknown>;
    raw.model = comboRows.fastRow.baseId;
    // A caller INTENT, not a decision. decideTier still rules on eligibility downstream, so
    // fastMode:false and an ineligible route both still suppress it.
    raw.service_tier = "priority";
  }
  if (comboEffortRow) {
    const raw = body as Record<string, unknown>;
    raw.model = comboEffortRow.baseId;
    const rawReasoning = raw.reasoning;
    raw.reasoning = {
      ...(rawReasoning && typeof rawReasoning === "object" && !Array.isArray(rawReasoning)
        ? rawReasoning as Record<string, unknown>
        : {}),
      effort: comboEffortRow.effort,
    };
  }
  const isCompactionTrigger = body !== null && typeof body === "object" && !Array.isArray(body)
    && Array.isArray((body as { input?: unknown }).input)
    && ((body as { input: unknown[] }).input).some((item: unknown) =>
      typeof item === "object" && item !== null && (item as { type?: string }).type === "compaction_trigger");
  // Compaction may send the last client-visible bare model after a combo switch.
  // Configured selectors take precedence; otherwise recall before combo dispatch (#3891).
  if (!concreteSelection && !options.compactionRoutingOverride && body && typeof body === "object" && !Array.isArray(body)) {
    const rawModel = (body as { model?: unknown }).model;
    if (typeof rawModel === "string" && !rawModel.includes("/") && isCompactionTrigger
      && !comboRows.fastRow && !comboEffortRow
      && !resolveComboId(config, rawModel)) {
      const recalledComboId = recallComboForLane(config, sessionLaneIdFromRequest(req.headers), rawModel);
      if (recalledComboId) {
        (body as Record<string, unknown>).model = `combo/${recalledComboId}`;
      }
    }
  }
  // A shadow-call replacement that names a COMBO is routing policy, not the identity of any
  // one pick. The late intercept site below resolves it through routeModel/tryPickComboModel,
  // which collapses the table to a single target while still tagging `routeKind: "combo"`, so
  // the combo gate on the next line never fires, handleComboResponses never runs, and 429/5xx
  // hops — which only exist inside that loop — are unreachable (#4129). Rewrite the selector
  // here instead, before comboIdFromRawBody reads `model`, and identify the combo by CONFIG
  // LOOKUP so the check can never observe a one-candidate collapse.
  // A memory target that names a combo has to reach the combo dispatcher as `model`, or its own
  // failover loop is unreachable (#4129) — the same reason the shadow intercept rewrites its combo
  // target here. Every other target is resolved at the late site, where the admission scope exists.
  let memoryModelComboRouted = false;
  if (memoryModelApplies && memoryModelTarget && body && typeof body === "object" && !Array.isArray(body)) {
    const memoryComboId = resolveComboId(config, memoryModelTarget.model);
    if (memoryComboId && Object.hasOwn(config.combos ?? {}, memoryComboId)) {
      memoryModelComboRouted = true;
      (body as Record<string, unknown>).model = memoryModelTarget.model;
    }
  }
  let shadowCallIntercepted = false;
  let shadowCallMatches = false;
  // Luna is also selectable by users/children. Both intercept sites use the same
  // per-turn provenance; WS frames must not inherit the handshake's classification.
  const threadSpawn = isThreadSpawnRequest(req.headers);
  const preserveShadowModel = shadowCallPreservesSelectedModel(body, req.headers, options.inboundTransport);
  if (!concreteSelection && !options.compactionRoutingOverride && !options.internalDecisionCall && !preserveShadowModel && !memoryModelApplies && body && typeof body === "object" && !Array.isArray(body)) {
    const shadowIntercept = config.shadowCallIntercept;
    const rawShadowModel = (body as { model?: unknown }).model;
    if (shadowIntercept?.enabled && shadowIntercept.model && typeof rawShadowModel === "string"
      && isShadowSourceModel(rawShadowModel, shadowIntercept.sourceModels)) {
      shadowCallMatches = true;
      const shadowComboId = resolveComboId(config, shadowIntercept.model);
      if (shadowComboId && Object.hasOwn(config.combos ?? {}, shadowComboId)) {
        shadowCallIntercepted = true;
        (body as Record<string, unknown>).model = shadowIntercept.model;
        // Same rule as the late intercept site: record the operator-configured prefix that
        // matched, never the caller's raw model string. Matching is by prefix, so the raw
        // value is caller-controlled and reaches usage.jsonl and /api/logs.
        logCtx.shadowCallRewrittenFrom = sanitizeLogMetadataString(
          shadowSourceModelPrefix(rawShadowModel, shadowIntercept.sourceModels),
        );
      }
    }
  }
  // The hard-lock fallback owns ordinary turns only, and only after every more specific
  // routing setting had its chance above: a shadow-intercepted, memory-phased, compaction
  // or decision turn keeps its own destination, and an intercepted combo selector is
  // already owned by the intercept. A spawned sub-agent turn names its model on purpose,
  // the same reason the shadow intercept leaves it alone. Like the sites above it, this
  // must run before comboIdFromRawBody reads `model`.
  if (!concreteSelection && !options.compactionRoutingOverride && !isCompactionTrigger && !options.internalDecisionCall
    && !shadowCallIntercepted && !shadowCallMatches && !memoryModelApplies && !threadSpawn && inboundWire === "responses") {
    try {
      options.mainHardLockFallbackOverride = await applyMainHardLockFallbackOverride(
        body, config, undefined, mainHardLockFallbackCallerCheck(req, config, options), options.admission,
      );
    } catch (error) {
      if (options.abortSignal?.aborted || req.signal.aborted) return clientCancelledResponse();
      if (error instanceof FallbackRefusedError) return error.response;
      const mapped = mapCodexAuthContextErrorToResponse(error, { now: Date.now() });
      if (mapped) return mapped;
      throw error;
    }
  }
  const comboId = !concreteSelection ? comboIdFromRawBody(body, config) : null;
  // A decision model may be a plain model or a non-JEV combo. A JEV combo here would recurse
  // into another decision, so the call is refused and the parent decision fails open.
  if (options.internalDecisionCall && comboId && config.combos?.[comboId]?.strategy === "jev") {
    return markProxyError(formatErrorResponse(400, "invalid_request_error", "A JEV decision model cannot be a JEV combo"));
  }
  if (comboId && Object.hasOwn(config.combos ?? {}, comboId)) {
    options.onRequestBodyRead?.();
    // The Antigravity direct lane is decided for one concrete route; a body that reached a combo
    // goes through the combo's own child loop with the full bridge conversation.
    restoreDirectRequestConversation(options, body, logCtx);
    return requestDispatchers.handleComboResponses(req, body, comboId, config, logCtx, {
      ...options,
      // Concrete combo child selectors no longer match the shadow source model. Carry the
      // interception decision explicitly so provider-specific helper isolation still applies.
      shadowCallIntercepted,
      // Same handoff for a memory phase whose target is a combo: the child keeps the phase's effort
      // override and stays out of the parent conversation.
      memoryModelPhase: memoryModelComboRouted ? memoryModelPhase : undefined,
      // The original request body was accepted above. Combo children are synthetic
      // replays and must not repeat the caller-owned timeout transition.
      onRequestBodyRead: undefined,
    });
  }
  let unreadableEncryptedAgentTask = hasUnreadableEncryptedAgentTask(
    (body as { input?: unknown } | undefined)?.input,
  );
  const inboundClientThreadId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
  // The request's OWN thread, which `x-codex-parent-thread-id` is not: parallel children of one
  // parent all present the same parent id. `codexConversationIdentity` already reads this header
  // for the same reason, and a surface that must tell siblings apart needs it too (#5033).
  const inboundOwnThreadId = req.headers.get("thread-id")?.trim() || undefined;
  const replayPrincipal = options.replayPrincipal
    ? options.replayPrincipal.clientPrincipalId : resolveContextPrincipal(req, config, options.admission);
  const strictReplay = options.plaintextV2Decision ?? isPlaintextV2AgentMessagesEnabled(config);
  const { replayOwnerKey, replayConnectionScope } = selectResponseReplayOwner(strictReplay, replayPrincipal, inboundOwnThreadId, options);
  const replayThreadId = strictReplay ? inboundOwnThreadId : inboundClientThreadId;
  const cursorClientThreadId = codexPoolAffinityKey(req.headers);
  const originalBody = body;
  if (options.comboReplaySnapshot) {
    copyPreviousResponseReplayProvenance(options.comboReplaySnapshot.sourceBody, body);
  } else {
    body = expandPreviousResponseInput(body, replayThreadId, replayOwnerKey);
    const replayFailure = previousResponseReplayFailure(body);
    if (replayFailure?.reason === "scope_mismatch") {
      // Bounded and content-free: no task scope and nothing about the retained entry.
      console.warn("[opencodex] refusing continuation because the client task scope does not match replay state");
    }
    // Local replay failures require full client replay.
    if (replayFailure) {
      failLinkTurnExpansion(options.linkTurn, req, logCtx, body, replayFailure.reason);
      const { code } = replayFailure;
      if (strictReplay) {
        logCtx.errorCode = code;
        if (logCtx.attempts?.some(attempt => attempt.sendCount > 0)) logCtx.terminalSource = "synthetic";
        else markLocalRequestLogRefusal(logCtx, code);
        // Attribute a direct native refusal using only request metadata and a route preview.
        // A miss never enters auth, subagent fallback or encrypted-task recovery for logging.
        const { model, reasoning } = body as { model?: unknown; reasoning?: unknown };
        try {
          const parsed = parseRequest({ model, reasoning });
          logCtx.requestedModel ??= options.mainHardLockFallbackOverride?.sourceModel
            ?? options.compactionRoutingOverride?.sourceModel ?? parsed.modelId;
          logCtx.requestedEffort ??= parsed.options.reasoning;
          if (!concreteSelection && !memoryModelApplies && !shadowCallMatches
            && !resolveComboId(config, parsed.modelId) && !resolvePolicyProfileId(config, parsed.modelId)) {
            const preview = previewRouteModel(config, parsed.modelId);
            if (isCanonicalOpenAiForwardProvider(preview.provider)) {
              logCtx.provider = preview.providerName;
              logCtx.model = preview.modelId;
              logCtx.routeDecision = preview.routeDecision;
            }
          }
        } catch { /* Unavailable attribution does not change the replay refusal. */ }
      }
      return markProxyError(formatErrorResponse(
        400,
        code,
        "Continuation state is unavailable or corrupt; resend the full conversation without previous_response_id.",
      ));
    }
  }
  const previousResponseInputExpanded = options.comboReplaySnapshot?.previousResponseInputExpanded
    ?? (body !== originalBody
      && typeof (body as { previous_response_id?: unknown }).previous_response_id === "string");
  // Remote Link holds and request-log fields (design T4 sections 5, 9.1): the expanded input, before any upstream I/O.
  if (!options.comboReplaySnapshot) observeLinkTurnExpansion(options.linkTurn, req, logCtx, body, previousResponseInputExpanded ? "chained"
    : body && typeof body === "object" && typeof (body as { previous_response_id?: unknown }).previous_response_id === "string" ? "unexpanded" : "none");
  options.responsesInstructionImage ||= responsesHasInstructionImage(body);
  options.responsesFileImage ||= responsesHasFileImage(body);
  // Counted after replay expansion so the catalog this request pays for is the one measured:
  // input restored from stored continuation state is history, and the prefix removes it.
  if (inboundWire === "responses" && !concreteSelection) {
    warnEagerCodexToolCatalog(body, req.headers, {
      surface: eagerCodexToolCatalogSurface(body, options.compactionRecoveryKind),
      replayPrefixLength: previousResponseRestoredPrefixLength(body),
      logicalRequest: logCtx,
    });
  }

  // Spawn-message compatibility (both directions): agent_message task payloads ride in
  // encrypted_content slots as plaintext. Rewrite them to input_text on the RAW body BEFORE
  // parsing so every consumer sees the payload: parseRequest (routed/translated providers read
  // the parsed messages) and the native passthrough (_rawBody is this same object, serialized
  // verbatim). Structurally valid backend ciphertext stays byte-identical; encoded-looking unknown
  // slots remain opaque only until final-route handling can preserve or strip them safely.
  {
    const rewritten = sanitizeEncryptedContentInPlace(
      (body as { input?: unknown } | undefined)?.input,
      // The final destination is not known yet. Keep ambiguous encoded slots opaque until route
      // selection can either strip them for a third party or apply strict native classification.
      { preserveUnknownOpaqueSlots: true },
    );
    if (rewritten > 0)
      console.warn(
        `[opencodex] rewrote ${rewritten} plaintext encrypted_content part(s) to input_text (spawn-message compatibility)`,
      );
  }

  const skillsSnapshotScopeKey = resolveSkillsSnapshotScopeKey({
    req,
    config,
    admission: options.admission,
        promptCacheKeyIsSharedCohort: options.promptCacheKeyIsSharedCohort,
  });
  // Substitutes a known snapshot now; a new catalog is only stored once the request is prepared.
  const commitSkillsSnapshot = snapshotSkillsCatalogInBody(body, skillsSnapshotScopeKey, config);

  const turnMembership = responseTurnMembership(req, config, options.admission);
  if (turnMembership && body && typeof body === "object" && "input" in body && Array.isArray(body.input)) {
    body.input = turnMembership.normalize(body.input);
  }

  let parsed: OcxParsedRequest;
  let toolBridgeMaps: ReturnType<typeof buildToolBridgeMaps>;
  let clientToolCatalogRestriction: ClientToolCatalogRestriction | undefined;
  try {
    parsed = parseRequest(body);
    // Antigravity direct lane: the body carried only the request settings, so the parse above
    // produced them with an empty conversation; the conversation itself comes straight from the
    // client body. Inside this try so a decode error answers exactly like a parse error.
    if (options.directRequest) parsed = options.directRequest.decode(parsed);
    parsed._nativeReasoningRetention = resolveNativeReasoningRetention(config);
    // Capture before route rewrites or hosted sidecars can add tools; replayed catalogs are history.
    // Direct decoders already own current function names (including legacy Chat functions).
    // Project only those names; bridging the conversation would retain its reasoning twice.
    const catalogBody = options.directRequest && parsed.context.tools?.length
      ? { tools: parsed.context.tools.map(tool => ({ type: "function", name: tool.name })) } : parsed._rawBody;
    const currentCatalog = currentTurnWireToolCatalogBody(catalogBody, parsed._replayPrefixLen);
    // A hosted tool declared this turn authorizes the function name its translation uses.
    const translatedHostedNames = collectTranslatedHostedToolNames(currentCatalog);
    clientToolCatalogRestriction = {
      declaredToolNames: new Set([...collectDeclaredWireToolNames(currentCatalog), ...translatedHostedNames]),
      bareCustomToolNames: collectDeclaredBareCustomWireToolNames(currentCatalog),
      canonicalToolNames: new Set([...collectDeclaredWireToolNames(currentCatalog, { canonicalOnly: true }), ...translatedHostedNames]),
      // Ordinary Responses validation stays with its delivery owner; replay cannot add authority.
      enforceDeclaredToolNames: (inboundWire === "responses" && (parsed._replayPrefixLen ?? 0) > 0)
        || options.clientDeclaredEmptyToolCatalog === true
        || hasExplicitEmptyToolCatalog(currentCatalog),
    };
    if (options.inboundWire === "anthropic") {
      parsed._nativeReasoningReplay = options.nativeReasoningReplay;
      parsed._nativeReasoningMint = options.nativeReasoningMint;
      parsed._anthropicServerTools = options.anthropicServerTools;
      // The lowered named choice serves the wire builder but grants no client or synthetic tool permission.
      if (options.anthropicHostedAdvisorSelection) {
        parsed.options.explicitRootFunctionChoices = [];
        parsed.options.explicitClientToolChoices = [];
      }
      parsed._anthropicServerReplay = options.anthropicServerReplay;
      parsed._anthropicSystemCachePrefix = options.anthropicSystemCachePrefix;
      parsed._anthropicInbound = true;
      if (parsed.options.textFormat?.type === "json_schema") parsed._structuredOutputConformance = true;
    }
    if (options.advisorInternal || options.internalSidecarCall || options.internalDecisionCall) {
      parsed._proxyOwnedSystemPrompt = true;
    }
    // Codex's own "new" turn metadata, for the experimental Anthropic perMessageEffort option (#6895).
    parsed._codexNewHistory = codexTurnStartsNewHistory(body, req.headers, options.inboundTransport);
    parsed._promptCacheKeyIsSharedCohort = options.promptCacheKeyIsSharedCohort;
    // The body may have been rebuilt since the inbound observation (previous-response
    // expansion); alias the parsed raw body to the same draft so the outbound
    // observation at the adapter seam still finds it.
    rebindCacheDiagnosticBody(parsed._rawBody, logCtx.cacheDiagnosticDraft);
    // Captured before any parser mutates it, so both grammars see the client's id.
    const { fastRow, effortRow } = parseSyntheticRowId(parsed.modelId, config);
    if (fastRow) {
      parsed.modelId = fastRow.baseId;
      parsed.options.serviceTier = "priority";
      const raw = parsed._rawBody as Record<string, unknown>;
      raw.model = fastRow.baseId;
      raw.service_tier = "priority";
    }
    if (effortRow) {
      parsed.modelId = effortRow.baseId;
      parsed.options.reasoning = effortRow.effort;
      const raw = parsed._rawBody as Record<string, unknown>;
      const rawReasoning = raw.reasoning;
      raw.model = effortRow.baseId;
      raw.reasoning = {
        ...(rawReasoning && typeof rawReasoning === "object" && !Array.isArray(rawReasoning)
          ? rawReasoning as Record<string, unknown>
          : {}),
        effort: effortRow.effort,
      };
    }
    if (options.comboReplaySnapshot?.recoveredPlaintext) {
      markBodyNonPersistable(parsed._rawBody);
    }
    toolBridgeMaps = buildToolBridgeMaps(parsed, translatorBudget);
    if (previousResponseInputExpanded) parsed._previousResponseInputExpanded = true;
    const providerContinuationCandidate = options.comboReplaySnapshot
      ? options.comboReplaySnapshot.providerContinuation
      : previousResponseProviderState(parsed.previousResponseId);
    if (providerContinuationCandidate) parsed._providerContinuationCandidate = providerContinuationCandidate;
    if (inboundOwnThreadId) parsed._codexOwnThreadId = inboundOwnThreadId;
    if (inboundClientThreadId) {
      parsed._clientThreadId = inboundClientThreadId;
    } else if (
      options.inboundWire === "anthropic"
      && options.promptCacheKeyIsSharedCohort !== true
      && typeof parsed.options.promptCacheKey === "string"
      && parsed.options.promptCacheKey.trim().length > 0
    ) {
      // Claude Code has no Codex parent-thread header, but its metadata.user_id is
      // translated into a stable per-session prompt_cache_key. Use it as the replay
      // thread identity so Gemini thought signatures are remembered by call_id for
      // Anthropic Messages clients too (#1735/#1926). Keep `_clientThreadId` unset so
      // existing provider session-id derivation (first-user-text fallback) is unchanged.
      // Normalize through anthropicSessionKeyFromParts so overlong keys are hashed and
      // trimming matches the affinity/session-key path exactly (no raw >128-char ids).
      const normalizedCacheKey = anthropicSessionKeyFromParts({
        promptCacheKey: parsed.options.promptCacheKey,
        // The enclosing branch already proves this is not the shared cohort.
        promptCacheKeyIsSharedCohort: false,
      });
      if (normalizedCacheKey) {
        parsed._reasoningReplayScope = { clientThreadId: normalizedCacheKey };
      }
    }
    if (cursorClientThreadId) parsed._cursorClientThreadId = cursorClientThreadId;
    if (options.shadowCallIntercepted === true) parsed._cursorIsolateConversation = true;
    if (options.memoryModelPhase !== undefined) {
      parsed._memoryModelPhase = options.memoryModelPhase;
      parsed._cursorIsolateConversation = true;
    }
  } catch (err) {
    if (isTranslatorBudgetExceededError(err)) {
      return markProxyError(formatErrorResponse(413, "request_too_large", "request translation buffer exceeded the safe limit", {
        code: "translation_buffer_limit",
      }));
    }
    return formatErrorResponse(400, "invalid_request_error", err instanceof Error ? err.message : String(err));
  }
  parsed._plaintextV2Decision = strictReplay;
  options.onRequestBodyRead?.();
  const responseStateOptions = (force = false) => ({
    replayOwnerKey,
    ...(replayConnectionScope ? { connectionScope: replayConnectionScope } : {}),
    compiledPlaintext: parsed._plaintextV2EverPrepared === true,
    ...(force ? { force: true } : {}),
    ...((strictReplay ? inboundOwnThreadId : parsed._clientThreadId) ? { clientThreadId: strictReplay ? inboundOwnThreadId : parsed._clientThreadId } : {}),
  });
  const resolvedConversationId = conversationIdFromResponsesRequest({
    clientThreadId: parsed._clientThreadId,
    sessionIdHeader: sessionIdHeaderFromRequest(req.headers),
    threadIdHeader: req.headers.get("thread-id"),
    cursorConversationId: parsed._cursorConversationId,
  });
  bindTurnTerminationScope(parsed, resolvedConversationId);
  const rememberKiroDeliveredFinalAnswer = (adapterName: string, response: unknown): void => {
    if (adapterName === "kiro") rememberDeliveredFinalAnswer(parsed, response);
  };
  // _clientThreadId remains the routing/continuation identity supplied by Codex. Replay state uses
  // a dedicated raw conversation namespace so mixed headers that carry the same identity still
  // match, and a shared/synthetic session_id cannot coalesce distinct thread/Cursor conversations.
  // Keep an Anthropic prompt_cache_key scope already bound above (#1735/#1926).
  if (!parsed._reasoningReplayScope) {
    const reasoningReplayConversationId = reasoningReplayConversationIdFromResponsesRequest({
      clientThreadId: parsed._clientThreadId,
      threadIdHeader: req.headers.get("thread-id"),
      cursorConversationId: parsed._cursorConversationId,
      sessionIdHeader: sessionIdHeaderFromRequest(req.headers),
    });
    if (reasoningReplayConversationId) {
      parsed._reasoningReplayScope = { clientThreadId: reasoningReplayConversationId };
    }
  }
  if (parsed._reasoningReplayScope) {
    // Scope replay cells to the caller principal. On loopback, admission carries no identity,
    // so resolve it from an opencodex API key the caller volunteered (same rule as context
    // history ownership). A caller that presents none has no principal, and none is invented:
    // every keyless local process would otherwise share one bucket, and a client-visible cell id
    // would become enough to read another caller's retained search result. Without a principal
    // bridgeSearchReplayScope yields no scope, so nothing is recorded or restored for it. The
    // field is always rewritten so an absent principal also clears one a reused holder carried.
    const clientPrincipalId = options.replayPrincipal
      ? options.replayPrincipal.clientPrincipalId
      : resolveContextPrincipal(req, config, options.admission);
    parsed._reasoningReplayScope = { ...parsed._reasoningReplayScope, clientPrincipalId };
  }
  // Prefer a pre-populated id (routed Claude) over Responses headers that may be
  // absent or synthetically injected (session_id from prompt_cache_key). A Hermes-only id
  // is a log fallback: native resolution replaces it, and it only fills an empty slot.
  assignNativeLogConversationId(logCtx, resolvedConversationId ?? nativeLogConversationIdFromHeaders(req.headers));
  fillHermesLogConversationFallback(logCtx, req.headers);
  // A rewritten turn logs the selector the client asked for, so the usage log never
  // claims the operator typed the fallback model themselves.
  logCtx.requestedModel = options.mainHardLockFallbackOverride?.sourceModel
    ?? options.compactionRoutingOverride?.sourceModel ?? parsed.modelId;
  logCtx.requestedEffort = parsed.options.reasoning;
  // What this request may spend beyond its input, for the durable spend reservation (#4707).
  // Read from the caller rather than from the adapter's serialized body, because the
  // reservation has to exist before the body does. A caller that omits it leaves the
  // provider/model default in charge and reserves only the input estimate; settlement then
  // books the real figure, so the gap is a looser bound up front, never a wrong one after.
  if (typeof parsed.options.maxOutputTokens === "number" && parsed.options.maxOutputTokens > 0) {
    logCtx.spendOutputCeilingTokens = Math.trunc(parsed.options.maxOutputTokens);
  }
  logCtx.callerServiceTier = sanitizeLogMetadataString(parsed.options.serviceTier);
  logCtx.requestedServiceTier = parsed.options.serviceTier;
  logCtx.requestedSpeedLabel = requestLogSpeedLabel(parsed.options.serviceTier);
  logCtx.configuredServiceTier = readConfiguredCodexServiceTier();
  logCtx.configuredSpeedLabel = requestLogSpeedLabel(logCtx.configuredServiceTier);

  let route: RouteResult;
  let credentialDomainWasRewritten = false;
  // The selector the caller actually sent, captured before shadow interception
  // or a subagent fallback rewrites it, so a refusal names the client's own
  // request rather than a destination it never asked for.
  const inboundSelector = options.clientModelLabel;
  const inboundRoutingSelector = options.mainHardLockFallbackOverride?.sourceModel ?? parsed.modelId;
  const selectorTargetsSecondary = (selector: string): boolean => {
    const slash = selector.indexOf("/");
    if (slash <= 0) return false;
    const qualifier = selector.slice(0, slash);
    // Match router precedence: exact custom keys (including uppercase names) win over aliases.
    if (Object.hasOwn(config.providers, qualifier)) return qualifier === "anthropic2";
    return qualifier === "anthropic2"
      || config.providers.anthropic2?.alias?.trim().toLowerCase() === qualifier.toLowerCase();
  };
  const explicitlyRequestsSecondary = selectorTargetsSecondary(inboundRoutingSelector);
  const secondaryProvider = config.providers.anthropic2;
  // Reserve an explicit B selector before an absent row can default-route it to A.
  // Combo parents have already dispatched above; concrete children retain their own target.
  if (explicitlyRequestsSecondary && (!secondaryProvider || secondaryProvider.disabled === true
    || secondaryProvider.authMode === "oauth" && configuredAnthropicInstance(config, "anthropic2") !== "anthropic2")) {
    return markProxyError(formatErrorResponse(401, "authentication_error", "Anthropic Pool 2 requires an enabled configured provider"));
  }
  const admissionScope = options.admissionScope ?? resolveAdmissionModelScope(config, options.admission);
  const advisorAdmissionPolicy = options.advisorAdmissionPolicy;
  const captureInboundRoutePolicy = (candidate: RouteResult, captureRequestPolicy = true): RouteResult => {
    // Router-collapsed aliases bypass the combo loop. Re-pick before capturing destination
    // policy so random/RR cannot refuse while an unmetered target is still usable.
    if (candidate.combo?.target.metered && !admissionMayUseMeteredComboTargets(
      config, options.admission, config.combos?.[candidate.combo.comboId],
    )) {
      const pick = pickComboTarget(config, candidate.combo.comboId, {
        eligible: target => !target.metered,
        allowCooldownReprobe: false,
      });
      if (!pick) {
        throw new NoAvailableComboTargetsError(candidate.combo.comboId,
          comboExclusion(config, candidate.combo.comboId, target => !target.metered));
      }
      const routed = routeConcreteModel(config, `${pick.target.provider}/${pick.target.model}`);
      candidate = { ...routed, combo: pick, routeKind: "combo", routeReason: routed.routeReason === "blocked-model-redirect" ? "blocked-model-redirect" : "combo-pick" };
    }
    // Every route this request path produces passes through here: the direct
    // name, an alias, a policy or combo selection, a compaction override, a
    // shadow-intercept target and both subagent-fallback re-routes. Checking
    // the key's scope at this one point is what stops a rewrite from reaching
    // a destination the front door would have refused.
    // A shadow-intercept target is probed before interception is decided, so it
    // skips the request-owned policy capture here; the accepted target is
    // captured where it becomes the request's route. A declined policy target
    // must not lend its eligibility or "policy" route kind to the request.
    if (captureRequestPolicy) capturePolicyRequestRoute(policyScope, candidate);
    candidate.staticPolicy = captureRouteStaticPolicy(
      candidate.providerName,
      candidate.modelId,
      candidate.provider,
      candidate.staticPolicy.effectiveAlias,
      inboundWire,
    );
    // Fast-only keys authorize the same billed lane that final normalization serializes.
    assertRouteAllowedByScope(admissionScope, inboundSelector, {
      providerName: candidate.providerName,
      modelId: previewXaiOauthWireModel(parsed, candidate, config, inboundWire),
    });
    return candidate;
  };
  try {
    // A `compaction_trigger` turn may name a bare native model the operator has
    // no canonical OpenAI route for (#2901). Only the initial compaction route
    // may fall back to the configured default provider; combo attempts and the
    // later fallback/recovery re-routes keep the ordinary reservation.
    const routeInbound = (modelId: string) => {
      const resolved = concreteSelection
        ? routeConcreteModel(config, modelId)
        : parsed._compactionRequest === true
          ? routeCompactionModel(config, modelId, routeEvidence(options, parsed))
          : routeModel(config, modelId, routeEvidence(options, parsed));
      // A Pool 2 selector may leave Pool 2 only through an operator-configured cross-provider
      // blocked-model redirect, which the router marks as a credential-domain rewrite. Any other
      // destination means the selector fell through to default resolution, which stays refused.
      const operatorRedirect = resolved.routeReason === "blocked-model-redirect" && resolved.credentialDomainRewrite === true;
      if (selectorTargetsSecondary(modelId) && resolved.providerName !== "anthropic2" && !operatorRedirect) {
        throw new Error("Anthropic Pool 2 selector cannot use the default provider");
      }
      return resolved;
    };
    const resolveRoute = (modelId: string) => captureInboundRoutePolicy(routeInbound(modelId));
    // The phase's destination. Resolved through the admission-scoped resolver every other route
    // uses, and it fails closed exactly like the shadow target: falling back to the native model
    // would spend the quota the operator routed away from, without their choosing it.
    let memoryRoute: RouteResult | undefined;
    if (memoryModelApplies && memoryModelPhase && memoryModelTarget) {
      const memoryTarget = resolveChosenTarget(memoryModelTarget.model, resolveRoute);
      if ("unavailable" in memoryTarget) {
        logCtx.errorCode = MEMORY_MODEL_TARGET_UNAVAILABLE_CODE;
        return memoryModelTargetUnavailableResponse(memoryModelPhase);
      }
      credentialDomainWasRewritten = true;
      parsed.modelId = memoryModelTarget.model;
      if (parsed._rawBody && typeof parsed._rawBody === "object") {
        (parsed._rawBody as { model?: string }).model = memoryModelTarget.model;
      }
      parsed._memoryModelPhase = memoryModelPhase;
      parsed._cursorIsolateConversation = true;
      memoryRoute = memoryTarget.route;
    }
    const _sci = config.shadowCallIntercept;
    let shadowRoute: RouteResult | undefined;
    if (!concreteSelection && !memoryRoute && !options.memoryModelPhase && !options.compactionRoutingOverride && !options.mainHardLockFallbackOverride && !options.internalDecisionCall && !preserveShadowModel && _sci?.enabled && _sci.model && isShadowSourceModel(parsed.modelId, _sci.sourceModels)) {
      const sourcePrefix = shadowSourceModelPrefix(parsed.modelId, _sci.sourceModels)!;
      let sourceIdentity = { providerName: OPENAI_CODEX_PROVIDER_ID, modelId: sourcePrefix };
      try {
        const resolvedSource = routeConcreteModel(config, parsed.modelId);
        sourceIdentity = { providerName: resolvedSource.providerName, modelId: sourcePrefix };
      } catch { /* Native Codex helper calls remain OpenAI-owned without an enabled OpenAI route. */ }
      // A dead target fails this helper call once, before any send; it never falls through to
      // the native source model or to the default provider (#5618).
      const target = resolveShadowCallTarget(_sci.model, modelId => captureInboundRoutePolicy(routeInbound(modelId), false));
      if ("unavailable" in target) {
        logCtx.shadowCallRewrittenFrom = sanitizeLogMetadataString(sourcePrefix);
        logCtx.errorCode = INTERCEPT_TARGET_UNAVAILABLE_CODE;
        return interceptTargetUnavailableResponse(_sci.model, target.unavailable);
      }
      const targetRoute = target.route;
      if (shouldInterceptShadowCall(parsed.modelId, _sci.sourceModels, sourceIdentity, targetRoute)) {
        credentialDomainWasRewritten = true;
        const _sciOriginal = parsed.modelId;
        parsed.modelId = _sci.model;
        if (parsed._rawBody && typeof parsed._rawBody === "object") {
          (parsed._rawBody as { model?: string }).model = _sci.model;
        }
        // Record the operator-configured prefix that matched, NOT the caller's raw model string.
        // Matching is by prefix, so a caller can append arbitrary text and still intercept; that
        // raw value would then land in usage.jsonl and /api/logs behind a pattern-based redactor
        // that does not recognize every credential family. The prefix is a value the operator
        // configured, so no caller-controlled string is persisted.
        logCtx.shadowCallRewrittenFrom = sanitizeLogMetadataString(
          shadowSourceModelPrefix(_sciOriginal, _sci.sourceModels),
        );
        // Helpers must not resume/append into the parent thread's Cursor conversation.
        parsed._cursorIsolateConversation = true;
        shadowRoute = capturePolicyRequestRoute(policyScope, targetRoute);
      }
    }
    if (parsed._compactionRequest === true || options.compactionRoutingOverride) parsed._cursorIsolateConversation = true;
    route = memoryRoute ?? shadowRoute ?? resolveRoute(options.policyFallbackCandidate
      ? `${options.policyFallbackCandidate.provider}/${options.policyFallbackCandidate.model}` : parsed.modelId);
    // Selection-free hard-lock preflight grants no hop. Enforce the actual ranked destination
    // against the locked source before admitting this first selection.
    const hardLockProfileTrace = options.mainHardLockFallbackOverride ? route.routeDecision?.profile : undefined;
    if (hardLockProfileTrace && options.mainHardLockFallbackOverride) {
      const override = options.mainHardLockFallbackOverride;
      const hop = guardFallbackHop(config, {
        site: "routing-profile",
        route: override.sourceModel,
        aliases: [`policy/${hardLockProfileTrace.id}`],
        from: { provider: OPENAI_CODEX_PROVIDER_ID, model: override.sourceModel },
        to: { provider: route.providerName, model: route.modelId },
        trigger: "hard_lock",
        admission: options.admission,
      });
      if (!hop.ok) return hop.response;
      hop.commit();
    }
    leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
    // Name the phase in the persisted route decision, so the request log says why this turn went to
    // the memory destination instead of leaving it looking like a plain user selection. Set here, on
    // the resolved route, so a combo child's own route carries it too.
    if (parsed._memoryModelPhase) {
      const reason = memoryModelRouteReason(parsed._memoryModelPhase);
      route.routeReason = reason;
      if (route.routeDecision) {
        route.routeDecision = {
          ...route.routeDecision,
          selected: { ...route.routeDecision.selected, reason },
        };
      }
    }
    if ((options.compactionRoutingOverride && !compactionRoutingKeepsProviderIdentity(config, options.compactionRoutingOverride, route))
      || options.mainHardLockFallbackOverride) {
      credentialDomainWasRewritten = true;
      // The destination does not share the conversation's credential domain, so it can neither
      // verify the source backend's reasoning ciphertext nor decode its native compaction blob.
      // This is the same condition an account change already reports (account-change-state.ts),
      // and the serializer turns a stored summary into readable text instead of dropping it.
      parsed._stripReasoningEncryptedContent = true;
      parsed._stripNativeCompactionEncryptedContent = true;
      if (parsed._compactionRequest === true) parsed._portableCompaction = true;
    }
    // A v1 fallback needs an ocx1 summary for replacement-history decoding, even when this
    // custom destination separately accepts native v2 triggers. Legacy defaults stay intact.
    if (options.compactionRecoveryKind === "compaction-v1" && parsed._compactionRequest === true
      && route.provider.adapter === "openai-responses" && route.provider.supportsNativeCompactionTrigger === true
      && !isCanonicalOpenAiForwardProvider(route.provider)) parsed._portableCompaction = true;
    logCtx.routeDecision = route.routeDecision;
    logCtx.policyEligibility = route.policyEligibility;
  } catch (err) {
    if (err instanceof AnthropicSecondaryInstanceUnavailableError) {
      return markProxyError(formatErrorResponse(401, "authentication_error", err.message));
    }
    const policyRefusal = policyCandidateRefusalResponse(err);
    if (policyRefusal) return policyRefusal;
    if (err instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(projectAdmissionModelDeniedLog(err, logCtx));
    if (err instanceof NoAvailableComboTargetsError) {
      return comboUnavailable(err.comboId, undefined, err.exclusion);
    }
    if (err instanceof NoEligiblePolicyCandidateError) {
      // Persist the evaluation trace (per-candidate exclusions + the
      // no-eligible reason) so failed policy requests stay auditable.
      logCtx.routeDecision = err.trace;
    }
    return formatErrorResponse(404, "invalid_request_error", err instanceof Error ? err.message : String(err));
  }

  const hasUnexpandedPreviousResponse = !!parsed.previousResponseId
    && parsed._previousResponseInputExpanded !== true;
  // Exact account selectors are isolated from Pool-wide quota work. A canonical replay miss must
  // also fail closed without polling quota upstream. Cached fallback state can still select a
  // provider with native continuation support below.
  const initialSubagentFallbackChain = threadSpawn && !options.comboAttempt
    ? resolveSubagentFallbackChain(parsed, config)
    : null;
  const previewSelectionAdmission = threadSpawn
    && !options.comboAttempt
    && (route.codexAccountId === undefined || initialSubagentFallbackChain !== null)
    ? codexAccountSelectionForTurn(options.turnAdmissionLease)?.()
    : undefined;
  // The credential headers final authentication will be given, resolved once and reused by
  // everything below that has to predict what final auth decides.
  const previewAuthHeaders = codexRouteCredentialDomainHeaders(
    req,
    route,
    options,
    credentialDomainWasRewritten,
    config,
  );
  // Does the CALLER own the credential this request will authenticate with? Validated exactly
  // the way final auth validates it: the route ownership predicate AND the caller-bearer check
  // `resolveCodexAuthContext` re-applies to these same headers.
  const previewRequestScopedMainCredential = codexRouteCredentialOwnership(
    previewAuthHeaders,
    config,
    route,
    options,
  ).requestScopedMainCredential && hasCallerCodexBearer(previewAuthHeaders);
  const nativeMainRecoveryBlocked = isNativeMainTrafficBlocked();
  // The same three inputs final auth ORs together (src/codex/auth-context.ts). Request-owned
  // ownership is first there and has to be first here: computing the preview fence from
  // recovery and drain state alone let a `thread_spawn` carrying a forwardable caller bearer
  // read the physical main token it is forbidden to touch, and score main differently than the
  // resolution this preview exists to predict.
  const nativeMainReadsForbidden = previewRequestScopedMainCredential
    || nativeMainRecoveryBlocked
    || previewSelectionAdmission?.mainProfileDraining === true;
  // The liveness answer final authentication gives its own selection options, computed from the
  // same shared predicate so the two cannot drift apart again (#4850). `fixedAccountId` is
  // mirrored through `route.codexAccountId` because that is literally what core-auth.ts passes
  // as `accountId`. A reserve-authorized request is the one input where the two can differ, and
  // it differs harmlessly: reserve plus a caller bearer is served as main either way, which is
  // the answer this produces.
  const previewRequestOwnedMainPin = requestOwnedMainPinState(
    previewAuthHeaders,
    config,
    options.codexAuthPolicy ?? config,
    previewRequestScopedMainCredential,
    route.codexAccountId,
    codexQuotaScopeForModel(route.modelId),
  ).preserve;
  // Final auth's own liveness answer for a request-owned bearer, from its own shared expression
  // (#5019). Predicting the pin alone dropped main here and handed subagent fallback a different
  // account than the one that serves.
  const previewRequestOwnedMainCredentialLive = requestOwnedMainCredentialIsLive({
    preserveRequestOwnedMainPin: previewRequestOwnedMainPin,
    requestScopedMainCredential: previewRequestScopedMainCredential,
    nativeMainTrafficBlocked: nativeMainRecoveryBlocked,
    mainProfileDraining: previewSelectionAdmission?.mainProfileDraining === true,
    // Final-auth-only, and stated rather than defaulted: see the field's own note.
    callerOwnsCooledPoolSubscription: false,
  });
  // Deliberately NOT fenced on ownership: final auth derives `nativeMainSelectionOnly` from the
  // drain alone, and adding a term here would diverge from it in the other direction.
  const previewSelectionOptions = {
    nativeMainSelectionOnly: !nativeMainRecoveryBlocked
      && previewSelectionAdmission?.mainProfileDraining === true,
    // Pool eligibility was the last part of preview still outside the fence (#4850). Without
    // this seam `codexAccountUnusableReason` takes its default branch into
    // `isMainAccountCredentialUsable()`, which opens the physical `auth.json` -- twice per
    // spawn, because subagent fallback re-enters the preview through the callback below.
    //
    // Scoped to ownership, and carrying final auth's value rather than a constant, because
    // preview exists to predict final auth. The request really is served by its own main
    // credential whenever that bearer is forwardable, so main stays eligible; while retained
    // recovery or a profile drain fences the physical identity, final auth drops main and preview
    // has to drop it too. A hardcoded `true` would be wrong in the second case and `false` in
    // the first.
    requestOwnedMainCredential: previewRequestScopedMainCredential,
    isMainAccountTokenLive: previewRequestScopedMainCredential
      ? () => previewRequestOwnedMainCredentialLive
      : undefined,
    // Preview must reach the same answer as the final resolution, including the uploaded-file
    // retention (#4778): a preview that reported a quota move the request will not make would
    // hand subagent fallback a different account than the one that actually serves.
    retainAccountForUploadedFiles: conversationCarriesUploadedFiles(parsed._rawBody),
  };
  let selectedForwardHeaders = req.headers;
  let subagentFallbackAccountId = config.activeCodexAccountId ?? null;
  // A typed fact for providers that refuse fallback-routed turns (the Antigravity ACP policy): set only
  // where a fallback actually moves the route (a selection that keeps the requested model is not one),
  // never inferred from headers, models or tools.
  let subagentFallbackSelected = false;
  let subagentFallbackAccountPreview: SubagentPoolAccountPreview | undefined;
  let subagentFallbackModelEligibleAccountIdsForModel: SubagentModelEligibleAccountIds | undefined;
  let subagentQuotaFailureModel = parsed.modelId;
  const parentThreadId = req.headers.get("x-codex-parent-thread-id")?.trim() ?? null;
  const poolAffinityKey = codexPoolAffinityKey(completeClaudeBridgePoolIdentity(req.headers, options)) ?? null;
  // Preview has to see the same lineage resolve does. Without it, a child's first turn is
  // previewed as a cold pick and resolved onto the family account, and the subagent fallback
  // then decides model eligibility against an account the request will never use.
  //
  // "The same" means both halves of the question the final resolution asks. The Authorization
  // it will be given, because the lineage scope is an HMAC of exactly that header; and its own
  // Pool-state predicate: fixed selectors and request-owned credentials never use stored-credential
  // lineage. An opt-in request-owned key has its own namespace; previewing a stored family binding
  // would hand model fallback an account this request will not use. Preview is read-only: only
  // eligible stored-credential resolutions record lineage.
  const poolLineage = previewCodexPoolLineage(previewAuthHeaders, options.codexAuthPolicy ?? config, {
    accountId: route.codexAccountId,
    modelId: route.modelId,
    admission: options.admission,
    requestScopedMainCredential: previewRequestScopedMainCredential,
  });

  try {
    if (
      threadSpawn
      && route.codexAccountId === undefined
      && !(hasUnexpandedPreviousResponse && isCanonicalOpenAiForwardProvider(route.provider))
    ) {
      await maybePrimeSubagentQuota(config, Date.now(), { nativeMainReadsForbidden });
    }

  // Subagent fallback must settle the final model/provider BEFORE route-dependent
  // normalization (virtual models, effort caps, service tier, wire protocol).
  // Preview the preferred Codex account without acquiring a probe lease or refreshing
  // tokens — auth is resolved only after the final route is selected.
  if (
    threadSpawn
    && !options.comboAttempt
    && (route.codexAccountId === undefined || initialSubagentFallbackChain !== null)
  ) {
    // The final resolveCodexAuthContext binds under codexQuotaScopeForModel(route.modelId),
    // so the preview must read the same scope slot — an undefined scope would map to the
    // "legacy" affinity bucket and never find a binding made under "shared" or a native
    // model scope, making the preview diverge from the account that actually authenticates.
    const fallbackChain = initialSubagentFallbackChain;
    subagentFallbackModelEligibleAccountIdsForModel = await resolveSubagentFallbackModelEligibility({
      config,
      fallbackChain,
      nativeMainReadsForbidden,
      resolver: options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements,
    });
    const fallbackNow = Date.now();
    subagentFallbackAccountPreview = (modelId, previewNow, modelEligibleAccountIds) => previewCodexAccountForRequest(
      codexRequestAffinityKey(previewAuthHeaders, config, options.codexAuthPolicy ?? config, { accountId: route.codexAccountId, modelId, admission: options.admission, requestScopedMainCredential: previewRequestScopedMainCredential }) ?? null,
      config,
      previewNow,
      codexQuotaScopeForModel(modelId),
      {
        ...previewSelectionOptions,
        modelEligibleAccountIds,
        // Per CANDIDATE model, like the scope and the eligible set above: the preference is
        // model-specific, so hoisting it out of the closure would score every fallback
        // candidate against the requested model's evidence and diverge from final auth (#4768).
        // Under the same native-main read fence final auth applies: the reader validates each
        // cached roster against the account's current credential, and for main that is a
        // synchronous read of the stored token. A preview that read it would both cross the
        // fence and score main differently than the resolution it is supposed to predict.
        deniedModelAccountIds: cachedDeniedCodexAccountIdsForModel(modelId, previewNow, {
          excludeAccountIds: nativeMainReadsForbidden ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined,
        }),
      },
      modelId,
      poolLineage,
    );
    const previewAccountId = route.codexAccountId ?? subagentFallbackAccountPreview(
      route.modelId,
      fallbackNow,
      subagentFallbackModelEligibleAccountIdsForModel?.(route.modelId),
    );
    subagentFallbackAccountId = previewAccountId ?? config.activeCodexAccountId ?? null;
    const fallback = applySubagentModelFallback(
      parsed,
      req.headers,
      config,
      previewAccountId,
      fallbackNow,
      unreadableEncryptedAgentTask,
      previewSelectionOptions,
      subagentFallbackAccountPreview,
      subagentFallbackModelEligibleAccountIdsForModel,
      fallbackChain,
      candidateRoute => canPassThroughEncryptedV2AgentTask(candidateRoute, inboundWire),
      options.admission,
    );
    if (fallback?.refusal) return fallback.refusal;
    if (fallback) {
      if (fallback.to !== fallback.from) subagentFallbackSelected = true;
      (logCtx as unknown as Record<string, unknown>).subagentModelFallbackFrom = fallback.from;
      (logCtx as unknown as Record<string, unknown>).subagentModelFallbackTo = fallback.to;
      if (isInjectionDebugEnabled()) {
        injectionDebugLog(`[opencodex] subagent model fallback ${fallback.from} -> ${fallback.to}`);
      }
    }
    subagentQuotaFailureModel = fallback?.to ?? parsed.modelId;

    if (fallback?.to && !slugsEquivalent(fallback.to, route.modelId)) {
      try {
        route = captureInboundRoutePolicy(
          routeModel(config, fallback.to, routeEvidence(options, parsed)),
        );
        leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
        credentialDomainWasRewritten = true;
        logCtx.routeDecision = route.routeDecision;
        logCtx.policyEligibility = route.policyEligibility;
      } catch (err) {
        const policyRefusal = policyCandidateRefusalResponse(err);
        if (policyRefusal) return policyRefusal;
        if (err instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(projectAdmissionModelDeniedLog(err, logCtx));
        if (err instanceof NoAvailableComboTargetsError) {
          return comboUnavailable(err.comboId, undefined, err.exclusion);
        }
        if (err instanceof NoEligiblePolicyCandidateError) {
          logCtx.routeDecision = err.trace;
        }
        return formatErrorResponse(404, "invalid_request_error", err instanceof Error ? err.message : String(err));
      }
    }
  }
  } finally {
    previewSelectionAdmission?.release();
  }

  let recoveryFailureReason: AgentTaskRecoveryFailureReason | undefined;
  let recoveryAttempts: PersistedUsageAttempt[] | undefined;
  // Native fallback and explicitly trusted direct Responses routes can consume ciphertext,
  // so recover only after final route selection.
  //
  // Deliberately NOT gated on `threadSpawn` (#4089). Switching a live thread from a native
  // ChatGPT model to a routed provider replays a backend-minted encrypted agent message on every
  // later turn, and a model switch is not a spawn, so the spawn requirement failed the thread
  // closed permanently without ever attempting recovery. The trust boundary is
  // `recoveryAdmission()` in ./agent-task-recovery -- Codex originator, live native ChatGPT
  // bearer, matching chatgpt-account-id, no inbound API key, no proxy-admission secret -- which
  // admits only the owner of the session that would be spent. `threadSpawn` narrowed which of
  // that owner's own requests could use their own session; it kept nobody else out. The combo
  // gate above keeps its spawn requirement: that path has its own native-target filtering and
  // per-attempt failover, and the reported defect is on this path.
  if (
    inboundWire === "responses"
    && agentTaskRecovery
    && !isCanonicalOpenAiForwardProvider(route.provider)
    && !options.comboAttempt
    && !canPassThroughEncryptedV2AgentTask(route, inboundWire)
  ) {
    let recovered = restoreCachedEncryptedAgentTasks(
      req, (body as { input?: unknown } | undefined)?.input, config, { parentThreadId },
    ) > 0;
    unreadableEncryptedAgentTask = hasUnreadableEncryptedAgentTask(
      (body as { input?: unknown } | undefined)?.input,
    );
    if (unreadableEncryptedAgentTask) try {
      const result = await recoverEncryptedAgentTaskWithResult(
        req,
        (body as { input?: unknown } | undefined)?.input,
        agentTaskRecovery,
        config,
        {
          parentThreadId,
          abortSignal: options.abortSignal,
          onSend: hasUnexpandedPreviousResponse ? ({ model, status, durationMs, usage }) => {
            const attempts = recoveryAttempts ??= [];
            const ordinal = (logCtx.attempts?.length ?? 0) + attempts.length + 1;
            const attempt = beginRequestAttempt(ordinal, OPENAI_CODEX_PROVIDER_ID, model, "openai-responses");
            noteAttemptSend(attempt, undefined);
            finishRequestAttempt(attempt, status ?? 502, durationMs, usageFromResponsesPayload(usage));
            if (status === undefined) {
              attempt.failureStage = "pre-header";
              attempt.failureCause = "transport-ambiguous";
            } else {
              attributePhysicalAttempt(attempt);
            }
            attempts.push(attempt);
          } : undefined,
        },
      );
      recovered = result.recovered;
      recoveryFailureReason = result.recovered ? undefined : result.reason;
    } catch {
      recovered = false;
      recoveryFailureReason = undefined;
    }
    if (recovered) {
      unreadableEncryptedAgentTask = hasUnreadableEncryptedAgentTask(
        (body as { input?: unknown } | undefined)?.input,
      );
      if (!unreadableEncryptedAgentTask) {
        try {
          const reparsed = parseRequest(body);
          const kept: Array<keyof OcxParsedRequest> = [
            "_plaintextV2Decision",
            "_plaintextV2EverPrepared",
            "_previousResponseInputExpanded",
            "_providerContinuation",
            "_providerContinuationCandidate",
            "_providerContinuationOwner",
            "_cursorConversationId",
            "_clientThreadId",
            "_codexOwnThreadId",
            "_promptCacheKeyIsSharedCohort",
            "_cursorClientThreadId",
            "_reasoningReplayScope",
            "_nativeReasoningRetention",
            "_cursorIsolateConversation",
            "_codexNewHistory",
            "_proxyOwnedSystemPrompt",
          ];
          for (const key of kept) {
            if (parsed[key] !== undefined) {
              (reparsed as unknown as Record<string, unknown>)[key] = parsed[key];
            }
          }
          bindTurnTerminationScope(reparsed, resolvedConversationId);
          parsed = reparsed;
          // The recovery mutated `body.input` in place, so `_rawBody` now carries decrypted task
          // text. Bar it from the continuation cache before any recording path can reach it —
          // that cache is persisted to disk, which would defeat the recovery cache's TTL.
          markBodyNonPersistable(parsed._rawBody);

          // The ciphertext-only pass intentionally excludes routed candidates. Once recovery
          // makes the assignment readable, run selection again with the full configured chain
          // and keep the route in sync with any newly selected fallback.
          const recoverySelectionAdmission = codexAccountSelectionForTurn(options.turnAdmissionLease)?.();
          const fallback = (() => {
            try {
              const recoveryNativeMainBlocked = isNativeMainTrafficBlocked();
              // Recompute ownership here rather than reusing the pre-decryption value: a
              // subagent fallback above may have re-routed, and `requestScopedMainCredential`
              // is a function of the route as well as the headers.
              const recoveryAuthHeaders = codexRouteCredentialDomainHeaders(
                req,
                route,
                options,
                credentialDomainWasRewritten,
                config,
              );
              const recoveryRequestScopedMainCredential = codexRouteCredentialOwnership(
                recoveryAuthHeaders,
                config,
                route,
                options,
              ).requestScopedMainCredential && hasCallerCodexBearer(recoveryAuthHeaders);
              // Recovery's own answer to the same question, against the route it may have moved
              // to. Reconstructing the options without it is what left pool eligibility outside
              // the fence on the first preview (#4850); recovery re-previews, so it would leave
              // the same two reads on the one path that runs after decryption.
              const recoveryRequestOwnedMainPin = requestOwnedMainPinState(
                recoveryAuthHeaders,
                config,
                options.codexAuthPolicy ?? config,
                recoveryRequestScopedMainCredential,
                route.codexAccountId,
                codexQuotaScopeForModel(route.modelId),
              ).preserve;
              // Same shared expression as the first preview and as final auth (#5019), recomputed
              // against the route recovery may have moved to.
              const recoveryRequestOwnedMainCredentialLive = requestOwnedMainCredentialIsLive({
                preserveRequestOwnedMainPin: recoveryRequestOwnedMainPin,
                requestScopedMainCredential: recoveryRequestScopedMainCredential,
                nativeMainTrafficBlocked: recoveryNativeMainBlocked,
                mainProfileDraining: recoverySelectionAdmission?.mainProfileDraining === true,
                callerOwnsCooledPoolSubscription: false,
              });
              const recoverySelectionOptions = {
                nativeMainSelectionOnly: !recoveryNativeMainBlocked
                  && recoverySelectionAdmission?.mainProfileDraining === true,
                requestOwnedMainCredential: recoveryRequestScopedMainCredential,
                isMainAccountTokenLive: recoveryRequestScopedMainCredential
                  ? () => recoveryRequestOwnedMainCredentialLive
                  : undefined,
                // #4778, same reason as `previewSelectionOptions` above: this preview decides
                // which account subagent fallback scores against, and final auth passes the
                // retention. Recovery is exactly where the two could diverge -- it re-previews
                // against the DECRYPTED body, which is the first point at which a file reference
                // that was ciphertext-only becomes readable, so reconstructing the options
                // without the bit lets preview report a quota move the request will not make.
                retainAccountForUploadedFiles: conversationCarriesUploadedFiles(parsed._rawBody),
              };
              const recoveryNow = Date.now();
              // Carry the entitlement filter through recovery too (#2509/#2623). The scope was
              // already re-previewed per candidate here; the ELIGIBLE-ACCOUNT set was not, so a
              // recovered assignment could select an account that is not entitled to the model
              // and then fail closed at final auth — the same class of stale-selection bug as
              // the quota scope, one layer over.
              subagentFallbackAccountPreview = (modelId, previewNow, modelEligibleAccountIds) => previewCodexAccountForRequest(
                codexRequestAffinityKey(recoveryAuthHeaders, config, options.codexAuthPolicy ?? config, { accountId: route.codexAccountId, modelId, admission: options.admission, requestScopedMainCredential: recoveryRequestScopedMainCredential }) ?? null,
                config,
                previewNow,
                codexQuotaScopeForModel(modelId),
                {
                  ...recoverySelectionOptions,
                  modelEligibleAccountIds,
                  // Same read fence as the first preview, evaluated against recovery's own view
                  // of the drain AND of credential ownership, rather than the one captured before
                  // decryption. Omitting ownership here would reopen the fence the first preview
                  // closes, on the one path that re-previews after the route may have moved.
                  deniedModelAccountIds: cachedDeniedCodexAccountIdsForModel(modelId, previewNow, {
                    excludeAccountIds: recoveryRequestScopedMainCredential
                      || recoveryNativeMainBlocked
                      || recoverySelectionAdmission?.mainProfileDraining === true
                      ? new Set([MAIN_CODEX_ACCOUNT_ID])
                      : undefined,
                  }),
                },
                modelId,
                previewCodexPoolLineage(recoveryAuthHeaders, options.codexAuthPolicy ?? config, { accountId: route.codexAccountId, modelId, admission: options.admission, requestScopedMainCredential: recoveryRequestScopedMainCredential }),
              );
              const recoveryPreviewAccountId = subagentFallbackAccountPreview(
                parsed.modelId,
                recoveryNow,
                subagentFallbackModelEligibleAccountIdsForModel?.(parsed.modelId),
              );
              return applySubagentModelFallback(
                parsed,
                req.headers,
                config,
                recoveryPreviewAccountId,
                recoveryNow,
                false,
                recoverySelectionOptions,
                subagentFallbackAccountPreview,
                subagentFallbackModelEligibleAccountIdsForModel,
                undefined,
                undefined,
                options.admission,
              );
            } finally {
              recoverySelectionAdmission?.release();
            }
          })();
          if (fallback?.refusal) return fallback.refusal;
          if (fallback) {
            if (fallback.to !== fallback.from) subagentFallbackSelected = true;
            (logCtx as unknown as Record<string, unknown>).subagentModelFallbackFrom = fallback.from;
            (logCtx as unknown as Record<string, unknown>).subagentModelFallbackTo = fallback.to;
            if (isInjectionDebugEnabled()) {
              injectionDebugLog(`[opencodex] subagent model fallback ${fallback.from} -> ${fallback.to}`);
            }
          }
          subagentQuotaFailureModel = fallback?.to ?? parsed.modelId;

          if (fallback?.to && !slugsEquivalent(fallback.to, route.modelId)) {
            try {
              route = captureInboundRoutePolicy(
                routeModel(config, fallback.to, routeEvidence(options, parsed)),
              );
              leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
              credentialDomainWasRewritten = true;
              logCtx.routeDecision = route.routeDecision;
              logCtx.policyEligibility = route.policyEligibility;
            } catch (err) {
              const policyRefusal = policyCandidateRefusalResponse(err);
              if (policyRefusal) return policyRefusal;
              if (err instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(projectAdmissionModelDeniedLog(err, logCtx));
              if (err instanceof NoAvailableComboTargetsError) {
                return comboUnavailable(err.comboId, undefined, err.exclusion);
              }
              if (err instanceof NoEligiblePolicyCandidateError) {
                logCtx.routeDecision = err.trace;
              }
              return formatErrorResponse(
                404,
                "invalid_request_error",
                err instanceof Error ? err.message : String(err),
              );
            }
          }
        } catch {
          unreadableEncryptedAgentTask = true;
        }
      }
    }
  }

  if (options.abortSignal?.aborted) return clientCancelledResponse();

  if (inboundWire === "responses" && isCanonicalOpenAiForwardProvider(route.provider)) {
    const rewritten = sanitizeEncryptedContentInPlace(
      (body as { input?: unknown } | undefined)?.input,
    );
    if (rewritten > 0) {
      console.warn(
        `[opencodex] rewrote ${rewritten} non-Fernet encrypted_content part(s) before canonical native replay`,
      );
    }
  }

  // Encrypted child tasks may reach the canonical native backend or an explicitly trusted
  // direct Responses route. This runs against the FINAL route so native-only fallback can
  // rescue an incompatible primary without weakening combo behavior.
  const finalRouteCanPassThroughEncryptedTask = !options.comboAttempt
    && canPassThroughEncryptedV2AgentTask(route, inboundWire);
  if (
    (route.combo !== undefined || !isCanonicalOpenAiForwardProvider(route.provider))
    && !finalRouteCanPassThroughEncryptedTask
    && unreadableEncryptedAgentTask
  ) {
    return unreadableEncryptedAgentTaskResponse(recoveryFailureReason);
  }

  // The guard above asks whether the CURRENT worker task is readable, and it only inspects the
  // tail item. An `agent_message` that mixes readable text with backend ciphertext answers
  // "readable" to that question at every position, so it passed -- and then
  // `normalizeRoutedAgentMessages` refused to lower it, because lowering requires every part to
  // be representable. The raw Responses passthrough serialized the private item as it stood, so
  // backend ciphertext and an item type only the Codex backend declares reached a third-party
  // provider, which answered `422 unknown item type "agent_message"` (#4454).
  //
  // The opaque-blob path already knows the repair: replace the undecryptable part with an
  // omission marker, which leaves the item lowerable. It applied that repair only AFTER an
  // upstream rejection. For a destination that cannot accept the private item under any
  // circumstances, that round trip was never going to succeed and sent the ciphertext to find
  // out, so do the repair here instead. Recovery above has already had its chance to turn the
  // same bytes into real plaintext; only what it could not rescue reaches this.
  if (inboundWire === "responses" && !finalRouteCanPassThroughEncryptedTask) {
    // Only the raw Responses passthrough puts input items on the wire verbatim, so that is the
    // only wire this has to repair: translated wires rebuild the body from parsed messages, where
    // `inputContentParts` drops an encrypted part instead of forwarding it. The exemption is the
    // canonical Codex backend alone, because it is the one destination that minted these bytes and
    // can read them. `authMode: "forward"` is NOT that test -- a noncanonical forward gateway is
    // somebody else's server that happens to be configured for passthrough, and it receives the
    // ciphertext like any other third party.
    //
    // Combo children run this too. Each child carries its own `structuredClone` of the body
    // (`concreteComboRequestBody`) and its own concrete route, so a sibling's repair is invisible
    // here and a target that resolves to a routed Responses wire would otherwise send the
    // ciphertext that the parent's own dispatch no longer does.
    const wireProvider = resolveWireProtocolOverride(
      route.providerName,
      route.modelId,
      route.provider,
      inboundWire,
      route.staticPolicy,
    );
    if (wireProvider.adapter === "openai-responses" && !isCanonicalOpenAiForwardProvider(wireProvider)) {
      const repaired = stripAgentMessageCiphertextInPlace((body as { input?: unknown } | undefined)?.input);
      if (repaired > 0) {
        console.warn(
          `[opencodex] replaced ciphertext in ${repaired} replayed agent message(s) with an omission marker; the selected provider cannot read native ChatGPT ciphertext`,
        );
      }
    }
  }

  // The canonical ChatGPT backend rejects previous_response_id, so a local replay miss leaves no
  // safe way to recover the omitted history. Fail before dispatching the continuation itself
  // instead of stripping the id and silently forwarding a context-free delta (#702).
  // Codex recognizes previous_response_not_found on WebSocket errors and reconnects with its
  // full input. A generic invalid_request_error instead terminates the task after cache expiry.
  if (
    hasUnexpandedPreviousResponse
    && isCanonicalOpenAiForwardProvider(route.provider)
  ) {
    markLinkTurnMissing(logCtx);
    const code = "previous_response_not_found";
    logCtx.provider = route.providerName;
    logCtx.model = route.modelId;
    logCtx.errorCode = code;
    // A recovery send already finished on its own model and status. Keep it off activeAttempt,
    // which the log finalizer stamps with the continuation's terminal outcome.
    if (recoveryAttempts) (logCtx.attempts ??= []).push(...recoveryAttempts);
    if (logCtx.attempts?.some(attempt => attempt.sendCount > 0)) logCtx.terminalSource = "synthetic";
    else markLocalRequestLogRefusal(logCtx, code);
    return markProxyError(formatErrorResponse(
      400,
      code,
      "Continuation state is unavailable or corrupt; resend the full conversation without previous_response_id.",
    ));
  }

  if (hasUnexpandedPreviousResponse) {
    const continuationProvider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy);
    // Can the DESTINATION see the history this process failed to restore? Only the native
    // Responses passthrough can: it forwards previous_response_id to a backend that stored the
    // chain. Every translated wire rebuilds the conversation from this request's input alone —
    // including the three that look stateful, for the reasons recorded in
    // responses/continuation-ownership.ts — so a replay miss there is not a degraded turn. It is
    // the entire conversation deleted, with one user line left in its place and nothing in the
    // response saying so. Refuse before auth or upstream I/O and let the client resend.
    const continuationWire = resolvedAdapterWire(continuationProvider.adapter);
    const upstreamOwnsOmittedHistory = continuationWire === "openai-responses"
      // Stateless destinations cannot resolve the omitted prefix. Stateful destinations may,
      // but a lowered custom result still needs its call to recover the original wire type.
      // Native function/custom continuations without lowering keep their upstream-owned state.
      ? !(continuationProvider.statelessResponses === true
        || hasUnmappedRoutedCustomToolOutput(parsed._rawBody, continuationProvider.supportsResponsesCustomTools))
      // An unknown adapter is left to the resolution error it already raises below.
      : continuationWire === undefined || PROVIDER_OWNED_CONTINUATION_WIRES.has(continuationWire);
    if (!upstreamOwnsOmittedHistory) {
      markLinkTurnMissing(logCtx);
      return markProxyError(formatErrorResponse(
        400,
        "previous_response_not_found",
        "Continuation state is unavailable or corrupt; resend the full conversation without previous_response_id.",
      ));
    }
  }

  // Captured before normalization: whether the CLIENT asked for SSE. The
  // transport-neutral upstream-streaming policy below may force a bounded JSON
  // upstream for reliability (#875); the answer must then be reframed to SSE
  // for streaming clients.
  const clientRequestedStream = parsed.stream;
  const admittedPolicyRoute = { providerName: route.providerName, modelId: route.modelId };
  // Final guard before normalization may inject guidance into the raw body.
  leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
  await applyFinalRouteRequestNormalization({
    parsed,
    route,
    config,
    req,
    logCtx,
    inboundWire,
    inboundTransport: options.inboundTransport,
    claudeGoAffinity: options.claudeGoAffinity,
    droidDefaultEffort: options.droidDefaultEffort,
  });
  try {
    assertPolicyNormalizedRoute(policyScope, admittedPolicyRoute, route);
    const copilotNegotiationPending = route.providerName === "github-copilot" && route.provider.authMode !== "forward";
    if (!options.anthropicHostedAdvisorSelection && !copilotNegotiationPending && route.provider.adapter === "openai-chat"
      && !chatCanPreserveMandatoryToolChoice(parsed._rawBody, route.provider, route.modelId, parsed.context.tools ?? [])) {
      // Combo children carry the refusal's local identity too, so a compatible sibling target
      // can still be tried; a direct request keeps the client-facing 400 below.
      if (policyScope.eligibility || options.comboAttempt) throw new MandatoryToolChoiceUnavailableError();
      return mandatoryToolChoiceUnavailableResponse();
    }
  } catch (error) {
    const policyRefusal = policyCandidateRefusalResponse(error);
    if (policyRefusal) return policyRefusal;
    throw error;
  }
  // Static normalization can move the destination: resolving an
  // OpenAI virtual model rewrites route.modelId to the wire id that will
  // actually be billed. A scope checked only before this would authorize the
  // public selector and send the wire model, so the settled route is checked
  // once more here.
  const scopedDestination = parsed._wireModelOverride === undefined
    ? route
    : { providerName: route.providerName, modelId: parsed._wireModelOverride };
  // Synthetic turns keep the original client envelope label across provider normalization.
  if (options.compactionRoutingOverride || options.mainHardLockFallbackOverride || options.clientResponseModelLabel
    || options.internalDecisionCall || options.memoryModelPhase || options.visionDescribeTerminal
    || options.policyFallbackCandidate || parsed._memoryModelPhase || logCtx.shadowCallRewrittenFrom) {
    parsed._responseModelId = clientFacingModelText(options.clientResponseModelLabel ?? inboundSelector);
  }
  if (!routeAllowedByScope(admissionScope, scopedDestination)) {
    return admissionModelDeniedResponse(projectAdmissionModelDeniedLog(new AdmissionModelDeniedError(inboundSelector, scopedDestination), logCtx));
  }
  // A typed Advisor runs its own model server-side on this provider (#8448). An out-of-scope
  // declaration is withheld. A named selection also needs that declaration on the final route.
  const serverTools = parsed._anthropicServerTools;
  const scopedServerTools = scopedAnthropicServerTools(admissionScope, route, serverTools);
  if (serverTools && scopedServerTools && scopedServerTools.length !== serverTools.length) {
    parsed._anthropicServerTools = scopedServerTools;
    if (advisorServerToolDestination(route.provider)) addProtocolEntryReason(logCtx, "advisor-tool-outside-model-scope");
  }
  if (options.anthropicHostedAdvisorSelection) {
    if (options.anthropicHostedAdvisorSelection === "ambiguous") {
      return markProxyError(formatErrorResponse(400, "invalid_request_error",
        "The hosted Advisor tool_choice is ambiguous because multiple tools are named advisor."));
    }
    if (!admitsHostedAdvisor(route.provider, scopedServerTools, parsed.context.tools)) {
      return markPolicyCandidateRefusal(markProxyError(formatErrorResponse(400, "invalid_request_error",
        "The selected hosted Advisor tool is unavailable for this route or model scope.")));
    }
  }
  // Attribute local auth/cooldown failures to the public selector too; exact auth may fail before
  // the normal post-resolution provider label is assigned.
  if (route.codexAccountNamespace) {
    logCtx.provider = `${route.providerName}-${route.codexAccountNamespace}`;
  }

  if (options.abortSignal?.aborted) return clientCancelledResponse();
  // Resolve aliases/combo children before refusing helpers; do not spend main auth or host budget.
  if (isCanonicalOpenAiForwardProvider(route.provider)
    && isCodexReserveHelperUnsupported(options.codexAuthPolicy ?? config, route.modelId,
      options.admission, options.visionDescribeTerminal === true)) {
    return markProxyError(formatErrorResponse(400, "invalid_request_error", CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE));
  }
  // #4940: the opt-in is off, so every Reserve affordance in this process is inert -- no catalog
  // row, no main-credential substitution, no authorization handshake, and no `luna-reserve` header
  // on the send. Forwarding `gpt-reserve` as an ordinary native model therefore buys nothing but a
  // 429 "The usage limit has been reached", which names neither the real cause nor the setting the
  // operator would have to change. Refuse here instead, on the same terms and in the same place as
  // the helper refusal above: after alias/combo resolution, before auth, host-circuit budget or any
  // upstream byte.
  //
  // Two narrowings beyond the predicate, both about not answering a question this refusal cannot
  // answer correctly. A terminal vision/search helper is excluded because enabling the opt-in would
  // not make it work -- it would produce the helper refusal above instead, so telling that caller to
  // enable the flag is advice that does not hold. Non-native inbound wires are excluded because a
  // `gpt-reserve` selector reaching us over Chat or Anthropic Messages is an operator-authored
  // route (a `claudeCode.modelMap` entry, say), not a Codex client that was forced onto Reserve by
  // its own usage snapshot, and that route keeps whatever behavior it has today.
  if (inboundWire === "responses"
    && options.visionDescribeTerminal !== true
    && isCanonicalOpenAiForwardProvider(route.provider)
    && isCodexReserveOptInMissing(options.codexAuthPolicy ?? config, route.modelId, options.admission)) {
    return markProxyError(formatErrorResponse(400, "invalid_request_error", CODEX_RESERVE_OPT_IN_REQUIRED_MESSAGE));
  }
  // Refuse an input that cannot plausibly fit the model context window before spending auth,
  // circuit budget, or upstream bandwidth on a turn the provider will reject anyway (#1412).
  //
  // Compaction turns are exempt: Codex sends compaction_trigger BECAUSE context is full, so
  // refusing the turn that shrinks the context would deadlock the client against the very
  // limit this gate reports — it would be told to compact and then denied the compaction.
  if (parsed._compactionRequest !== true) {
    // A combo child is the one caller that can afford a strict gate: skipping a target it
    // cannot fit is safe before any upstream bytes are sent, and the ladder continues. A
    // direct request has nowhere to go, so it keeps the loose pathological-input gate.
    const inputAdmission = options.comboAttempt && options.comboContextDegraded !== true
      ? checkComboTargetInputAdmission(parsed, route.provider, route.providerName, parsed.modelId, nativeContextLimits(config))
      : checkInputAdmission(parsed, route.provider, route.providerName, parsed.modelId, nativeContextLimits(config));
    if (!inputAdmission.admitted) {
      // #1524: this is a LOCAL preflight refusal, not an upstream verdict. A policy or combo
      // fallback must be able to skip this candidate and try one whose context window fits,
      // instead of treating the first incompatible candidate as the end of the chain. The
      // distinct code is what lets the fallback layer tell the two apart -- an upstream
      // `context_length_exceeded` still stops, because retrying it elsewhere is guesswork.
      projectLocalModelRefusalLog(logCtx, inboundSelector);
      if (clientRequestedStream && !options.comboAttempt) {
        return streamingContextOverflowResponse(
          clientFacingModelText(inboundSelector),
          translatorBudget,
        );
      }
      return markProxyError(formatErrorResponse(
        413,
        "input_admission_refused",
        inputAdmissionRefusalMessage(inputAdmission, inboundSelector),
      ), "input");
    }
  }
  const preAuthHostKey = preAuthUpstreamHostCircuitKey(route, config);
  if (preAuthHostKey) {
    const admission = acquireUpstreamHostAdmission(
      preAuthHostKey,
      config.upstreamHostCircuitThreshold,
    );
    if (admission.kind === "blocked") {
      return upstreamHostCircuitOpenResponse(admission.retryAfterSeconds);
    }
    admissionState.pendingHostAdmissionLease = admission.lease;
  }

  let substituteMainCredential = false;
  let callerAuthHeaders: Headers;
  {
    // #4778: uploaded files are scoped to the account that issued them, so a conversation
    // carrying live references must retain its binding across a voluntary quota move. Answered
    // from the body alone, by the same predicate the refusal guard uses, so the two can never
    // disagree about which conversations are in scope.
    const finalAuth = await resolveResponsesCodexAuth(
      req,
      config,
      route,
      options,
      credentialDomainWasRewritten,
      conversationCarriesUploadedFiles(parsed._rawBody),
    );
    if (!finalAuth.ok) return finalAuth.response;
    admissionState.authCtx = finalAuth.authCtx;
    selectedForwardHeaders = withClaudeNativeSession(finalAuth.headers, route.provider, options.claudeNativeSessionId);
    callerAuthHeaders = withClaudeNativeSession(finalAuth.callerAuthHeaders, route.provider, options.claudeNativeSessionId);
    substituteMainCredential = finalAuth.substituteMainCredential;
  }

  try {
    route.provider = applyCodexAuthContextToProvider(route.provider, admissionState.authCtx, route.codexAccountMode);
  } catch (error) {
    releaseCodexAuthContextProbeLease(admissionState.authCtx);
    if (options.abortSignal?.aborted || req.signal.aborted) return clientCancelledResponse();
    const mapped = mapCodexAuthContextErrorToResponse(error, { now: Date.now(), accountSelector: route.codexAccountNamespace });
    if (mapped) return mapped;
    throw error;
  }
  applyCodexAccountGatedWireNormalization(parsed, route, logCtx);
  try {
    recordPolicyPreparedDestination(policyScope, route.providerName, parsed._wireModelOverride ?? parsed.modelId);
  } catch (error) {
    const policyRefusal = policyCandidateRefusalResponse(error);
    if (policyRefusal) return policyRefusal;
    throw error;
  }
  logCtx.provider = route.codexAccountNamespace
    ? `${route.providerName}-${route.codexAccountNamespace}`
    : formatCodexProviderForLog(route.providerName, codexLogAccountId(admissionState.authCtx), config);
  logCtx.accountLogLabel = codexAuthContextLogLabel(admissionState.authCtx, config);
  // A move is the expensive event: it discards the prefix warmed on the previous account. Record
  // it as an event with its cause, so the operator reads it off one line instead of inferring it
  // from account labels across many (#4546).
  noteCodexSelectionAffinity(logCtx, admissionState.authCtx);
  {
    const binding = conversationStateBindingFromAuth(admissionState.authCtx, poolAffinityKey);
    if (binding) {
      // Before the scrub, because a file reference is refused rather than removed and the
      // refusal has to happen while there is still no dispatch to undo.
      const refusal = accountChangeFileReferenceRefusal({
        body: parsed._rawBody,
        bindingKey: binding.bindingKey,
        servingAccountId: binding.accountId,
      });
      if (refusal) return refusal;
      applyAccountChangeConversationStateScrub({
        body: parsed._rawBody,
        headers: selectedForwardHeaders,
        parsed,
        preserveReasoningEncryptedContent: isCanonicalOpenAiForwardProvider(route.provider)
          && parsed._nativeReasoningRetention?.accountSwitch === true,
        bindingKey: binding.bindingKey,
        servingAccountId: binding.accountId,
        logCtx,
      });
    }
  }
  // Seed an account-derived scope before final adapter binding. Cursor never treats it as
  // authoritative: bindRouteReasoningReplayScope replaces it with the exact route owner or a
  // per-request fail-closed sentinel after the final provider and credential are known.
  const identityScope = codexLogAccountId(admissionState.authCtx);
  if (identityScope) parsed._cursorIdentityScope = identityScope;
  subagentFallbackAccountId = admissionState.authCtx.kind === "pool" || admissionState.authCtx.kind === "main-pool"
    ? admissionState.authCtx.accountId
    : config.activeCodexAccountId ?? null;

  commitSkillsSnapshot?.();
  return {
    inboundWire,
    ...(turnMembership ? { turnMembership } : {}),
    ...(turnMembership && inboundWire === "responses" && parsed.stream && !parsed._compactionRequest ? { completedToolBlocks: true as const } : {}),
    clientDeclaredEmptyToolCatalog: options.clientDeclaredEmptyToolCatalog === true,
    clientToolCatalogRestriction,
    // Admission facts later route rewrites must not re-derive: the selector the caller sent and
    // the key scope as it stood when this request was admitted.
    inboundSelector,
    admissionScope,
    advisorAdmissionPolicy,
    translatorBudget,
    parsed,
    toolBridgeMaps,
    responseStateOptions,
    rememberKiroDeliveredFinalAnswer,
    route,
    get selectedForwardHeaders(): typeof selectedForwardHeaders {
      return selectedForwardHeaders;
    },
    set selectedForwardHeaders(value: typeof selectedForwardHeaders) {
      selectedForwardHeaders = value;
    },
    get subagentFallbackAccountId(): typeof subagentFallbackAccountId {
      return subagentFallbackAccountId;
    },
    set subagentFallbackAccountId(value: typeof subagentFallbackAccountId) {
      subagentFallbackAccountId = value;
    },
    subagentQuotaFailureModel,
    subagentFallbackSelected,
    poolAffinityKey,
    clientRequestedStream,
    substituteMainCredential,
    callerAuthHeaders,
  };
}

export type PreparedResponsesRequest = Exclude<Awaited<ReturnType<typeof prepareResponsesRequest>>, Response>;