opencode-anthropic-fix 0.5.0 → 1.0.0

package/lib/betas.mjs

@@ -0,0 +1,131 @@
+/**
+ * Host beta policy.
+ *
+ * Three things live here, and none of them is wire construction:
+ *  - `EXPERIMENTAL_BETA_FLAGS`: the betas the HOST treats as experimental, i.e.
+ *    the set it filters out when `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` is on;
+ *  - `BETA_SHORTCUTS`: CLI UX aliases for `/anthropic betas` and
+ *    `config.custom_betas`;
+ *  - `resolveBetaShortcut`: the resolver behind those aliases.
+ *
+ * The betas that actually go on the wire are the shared package's business
+ * (`lib/mimicry/wire-compat.mjs`); this module only decides what the plugin
+ * ADDS or SUPPRESSES on top of them.
+ *
+ * RECONCILIATION IS ENFORCED BY TEST, not by convention. Every literal header
+ * below is checked against the package's `BETA_REGISTRY_2_1_233` — the genuine
+ * client's own registry — by `lib/betas.test.mjs`, which fails on a stale date
+ * stamp and requires the host-only entries (the ones upstream has no registry
+ * slot for) to be enumerated and justified rather than merely accumulated. Add
+ * a beta here that upstream does not ship and the test will tell you to say why.
+ */
+
+/**
+ * Set of all known experimental/optional beta flags.
+ * Used to filter betas when CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.
+ * WARNING: this set intentionally overlaps with always-on betas - only use
+ * it with the disable-experimental guard, never unconditionally.
+ */
+export const EXPERIMENTAL_BETA_FLAGS = new Set([
+  "adaptive-thinking-2026-01-28",
+  "advanced-tool-use-2025-11-20",
+  "advisor-tool-2026-03-01",
+  "afk-mode-2026-01-31",
+  "cache-diagnosis-2026-04-07",
+  // CCR bring-your-own-cloud beta. Registered in the 2.1.154 binary's _W() table
+  // but not emitted on /v1/messages; kept here for the disable-experimental guard.
+  "ccr-byoc-2025-07-29",
+  "code-execution-2025-08-25",
+  "compact-2026-01-12",
+  "context-1m-2025-08-07",
+  "context-hint-2026-04-09",
+  "context-management-2025-06-27",
+  "environments-2025-11-01",
+  "extended-cache-ttl-2025-04-11",
+  // Refusal-fallback credit beta from the upstream Udd registry (CC 2.1.195).
+  // Opt-in/GrowthBook-gated; never auto-emitted on a default /v1/messages turn.
+  // Listed here for the disable-experimental guard + manual opt-in ONLY.
+  "fallback-credit-2026-06-01",
+  "fast-mode-2026-02-01",
+  "files-api-2025-04-14",
+  "interleaved-thinking-2025-05-14",
+  // Registered in the 2.1.154 binary's _W() table (mcp_servers label). Plugin
+  // proxies MCP tool calls inline and does not emit this on chat completions.
+  "mcp-servers-2025-12-04",
+  // Registered in CC v2.1.143 but NOT in real CC's always-on emission set
+  // (master registry only, not in the always-on subset). Likely GrowthBook-gated
+  // pending server rollout. Paired telemetry: tengu_mid_conv_system_fallback_retry.
+  "mid-conversation-system-2026-04-07",
+  "prompt-caching-scope-2026-01-05",
+  "redact-thinking-2026-02-12",
+  // Server-side refusal-fallback beta from the upstream Udd registry (CC 2.1.195).
+  // Opt-in/GrowthBook-gated; never auto-emitted on a default /v1/messages turn.
+  // Listed here for the disable-experimental guard + manual opt-in ONLY.
+  "server-side-fallback-2026-06-01",
+  "structured-outputs-2025-12-15",
+  // Revived in CC 2.1.159 as registry label `narration_summaries` (it was a dead
+  // slot from v2.1.90-2.1.154). Real CC emits it only when GrowthBook flag
+  // `pewter_owl_header` is on (default-off), first-party, and NOT in fast-mode.
+  // Listed here for the disable-guard + manual opt-in ONLY; never emitted always-on.
+  "summarize-connector-text-2026-03-13",
+  "task-budgets-2026-03-13",
+  "tool-search-tool-2025-10-19",
+  // SDK admin route beta (used for /v1/user_profiles* endpoints). Registered for
+  // forward-compat; the plugin proxies /v1/messages only and does NOT emit this
+  // on chat completions.
+  "user-profiles-2026-03-24",
+  "web-search-2025-03-05",
+]);
+
+/** Friendly shortcut aliases for config.custom_betas values. */
+export const BETA_SHORTCUTS = new Map([
+  ["1m", "context-1m-2025-08-07"],
+  ["1m-context", "context-1m-2025-08-07"],
+  ["context-1m", "context-1m-2025-08-07"],
+  ["cache-diagnosis", "cache-diagnosis-2026-04-07"],
+  ["cache-diag", "cache-diagnosis-2026-04-07"],
+  ["cache-ttl", "extended-cache-ttl-2025-04-11"],
+  ["context-hint", "context-hint-2026-04-09"],
+  ["environments", "environments-2025-11-01"],
+  ["extended-cache-ttl", "extended-cache-ttl-2025-04-11"],
+  ["hint", "context-hint-2026-04-09"],
+  ["fast", "fast-mode-2026-02-01"],
+  ["fast-mode", "fast-mode-2026-02-01"],
+  ["opus-fast", "fast-mode-2026-02-01"],
+  ["task-budgets", "task-budgets-2026-03-13"],
+  ["budgets", "task-budgets-2026-03-13"],
+  ["redact-thinking", "redact-thinking-2026-02-12"],
+  ["mid-conv-system", "mid-conversation-system-2026-04-07"],
+  ["mid-system", "mid-conversation-system-2026-04-07"],
+  ["context-management", "context-management-2025-06-27"],
+  ["structured-outputs", "structured-outputs-2025-12-15"],
+  ["web-search", "web-search-2025-03-05"],
+  ["advanced-tool-use", "advanced-tool-use-2025-11-20"],
+  ["tool-search-tool", "tool-search-tool-2025-10-19"],
+  ["effort", "effort-2025-11-24"],
+  ["prompt-caching-scope", "prompt-caching-scope-2026-01-05"],
+  ["thinking-token-count", "thinking-token-count-2026-05-13"],
+  ["afk-mode", "afk-mode-2026-01-31"],
+  ["advisor-tool", "advisor-tool-2026-03-01"],
+  ["mcp-servers", "mcp-servers-2025-12-04"],
+  ["ccr-byoc", "ccr-byoc-2025-07-29"],
+  ["connector-text", "summarize-connector-text-2026-03-13"],
+  ["narration-summaries", "summarize-connector-text-2026-03-13"],
+  ["summarize-connector-text", "summarize-connector-text-2026-03-13"],
+  ["server-side-fallback", "server-side-fallback-2026-06-01"],
+  ["fallback", "server-side-fallback-2026-06-01"],
+  ["fallback-credit", "fallback-credit-2026-06-01"],
+]);
+
+/**
+ * Resolve a beta shortcut alias to its canonical flag name.
+ * Returns the value unchanged if no alias matches.
+ * @param {string | null | undefined} value
+ * @returns {string}
+ */
+export function resolveBetaShortcut(value) {
+  if (!value) return "";
+  const trimmed = value.trim();
+  const mapped = BETA_SHORTCUTS.get(trimmed.toLowerCase());
+  return mapped || trimmed;
+}

package/lib/diagnose.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 
 import { getConfigDir, loadConfig } from "./config.mjs";
 import { redactSecrets } from "./redact.mjs";
-import { FALLBACK_CLAUDE_CLI_VERSION } from "./request-headers.mjs";
+import { WIRE_PROFILE } from "./mimicry/wire-compat.mjs";
 import { loadAccounts } from "./storage.mjs";
 
 const ENV_KEYS = [
@@ -172,7 +172,9 @@ export async function buildDiagnosticBundle() {
       pluginVersion: getPluginVersion(),
       nodeVersion: process.version,
       platform: process.platform,
-      mimicryBaseline: FALLBACK_CLAUDE_CLI_VERSION,
+      // Static baseline on purpose: the CLI version the wire package's profile
+      // declares, NOT the (possibly npm-updated) version of the running session.
+      mimicryBaseline: WIRE_PROFILE.cliVersion,
     },
     config: redactSecrets(loadConfig()),
     env: getRuntimeEnv(),

package/lib/mimicry/adapter-input.mjs

@@ -23,19 +23,30 @@
  */
 
 import { isTruthyEnv, isFalsyEnv } from "../env.mjs";
-import { CLAUDE_3_MODEL_RE, hasOneMillionContext } from "./models.mjs";
-import { BETA_SHORTCUTS, EXPERIMENTAL_BETA_FLAGS } from "../request-headers.mjs";
+import {
+  hasOneMillionContext,
+  isClaude3Model,
+  isHaikuModel,
+  supportsStructuredOutputs,
+  supportsWebSearch,
+  WIRE_PROFILE,
+  BETA_REGISTRY_2_1_233,
+} from "./wire-compat.mjs";
+import { BETA_SHORTCUTS, EXPERIMENTAL_BETA_FLAGS } from "../betas.mjs";
 import { resolveCacheTtl } from "./cache.mjs";
+// CLAUDE_CODE_BETA_FLAG and HOST_SDK_BETAS_BLOCKLIST are HOST POLICY, not wire
+// capability: the first is the sentinel this module tests for when deciding
+// whether a rescued host beta is already package-composed, the second is the
+// plugin's own list of betas the host SDK injects that the genuine client never
+// sends. Both stay plugin-side by design; only the model CAPABILITY predicates
+// moved to the package seam above.
 import {
   CLAUDE_CODE_BETA_FLAG,
   HOST_SDK_BETAS_BLOCKLIST,
   buildStainlessHelperHeader,
   getStainlessArch,
   getStainlessOs,
-  isHaikuModel,
   parseRequestBodyMetadata,
-  supportsStructuredOutputs,
-  supportsWebSearch,
 } from "./headers.mjs";
 
 // ---------------------------------------------------------------------------
@@ -48,6 +59,69 @@ export const ADAPTER_SKIP_SIGNATURE_DISABLED = "signature-disabled";
 /** The shared package pins the Anthropic first-party URL and rejects any other. */
 export const ADAPTER_SKIP_NON_ANTHROPIC_PROVIDER = "non-anthropic-provider";
 
+/**
+ * The pathnames the shared package has a surface for. `/v1/messages` and
+ * `/messages` go to `buildClaudeCodeRequest`; the count pair goes to
+ * `buildClaudeCodeCountTokensRequest`. Every other pathname (files, models,
+ * a gateway-prefixed route) is passed through untouched by the interceptor.
+ */
+export const ADAPTER_MESSAGES_PATHNAMES = new Set(["/v1/messages", "/messages"]);
+
+/** @see ADAPTER_MESSAGES_PATHNAMES */
+export const ADAPTER_COUNT_TOKENS_PATHNAMES = new Set(["/v1/messages/count_tokens", "/messages/count_tokens"]);
+
+/**
+ * Reject a request the adapter is REQUIRED to handle but cannot.
+ *
+ * WHY THIS THROWS INSTEAD OF DEGRADING. Since Phase 2.2 the adapter is
+ * unconditional: with signature emulation on, a messages/count_tokens turn has
+ * exactly one construction path. A body the package cannot consume used to fall
+ * back to the legacy forge, which meant a malformed or bodiless request quietly
+ * went on the wire with a different fingerprint than every other turn in the
+ * session — the failure mode the migration exists to remove. Failing loudly
+ * here keeps the path single, and the message names the endpoint and the exact
+ * defect so the caller can fix its request.
+ *
+ * The check is deliberately structural (a JSON object), not semantic: `model`,
+ * `max_tokens` and `messages` validation belongs to the package, which already
+ * reports it as `INVALID_INPUT` with `safeDetails`.
+ *
+ * @param {unknown} body The body the host handed the interceptor.
+ * @param {string | undefined} pathname The outgoing pathname, for the message.
+ * @returns {void}
+ * @throws {Error} When the body is absent, unparsable, or not a JSON object.
+ */
+export function assertAdapterBodyUsable(body, pathname) {
+  const where = `${pathname ?? "the messages endpoint"} with signature emulation on`;
+  if (typeof body !== "string" || body.length === 0) {
+    throw new Error(
+      `opencode-anthropic-fix: ${where} requires a JSON request body, but the request carried ` +
+        `${typeof body === "string" ? "an empty string" : `no usable body (${typeof body})`}. ` +
+        `The Claude Code wire adapter cannot construct this request.`,
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch (error) {
+    throw new Error(
+      `opencode-anthropic-fix: ${where} requires a JSON request body, but the body could not be ` +
+        `parsed as JSON (${error instanceof Error ? error.message : String(error)}). ` +
+        `The Claude Code wire adapter cannot construct this request.`,
+      { cause: error },
+    );
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      `opencode-anthropic-fix: ${where} requires a JSON OBJECT request body, but the body parsed ` +
+        `as ${Array.isArray(parsed) ? "an array" : String(parsed === null ? "null" : typeof parsed)}. ` +
+        `The Claude Code wire adapter cannot construct this request.`,
+    );
+  }
+}
+
 /**
  * `additionalBetas` accepts at most 32 entries; overflow is `INVALID_INPUT`,
  * a hard failure rather than a degradation. Exported so the test suite can
@@ -70,8 +144,28 @@ export const MAX_SUPPRESS_BETAS = 32;
  * the round-robin strategy: rotating accounts means the cache scope marker
  * points at a prompt cache the next account cannot read, so paying the beta's
  * bookkeeping buys nothing.
+ *
+ * The header string itself is WIRE state, so it is read from the package's beta
+ * registry through the seam rather than re-typed here: if the package ever
+ * re-dates the beta, the suppression keeps matching what the package composes.
  */
-export const PROMPT_CACHING_SCOPE_BETA = "prompt-caching-scope-2026-01-05";
+export const PROMPT_CACHING_SCOPE_BETA = BETA_REGISTRY_2_1_233.PROMPT_CACHING_SCOPE.header;
+
+/**
+ * Betas the plugin opts INTO on its own (see `buildAdditionalBetas`): whether
+ * each one is emitted is HOST POLICY — model capability, request shape, the
+ * round-robin rotation, `toolEnablement` — and that policy stays here.
+ *
+ * The CANONICAL NAMES are not host policy; they are wire state owned by the
+ * package. Reading them from the registry through the seam means an upstream
+ * rename or date bump surfaces as a changed emission instead of drifting
+ * silently against a literal re-typed in this file.
+ */
+export const WEB_SEARCH_BETA = BETA_REGISTRY_2_1_233.WEB_SEARCH.header;
+export const ADVISOR_TOOL_BETA = BETA_REGISTRY_2_1_233.ADVISOR_TOOL.header;
+export const FILES_API_BETA = BETA_REGISTRY_2_1_233.FILES_API.header;
+export const EXTENDED_CACHE_TTL_BETA = BETA_REGISTRY_2_1_233.EXTENDED_CACHE_TTL.header;
+export const STRUCTURED_OUTPUTS_BETA = BETA_REGISTRY_2_1_233.STRUCTURED_OUTPUTS.header;
 
 /**
  * `runtime.sessionId` is REQUIRED by the package (`requiredString`), while the
@@ -82,6 +176,13 @@ export const PROMPT_CACHING_SCOPE_BETA = "prompt-caching-scope-2026-01-05";
  * package's own correlation checks; in practice `signatureSessionId` is always
  * populated when signature emulation is enabled, so this is a safety net rather
  * than a routine path.
+ *
+ * BOUNDARY: host policy, NOT wire state. This is a plugin invention — genuine
+ * Claude Code always has a session id, so it has no equivalent constant, and
+ * neither the package (no occurrence in `dist/`) nor the reverse-engineering
+ * notes carry this UUID. It therefore stays a local literal by design and is
+ * exempt from the version-literal governance guard
+ * (`test/conformance/version-literals-retired.test.mjs`).
  */
 export const SESSION_ID_FALLBACK = "00000000-0000-4000-8000-000000000000";
 
@@ -143,14 +244,15 @@ export const ADAPTER_ENV_KEYS = Object.freeze([
  * the `latest` dist-tag, so each package release can advance the default profile
  * and the plugin follows without a code change to the composition path.
  *
- * These two constants are the ONLY thing that has to move in lockstep: they
- * mirror the default profile's `cliVersion` / `userAgent` so that
- * `resolveProfileOverride` stays silent in the common case. Keep them in sync
- * with `FALLBACK_CLAUDE_CLI_VERSION` (lib/request-headers.mjs) on every package
- * bump that changes the default profile.
+ * These two constants are the baseline `resolveProfileOverride` compares
+ * against, and they are READ FROM the profile through the seam
+ * (`WIRE_PROFILE`, lib/mimicry/wire-compat.mjs) rather than re-typed. A package
+ * bump that advances the default profile therefore moves the plugin's baseline
+ * with it — no lockstep edit, and no way for the two to silently disagree and
+ * emit a spurious profile override on every request.
  */
-export const PROFILE_CLI_VERSION = "2.1.233";
-export const PROFILE_USER_AGENT = "claude-cli/2.1.233 (external, cli)";
+export const PROFILE_CLI_VERSION = WIRE_PROFILE.cliVersion;
+export const PROFILE_USER_AGENT = WIRE_PROFILE.userAgent;
 
 // ---------------------------------------------------------------------------
 // Environment snapshot
@@ -177,7 +279,7 @@ export function resolveAdapterEnv(source) {
 // ---------------------------------------------------------------------------
 
 /**
- * Pure mirror of `buildExtendedUserAgent` (lib/request-headers.mjs) with the
+ * Pure mirror of `buildExtendedUserAgent` (lib/mimicry/headers.mjs) with the
  * environment injected instead of read. The two are pinned to agree by
  * `adapter-input.test.mjs`.
  *
@@ -385,11 +487,11 @@ function buildAdditionalBetas(args) {
   const isRoundRobin = strategy === "round-robin";
   const te = tokenEconomy || {};
 
-  if (supportsWebSearch(model)) betas.push("web-search-2025-03-05");
-  if (!CLAUDE_3_MODEL_RE.test(model)) betas.push("advisor-tool-2026-03-01");
-  if (isFilesEndpoint || hasFileReferences) betas.push("files-api-2025-04-14");
-  if (te.extended_cache_ttl !== false && !isRoundRobin) betas.push("extended-cache-ttl-2025-04-11");
-  if (te.structured_outputs && supportsStructuredOutputs(model)) betas.push("structured-outputs-2025-12-15");
+  if (supportsWebSearch(model)) betas.push(WEB_SEARCH_BETA);
+  if (!isClaude3Model(model)) betas.push(ADVISOR_TOOL_BETA);
+  if (isFilesEndpoint || hasFileReferences) betas.push(FILES_API_BETA);
+  if (te.extended_cache_ttl !== false && !isRoundRobin) betas.push(EXTENDED_CACHE_TTL_BETA);
+  if (te.structured_outputs && supportsStructuredOutputs(model)) betas.push(STRUCTURED_OUTPUTS_BETA);
   // The package deliberately excludes Haiku from `claude-code-20250219`; the
   // plugin deliberately includes it so Haiku subagents reached through
   // model-router delegation still get full mimic behaviour.
@@ -639,17 +741,17 @@ export function buildAdapterTransport(state) {
   }
   // Lean system prompt for non-main requests (`token_economy.lean_system_non_main`).
   //
-  // On the LEGACY path this decision lives in `buildSystemPromptBlocks`
-  // (`leanNonMain` in lib/mimicry/system-prompt.mjs), which returns the
-  // sanitized blocks before the billing header and the identity prefix are
-  // prepended. On the ADAPTER path those two blocks are no longer the plugin's
-  // to withhold — `suppressCanonicalBlocks` hands their composition to the
-  // package — so the same decision has to be re-expressed as the package's two
-  // root seams, or the opt-in silently degrades to a no-op.
+  // This is the ONLY place the lean decision is made. `suppressCanonicalBlocks`
+  // hands the composition of the billing header and the identity prefix to the
+  // package, so the plugin can no longer withhold either block by simply not
+  // emitting it; the intent has to be expressed as the package's two root
+  // seams (`suppressBillingBlock` / `suppressIdentityBlock`), which the package
+  // honours when it assembles the canonical blocks. Without them the opt-in
+  // silently degrades to a no-op.
   //
-  // The gate is the SAME conjunction as the legacy one: opt-in flag, a "title"
-  // or "small" role, and not a title-generator turn (that shape gets its own
-  // canonical system prompt swap and keeps the attribution).
+  // The gate: opt-in flag, a "title" or "small" role, and not a title-generator
+  // turn (that shape gets its own canonical system prompt swap and keeps the
+  // attribution).
   if (
     tokenEconomy.lean_system_non_main === true &&
     (state.requestRole === "title" || state.requestRole === "small") &&

package/lib/mimicry/headers.mjs

@@ -1,12 +1,94 @@
+/**
+ * ===========================================================================
+ * BOUNDARY: THE LEGACY HEADER FORGE IS A FROZEN COMPATIBILITY SHIM.
+ * ===========================================================================
+ *
+ * WHAT IS FROZEN. The beta/header COMPOSITION in this module —
+ * `buildAnthropicBetaHeader`, `buildRequestHeaders`, and the Claude Code beta
+ * constants and model gates they consume (`CLAUDE_CODE_BETA_FLAG`,
+ * `_EFFORT_BETA_FLAG`, `FAST_MODE_BETA_FLAG`, `TOKEN_COUNTING_BETA_FLAG`,
+ * `_EFFORT_EXCLUDED_MODELS`, `isEffortCapableModel`, and the local
+ * `isHaikuModel` / `supportsStructuredOutputs` / `supportsWebSearch` copies).
+ * It is a hand-written reimplementation of what
+ * `@tormentalabs/claude-code-wire-compat` now does from the genuine client's
+ * own tables.
+ *
+ * WHY IT IS STILL HERE. It is reachable ONLY for requests the shared package
+ * has no surface for: the files and models endpoints, a gateway-prefixed route,
+ * or any request made with signature emulation switched off. On `/v1/messages`
+ * and `/v1/messages/count_tokens` with emulation on — the path that carries the
+ * fingerprint claim — the adapter never enters it. It is a fallback, not a
+ * second implementation competing for the same traffic.
+ *
+ * THE RULE. Do not extend it, do not add a beta to it, do not "improve" its
+ * gating, and do not let a new caller in. Fixes to wire behaviour belong in the
+ * package. When the package grows a files/models/gateway surface, DELETE this
+ * forge and the constants above rather than porting them forward.
+ *
+ * GOVERNANCE. The Claude Code beta constants here would otherwise trip the
+ * Phase 4.1 guard against locally-declared wire constants; they are allowlisted
+ * as an explicitly-commented compat exception, and this banner is the comment
+ * the allowlist points at. Removing it should fail that guard, by design.
+ *
+ * NOT FROZEN, and NOT part of the exception: `HOST_SDK_BETAS_BLOCKLIST` (host
+ * policy — see its own comment), `parseRequestBodyMetadata`,
+ * `stripStainlessHelperMarkers`, `getStainlessOs`/`getStainlessArch` and
+ * `buildStainlessHelperHeader`, all of which the adapter path imports and uses.
+ */
+
 import { isTruthyEnv, isFalsyEnv } from "../env.mjs";
-import { CLAUDE_3_MODEL_RE, hasOneMillionContext } from "./models.mjs";
-import { EXPERIMENTAL_BETA_FLAGS, BETA_SHORTCUTS, buildExtendedUserAgent } from "../request-headers.mjs";
+import { hasOneMillionContext, isClaude3Model } from "./wire-compat.mjs";
+import { EXPERIMENTAL_BETA_FLAGS, BETA_SHORTCUTS } from "../betas.mjs";
 import { randomUUID } from "node:crypto";
 
+/**
+ * Build the extended User-Agent for API calls.
+ * Real CC v96 sends "claude-cli/{version} (external, {entrypoint})" - confirmed via
+ * proxy capture of real CC on Windows/Node.js.
+ *
+ * SCOPE: the legacy forge below is its only production caller, i.e. the
+ * endpoints the shared wire package has no surface for. `buildAdapterUserAgent`
+ * (lib/mimicry/adapter-input.mjs) is the pure mirror the adapter path uses, and
+ * `adapter-input.test.mjs` pins the two to agree. Phase 3.3 of the wire-compat
+ * migration may replace this with the package's own user-agent template.
+ *
+ * @param {string} version
+ * @returns {string}
+ */
+export function buildExtendedUserAgent(version) {
+  const entrypoint = process.env.CLAUDE_CODE_ENTRYPOINT ?? "cli";
+  const sdkVersion = process.env.CLAUDE_AGENT_SDK_VERSION ? `, agent-sdk/${process.env.CLAUDE_AGENT_SDK_VERSION}` : "";
+  const clientApp = process.env.CLAUDE_AGENT_SDK_CLIENT_APP
+    ? `, client-app/${process.env.CLAUDE_AGENT_SDK_CLIENT_APP}`
+    : "";
+  return `claude-cli/${version} (external, ${entrypoint}${sdkVersion}${clientApp})`;
+}
+
 export const CLAUDE_CODE_BETA_FLAG = "claude-code-20250219";
 export const _EFFORT_BETA_FLAG = "effort-2025-11-24";
 export const FAST_MODE_BETA_FLAG = "fast-mode-2026-02-01";
 export const TOKEN_COUNTING_BETA_FLAG = "token-counting-2024-11-01";
+/**
+ * BOUNDARY: host policy, not wire construction. Deliberately plugin-side.
+ *
+ * These are betas the HOST SDK injects into its outgoing request that the
+ * genuine Claude Code client NEVER sends. They are not stale registry entries
+ * and they are not the package's business — `BETA_REGISTRY_2_1_233` has no slot
+ * for either, because upstream has no reason to model a header it does not
+ * emit. The plugin drops them so a host's own SDK cannot leak a foreign
+ * fingerprint into a request that is otherwise byte-identical to the real
+ * client's.
+ *
+ * `structured-outputs-2025-11-13` is the sharp one: it is an OLDER date stamp of
+ * a beta upstream does ship (`structured-outputs-2025-12-15`). Blocking it is
+ * what keeps a host SDK from pinning the plugin to a superseded revision of a
+ * live beta. `lib/betas.test.mjs` reconciles the host tables against the
+ * registry; this set is intentionally exempt from that reconciliation, because
+ * its whole purpose is to name headers the registry does not contain.
+ *
+ * Consumed by BOTH paths — `lib/mimicry/adapter-input.mjs` imports it — so
+ * unlike the beta constants above it does NOT die with the legacy forge.
+ */
 export const HOST_SDK_BETAS_BLOCKLIST = new Set([
   "fine-grained-tool-streaming-2025-05-14",
   "structured-outputs-2025-11-13",
@@ -160,10 +242,35 @@ export function stripStainlessHelperMarkers(tools, messages) {
 
 export function isEffortCapableModel(model) {
   if (!model) return false;
-  if (CLAUDE_3_MODEL_RE.test(model)) return false;
+  if (isClaude3Model(model)) return false;
   return !_EFFORT_EXCLUDED_MODELS.some((re) => re.test(model));
 }
 
+/**
+ * ===========================================================================
+ * FROZEN COMPATIBILITY SHIM — DO NOT EXTEND. See the banner at the top of this
+ * file for the full boundary contract.
+ * ===========================================================================
+ *
+ * The legacy beta composer. On a `/v1/messages` or `/v1/messages/count_tokens`
+ * turn with signature emulation on — i.e. the overwhelming majority of traffic
+ * — the adapter path NEVER enters this function: the shared package composes the
+ * beta list and `lib/mimicry/adapter-input.mjs` only supplies `additionalBetas`
+ * and `suppressBetas` on top of it.
+ *
+ * It survives for exactly ONE caller and no more: `buildRequestHeaders` below,
+ * i.e. the endpoints the package has no surface for (files, models, a
+ * gateway-prefixed route).
+ *
+ * PHASE 4.1 — RESOLVED. The second caller, the `computedBetaHeader` call in
+ * `index.mjs`, is gone. It never reached the wire; it existed only so
+ * `transformRequestBody` could substring-test for `task-budgets-2026-03-13`,
+ * and that consumer now takes a boolean derived at the call site from the same
+ * gates `buildAdditionalBetas` applies. Do not add a caller back.
+ *
+ * @param {string} incomingBeta
+ * @param {boolean} signatureEnabled
+ */
 export function buildAnthropicBetaHeader(
   incomingBeta,
   signatureEnabled,
@@ -222,7 +329,7 @@ export function buildAnthropicBetaHeader(
   // (firstParty && non-Claude-3). Claude 3.x models don't support interleaved
   // thinking and real CC never sends this flag for them, so emitting it
   // diverges the fingerprint for legacy Haiku/Sonnet 3.x requests.
-  if (!isTruthyEnv(process.env.DISABLE_INTERLEAVED_THINKING) && !CLAUDE_3_MODEL_RE.test(model)) {
+  if (!isTruthyEnv(process.env.DISABLE_INTERLEAVED_THINKING) && !isClaude3Model(model)) {
     betas.push("interleaved-thinking-2025-05-14");
   }
 
@@ -257,7 +364,7 @@ export function buildAnthropicBetaHeader(
   // analyses read only the separate USE_API_CONTEXT_MANAGEMENT env term (hardcoded
   // && false) and recorded it as off; 2.1.195 confirms it ships by default for modern
   // first-party models. Opt out via token_economy.context_management = false.
-  if (te.context_management !== false && !CLAUDE_3_MODEL_RE.test(model)) {
+  if (te.context_management !== false && !isClaude3Model(model)) {
     betas.push("context-management-2025-06-27");
   }
 
@@ -284,7 +391,7 @@ export function buildAnthropicBetaHeader(
   // (tengu_sage_compass2) and firstParty+isLoggedIn. Since we can't check
   // CC's feature flags, include it unconditionally for Claude 4+ models.
   // CC v108 sends it in MITM captures for Max/Pro users.
-  if (!CLAUDE_3_MODEL_RE.test(model)) {
+  if (!isClaude3Model(model)) {
     betas.push("advisor-tool-2026-03-01");
   }
 
@@ -310,13 +417,13 @@ export function buildAnthropicBetaHeader(
 
   // v2.1.150: redact-thinking is default-ON in CC (first-party, non-SDK, thinking models).
   // Opt out via `/anthropic set redact-thinking off` to see thinking content.
-  if (te.redact_thinking !== false && !disableExperimentalBetas && !CLAUDE_3_MODEL_RE.test(model)) {
+  if (te.redact_thinking !== false && !disableExperimentalBetas && !isClaude3Model(model)) {
     betas.push("redact-thinking-2026-02-12");
   }
 
   // v2.1.150: thinking-token-count for token budget tracking (behind tengu_chert_bezel in CC).
   // Default ON for token economy visibility. Opt out via token_economy.thinking_token_count = false.
-  if (te.thinking_token_count !== false && !disableExperimentalBetas && !CLAUDE_3_MODEL_RE.test(model)) {
+  if (te.thinking_token_count !== false && !disableExperimentalBetas && !isClaude3Model(model)) {
     betas.push("thinking-token-count-2026-05-13");
   }
 
@@ -383,6 +490,27 @@ export function getStainlessArch(value) {
   return value;
 }
 
+/**
+ * ===========================================================================
+ * FROZEN COMPATIBILITY SHIM — DO NOT EXTEND. See the banner at the top of this
+ * file for the full boundary contract.
+ * ===========================================================================
+ *
+ * The legacy header forge. ONE production caller (`index.mjs`), reached only
+ * when the wire adapter declines the request — signature emulation off, or a
+ * pathname the shared package has no surface for. Every `/v1/messages` and
+ * `/v1/messages/count_tokens` turn with emulation on is built by the package
+ * instead, so this function's output is not what the plugin's fingerprint claim
+ * rests on.
+ *
+ * Deleting it is a package-capability question, not a plugin one: when
+ * `@tormentalabs/claude-code-wire-compat` grows a files / models / gateway
+ * surface, this forge and the CC beta constants it consumes go with it.
+ *
+ * @param {Record<string, unknown>} input
+ * @param {RequestInit | undefined} requestInit
+ * @param {string} accessToken
+ */
 export function buildRequestHeaders(
   input,
   requestInit,
@@ -423,12 +551,12 @@ export function buildRequestHeaders(
   const incomingBeta = requestHeaders.get("anthropic-beta") || "";
   const { model, tools, messages, hasFileReferences } = parseRequestBodyMetadata(requestBody);
   // Detect fast mode structurally from the already-transformed body string.
-  // transformRequestBody runs before buildRequestHeaders (see index.mjs:2986 vs 3039),
-  // so speed:"fast" is already present when fast mode fired. Same detection idiom as the
-  // toast check (~line 3018). This is the correct call site for fast-mode: the
-  // computedBetaHeader call at index.mjs:2905 runs BEFORE body transform, so fastModeActive
-  // is always false/absent there, keeping the latch free of fast-mode. The
-  // requestHeaders.set("anthropic-beta", mergedBetas) call below is what reaches the wire.
+  // transformRequestBody runs before buildRequestHeaders in index.mjs, so speed:"fast" is
+  // already present when fast mode fired. This is now the ONLY call site of
+  // buildAnthropicBetaHeader (the pre-transform `computedBetaHeader` caller was deleted in
+  // Phase 4.1), and it is the correct one for fast-mode detection: it runs AFTER the body
+  // transform. The requestHeaders.set("anthropic-beta", mergedBetas) call below is what
+  // reaches the wire.
   const fastModeActive = typeof requestBody === "string" && requestBody.includes('"speed":"fast"');
   const mergedBetas = buildAnthropicBetaHeader(
     incomingBeta,
@@ -440,7 +568,7 @@ export function buildRequestHeaders(
     hasFileReferences,
     adaptiveOverride,
     tokenEconomy,
-    undefined, // microcompactBetas: not available at this call site (handled via computedBetaHeader path at 2905)
+    undefined, // microcompactBetas: not available at this call site (the interceptor computes them)
     fastModeActive, // NEW 12th param: emit fast-mode-2026-02-01 beta when body contains speed:"fast"
   );