@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/advisor/state.ts

@@ -0,0 +1,369 @@
+import { createHash } from "node:crypto";
+import { advisorResultIsAdvice } from "./context";
+
+/**
+ * Conversation- and task-scoped advisor state.
+ *
+ * Three scopes, deliberately separate:
+ *
+ * 1. REQUEST-scoped state lives in the per-request plan closure (see runtime.ts) — consultation
+ *    count, dedup fingerprints, the preflight flag. Born and dies with one request.
+ *
+ * 2. TASK-scoped preflight ledger (this file): a bounded, process-local claim table that makes
+ *    "at most one automatic consultation per task" atomic across concurrent requests. A claim
+ *    requires a STABLE conversation identity plus the current task boundary; a client that sends
+ *    no identity never enters this ledger (see `advisorLedgerKey`) and therefore fails open —
+ *    it may be consulted once per request rather than risk two independent tasks suppressing
+ *    each other through a shared guess.
+ *
+ * 3. PROVENANCE, split by authority:
+ *    - MANUAL advice is verifiable history: a `toolResult` whose `toolName` is the synthetic
+ *      advisor tool and whose content parses as a runtime-written advice object. Ordinary tool
+ *      output, developer text, user text, and failure notices can never match it. Bytes inside
+ *      the quoted advice field cannot change the runtime-owned status.
+ *    - AUTOMATIC preflight dedup is NOT decided from history at all. The developer transport
+ *      envelope labels the payload for the worker; any client could echo or forge such a message,
+ *      so the ledger below is the authoritative source for "this task was already consulted" —
+ *      `success`, `inflight` and `cooldown` states. A conversation with no stable identity gets
+ *      no ledger and therefore fails open (at most one extra attempt). A forged marker or a
+ *      forged developer message cannot suppress the policy.
+ *
+ * Ledger entries are plain state records — no message bodies, no credentials. Every state is
+ * bounded by entry count and its own TTL.
+ */
+
+/** Long-lived success suppression: the task lifetime approximation (also the ledger TTL cap). */
+export const ADVISOR_SUCCESS_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Failure cooldown. One minute is the repository's standing minute-scale unit (tray polling,
+ * subagent availability polling); it turns a transient 503 into a short pause instead of
+ * silencing the policy for the rest of the coding session.
+ */
+export const ADVISOR_FAILURE_COOLDOWN_MS = 60 * 1000;
+/**
+ * In-flight claim expiry. Longer than the largest configurable consultation timeout (600s
+ * upper bound on `advisor.timeoutMs`, default 120s) so a slow-but-alive consultation is never
+ * mistaken for a wedged one, while a crashed claim cannot block a task forever.
+ */
+export const ADVISOR_INFLIGHT_TTL_MS = 10 * 60 * 1000;
+
+const MAX_ENTRIES = 512;
+
+export type AdvisorClaimState =
+  /** The caller now owns the consultation for this task. */
+  | "claimed"
+  /** Another request for the same task is consulting right now. */
+  | "inflight"
+  /** This task already received advice; suppression holds until the success TTL expires. */
+  | "complete"
+  /** A recent consultation failed; suppression holds for the short failure cooldown. */
+  | "cooldown"
+  /**
+   * The ledger is full of live claims and granted nothing. Fail-open: the worker continues
+   * without a new automatic consultation rather than evicting a claim that is still running.
+   */
+  | "saturated";
+
+/**
+ * The result of a claim attempt. `token` identifies THIS claim and is present only on
+ * `"claimed"`; settlement must present it, so a slow consultation whose in-flight entry expired
+ * cannot settle the successor claim that took its place.
+ */
+export interface AdvisorClaim {
+  state: AdvisorClaimState;
+  token?: string;
+}
+
+interface LedgerEntry {
+  state: "inflight" | "success" | "failed";
+  at: number;
+  /** Present on in-flight entries: which claim owns this entry. */
+  token?: string;
+}
+
+export interface AdvisorPreflightLedger {
+  /**
+   * Atomically try to own the consultation for a task key. Returns `claimed` exactly once per
+   * task (with the ownership token) until a matching settlement releases it, so two concurrent
+   * requests cannot both consult.
+   */
+  claim(key: string, now?: number): AdvisorClaim;
+  /**
+   * Settle a claim the caller owns. A settlement whose token does not match the current entry
+   * is a no-op: the entry now belongs to a successor claim (the caller's in-flight window
+   * expired), and it must not be able to erase or overwrite that successor's state.
+   */
+  complete(key: string, token: string, now?: number): void;
+  fail(key: string, token: string, now?: number): void;
+  release(key: string, token: string, now?: number): void;
+  /**
+   * Fact, not settlement: this task received advice (used by a successful MANUAL consultation,
+   * which owns no preflight claim). Records success regardless of the current entry, because
+   * "the task was advised" is true whichever consultation produced it.
+   */
+  markAdvised(key: string, now?: number): void;
+  /** Test/observability seam: current entry count. */
+  size(): number;
+}
+
+export function createAdvisorPreflightLedger(): AdvisorPreflightLedger {
+  const entries = new Map<string, LedgerEntry>();
+  let claimSequence = 0;
+
+  const isExpired = (entry: LedgerEntry, now: number): boolean => {
+    const ttl = entry.state === "success"
+      ? ADVISOR_SUCCESS_TTL_MS
+      : entry.state === "failed"
+        ? ADVISOR_FAILURE_COOLDOWN_MS
+        : ADVISOR_INFLIGHT_TTL_MS;
+    return now - entry.at > ttl;
+  };
+
+  /**
+   * Make room for ONE new claim without ever evicting a live in-flight entry, because that entry
+   * is the only thing preventing a second automatic consultation for its task. Order: expired
+   * entries first, then settled ones (success before failure), oldest first. Returns false when
+   * every entry is a live claim — the caller then reports `saturated` instead of breaking the
+   * "at most one in-flight consultation per task" guarantee.
+   */
+  const makeRoom = (now: number): boolean => {
+    if (entries.size < MAX_ENTRIES) return true;
+    for (const [key, entry] of entries) {
+      if (isExpired(entry, now)) entries.delete(key);
+    }
+    if (entries.size < MAX_ENTRIES) return true;
+    for (const state of ["success", "failed"] as const) {
+      for (const [key, entry] of entries) {
+        if (entry.state === state) {
+          entries.delete(key);
+          return true;
+        }
+      }
+    }
+    return false;
+  };
+
+  const liveEntry = (key: string, now: number): LedgerEntry | undefined => {
+    const entry = entries.get(key);
+    if (!entry) return undefined;
+    if (isExpired(entry, now)) {
+      entries.delete(key);
+      return undefined;
+    }
+    return entry;
+  };
+
+  // Replacing an existing key never grows the map, and every NEW key is admitted only through
+  // claim()'s makeRoom gate, so the table cannot exceed MAX_ENTRIES.
+  const set = (key: string, state: LedgerEntry["state"], now: number, token?: string): void => {
+    if (entries.has(key)) entries.delete(key);
+    entries.set(key, { state, at: now, ...(token !== undefined ? { token } : {}) });
+  };
+
+  /** True when the caller's token still owns the current in-flight entry for this key. */
+  const owns = (key: string, token: string, now: number): boolean => {
+    const entry = liveEntry(key, now);
+    return entry?.state === "inflight" && entry.token === token;
+  };
+
+  return {
+    claim(key, now = Date.now()) {
+      const entry = liveEntry(key, now);
+      if (entry?.state === "success") return { state: "complete" };
+      if (entry?.state === "failed") return { state: "cooldown" };
+      if (entry?.state === "inflight") return { state: "inflight" };
+      if (!makeRoom(now)) return { state: "saturated" };
+      claimSequence += 1;
+      const token = `claim-${claimSequence.toString(36)}`;
+      set(key, "inflight", now, token);
+      return { state: "claimed", token };
+    },
+    complete(key, token, now = Date.now()) {
+      // A settlement that no longer owns the entry is a no-op: the claim it belonged to expired
+      // and a successor now owns the state.
+      if (owns(key, token, now)) set(key, "success", now);
+    },
+    fail(key, token, now = Date.now()) {
+      if (owns(key, token, now)) set(key, "failed", now);
+    },
+    release(key, token, now = Date.now()) {
+      if (owns(key, token, now)) entries.delete(key);
+    },
+    markAdvised(key, now = Date.now()) {
+      // Recording the FACT must respect the same cap as claiming: a key that is not present and a
+      // table holding nothing but live claims means no room, so the record is skipped rather than
+      // evicting a claim that is still running. Fail-open: at worst one extra automatic attempt.
+      const present = liveEntry(key, now) !== undefined;
+      if (!present && !makeRoom(now)) return;
+      set(key, "success", now);
+    },
+    size() {
+      return entries.size;
+    },
+  };
+}
+
+/**
+ * Stable conversation identity for the ledger, reusing the repository's existing request
+ * identities in specificity order: the client's own thread, the shared parent thread, the
+ * Cursor conversation, the Cursor client thread, then the reasoning-replay scope's thread.
+ * Returns undefined for a client that sends no identity at all — such a caller stays out of the
+ * process-global ledger on purpose (fail-open, see the module header).
+ */
+export function advisorConversationIdentity(parsed: {
+  _codexOwnThreadId?: string;
+  _clientThreadId?: string;
+  _cursorConversationId?: string;
+  _cursorClientThreadId?: string;
+  _reasoningReplayScope?: { clientThreadId?: string };
+}): string | undefined {
+  return parsed._codexOwnThreadId
+    ?? parsed._clientThreadId
+    ?? parsed._cursorConversationId
+    ?? parsed._cursorClientThreadId
+    ?? parsed._reasoningReplayScope?.clientThreadId
+    ?? undefined;
+}
+
+/**
+ * Domain-separated SHA-256 digest. Task identity and suppression are CORRECTNESS boundaries, so a
+ * 32-bit non-cryptographic hash is not an acceptable primary digest: distinct tasks must not
+ * collide because of a short fold. The ledger stores only this digest, never the raw text, so a
+ * captured key reveals nothing about the conversation. The domain prefix keeps digests from
+ * different purposes apart even if their inputs coincide.
+ */
+function sha256Hex(domain: string, value: string, hexChars: number): string {
+  return createHash("sha256").update(`${domain}\0${value}`, "utf8").digest("hex").slice(0, hexChars);
+}
+
+/**
+ * The current task boundary inside a conversation: how many user turns the history carries and a
+ * digest of the FULL latest user text. A new user message moves the boundary (a new task gets its
+ * own claim); the same turn re-sent by a stateless full-history client keeps the same boundary,
+ * and a `previous_response_id` expansion replays the same user turns, so continuations dedup.
+ * The whole text participates — no truncation — so two tasks that share an opening prefix still
+ * get different boundaries.
+ */
+export function advisorTaskBoundary(parsed: {
+  context: { messages: readonly { role: string; content: unknown }[] };
+}): string {
+  let userTurns = 0;
+  let lastUserText = "";
+  for (const message of parsed.context.messages) {
+    if (message.role !== "user") continue;
+    userTurns += 1;
+    lastUserText = contentText(message.content);
+  }
+  return `t${userTurns}:${sha256Hex("advisor-task-boundary", lastUserText, 32)}`;
+}
+
+/**
+ * The ledger key: one domain-separated SHA-256 digest over conversation identity + task boundary
+ * + worker model. Returns undefined when the caller has no stable conversation identity — the
+ * caller then relies on request-scoped dedup and genuine in-history provenance instead of a
+ * shared guess (documented fail-open).
+ */
+export function advisorLedgerKey(
+  parsed: {
+    context: { messages: readonly { role: string; content: unknown }[] };
+    _codexOwnThreadId?: string;
+    _clientThreadId?: string;
+    _cursorConversationId?: string;
+    _cursorClientThreadId?: string;
+    _reasoningReplayScope?: { clientThreadId?: string };
+  },
+  workerModelId: string,
+): string | undefined {
+  const identity = advisorConversationIdentity(parsed);
+  if (!identity) return undefined;
+  const material = `${identity}\0${advisorTaskBoundary(parsed)}\0${workerModelId}`;
+  return `ak-${sha256Hex("advisor-task-key", material, 40)}`;
+}
+
+/** Text projection for string-or-parts content; used only for hashing, never transmitted. */
+export function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part): part is { type: "text"; text: string } =>
+      !!part && typeof part === "object" && (part as { type?: unknown }).type === "text"
+      && typeof (part as { text?: unknown }).text === "string")
+    .map(part => part.text)
+    .join("");
+}
+
+/**
+ * Legacy marker spellings. Failure text still neutralizes them so an upstream error cannot
+ * look like an old wrapper. They are not suppression authority and are not emitted.
+ */
+export const ADVISOR_PREFLIGHT_MARKER = "<opencodex_advisor_preflight>";
+
+/** The synthetic advisor tool's wire name; kept in sync with the tool definition by test. */
+export const ADVISOR_RESULT_TOOL_NAME = "advisor";
+
+/** Legacy manual wrapper spelling. Detection does not search for this substring. */
+export const ADVISOR_ADVICE_MARKER = "<opencodex_advisor>";
+
+/**
+ * Detect an ALREADY-PRESENT MANUAL advisor result — by provenance, never by a bare string.
+ * The message must be a `toolResult` whose `toolName` is the synthetic advisor tool, and its
+ * content must parse as a runtime-written advice object (`status === "advice"` on the sibling
+ * field the runtime sets). Text inside `advice` cannot flip that field.
+ *
+ * Only messages after the latest user turn count. Manual advice from an earlier task in the
+ * same thread does not suppress preflight for a later task; the ledger keys those separately.
+ * Developer messages are deliberately NOT inspected. Automatic preflight dedup lives in the
+ * ledger. A client-echoed developer envelope, a shell result, or a failure notice matches nothing.
+ */
+export function historyHasManualAdvisorResult(parsed: {
+  context: { messages: readonly { role: string; content?: unknown; toolName?: string }[] };
+}): boolean {
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i]!;
+    if (message.role === "user") break;
+    if (message.role !== "toolResult") continue;
+    if (message.toolName !== ADVISOR_RESULT_TOOL_NAME) continue;
+    if (advisorResultIsAdvice(contentText(message.content))) return true;
+  }
+  return false;
+}
+
+/** Kept for callers that only need the first user text (payload building, tests). */
+export function firstUserText(parsed: { context: { messages: readonly { role: string; content: unknown }[] } }): string {
+  for (const message of parsed.context.messages) {
+    if (message.role !== "user") continue;
+    const text = contentText(message.content);
+    if (text.trim() !== "") return text;
+  }
+  return "";
+}
+
+/**
+ * Deterministic preflight trigger: has this conversation already produced orientation evidence
+ * since the latest user message? The documented approximation for "before the first substantive
+ * implementation" — the protocol layer offers no safe pre-mutation checkpoint, so OpenCodex fires
+ * the automatic attempt on the first worker reasoning turn that arrives with that evidence.
+ * Evidence is an assistant tool call OR a tool result after the latest user message (both forms
+ * are genuinely accepted; the docs say so). Only text/toolResult content is inspected — never
+ * reasoning, never encrypted items.
+ */
+export function hasOrientationEvidence(parsed: { context: { messages: readonly { role: string; content: unknown }[] } }): boolean {
+  let latestUserIndex = -1;
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    if (parsed.context.messages[i]?.role === "user") {
+      latestUserIndex = i;
+      break;
+    }
+  }
+  if (latestUserIndex < 0) return false;
+  for (let i = latestUserIndex + 1; i < parsed.context.messages.length; i += 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "toolResult") return true;
+    if (message.role === "assistant" && Array.isArray(message.content)
+      && message.content.some(part =>
+        !!part && typeof part === "object" && (part as { type?: unknown }).type === "toolCall")) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/advisor/synthetic-tool.ts

@@ -0,0 +1,33 @@
+/**
+ * The synthetic `advisor` tool injected into routed worker turns.
+ *
+ * Mirrors src/web-search/synthetic-tool.ts: the proxy OWNS this tool — the worker only expresses
+ * "I want to consult the expert" (optionally with a focus), and OpenCodex builds everything else
+ * (task context, conversation, tool catalog, identities) itself. The worker never passes a
+ * transcript, provider, model, or files.
+ */
+import type { OcxTool } from "../types";
+
+export const ADVISOR_TOOL_NAME = "advisor";
+
+export function buildAdvisorTool(): OcxTool {
+  return {
+    name: ADVISOR_TOOL_NAME,
+    description:
+      "Consult an independent expert advisor model about the current task. The advisor receives a "
+      + "summary of what you have done so far (task, conversation, tool results) and returns "
+      + "strategic advice, critique, root-cause reasoning, or alternative approaches. Use it when "
+      + "you are stuck, before starting substantive implementation on a hard task, or when you want "
+      + "a second opinion on a plan or diagnosis. The advisor cannot execute tools or edit files; "
+      + "you remain responsible for all execution. Optionally pass a short `question` to focus the "
+      + "consultation.",
+    parameters: {
+      type: "object",
+      properties: {
+        question: { type: "string", description: "Optional short focus question for the advisor." },
+      },
+      required: [],
+    },
+    advisor: true,
+  };
+}

package/src/bridge/errors.ts

@@ -13,6 +13,7 @@ import {
   CYBER_POLICY_ERROR_CODE,
   isCyberPolicyCode,
   SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE,
+  UNDECLARED_TOOL_CALL_ERROR_CODE,
   type OcxErrorPayload,
 } from "../lib/errors";
 
@@ -31,6 +32,10 @@ export function formatErrorResponse(
     error.code = CYBER_POLICY_ERROR_CODE;
     error.type = cyberPolicyErrorType(type);
   }
+  // The undeclared-tool refusal is deterministic, not a transient upstream failure: its code
+  // survives so the Anthropic translator can classify it instead of folding it into a
+  // retryable overload (and so clients see the SSE path's rejection identity).
+  if (options?.code === UNDECLARED_TOOL_CALL_ERROR_CODE) error.code = options.code;
   // Only the allowlisted transport verdicts survive this formatter. Do not forward
   // arbitrary provider codes, and preserve the existing cyber-policy precedence.
   const replayBlocked = error.code !== CYBER_POLICY_ERROR_CODE
@@ -68,3 +73,22 @@ export function formatErrorResponse(
   if (refusal) retainReplayRefusal(response);
   return response;
 }
+
+/**
+ * A spent usage window, in the shape the Codex client treats as final (#6991): HTTP 429 with
+ * `error.type: "usage_limit_reached"` and, when the reset is known, `resets_at` in epoch
+ * seconds. Codex stops (and shows the reset time when present) instead of backing off through its
+ * retry budget, which is what it does with `rate_limit_exceeded`. No `plan_type` is sent: Codex
+ * would read it as a ChatGPT plan and print that plan's upgrade advice. `formatErrorResponse`
+ * cannot build this, because every 429 it classifies becomes `rate_limit_exceeded` and its
+ * payload has no `resets_at`.
+ */
+export function formatUsageLimitReachedResponse(message: string, resetsAtMs: number | null, retryAfterSeconds: number | null): Response {
+  const error = {
+    message, type: "usage_limit_reached", code: "usage_limit_reached",
+    ...(resetsAtMs !== null ? { resets_at: Math.ceil(resetsAtMs / 1000) } : {}),
+  };
+  const headers = new Headers({ "Content-Type": "application/json" });
+  if (retryAfterSeconds !== null) headers.set("Retry-After", String(retryAfterSeconds));
+  return new Response(JSON.stringify({ error }), { status: 429, headers });
+}

package/src/bridge.ts

@@ -1,6 +1,6 @@
 export { adapterFailureFromMessage } from "./lib/errors";
 
-export { formatErrorResponse } from "./bridge/errors";
+export { formatErrorResponse, formatUsageLimitReachedResponse } from "./bridge/errors";
 export { setOwnedBudgetAbandonedMsForTests } from "./bridge/internal";
 export { buildResponseJSON } from "./bridge/response-json";
 export { bridgeToResponsesSSE } from "./bridge/sse";

package/src/chat/inbound.ts

@@ -36,7 +36,7 @@ export function assertChatCompletionsRoutingBody(raw: unknown): asserts raw is C
 const OUTPUT_CONFIG_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
 const OUTPUT_CONFIG_SUMMARIES = new Set(["auto", "concise", "detailed", "none"]);
 
-function contentToText(content: unknown): string {
+export function contentToText(content: unknown): string {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return "";
   const parts: string[] = [];
@@ -62,7 +62,7 @@ const imageUrlFromPart = chatImageUrlFromPart;
  * understanding is requested by (#3271). The object form is the only one that
  * can carry it — `video_url` as a bare string has nowhere to put it.
  */
-function videoFromPart(part: Rec): { url: string; processing?: string } | null {
+export function videoFromPart(part: Rec): { url: string; processing?: string } | null {
   if (part.type !== "video_url") return null;
   const videoUrl = part.video_url;
   if (typeof videoUrl === "string" && videoUrl.length > 0) return { url: videoUrl };
@@ -123,7 +123,7 @@ function userContentToBlocks(content: unknown): Rec[] {
  * was dropped in silence (#5212). A part with no inline bytes is still not translatable and is
  * left to the untranslated-media refusal, which runs before this loop.
  */
-function fileFromPart(part: Rec): Rec | null {
+export function fileFromPart(part: Rec): Rec | null {
   if (part.type !== "file" && part.type !== "input_file") return null;
   const file = isRec(part.file) ? part.file : part;
   const fileData = file.file_data;
@@ -143,7 +143,7 @@ function fileFromPart(part: Rec): Rec | null {
  * Only representable plaintext is read. No signature, encrypted payload or
  * provider-issued item id is reconstructed — see the reasoning item built below.
  */
-function assistantReasoningText(msg: Rec): string | undefined {
+export function assistantReasoningText(msg: Rec): string | undefined {
   if (typeof msg.reasoning_content === "string" && msg.reasoning_content.length > 0) {
     return msg.reasoning_content;
   }
@@ -601,6 +601,32 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
     ...(legacyFunctionsToResponses(raw.functions) ?? []),
   ];
   if (tools.length > 0) body.tools = tools;
+  applyChatSettings(raw, body);
+  return body;
+}
+
+/**
+ * The request settings of a Chat body as a Responses body with no conversation: `input` is
+ * empty and there are no `instructions` or `tools`. The Antigravity direct lane hands this to
+ * the Responses core so routing, effort policy, tier and logging keep reading the fields they
+ * read today, while the conversation is decoded straight into the IR
+ * (`src/protocols/codecs/chat-ir.ts`). Field order and validation are the bridge body's own:
+ * both are built by `applyChatSettings`.
+ */
+export function chatSettingsToResponsesBody(raw: unknown): Rec {
+  assertChatCompletionsRoutingBody(raw);
+  const body: Rec = {
+    model: raw.model,
+    input: [],
+    stream: raw.stream === true,
+    store: false,
+  };
+  applyChatSettings(raw, body);
+  return body;
+}
+
+/** Everything after the conversation and tool catalog: choice, limits, sampling, reasoning, format. */
+function applyChatSettings(raw: ChatCompletionsRoutingBody, body: Rec): void {
   if (raw.tool_choice !== undefined) toolChoiceToResponses(raw.tool_choice, body);
   else legacyFunctionChoiceToResponses(raw.function_call, body);
 
@@ -637,6 +663,4 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
 
   const text = responseFormatToText(raw.response_format);
   if (text) body.text = text;
-
-  return body;
 }

package/src/chat/outbound.ts

@@ -19,6 +19,7 @@ import {
   CYBER_POLICY_ERROR_CODE,
   isCyberPolicyCode,
   isCyberPolicyMessage,
+  UNDECLARED_TOOL_CALL_ERROR_CODE,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { createSseBlockBuffer, sseDataPayload } from "../server/sse-payload-rewrite";
@@ -196,6 +197,10 @@ export function chatCompletionsStreamErrorPayload(
   } else if (isCyberPolicyCode(details?.code) || classified.code === CYBER_POLICY_ERROR_CODE) {
     classified.code = CYBER_POLICY_ERROR_CODE;
     classified.type = cyberPolicyErrorType(details?.type);
+  } else if (details?.code === UNDECLARED_TOOL_CALL_ERROR_CODE) {
+    // The guard's deterministic refusal keeps its wire identity past classifyError's
+    // generic 5xx remap — same code the buffered Chat error and the SSE frame carry.
+    classified.code = UNDECLARED_TOOL_CALL_ERROR_CODE;
   } else if (details?.code !== undefined && details.code !== null && !classified.code) {
     classified.code = details.code;
   }

package/src/claude/context-windows.ts

@@ -10,7 +10,7 @@
  * adapter-reported CatalogModel.contextWindow / the Anthropic registry for passthrough ids);
  * nothing is guessed.
  */
-import { aliasForNative, aliasForRoute, currentClaudeAliasSpelling, legacyAliasForNative, legacyAliasForRoute } from "./alias";
+import { aliasForNative, aliasForRoute, currentClaudeAliasSpelling, legacyAliasForNative, legacyAliasForRoute, resolveAlias } from "./alias";
 import { desktop3pAlias } from "./desktop-3p";
 import { nativeOpenAiContextWindow, type CatalogModel, type NativeContextLimitsInput } from "../codex/catalog";
 import { ANTHROPIC_MODEL_CONTEXT_WINDOWS } from "../providers/registry/model-seeds";
@@ -277,6 +277,59 @@ export function effectiveModelEnv(
   return out;
 }
 
+/**
+ * Tier slots Claude Code pairs with a `<slot>_NAME` label (#6926). Its /model tier row is
+ * `label: <slot>_NAME ?? <first-party display name> ?? <slot value>` (2.1.296), and an
+ * `ocx-claude-*` alias is not a first-party id, so without the label the row prints the alias.
+ * The alias itself stays the submitted id: saved selections and inbound resolution depend on it.
+ */
+export const CLAUDE_TIER_LABEL_SLOTS = [
+  "ANTHROPIC_DEFAULT_OPUS_MODEL",
+  "ANTHROPIC_DEFAULT_SONNET_MODEL",
+  "ANTHROPIC_DEFAULT_FABLE_MODEL",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+] as const;
+
+export type ClaudeTierLabelSlot = (typeof CLAUDE_TIER_LABEL_SLOTS)[number];
+
+export function isClaudeTierLabelSlot(name: string): name is ClaudeTierLabelSlot {
+  return (CLAUDE_TIER_LABEL_SLOTS as readonly string[]).includes(name);
+}
+
+/**
+ * The picker label for a tier slot holding an OpenCodex alias, spelled like the discovery
+ * row's `display_name` (model-info.ts): `<slug> (native)`, `<model> (<provider>)` and a
+ * ` · 1M` variant. The native-namespaced `claude-*` selector is the Anthropic Fable picker
+ * alias, which discovery labels `(anthropic)`. A trailing `--fast` stays in the model name:
+ * without the catalog this cannot tell a synthetic Fast sibling from a real model whose id ends
+ * in `--fast`, and naming the exact model beats a prettier label that could name the wrong one.
+ * Anything that is not an alias (a first-party id, `provider/model`, a bare slug) gets no
+ * label: Claude Code either names it itself or the id is already what the user typed.
+ */
+export function claudeTierDisplayName(selector: string): string | undefined {
+  const trimmed = selector.trim();
+  const oneMillion = hasOneMillionMarker(trimmed);
+  const route = resolveAlias(stripOneMillionMarker(trimmed));
+  if (route === null) return undefined;
+  const slash = route.indexOf("/");
+  let provider = slash > 0 ? route.slice(0, slash) : "native";
+  const model = slash > 0 ? route.slice(slash + 1) : route;
+  if (!model) return undefined;
+  if (provider === "native" && model.startsWith("claude-")) provider = "anthropic";
+  return `${model} (${provider})${oneMillion ? " · 1M" : ""}`;
+}
+
+/** `{ "<slot>_NAME": label }` for each tier slot in `env` that holds an OpenCodex alias. */
+export function claudeTierDisplayNameEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const slot of CLAUDE_TIER_LABEL_SLOTS) {
+    const value = env[slot];
+    const label = value ? claudeTierDisplayName(value) : undefined;
+    if (label !== undefined) out[`${slot}_NAME`] = label;
+  }
+  return out;
+}
+
 /** Shared 3s bounded acquisition (audit R4#3) for context-window sources. */
 export async function boundedContextWindows(
   acquire: () => Promise<Record<string, number>>,