opencode-anthropic-fix 0.6.0 → 2.0.0

package/lib/config.mjs

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
+import { OAUTH_CLIENT_ID } from "./oauth-constants.mjs";
+import { PROJECT_SCOPES } from "./oauth-scopes.mjs";
 
 /**
  * @typedef {'sticky' | 'round-robin' | 'hybrid' | 'single'} AccountSelectionStrategy
@@ -104,7 +106,7 @@ import { randomBytes } from "node:crypto";
  * @property {{ enabled: boolean, default_cooldown_ms: number, poll_quota_on_overload: boolean }} overload_recovery
  * @property {{ proactive_disabled: boolean }} account_management
  * @property {{ enabled: boolean }} anti_verbosity
- * @property {{ sdk_token_useragent: boolean }} oauth
+ * @property {{ sdk_token_useragent: boolean, revoke_on_logout: boolean, plugins_scope: boolean, project_scopes: string[] }} oauth
  */
 
 /** @type {AnthropicAuthConfig} */
@@ -438,22 +440,51 @@ export const DEFAULT_CONFIG = {
   },
   /** OAuth token-endpoint request fingerprint. */
   oauth: {
-    /** When true (DEFAULT), the OAuth token EXCHANGE/REFRESH POSTs use Claude
-     *  Code 2.1.195's SDK-native-fetch fingerprint (`User-Agent:
-     *  anthropic-sdk-typescript/0.94.0 userOAuthProvider`, `anthropic-beta:
-     *  oauth-2025-04-20`, no axios `Accept`). When false, the legacy axios
-     *  fingerprint (`User-Agent: axios/1.13.6`, axios `Accept` header) is sent
-     *  byte-for-byte as before.
-     *  Default ON to match upstream CC 2.1.195's userOAuthProvider. Set to
-     *  `false` to revert to the legacy axios/1.13.6 + `Accept` fingerprint. */
+    /** [DEPRECATED — has no effect] Formerly selected between the SDK
+     *  fingerprint and a legacy `axios/1.13.6` one. Claude Code 2.1.280 has no
+     *  axios OAuth path, so setting this to `false` did not make a user more
+     *  anonymous — it made them the only client on the network sending that
+     *  shape. The axios path is removed; every token request now carries
+     *  `anthropic-sdk-typescript/0.112.1 userOAuthProvider`.
+     *  The key stays recognised so existing config files keep loading, and an
+     *  explicit value warns once per process.
+     *  @see docs/oauth-2.1.280-contract.md §7 divergence D2 */
     sdk_token_useragent: true,
+    /** Attempt RFC 7009 server-side revocation on logout. Default OFF.
+     *  `/v1/oauth/revoke` appears nowhere in the Claude Code 2.1.280 bundle, so
+     *  every revocation is a request that identifies this client. It is kept as
+     *  an opt-in rather than deleted, because users who want the affordance
+     *  should be able to choose it knowingly.
+     *  @see docs/oauth-2.1.280-contract.md §7 divergence D1 */
+    revoke_on_logout: false,
+    /** Request the `user:plugins` scope at authorize time. Default OFF.
+     *  §13.8 records that the genuine client appends `user:plugins` when its
+     *  `PLUGINS_SCOPE_REGISTERED` gate is on, but does not record the gate's
+     *  shipped state. Defaulting to off preserves the previously-emitted
+     *  five-scope string byte for byte; it is not a claim that the genuine
+     *  default is off.
+     *  @see docs/oauth-2.1.280-contract.md §4.2, §7 divergence D9 */
+    plugins_scope: false,
+    /** Extra project scopes to request at authorize time. Default none.
+     *  Only `user:projects:read` and `user:projects:write` are recognised;
+     *  anything else is dropped by the scope composer rather than forwarded,
+     *  because an unrecognised scope in the authorize URL is a fingerprint and
+     *  is likely to be rejected by the server. (§13.8 does not record how the
+     *  authorize endpoint treats an unknown scope, so "likely" is the strongest
+     *  claim the evidence supports.) A dropped entry is warned about once at
+     *  config-load time so the user is not left wondering.
+     *  @see docs/oauth-2.1.280-contract.md §4.2, §7 divergence D9 */
+    project_scopes: Object.freeze([]),
   },
 };
 
 export const VALID_STRATEGIES = ["sticky", "round-robin", "hybrid", "single"];
 
-/** OpenCode's OAuth client ID for Anthropic console auth flows. */
-export const CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+/** The OAuth client ID for Anthropic auth flows.
+ *  Re-exported from ./oauth-constants.mjs so there is exactly one literal in
+ *  the repository; this alias exists for the call sites that already import it
+ *  from here. */
+export const CLIENT_ID = OAUTH_CLIENT_ID;
 
 /**
  * Build a deep-cloned config object from defaults.
@@ -487,7 +518,7 @@ function createDefaultConfig() {
     microcompact: { ...DEFAULT_CONFIG.microcompact },
     overload_recovery: { ...DEFAULT_CONFIG.overload_recovery },
     account_management: { ...DEFAULT_CONFIG.account_management },
-    oauth: { ...DEFAULT_CONFIG.oauth },
+    oauth: { ...DEFAULT_CONFIG.oauth, project_scopes: [...DEFAULT_CONFIG.oauth.project_scopes] },
   };
 }
 
@@ -537,6 +568,12 @@ function clampNumber(value, min, max, fallback) {
  */
 let contextHintDeprecationWarned = false;
 
+/** One-time latch for the `oauth.sdk_token_useragent` deprecation warning. */
+let sdkTokenUserAgentDeprecationWarned = false;
+
+/** One-time latch for the `oauth.project_scopes` unrecognised-entry warning. */
+let projectScopesDropWarned = false;
+
 function validateConfig(raw) {
   const config = createDefaultConfig();
 
@@ -1045,9 +1082,50 @@ function validateConfig(raw) {
   // OAuth token-endpoint fingerprint sub-config
   if (raw.oauth && typeof raw.oauth === "object") {
     const o = /** @type {Record<string, unknown>} */ (raw.oauth);
+
+    // Non-silent deprecation. Any explicit value warns, because both values now
+    // produce the same request: a user who set `false` deliberately is relying
+    // on behaviour that no longer exists and deserves to be told, and a user who
+    // set `true` is carrying a setting that no longer means anything.
+    if (typeof o.sdk_token_useragent === "boolean" && !sdkTokenUserAgentDeprecationWarned) {
+      sdkTokenUserAgentDeprecationWarned = true;
+
+      // The message deliberately carries no `2.1.<NN>` literal. A version string
+      // in production source is exactly what the version-literals conformance
+      // guard exists to forbid, and weakening that guard for a log line would
+      // trade a real invariant for a cosmetic one.
+      console.warn(
+        "[anthropic-auth] oauth.sdk_token_useragent is deprecated and has no effect: " +
+          "no axios OAuth path exists in the genuine client, so token requests always send " +
+          "the SDK user-agent. See the OAuth wire contract doc, divergence D2. " +
+          "Remove the setting from your config to silence this warning.",
+      );
+    }
+
+    // Unrecognised project scopes are dropped here AND downstream by the scope
+    // composer. Dropping silently in two places is how a user ends up staring
+    // at a typo that produces no error and no scope, so say it once.
+    let projectScopes = [...DEFAULT_CONFIG.oauth.project_scopes];
+    if (Array.isArray(o.project_scopes)) {
+      const requested = o.project_scopes.filter((s) => typeof s === "string");
+      projectScopes = requested.filter((s) => PROJECT_SCOPES.includes(s));
+      const dropped = requested.filter((s) => !PROJECT_SCOPES.includes(s));
+      if (dropped.length > 0 && !projectScopesDropWarned) {
+        projectScopesDropWarned = true;
+        console.warn(
+          `[anthropic-auth] oauth.project_scopes contains unrecognised entries that were dropped: ` +
+            `${dropped.join(", ")}. Recognised values are: ${PROJECT_SCOPES.join(", ")}.`,
+        );
+      }
+    }
+
     config.oauth = {
       sdk_token_useragent:
         typeof o.sdk_token_useragent === "boolean" ? o.sdk_token_useragent : DEFAULT_CONFIG.oauth.sdk_token_useragent,
+      revoke_on_logout:
+        typeof o.revoke_on_logout === "boolean" ? o.revoke_on_logout : DEFAULT_CONFIG.oauth.revoke_on_logout,
+      plugins_scope: typeof o.plugins_scope === "boolean" ? o.plugins_scope : DEFAULT_CONFIG.oauth.plugins_scope,
+      project_scopes: projectScopes,
     };
   }
 

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 = 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 PROMPT_CACHING_SCOPE_BETA = "prompt-caching-scope-2026-01-05";
+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";
 
@@ -139,18 +240,21 @@ export const ADAPTER_ENV_KEYS = Object.freeze([
  * PROFILE INHERITANCE POLICY. The adapter never passes an explicit `profile`
  * argument to the package's entry points; omitting it IS the mechanism by which
  * the plugin inherits whatever `DEFAULT_PROFILE` the installed
- * `@tormentalabs/claude-code-wire-compat` declares. The dependency is tracked at
- * 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.
+ * `@tormentalabs/claude-code-wire-compat` declares. Under the `latest` dist-tag
+ * each package release can advance the default profile and the plugin follows
+ * without a code change to the composition path. The dependency is currently
+ * pinned to an exact version instead, holding the default profile back until the
+ * plugin is ported to the next one (docs/shared-package-provenance.md).
+ *
+ * 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 +281,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 +489,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 +743,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"
   );