feat(effort-cap): hard reasoning-effort ceiling for main and sub-agent turns

Add effortCap and subagentEffortCap config options that enforce a per-request
hard ceiling on reasoning effort at the proxy layer. This closes the gap where
codex-rs inherits the parent's ultra-tier default on bare spawns regardless of
injection-side advisory effort.

- src/server/effort-policy.ts: sub-agent request detection from codex-rs
  spawn markers (x-openai-subagent, x-codex-turn-metadata), cap resolution
  against the model's supported effort ladder, dual-shape rewrite (parsed
  options + raw body) that runs before the native effort clamp
- src/server/responses.ts: effort cap enforcement hook before mock-max clamp
- src/server/management-api.ts: GET/PUT /api/effort-caps endpoints
- src/types.ts: effortCap, subagentEffortCap on OcxConfig
- src/reasoning-effort.ts: codexEffortRank helper
- src/adapters/openai-responses.ts: forward x-openai-subagent header
- gui: dashboard effort cap selectors with i18n (en/de/ko/zh)
- docs: configuration reference (en/ko/zh)
- tests: 32 tests covering classification, resolution, rewrite, and API

Author: lidge-jun

docs-site/src/content/docs/ko/reference/configuration.md

@@ -20,6 +20,8 @@ opencodex는 `~/.opencodex/config.json`에서 설정을 읽습니다. `ocx init`
 | `subagentModels?` | `string[]` | `gpt-5.5`, GPT-5.6 3종, `gpt-5.4-mini` | Codex 서브에이전트 선택기 앞쪽에 표시할 네이티브 slug 또는 `provider/model` id. 최대 5개이며, 명시적인 빈 배열도 그대로 보존합니다. v2 위임 안내에는 사용 가능한 모델 로스터로도 주입되며, 각 항목이 카탈로그에 광고하는 effort 사다리가 함께 표기됩니다. |
 | `injectionModel?` | `string` | — | 주입되는 multi-agent 안내(v2 표면)에 들어갈 네이티브/라우팅 모델. 위임 안내에서 이 모델을 `fork_turns: "none"`과 함께 `spawn_agent`에 넘기게 합니다. |
 | `injectionEffort?` | `string` | — | 선호하는 `spawn_agent` reasoning effort(`low`부터 `ultra`). `injectionModel`과 함께 쓸 때만 의미가 있습니다. |
+| `effortCap?` | `string` | — | 프록시를 거치는 모든 턴(메인 에이전트와 서브에이전트)의 reasoning effort에 요청별로 적용하는 강제 상한입니다. `low`부터 `ultra`까지 허용하며 값을 높이지 않고 낮추기만 합니다. 상한 이하에서 모델이 지원하는 가장 높은 단계로 내립니다. 모델이 effort 제어를 노출하지 않거나 상한 이하에 지원 단계가 없으면 effort 필드를 제거하고 프로바이더 기본값을 적용합니다. `max`와 `ultra`도 허용하지만 더 낮은 rank 상한을 만들지는 않습니다(클라이언트가 `ultra`를 `max`로 변환하므로 요청은 `low`부터 `max`로 들어옵니다). 단, 알려진 모델 effort 사다리에 따라 단계가 내려가거나 필드가 제거될 수 있습니다. 대시보드 선택기는 `low`부터 `xhigh`까지 제공합니다. `GET /api/effort-caps`와 `PUT /api/effort-caps`로 관리합니다. |
+| `subagentEffortCap?` | `string` | — | codex-rs가 생성한 자식 요청에 붙이는 표식, 즉 `x-openai-subagent` 헤더나 `x-codex-turn-metadata`의 `subagent_kind`로 식별된 서브에이전트 턴에만 같은 강제 상한을 적용합니다. `low`부터 `ultra`까지 허용하며 두 상한이 모두 설정되면 더 낮은 값이 적용되고, 값을 높이지 않고 낮추기만 합니다. 상한 이하에서 모델이 지원하는 가장 높은 단계로 내립니다. 모델이 effort 제어를 노출하지 않거나 상한 이하에 지원 단계가 없으면 effort 필드를 제거하고 프로바이더 기본값을 적용합니다. `max`와 `ultra`도 허용하지만 더 낮은 rank 상한을 만들지는 않습니다(클라이언트가 `ultra`를 `max`로 변환하므로 요청은 `low`부터 `max`로 들어옵니다). 단, 알려진 모델 effort 사다리에 따라 단계가 내려가거나 필드가 제거될 수 있습니다. 대시보드 선택기는 `low`부터 `xhigh`까지 제공합니다. `GET /api/effort-caps`와 `PUT /api/effort-caps`로 관리합니다. |
 | `injectionPrompt?` | `string` | — | 주입되는 v2 안내 본문을 통째로 교체하는 커스텀 텍스트. `{{model}}`, `{{effort}}`, `{{roster}}` 플레이스홀더가 치환되며 발화 조건은 그대로입니다. `PUT /api/injection-model`의 `prompt` 키로도 설정할 수 있습니다. |
 | `disabledModels?` | `string[]` | — | Codex에서 숨길 모델. 라우팅된 `provider/model` id는 카탈로그와 `/v1/models`에서 제외합니다. `gpt-5.4` 같은 일반 네이티브 GPT slug는 카탈로그 항목을 `visibility: "hide"`로 바꾸고 일반 `/v1/models` 목록에서 뺍니다. 대시보드 Models 페이지에서 모델별로 전환할 수 있습니다. |
 | `multiAgentMode?` | `"v1" \| "default" \| "v2"` | `"default"` | 3단계 multi-agent surface override. `"v1"`은 업스트림 pin보다 우선해 모든 모델을 v1로, `"default"`는 업스트림 model pin(sol/terra=v2, luna=v1)을 따르고, `"v2"`는 모두 v2로 강제합니다. 대시보드 Models 페이지나 `ocx v2 mode`에서 설정합니다. |

docs-site/src/content/docs/reference/configuration.md

@@ -21,6 +21,8 @@ console warning, and starts with defaults. Missing files also fall back to a def
 | `subagentModels?` | `string[]` | `gpt-5.5`, GPT-5.6 trio, `gpt-5.4-mini` | Up to 5 native slugs or `provider/model` ids featured first in Codex's subagent picker. Also injected into v2 delegation guidance as the available-model roster, annotated with the effort ladder each entry advertises in the catalog. An explicit empty list is preserved. |
 | `injectionModel?` | `string` | — | Preferred native or routed model named in the injected multi-agent guidance (v2 surface); delegation is told to pass this exact model to `spawn_agent` with `fork_turns: "none"`. |
 | `injectionEffort?` | `string` | — | Preferred `spawn_agent` reasoning effort (`low` through `ultra`). Only meaningful with `injectionModel`. |
+| `effortCap?` | `string` | — | Hard per-request ceiling for the reasoning effort of every proxied turn (main agent and sub-agents). Accepts `low` through `ultra`; caps only lower, never raise. Snaps down to the highest supported rung at or below the cap. If the model exposes no effort control, or no supported rung fits under the cap, the effort field is removed and the provider default applies. `max` and `ultra` are accepted but do not impose a lower rank ceiling (requests arrive as `low` through `max` after the client's `ultra` → `max` conversion), though known model ladders may still cause snap-down or strip. The Dashboard picker offers `low` through `xhigh`. Managed via `GET /api/effort-caps` and `PUT /api/effort-caps`. |
+| `subagentEffortCap?` | `string` | — | The same hard ceiling, applied only to sub-agent turns identified by codex-rs spawned-child markers: the `x-openai-subagent` header or `subagent_kind` in `x-codex-turn-metadata`. Accepts `low` through `ultra`; when both caps are set, the lower one wins, and caps only lower, never raise. Snaps down to the highest supported rung at or below the cap. If the model exposes no effort control, or no supported rung fits under the cap, the effort field is removed and the provider default applies. `max` and `ultra` are accepted but do not impose a lower rank ceiling (requests arrive as `low` through `max` after the client's `ultra` → `max` conversion), though known model ladders may still cause snap-down or strip. The Dashboard picker offers `low` through `xhigh`. Managed via `GET /api/effort-caps` and `PUT /api/effort-caps`. |
 | `injectionPrompt?` | `string` | — | Custom override for the injected v2 guidance body. Replaces the built-in text; `{{model}}`, `{{effort}}`, and `{{roster}}` placeholders are substituted. Firing gates are unchanged. Settable via `PUT /api/injection-model` (`prompt` key). |
 | `disabledModels?` | `string[]` | — | Models hidden from Codex. Routed `provider/model` ids are excluded from the catalog and `/v1/models`; bare native GPT slugs (e.g. `gpt-5.4`) flip their catalog entry to `visibility: "hide"` and drop from the bare `/v1/models` list. Toggleable per model from the dashboard Models page. |
 | `multiAgentMode?` | `"v1" \| "default" \| "v2"` | `"default"` | 3-state multi-agent surface override. `"v1"` forces all models to the v1 surface (overrides upstream pins); `"default"` respects upstream model pins (sol/terra=v2, luna=v1); `"v2"` forces all models to v2. Settable from the dashboard Models page or `ocx v2 mode`. |

docs-site/src/content/docs/zh-cn/reference/configuration.md

@@ -20,6 +20,8 @@ opencodex 使用 `~/.opencodex/config.json` 配置。`ocx init` 和仪表盘会
 | `subagentModels?` | `string[]` | `gpt-5.5`、三款 GPT-5.6、`gpt-5.4-mini` | 最多 5 个原生 slug 或 `provider/model` id，优先显示在 Codex subagent picker 中。显式空数组会被保留。 也会作为可用模型清单注入 v2 委派指南，并标注各模型在目录中公布的 effort 阶梯。 |
 | `injectionModel?` | `string` | — | 注入 multi-agent 指南（v2 界面）的首选原生或路由模型；委派指南会要求把该模型连同 `fork_turns: "none"` 一起传给 `spawn_agent`。 |
 | `injectionEffort?` | `string` | — | 首选 `spawn_agent` reasoning effort（`low` 到 `ultra`）。只有与 `injectionModel` 一起使用才有意义。 |
+| `effortCap?` | `string` | — | 为经过代理的每个轮次（主代理和子代理）的 reasoning effort 设置逐请求硬上限。接受 `low` 到 `ultra`；只会降低 effort，绝不会提高。会降至不高于上限的最高受支持档位。若模型不提供 effort 控制，或上限之下没有可用档位，则移除 effort 字段并采用 provider 默认值。`max` 和 `ultra` 均可使用，但不会形成更低的等级上限（客户端会将 `ultra` 转换为 `max`，因此请求以 `low` 到 `max` 的范围到达）；不过，已知的模型 effort 阶梯仍可能触发降档或移除字段。仪表盘选择器提供 `low` 到 `xhigh`。通过 `GET /api/effort-caps` 和 `PUT /api/effort-caps` 管理。 |
+| `subagentEffortCap?` | `string` | — | 同样的硬上限，但只用于带有 codex-rs 派生子级标记的子代理轮次：`x-openai-subagent` 请求头，或 `x-codex-turn-metadata` 中的 `subagent_kind`。接受 `low` 到 `ultra`；两个上限同时设置时取较低者，且只会降低 effort，绝不会提高。会降至不高于上限的最高受支持档位。若模型不提供 effort 控制，或上限之下没有可用档位，则移除 effort 字段并采用 provider 默认值。`max` 和 `ultra` 均可使用，但不会形成更低的等级上限（客户端会将 `ultra` 转换为 `max`，因此请求以 `low` 到 `max` 的范围到达）；不过，已知的模型 effort 阶梯仍可能触发降档或移除字段。仪表盘选择器提供 `low` 到 `xhigh`。通过 `GET /api/effort-caps` 和 `PUT /api/effort-caps` 管理。 |
 | `injectionPrompt?` | `string` | — | 整体替换注入的 v2 指南正文的自定义文本。`{{model}}`、`{{effort}}`、`{{roster}}` 占位符会被替换，触发条件保持不变。也可通过 `PUT /api/injection-model` 的 `prompt` 键设置。 |
 | `disabledModels?` | `string[]` | — | 从 Codex 隐藏的模型。路由 `provider/model` id 会从目录和 `/v1/models` 排除；bare 原生 GPT slug（如 `gpt-5.4`）的目录条目会改成 `visibility: "hide"`，并从 bare `/v1/models` 列表移除。可在仪表盘 Models 页面按模型切换。 |
 | `multiAgentMode?` | `"v1" \| "default" \| "v2"` | `"default"` | 三态 multi-agent surface override。`"v1"` 覆盖 upstream pin，强制全部模型使用 v1；`"default"` 遵循 upstream model pin（sol/terra=v2，luna=v1）；`"v2"` 强制全部模型使用 v2。可在仪表盘 Models 页面或 `ocx v2 mode` 中设置。 |

gui/src/i18n/de.ts

@@ -54,6 +54,9 @@ export const de = {
   "dash.injectionNone": "Keine",
   "dash.injectionEffortLabel": "Reasoning-Aufwand",
   "dash.injectionEffortNone": "Modell-Standard",
+  "dash.effortCapLabel": "Ultra Effort-Limit",
+  "dash.subagentEffortCapLabel": "Effort-Limit (Sub-Agents)",
+  "dash.effortCapNone": "Kein Limit",
   "dash.maintenance": "Wartung",
   "dash.maintenanceHint": "Aktualisiere Codex’ Modellkatalog oder installiere eine neuere opencodex-Version.",
   "dash.syncModels": "Modelle synchronisieren",

gui/src/i18n/en.ts

@@ -58,6 +58,9 @@ export const en = {
   "dash.injectionNone": "None",
   "dash.injectionEffortLabel": "Reasoning effort",
   "dash.injectionEffortNone": "Model default",
+  "dash.effortCapLabel": "Ultra reasoning effort limit",
+  "dash.subagentEffortCapLabel": "Effort cap (sub-agents)",
+  "dash.effortCapNone": "No cap",
   "dash.maintenance": "Maintenance",
   "dash.maintenanceHint": "Refresh Codex's model catalog or install a newer opencodex release.",
   "dash.syncModels": "Sync models",

gui/src/i18n/ko.ts

@@ -58,6 +58,9 @@ export const ko: Record<TKey, string> = {
   "dash.injectionNone": "없음",
   "dash.injectionEffortLabel": "추론 강도",
   "dash.injectionEffortNone": "모델 기본값",
+  "dash.effortCapLabel": "ultra 추론 강도 제한",
+  "dash.subagentEffortCapLabel": "추론 강도 상한 (서브에이전트)",
+  "dash.effortCapNone": "상한 없음",
     "dash.maintenance": "유지보수",
   "dash.maintenanceHint": "Codex 모델 카탈로그를 새로고침하거나 최신 opencodex 릴리스를 설치합니다.",
   "dash.syncModels": "모델 동기화",

gui/src/i18n/zh.ts

@@ -58,6 +58,9 @@ export const zh: Record<TKey, string> = {
   "dash.injectionNone": "无",
   "dash.injectionEffortLabel": "推理强度",
   "dash.injectionEffortNone": "模型默认",
+  "dash.effortCapLabel": "Ultra 推理强度限制",
+  "dash.subagentEffortCapLabel": "推理强度上限（子代理）",
+  "dash.effortCapNone": "无上限",
     "dash.maintenance": "维护",
   "dash.maintenanceHint": "刷新 Codex 模型目录，或安装新的 opencodex 版本。",
   "dash.syncModels": "同步模型",

gui/src/pages/Dashboard.tsx

@@ -66,6 +66,7 @@ import { modelLabel } from "../model-display";
 const SEARCH_SIDECAR_MODELS = ["gpt-5.6-luna", "gpt-5.4-mini", "gpt-5.4", "gpt-5.5", "gpt-5.3-codex-spark", "gpt-5.6-sol", "gpt-5.6-terra"];
 const VISION_SIDECAR_MODELS = ["gpt-5.6-luna", "gpt-5.4-mini", "gpt-5.4", "gpt-5.5", "gpt-5.6-sol", "gpt-5.6-terra"];
 const REASONING_LEVELS = ["low", "medium", "high"];
+const EFFORT_CAP_LEVELS = ["low", "medium", "high", "xhigh"];
 const UPDATE_CHECK_MAX_AUTO_RETRIES = 2;
 const UPDATE_CHECK_RETRY_BASE_MS = 800;
 
@@ -102,6 +103,9 @@ export default function Dashboard({ apiBase }: { apiBase: string }) {
   const [injectionEfforts, setInjectionEfforts] = useState<string[]>([]);
   const [injectionAvailable, setInjectionAvailable] = useState<Array<{ provider: string; model: string; namespaced: string }>>([]);
   const [injectionSaving, setInjectionSaving] = useState(false);
+  const [effortCap, setEffortCap] = useState<string>("");
+  const [subagentEffortCap, setSubagentEffortCap] = useState<string>("");
+  const [effortCapSaving, setEffortCapSaving] = useState(false);
   const [syncResult, setSyncResult] = useState<SyncResult | null>(null);
   const [syncError, setSyncError] = useState<string | null>(null);
   const [projectConfigWarnings, setProjectConfigWarnings] = useState<ProjectCodexConfigGroup[]>([]);
@@ -161,6 +165,14 @@ export default function Dashboard({ apiBase }: { apiBase: string }) {
             setInjectionAvailable(imData.available ?? []);
           }
         } catch { /* old server */ }
+        try {
+          const ecRes = await fetch(`${apiBase}/api/effort-caps`);
+          if (ecRes.ok) {
+            const ecData = await ecRes.json() as { effortCap?: string | null; subagentEffortCap?: string | null; efforts?: string[] };
+            setEffortCap(ecData.effortCap ?? "");
+            setSubagentEffortCap(ecData.subagentEffortCap ?? "");
+          }
+        } catch { /* old server */ }
       } catch {
         setError(true);
       }
@@ -496,6 +508,64 @@ export default function Dashboard({ apiBase }: { apiBase: string }) {
         </div>
       )}
 
+      <div className="panel" style={{ marginBottom: 24 }}>
+        <div className="injection-head">
+          <span className="injection-label">{t("dash.effortCapLabel")}</span>
+          <Select
+            value={effortCap}
+            options={[
+              { value: "", label: t("dash.effortCapNone") },
+              ...EFFORT_CAP_LEVELS.map(e => ({ value: e, label: e })),
+            ]}
+            onChange={async (v) => {
+              if (effortCapSaving) return;
+              setEffortCapSaving(true);
+              try {
+                const res = await fetch(`${apiBase}/api/effort-caps`, {
+                  method: "PUT",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({ effortCap: v || null }),
+                });
+                if (res.ok) {
+                  const data = await res.json() as { ok: boolean; effortCap?: string | null; subagentEffortCap?: string | null };
+                  setEffortCap(data.effortCap ?? "");
+                  setSubagentEffortCap(data.subagentEffortCap ?? "");
+                }
+              } catch { /* ignore */ }
+              finally { setEffortCapSaving(false); }
+            }}
+            disabled={effortCapSaving}
+            label={t("dash.effortCapLabel")}
+          />
+          <Select
+            value={subagentEffortCap}
+            options={[
+              { value: "", label: t("dash.effortCapNone") },
+              ...EFFORT_CAP_LEVELS.map(e => ({ value: e, label: e })),
+            ]}
+            onChange={async (v) => {
+              if (effortCapSaving) return;
+              setEffortCapSaving(true);
+              try {
+                const res = await fetch(`${apiBase}/api/effort-caps`, {
+                  method: "PUT",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({ subagentEffortCap: v || null }),
+                });
+                if (res.ok) {
+                  const data = await res.json() as { ok: boolean; effortCap?: string | null; subagentEffortCap?: string | null };
+                  setEffortCap(data.effortCap ?? "");
+                  setSubagentEffortCap(data.subagentEffortCap ?? "");
+                }
+              } catch { /* ignore */ }
+              finally { setEffortCapSaving(false); }
+            }}
+            disabled={effortCapSaving}
+            label={t("dash.subagentEffortCapLabel")}
+          />
+        </div>
+      </div>
+
       <div className="panel" style={{ marginBottom: 24 }}>
         <div className="injection-head">
           <span className="injection-label">{t("dash.injectionLabel")}</span>

src/adapters/openai-responses.ts

@@ -21,6 +21,7 @@ export const FORWARD_HEADERS = [
   "x-codex-turn-state",
   "x-codex-window-id",
   "x-oai-attestation",
+  "x-openai-subagent",
   "x-responsesapi-include-timing-metrics",
 ];
 

src/reasoning-effort.ts

@@ -19,6 +19,11 @@ export function isCodexReasoningEffort(effort: string): boolean {
   return CODEX_REASONING_SET.has(effort);
 }
 
+/** Position of `effort` in the Codex ladder (low=0 .. ultra=5), or -1 when not a ladder member. */
+export function codexEffortRank(effort: string): number {
+  return CODEX_REASONING_ORDER.indexOf(effort);
+}
+
 export function modelRecordValue<T>(record: Record<string, T> | undefined, modelId: string): T | undefined {
   if (!record) return undefined;
   if (Object.prototype.hasOwnProperty.call(record, modelId)) return record[modelId];