harden effort-cap gate: strict thread-spawn markers, surface-agnostic child admission, compaction bypass

Audit blockers (sol reviewer, GO-WITH-FIXES):
- isSubagentRequest -> isThreadSpawnRequest: exact x-openai-subagent=collab_spawn
  or subagent_kind=thread_spawn; review/compact/memory_consolidation and other
  maintenance markers no longer trip subagentEffortCap
- effortCapAppliesTo admits header-marked children regardless of tool surface
  (depth-limited leaves vs shallower children were capped inconsistently)
- compaction turns bypass caps so routed compaction matches native
  /v1/responses/compact which never enters handleResponses

Author: lidge-jun

src/server/effort-policy.ts

@@ -18,20 +18,25 @@ import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, mo
 import { catalogModelEfforts } from "../codex/catalog";
 
 /**
- * True when the request carries codex-rs's spawned-child markers. Source of truth
- * (openai/codex @ 6138909d): every collab-spawned child turn sends
+ * True when the request carries codex-rs's spawned-child markers, matched EXACTLY.
+ * Source of truth (openai/codex @ 6138909d): every collab-spawned child turn sends
  * `x-openai-subagent: collab_spawn` (core/src/responses_metadata.rs) and embeds
  * `"subagent_kind":"thread_spawn"` in the JSON `x-codex-turn-metadata` compatibility
  * header. Both are checked: the WS bridge rebuilds internal requests from the
  * FORWARD_HEADERS allowlist, so either header alone is sufficient evidence.
+ *
+ * Exact matching matters: upstream emits `x-openai-subagent` for OTHER internal
+ * turn categories too (review, compact, memory_consolidation, arbitrary "other"
+ * sources — responses_metadata.rs subagent_source). Those are maintenance turns,
+ * not spawned children, and must never trip subagentEffortCap.
  */
-export function isSubagentRequest(headers: Headers): boolean {
-  if (headers.get("x-openai-subagent")) return true;
+export function isThreadSpawnRequest(headers: Headers): boolean {
+  if (headers.get("x-openai-subagent") === "collab_spawn") return true;
   const turnMeta = headers.get("x-codex-turn-metadata");
   if (!turnMeta) return false;
   try {
     const parsed = JSON.parse(turnMeta) as { subagent_kind?: unknown };
-    return typeof parsed.subagent_kind === "string" && parsed.subagent_kind.length > 0;
+    return parsed.subagent_kind === "thread_spawn";
   } catch {
     return false;
   }
@@ -52,20 +57,26 @@ export function effortCapFor(config: OcxConfig, subagent: boolean): string | und
  * 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):
+ *  - compaction turns are maintenance, not agent turns: they bypass caps entirely so
+ *    native /v1/responses/compact (forwarded, never enters handleResponses) and routed
+ *    compaction (synthesized internal request) get identical cap semantics.
  *  - 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.
+ *  - a CHILD turn is admitted by its spawned-child markers (isThreadSpawnRequest)
+ *    REGARDLESS of tool surface: depth-limited leaves carry no collab tools (surface
+ *    null) while children below the spawn-depth limit retain collab tools (spec_plan.rs
+ *    leaf guard), so tool sniffing alone would cap siblings inconsistently.
+ *  - a v1-surface MAIN turn (no child markers) never qualifies.
  */
 export function effortCapAppliesTo(
   surface: "v1" | "v2" | null,
   headers: Headers,
   config: OcxConfig,
+  compaction = false,
 ): boolean {
+  if (compaction) return false;
   if (config.multiAgentMode === "v1") return false;
-  return surface === "v2" || (surface === null && isSubagentRequest(headers));
+  return surface === "v2" || isThreadSpawnRequest(headers);
 }
 
 /**
@@ -141,7 +152,7 @@ export function applyEffortCap(
   config: OcxConfig,
   supported?: readonly string[] | undefined,
 ): { from: string; to: string; subagent: boolean } | null {
-  const subagent = isSubagentRequest(headers);
+  const subagent = isThreadSpawnRequest(headers);
   const cap = effortCapFor(config, subagent);
   if (!cap) return null;
   const resolved = resolveCappedEffort(cap, supported);

src/server/responses.ts

@@ -476,12 +476,15 @@ export async function handleResponses(
   // 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.
+  // child turns admitted regardless of tool surface (depth-limited leaves carry no collab
+  // tools while shallower children do, so tool sniffing alone would cap siblings
+  // inconsistently); multiAgentMode "v1" disables caps entirely; compaction turns bypass
+  // caps so routed compaction matches native /v1/responses/compact (which never enters
+  // handleResponses).
   {
     const { applyEffortCap, effortCapAppliesTo, supportedLadderFor } = await import("./effort-policy");
     const surface = collabSurface(parsed);
-    if (effortCapAppliesTo(surface, req.headers, config)) {
+    if (effortCapAppliesTo(surface, req.headers, config, parsed._compactionRequest === true)) {
       const capped = applyEffortCap(parsed, req.headers, config, supportedLadderFor(route));
       if (capped) {
         logCtx.requestedEffort = `${capped.from}->${capped.to}`;

tests/effort-policy.test.ts

@@ -7,7 +7,7 @@ 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, effortCapAppliesTo, effortCapFor, isSubagentRequest, resolveCappedEffort, supportedLadderFor } from "../src/server/effort-policy";
+import { applyEffortCap, effortCapAppliesTo, effortCapFor, isThreadSpawnRequest, 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";
@@ -51,22 +51,33 @@ const MAIN_HEADERS = new Headers({
   "x-codex-turn-metadata": JSON.stringify({ turn_id: "t1" }),
 });
 
-describe("isSubagentRequest", () => {
-  test("x-openai-subagent marker classifies as sub-agent", () => {
-    expect(isSubagentRequest(SUBAGENT_HEADERS)).toBe(true);
+describe("isThreadSpawnRequest", () => {
+  test("x-openai-subagent: collab_spawn classifies as spawned child", () => {
+    expect(isThreadSpawnRequest(SUBAGENT_HEADERS)).toBe(true);
   });
 
-  test("subagent_kind inside x-codex-turn-metadata classifies as sub-agent", () => {
-    expect(isSubagentRequest(TURN_META_HEADERS)).toBe(true);
+  test("subagent_kind: thread_spawn inside x-codex-turn-metadata classifies as spawned child", () => {
+    expect(isThreadSpawnRequest(TURN_META_HEADERS)).toBe(true);
   });
 
   test("main-agent turn metadata and bare headers stay main", () => {
-    expect(isSubagentRequest(MAIN_HEADERS)).toBe(false);
-    expect(isSubagentRequest(new Headers())).toBe(false);
+    expect(isThreadSpawnRequest(MAIN_HEADERS)).toBe(false);
+    expect(isThreadSpawnRequest(new Headers())).toBe(false);
   });
 
-  test("malformed turn metadata never classifies as sub-agent", () => {
-    expect(isSubagentRequest(new Headers({ "x-codex-turn-metadata": "{not json" }))).toBe(false);
+  test("non-spawn subagent categories never classify as spawned children", () => {
+    // Upstream emits x-openai-subagent for review/compact/memory-consolidation/"other"
+    // maintenance turns too (responses_metadata.rs) — only collab_spawn is a child.
+    for (const kind of ["review", "compact", "memory_consolidation", "other", "anything"]) {
+      expect(isThreadSpawnRequest(new Headers({ "x-openai-subagent": kind }))).toBe(false);
+      const meta = new Headers({ "x-codex-turn-metadata": JSON.stringify({ subagent_kind: kind }) });
+      expect(isThreadSpawnRequest(meta)).toBe(false);
+    }
+  });
+
+  test("malformed turn metadata never classifies as spawned child", () => {
+    expect(isThreadSpawnRequest(new Headers({ "x-codex-turn-metadata": "{not json" }))).toBe(false);
+    expect(isThreadSpawnRequest(new Headers({ "x-codex-turn-metadata": JSON.stringify({ subagent_kind: 42 }) }))).toBe(false);
   });
 });
 
@@ -320,9 +331,10 @@ describe("effortCapAppliesTo (caps are a v2-feature gate)", () => {
     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.
+  test("depth-limited child turn carries no collab tools — the spawned-child header still admits the cap", () => {
+    // Regression guard: depth-limited leaf children carry no collab tools (surface
+    // null), 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" });
@@ -331,6 +343,29 @@ describe("effortCapAppliesTo (caps are a v2-feature gate)", () => {
     expect(applyEffortCap(parsed, childHeaders, config)).toEqual({ from: "max", to: "medium", subagent: true });
   });
 
+  test("header-marked child with a v1 tool surface is still admitted (surface-agnostic child gate)", () => {
+    // Children below the spawn-depth limit retain collab tools (spec_plan.rs leaf
+    // guard) — two siblings must not get different cap treatment based on depth.
+    const childHeaders = new Headers({ "x-openai-subagent": "collab_spawn" });
+    const config = makeConfig({ subagentEffortCap: "medium" });
+    expect(effortCapAppliesTo("v1", childHeaders, config)).toBe(true);
+    expect(effortCapAppliesTo("v2", childHeaders, config)).toBe(true);
+  });
+
+  test("non-spawn subagent markers do not admit the cap", () => {
+    const config = makeConfig({ effortCap: "high", subagentEffortCap: "medium" });
+    expect(effortCapAppliesTo(null, new Headers({ "x-openai-subagent": "review" }), config)).toBe(false);
+    expect(effortCapAppliesTo(null, new Headers({ "x-openai-subagent": "compact" }), config)).toBe(false);
+    expect(effortCapAppliesTo(null, new Headers({ "x-openai-subagent": "memory_consolidation" }), config)).toBe(false);
+    const otherMeta = new Headers({ "x-codex-turn-metadata": JSON.stringify({ subagent_kind: "other" }) });
+    expect(effortCapAppliesTo(null, otherMeta, config)).toBe(false);
+  });
+
+  test("malformed turn metadata never admits the cap", () => {
+    const config = makeConfig({ effortCap: "high", subagentEffortCap: "medium" });
+    expect(effortCapAppliesTo(null, new Headers({ "x-codex-turn-metadata": "{not json" }), config)).toBe(false);
+  });
+
   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);
@@ -341,6 +376,24 @@ describe("effortCapAppliesTo (caps are a v2-feature gate)", () => {
     expect(effortCapAppliesTo("v2", new Headers(), config)).toBe(false);
     expect(effortCapAppliesTo(null, new Headers({ "x-openai-subagent": "collab_spawn" }), config)).toBe(false);
   });
+
+  test("explicit default and forced-v2 modes keep the gate open for v2 surfaces and marked children", () => {
+    for (const mode of ["default", "v2"] as const) {
+      const config = makeConfig({ effortCap: "high", multiAgentMode: mode });
+      expect(effortCapAppliesTo("v2", new Headers(), config)).toBe(true);
+      expect(effortCapAppliesTo(null, new Headers({ "x-openai-subagent": "collab_spawn" }), config)).toBe(true);
+      // A plain main turn stays out even under forced v2 — no collab tools, no markers.
+      expect(effortCapAppliesTo(null, new Headers(), config)).toBe(false);
+    }
+  });
+
+  test("compaction turns bypass the cap regardless of surface or markers", () => {
+    // Native /v1/responses/compact never enters handleResponses; routed compaction
+    // must not diverge from it, so the gate refuses when the compaction flag is set.
+    const config = makeConfig({ effortCap: "high", subagentEffortCap: "medium" });
+    expect(effortCapAppliesTo("v2", new Headers(), config, true)).toBe(false);
+    expect(effortCapAppliesTo(null, new Headers({ "x-openai-subagent": "collab_spawn" }), config, true)).toBe(false);
+  });
 });
 
 describe("cap composition with downstream clamps", () => {