@yansigit/opencodex 2.36.1-dev.20260829.35 → 2.36.1-dev.20260829.39

package/src/generated/compatibility-version.json

@@ -10,7 +10,7 @@
     },
     {
       "path": "package.json",
-      "sha256": "237debdd8a2a62e40e44d7e5f1ccd6cd641abe3cb694d2edb60fd004c698e4e7"
+      "sha256": "0056c7ad8f06271be7aceee8ea055ad817e2aeeb3ede46fcf21b48e812c1c420"
     },
     {
       "path": "scripts/model-metadata.source.json",
@@ -730,7 +730,7 @@
     },
     {
       "path": "src/codex/app-server-processes.ts",
-      "sha256": "605e11ba25a31e7d6a2bda30325794bfee9829b6c617c2865e90e6e4ed92a00a"
+      "sha256": "00e00faf3a032c13db509e4b38c3c7dc9e1a7b532a1b48dc34d7d5de10d80615"
     },
     {
       "path": "src/codex/app-server-restart-service.ts",
@@ -910,7 +910,7 @@
     },
     {
       "path": "src/codex/internal/catalog-writer.ts",
-      "sha256": "a38a3b3b0735997cac608eb0f0a2147e15d5d3a2bf8bbd73f3bb4b538fc47517"
+      "sha256": "d59f218683c102f5f629ee092a0076deeefb01cc8a20ecde13d197d3ec4a034b"
     },
     {
       "path": "src/codex/internal/history-writer.ts",
@@ -1098,7 +1098,7 @@
     },
     {
       "path": "src/codex/subagent-defaults.ts",
-      "sha256": "66ac781355642d64e6926676f05d8e44f68bc27cc26c2edd66c9e0ffd19d5613"
+      "sha256": "08e3efa192430891d9d221d41e5124177c2c03656e3eb832087fdfb778a7703e"
     },
     {
       "path": "src/codex/subagent-model-fallback.ts",
@@ -1106,7 +1106,7 @@
     },
     {
       "path": "src/codex/sync.ts",
-      "sha256": "faceb0d8b621e6471b34f9e1d9519d1feb36a33d39ad984fc3acb5748bf52a7b"
+      "sha256": "b2b413f985c058024f5cf0714255ab8b3f74858d159631d22201c237c9aea134"
     },
     {
       "path": "src/codex/transition-state.ts",
@@ -2662,7 +2662,7 @@
     },
     {
       "path": "src/server/effort-policy.ts",
-      "sha256": "fc944973196eb482e4fe0310a64e46d69455d9f9bffb984a13d94581ff5bcff9"
+      "sha256": "d00bd3a42975adec4c62560d57e564da28e4fc7476cc57fea7103f3d61080fc3"
     },
     {
       "path": "src/server/github-copilot-responses-repair.ts",
@@ -2682,7 +2682,7 @@
     },
     {
       "path": "src/server/index.ts",
-      "sha256": "571ee5edbbff9311f3c5bf044c5330b03b8defc47dd6c05ea118ece2b91c1b3d"
+      "sha256": "e39a7d1b9812bdf91677f27be4b4ef0a486015170f41e69fb3d8c330970f0aba"
     },
     {
       "path": "src/server/lifecycle.ts",
@@ -2710,7 +2710,7 @@
     },
     {
       "path": "src/server/management/agent-settings-routes.ts",
-      "sha256": "223da28c5ed1951dbaf014ebac9e26c8035d14884b50b7985294c0d39e1c0ab8"
+      "sha256": "2ba31a9adb7ba798a7a9fdeada3a2430ad2497205ec3671f4c3a5bfbab68f8c5"
     },
     {
       "path": "src/server/management/api-access.ts",
@@ -2874,7 +2874,7 @@
     },
     {
       "path": "src/server/request-log.ts",
-      "sha256": "a8980d727760364b174ec8a2ac020d482f5fcf58371a4557f806e2b487355542"
+      "sha256": "b05d8d7b84f9cc6bf7cdd003aae7b2ef3791eed9353ee9441f10b87dd34b1621"
     },
     {
       "path": "src/server/responses-custom-tool-repair.ts",
@@ -2934,7 +2934,7 @@
     },
     {
       "path": "src/server/responses/collaboration.ts",
-      "sha256": "ce48f612fd22f4bdff7198089411aeabbd43228130eeaa464e5705a73a814237"
+      "sha256": "c06f21efd00814eb1021b73e4fe16e693a93205768f8f1a55c63e854e657075d"
     },
     {
       "path": "src/server/responses/combo-stream-preflight.ts",
@@ -2946,7 +2946,7 @@
     },
     {
       "path": "src/server/responses/core.ts",
-      "sha256": "90ce7232996139a594f4055155db1cba61692f680c85e9d6d5601a0657c12c49"
+      "sha256": "ff08c82f4289d3227725566fd7637e8f7b382bb0a1f303846f9c2da9c7889acf"
     },
     {
       "path": "src/server/responses/empty-completion-guard.ts",
@@ -3034,7 +3034,7 @@
     },
     {
       "path": "src/server/ws-bridge.ts",
-      "sha256": "515a150f3b1d71f29efe566629dea2056b7562f669c0f98464cf9000577541b3"
+      "sha256": "0f7ea03225ddd992fad14dab1dda99a3890a380061f99f0e94fb05efb33e421f"
     },
     {
       "path": "src/service-manager-probe.ts",
@@ -3250,7 +3250,7 @@
     },
     {
       "path": "src/usage/log.ts",
-      "sha256": "2178aa1e4466a1bfa96806a1d4348ae0e8fc717d418c9f2f76dd37466d3a2013"
+      "sha256": "a559008076a3d43365d4aa87f7d1b24c939822d915c143f7221cd3b915dc1f96"
     },
     {
       "path": "src/usage/summary.ts",

package/src/server/effort-policy.ts

@@ -17,6 +17,43 @@ import { modelInList } from "../types";
 import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, modelRecordValue } from "../reasoning-effort";
 import { catalogModelEfforts } from "../codex/catalog";
 
+export type AgentKind = "main" | "subagent" | "internal";
+
+type MarkerValue = { value: string; valid: boolean } | undefined;
+
+function turnMetadataMarker(headers: Headers): MarkerValue {
+  const raw = headers.get("x-codex-turn-metadata");
+  if (raw === null) return undefined;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { value: "", valid: false };
+    const metadata = parsed as Record<string, unknown>;
+    if (!("subagent_kind" in metadata)) return undefined;
+    const value = metadata.subagent_kind;
+    if (typeof value !== "string" || value.trim().length === 0) return { value: "", valid: false };
+    return { value, valid: true };
+  } catch {
+    return { value: "", valid: false };
+  }
+}
+
+/** Classify Responses-origin headers without retaining any marker values. */
+export function classifyAgentKind(headers: Headers, traffic?: "responses"): AgentKind | undefined {
+  const headerRaw = headers.get("x-openai-subagent");
+  const headerMarker: MarkerValue = headerRaw === null
+    ? undefined
+    : { value: headerRaw, valid: headerRaw.length > 0 };
+  const metadataMarker = turnMetadataMarker(headers);
+
+  // A genuine spawn marker is authoritative even when a sibling marker is stale or malformed.
+  if (headerMarker?.value === "collab_spawn" || metadataMarker?.value === "thread_spawn") return "subagent";
+  const present = [headerMarker, metadataMarker].filter((marker): marker is NonNullable<MarkerValue> => marker !== undefined);
+  if (present.some(marker => !marker.valid)) return undefined;
+  if (present.length > 1 && present[0].value !== present[1].value) return undefined;
+  if (present.length > 0) return "internal";
+  return traffic === "responses" ? "main" : undefined;
+}
+
 /**
  * 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
@@ -30,16 +67,8 @@ import { catalogModelEfforts } from "../codex/catalog";
  * 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;
-  }
+export function isThreadSpawnRequest(headers: Headers, agentKind?: AgentKind): boolean {
+  return (agentKind ?? classifyAgentKind(headers)) === "subagent";
 }
 
 /** The effective ceiling for this turn, or undefined when no configured cap applies. */
@@ -73,10 +102,11 @@ export function effortCapAppliesTo(
   headers: Headers,
   config: OcxConfig,
   compaction = false,
+  agentKind?: AgentKind,
 ): boolean {
   if (compaction) return false;
   if (config.multiAgentMode === "v1") return false;
-  return surface === "v2" || isThreadSpawnRequest(headers);
+  return surface === "v2" || isThreadSpawnRequest(headers, agentKind);
 }
 
 /**
@@ -185,8 +215,9 @@ export function applyEffortCap(
   headers: Headers,
   config: OcxConfig,
   supported?: readonly string[] | undefined,
+  agentKind?: AgentKind,
 ): { from: string; to: string; subagent: boolean } | null {
-  const subagent = isThreadSpawnRequest(headers);
+  const subagent = isThreadSpawnRequest(headers, agentKind);
   const cap = effortCapFor(config, subagent);
   if (!cap) return null;
   const resolved = resolveCappedEffort(cap, supported);

package/src/server/index.ts

@@ -113,6 +113,7 @@ import {
   type RequestLogEntry,
 } from "./request-log";
 import { sessionLaneIdFromRequest } from "./request-log-conversation";
+import { classifyAgentKind } from "./effort-policy";
 export {
   addFinalRequestLog,
   filterRequestLogs,
@@ -972,12 +973,14 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         // binding. They are the same object for the public listener, but the
         // unauthenticated loopback listener (#1102) is a second Bun.serve, and handing its
         // request to the public server's upgrade would fail or cross sockets.
+        const agentKind = classifyAgentKind(req.headers, "responses");
         if (requestServer.upgrade(req, {
           data: buildResponsesWsData(
             selectForwardHeaders(req.headers),
             admission,
             websocketLease,
             sessionLaneIdFromRequest(req.headers),
+            agentKind,
           ),
         })) return undefined as unknown as Response;
         websocketLease.release();
@@ -1395,6 +1398,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
           provider: "unknown",
           ...admissionFields(admission),
           inboundProtocol: "responses",
+          agentKind: classifyAgentKind(req.headers, "responses"),
         };
         return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
           let response: Response;
@@ -1508,6 +1512,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
           provider: "unknown",
           ...admissionFields(admission),
           inboundProtocol: "responses",
+          agentKind: classifyAgentKind(req.headers, "responses"),
         };
         if (req.headers.get("x-opencodex-grok") === "1") logCtx.surface = "grok";
         let logged = false;
@@ -1857,6 +1862,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             provider: "unknown",
             ...(wsAdmission ? admissionFields(wsAdmission) : {}),
             inboundProtocol: "responses",
+            agentKind: ws.data.agentKind,
           };
           let logged = false;
           const finalizeLog = (

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

@@ -797,6 +797,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     const disabled = new Set(config.disabledModels ?? []);
     const { listCatalogNativeSlugs } = await import("../../codex/catalog");
     const { CODEX_REASONING_LEVELS } = await import("../../reasoning-effort");
+    const { resolveNativeDefaultState } = await import("../../codex/subagent-defaults");
     const nativeModels = listCatalogNativeSlugs()
       .filter(slug => !disabled.has(slug))
       .map(slug => ({ provider: "openai", model: slug, namespaced: slug }));
@@ -811,6 +812,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       model: config.injectionModel ?? null,
       effort: config.injectionEffort ?? null,
       prompt: config.injectionPrompt ?? null,
+      nativeDefaultState: await resolveNativeDefaultState(config),
       efforts: CODEX_REASONING_LEVELS.map(l => l.effort),
       available: [...nativeModels, ...routedModels],
     });

package/src/server/request-log.ts

@@ -17,6 +17,7 @@ import type { AdapterTierMetadata } from "../providers/fastwire";
 import { redactSecretString, sanitizeLogMetadataString } from "../lib/redact";
 import {
   appendUsageEntry,
+  isKnownAgentKind,
   isKnownAdmissionKind,
   isKnownInboundProtocol,
   isKnownUsageSurface,
@@ -31,6 +32,7 @@ import {
   type PersistedUsageEntry,
   type UsageStatus,
 } from "../usage/log";
+import type { AgentKind } from "./effort-policy";
 import {
   appendUsageDebug,
   isUsageDebugEnabled,
@@ -63,6 +65,7 @@ export interface RequestLogContext {
    *  product: widening that enum would merge Responses and Chat Completions,
    *  since both leave it undefined. */
   inboundProtocol?: "responses" | "chat" | "messages";
+  agentKind?: AgentKind;
   /** Stable non-PII Codex Pool account identity for durable usage attribution. */
   accountLogLabel?: string;
   requestedModel?: string;
@@ -143,6 +146,7 @@ export interface RequestLogEntry {
    *  product: widening that enum would merge Responses and Chat Completions,
    *  since both leave it undefined. */
   inboundProtocol?: "responses" | "chat" | "messages";
+  agentKind?: AgentKind;
   accountLogLabel?: string;
   /** Best-effort chat/session correlation for Logs grouping (#330). */
   conversationId?: string;
@@ -256,6 +260,7 @@ export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): R
     timestamp: entry.timestamp,
     model: entry.model,
     provider: entry.provider,
+    ...(isKnownAgentKind(entry.agentKind) ? { agentKind: entry.agentKind } : {}),
     ...(entry.firstOutputMs !== undefined ? { firstOutputMs: entry.firstOutputMs } : {}),
     ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
     ...(entry.conversationId ? { conversationId: entry.conversationId } : {}),
@@ -378,6 +383,7 @@ export function addRequestLog(entry: RequestLogEntry) {
       ...(entry.apiKeyId ? { apiKeyId: entry.apiKeyId } : {}),
       ...(isKnownAdmissionKind(entry.admissionKind) ? { admissionKind: entry.admissionKind } : {}),
       ...(isKnownInboundProtocol(entry.inboundProtocol) ? { inboundProtocol: entry.inboundProtocol } : {}),
+      ...(isKnownAgentKind(entry.agentKind) ? { agentKind: entry.agentKind } : {}),
       ...(isPersistableAccountLogLabel(entry.accountLogLabel)
         ? { accountLogLabel: entry.accountLogLabel }
         : {}),
@@ -970,6 +976,7 @@ export function addFinalRequestLog(
     ...(logCtx.apiKeyId ? { apiKeyId: logCtx.apiKeyId } : {}),
     ...(logCtx.admissionKind ? { admissionKind: logCtx.admissionKind } : {}),
     ...(logCtx.inboundProtocol ? { inboundProtocol: logCtx.inboundProtocol } : {}),
+    ...(logCtx.agentKind ? { agentKind: logCtx.agentKind } : {}),
     ...(isPersistableAccountLogLabel(logCtx.accountLogLabel)
       ? { accountLogLabel: logCtx.accountLogLabel }
       : {}),

package/src/server/responses/collaboration.ts

@@ -77,6 +77,7 @@ import { registerTurn, trackStreamLifetime, unregisterTurn } from "../lifecycle"
 import { redactSecretString } from "../../lib/redact";
 import { readBoundedResponseBody } from "../../lib/bounded-body";
 import { supportedLadderFor } from "../effort-policy";
+import { resolveNativeDefaultState, type NativeDefaultState } from "../../codex/subagent-defaults";
 import {
   beginRequestAttempt,
   catalogModelSupportsServiceTier,
@@ -216,11 +217,18 @@ export interface MultiAgentGuidanceOptions {
   subagentModelFallback?: string[];
   injectionPrompt?: string;
   subagentRoles?: OcxSubagentRole[];
+  nativeDefaultState?: NativeDefaultState;
+  syncCodexSubagentDefaults?: boolean;
 }
 
 
 
 export interface MultiAgentGuidanceDeps {
+  resolveNativeDefaultState?: (config: {
+    injectionModel?: string;
+    injectionEffort?: string;
+    syncCodexSubagentDefaults?: boolean;
+  }) => NativeDefaultState | Promise<NativeDefaultState>;
   resolveEffectiveSubagentRoster?: (
     configuredModels: readonly string[],
     surface: SpawnAgentSurface,
@@ -308,6 +316,8 @@ export async function multiAgentGuidanceText(
     subagentModelFallback,
     injectionPrompt,
     subagentRoles,
+    nativeDefaultState: configuredNativeDefaultState,
+    syncCodexSubagentDefaults,
   } = options;
   const activeAccountNamespace = codexAccountNamespace?.length
     ? codexAccountNamespace
@@ -340,6 +350,10 @@ export async function multiAgentGuidanceText(
     if (catalogState.state === "stale" || catalogState.state === "unknown") {
       return null;
     }
+    const nativeDefaultState = configuredNativeDefaultState
+      ?? await (deps.resolveNativeDefaultState ?? resolveNativeDefaultState)({
+        injectionModel, injectionEffort, syncCodexSubagentDefaults,
+      });
     // codex-rs supplies the Proactive text on v2; the proxy only adds model-designation
     // guidance, and only when there is something concrete to designate: a configured
     // injectionModel and/or a roster entry that resolves in the injected catalog.
@@ -417,7 +431,7 @@ export async function multiAgentGuidanceText(
       // fallback only for explicit routed/account-qualified ids.
       const promptModel = preferred?.model
         ?? (injectionModel?.includes("/") ? injectionModel : undefined);
-      return `<multi_agent_mode>${applyInjectionPlaceholders(injectionPrompt, promptModel, injectionEffort, roster, fallbackGuidance, customRolesText)}</multi_agent_mode>`;
+      return `<multi_agent_mode>${applyInjectionPlaceholders(injectionPrompt, promptModel, injectionEffort, roster, fallbackGuidance, customRolesText, nativeDefaultState)}</multi_agent_mode>`;
     }
     if (!preferred && roster === "" && fallbackGuidance === "" && customRolesText === "") return null;
     const preamble = "When the active spawn_agent tool supports optional \"model\" or \"reasoning_effort\" overrides, "
@@ -425,13 +439,14 @@ export async function multiAgentGuidanceText(
       + "When setting either override, set fork_turns to \"none\" "
       + "(or a positive turn count such as \"3\"; full-history forks reject overrides) "
       + "and make the task message self-contained. "
-      + "When specifying model overrides, omit agent_type or use \"worker\" to prevent enforcing locked default models. "
+      + "When specifying model overrides, preserve any caller-provided agent_type; do not replace it with \"worker\". "
       + "Subagent exec runs in a pure V8 isolate without require('fs'); "
       + "escape nested template literals in tools.apply_patch to prevent JavaScript syntax errors (e.g., write \\` and \\\${var}).";
     let preferredText = "";
     if (preferred) {
       preferredText = ` Preferred sub-agent: model "${preferred.model}"`
         + (injectionEffort ? `, reasoning_effort "${injectionEffort}"` : "")
+        + `; nativeDefaultState: ${nativeDefaultState}.`
         + " — use it unless the user names another.";
     }
     const specialist = (catalog: string): string =>
@@ -465,13 +480,14 @@ export async function multiAgentGuidanceText(
 
 export const V2_GUIDANCE_CHAR_BUDGET = 1200;
 
-export function applyInjectionPlaceholders(prompt: string, model?: string, effort?: string, roster?: string, fallback?: string, roles?: string): string {
+export function applyInjectionPlaceholders(prompt: string, model?: string, effort?: string, roster?: string, fallback?: string, roles?: string, nativeDefaultState?: NativeDefaultState): string {
   return prompt
     .replaceAll("{{model}}", model ?? "")
     .replaceAll("{{effort}}", effort ?? "")
     .replaceAll("{{roster}}", roster ?? "")
     .replaceAll("{{fallback}}", fallback ?? "")
-    .replaceAll("{{roles}}", roles ?? "");
+    .replaceAll("{{roles}}", roles ?? "")
+    .replaceAll("{{nativeDefaultState}}", nativeDefaultState ?? "");
 }
 
 

package/src/server/responses/core.ts

@@ -1879,6 +1879,7 @@ async function applyFinalRouteRequestNormalization(args: {
       subagentModelFallback: config.subagentModelFallback,
       injectionPrompt: config.injectionPrompt,
       subagentRoles: config.subagentRoles,
+      syncCodexSubagentDefaults: config.syncCodexSubagentDefaults === true,
     });
     if (guidance) {
       injectDeveloperMessage(parsed, guidance);
@@ -1893,8 +1894,8 @@ async function applyFinalRouteRequestNormalization(args: {
   {
     const { applyEffortCap, effortCapAppliesTo, supportedLadderFor } = await import("../effort-policy");
     const surface = collabSurface(parsed);
-    if (effortCapAppliesTo(surface, req.headers, config, parsed._compactionRequest === true)) {
-      const capped = applyEffortCap(parsed, req.headers, config, supportedLadderFor(route));
+    if (effortCapAppliesTo(surface, req.headers, config, parsed._compactionRequest === true, logCtx.agentKind)) {
+      const capped = applyEffortCap(parsed, req.headers, config, supportedLadderFor(route), logCtx.agentKind);
       if (capped) {
         logCtx.requestedEffort = `${capped.from}->${capped.to}`;
         if (isInjectionDebugEnabled()) {
@@ -2057,6 +2058,7 @@ export async function handleComboResponses(
     const childLog: RequestLogContext = {
       model: pick.target.model,
       provider: pick.target.provider,
+      ...(logCtx.agentKind ? { agentKind: logCtx.agentKind } : {}),
       ...(logCtx.conversationId ? { conversationId: logCtx.conversationId } : {}),
       ...(logCtx.surface ? { surface: logCtx.surface } : {}),
     };
@@ -2613,7 +2615,7 @@ async function handleResponsesInner(
     && isMultiAgentV2Enabled()
     && isCanonicalOpenAiForwardProvider(route.provider)
     && collabSurface(parsed) === "v2"
-    && !isThreadSpawnRequest(req.headers)
+    && !isThreadSpawnRequest(req.headers, logCtx.agentKind)
     && !req.headers.has("x-openai-subagent")
     && !options.comboAttempt
     && parsed._compactionRequest !== true
@@ -2632,7 +2634,7 @@ async function handleResponsesInner(
   // Exact account selectors are isolated from Pool-wide quota work. A canonical replay miss must
   // also fail closed without polling quota upstream. Cached fallback state can still select a
   // provider with native continuation support below.
-  const threadSpawn = isThreadSpawnRequest(req.headers);
+  const threadSpawn = isThreadSpawnRequest(req.headers, logCtx.agentKind);
   const initialSubagentFallbackChain = threadSpawn && !options.comboAttempt
     ? resolveSubagentFallbackChain(parsed, config)
     : null;

package/src/server/ws-bridge.ts

@@ -7,6 +7,7 @@ import type { ResponsesTerminalStatus } from "../bridge";
 import type { DataPlaneAdmission } from "./auth-cors";
 import type { AdmissionLease, AdmissionReservation } from "../lib/admission";
 import { BoundedSseFrameBuffer } from "./sse-frame-buffer";
+import { classifyAgentKind, type AgentKind } from "./effort-policy";
 
 const OPEN = 1;
 type ResponsesTerminalReporter = (status: ResponsesTerminalStatus) => void;
@@ -23,6 +24,7 @@ const SAFE_RESPONSE_HEADER_EXACT = new Set([
 
 export interface WsData {
   headers?: Headers; // base inbound forward headers only; per-turn auth refresh injects current pool tokens
+  agentKind?: AgentKind;
   /**
    * Resolved once at the handshake. Auth is handshake-time only on this path, so
    * the per-frame log contexts have no request headers left to re-resolve from.
@@ -67,11 +69,14 @@ export function buildResponsesWsData(
   admission: DataPlaneAdmission,
   admissionLease?: AdmissionReservation<ServerWebSocket<WsData>>,
   sessionLaneId?: string,
+  agentKind?: AgentKind,
 ): WsData {
   // Auth is handshake-time only on this path: the per-frame contexts have no
   // request headers left to re-resolve from, so the decision rides along here.
+  const resolvedAgentKind = arguments.length >= 5 ? agentKind : classifyAgentKind(headers, "responses");
   return {
     headers,
+    agentKind: resolvedAgentKind,
     admission,
     ...(admissionLease ? { admissionLease } : {}),
     ...(sessionLaneId ? { sessionLaneId } : {}),

package/src/usage/log.ts

@@ -9,6 +9,7 @@ import { usageDisplayTotalTokens } from "./totals";
 import type { AttemptTierOutcome, OcxUsage } from "../types";
 import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
 import { CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
+import type { AgentKind } from "../server/effort-policy";
 
 export type UsageStatus = "reported" | "unreported" | "unsupported" | "estimated";
 export type CodexUsageAccountLogLabel = "main" | `p${string}`;
@@ -80,6 +81,8 @@ export interface PersistedUsageAttempt {
 }
 
 export interface PersistedUsageEntry {
+  /** Responses request origin; absent for unrelated traffic and old rows. */
+  agentKind?: AgentKind;
   requestedAlias?: string;
   requestId: string;
   timestamp: number;
@@ -163,6 +166,11 @@ const KNOWN_ADMISSION_KINDS = new Set<NonNullable<PersistedUsageEntry["admission
 const KNOWN_INBOUND_PROTOCOLS = new Set<NonNullable<PersistedUsageEntry["inboundProtocol"]>>([
   "responses", "chat", "messages",
 ]);
+const KNOWN_AGENT_KINDS = new Set<AgentKind>(["main", "subagent", "internal"]);
+
+export function isKnownAgentKind(value: unknown): value is AgentKind {
+  return typeof value === "string" && KNOWN_AGENT_KINDS.has(value as AgentKind);
+}
 
 /** Same closed-set discipline as `isKnownUsageSurface`: an old or corrupted row
  *  carrying an unexpected value drops the field instead of poisoning the enum. */
@@ -454,6 +462,7 @@ function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
     timestamp: entry.timestamp,
     provider: entry.provider,
     model: entry.model,
+    ...(isKnownAgentKind(entry.agentKind) ? { agentKind: entry.agentKind } : {}),
     ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
     ...(typeof entry.apiKeyId === "string" && entry.apiKeyId.trim()
       // Deliberately NOT capped. `capMetadataString` protects free-form metadata