fix(responses): sanitize Codex metadata and route vision by backend capability

docs-site/src/content/docs/fr/guides/combos.md

@@ -365,3 +365,9 @@ message de validation.
 
 L’erreur était terminale plutôt que spécifique à la cible. Corriger une entrée invalide, réduire un contexte surdimensionné,
 gérer un refus de politique ou corriger l’origine de la demande rejetée. Les combos ne sautent pas dans ces cas-là.
+
+## Compatibilité des paramètres facultatifs
+
+Exception aux erreurs 400 terminales : un rejet structuré de `user`, une valeur non prise en charge pour `reasoning.effort`/`reasoning_effort`, ou un rejet d’entrée d’image propre à un modèle (`param: input`) peut faire passer le combo à la cible admissible suivante, sans délai de refroidissement. Le refus de sécurité, l’annulation et une sortie déjà commencée restent non rejouables.
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

docs-site/src/content/docs/guides/combos.md

@@ -213,7 +213,8 @@ Combo failures are divided into **hop** failures and **terminal** failures.
 | HTTP 401, 403, 404, 408, 429, or any 5xx | Cool the target and hop to the next eligible target. |
 | HTTP 410 with an explicit model end-of-life, retired, deprecated, sunset, decommissioned, or no-longer-available signal | Cool that target and hop. Unrelated 410 responses remain terminal. |
 | Classified authentication, subscription, quota, rate-limit, overload, or upstream-server error | Cool the target and hop, even when the status alone is not sufficient. |
-| Client cancellation (499), `origin_rejected`, cyber-policy refusal, context overflow, or invalid request | Stop and return the error; another target would not make the request valid. |
+| Client cancellation (499), `origin_rejected`, cyber-policy refusal, context overflow, or other invalid request | Stop and return the error; another target would not make the request valid. |
+| Structured HTTP 400 rejecting optional `user`, an unsupported reasoning effort, or model-scoped image input | Hop before output commitment without cooling; see optional-control compatibility below. |
 | Any other unclassified error | Stop and return the error. |
 
 When `cooldownMs` is unset, a hopped target uses an upstream fallback: 5 seconds for request-rate
@@ -227,8 +228,8 @@ fallback for upstream rate-limit codes `1302`/`1305` → the 60-second default.
 `Retry-After: 0` remains an immediate upstream directive rather than being replaced by a configured
 cooldown.
 
-The current request never retries the same attempted target. Later requests skip it until its
-cooldown expires. A `Retry-After` HTTP-date that is already in the past is also preserved as an
+The current request never retries the same attempted target. Later requests skip a cooled target until its
+cooldown expires; request-local compatibility rejections do not cool the target. A `Retry-After` HTTP-date that is already in the past is also preserved as an
 immediate upstream directive, just like `Retry-After: 0`. Set `waitForCooldownMs` to allow a later
 request to wait for the earliest eligible target cooldown, up to that cap on each selection attempt,
 and then make one fresh selection. A request may therefore wait up to `hops × waitForCooldownMs`
@@ -254,6 +255,12 @@ another provider, which prevents duplicate text and tool execution. If the pre-o
 its safety cap without a terminal or output boundary, OpenCodex also commits the current target
 instead of growing memory without a bound.
 
+## Request-local target compatibility
+
+When routing Claude Code to the canonical ChatGPT Codex backend, OpenCodex removes the unsupported top-level `user` metadata field without changing the session/cache key, input messages, tool schemas, or safety identifiers. Public Responses API and noncanonical forward gateways keep that field.
+
+A combo can also advance after an intact HTTP 400 `invalid_request_error` that specifically rejects `user`, reports `unsupported_value` for `reasoning.effort`/`reasoning_effort`, or reports `param: input` with an exact model-scoped `does not support image inputs` rejection. This is a mismatch for that request, not evidence that the target is unhealthy, so it records no cooldown. This compatibility recovery does not silently change `none` into a different effort or broaden this exception to arbitrary invalid requests. Policy refusals, cancellation and already-committed output remain non-replayable. A single-target request still returns an unresolved upstream rejection.
+
 ## Default reasoning effort
 
 `defaultEffort` fills an absent `reasoning.effort` when the combo has a non-null default and the selected target has a known, nonempty supported ladder. If the target supports the configured value, it is retained; otherwise the highest supported rung at or below it is used, or the lowest supported rung when none is lower. Unknown or empty ladders omit the default.

docs-site/src/content/docs/guides/sidecars.md

@@ -123,11 +123,9 @@ failures after response headers have started are delivered as `response.failed`
 
 ## Vision sidecar
 
-When the routed model is listed in its provider's `noVisionModels` — or declared text-only for
-that model via `modelInputModalities` — and a request carries an image, opencodex describes each
-image **before** the main call and replaces it with text, provided a vision sidecar plan is
-available. Without an available plan the raw image is stripped rather than forwarded to a
-text-only backend. The model catalog advertises image input for every sidecar-covered model.
+Image routing is capability-aware. Before an image-bearing upstream send, opencodex resolves the selected model's effective input modalities from runtime provider evidence, explicit operator declarations, backend/registry metadata, and generated vendor metadata. A target positively known to be text-only goes through the Vision Sidecar first; the image is described **before** the main call and replaced inline with text. A target positively known to support images receives the image directly. Unknown custom models keep the existing compatibility behavior rather than being guessed text-only.
+
+For the canonical ChatGPT Codex route, opencodex uses the `openai-codex` metadata bundle rather than public OpenAI API metadata, so backend-specific modality differences are respected. The native Chat fast path uses the same gate and cannot bypass a known text-only verdict. Without an available sidecar plan, raw images are stripped before a proven text-only backend.
 Combos advertise image input only when every member accepts images, either natively or through a
 sidecar, and the combo's `imageInput` setting is not disabled, so clients such as the Codex app
 allow attachments instead of blocking them before the sidecar runs. When
@@ -164,10 +162,12 @@ sidecar-backed by default; Zen routes are unchanged and were not probed in this
   keys (Anthropic keys omit it, since that field is ignored there); mutable `https:` images are not
   cached.
 
-The management API and Dashboard picker now list models that can actually accept image input.
-When the matching backend is available, `gpt-5.6-luna` (OpenAI) and `claude-haiku-4-5` (Anthropic)
-are always offered as baseline options. `PUT /api/sidecar-settings` rejects a model known to be
-text-only, but still accepts an unknown id so custom or ahead-of-catalog names keep working.
+The management API and Dashboard picker list models that can accept image input. When the matching
+backend is available, `gpt-5.6-luna` (OpenAI) and `claude-haiku-4-5` (Anthropic) are always offered
+as baseline options. `PUT /api/sidecar-settings` may retain an unknown custom/ahead-of-catalog id.
+An explicitly configured routed Vision Sidecar is therefore usable unless capability evidence proves
+that model cannot accept images; this preserves operator-selected custom sidecars without allowing a
+known text-only sidecar to receive image bytes.
 
 ```json
 {

docs-site/src/content/docs/ja/guides/combos.md

@@ -260,3 +260,9 @@ ocx combo remove <id> --yes
 ### 最初のエラーの後にフェイルオーバーが停止したのはなぜですか?
 
 このエラーはターゲット固有のものではなく、最終的なものでした。無効な入力を修正し、大きすぎるコンテキストを削減し、ポリシーの拒否を処理し、拒否されたリクエストの送信元を修正します。コンボはそのような場合には機能しません。
+
+## 任意パラメーターの互換性
+
+通常の 400 エラーは終了扱いですが、`user` の明示的な拒否、`reasoning.effort`/`reasoning_effort` の非対応値、またはモデル固有の画像入力拒否（`param: input`）を示す構造化エラーでは、出力開始前に次の適格なターゲットへ進めます。この不一致ではクールダウンを記録しません。安全ポリシーによる拒否、キャンセル、出力開始後の再実行は禁止のままです。
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

docs-site/src/content/docs/ko/guides/combos.md

@@ -272,3 +272,9 @@ opencodex 인스턴스에 기록했는지 확인하세요.
 대상별 오류가 아니라 종결 오류였기 때문입니다. 잘못된 입력을 수정하고, 너무 큰 context를 줄이고,
 정책 거부를 처리하거나, 거부된 요청 origin을 바로잡으세요. combo는 이런 경우 다음 대상으로 넘어가지
 않습니다.
+
+## 선택적 매개변수 호환성
+
+일반적인 400 오류는 종료되지만, `user`를 명시적으로 거부하거나 `reasoning.effort`/`reasoning_effort`의 지원되지 않는 값 또는 모델별 이미지 입력 거부(`param: input`)를 나타내는 구조화된 오류는 출력 시작 전에 다음 적격 대상으로 넘어갈 수 있습니다. 이 경우 쿨다운을 기록하지 않습니다. 보안 정책 거부, 취소 및 이미 시작된 출력은 재실행하지 않습니다.
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

docs-site/src/content/docs/ru/guides/combos.md

@@ -319,3 +319,9 @@ CLI и дашборд показывают точное сообщение ва
 Ошибка была terminal, а не специфичной для конкретной цели. Исправьте некорректный ввод, сократите
 слишком большой контекст, обработайте отказ политики или исправьте отклонённое происхождение
 запроса. В таких случаях combo не выполняют hop.
+
+## Совместимость необязательных параметров
+
+Исключение для завершающих ошибок 400: структурированный отказ от `user`, неподдерживаемое значение `reasoning.effort`/`reasoning_effort` или специфичный для модели отказ входного изображения (`param: input`) позволяет до начала вывода перейти к следующей допустимой цели без периода охлаждения. Отказ политики безопасности, отмена и уже начавшийся вывод по-прежнему запрещают повторное выполнение.
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

docs-site/src/content/docs/tr/guides/combos.md

@@ -404,3 +404,9 @@ Hata hedefe özgü olmaktan ziyade uç (terminal) bir hataydı. Geçersiz girdiy
 düzeltin, aşırı büyük bir bağlamı azaltın, bir politika reddini işleyin veya
 reddedilen istek kaynağını düzeltin. Kombolar bu durumlar için atlama yapmaz.
 
+
+## İsteğe bağlı parametre uyumluluğu
+
+Sonlandırıcı 400 hatalarının dar bir istisnası vardır: `user` alanını açıkça reddeden, `reasoning.effort`/`reasoning_effort` için desteklenmeyen değer bildiren veya modele özgü görüntü girdisini reddeden (`param: input`) yapılandırılmış hata, çıktı başlamadan sonraki uygun hedefe geçebilir. Bu uyumsuzluk için bekleme süresi kaydedilmez. Güvenlik politikası reddi, iptal ve başlamış çıktı yeniden yürütülmez.
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

docs-site/src/content/docs/zh-cn/guides/combos.md

@@ -290,3 +290,9 @@ combo id 不存在。响应是 HTTP 404，类型为 `invalid_request_error`。
 ### 为什么故障切换在第一次错误后就停止了？
 
 该错误是终止性的，而不是针对目标的。修复无效输入、缩小过大的上下文、处理策略拒绝，或者纠正被拒绝的请求来源。对于这些情况，combo 不会继续跳转。
+
+## 可选参数兼容性
+
+一般 400 错误仍会终止请求，但明确拒绝 `user`、对 `reasoning.effort`/`reasoning_effort` 返回不支持值，或返回模型特定图像输入拒绝（`param: input`）的结构化错误，可让 combo 在输出开始前尝试下一个符合条件的目标，而不记录冷却时间。安全策略拒绝、取消以及已经开始的输出仍不可重放。
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

docs-site/src/content/docs/zh-tw/guides/combos.md

@@ -290,3 +290,9 @@ Combo id 未知。回應為 HTTP 404 並帶 type `invalid_request_error`。執
 ### 為什麼 failover 在第一個錯誤後就停止了？
 
 該錯誤是終端的而非目標特定的。修正無效輸入、縮減過大的上下文、處理策略拒絕，或更正被拒的請求來源。Combo 對那些情況不會跳轉。
+
+## 選用參數相容性
+
+一般 400 錯誤仍會終止請求，但明確拒絕 `user`、對 `reasoning.effort`/`reasoning_effort` 回傳不支援值，或回傳模型特定影像輸入拒絕（`param: input`）的結構化錯誤，可讓 combo 在輸出開始前嘗試下一個符合條件的目標，而不記錄冷卻時間。安全政策拒絕、取消及已開始的輸出仍不可重播。
+
+[Canonical compatibility details](/guides/combos/#request-local-target-compatibility).

scripts/generate-model-metadata.ts

@@ -44,8 +44,13 @@ const COST_VENDOR_BUNDLES = [
   "zai", "mistral", "cerebras", "azure-openai", "amazon-bedrock", "xiaomi",
 ];
 
+// Capability-only bundles may describe a transport/backend that is not a public provider preset.
+// The canonical ChatGPT Codex forward route has modality differences from the public OpenAI API
+// (for example retired Spark is text-only there), so keep that evidence distinct.
+const CAPABILITY_ONLY_BUNDLES = ["openai-codex"];
+
 const allowedProviders = Array.from(
-  new Set([...Object.values(PROVIDER_ALIASES), ...COST_VENDOR_BUNDLES]),
+  new Set([...Object.values(PROVIDER_ALIASES), ...COST_VENDOR_BUNDLES, ...CAPABILITY_ONLY_BUNDLES]),
 ).sort();
 
 // Models the upstream catalogue lists but the provider rejects at request time. Issue #82:

src/adapters/openai-responses.ts

@@ -1285,6 +1285,15 @@ function stripUnsupportedForwardParams(body: unknown): unknown {
   return rest;
 }
 
+/** Drop client identity metadata only at the canonical Codex destination, not public gateways.
+ * Claude translation still owns local session/cache identity; never mutate its replay body.
+ */
+function stripCanonicalForwardUser(body: unknown): unknown {
+  if (!isPlainObject(body) || !Object.hasOwn(body, "user")) return body;
+  const { user: _user, ...rest } = body;
+  return rest;
+}
+
 /** Return the lossless text represented by one system message, or null when it is multimodal. */
 function canonicalForwardSystemText(item: Record<string, unknown>): string | null {
   const content = item.content;
@@ -2256,6 +2265,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         if (isCanonicalOpenAiForwardProvider(provider)) {
           outBody = stripDeprecatedPromptCacheRetention(outBody, parsed.modelId);
           outBody = stripCanonicalForwardPromptCacheOptions(outBody);
+          outBody = stripCanonicalForwardUser(outBody);
           outBody = normalizeCanonicalForwardPromptEnvelope(outBody);
           outBody = normalizeCanonicalForwardContinuationEnvelope(outBody);
         }

src/combos/failover.ts

@@ -351,6 +351,49 @@ const PROVIDER_SCOPED_FAILURE_CODES = new Set([
   "insufficient_balance",
 ]);
 
+/**
+ * Precise target-local request incompatibilities are request-local, not terminal for a combo.
+ * Require a bounded, intact provider envelope; never infer compatibility from echoed prompt text.
+ * Only OpenCodex's exact error wrapper may be unwrapped, with a fixed depth budget. Unknown or
+ * conflicting codes fail closed. No fields are removed here and no same-target replay is added.
+ * Image rejection requires `param: input` and an exact model-scoped prefix.
+ */
+function isRequestLocalTargetIncompatibility(status: number, message: string, code?: string | null): boolean {
+  if (status !== 400 || message.length > 16_384) return false;
+  const genericCodes = new Set(["", "invalid_request_error", "unsupported_parameter", "unsupported_value"]);
+  if (!genericCodes.has(normalizedFailureCode(code))) return false;
+  let text = message.trim();
+  for (let depth = 0; depth < 3; depth += 1) {
+    if (text.startsWith("Provider error 400: ")) text = text.slice("Provider error 400: ".length);
+    let payload: unknown;
+    try { payload = JSON.parse(text); } catch { return false; }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+    const error = (payload as Record<string, unknown>).error;
+    if (!error || typeof error !== "object" || Array.isArray(error)) return false;
+    const e = error as Record<string, unknown>;
+    if (e.code !== undefined && e.code !== null && typeof e.code !== "string") return false;
+    const errorCode = normalizedFailureCode(typeof e.code === "string" ? e.code : undefined);
+    if (!genericCodes.has(errorCode) || typeof e.message !== "string") return false;
+    if (e.type !== "invalid_request_error" && e.type !== "upstream_error") return false;
+    if (e.message.startsWith("Provider error 400: ") && e.param === undefined
+      && (errorCode === "" || errorCode === "invalid_request_error")) {
+      text = e.message;
+      continue;
+    }
+    if (e.type !== "invalid_request_error") return false;
+    if (e.message === "Unsupported parameter: user") {
+      return (e.param === undefined || e.param === "user") && errorCode !== "unsupported_value";
+    }
+    if (errorCode === "unsupported_value"
+      && (e.param === "reasoning.effort" || e.param === "reasoning_effort")
+      && e.message.startsWith("Unsupported value:") && e.message.includes("not supported")) return true;
+    return e.param === "input"
+      && (errorCode === "" || errorCode === "invalid_request_error")
+      && /^Model '[^']{1,256}' does not support image inputs\./.test(e.message);
+  }
+  return false;
+}
+
 export function comboFailureCooldownScope(
   status: number,
   message: string,
@@ -363,6 +406,7 @@ export function comboFailureCooldownScope(
     || REQUEST_SHAPE_FAILURE_CODES.has(code)
     || isRequestLocalFreePromptCap(status, message, options?.code)
     || isProviderTargetContextOverflow(status, message, options?.code)
+    || isRequestLocalTargetIncompatibility(status, message, options?.code)
   ) return "none";
   if (isProviderScopedQuotaCap(status, message, options?.code)) return "provider";
   // A rejected or unpaid credential is provider-wide evidence: every target that routes
@@ -465,6 +509,7 @@ export function comboFailureDecision(
   // `free_rate_limited` no longer routes through `isProviderScopedQuotaCap` (it is a
   // per-request cap, not provider-wide evidence), so keep its hop verdict explicit here.
   if (failureCode === "free_rate_limited") return "hop";
+  if (isRequestLocalTargetIncompatibility(status, message, options?.code)) return "hop";
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }