feat(router): add per-model pinned reasoning effort overrides

src/providers/derive.ts

@@ -32,6 +32,8 @@ export interface DerivedKeyLoginProvider {
   reasoningEfforts?: string[];
   modelReasoningEfforts?: Record<string, string[]>;
   modelDefaultReasoningEfforts?: Record<string, string>;
+  pinnedReasoningEffort?: string;
+  modelPinnedReasoningEfforts?: Record<string, string>;
   reasoningEffortMap?: Record<string, string>;
   modelReasoningEffortMap?: Record<string, Record<string, string>>;
   reasoningWireFormat?: OcxProviderConfig["reasoningWireFormat"];
@@ -124,7 +126,7 @@ function sameStringArray(left: readonly string[] | undefined, right: readonly st
 
 type DirectReasoningEffortOverrides = Pick<
   OcxProviderConfig,
-  "thinkingBudgetModels" | "modelReasoningEfforts" | "modelDefaultReasoningEfforts" | "modelReasoningEffortMap"
+  "thinkingBudgetModels" | "modelReasoningEfforts" | "modelDefaultReasoningEfforts" | "pinnedReasoningEffort" | "modelPinnedReasoningEfforts" | "modelReasoningEffortMap"
 >;
 
 function fillFoldedModelDefault<T>(
@@ -194,6 +196,15 @@ export function applyDirectReasoningEffortContracts(
       value => value,
     );
 
+    const pinnedEffort = entry.modelPinnedReasoningEfforts?.[model];
+    prov.modelPinnedReasoningEfforts = fillFoldedModelDefault(
+      prov.modelPinnedReasoningEfforts,
+      explicit.modelPinnedReasoningEfforts,
+      model,
+      pinnedEffort,
+      value => value,
+    );
+
     // An explicit empty model map masks any provider-wide aliases. Without it, a stale global
     // mapping such as xhigh -> max would win before the verified direct ladder can clamp it.
     prov.modelReasoningEffortMap = fillFoldedModelDefault(
@@ -239,6 +250,8 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.reasoningEfforts ? { reasoningEfforts: [...entry.reasoningEfforts] } : {}),
     ...(entry.modelReasoningEfforts ? { modelReasoningEfforts: cloneRecordOfArrays(entry.modelReasoningEfforts) } : {}),
     ...(entry.modelDefaultReasoningEfforts ? { modelDefaultReasoningEfforts: { ...entry.modelDefaultReasoningEfforts } } : {}),
+    ...(entry.pinnedReasoningEffort !== undefined ? { pinnedReasoningEffort: entry.pinnedReasoningEffort } : {}),
+    ...(entry.modelPinnedReasoningEfforts ? { modelPinnedReasoningEfforts: { ...entry.modelPinnedReasoningEfforts } } : {}),
     ...(entry.reasoningEffortMap ? { reasoningEffortMap: { ...entry.reasoningEffortMap } } : {}),
     ...(entry.modelReasoningEffortMap ? { modelReasoningEffortMap: cloneNestedRecord(entry.modelReasoningEffortMap) } : {}),
     ...(entry.reasoningWireFormat ? { reasoningWireFormat: entry.reasoningWireFormat } : {}),
@@ -299,6 +312,8 @@ export function deriveKeyLoginMap(): Record<string, DerivedKeyLoginProvider> {
       ...(entry.reasoningEfforts ? { reasoningEfforts: [...entry.reasoningEfforts] } : {}),
       ...(entry.modelReasoningEfforts ? { modelReasoningEfforts: cloneRecordOfArrays(entry.modelReasoningEfforts) } : {}),
       ...(entry.modelDefaultReasoningEfforts ? { modelDefaultReasoningEfforts: { ...entry.modelDefaultReasoningEfforts } } : {}),
+      ...(entry.pinnedReasoningEffort !== undefined ? { pinnedReasoningEffort: entry.pinnedReasoningEffort } : {}),
+      ...(entry.modelPinnedReasoningEfforts ? { modelPinnedReasoningEfforts: { ...entry.modelPinnedReasoningEfforts } } : {}),
       ...(entry.reasoningEffortMap ? { reasoningEffortMap: { ...entry.reasoningEffortMap } } : {}),
       ...(entry.modelReasoningEffortMap ? { modelReasoningEffortMap: cloneNestedRecord(entry.modelReasoningEffortMap) } : {}),
       ...(entry.reasoningWireFormat ? { reasoningWireFormat: entry.reasoningWireFormat } : {}),
@@ -466,6 +481,8 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
     thinkingBudgetModels: prov.thinkingBudgetModels,
     modelReasoningEfforts: prov.modelReasoningEfforts,
     modelDefaultReasoningEfforts: prov.modelDefaultReasoningEfforts,
+    pinnedReasoningEffort: prov.pinnedReasoningEffort,
+    modelPinnedReasoningEfforts: prov.modelPinnedReasoningEfforts,
     modelReasoningEffortMap: prov.modelReasoningEffortMap,
   };
   const seed = providerConfigSeed(entry);
@@ -492,6 +509,8 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   }
   if (!prov.modelReasoningEfforts && seed.modelReasoningEfforts) prov.modelReasoningEfforts = cloneRecordOfArrays(seed.modelReasoningEfforts);
   if (!prov.modelDefaultReasoningEfforts && seed.modelDefaultReasoningEfforts) prov.modelDefaultReasoningEfforts = { ...seed.modelDefaultReasoningEfforts };
+  if (!prov.pinnedReasoningEffort && seed.pinnedReasoningEffort) prov.pinnedReasoningEffort = seed.pinnedReasoningEffort;
+  if (!prov.modelPinnedReasoningEfforts && seed.modelPinnedReasoningEfforts) prov.modelPinnedReasoningEfforts = { ...seed.modelPinnedReasoningEfforts };
   if (!prov.reasoningEffortMap && seed.reasoningEffortMap) prov.reasoningEffortMap = { ...seed.reasoningEffortMap };
   if (!prov.modelReasoningEffortMap && seed.modelReasoningEffortMap) prov.modelReasoningEffortMap = cloneNestedRecord(seed.modelReasoningEffortMap);
   if (prov.reasoningWireFormat === undefined && seed.reasoningWireFormat !== undefined) prov.reasoningWireFormat = seed.reasoningWireFormat;

src/router.ts

@@ -315,6 +315,8 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
   const modelReasoningEffortMap = mergeNestedRecord(registryEntry.modelReasoningEffortMap, provider.modelReasoningEffortMap);
   const modelReasoningEfforts = mergeStringArrayRecord(registryEntry.modelReasoningEfforts, provider.modelReasoningEfforts);
   const modelDefaultReasoningEfforts = mergeRecordFill(registryEntry.modelDefaultReasoningEfforts, provider.modelDefaultReasoningEfforts);
+  const modelPinnedReasoningEfforts = mergeRecordFill(registryEntry.modelPinnedReasoningEfforts, provider.modelPinnedReasoningEfforts);
+  const pinnedReasoningEffort = provider.pinnedReasoningEffort ?? registryEntry.pinnedReasoningEffort;
   const modelContextWindows = providerName === OPENAI_API_PROVIDER_ID
     ? mergePositiveNumberCaps(registryEntry.modelContextWindows, provider.modelContextWindows)
     : mergeRecordFill(registryEntry.modelContextWindows, provider.modelContextWindows);
@@ -460,6 +462,8 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(modelSupportsVerbosity ? { modelSupportsVerbosity } : {}),
     ...(modelReasoningEfforts ? { modelReasoningEfforts } : {}),
     ...(modelDefaultReasoningEfforts ? { modelDefaultReasoningEfforts } : {}),
+    ...(pinnedReasoningEffort ? { pinnedReasoningEffort } : {}),
+    ...(modelPinnedReasoningEfforts ? { modelPinnedReasoningEfforts } : {}),
     ...(reasoningEffortMap ? { reasoningEffortMap } : {}),
     ...(modelReasoningEffortMap ? { modelReasoningEffortMap } : {}),
     ...(noVisionModels ? { noVisionModels } : {}),

src/server/chat-native.ts

@@ -6,6 +6,7 @@ import {
   collectChatCompletion,
   isChatCompletionsStreamError,
 } from "../chat/outbound";
+import { applyChatEffortCap, chatCollabSurface, effortCapAppliesTo, resolvePinnedEffort, supportedLadderFor } from "./effort-policy";
 import {
   classifyError,
   cyberPolicyErrorType,
@@ -144,9 +145,28 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
     return chatCompletionsErrorResponse(status, safeMessage, type, code);
   };
 
-  logCtx.requestedEffort = typeof options.chatBody.reasoning_effort === "string"
-    ? options.chatBody.reasoning_effort
-    : undefined;
+  const pinnedEffort = resolvePinnedEffort(route, requestedModel, config);
+  if (pinnedEffort) {
+    const from = typeof options.chatBody.reasoning_effort === "string" ? options.chatBody.reasoning_effort : undefined;
+    logCtx.requestedEffort = from ? `${from}->${pinnedEffort}` : pinnedEffort;
+    if (pinnedEffort === "none") {
+      delete options.chatBody.reasoning_effort;
+    } else {
+      options.chatBody.reasoning_effort = pinnedEffort;
+    }
+  } else {
+    logCtx.requestedEffort = typeof options.chatBody.reasoning_effort === "string"
+      ? options.chatBody.reasoning_effort
+      : undefined;
+  }
+
+  const surface = chatCollabSurface(options.chatBody);
+  if (effortCapAppliesTo(surface, req.headers, config)) {
+    const capped = applyChatEffortCap(options.chatBody, req.headers, config, supportedLadderFor(route));
+    if (capped) {
+      logCtx.requestedEffort = `${logCtx.requestedEffort ?? capped.from}->${capped.to}`;
+    }
+  }
   logCtx.requestedServiceTier = typeof options.chatBody.service_tier === "string"
     ? options.chatBody.service_tier
     : undefined;

src/server/effort-policy.ts

@@ -14,7 +14,7 @@
  */
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
 import { modelInList } from "../types";
-import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, modelRecordValue } from "../reasoning-effort";
+import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
 import { catalogModelEfforts } from "../codex/catalog";
 
 /**
@@ -188,3 +188,130 @@ export function applyEffortCap(
   if (raw?.reasoning && typeof raw.reasoning === "object") raw.reasoning.effort = resolved;
   return { from: requested, to: resolved, subagent };
 }
+
+/**
+ * Resolve any pinned reasoning effort configured for this model or provider.
+ * Priority order:
+ * 1. Provider model-specific pinned effort (`provider.modelPinnedReasoningEfforts[modelId]`)
+ * 2. Provider-wide pinned effort (`provider.pinnedReasoningEffort`)
+ * 3. Global config model-specific pinned effort (`config.modelPinnedEfforts[modelId]`)
+ *
+ * Returns undefined when no valid pinned effort tier is configured.
+ */
+export function resolvePinnedEffort(
+  route: { provider: OcxProviderConfig; modelId: string },
+  parsedModelId?: string,
+  config?: OcxConfig,
+): string | undefined {
+  const prov = route.provider;
+  const rawProvModel = modelRecordValue(prov.modelPinnedReasoningEfforts, route.modelId)
+    ?? (parsedModelId ? modelRecordValue(prov.modelPinnedReasoningEfforts, parsedModelId) : undefined);
+  if (rawProvModel && isDeclaredReasoningEffort(rawProvModel)) {
+    return rawProvModel;
+  }
+  if (prov.pinnedReasoningEffort && isDeclaredReasoningEffort(prov.pinnedReasoningEffort)) {
+    return prov.pinnedReasoningEffort;
+  }
+  if (config?.modelPinnedEfforts) {
+    const rawGlobal = modelRecordValue(config.modelPinnedEfforts, route.modelId)
+      ?? (parsedModelId ? modelRecordValue(config.modelPinnedEfforts, parsedModelId) : undefined);
+    if (rawGlobal && isDeclaredReasoningEffort(rawGlobal)) {
+      return rawGlobal;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Apply any pinned reasoning effort to the parsed request and raw body in BOTH shapes.
+ * Forces the reasoning effort regardless of what the caller sent, or when the caller sent none.
+ * Returns the rewrite transition { from, to } for logging, or null if no pinned effort applied.
+ */
+/**
+ * Detect collaboration surface for a native chat request body.
+ * Mirrors Responses collabSurface behavior across function and custom tool representations.
+ */
+export function chatCollabSurface(chatBody: Record<string, unknown>): "v1" | "v2" | null {
+  if (!Array.isArray(chatBody.tools)) return null;
+  let namespacedSpawn = false;
+  let flatSpawn = false;
+  let v1Only = false;
+  let v2Only = false;
+  for (const raw of chatBody.tools) {
+    if (!raw || typeof raw !== "object") continue;
+    const tool = raw as Record<string, unknown>;
+    let name = "";
+    let namespace: string | undefined = undefined;
+    if (tool.type === "function" && tool.function && typeof tool.function === "object") {
+      const fn = tool.function as Record<string, unknown>;
+      name = typeof fn.name === "string" ? fn.name : "";
+    } else if (tool.type === "custom" && tool.custom && typeof tool.custom === "object") {
+      const cust = tool.custom as Record<string, unknown>;
+      name = typeof cust.name === "string" ? cust.name : "";
+    } else if (typeof tool.name === "string") {
+      name = tool.name;
+    }
+    if (typeof tool.namespace === "string") namespace = tool.namespace;
+    if (name === "spawn_agent") {
+      if (namespace) namespacedSpawn = true;
+      else flatSpawn = true;
+    } else if (name === "send_input" || name === "resume_agent" || name === "close_agent") {
+      v1Only = true;
+    } else if (name === "send_message" || name === "followup_task" || name === "interrupt_agent" || name === "list_agents") {
+      v2Only = true;
+    }
+  }
+  if (!namespacedSpawn && !flatSpawn) return null;
+  if (namespacedSpawn && flatSpawn) return null;
+  if (v1Only && v2Only) return null;
+  if (v1Only) return "v1";
+  if (v2Only) return "v2";
+  return namespacedSpawn ? "v1" : "v2";
+}
+
+/**
+ * Apply effortCap to a native chat completions body when admitted by the collaboration gate.
+ */
+export function applyChatEffortCap(
+  chatBody: Record<string, unknown>,
+  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 = typeof chatBody.reasoning_effort === "string" ? chatBody.reasoning_effort : undefined;
+  if (resolved === null) {
+    if (!requested) return null;
+    delete chatBody.reasoning_effort;
+    return { from: requested, to: "none", subagent };
+  }
+  if (!requested || !isCodexReasoningEffort(requested)) return null;
+  if (codexEffortRank(requested) <= codexEffortRank(resolved)) return null;
+  chatBody.reasoning_effort = resolved;
+  return { from: requested, to: resolved, subagent };
+}
+
+export function applyPinnedEffort(
+  parsed: OcxParsedRequest,
+  route: { provider: OcxProviderConfig; modelId: string },
+  config?: OcxConfig,
+): { from: string | undefined; to: string } | null {
+  const pinned = resolvePinnedEffort(route, parsed.modelId, config);
+  if (!pinned) return null;
+  const requested = parsed.options.reasoning;
+  const raw = parsed._rawBody as { reasoning?: { effort?: string } } | undefined;
+  const targetEffort = pinned === "none" ? undefined : pinned;
+  parsed.options.reasoning = targetEffort;
+  if (targetEffort) {
+    if (raw && typeof raw === "object") {
+      if (!raw.reasoning || typeof raw.reasoning !== "object") raw.reasoning = {};
+      raw.reasoning.effort = targetEffort;
+    }
+  } else if (raw?.reasoning && typeof raw.reasoning === "object") {
+    delete raw.reasoning.effort;
+  }
+  return { from: requested, to: pinned };
+}

src/server/management/agent-settings-routes.ts

@@ -602,13 +602,14 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     return jsonResponse({
       effortCap: config.effortCap ?? null,
       subagentEffortCap: config.subagentEffortCap ?? null,
+      modelPinnedEfforts: config.modelPinnedEfforts ?? {},
       efforts: CODEX_REASONING_LEVELS.map(l => l.effort),
     });
   }
   if (url.pathname === "/api/effort-caps" && req.method === "PUT") {
-    let body: { effortCap?: unknown; subagentEffortCap?: unknown };
+    let body: { effortCap?: unknown; subagentEffortCap?: unknown; modelPinnedEfforts?: unknown };
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
-    const { isCodexReasoningEffort } = await import("../../reasoning-effort");
+    const { isCodexReasoningEffort, isDeclaredReasoningEffort } = await import("../../reasoning-effort");
     for (const key of ["effortCap", "subagentEffortCap"] as const) {
       if (!(key in body)) continue;
       const value = body[key];
@@ -618,8 +619,40 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
       config[key] = value;
     }
+    if ("modelPinnedEfforts" in body) {
+      const val = body.modelPinnedEfforts;
+      if (val === null || val === undefined) {
+        deleteConfigTopLevelKey(config, "modelPinnedEfforts");
+      } else if (typeof val === "object" && !Array.isArray(val)) {
+        const efforts: Record<string, string> = { ...(config.modelPinnedEfforts ?? {}) };
+        for (const [m, eff] of Object.entries(val as Record<string, unknown>)) {
+          if (!m.trim()) return jsonResponse({ error: "modelPinnedEfforts keys must be nonblank model ids" }, 400);
+          if (eff === null || eff === "" || eff === undefined) {
+            delete efforts[m.trim()];
+            continue;
+          }
+          if (typeof eff === "string" && isDeclaredReasoningEffort(eff)) {
+            efforts[m.trim()] = eff;
+          } else {
+            return jsonResponse({ error: `unknown reasoning effort "${String(eff)}" for model "${m}"` }, 400);
+          }
+        }
+        if (Object.keys(efforts).length > 0) {
+          config.modelPinnedEfforts = efforts;
+        } else {
+          deleteConfigTopLevelKey(config, "modelPinnedEfforts");
+        }
+      } else {
+        return jsonResponse({ error: "modelPinnedEfforts must be a plain object or null" }, 400);
+      }
+    }
     saveConfigPreservingClaudeCode(config);
-    return jsonResponse({ ok: true, effortCap: config.effortCap ?? null, subagentEffortCap: config.subagentEffortCap ?? null });
+    return jsonResponse({
+      ok: true,
+      effortCap: config.effortCap ?? null,
+      subagentEffortCap: config.subagentEffortCap ?? null,
+      ...(config.modelPinnedEfforts ? { modelPinnedEfforts: config.modelPinnedEfforts } : {}),
+    });
   }
 
   // Subagent model picker: which ≤5 routed models Codex's spawn_agent advertises (it shows the