From 0fef0cdf41206a1c28c4c2ddcb631f2216507338 Mon Sep 17 00:00:00 2001
From: luvs01 <27862058+luvs01@users.noreply.github.com>
Date: Wed, 9 Sep 2026 22:42:22 +0900
Subject: [PATCH 1/6] fix(chat): enforce effort caps without model pins

---
 .../docs/fr/reference/configuration/agents.md |  2 +
 .../docs/ja/reference/configuration/agents.md |  2 +
 .../docs/ko/reference/configuration/agents.md |  2 +
 .../docs/reference/configuration/agents.md    |  2 +
 .../docs/ru/reference/configuration/agents.md |  2 +
 .../docs/tr/reference/configuration/agents.md |  2 +
 .../zh-cn/reference/configuration/agents.md   |  2 +
 .../zh-tw/reference/configuration/agents.md   |  2 +
 src/server/chat-native.ts                     | 20 ++++--
 .../model-pinned-effort.test.ts               | 66 ++++++++++++++++++-
 10 files changed, 94 insertions(+), 8 deletions(-)

diff --git a/docs-site/src/content/docs/fr/reference/configuration/agents.md b/docs-site/src/content/docs/fr/reference/configuration/agents.md
index 03e289e3e9..60ce3c0340 100644
--- a/docs-site/src/content/docs/fr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/fr/reference/configuration/agents.md
@@ -24,6 +24,8 @@ Les paramètres des agents déterminent la surface de collaboration Codex annonc
 | `subagentEffortCap?` | `string` | — | Plafond supplémentaire réservé aux tours enfants créés. Lorsque les deux plafonds s’appliquent, le plus bas l’emporte. |
 | `agentTaskRecovery?` | `object` | — | Mécanisme expérimental, soumis à activation explicite, pour récupérer les tâches v2 chiffrées par le service en amont lorsqu’elles sont envoyées à des fournisseurs routés. Désactivé sauf si `enabled: true` ; voir [Récupération des tâches v2 chiffrées](#récupération-des-tâches-v2-chiffrées). |
 
+Les plafonds configurés s’appliquent aux tours Chat Completions natifs admissibles même sans effort épinglé pour le modèle. Les tours principaux v2 admissibles utilisent `effortCap` ; les tours enfants portant les marqueurs requis utilisent le plus bas des plafonds principal et enfant applicables. Le mode explicite `multiAgentMode: "v1"` et les opérations de compaction échappent aux plafonds. Un plafond ne fait que réduire ou omettre un effort explicite ; la conversion vers la valeur du fournisseur intervient lorsqu’un épinglage est appliqué ou qu’un plafond modifie la valeur. Les valeurs de l’appelant natif conservent leur forme d’origine si aucun épinglage n’est appliqué et qu’aucun plafond ne les réécrit.
+
 Gérez la surface depuis le tableau de bord ou avec `ocx v2 status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>`. Les changements de mode s’appliquent aux nouvelles sessions. `maxConcurrentThreadsPerSession` est un champ de `PUT /api/v2`, et non une clé de `config.json`. Après l’activation de v2, `ocx v2 threads <n>` écrit `max_concurrent_threads_per_session` sous `[features.multi_agent_v2]` dans le fichier `$CODEX_HOME/config.toml` de Codex.
 
 Le **mode Ultra** — accessible depuis l’interrupteur Sous-agents du tableau de bord, le champ `multiAgentModeHintText` de `PUT /api/v2` et `ocx v2 mode-hint` — écrit `features.multi_agent_v2.multi_agent_mode_hint_text` dans le fichier `$CODEX_HOME/config.toml` de Codex. La commande CLI `ocx v2 mode-hint` conserve cette clé même lorsque `multi_agent_v2` est désactivé ; elle n’active ni ne désactive la fonctionnalité. Cette indication remplace la politique multi-agents que codex-rs déduit du niveau d’effort : tous les modèles et tous les niveaux d’effort reçoivent alors le prompt de délégation Proactive. Elle ne modifie **pas** le niveau d’effort de raisonnement.
diff --git a/docs-site/src/content/docs/ja/reference/configuration/agents.md b/docs-site/src/content/docs/ja/reference/configuration/agents.md
index def092132c..eea4ef5530 100644
--- a/docs-site/src/content/docs/ja/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ja/reference/configuration/agents.md
@@ -22,6 +22,8 @@ description: マルチエージェント サーフェス、委任ガイダンス
 | `effortCap?` | `string` | — | v2 のメイン ターンとマークされた子ターンの条件を満たすためのハード シーリング。 `low` ～ `ultra` を受け入れます。 |
 | `subagentEffortCap?` | `string` | — |スポーンされた子のターンのみの追加の上限。両方の上限が適用される場合は、低い方が優先されます。 |
 
+モデルの effort pin がなくても、対象のネイティブ Chat Completions ターンには設定された上限が適用されます。対象の v2 メインターンには `effortCap`、生成された子ターンのマーカーがある場合には適用可能なメインと子の上限のうち低い方を使用します。明示的な `multiAgentMode: "v1"` と compaction の保守処理は上限の対象外です。上限は明示された effort を下げるか省略するだけで、pin を適用した場合、または上限で値を変更した場合にプロバイダーの送信値へ変換します。pin の適用も上限による書き換えもない呼び出し元の値は元の表記を維持します。
+
 ダッシュボードまたは `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>` でサーフェスを管理します。モードの変更は新しいセッションに適用されます。 `maxConcurrentThreadsPerSession` は `PUT /api/v2` フィールドであり、`config.json` キーではありません。 `ocx v2 threads <n>` は、v2 が有効になった後、Codex の `$CODEX_HOME/config.toml` の `[features.multi_agent_v2]` の下に `max_concurrent_threads_per_session` を書き込みます。
 
 管理 API は、`GET`/`PUT /api/v2`、`/api/injection-model`、`/api/effort-caps`、`/api/subagent-models`、および `/api/subagent-model-fallback` を公開します。インジェクションモデルの更新は部分的です。カスタム プロンプトは、その API の `prompt` フィールドです。
diff --git a/docs-site/src/content/docs/ko/reference/configuration/agents.md b/docs-site/src/content/docs/ko/reference/configuration/agents.md
index 5393052849..c2ecce6b43 100644
--- a/docs-site/src/content/docs/ko/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ko/reference/configuration/agents.md
@@ -22,6 +22,8 @@ description: 멀티 에이전트 표면, 위임 안내, 선호 모델, 대체 
 | `effortCap?` | `string` | — | 자격을 갖춘 v2 메인 턴과 표시된 생성 하위 턴에 대한 하드 상한입니다. `low`부터 `ultra`까지 허용합니다. |
 | `subagentEffortCap?` | `string` | — | 생성된 하위 턴에만 적용되는 추가 상한입니다. 두 상한이 모두 적용되면 더 낮은 값이 이깁니다. |
 
+모델 effort pin이 없어도 적용 대상 native Chat Completions 요청에는 설정된 상한이 적용됩니다. 대상 v2 메인 요청에는 `effortCap`을, 생성된 자식 표지가 있는 요청에는 메인·자식 상한 중 적용 가능한 더 낮은 값을 사용합니다. 명시적 `multiAgentMode: "v1"`과 compaction 유지관리 요청은 상한 적용에서 제외됩니다. 상한은 명시된 effort를 낮추거나 제거하며, pin을 적용하거나 상한이 값을 바꾼 경우에 제공자 전송 값으로 매핑합니다. pin 적용도 상한에 의한 변경도 없는 호출자 값은 원래 표기를 유지합니다.
+
 이 표면은 대시보드나 `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>`로 관리합니다. 모드 변경은 새 세션에 적용됩니다. `maxConcurrentThreadsPerSession`은 `config.json` 키가 아니라 `PUT /api/v2` 필드입니다. `ocx v2 threads <n>`는 v2가 활성화된 뒤 Codex의 `$CODEX_HOME/config.toml` 안 `[features.multi_agent_v2]` 아래에 `max_concurrent_threads_per_session`을 기록합니다.
 
 관리 API는 `GET`/`PUT /api/v2`, `/api/injection-model`, `/api/effort-caps`, `/api/subagent-models`, `/api/subagent-model-fallback`를 제공합니다. injection-model 업데이트는 부분 업데이트입니다. 사용자 지정 프롬프트는 이 API의 `prompt` 필드입니다.
diff --git a/docs-site/src/content/docs/reference/configuration/agents.md b/docs-site/src/content/docs/reference/configuration/agents.md
index 24dd9dec16..df3b3fe804 100644
--- a/docs-site/src/content/docs/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/reference/configuration/agents.md
@@ -39,6 +39,8 @@ still depends on upstream support for your account.
 | `subagentEffortCap?` | `string` | — | Additional ceiling for spawned-child turns only. When both caps apply, the lower wins. |
 | `agentTaskRecovery?` | `object` | — | Experimental opt-in recovery for backend-encrypted v2 tasks sent to routed providers. Disabled unless `enabled: true`; see [Encrypted v2 task recovery](#encrypted-v2-task-recovery). |
 
+Configured effort caps apply to eligible native Chat Completions turns even without a model effort pin. Qualifying v2 main turns use `effortCap`; marked spawned-child turns use the lower applicable main/child ceiling. Explicit `multiAgentMode: "v1"` and compaction maintenance bypass caps. A cap only lowers or omits explicit effort, and provider wire mapping runs when a pin is applied or a cap changes the value. Native caller values retain their original wire spelling when no pin is applied and no cap rewrite occurs.
+
 Manage the surface with the dashboard or
 `ocx v2 status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>`.
 Mode changes apply to new sessions. `maxConcurrentThreadsPerSession` is a `PUT /api/v2` field, not a
diff --git a/docs-site/src/content/docs/ru/reference/configuration/agents.md b/docs-site/src/content/docs/ru/reference/configuration/agents.md
index 831f49bcf9..3f36df5460 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/agents.md
@@ -23,6 +23,8 @@ description: Multi-agent surface, guidance при делегировании, pr
 | `effortCap?` | `string` | — | Жёсткий потолок effort для qualifying v2 main-turn'ов и помеченных spawned-child turn'ов. Принимает `low`–`ultra`. |
 | `subagentEffortCap?` | `string` | — | Дополнительный потолок только для spawned-child turn'ов. Если применимы оба cap'а, выигрывает более низкий. |
 
+Настроенные потолки effort применяются к подходящим нативным запросам Chat Completions даже без закреплённого effort модели. Основные запросы с поверхностью v2 используют `effortCap`, а помеченные дочерние запросы — меньший из применимых основного и дочернего потолков. Явный режим `multiAgentMode: "v1"` и служебная компактизация обходят потолки. Потолок только снижает или удаляет явно заданный effort; преобразование в значение провайдера выполняется, когда применяется закрепление или потолок меняет значение. Значения нативного вызывающего клиента сохраняют исходное написание, если закрепление не применяется и потолок не переписывает значение.
+
 Управляйте surface через дашборд или `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>`.
 Смена режима применяется к новым сессиям. `maxConcurrentThreadsPerSession` — это поле
 `PUT /api/v2`, а не ключ `config.json`; `ocx v2 threads <n>` записывает
diff --git a/docs-site/src/content/docs/tr/reference/configuration/agents.md b/docs-site/src/content/docs/tr/reference/configuration/agents.md
index 128ac3920a..4993a6bb88 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/agents.md
@@ -25,6 +25,8 @@ kontrol eder.
 | `subagentEffortCap?` | `string` | — | Yalnızca oluşturulan çocuk turları için ek tavan. Her iki sınır da geçerli olduğunda daha düşük olan kazanır. |
 | `agentTaskRecovery?` | `object` | — | Yönlendirilen sağlayıcılara gönderilen arka uçta şifrelenmiş v2 görevleri için deneysel isteğe bağlı kurtarma. `enabled: true` olmadıkça devre dışıdır; bkz. [Şifrelenmiş v2 görev kurtarma](#sifrelenmis-v2-gorev-kurtarma). |
 
+Yapılandırılmış effort sınırları, model effort sabitlemesi olmasa da uygun yerel Chat Completions turlarına uygulanır. Uygun v2 ana turları `effortCap` değerini, işaretlenmiş çocuk turları ise geçerli ana ve çocuk sınırlarının düşük olanını kullanır. Açık `multiAgentMode: "v1"` ayarı ve compaction bakım turları bu sınırlardan muaftır. Sınır yalnızca açık effort değerini düşürür veya kaldırır; sağlayıcının iletim değerine eşleme, sabitleme uygulandığında veya sınır değeri değiştirdiğinde yapılır. Sabitleme uygulanmayan ve sınır tarafından yeniden yazılmayan yerel çağıran değerleri özgün yazımını korur.
+
 Arayüzü kontrol paneli veya `ocx v2 status|on|off|mode <v1|default|v2>|threads
 <n>|mode-hint <metin|--clear>` ile yönetin. Mod değişiklikleri yeni oturumlara
 uygulanır. `maxConcurrentThreadsPerSession`, bir `config.json` anahtarı değil,
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
index 094e6df720..a3e7bdcf00 100644
--- a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
@@ -22,6 +22,8 @@ description: 多代理界面、委派引导、首选模型、回退链、原生
 | `effortCap?` | `string` | — | 对符合条件的 v2 主轮次和标记的派生子轮次设置硬上限。接受 `low` 到 `ultra`。 |
 | `subagentEffortCap?` | `string` | — | 仅针对派生子轮次的额外上限。两个上限同时适用时，较低者生效。 |
 
+即使没有设置模型 effort pin，符合条件的原生 Chat Completions 轮次也会应用配置的上限。符合条件的 v2 主轮次使用 `effortCap`；带有派生子轮次标记的请求使用适用的主轮次和子轮次上限中的较低值。显式 `multiAgentMode: "v1"` 和 compaction 维护请求不应用上限。上限只会降低或省略显式 effort；应用 pin 或上限改变值时，才会映射为提供方的传输值。未应用 pin 且未被上限改写的原生调用方值保留原始写法。
+
 通过仪表板或 `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>` 管理该界面。模式变更会应用于新会话。`maxConcurrentThreadsPerSession` 是 `PUT /api/v2` 字段，不是 `config.json` 键；`ocx v2 threads <n>` 会在启用 v2 后，将 `max_concurrent_threads_per_session` 写入 Codex 的 `$CODEX_HOME/config.toml` 中的 `[features.multi_agent_v2]` 下。
 
 管理 API 公开 `GET`/`PUT /api/v2`、`/api/injection-model`、`/api/effort-caps`、`/api/subagent-models` 和 `/api/subagent-model-fallback`。injection-model 更新是部分更新；自定义 prompt 是该 API 上的 `prompt` 字段。
diff --git a/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md b/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
index d3fdf7059b..a960781728 100644
--- a/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
@@ -21,6 +21,8 @@ Agent 設定控制要廣告哪個 Codex 協作介面，以及 opencodex 如何
 | `effortCap?` | `string` | — | 合格 v2 主回合與標記的生成子回合的硬性上限。接受 `low` 到 `ultra`。 |
 | `subagentEffortCap?` | `string` | — | 僅針對生成子回合的額外上限。當兩個上限都適用時，取較低者。 |
 
+即使沒有設定模型 effort pin，符合條件的原生 Chat Completions 回合也會套用設定的上限。符合條件的 v2 主回合使用 `effortCap`；帶有生成子回合標記的請求使用適用的主回合與子回合上限中的較低值。明確的 `multiAgentMode: "v1"` 與 compaction 維護請求不套用上限。上限只會降低或省略明確指定的 effort；套用 pin 或上限改變值時，才會對應為供應商的傳輸值。未套用 pin 且未被上限改寫的原生呼叫端值保留原始寫法。
+
 使用儀表板或 `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>` 管理介面。模式變更套用於新 session。`maxConcurrentThreadsPerSession` 是 `PUT /api/v2` 欄位，不是 `config.json` key；`ocx v2 threads <n>` 在啟用 v2 後，將 `max_concurrent_threads_per_session` 寫入 Codex 的 `$CODEX_HOME/config.toml` 中 `[features.multi_agent_v2]` 之下。
 
 管理 API 暴露 `GET`/`PUT /api/v2`、`/api/injection-model`、`/api/effort-caps`、`/api/subagent-models` 與 `/api/subagent-model-fallback`。注入模型更新為部分更新；自訂 prompt 是該 API 的 `prompt` 欄位。
diff --git a/src/server/chat-native.ts b/src/server/chat-native.ts
index 7f3c97c10e..9fb24e143a 100644
--- a/src/server/chat-native.ts
+++ b/src/server/chat-native.ts
@@ -105,19 +105,27 @@ function normalizePinnedChatEffort(options: HandleNativeChatOptions): void {
   const from = typeof chatBody.reasoning_effort === "string" ? chatBody.reasoning_effort : undefined;
   logCtx.requestedEffort = from;
   // Compaction is normally excluded by native-route eligibility; preserve that boundary here too.
-  const pinned = chatBody.compaction_trigger === undefined
+  const compaction = chatBody.compaction_trigger !== undefined;
+  const pinned = !compaction
     ? resolvePinnedEffort(route, selector, config)
     : undefined;
+  let normalizeForWire = false;
   if (pinned !== undefined) {
     logCtx.requestedEffort = from ? `${from}->${pinned}` : pinned;
     if (pinned === "none") delete chatBody.reasoning_effort;
     else chatBody.reasoning_effort = pinned;
-    // The native lane historically passes caller effort through, including with caps set.
-    // Only a newly operator-pinned value enters the cap and provider-mapping pipeline.
-    if (effortCapAppliesTo(chatCollabSurface(chatBody), req.headers, config)) {
-      const capped = applyChatEffortCap(chatBody, req.headers, config, supportedLadderFor(route));
-      if (capped) logCtx.requestedEffort = `${logCtx.requestedEffort}->${capped.to}`;
+    normalizeForWire = true;
+  }
+  // A qualifying turn's ceiling is independent of whether an operator pin resolved.
+  if (effortCapAppliesTo(chatCollabSurface(chatBody), req.headers, config, compaction)) {
+    const capped = applyChatEffortCap(chatBody, req.headers, config, supportedLadderFor(route));
+    if (capped) {
+      logCtx.requestedEffort = `${logCtx.requestedEffort ?? capped.from}->${capped.to}`;
+      normalizeForWire = true;
     }
+  }
+  // Normalize operator-pinned values and cap rewrites; otherwise preserve caller spelling.
+  if (normalizeForWire) {
     const effort = typeof chatBody.reasoning_effort === "string" ? chatBody.reasoning_effort : undefined;
     const wireEffort = mapReasoningEffort(route.provider, route.modelId, effort);
     if (wireEffort === undefined) delete chatBody.reasoning_effort;
diff --git a/tests/codex-integration/model-pinned-effort.test.ts b/tests/codex-integration/model-pinned-effort.test.ts
index 7c7b15401c..a808b86767 100644
--- a/tests/codex-integration/model-pinned-effort.test.ts
+++ b/tests/codex-integration/model-pinned-effort.test.ts
@@ -428,12 +428,74 @@ describe("operator pins on the actual request wire", () => {
     expect(wire.reasoning).toEqual({ effort: "max", summary: "auto" });
   });
 
-  test("native Chat without pins preserves caller wire spelling and existing cap behavior", async () => {
+  test("native Chat without pins caps spawned children and preserves unqualified caller spelling", async () => {
     const c = config({ reasoningEfforts: ["low"], reasoningEffortMap: { max: "enabled" } }, { effortCap: "low", subagentEffortCap: "low" });
-    expect((await request(c, "chat", { reasoning_effort: "ultra" }, { "x-openai-subagent": "collab_spawn" })).reasoning_effort).toBe("ultra");
+    expect((await request(c, "chat", { reasoning_effort: "ultra" }, { "x-openai-subagent": "collab_spawn" })).reasoning_effort).toBe("low");
+    expect((await request(c, "chat", { reasoning_effort: "ultra" })).reasoning_effort).toBe("ultra");
     expect(Object.hasOwn(await request(c, "chat", { reasoning_effort: undefined }), "reasoning_effort")).toBe(false);
   });
 
+  test("native Chat without pins caps v2 main turns and preserves forced v1", async () => {
+    const c = config({}, { effortCap: "medium", subagentEffortCap: "low" });
+    const tools = [{ type: "function", function: { name: "spawn_agent", parameters: { type: "object", properties: {} } } }];
+    expect((await request(c, "chat", { tools, reasoning_effort: "ultra" })).reasoning_effort).toBe("medium");
+    expect((await request(c, "chat", { tools, reasoning_effort: "ultra" }, { "x-openai-subagent": "collab_spawn" })).reasoning_effort).toBe("low");
+    c.multiAgentMode = "v1";
+    expect((await request(c, "chat", { tools, reasoning_effort: "ultra" }, { "x-openai-subagent": "collab_spawn" })).reasoning_effort).toBe("ultra");
+  });
+
+  test("native Chat maps newly capped values and preserves lower, non-ladder and absent efforts", async () => {
+    const c = config({ reasoningEffortMap: { medium: "enabled", low: "disabled" } }, { subagentEffortCap: "medium" });
+    const headers = { "x-codex-turn-metadata": JSON.stringify({ subagent_kind: "thread_spawn" }) };
+    expect((await request(c, "chat", { reasoning_effort: "ultra" }, headers)).reasoning_effort).toBe("enabled");
+    expect((await request(c, "chat", { reasoning_effort: "low" }, headers)).reasoning_effort).toBe("low");
+    expect((await request(c, "chat", { reasoning_effort: "enabled" }, headers)).reasoning_effort).toBe("enabled");
+    expect(Object.hasOwn(await request(c, "chat", { reasoning_effort: undefined }, headers), "reasoning_effort")).toBe(false);
+    c.providers.fixture!.pinnedReasoningEffort = "medium";
+    expect((await request(c, "chat", { reasoning_effort: "medium" })).reasoning_effort).toBe("enabled");
+  });
+
+  test("native Chat without pins omits effort when no supported rung fits the cap", async () => {
+    for (const reasoningEfforts of [[], ["high", "max"]]) {
+      const c = config({ reasoningEfforts }, { subagentEffortCap: "low" });
+      const wire = await request(c, "chat", { reasoning_effort: "max", temperature: 0.4 }, { "x-openai-subagent": "collab_spawn" });
+      expect(Object.hasOwn(wire, "reasoning_effort")).toBe(false);
+      expect(wire.temperature).toBe(0.4);
+    }
+  });
+
+  test("direct native Chat compaction keeps its pin and cap exemption", async () => {
+    const c = config({ pinnedReasoningEffort: "high" }, { subagentEffortCap: "low" });
+    const chatBody = { model: "fixture/pin-model", messages: [{ role: "user", content: "summarize" }],
+      reasoning_effort: "ultra", compaction_trigger: {} };
+    const req = new Request("http://localhost/v1/chat/completions", { method: "POST", headers: { "x-openai-subagent": "collab_spawn" } });
+    const response = await handleNativeChatCompletions({ req, config: c, logCtx: { model: "", provider: "" },
+      route: routeModel(c, chatBody.model), chatBody, requestedModel: chatBody.model,
+      requestedStream: false, translatorBudget: createTestTranslatorBudget() });
+    expect(response.status, await response.text()).toBe(200);
+    expect(captured.at(-1)!.body.reasoning_effort).toBe("ultra");
+  });
+
+  test("native cap retries retain their annotation and restore original effort for a new destination", async () => {
+    const c = config({}, { defaultProvider: "first", subagentEffortCap: "high", providers: {
+      first: provider({ reasoningEfforts: ["low", "max"] }),
+      second: provider({ reasoningEfforts: ["medium", "high"] }),
+    } });
+    const chatBody = { model: "first/pin-model", messages: [{ role: "user", content: "hello" }], reasoning_effort: "ultra" };
+    const req = new Request("http://localhost/v1/chat/completions", { method: "POST", headers: { "x-openai-subagent": "collab_spawn" } });
+    const annotations: Array<string | undefined> = [];
+    for (const name of ["first", "first", "second"]) {
+      const logCtx = { model: "", provider: "", requestedEffort: undefined as string | undefined };
+      const response = await handleNativeChatCompletions({ req, config: c, logCtx,
+        route: routeModel(c, `${name}/pin-model`), chatBody, requestedModel: `${name}/pin-model`,
+        requestedStream: false, translatorBudget: createTestTranslatorBudget() });
+      expect(response.status, await response.text()).toBe(200);
+      annotations.push(logCtx.requestedEffort);
+    }
+    expect(captured.map(({ body }) => body.reasoning_effort)).toEqual(["low", "low", "high"]);
+    expect(annotations).toEqual(["ultra->low", "ultra->low", "ultra->high"]);
+  });
+
   test("unpinned Responses keeps its existing applicable cap", async () => {
     expect((await request(config({}, { subagentEffortCap: "medium" }), "responses",
       { reasoning: { effort: "max", summary: "auto" } }, { "x-openai-subagent": "collab_spawn" })).reasoning_effort).toBe("medium");

From ac03c292c0e05523ecced1ca5bdfaad1ee20a1cf Mon Sep 17 00:00:00 2001
From: luvs01 <27862058+luvs01@users.noreply.github.com>
Date: Thu, 10 Sep 2026 10:18:25 +0900
Subject: [PATCH 2/6] docs: consolidate localized native Chat effort guidance

---
 .../src/content/docs/ko/reference/configuration/agents.md     | 4 ++--
 .../src/content/docs/ru/reference/configuration/agents.md     | 4 ++--
 .../src/content/docs/tr/reference/configuration/agents.md     | 4 ++--
 .../src/content/docs/zh-cn/reference/configuration/agents.md  | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs-site/src/content/docs/ko/reference/configuration/agents.md b/docs-site/src/content/docs/ko/reference/configuration/agents.md
index c2ecce6b43..e5c03a8112 100644
--- a/docs-site/src/content/docs/ko/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ko/reference/configuration/agents.md
@@ -22,8 +22,6 @@ description: 멀티 에이전트 표면, 위임 안내, 선호 모델, 대체 
 | `effortCap?` | `string` | — | 자격을 갖춘 v2 메인 턴과 표시된 생성 하위 턴에 대한 하드 상한입니다. `low`부터 `ultra`까지 허용합니다. |
 | `subagentEffortCap?` | `string` | — | 생성된 하위 턴에만 적용되는 추가 상한입니다. 두 상한이 모두 적용되면 더 낮은 값이 이깁니다. |
 
-모델 effort pin이 없어도 적용 대상 native Chat Completions 요청에는 설정된 상한이 적용됩니다. 대상 v2 메인 요청에는 `effortCap`을, 생성된 자식 표지가 있는 요청에는 메인·자식 상한 중 적용 가능한 더 낮은 값을 사용합니다. 명시적 `multiAgentMode: "v1"`과 compaction 유지관리 요청은 상한 적용에서 제외됩니다. 상한은 명시된 effort를 낮추거나 제거하며, pin을 적용하거나 상한이 값을 바꾼 경우에 제공자 전송 값으로 매핑합니다. pin 적용도 상한에 의한 변경도 없는 호출자 값은 원래 표기를 유지합니다.
-
 이 표면은 대시보드나 `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>`로 관리합니다. 모드 변경은 새 세션에 적용됩니다. `maxConcurrentThreadsPerSession`은 `config.json` 키가 아니라 `PUT /api/v2` 필드입니다. `ocx v2 threads <n>`는 v2가 활성화된 뒤 Codex의 `$CODEX_HOME/config.toml` 안 `[features.multi_agent_v2]` 아래에 `max_concurrent_threads_per_session`을 기록합니다.
 
 관리 API는 `GET`/`PUT /api/v2`, `/api/injection-model`, `/api/effort-caps`, `/api/subagent-models`, `/api/subagent-model-fallback`를 제공합니다. injection-model 업데이트는 부분 업데이트입니다. 사용자 지정 프롬프트는 이 API의 `prompt` 필드입니다.
@@ -89,4 +87,6 @@ opencodex는 비활성, 라우팅 불가, 비정상, 쿨다운 중, 또는 할
 
 상한은 노력만 낮춥니다. 모델이 광고한 단계 중 상한 이하에서 가장 높은 단계로 맞춥니다. 모델에 노력 제어가 없거나 맞는 지원 단계가 없으면, opencodex는 노력을 제거하고 제공자 기본값을 적용합니다. `max`와 `ultra`는 허용되며, 대시보드는 `low`부터 `xhigh`까지 제공합니다.
 
+모델 effort pin이 없어도 적용 대상 native Chat Completions 요청에는 설정된 상한이 적용됩니다. pin을 적용하거나 상한이 값을 바꾼 경우에 제공자 전송 값으로 매핑합니다. pin 적용도 상한에 의한 변경도 없는 호출자 값은 원래 표기를 유지합니다.
+
 v1, default, v2 동작에 대한 초보자용 설명은 [Sub-agent surfaces](/guides/sub-agent-surface/)를 참고하세요.
diff --git a/docs-site/src/content/docs/ru/reference/configuration/agents.md b/docs-site/src/content/docs/ru/reference/configuration/agents.md
index 3f36df5460..f67256f8c4 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/agents.md
@@ -23,8 +23,6 @@ description: Multi-agent surface, guidance при делегировании, pr
 | `effortCap?` | `string` | — | Жёсткий потолок effort для qualifying v2 main-turn'ов и помеченных spawned-child turn'ов. Принимает `low`–`ultra`. |
 | `subagentEffortCap?` | `string` | — | Дополнительный потолок только для spawned-child turn'ов. Если применимы оба cap'а, выигрывает более низкий. |
 
-Настроенные потолки effort применяются к подходящим нативным запросам Chat Completions даже без закреплённого effort модели. Основные запросы с поверхностью v2 используют `effortCap`, а помеченные дочерние запросы — меньший из применимых основного и дочернего потолков. Явный режим `multiAgentMode: "v1"` и служебная компактизация обходят потолки. Потолок только снижает или удаляет явно заданный effort; преобразование в значение провайдера выполняется, когда применяется закрепление или потолок меняет значение. Значения нативного вызывающего клиента сохраняют исходное написание, если закрепление не применяется и потолок не переписывает значение.
-
 Управляйте surface через дашборд или `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>`.
 Смена режима применяется к новым сессиям. `maxConcurrentThreadsPerSession` — это поле
 `PUT /api/v2`, а не ключ `config.json`; `ocx v2 threads <n>` записывает
@@ -138,5 +136,7 @@ Cap'ы умеют только понижать effort. Они опускают
 помещается под cap, opencodex убирает поле effort и позволяет провайдеру применить собственный
 дефолт. `max` и `ultra` принимаются, хотя дашборд предлагает только `low`–`xhigh`.
 
+Настроенные потолки effort применяются к подходящим нативным запросам Chat Completions даже без закреплённого effort модели. Преобразование в значение провайдера выполняется, когда применяется закрепление или потолок меняет значение. Значения нативного вызывающего клиента сохраняют исходное написание, если закрепление не применяется и потолок не переписывает значение.
+
 Если нужен объясняющий вариант для начинающих о поведении v1, default и v2, см.
 [Поверхность подагентов](/guides/sub-agent-surface/).
diff --git a/docs-site/src/content/docs/tr/reference/configuration/agents.md b/docs-site/src/content/docs/tr/reference/configuration/agents.md
index 4993a6bb88..c33f2b14d2 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/agents.md
@@ -25,8 +25,6 @@ kontrol eder.
 | `subagentEffortCap?` | `string` | — | Yalnızca oluşturulan çocuk turları için ek tavan. Her iki sınır da geçerli olduğunda daha düşük olan kazanır. |
 | `agentTaskRecovery?` | `object` | — | Yönlendirilen sağlayıcılara gönderilen arka uçta şifrelenmiş v2 görevleri için deneysel isteğe bağlı kurtarma. `enabled: true` olmadıkça devre dışıdır; bkz. [Şifrelenmiş v2 görev kurtarma](#sifrelenmis-v2-gorev-kurtarma). |
 
-Yapılandırılmış effort sınırları, model effort sabitlemesi olmasa da uygun yerel Chat Completions turlarına uygulanır. Uygun v2 ana turları `effortCap` değerini, işaretlenmiş çocuk turları ise geçerli ana ve çocuk sınırlarının düşük olanını kullanır. Açık `multiAgentMode: "v1"` ayarı ve compaction bakım turları bu sınırlardan muaftır. Sınır yalnızca açık effort değerini düşürür veya kaldırır; sağlayıcının iletim değerine eşleme, sabitleme uygulandığında veya sınır değeri değiştirdiğinde yapılır. Sabitleme uygulanmayan ve sınır tarafından yeniden yazılmayan yerel çağıran değerleri özgün yazımını korur.
-
 Arayüzü kontrol paneli veya `ocx v2 status|on|off|mode <v1|default|v2>|threads
 <n>|mode-hint <metin|--clear>` ile yönetin. Mod değişiklikleri yeni oturumlara
 uygulanır. `maxConcurrentThreadsPerSession`, bir `config.json` anahtarı değil,
@@ -261,5 +259,7 @@ hiçbir basamak uymuyorsa opencodex çabayı kaldırır ve sağlayıcı varsayı
 uygulanmasına izin verir. `max` ve `ultra` kabul edilirken kontrol paneli `low`
 ile `xhigh` arasını sunar.
 
+Yapılandırılmış effort sınırları, model effort sabitlemesi olmasa da uygun yerel Chat Completions turlarına uygulanır. Sağlayıcının iletim değerine eşleme, sabitleme uygulandığında veya sınır değeri değiştirdiğinde yapılır. Sabitleme uygulanmayan ve sınır tarafından yeniden yazılmayan yerel çağıran değerleri özgün yazımını korur.
+
 v1, varsayılan ve v2 davranışının yeni başlayanlara yönelik açıklaması için [Alt
 ajan yüzeyleri](/tr/guides/sub-agent-surface/) sayfasına bakın.
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
index a3e7bdcf00..b55badecab 100644
--- a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
@@ -22,8 +22,6 @@ description: 多代理界面、委派引导、首选模型、回退链、原生
 | `effortCap?` | `string` | — | 对符合条件的 v2 主轮次和标记的派生子轮次设置硬上限。接受 `low` 到 `ultra`。 |
 | `subagentEffortCap?` | `string` | — | 仅针对派生子轮次的额外上限。两个上限同时适用时，较低者生效。 |
 
-即使没有设置模型 effort pin，符合条件的原生 Chat Completions 轮次也会应用配置的上限。符合条件的 v2 主轮次使用 `effortCap`；带有派生子轮次标记的请求使用适用的主轮次和子轮次上限中的较低值。显式 `multiAgentMode: "v1"` 和 compaction 维护请求不应用上限。上限只会降低或省略显式 effort；应用 pin 或上限改变值时，才会映射为提供方的传输值。未应用 pin 且未被上限改写的原生调用方值保留原始写法。
-
 通过仪表板或 `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>` 管理该界面。模式变更会应用于新会话。`maxConcurrentThreadsPerSession` 是 `PUT /api/v2` 字段，不是 `config.json` 键；`ocx v2 threads <n>` 会在启用 v2 后，将 `max_concurrent_threads_per_session` 写入 Codex 的 `$CODEX_HOME/config.toml` 中的 `[features.multi_agent_v2]` 下。
 
 管理 API 公开 `GET`/`PUT /api/v2`、`/api/injection-model`、`/api/effort-caps`、`/api/subagent-models` 和 `/api/subagent-model-fallback`。injection-model 更新是部分更新；自定义 prompt 是该 API 上的 `prompt` 字段。
@@ -88,4 +86,6 @@ opencodex 会跳过已禁用、不可路由、不健康、处于冷却中，或
 
 上限只会降低 effort。它们会向下贴合到不高于上限、且模型公开的最高档位。如果模型没有 effort 控制，或者没有任何受支持的档位可用，opencodex 会移除 effort，让提供方默认值生效。`max` 和 `ultra` 都可接受，而仪表板提供 `low` 到 `xhigh`。
 
+即使没有设置模型 effort pin，符合条件的原生 Chat Completions 轮次也会应用配置的上限。应用 pin 或上限改变值时，才会映射为提供方的传输值。未应用 pin 且未被上限改写的原生调用方值保留原始写法。
+
 关于 v1、default 和 v2 行为的面向初学者说明，请参阅 [Sub-agent surfaces](/guides/sub-agent-surface/)。

From 83e85217776d53e6d196cbcb9424931b9201acb7 Mon Sep 17 00:00:00 2001
From: luvs01 <27862058+luvs01@users.noreply.github.com>
Date: Fri, 11 Sep 2026 21:47:36 +0900
Subject: [PATCH 3/6] docs(agents): keep the effort-cap policy in one section

The new paragraph restated cap eligibility, exemptions, and the
lowering rule that the existing effort-cap section already owns, and
the duplication was repeated across every translated page. Keep only
the new native Chat Completions and wire-mapping detail, and move it
into that section so the policy has a single home.
---
 .../src/content/docs/fr/reference/configuration/agents.md     | 4 ++--
 .../src/content/docs/ja/reference/configuration/agents.md     | 4 ++--
 .../src/content/docs/ko/reference/configuration/agents.md     | 2 +-
 docs-site/src/content/docs/reference/configuration/agents.md  | 4 ++--
 .../src/content/docs/ru/reference/configuration/agents.md     | 4 ++--
 .../src/content/docs/tr/reference/configuration/agents.md     | 4 ++--
 .../src/content/docs/zh-cn/reference/configuration/agents.md  | 2 +-
 .../src/content/docs/zh-tw/reference/configuration/agents.md  | 4 ++--
 8 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs-site/src/content/docs/fr/reference/configuration/agents.md b/docs-site/src/content/docs/fr/reference/configuration/agents.md
index 60ce3c0340..8e6d4522a2 100644
--- a/docs-site/src/content/docs/fr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/fr/reference/configuration/agents.md
@@ -24,8 +24,6 @@ Les paramètres des agents déterminent la surface de collaboration Codex annonc
 | `subagentEffortCap?` | `string` | — | Plafond supplémentaire réservé aux tours enfants créés. Lorsque les deux plafonds s’appliquent, le plus bas l’emporte. |
 | `agentTaskRecovery?` | `object` | — | Mécanisme expérimental, soumis à activation explicite, pour récupérer les tâches v2 chiffrées par le service en amont lorsqu’elles sont envoyées à des fournisseurs routés. Désactivé sauf si `enabled: true` ; voir [Récupération des tâches v2 chiffrées](#récupération-des-tâches-v2-chiffrées). |
 
-Les plafonds configurés s’appliquent aux tours Chat Completions natifs admissibles même sans effort épinglé pour le modèle. Les tours principaux v2 admissibles utilisent `effortCap` ; les tours enfants portant les marqueurs requis utilisent le plus bas des plafonds principal et enfant applicables. Le mode explicite `multiAgentMode: "v1"` et les opérations de compaction échappent aux plafonds. Un plafond ne fait que réduire ou omettre un effort explicite ; la conversion vers la valeur du fournisseur intervient lorsqu’un épinglage est appliqué ou qu’un plafond modifie la valeur. Les valeurs de l’appelant natif conservent leur forme d’origine si aucun épinglage n’est appliqué et qu’aucun plafond ne les réécrit.
-
 Gérez la surface depuis le tableau de bord ou avec `ocx v2 status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>`. Les changements de mode s’appliquent aux nouvelles sessions. `maxConcurrentThreadsPerSession` est un champ de `PUT /api/v2`, et non une clé de `config.json`. Après l’activation de v2, `ocx v2 threads <n>` écrit `max_concurrent_threads_per_session` sous `[features.multi_agent_v2]` dans le fichier `$CODEX_HOME/config.toml` de Codex.
 
 Le **mode Ultra** — accessible depuis l’interrupteur Sous-agents du tableau de bord, le champ `multiAgentModeHintText` de `PUT /api/v2` et `ocx v2 mode-hint` — écrit `features.multi_agent_v2.multi_agent_mode_hint_text` dans le fichier `$CODEX_HOME/config.toml` de Codex. La commande CLI `ocx v2 mode-hint` conserve cette clé même lorsque `multi_agent_v2` est désactivé ; elle n’active ni ne désactive la fonctionnalité. Cette indication remplace la politique multi-agents que codex-rs déduit du niveau d’effort : tous les modèles et tous les niveaux d’effort reçoivent alors le prompt de délégation Proactive. Elle ne modifie **pas** le niveau d’effort de raisonnement.
@@ -121,4 +119,6 @@ Les plafonds s’appliquent uniquement à la fonctionnalité de collaboration v2
 
 Un plafond ne peut que réduire l’effort. Le niveau retenu est le niveau annoncé le plus élevé qui ne dépasse pas le plafond. Si le modèle ne propose aucun contrôle d’effort ou si aucun niveau pris en charge ne convient, opencodex supprime le paramètre d’effort et laisse le fournisseur appliquer sa valeur par défaut. `max` et `ultra` sont acceptés, tandis que le tableau de bord propose les niveaux de `low` à `xhigh`.
 
+Les plafonds configurés s’appliquent aussi aux tours Chat Completions natifs admissibles sans effort épinglé pour le modèle. La conversion vers la valeur du fournisseur intervient lorsqu’un épinglage est appliqué ou qu’un plafond modifie la valeur ; sinon, la valeur de l’appelant natif conserve sa forme d’origine.
+
 Pour une présentation destinée aux débutants des comportements v1, default et v2, consultez [Surfaces de sous-agents](/fr/guides/sub-agent-surface/).
diff --git a/docs-site/src/content/docs/ja/reference/configuration/agents.md b/docs-site/src/content/docs/ja/reference/configuration/agents.md
index eea4ef5530..3ab50e22fc 100644
--- a/docs-site/src/content/docs/ja/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ja/reference/configuration/agents.md
@@ -22,8 +22,6 @@ description: マルチエージェント サーフェス、委任ガイダンス
 | `effortCap?` | `string` | — | v2 のメイン ターンとマークされた子ターンの条件を満たすためのハード シーリング。 `low` ～ `ultra` を受け入れます。 |
 | `subagentEffortCap?` | `string` | — |スポーンされた子のターンのみの追加の上限。両方の上限が適用される場合は、低い方が優先されます。 |
 
-モデルの effort pin がなくても、対象のネイティブ Chat Completions ターンには設定された上限が適用されます。対象の v2 メインターンには `effortCap`、生成された子ターンのマーカーがある場合には適用可能なメインと子の上限のうち低い方を使用します。明示的な `multiAgentMode: "v1"` と compaction の保守処理は上限の対象外です。上限は明示された effort を下げるか省略するだけで、pin を適用した場合、または上限で値を変更した場合にプロバイダーの送信値へ変換します。pin の適用も上限による書き換えもない呼び出し元の値は元の表記を維持します。
-
 ダッシュボードまたは `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>` でサーフェスを管理します。モードの変更は新しいセッションに適用されます。 `maxConcurrentThreadsPerSession` は `PUT /api/v2` フィールドであり、`config.json` キーではありません。 `ocx v2 threads <n>` は、v2 が有効になった後、Codex の `$CODEX_HOME/config.toml` の `[features.multi_agent_v2]` の下に `max_concurrent_threads_per_session` を書き込みます。
 
 管理 API は、`GET`/`PUT /api/v2`、`/api/injection-model`、`/api/effort-caps`、`/api/subagent-models`、および `/api/subagent-model-fallback` を公開します。インジェクションモデルの更新は部分的です。カスタム プロンプトは、その API の `prompt` フィールドです。
@@ -89,4 +87,6 @@ opencodex は、無効、ルーティング不能、異常、冷却期間、ま
 
 キャップは労力を軽減するだけです。これらは、キャップまたはキャップの下で宣伝されている最も高い段にスナップします。モデルにエフォート制御がない場合、またはサポートされているラングフィットがない場合、opencodex はエフォートを削除し、プロバイダーのデフォルトを適用します。 `max` および `ultra` が受け入れられますが、ダッシュボードでは `low` から `xhigh` が提供されます。
 
+モデルの effort pin がなくても、対象のネイティブ Chat Completions ターンには設定された上限が適用されます。pin を適用した場合、または上限で値を変更した場合にプロバイダーの送信値へ変換し、どちらも起きない呼び出し元の値は元の表記を維持します。
+
 v1、デフォルト、および v2 の動作に関する初心者向けの説明については、「[サブエージェントサーフェス](/guides/sub-agent-surface/)」を参照してください。
diff --git a/docs-site/src/content/docs/ko/reference/configuration/agents.md b/docs-site/src/content/docs/ko/reference/configuration/agents.md
index e5c03a8112..58383e63a4 100644
--- a/docs-site/src/content/docs/ko/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ko/reference/configuration/agents.md
@@ -87,6 +87,6 @@ opencodex는 비활성, 라우팅 불가, 비정상, 쿨다운 중, 또는 할
 
 상한은 노력만 낮춥니다. 모델이 광고한 단계 중 상한 이하에서 가장 높은 단계로 맞춥니다. 모델에 노력 제어가 없거나 맞는 지원 단계가 없으면, opencodex는 노력을 제거하고 제공자 기본값을 적용합니다. `max`와 `ultra`는 허용되며, 대시보드는 `low`부터 `xhigh`까지 제공합니다.
 
-모델 effort pin이 없어도 적용 대상 native Chat Completions 요청에는 설정된 상한이 적용됩니다. pin을 적용하거나 상한이 값을 바꾼 경우에 제공자 전송 값으로 매핑합니다. pin 적용도 상한에 의한 변경도 없는 호출자 값은 원래 표기를 유지합니다.
+모델 effort pin이 없어도 적용 대상 native Chat Completions 요청에는 설정된 상한이 적용됩니다. pin을 적용하거나 상한이 값을 바꾼 경우에 제공자 전송 값으로 매핑하며, 둘 다 없으면 호출자 값은 원래 표기를 유지합니다.
 
 v1, default, v2 동작에 대한 초보자용 설명은 [Sub-agent surfaces](/guides/sub-agent-surface/)를 참고하세요.
diff --git a/docs-site/src/content/docs/reference/configuration/agents.md b/docs-site/src/content/docs/reference/configuration/agents.md
index df3b3fe804..d51e3d4672 100644
--- a/docs-site/src/content/docs/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/reference/configuration/agents.md
@@ -39,8 +39,6 @@ still depends on upstream support for your account.
 | `subagentEffortCap?` | `string` | — | Additional ceiling for spawned-child turns only. When both caps apply, the lower wins. |
 | `agentTaskRecovery?` | `object` | — | Experimental opt-in recovery for backend-encrypted v2 tasks sent to routed providers. Disabled unless `enabled: true`; see [Encrypted v2 task recovery](#encrypted-v2-task-recovery). |
 
-Configured effort caps apply to eligible native Chat Completions turns even without a model effort pin. Qualifying v2 main turns use `effortCap`; marked spawned-child turns use the lower applicable main/child ceiling. Explicit `multiAgentMode: "v1"` and compaction maintenance bypass caps. A cap only lowers or omits explicit effort, and provider wire mapping runs when a pin is applied or a cap changes the value. Native caller values retain their original wire spelling when no pin is applied and no cap rewrite occurs.
-
 Manage the surface with the dashboard or
 `ocx v2 status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>`.
 Mode changes apply to new sessions. `maxConcurrentThreadsPerSession` is a `PUT /api/v2` field, not a
@@ -256,6 +254,8 @@ no effort control or no supported rung fits, opencodex removes the effort and le
 apply. `max` and `ultra` are accepted, while the dashboard offers `low` through `xhigh`.
 
 For a beginner-oriented explanation of v1, default, and v2 behavior, see
+Configured caps also apply to eligible native Chat Completions turns that carry no model effort pin. Provider wire mapping runs when a pin is applied or when a cap changes the value; a native caller value keeps its original wire spelling when neither happens.
+
 [Sub-agent surfaces](/guides/sub-agent-surface/).
 
 ## Global model effort pins
diff --git a/docs-site/src/content/docs/ru/reference/configuration/agents.md b/docs-site/src/content/docs/ru/reference/configuration/agents.md
index f67256f8c4..314b5f1a7e 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/agents.md
@@ -136,7 +136,7 @@ Cap'ы умеют только понижать effort. Они опускают
 помещается под cap, opencodex убирает поле effort и позволяет провайдеру применить собственный
 дефолт. `max` и `ultra` принимаются, хотя дашборд предлагает только `low`–`xhigh`.
 
-Настроенные потолки effort применяются к подходящим нативным запросам Chat Completions даже без закреплённого effort модели. Преобразование в значение провайдера выполняется, когда применяется закрепление или потолок меняет значение. Значения нативного вызывающего клиента сохраняют исходное написание, если закрепление не применяется и потолок не переписывает значение.
-
 Если нужен объясняющий вариант для начинающих о поведении v1, default и v2, см.
+Настроенные потолки применяются и к подходящим нативным запросам Chat Completions без закреплённого effort модели. Преобразование в значение провайдера выполняется, когда применяется закрепление или потолок меняет значение; иначе значение нативного вызывающего клиента сохраняет исходное написание.
+
 [Поверхность подагентов](/guides/sub-agent-surface/).
diff --git a/docs-site/src/content/docs/tr/reference/configuration/agents.md b/docs-site/src/content/docs/tr/reference/configuration/agents.md
index c33f2b14d2..291a405417 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/agents.md
@@ -259,7 +259,7 @@ hiçbir basamak uymuyorsa opencodex çabayı kaldırır ve sağlayıcı varsayı
 uygulanmasına izin verir. `max` ve `ultra` kabul edilirken kontrol paneli `low`
 ile `xhigh` arasını sunar.
 
-Yapılandırılmış effort sınırları, model effort sabitlemesi olmasa da uygun yerel Chat Completions turlarına uygulanır. Sağlayıcının iletim değerine eşleme, sabitleme uygulandığında veya sınır değeri değiştirdiğinde yapılır. Sabitleme uygulanmayan ve sınır tarafından yeniden yazılmayan yerel çağıran değerleri özgün yazımını korur.
-
 v1, varsayılan ve v2 davranışının yeni başlayanlara yönelik açıklaması için [Alt
+Yapılandırılmış sınırlar, model effort sabitlemesi olmayan uygun yerel Chat Completions turlarına da uygulanır. Sağlayıcının iletim değerine eşleme yalnızca sabitleme uygulandığında veya sınır değeri değiştirdiğinde yapılır; aksi hâlde yerel çağıran değeri özgün yazımını korur.
+
 ajan yüzeyleri](/tr/guides/sub-agent-surface/) sayfasına bakın.
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
index b55badecab..fcc84ab87f 100644
--- a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
@@ -86,6 +86,6 @@ opencodex 会跳过已禁用、不可路由、不健康、处于冷却中，或
 
 上限只会降低 effort。它们会向下贴合到不高于上限、且模型公开的最高档位。如果模型没有 effort 控制，或者没有任何受支持的档位可用，opencodex 会移除 effort，让提供方默认值生效。`max` 和 `ultra` 都可接受，而仪表板提供 `low` 到 `xhigh`。
 
-即使没有设置模型 effort pin，符合条件的原生 Chat Completions 轮次也会应用配置的上限。应用 pin 或上限改变值时，才会映射为提供方的传输值。未应用 pin 且未被上限改写的原生调用方值保留原始写法。
+即使没有设置模型 effort pin，符合条件的原生 Chat Completions 轮次也会应用配置的上限。仅在应用 pin 或上限改变值时才映射为提供方的传输值；两者都未发生时，原生调用方值保留原始写法。
 
 关于 v1、default 和 v2 行为的面向初学者说明，请参阅 [Sub-agent surfaces](/guides/sub-agent-surface/)。
diff --git a/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md b/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
index a960781728..6f3ad3c84e 100644
--- a/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
@@ -21,8 +21,6 @@ Agent 設定控制要廣告哪個 Codex 協作介面，以及 opencodex 如何
 | `effortCap?` | `string` | — | 合格 v2 主回合與標記的生成子回合的硬性上限。接受 `low` 到 `ultra`。 |
 | `subagentEffortCap?` | `string` | — | 僅針對生成子回合的額外上限。當兩個上限都適用時，取較低者。 |
 
-即使沒有設定模型 effort pin，符合條件的原生 Chat Completions 回合也會套用設定的上限。符合條件的 v2 主回合使用 `effortCap`；帶有生成子回合標記的請求使用適用的主回合與子回合上限中的較低值。明確的 `multiAgentMode: "v1"` 與 compaction 維護請求不套用上限。上限只會降低或省略明確指定的 effort；套用 pin 或上限改變值時，才會對應為供應商的傳輸值。未套用 pin 且未被上限改寫的原生呼叫端值保留原始寫法。
-
 使用儀表板或 `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>` 管理介面。模式變更套用於新 session。`maxConcurrentThreadsPerSession` 是 `PUT /api/v2` 欄位，不是 `config.json` key；`ocx v2 threads <n>` 在啟用 v2 後，將 `max_concurrent_threads_per_session` 寫入 Codex 的 `$CODEX_HOME/config.toml` 中 `[features.multi_agent_v2]` 之下。
 
 管理 API 暴露 `GET`/`PUT /api/v2`、`/api/injection-model`、`/api/effort-caps`、`/api/subagent-models` 與 `/api/subagent-model-fallback`。注入模型更新為部分更新；自訂 prompt 是該 API 的 `prompt` 欄位。
@@ -73,4 +71,6 @@ opencodex 會跳過已停用、不可路由、不健康、冷卻中或達到配
 
 上限僅會降低 effort。它們吸附到上限或以下的最高宣告級別。若模型沒有 effort 控制或沒有支援的級別符合，opencodex 會移除 effort 並讓供應商預設值套用。`max` 與 `ultra` 被接受，而儀表板提供 `low` 到 `xhigh`。
 
+即使沒有設定模型 effort pin，符合條件的原生 Chat Completions 回合也會套用設定的上限。套用 pin 或上限改變值時才會對應為供應商的傳輸值；兩者皆未發生時，原生呼叫端值保留原始寫法。
+
 關於 v1、default 與 v2 行為的入門導向說明，請見[子代理介面](/zh-tw/guides/sub-agent-surface/)。

From dc57cfb3e4c7eac3be4af991db44f0a908e1187b Mon Sep 17 00:00:00 2001
From: luvs01 <27862058+luvs01@users.noreply.github.com>
Date: Fri, 11 Sep 2026 21:57:12 +0900
Subject: [PATCH 4/6] docs(structure): move the native Chat cap note to its new
 SOT home

dev restructured structure/ and deleted 03_catalog-and-subagents.md, so
the effort-cap SOT paragraph now lives in structure/catalog.md next to the
existing pin/cap ordering rules.
---
 structure/catalog.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/structure/catalog.md b/structure/catalog.md
index 0ba4acca3e..eda6f26e80 100644
--- a/structure/catalog.md
+++ b/structure/catalog.md
@@ -251,8 +251,10 @@ Provider model pins precede provider-wide pins, then global selector/destination
 A pin can raise the effective caller effort; the later cap can still lower or omit it.
 `none` means explicit-effort omission (provider default), not guaranteed reasoning disablement.
 Compaction maintenance is exempt. Pins are user overlays and do not alter registry seeds,
-model discovery or advertised ladders. Native Chat normalizes newly pinned values through
-provider wire mapping; unpinned native requests retain their existing pass-through contract.
+model discovery or advertised ladders. Native Chat applies qualifying caps even without a
+pin, and normalizes pinned values and values rewritten by a cap through provider wire
+mapping. Without a pin or a cap rewrite, native caller values retain their original wire
+spelling; the V1 and compaction cap exemptions are preserved.
 
 > Decision record: [ADR-0023](decisions/ADR-0023-ultra-reasoning-level.md)
 

From 03932ffb4fe2b8696f43d5cc9d6efbbeebe32af2 Mon Sep 17 00:00:00 2001
From: luvs01 <27862058+luvs01@users.noreply.github.com>
Date: Fri, 11 Sep 2026 22:57:00 +0900
Subject: [PATCH 5/6] docs(agents): stop splitting the sub-agent
 cross-reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The cap paragraph was inserted before the line holding the link, which
lands inside the sentence when that sentence wraps: English and Russian
broke after "see"/"см.", and Turkish split the [Alt ajan yüzeyleri] link
span itself. Place the paragraph before the whole sentence, matching the
five locales whose reference fits on one line.
---
 docs-site/src/content/docs/reference/configuration/agents.md    | 2 +-
 docs-site/src/content/docs/ru/reference/configuration/agents.md | 2 +-
 docs-site/src/content/docs/tr/reference/configuration/agents.md | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs-site/src/content/docs/reference/configuration/agents.md b/docs-site/src/content/docs/reference/configuration/agents.md
index d51e3d4672..a113813b40 100644
--- a/docs-site/src/content/docs/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/reference/configuration/agents.md
@@ -253,9 +253,9 @@ Caps only lower effort. They snap to the highest advertised rung at or below the
 no effort control or no supported rung fits, opencodex removes the effort and lets the provider default
 apply. `max` and `ultra` are accepted, while the dashboard offers `low` through `xhigh`.
 
-For a beginner-oriented explanation of v1, default, and v2 behavior, see
 Configured caps also apply to eligible native Chat Completions turns that carry no model effort pin. Provider wire mapping runs when a pin is applied or when a cap changes the value; a native caller value keeps its original wire spelling when neither happens.
 
+For a beginner-oriented explanation of v1, default, and v2 behavior, see
 [Sub-agent surfaces](/guides/sub-agent-surface/).
 
 ## Global model effort pins
diff --git a/docs-site/src/content/docs/ru/reference/configuration/agents.md b/docs-site/src/content/docs/ru/reference/configuration/agents.md
index 314b5f1a7e..62a5723508 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/agents.md
@@ -136,7 +136,7 @@ Cap'ы умеют только понижать effort. Они опускают
 помещается под cap, opencodex убирает поле effort и позволяет провайдеру применить собственный
 дефолт. `max` и `ultra` принимаются, хотя дашборд предлагает только `low`–`xhigh`.
 
-Если нужен объясняющий вариант для начинающих о поведении v1, default и v2, см.
 Настроенные потолки применяются и к подходящим нативным запросам Chat Completions без закреплённого effort модели. Преобразование в значение провайдера выполняется, когда применяется закрепление или потолок меняет значение; иначе значение нативного вызывающего клиента сохраняет исходное написание.
 
+Если нужен объясняющий вариант для начинающих о поведении v1, default и v2, см.
 [Поверхность подагентов](/guides/sub-agent-surface/).
diff --git a/docs-site/src/content/docs/tr/reference/configuration/agents.md b/docs-site/src/content/docs/tr/reference/configuration/agents.md
index 291a405417..6320e18f08 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/agents.md
@@ -259,7 +259,7 @@ hiçbir basamak uymuyorsa opencodex çabayı kaldırır ve sağlayıcı varsayı
 uygulanmasına izin verir. `max` ve `ultra` kabul edilirken kontrol paneli `low`
 ile `xhigh` arasını sunar.
 
-v1, varsayılan ve v2 davranışının yeni başlayanlara yönelik açıklaması için [Alt
 Yapılandırılmış sınırlar, model effort sabitlemesi olmayan uygun yerel Chat Completions turlarına da uygulanır. Sağlayıcının iletim değerine eşleme yalnızca sabitleme uygulandığında veya sınır değeri değiştirdiğinde yapılır; aksi hâlde yerel çağıran değeri özgün yazımını korur.
 
+v1, varsayılan ve v2 davranışının yeni başlayanlara yönelik açıklaması için [Alt
 ajan yüzeyleri](/tr/guides/sub-agent-surface/) sayfasına bakın.

From 9309e4bcc92c43fd12d6fc62528ddf323160d5fb Mon Sep 17 00:00:00 2001
From: luvs01 <27862058+luvs01@users.noreply.github.com>
Date: Sat, 12 Sep 2026 14:45:41 +0900
Subject: [PATCH 6/6] docs(structure): synchronize native Chat cap owners

---
 structure/adapters/registry.md           | 4 ++++
 structure/clients/claude-desktop.md      | 4 ++++
 structure/data-planes/images.md          | 3 +++
 structure/data-planes/inbound-compat.md  | 6 ++++++
 structure/gui-and-management-api.md      | 4 ++++
 structure/ops/service-and-sidecars.md    | 4 ++++
 structure/providers/xai-grok.md          | 4 ++++
 structure/runtime.md                     | 4 ++++
 structure/subagents.md                   | 4 ++++
 structure/transports/inventory.md        | 2 +-
 structure/transports/responses.md        | 4 ++++
 structure/transports/streaming-health.md | 4 ++++
 12 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/structure/adapters/registry.md b/structure/adapters/registry.md
index 9e869c4f7a..7da15cd16a 100644
--- a/structure/adapters/registry.md
+++ b/structure/adapters/registry.md
@@ -4,6 +4,10 @@
 
 Runtime adapter construction has one authority: `src/adapters/registry.ts`.
 
+Native Chat admission in `src/server/chat-native.ts` applies the shared
+[effort-cap and wire-mapping policy](../catalog.md#ultra-reasoning-level) before the selected
+adapter builds its request, including when no model effort pin resolves.
+
 `src/server/adapter-resolve.ts` may resolve a provider/model onto an adapter id, but it does not maintain a second adapter factory inventory. The selected persisted/configured adapter id remains an untrusted string until the registry lookup succeeds. Unknown ids fail with the existing `Unknown adapter: <id>` error instead of widening configuration types around a closed compile-time union.
 
 ## Semantic inheritance is not constructor inheritance
diff --git a/structure/clients/claude-desktop.md b/structure/clients/claude-desktop.md
index 2914823958..9caccaeb4c 100644
--- a/structure/clients/claude-desktop.md
+++ b/structure/clients/claude-desktop.md
@@ -1,5 +1,9 @@
 # Claude Desktop Integration
 
+Client profile discovery and persistence do not determine per-turn effort-cap admission.
+For native Chat requests, `src/server/chat-native.ts` owns the
+[shared cap contract](../catalog.md#ultra-reasoning-level), including eligible unpinned turns.
+
 ## Connected Claude Desktop profiles
 
 Connected `ocx claude desktop apply` reads the hub's Desktop snapshot and writes the hub origin
diff --git a/structure/data-planes/images.md b/structure/data-planes/images.md
index 25646c7de4..affe7696a8 100644
--- a/structure/data-planes/images.md
+++ b/structure/data-planes/images.md
@@ -6,6 +6,9 @@ Codex's local `image_gen.imagegen` tool makes a second Images request after the
 `POST /v1/images/generations` for generation or `POST /v1/images/edits` for reference-image edits.
 These are standalone Images API routes, not the hosted Responses `image_generation` tool.
 
+The [native Chat effort-cap contract](../catalog.md#ultra-reasoning-level) belongs to
+`src/server/chat-native.ts`; the standalone Images relay does not apply that Chat request policy.
+
 `src/server/images.ts` uses the existing ChatGPT/OpenAI fallback unless `images.provider` explicitly
 selects a custom API-key `openai-responses` provider. Explicit selection fails closed when the
 provider is missing, disabled, registry-managed, incompatible, or lacks a usable key; it never
diff --git a/structure/data-planes/inbound-compat.md b/structure/data-planes/inbound-compat.md
index 2d17c11875..b51e9e9e7c 100644
--- a/structure/data-planes/inbound-compat.md
+++ b/structure/data-planes/inbound-compat.md
@@ -22,6 +22,12 @@ parallel tools (or pinned false by the existing provider opt-out contract).
 Combo/policy routes and requests that need Responses-only hosted tools, continuation, background,
 or storage semantics retain the existing Chat -> Responses -> Chat bridge.
 
+`src/server/chat-native.ts` applies the shared
+[effort-cap contract](../catalog.md#ultra-reasoning-level) independently of model pins.
+Provider wire mapping runs for an applied pin or a cap rewrite; otherwise the caller's
+effort spelling is preserved. Same-destination retries reuse the normalized value and
+annotation; a destination change starts again from the original caller effort.
+
 The direct SSE relay accepts CRLF and arbitrary transport chunk boundaries while retaining at most
 one bounded event. EOF with an unterminated event and an event above the translator limit are typed
 upstream failures, never successful partial completions. Provider-controlled structured error
diff --git a/structure/gui-and-management-api.md b/structure/gui-and-management-api.md
index 73090d646e..5d202f1ba0 100644
--- a/structure/gui-and-management-api.md
+++ b/structure/gui-and-management-api.md
@@ -1,5 +1,9 @@
 # GUI And Management API
 
+Configured effort ceilings are enforced per request by the
+[shared effort policy](catalog.md#ultra-reasoning-level). The native Chat implementation in
+`src/server/chat-native.ts` applies eligible caps without requiring a model-pin setting.
+
 ## Dashboard serving
 
 The bundled React dashboard is built into `gui/dist` and served by the same Bun proxy. `ocx gui`
diff --git a/structure/ops/service-and-sidecars.md b/structure/ops/service-and-sidecars.md
index 39dc9a82da..6f6fb67cda 100644
--- a/structure/ops/service-and-sidecars.md
+++ b/structure/ops/service-and-sidecars.md
@@ -1,5 +1,9 @@
 # Background Service And Sidecars
 
+Effort ceilings are request policy rather than service or sidecar startup policy.
+`src/server/chat-native.ts` applies the [shared cap contract](../catalog.md#ultra-reasoning-level)
+to eligible native Chat turns with or without a model pin before dispatch.
+
 ## Background service command selection
 
 A bare `ocx service` is an idempotent install-or-repair command. Argument validation happens before
diff --git a/structure/providers/xai-grok.md b/structure/providers/xai-grok.md
index 5b149ac6a2..1d322824f9 100644
--- a/structure/providers/xai-grok.md
+++ b/structure/providers/xai-grok.md
@@ -1,5 +1,9 @@
 # xAI Grok Provider
 
+For routes admitted to `src/server/chat-native.ts`, request effort follows the shared
+[cap and provider-mapping contract](../catalog.md#ultra-reasoning-level), including eligible
+requests without a pin. Provider-specific Grok transport behavior is described below.
+
 ## xAI Grok hardening (official Grok Build contract parity)
 
 Grounded in the open-sourced official client (xai-org/grok-build); unit + evidence:
diff --git a/structure/runtime.md b/structure/runtime.md
index 2f5ce70e21..0aa10d09ad 100644
--- a/structure/runtime.md
+++ b/structure/runtime.md
@@ -1,5 +1,9 @@
 # Runtime
 
+Native Chat request preparation in `src/server/chat-native.ts` applies the shared
+[effort-cap contract](catalog.md#ultra-reasoning-level) before provider dispatch, including
+eligible requests without an operator effort pin.
+
 ## Entrypoints
 
 | Path | Responsibility |
diff --git a/structure/subagents.md b/structure/subagents.md
index f190aab084..27d8d2f396 100644
--- a/structure/subagents.md
+++ b/structure/subagents.md
@@ -133,6 +133,10 @@ availability on a bounded interval (default 60 s, `src/codex/subagent-model-fall
 the requested model id only; effort remains owned by the caps described under
 [Ultra reasoning level](catalog.md#ultra-reasoning-level).
 
+Native Chat uses that same cap policy in `src/server/chat-native.ts` for qualifying v2 main
+turns and exactly marked spawned children, even without a model effort pin. Leaf children
+do not need collaboration tools to qualify; forced v1 and compaction remain exempt.
+
 `injectionModel` and `injectionEffort` are shared selections with two independent consumers.
 `multiAgentGuidanceEnabled` controls only OpenCodex-authored delegation guidance.
 `syncCodexSubagentDefaults` is a separate, default-off opt-in that applies the selected values to
diff --git a/structure/transports/inventory.md b/structure/transports/inventory.md
index b2fc3b3fae..94cc33062b 100644
--- a/structure/transports/inventory.md
+++ b/structure/transports/inventory.md
@@ -14,7 +14,7 @@ surface is listed here so a maintainer can find the owner without grepping:
 | Adapter execution support | `src/adapters/run-turn-queue.ts`, `src/adapters/tool-catalog-nudge.ts`, `src/adapters/identity.ts`, `src/adapters/image.ts`, `src/adapters/upstream-http-error.ts` | Shared machinery: turn ordering, tool-catalog nudging, client fingerprinting, image conversion, upstream error normalization. |
 | Cursor (beyond the sections above) | `src/adapters/cursor/live-transport.ts`, `src/adapters/cursor/http1-bidi.ts`, `src/adapters/cursor/live-models.ts`, `src/adapters/cursor/transport-retry.ts`, `src/adapters/cursor/mcp-manager.ts`, `src/adapters/cursor/thread-continuity.ts`, `src/adapters/cursor/checkpoint-store.ts` | Thread continuity is the point: a retry must not start a new Cursor thread, and a validated checkpoint must not rebuild the full root history. HTTP/2 remains the default; an explicit `http1.1`/`h1` pin maps the bidi run onto Cursor's `RunSSE` receive stream plus sequenced `BidiAppend` sends, and applies to live discovery too. |
 | Claude Messages | `src/server/claude-messages.ts` | Routed translation, a native Anthropic passthrough branch, and `count_tokens`. |
-| Chat Completions inbound | `src/server/chat-completions.ts`, `src/chat/` | Inbound translation onto the same routing pipeline. The content mapper preserves image URLs and supported detail, including screenshot-bearing tool results; target adapters own image placement on their wire. Image-free tool results stay strings. |
+| Chat Completions inbound | `src/server/chat-completions.ts`, `src/server/chat-native.ts`, `src/chat/` | Eligible native requests retain their Chat wire source and apply the shared [effort-cap policy](../catalog.md#ultra-reasoning-level), including without a pin. Other requests translate onto the same routing pipeline. The content mapper preserves image URLs and supported detail, including screenshot-bearing tool results; target adapters own image placement on their wire. Image-free tool results stay strings. |
 | Hosted search relay | `src/server/search.ts` | Direct relay; distinct from the web-search sidecar loop below. |
 | Image/video generation loop | `src/images/loop.ts`, `src/images/plan.ts`, `src/images/fulfill.ts`, `src/images/xai-client.ts`, `src/images/xai-video-client.ts`, `src/images/artifacts.ts` | A provider-returned image URL is downloaded into a local artifact once, then served locally; warnings stay URL-free because provider CDN URLs may embed credentials. |
 | GitHub Copilot | `src/providers/xai-transport.ts` (`resolveProviderTransport`), `src/providers/github-copilot-transport.ts` | `resolveProviderTransport` selects the Copilot transport when the routed provider name is `github-copilot`; the Copilot module then resolves its headers and base URL, and the registry seeds the provider row and model fallback. |
diff --git a/structure/transports/responses.md b/structure/transports/responses.md
index 2321d78dd6..8f18c8c9a6 100644
--- a/structure/transports/responses.md
+++ b/structure/transports/responses.md
@@ -6,6 +6,10 @@
 provider, lets the selected adapter speak the upstream protocol, then bridges adapter events back to
 Responses-compatible streaming output.
 
+The native Chat lane applies the same [effort-cap contract](../catalog.md#ultra-reasoning-level)
+in `src/server/chat-native.ts` before dispatch, so eligible unpinned Chat requests do not
+need a Responses projection to receive their configured ceiling.
+
 ### Credential-bearing HTTP redirects
 
 Credential/body-bearing HTTP sends use `redirect: "manual"` at the final executor boundary,
diff --git a/structure/transports/streaming-health.md b/structure/transports/streaming-health.md
index 68093843ea..43d237f70e 100644
--- a/structure/transports/streaming-health.md
+++ b/structure/transports/streaming-health.md
@@ -1,5 +1,9 @@
 # Streaming Health And WebSocket
 
+Native Chat effort normalization occurs before the upstream send in `src/server/chat-native.ts`.
+Its [cap and wire-mapping policy](../catalog.md#ultra-reasoning-level) also covers eligible
+unpinned requests; the SSE relay and its cancellation/deadline ownership follow the resulting send.
+
 ## Heartbeat and stall deadline
 
 The HTTP/SSE bridge emits an SSE comment-line keep-alive (`: opencodex heartbeat`) during upstream