feat(effort-cap): gate caps to the v2 feature surface

- effortCapAppliesTo: multiAgentMode "v1" disables caps; v2-surface main
  turns qualify by tool list; child turns (which never carry collab tools)
  qualify via the spawned-child headers, so subagentEffortCap actually lands
  on the turns it targets
- Dashboard: effort-cap panel hidden in v1 mode, help popup + i18n
  (en/ko/zh/de) explaining v2-only cap semantics
- tests: child-header admission regression + mode kill-switch coverage

Author: lidge-jun

gui/src/i18n/de.ts

@@ -54,8 +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.effortCapLabel": "V2 Ultra Effort-Limit",
+  "dash.subagentEffortCapLabel": "V2 Sub-Agent Effort-Limit",
+  "dash.effortCapHelp": "Begrenzt die Reasoning-Intensität für V2-Ultra-Modus-Turns. Wenn gesetzt, werden eingehende Max-Anfragen (aus dem Ultra-Modus) auf das gewählte Niveau begrenzt. Das Sub-Agent-Limit gilt nur für erzeugte Kind-Agenten. Limits senken die Intensität nur, sie erhöhen sie nie. Wenn ein Modell das gewählte Niveau nicht unterstützt, wird automatisch auf das nächste unterstützte Niveau herabgesetzt.",
   "dash.effortCapNone": "Kein Limit",
   "dash.maintenance": "Wartung",
   "dash.maintenanceHint": "Aktualisiere Codex’ Modellkatalog oder installiere eine neuere opencodex-Version.",

gui/src/i18n/en.ts

@@ -58,8 +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.effortCapLabel": "V2 ultra effort limit",
+  "dash.subagentEffortCapLabel": "V2 sub-agent effort limit",
+  "dash.effortCapHelp": "Limits the reasoning effort for V2 ultra-mode turns. When set, incoming max-effort requests (from ultra mode) are capped to the selected level. The sub-agent limit applies only to spawned child agents. Caps only lower effort, never raise it. If a model doesn't support the capped level, it snaps down to the nearest supported level.",
   "dash.effortCapNone": "No cap",
   "dash.maintenance": "Maintenance",
   "dash.maintenanceHint": "Refresh Codex's model catalog or install a newer opencodex release.",

gui/src/i18n/ko.ts

@@ -58,8 +58,9 @@ export const ko: Record<TKey, string> = {
   "dash.injectionNone": "없음",
   "dash.injectionEffortLabel": "추론 강도",
   "dash.injectionEffortNone": "모델 기본값",
-  "dash.effortCapLabel": "ultra 추론 강도 제한",
-  "dash.subagentEffortCapLabel": "추론 강도 상한 (서브에이전트)",
+  "dash.effortCapLabel": "V2 ultra 추론 강도 제한",
+  "dash.subagentEffortCapLabel": "V2 서브에이전트 추론 강도 제한",
+  "dash.effortCapHelp": "V2 ultra 모드 턴의 추론 강도를 제한합니다. 설정하면 ultra 모드에서 들어오는 max 요청이 선택한 수준으로 내려갑니다. 서브에이전트 제한은 스폰된 자식 에이전트에만 적용됩니다. 강도를 낮추기만 하고 올리지는 않습니다. 모델이 해당 수준을 지원하지 않으면 가장 가까운 지원 수준으로 내려갑니다.",
   "dash.effortCapNone": "상한 없음",
     "dash.maintenance": "유지보수",
   "dash.maintenanceHint": "Codex 모델 카탈로그를 새로고침하거나 최신 opencodex 릴리스를 설치합니다.",

gui/src/i18n/zh.ts

@@ -58,8 +58,9 @@ export const zh: Record<TKey, string> = {
   "dash.injectionNone": "无",
   "dash.injectionEffortLabel": "推理强度",
   "dash.injectionEffortNone": "模型默认",
-  "dash.effortCapLabel": "Ultra 推理强度限制",
-  "dash.subagentEffortCapLabel": "推理强度上限（子代理）",
+  "dash.effortCapLabel": "V2 ultra 推理强度限制",
+  "dash.subagentEffortCapLabel": "V2 子代理推理强度限制",
+  "dash.effortCapHelp": "限制 V2 ultra 模式轮次的推理强度。设置后，来自 ultra 模式的 max 请求将被限制到所选级别。子代理限制仅适用于衍生的子代理。只会降低强度，不会提高。如果模型不支持所选级别，将自动降至最近的支持级别。",
   "dash.effortCapNone": "无上限",
     "dash.maintenance": "维护",
   "dash.maintenanceHint": "刷新 Codex 模型目录，或安装新的 opencodex 版本。",

gui/src/pages/Dashboard.tsx

@@ -98,6 +98,7 @@ export default function Dashboard({ apiBase }: { apiBase: string }) {
   const [maMode, setMaMode] = useState<"v1" | "default" | "v2">("default");
   const [maBusy, setMaBusy] = useState(false);
   const [maHelpOpen, setMaHelpOpen] = useState(false);
+  const [effortCapHelpOpen, setEffortCapHelpOpen] = useState(false);
   const [injectionModel, setInjectionModel] = useState<string>("");
   const [injectionEffort, setInjectionEffort] = useState<string>("");
   const [injectionEfforts, setInjectionEfforts] = useState<string[]>([]);
@@ -508,9 +509,43 @@ 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>
+      {maMode !== "v1" && (
+        <div className="panel" style={{ marginBottom: 24 }}>
+          <div className="injection-head">
+            <span className="injection-label" style={{ display: "inline-flex", alignItems: "center", gap: 6 }}>
+              {t("dash.effortCapLabel")}
+              <span style={{ position: "relative", display: "inline-flex" }}>
+                <button
+                  type="button"
+                  className="btn btn-ghost btn-sm"
+                  style={{ width: 22, height: 22, minWidth: 22, padding: 0, borderRadius: 999, color: "var(--muted)" }}
+                  onClick={() => setEffortCapHelpOpen(open => !open)}
+                  aria-label={t("dash.effortCapLabel")}
+                  aria-expanded={effortCapHelpOpen}
+                  aria-haspopup="dialog"
+                >
+                  <IconInfo width={13} height={13} aria-hidden="true" />
+                </button>
+                {effortCapHelpOpen && (
+                  <div
+                    role="dialog"
+                    className="help-popup"
+                    style={{ position: "absolute", top: "calc(100% + 8px)", left: 0, width: "min(360px, calc(100vw - 48px))", padding: "12px 16px", border: "1px solid var(--border)", borderRadius: 8, background: "var(--bg)", boxShadow: "0 8px 24px rgba(0, 0, 0, 0.14)", color: "var(--text)", fontSize: 13, fontWeight: 400, lineHeight: 1.5, zIndex: 10 }}
+                  >
+                    <button
+                      type="button"
+                      className="btn btn-ghost btn-icon"
+                      style={{ position: "absolute", top: 4, right: 4, width: 24, height: 24, minWidth: 24 }}
+                      onClick={() => setEffortCapHelpOpen(false)}
+                      aria-label="Close"
+                    >
+                      <IconX width={14} height={14} />
+                    </button>
+                    <div style={{ paddingRight: 16 }}>{t("dash.effortCapHelp")}</div>
+                  </div>
+                )}
+              </span>
+            </span>
           <Select
             value={effortCap}
             options={[
@@ -563,8 +598,9 @@ export default function Dashboard({ apiBase }: { apiBase: string }) {
             disabled={effortCapSaving}
             label={t("dash.subagentEffortCapLabel")}
           />
+          </div>
         </div>
-      </div>
+      )}
 
       <div className="panel" style={{ marginBottom: 24 }}>
         <div className="injection-head">

src/server/effort-policy.ts

@@ -48,6 +48,26 @@ export function effortCapFor(config: OcxConfig, subagent: boolean): string | und
   return caps.reduce((low, cap) => (codexEffortRank(cap) < codexEffortRank(low) ? cap : low));
 }
 
+/**
+ * Whether the effort caps apply to this turn at all. Caps are a V2-surface feature
+ * (v1 sub-agents are pinned via explicit spawn args + injectionEffort prompting, so
+ * the ultra-default leak this module intercepts is v2-specific):
+ *  - multiAgentMode "v1" disables caps entirely (mirrors the GUI hiding the panel).
+ *  - a main turn qualifies when its own tool list carries the v2 collab surface.
+ *  - a CHILD turn carries no collab tools (surface null) — its discriminator is the
+ *    spawned-child header pair (isSubagentRequest), so the subagent cap still lands
+ *    on exactly the turns it targets.
+ *  - a v1-surface turn never qualifies.
+ */
+export function effortCapAppliesTo(
+  surface: "v1" | "v2" | null,
+  headers: Headers,
+  config: OcxConfig,
+): boolean {
+  if (config.multiAgentMode === "v1") return false;
+  return surface === "v2" || (surface === null && isSubagentRequest(headers));
+}
+
 /**
  * The routed model's supported effort ladder for cap resolution, from the ROUTE's
  * registry-merged provider (router.ts routedProviderConfig) — the persisted

src/server/responses.ts

@@ -475,14 +475,22 @@ export async function handleResponses(
   // ultra-tier default on bare spawns (see src/server/effort-policy.ts). Runs BEFORE the
   // mock-max clamp so a capped effort is what nativeness clamping then validates; rewrites
   // both request shapes (same dual-write contract as the clamp below).
+  // GATE: v2 feature only (effortCapAppliesTo) — v2-surface main turns plus header-marked
+  // child turns (children carry no collab tools, so tool sniffing alone would skip the very
+  // turns subagentEffortCap targets); multiAgentMode "v1" disables caps entirely.
   {
-    const { applyEffortCap, supportedLadderFor } = await import("./effort-policy");
-    const capped = applyEffortCap(parsed, req.headers, config, supportedLadderFor(route));
-    if (capped) {
-      logCtx.requestedEffort = `${capped.from}->${capped.to}`;
-      if (isInjectionDebugEnabled()) {
-        console.log(`[opencodex] ${route.modelId}: effort cap applied (${capped.from} -> ${capped.to}, ${capped.subagent ? "sub-agent" : "main"} turn)`);
+    const { applyEffortCap, effortCapAppliesTo, supportedLadderFor } = await import("./effort-policy");
+    const surface = collabSurface(parsed);
+    if (effortCapAppliesTo(surface, req.headers, config)) {
+      const capped = applyEffortCap(parsed, req.headers, config, supportedLadderFor(route));
+      if (capped) {
+        logCtx.requestedEffort = `${capped.from}->${capped.to}`;
+        if (isInjectionDebugEnabled()) {
+          console.log(`[opencodex] ${route.modelId}: effort cap applied (${capped.from} -> ${capped.to}, ${capped.subagent ? "sub-agent" : "main"} turn)`);
+        }
       }
+    } else if (isInjectionDebugEnabled() && (config.effortCap || config.subagentEffortCap)) {
+      console.log(`[opencodex] ${route.modelId}: effort cap skipped (surface=${surface ?? "none"}, v2 feature only)`);
     }
   }
 

tests/effort-policy.test.ts

@@ -7,7 +7,8 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { applyEffortCap, effortCapFor, isSubagentRequest, resolveCappedEffort, supportedLadderFor } from "../src/server/effort-policy";
+import { applyEffortCap, effortCapAppliesTo, effortCapFor, isSubagentRequest, resolveCappedEffort, supportedLadderFor } from "../src/server/effort-policy";
+import { collabSurface } from "../src/server/responses";
 import { handleManagementAPI } from "../src/server/management-api";
 import { routeModel } from "../src/router";
 import { mapReasoningEffort } from "../src/reasoning-effort";
@@ -281,6 +282,67 @@ describe("supportedLadderFor (real routeModel routes)", () => {
   });
 });
 
+describe("effortCapAppliesTo (caps are a v2-feature gate)", () => {
+  function parsedWithTools(tools: Array<{ name: string; namespace?: string }>, reasoning?: string): OcxParsedRequest {
+    return {
+      modelId: "gpt-5.6-sol",
+      context: {
+        messages: [{ role: "user", content: "hi", timestamp: 1 }],
+        tools: tools as never,
+      },
+      stream: true,
+      options: reasoning ? { reasoning: reasoning as never } : {},
+      _rawBody: { model: "gpt-5.6-sol", reasoning: reasoning ? { effort: reasoning } : undefined },
+    };
+  }
+
+  test("v2 flat spawn_agent surface is classified v2 — caps apply", () => {
+    const parsed = parsedWithTools([{ name: "spawn_agent" }], "max");
+    expect(collabSurface(parsed)).toBe("v2");
+    const config = makeConfig({ effortCap: "high" });
+    expect(effortCapAppliesTo("v2", new Headers(), config)).toBe(true);
+    expect(applyEffortCap(parsed, new Headers(), config)).toEqual({ from: "max", to: "high", subagent: false });
+  });
+
+  test("v1 namespaced spawn + send_input is classified v1 — gate refuses", () => {
+    const parsed = parsedWithTools([
+      { name: "spawn_agent", namespace: "agents" },
+      { name: "send_input", namespace: "agents" },
+    ], "max");
+    expect(collabSurface(parsed)).toBe("v1");
+    // applyEffortCap itself is surface-unaware; handleResponses consults the gate.
+    expect(effortCapAppliesTo("v1", new Headers(), makeConfig({ effortCap: "high" }))).toBe(false);
+  });
+
+  test("plain main turn (no collab tools, no child headers) — gate refuses", () => {
+    const parsed = parsedWithTools([{ name: "shell" }], "max");
+    expect(collabSurface(parsed)).toBeNull();
+    expect(effortCapAppliesTo(null, new Headers(), makeConfig({ effortCap: "high", subagentEffortCap: "medium" }))).toBe(false);
+  });
+
+  test("child turn carries no collab tools — the spawned-child header still admits the cap", () => {
+    // Regression guard: children never carry spawn_agent, so a surface-only gate would
+    // skip exactly the turns subagentEffortCap exists for.
+    const parsed = parsedWithTools([{ name: "shell" }], "max");
+    expect(collabSurface(parsed)).toBeNull();
+    const config = makeConfig({ subagentEffortCap: "medium" });
+    const childHeaders = new Headers({ "x-openai-subagent": "collab_spawn" });
+    expect(effortCapAppliesTo(null, childHeaders, config)).toBe(true);
+    expect(applyEffortCap(parsed, childHeaders, config)).toEqual({ from: "max", to: "medium", subagent: true });
+  });
+
+  test("turn-metadata subagent_kind alone admits the cap for a child turn", () => {
+    const headers = new Headers({ "x-codex-turn-metadata": JSON.stringify({ subagent_kind: "thread_spawn" }) });
+    expect(effortCapAppliesTo(null, headers, makeConfig({ subagentEffortCap: "medium" }))).toBe(true);
+  });
+
+  test("multiAgentMode v1 disables the gate entirely, even for v2 surfaces and child headers", () => {
+    const config = makeConfig({ effortCap: "high", subagentEffortCap: "medium", multiAgentMode: "v1" });
+    expect(effortCapAppliesTo("v2", new Headers(), config)).toBe(false);
+    expect(effortCapAppliesTo(null, new Headers({ "x-openai-subagent": "collab_spawn" }), config)).toBe(false);
+  });
+});
+
 describe("cap composition with downstream clamps", () => {
   test("snapped ordinary rung passes mapReasoningEffort unchanged for a supporting provider", () => {
     const provider = {