@yansigit/opencodex 2.31.0

package/src/server/direct-local-http.ts

@@ -0,0 +1,347 @@
+import net, { type Socket } from "node:net";
+
+const DIRECT_LOCAL_HTTP_MAX_BYTES = 8 * 1024 * 1024;
+const DIRECT_LOCAL_HTTP_TIMEOUT_MS = 10_000;
+
+type DirectLocalHttpIo = {
+  timeoutMs?: number;
+  connect?: (hostname: string, port: number) => Socket;
+};
+
+function abortReason(signal: AbortSignal): Error {
+  if (signal.reason instanceof Error) return signal.reason;
+  const error = new Error("direct local HTTP request aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+function headerBoundary(bytes: Buffer): number {
+  return bytes.indexOf("\r\n\r\n");
+}
+
+function validateTrailerLines(bytes: Buffer, start: number, end: number): void {
+  if (end === start) return;
+  for (const line of bytes.subarray(start, end).toString("latin1").split("\r\n")) {
+    if (line.indexOf(":") <= 0) {
+      throw new Error("direct local HTTP response has an invalid chunk trailer");
+    }
+  }
+}
+
+function decodeChunkedBody(body: Buffer): Buffer {
+  const chunks: Buffer[] = [];
+  let offset = 0;
+  for (;;) {
+    const lineEnd = body.indexOf("\r\n", offset);
+    if (lineEnd < 0) throw new Error("direct local HTTP response has a truncated chunk header");
+    const rawSize = body.subarray(offset, lineEnd).toString("ascii").split(";", 1)[0]?.trim() ?? "";
+    if (!/^[0-9a-f]+$/i.test(rawSize)) throw new Error("direct local HTTP response has an invalid chunk size");
+    const size = Number.parseInt(rawSize, 16);
+    offset = lineEnd + 2;
+    if (size === 0) {
+      if (body.length < offset + 2) throw new Error("direct local HTTP response has a truncated chunk trailer");
+      if (body[offset] !== 13 || body[offset + 1] !== 10) {
+        const trailerEnd = body.indexOf("\r\n\r\n", offset);
+        if (trailerEnd < 0) {
+          throw new Error("direct local HTTP response has a truncated chunk trailer");
+        }
+        validateTrailerLines(body, offset, trailerEnd);
+        if (trailerEnd + 4 !== body.length) {
+          throw new Error("direct local HTTP response has trailing bytes");
+        }
+      } else if (offset + 2 !== body.length) {
+        throw new Error("direct local HTTP response has trailing bytes");
+      }
+      return Buffer.concat(chunks);
+    }
+    if (!Number.isSafeInteger(size) || offset + size + 2 > body.length) {
+      throw new Error("direct local HTTP response has a truncated chunk body");
+    }
+    chunks.push(body.subarray(offset, offset + size));
+    offset += size;
+    if (body[offset] !== 13 || body[offset + 1] !== 10) {
+      throw new Error("direct local HTTP response has an invalid chunk terminator");
+    }
+    offset += 2;
+  }
+}
+
+type ResponseFraming =
+  | { kind: "head"; searchFrom: number }
+  | { kind: "content-length"; totalBytes: number }
+  | { kind: "chunk-size"; offset: number; searchFrom: number }
+  | { kind: "chunk-body"; offset: number; size: number }
+  | { kind: "trailers"; offset: number; searchFrom: number }
+  | { kind: "close" }
+  | { kind: "complete" };
+
+function parseResponseHead(bytes: Buffer, boundary: number): {
+  status: number;
+  statusText: string;
+  headers: Headers;
+} {
+  const lines = bytes.subarray(0, boundary).toString("latin1").split("\r\n");
+  const statusLine = lines.shift() ?? "";
+  const match = /^HTTP\/1\.[01] ([0-9]{3})(?: (.*))?$/.exec(statusLine);
+  if (!match) throw new Error("direct local HTTP response has an invalid status line");
+  const status = Number(match[1]);
+  if (status < 200 || status > 599) throw new Error("direct local HTTP response has an unsupported status");
+  const headers = new Headers();
+  for (const line of lines) {
+    const colon = line.indexOf(":");
+    if (colon <= 0) throw new Error("direct local HTTP response has an invalid header");
+    headers.append(line.slice(0, colon).trim(), line.slice(colon + 1).trim());
+  }
+  return { status, statusText: match[2] ?? "", headers };
+}
+
+function advanceResponseFraming(bytes: Buffer, initial: ResponseFraming): ResponseFraming {
+  let framing = initial;
+  for (;;) {
+    if (framing.kind === "complete" || framing.kind === "close") return framing;
+    if (framing.kind === "head") {
+      const boundary = bytes.indexOf("\r\n\r\n", framing.searchFrom);
+      if (boundary < 0) {
+        if (bytes.length > 64 * 1024) throw new Error("direct local HTTP response headers exceed the byte cap");
+        return { kind: "head", searchFrom: Math.max(0, bytes.length - 3) };
+      }
+      const { status, headers } = parseResponseHead(bytes, boundary);
+      const bodyStart = boundary + 4;
+      if (status === 204 || status === 205 || status === 304) {
+        if (bytes.length > bodyStart) {
+          throw new Error("direct local HTTP response has a body for a bodyless status");
+        }
+        return { kind: "complete" };
+      }
+      if (/\bchunked\b/i.test(headers.get("transfer-encoding") ?? "")) {
+        framing = { kind: "chunk-size", offset: bodyStart, searchFrom: bodyStart };
+        continue;
+      }
+      const rawLength = headers.get("content-length");
+      if (rawLength === null) return { kind: "close" };
+      if (!/^[0-9]+$/.test(rawLength)) throw new Error("direct local HTTP response has an invalid content length");
+      const length = Number(rawLength);
+      const totalBytes = bodyStart + length;
+      if (!Number.isSafeInteger(length) || totalBytes > DIRECT_LOCAL_HTTP_MAX_BYTES) {
+        throw new Error("direct local HTTP response exceeds the byte cap");
+      }
+      framing = { kind: "content-length", totalBytes };
+      continue;
+    }
+    if (framing.kind === "content-length") {
+      if (bytes.length > framing.totalBytes) {
+        throw new Error("direct local HTTP response has trailing bytes");
+      }
+      return bytes.length === framing.totalBytes ? { kind: "complete" } : framing;
+    }
+    if (framing.kind === "chunk-size") {
+      const lineEnd = bytes.indexOf("\r\n", framing.searchFrom);
+      if (lineEnd < 0) {
+        if (bytes.length - framing.offset > 8 * 1024) {
+          throw new Error("direct local HTTP response chunk header exceeds the byte cap");
+        }
+        return {
+          ...framing,
+          searchFrom: Math.max(framing.offset, bytes.length - 1),
+        };
+      }
+      const rawSize = bytes.subarray(framing.offset, lineEnd).toString("ascii").split(";", 1)[0]?.trim() ?? "";
+      if (!/^[0-9a-f]+$/i.test(rawSize)) throw new Error("direct local HTTP response has an invalid chunk size");
+      const size = Number.parseInt(rawSize, 16);
+      if (!Number.isSafeInteger(size) || size > DIRECT_LOCAL_HTTP_MAX_BYTES) {
+        throw new Error("direct local HTTP response chunk exceeds the byte cap");
+      }
+      const offset = lineEnd + 2;
+      framing = size === 0
+        ? { kind: "trailers", offset, searchFrom: offset }
+        : { kind: "chunk-body", offset, size };
+      continue;
+    }
+    if (framing.kind === "chunk-body") {
+      const terminator = framing.offset + framing.size;
+      if (terminator + 2 > bytes.length) return framing;
+      if (bytes[terminator] !== 13 || bytes[terminator + 1] !== 10) {
+        throw new Error("direct local HTTP response has an invalid chunk terminator");
+      }
+      framing = { kind: "chunk-size", offset: terminator + 2, searchFrom: terminator + 2 };
+      continue;
+    }
+    if (bytes.length < framing.offset + 2) return framing;
+    if (bytes[framing.offset] === 13 && bytes[framing.offset + 1] === 10) {
+      if (bytes.length > framing.offset + 2) {
+        throw new Error("direct local HTTP response has trailing bytes");
+      }
+      return { kind: "complete" };
+    }
+    const trailerEnd = bytes.indexOf("\r\n\r\n", framing.searchFrom);
+    if (trailerEnd >= 0) {
+      validateTrailerLines(bytes, framing.offset, trailerEnd);
+      if (bytes.length > trailerEnd + 4) {
+        throw new Error("direct local HTTP response has trailing bytes");
+      }
+      return { kind: "complete" };
+    }
+    if (bytes.length - framing.offset > 64 * 1024) {
+      throw new Error("direct local HTTP response trailers exceed the byte cap");
+    }
+    return { ...framing, searchFrom: Math.max(framing.offset, bytes.length - 3) };
+  }
+}
+
+function parseResponse(bytes: Buffer): Response {
+  const boundary = headerBoundary(bytes);
+  if (boundary < 0) throw new Error("direct local HTTP response has no header boundary");
+  const { status, statusText, headers } = parseResponseHead(bytes, boundary);
+
+  let body = bytes.subarray(boundary + 4);
+  if (/\bchunked\b/i.test(headers.get("transfer-encoding") ?? "")) {
+    body = decodeChunkedBody(body);
+    headers.delete("transfer-encoding");
+    headers.delete("content-length");
+  } else {
+    const rawLength = headers.get("content-length");
+    if (rawLength !== null) {
+      if (!/^[0-9]+$/.test(rawLength)) throw new Error("direct local HTTP response has an invalid content length");
+      const length = Number(rawLength);
+      if (!Number.isSafeInteger(length) || body.byteLength < length) {
+        throw new Error("direct local HTTP response body is truncated");
+      }
+      body = body.subarray(0, length);
+    }
+  }
+
+  const bodyless = status === 204 || status === 205 || status === 304;
+  return new Response(bodyless ? null : new Uint8Array(body), {
+    status,
+    statusText,
+    headers,
+  });
+}
+
+/**
+ * Fetch one bodyless local HTTP GET or POST over a direct TCP connection.
+ *
+ * Bun's global fetch and Bun 1.3's node:http compatibility layer can honor
+ * HTTP(S)_PROXY. Local identity and capability probes must not expose headers
+ * to, or accept a fabricated response from, such a proxy. node:net connects to
+ * the selected listener without consulting proxy environment variables. Each
+ * caller retains an injected fetch seam for deterministic unit tests.
+ */
+export async function directLocalHttpFetch(
+  input: string | URL | Request,
+  init: RequestInit = {},
+  io: DirectLocalHttpIo = {},
+): Promise<Response> {
+  const url = new URL(input instanceof Request ? input.url : String(input));
+  const method = (init.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+  const signal = init.signal ?? (input instanceof Request ? input.signal : undefined);
+  const body = init.body ?? (input instanceof Request ? input.body : null);
+
+  if (url.protocol !== "http:") throw new Error("direct local request must use HTTP");
+  if (url.username || url.password) throw new Error("direct local request URL must not contain credentials");
+  if ((method !== "GET" && method !== "POST") || body !== null) {
+    throw new Error("direct local request must be a bodyless GET or POST");
+  }
+  if (signal?.aborted) throw abortReason(signal);
+
+  const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
+  headers.delete("proxy-authorization");
+  headers.delete("proxy-connection");
+  if (method === "POST") headers.set("content-length", "0");
+  else headers.delete("content-length");
+  headers.set("host", url.host);
+  headers.set("connection", "close");
+  const headerLines: string[] = [];
+  headers.forEach((value, key) => { headerLines.push(`${key}: ${value}`); });
+  const requestBytes = Buffer.from(
+    `${method} ${url.pathname}${url.search} HTTP/1.1\r\n${headerLines.join("\r\n")}\r\n\r\n`,
+    "latin1",
+  );
+  const parsedHostname = url.hostname.startsWith("[") && url.hostname.endsWith("]")
+    ? url.hostname.slice(1, -1)
+    : url.hostname;
+  const hostname = parsedHostname;
+  const port = url.port ? Number(url.port) : 80;
+  const timeoutMs = io.timeoutMs ?? DIRECT_LOCAL_HTTP_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("direct local HTTP timeout must be positive");
+  }
+
+  return await new Promise<Response>((resolve, reject) => {
+    let socket: Socket | undefined;
+    let settled = false;
+    let receivedBytes = 0;
+    let responseBytes = Buffer.allocUnsafe(4 * 1024);
+    let framing: ResponseFraming = { kind: "head", searchFrom: 0 };
+    const cleanup = () => {
+      signal?.removeEventListener("abort", onAbort);
+      socket?.setTimeout(0);
+    };
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      try { socket?.destroy(); } catch { /* ignore */ }
+      if (error) {
+        reject(error);
+        return;
+      }
+      try {
+        resolve(parseResponse(responseBytes.subarray(0, receivedBytes)));
+      } catch (parseError) {
+        reject(parseError instanceof Error ? parseError : new Error(String(parseError)));
+      }
+    };
+    const onAbort = () => {
+      const error = signal ? abortReason(signal) : new Error("direct local HTTP request aborted");
+      finish(error);
+    };
+
+    socket = (io.connect ?? ((host, selectedPort) => net.createConnection({
+      host,
+      port: selectedPort,
+      autoSelectFamily: true,
+    })))(hostname, port);
+    socket.setTimeout(timeoutMs, () => {
+      const error = new Error("direct local HTTP request timed out");
+      error.name = "TimeoutError";
+      finish(error);
+    });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    socket.on("connect", () => {
+      try { socket?.write(requestBytes); } catch (error) {
+        finish(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+    socket.on("data", chunk => {
+      if (settled) return;
+      const bytes = Buffer.from(chunk);
+      receivedBytes += bytes.byteLength;
+      if (receivedBytes > DIRECT_LOCAL_HTTP_MAX_BYTES) {
+        finish(new Error("direct local HTTP response exceeds the byte cap"));
+        return;
+      }
+      if (receivedBytes > responseBytes.byteLength) {
+        let capacity = responseBytes.byteLength;
+        while (capacity < receivedBytes) capacity = Math.min(DIRECT_LOCAL_HTTP_MAX_BYTES, capacity * 2);
+        const grown = Buffer.allocUnsafe(capacity);
+        responseBytes.copy(grown);
+        responseBytes = grown;
+      }
+      bytes.copy(responseBytes, receivedBytes - bytes.byteLength);
+      try {
+        framing = advanceResponseFraming(responseBytes.subarray(0, receivedBytes), framing);
+        if (framing.kind === "complete") finish();
+      } catch (error) {
+        finish(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+    socket.once("end", () => finish());
+    socket.once("error", error => finish(error));
+    socket.once("close", () => finish());
+  });
+}

package/src/server/effort-policy.ts

@@ -0,0 +1,190 @@
+/**
+ * Hard reasoning-effort caps (devlog/260710_subagent_effort_intercept).
+ *
+ * Prompt-side effort designation (injectionEffort) is advisory only: codex-rs inherits the
+ * parent's effective effort when spawn_agent carries no model/effort args
+ * (multi_agents_common.rs resolve defaults), rejects overrides on full-history forks, and a
+ * non-empty agent-role file rebuilds the child Config and silently drops spawn-time
+ * model/effort. So a session whose config default is ultra leaks max-tier children whenever
+ * the parent model spawns bare. This module is the enforcement path: it rewrites the effort
+ * of proxied turns at the single choke point every HTTP/WS turn passes through
+ * (handleResponses), using the same dual-shape rewrite contract as nativeEffortClamp —
+ * parsed.options.reasoning feeds routed adapters, _rawBody.reasoning.effort feeds the
+ * ChatGPT passthrough serializer.
+ */
+import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
+import { modelInList } from "../types";
+import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, modelRecordValue } from "../reasoning-effort";
+import { catalogModelEfforts } from "../codex/catalog";
+
+/**
+ * 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 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 parsed.subagent_kind === "thread_spawn";
+  } catch {
+    return false;
+  }
+}
+
+/** The effective ceiling for this turn, or undefined when no configured cap applies. */
+export function effortCapFor(config: OcxConfig, subagent: boolean): string | undefined {
+  const caps: string[] = [];
+  if (config.effortCap && isCodexReasoningEffort(config.effortCap)) caps.push(config.effortCap);
+  if (subagent && config.subagentEffortCap && isCodexReasoningEffort(config.subagentEffortCap)) {
+    caps.push(config.subagentEffortCap);
+  }
+  if (caps.length === 0) return undefined;
+  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):
+ *  - 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 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" || isThreadSpawnRequest(headers);
+}
+
+/**
+ * The routed model's supported effort ladder for cap resolution, from the ROUTE's
+ * registry-merged provider (router.ts routedProviderConfig) — the persisted
+ * config.providers entry misses registry seeds, and bare ids can route via
+ * defaultModel/model-list/default-provider, so no "/" heuristic anywhere.
+ *
+ * - `[]`   -> the model intentionally exposes no effort control (noReasoningModels or
+ *             an explicitly empty configured ladder): cap resolution strips.
+ * - list   -> sanitized + healed ladder (configuredReasoningEfforts).
+ * - undefined -> unknown. Includes the raw-nonempty-but-non-rankable case (e.g. a
+ *             thinking-toggle ladder of ["enabled"]): sanitizing would flatten it to []
+ *             and mis-classify it as "no effort control", so it stays unknown.
+ *
+ * Catalog fallback fires only for the ChatGPT-backend native passthrough IDENTITY
+ * (adapter "openai-responses" + authMode "forward", the fresh-install `openai`
+ * provider shape): the injected catalog is authoritative exactly for models Codex
+ * validates against that backend. A custom responses provider (key mode) serving a
+ * native-looking bare id must NOT inherit the unrelated native ladder.
+ */
+/**
+ * Empty ladders mean "no effort control", not "this model cannot emit reasoning".
+ * Drop only `effort` so a Chat Completions `include_reasoning` / `reasoning.summary`
+ * request still reaches parseRequest and is not hidden by hideThinkingSummary.
+ */
+export function stripEmptyLadderEffort(
+  reasoning: unknown,
+  ladder: readonly string[] | undefined,
+): unknown {
+  if (ladder === undefined || ladder.length > 0) return reasoning;
+  if (reasoning === undefined || reasoning === null || typeof reasoning !== "object" || Array.isArray(reasoning)) {
+    return reasoning;
+  }
+  const next = { ...(reasoning as Record<string, unknown>) };
+  delete next.effort;
+  return Object.keys(next).length > 0 ? next : undefined;
+}
+
+export function supportedLadderFor(route: { provider: OcxProviderConfig; modelId: string }): string[] | undefined {
+  const { provider, modelId } = route;
+  if (modelInList(provider.noReasoningModels, modelId)) return [];
+  const raw = modelRecordValue(provider.modelReasoningEfforts, modelId) ?? provider.reasoningEfforts;
+  if (raw !== undefined) {
+    const sanitized = configuredReasoningEfforts(provider, modelId) ?? [];
+    if (sanitized.length === 0 && raw.length > 0) return undefined;
+    return sanitized;
+  }
+  if (provider.adapter === "openai-responses" && provider.authMode === "forward") {
+    const efforts = catalogModelEfforts([modelId]).get(modelId);
+    if (efforts && efforts.length > 0) return efforts;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the configured cap against the model's supported ladder. Returns the effective
+ * ceiling rung, or null when the turn must be STRIPPED of its effort entirely. The cap
+ * NEVER raises: when rankable rungs exist but none sits at or below the cap, the model
+ * cannot run within the ceiling, so the effort is stripped and the provider default
+ * applies (never a rung above the cap).
+ */
+export function resolveCappedEffort(cap: string, supported: readonly string[] | undefined): string | null {
+  if (supported === undefined) return cap;
+  const rankable = supported.filter(isCodexReasoningEffort);
+  if (rankable.length === 0) {
+    // Nonempty but non-rankable (e.g. ["enabled"]) -> unknown ladder, cap as-is.
+    // Genuinely empty -> no effort control at all -> strip.
+    return supported.length > 0 ? cap : null;
+  }
+  const capRank = codexEffortRank(cap);
+  let best: string | null = null;
+  for (const rung of rankable) {
+    const rank = codexEffortRank(rung);
+    if (rank <= capRank && (best === null || rank > codexEffortRank(best))) best = rung;
+  }
+  return best;
+}
+
+/**
+ * Cap the turn's reasoning effort in BOTH request shapes. Non-strip resolution only
+ * lowers: efforts at or below the resolved ceiling (and non-ladder/absent efforts) pass
+ * untouched. Strip resolution (model exposes no effort control, or no supported rung
+ * fits under the cap) removes whatever effort is present — regardless of its rank —
+ * from both shapes while preserving `reasoning.summary`. Returns the applied rewrite
+ * for request-log annotation (`to: "none"` on strip), or null when nothing changed.
+ */
+export function applyEffortCap(
+  parsed: OcxParsedRequest,
+  headers: Headers,
+  config: OcxConfig,
+  supported?: readonly string[] | undefined,
+): { from: string; to: string; subagent: boolean } | null {
+  const subagent = isThreadSpawnRequest(headers);
+  const cap = effortCapFor(config, subagent);
+  if (!cap) return null;
+  const resolved = resolveCappedEffort(cap, supported);
+  const requested = parsed.options.reasoning;
+  const raw = parsed._rawBody as { reasoning?: { effort?: string } } | undefined;
+  if (resolved === null) {
+    if (!requested) return null;
+    parsed.options.reasoning = undefined;
+    if (raw?.reasoning && typeof raw.reasoning === "object") delete raw.reasoning.effort;
+    return { from: requested, to: "none", subagent };
+  }
+  if (!requested || !isCodexReasoningEffort(requested)) return null;
+  if (codexEffortRank(requested) <= codexEffortRank(resolved)) return null;
+  parsed.options.reasoning = resolved;
+  if (raw?.reasoning && typeof raw.reasoning === "object") raw.reasoning.effort = resolved;
+  return { from: requested, to: resolved, subagent };
+}