@oar-sh/oar 0.9.17 → 0.9.19

package/server/claude-api-worker/claude-api-backend.mjs

@@ -0,0 +1,345 @@
+// The Claude API backend of the Claude session runner: Claude Code on the
+// Anthropic API, billed to the API key saved in Settings → Providers → Claude
+// API instead of the host's Claude login.
+//
+// - The CLI's environment: the key as ANTHROPIC_API_KEY, the Anthropic API as
+//   ANTHROPIC_BASE_URL, and nothing of the host's Claude login, another
+//   Anthropic configuration or another provider's switch. The host's Claude
+//   Code state directory stays (CLAUDE_CONFIG_DIR is left as the relay set
+//   it): the chats are Claude chats, with the Claude provider's sessions,
+//   transcripts, resume and task output.
+// - The flag settings layer: the user's settings and the chat folder's
+//   (.claude/settings.json, .claude/settings.local.json) can set `env`
+//   (another ANTHROPIC_BASE_URL, an ANTHROPIC_API_KEY that replaces the key,
+//   an ANTHROPIC_AUTH_TOKEN that beats it, a proxy, another provider, custom
+//   headers, a CA) and `apiKeyHelper` (a script whose output beats it). The
+//   flag layer outranks them all, so it pins the base URL and the key, blanks
+//   the bearer token and the helper, and holds every other variable that
+//   routes the requests or decides whom the CLI trusts at the CLI's own value
+//   (CLAUDE_CLI_PINNED_ENV, shared with the DeepSeek backend). The spawn's
+//   `--settings` argument, which other users of the host can read, carries
+//   the endpoint and the blanks (claudeApiFlagSettings); the key and the
+//   worker's own proxy and TLS values go into the same layer over the CLI's
+//   stdin before the first message (liveFlagSettings, claude-sdk-adapter.mjs;
+//   scripts/claude-api-cli-proof.mjs shows it).
+// - The check: the CLI's `system/init` names where it took its API key from.
+//   Anything but ANTHROPIC_API_KEY stops the turn as soon as the init is read
+//   (checkInit). The CLI does not wait for that verdict: it sends its first
+//   request some 50 to 90 ms after the init (scripts/claude-api-cli-proof.mjs),
+//   so one request may already be out on the other credential when the stop
+//   lands. The check limits a wrong credential to that one request; it does
+//   not prevent it.
+// - The model, effort, thinking and images: Claude's, exactly as the Claude
+//   worker has them (`claudeModels`).
+// - What it reports: no Claude plan usage (there is no plan) and no Claude
+//   usage limit (the API answers with its own errors, which describeFailure
+//   reads in plain words).
+//
+// - Hooks: none run, neither the user's nor the chat folder's, and no
+//   statusLine command (CLAUDE_CLI_KEY_CHAT_SETTINGS, on the command line).
+//
+// The agent's shell inherits the CLI's environment, the key included; the
+// relay takes the saved key out of what the worker posts and logs.
+
+import { resolveAnthropicApiBaseUrl } from '../../shared/anthropic-api.mjs';
+import { isHostClaudeSessionVariable } from '../../shared/host-claude-session-env.mjs';
+import { CLAUDE_CLI_KEY_CHAT_SETTINGS, claudeCliPinnedEnv } from '../claude-worker/claude-cli-pinned-env.mjs';
+
+export const CLAUDE_API_BACKEND_ID = 'claude-api';
+export const CLAUDE_API_BACKEND_LABEL = 'Claude API';
+// Where the relay's launch puts the key (session-worker-launch-service.mjs).
+export const CLAUDE_API_KEY_ENV = 'OAR_CLAUDE_API_KEY';
+// The stable code of a turn stopped because the CLI took another credential.
+export const CLAUDE_API_KEY_SOURCE_CODE = 'claude-api-key-source';
+// The only API key source the check lets through: the key in the CLI's
+// environment, which is this backend's.
+export const EXPECTED_API_KEY_SOURCE = 'ANTHROPIC_API_KEY';
+// The sources the SDK's `system/init` can name (sdk.d.ts, ApiKeySource). A
+// note names one of these, never a text of the CLI's own.
+const KNOWN_API_KEY_SOURCES = Object.freeze([
+  'ANTHROPIC_API_KEY',
+  'apiKeyHelper',
+  '/login managed key',
+  'none',
+  'user',
+  'project',
+  'org',
+  'temporary',
+  'oauth',
+]);
+
+const BILLING_URL = 'https://platform.claude.com/settings/billing';
+const LIMITS_URL = 'https://platform.claude.com/settings/limits';
+const SETTINGS_PLACE = 'Settings → Providers → Claude API';
+const KEY_SOURCE_GUIDANCE = 'Remove the apiKeyHelper or other credential from the host\'s Claude Code settings '
+  + `(settings.json), check the key in ${SETTINGS_PLACE}, then send the message again.`;
+
+// Variables that would hand the CLI another credential or point it at another
+// endpoint or cloud (the bundled CLI, 2026-10-25). Every ANTHROPIC_* is
+// dropped as well (FOREIGN_CLI_PREFIXES).
+const FOREIGN_CLI_VARIABLES = Object.freeze([
+  // The host's Claude login, and the other ways to hand the CLI a login or
+  // a key.
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR',
+  'CLAUDE_CODE_OAUTH_REFRESH_TOKEN',
+  'CLAUDE_CODE_OAUTH_SCOPES',
+  'CLAUDE_CODE_OAUTH_CLIENT_ID',
+  'CLAUDE_CODE_CUSTOM_OAUTH_URL',
+  'CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR',
+  'CLAUDE_CODE_API_KEY_HELPER_TTL_MS',
+  // Another provider for the CLI's requests, and their auth bypasses.
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+  'CLAUDE_CODE_USE_ANTHROPIC_AWS',
+  'CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD',
+  'CLAUDE_CODE_USE_GATEWAY',
+  'CLAUDE_CODE_USE_MANTLE',
+  'CLAUDE_CODE_USE_CCR_V2',
+  'CLAUDE_CODE_SKIP_BEDROCK_AUTH',
+  'CLAUDE_CODE_SKIP_VERTEX_AUTH',
+  'CLAUDE_CODE_SKIP_FOUNDRY_AUTH',
+  'CLAUDE_CODE_SKIP_MANTLE_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_GOOGLE_CLOUD_AUTH',
+  'CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST',
+  // A host's model and effort pins: the turn's model and effort come from
+  // the relay, which bills them to the key.
+  'CLAUDE_CODE_SUBAGENT_MODEL',
+  'CLAUDE_CODE_SUBAGENT_MODEL_FORCE',
+  'CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL',
+  'CLAUDE_CODE_EFFORT_LEVEL',
+  'CLAUDE_CODE_AUTO_COMPACT_WINDOW',
+  // Never set, and dropped when inherited: it forces the permission mode to
+  // default (plan mode is lost) and sandboxes Bash.
+  'CLAUDE_CODE_SUBPROCESS_ENV_SCRUB',
+  // What the relay hands its worker (session-worker-launch-service.mjs,
+  // TMUX_WORKER_EXPORTED_ENV_VARS): the worker's own settings, which neither
+  // Claude Code nor anything the agent runs reads. A shell of the agent's
+  // that starts a relay of its own would take the worker's kind, folders and
+  // tools file for its own. The relay's Claude configuration
+  // (CLAUDE_CONFIG_DIR, CLAUDE_CODE_EXECUTABLE) is not on it.
+  'COPILOT_ALLOW_ALL',
+  'GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS',
+  'COPILOT_SDK_PATH',
+  'EXTENSION_PATH',
+  'COPILOT_MODEL',
+  'COPILOT_RELAY_MODEL',
+  'CLAUDE_RELAY_MODEL',
+  'CLAUDE_CLOUD_RELAY_MODEL',
+  'CLAUDE_API_RELAY_MODEL',
+  'CURSOR_RELAY_MODEL',
+  'CURSOR_AGENT_STORE_DIR',
+  'CURSOR_API_KEY',
+  'GROK_RELAY_MODEL',
+  'GROK_CLI_COMMAND',
+  'GROK_ALWAYS_APPROVE',
+  'SESSION_ID',
+  'COPILOT_WORKSPACE_ROOT',
+  'INIT_CWD',
+]);
+// The same by prefix: every Anthropic variable (the two the CLI needs are set
+// again below), the relay's folders, config, tools file, worker kind and log
+// file (COPILOT_WEB_RELAY_*), the Copilot provider settings, the DeepSeek
+// worker's settings, every Claude gateway setting and the relay's own OAR_*
+// switches (the key's own variable among them).
+const FOREIGN_CLI_PREFIXES = Object.freeze([
+  'ANTHROPIC_',
+  'COPILOT_WEB_RELAY_',
+  'COPILOT_PROVIDER_',
+  'DEEPSEEK_',
+  'CLAUDE_GATEWAY_',
+  'OAR_',
+]);
+
+/**
+ * Whether a variable of the worker's stays out of the CLI's environment:
+ * another credential, endpoint or provider, the relay's settings for its
+ * worker, or the host Claude Code session's variables when the relay was
+ * started from inside one (shared/host-claude-session-env.mjs; the launcher
+ * drops those for every worker, the backend again, however the worker was
+ * started).
+ */
+function isForeignCliVariable(key) {
+  const name = String(key).toUpperCase();
+  return FOREIGN_CLI_VARIABLES.includes(name)
+    || FOREIGN_CLI_PREFIXES.some((prefix) => name.startsWith(prefix))
+    || isHostClaudeSessionVariable(name);
+}
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+/**
+ * The environment the CLI runs with: the worker's own without anything
+ * foreign, then the key and the endpoint. `OAR_ANTHROPIC_API_BASE_URL` names
+ * a fake API for tests; only a loopback URL is taken from it
+ * (resolveAnthropicApiBaseUrl), anything else is the Anthropic API.
+ */
+export function claudeApiCliEnv(baseEnv = process.env, { apiKey = '', baseUrl = '' } = {}) {
+  const key = text(apiKey);
+  if (!key) throw new Error('claude-api-key-not-configured');
+  const next = {};
+  for (const [name, value] of Object.entries(baseEnv || {})) {
+    if (isForeignCliVariable(name)) continue;
+    next[name] = value;
+  }
+  next.ANTHROPIC_API_KEY = key;
+  next.ANTHROPIC_BASE_URL = text(baseUrl) || resolveAnthropicApiBaseUrl(baseEnv || {});
+  return next;
+}
+
+/**
+ * The flag settings layer every CLI of this backend is spawned with, on its
+ * command line: no key in it. It outranks the user's, the project's and the
+ * local settings, so their `env` cannot send the requests elsewhere or swap
+ * the key for a bearer token, and their `apiKeyHelper` cannot swap it for
+ * its own (nor run at the CLI's startup). No hooks and no statusLine command
+ * run (CLAUDE_CLI_KEY_CHAT_SETTINGS). Skills, plugins and MCP servers are
+ * left as the other layers have them.
+ */
+export function claudeApiFlagSettings(baseUrl) {
+  return {
+    ...CLAUDE_CLI_KEY_CHAT_SETTINGS,
+    env: {
+      ANTHROPIC_BASE_URL: text(baseUrl),
+      ANTHROPIC_AUTH_TOKEN: '',
+    },
+    apiKeyHelper: '',
+  };
+}
+
+/**
+ * The same layer with the key, which the CLI takes over stdin before the
+ * first message (claude-sdk-adapter.mjs): a settings file's
+ * env.ANTHROPIC_API_KEY would otherwise replace the CLI's environment's.
+ * Every other variable that routes the CLI's requests, and with them the key,
+ * or decides whom it trusts on the way (the proxies, the other providers'
+ * switches and endpoints, the custom headers, the CA and TLS settings) holds
+ * the value of `cliEnv`, the environment the CLI was spawned with, or is
+ * blanked (claudeCliPinnedEnv).
+ */
+export function claudeApiLiveFlagSettings(baseUrl, apiKey, cliEnv = {}) {
+  const key = text(apiKey);
+  if (!key) throw new Error('claude-api-key-not-configured');
+  const settings = claudeApiFlagSettings(baseUrl);
+  return { ...settings, env: { ...claudeCliPinnedEnv(cliEnv), ...settings.env, ANTHROPIC_API_KEY: key } };
+}
+
+/** The source the CLI named, as a note may quote it: a known name, or a stand-in. */
+function quotedApiKeySource(value) {
+  const source = typeof value === 'string' ? value : '';
+  if (KNOWN_API_KEY_SOURCES.includes(source)) return `"${source}"`;
+  return source ? 'a source this relay does not know' : 'no source';
+}
+
+/**
+ * Null when the CLI's `system/init` says it took the key from
+ * ANTHROPIC_API_KEY (the backend's), else the Error that stops the turn. Its
+ * message names the source the CLI reported, never a key. `afterTraffic`: the
+ * init came while the turn was already talking to the API, so one request
+ * may have gone out on the other credential.
+ */
+export function checkClaudeApiInit(sdkMessage, { afterTraffic = false } = {}) {
+  if (!sdkMessage || sdkMessage.type !== 'system' || sdkMessage.subtype !== 'init') return null;
+  const source = sdkMessage.apiKeySource;
+  if (source === EXPECTED_API_KEY_SOURCE) return null;
+  const error = new Error(
+    `Claude Code reported ${quotedApiKeySource(source)} as its API key source instead of the saved Claude API key, so the turn was stopped.`
+    + (afterTraffic ? ' At most one request may have gone out on that credential.' : ''),
+  );
+  error.code = CLAUDE_API_KEY_SOURCE_CODE;
+  error.apiKeySource = KNOWN_API_KEY_SOURCES.includes(source) ? source : null;
+  error.guidance = KEY_SOURCE_GUIDANCE;
+  return error;
+}
+
+/**
+ * `{ code, guidance }` for a failed request the Claude API has its own advice
+ * for, or null. Read from the error the runner stopped the turn with, the
+ * HTTP status the result reports, else from the status and the words the CLI
+ * quotes in its error text ("API Error: 401 …"). The account refusals come
+ * first: a spend limit can come as a 429, which is not a rate limit.
+ */
+export function describeClaudeApiFailure(errorText, { status = null, error = null } = {}) {
+  if (error?.code === CLAUDE_API_KEY_SOURCE_CODE) {
+    return { code: CLAUDE_API_KEY_SOURCE_CODE, guidance: error.guidance || KEY_SOURCE_GUIDANCE };
+  }
+  const message = text(errorText);
+  const code = Number(status);
+  if (/credit balance is too low/i.test(message)) {
+    return {
+      code: 'claude-api-credit',
+      guidance: `The Claude API account's credit balance is too low. Add credits in the Claude Console (${BILLING_URL}), then send the message again.`,
+    };
+  }
+  if (/API usage limits|enforced_spend_limit_reached/i.test(message)) {
+    return {
+      code: 'claude-api-spend-limit',
+      guidance: `The Claude API account has reached its spend limit. Raise the limit in the Claude Console (${LIMITS_URL}) or wait until it resets, then send the message again.`,
+    };
+  }
+  if (code === 402 || /\b402\b|billing_error/i.test(message)) {
+    return {
+      code: 'claude-api-billing',
+      guidance: `The Claude API refused the request for a billing reason. Check the payment details in the Claude Console (${BILLING_URL}), then send the message again.`,
+    };
+  }
+  if (
+    code === 401
+    || code === 403
+    || /\b40[13]\b|authentication_error|permission_error|invalid x-api-key|invalid api key/i.test(message)
+  ) {
+    return {
+      code: 'claude-api-key',
+      guidance: `The Claude API did not accept the API key. Check it in ${SETTINGS_PLACE}, then send the message again.`,
+    };
+  }
+  if (code === 429 || code === 529 || /\b(?:429|529)\b|rate_limit_error|overloaded_error/i.test(message)) {
+    return {
+      code: 'claude-api-rate-limit',
+      guidance: `The Claude API is rate-limiting this key or is overloaded. Send the message again in a moment; the key's rate limits are in the Claude Console (${LIMITS_URL}).`,
+    };
+  }
+  return null;
+}
+
+export function createClaudeApiClaudeBackend({ env = process.env } = {}) {
+  const apiKey = text(env[CLAUDE_API_KEY_ENV]);
+  const baseUrl = resolveAnthropicApiBaseUrl(env);
+
+  return {
+    id: CLAUDE_API_BACKEND_ID,
+    providerType: CLAUDE_API_BACKEND_ID,
+    label: CLAUDE_API_BACKEND_LABEL,
+    // Claude's models, effort, thinking, `[1m]`, images and sub-agent models,
+    // exactly as the Claude worker has them: the runner and the adapter take
+    // none of those from this backend.
+    claudeModels: true,
+    // No plan windows and no subscription usage limit on an API key, and no
+    // usage route of its own.
+    reportsPlanUsage: false,
+    reportsUsageLimit: false,
+    usageRoute: null,
+    describeFailure: describeClaudeApiFailure,
+    checkInit: checkClaudeApiInit,
+    /** The settings layer pin, merged into the spawn's `settings` (no key in it). */
+    flagSettings: () => claudeApiFlagSettings(baseUrl),
+    /**
+     * The layer again with the key and the routing and trust pins for a CLI
+     * spawned with `cliEnv`, over stdin before the first message.
+     */
+    liveFlagSettings: (cliEnv = claudeApiCliEnv(env, { apiKey, baseUrl })) => claudeApiLiveFlagSettings(baseUrl, apiKey, cliEnv),
+
+    /**
+     * The CLI's environment, built from the worker's own (which must not
+     * reach the CLI as it is: it carries OAR_CLAUDE_API_KEY and possibly the
+     * host's login or Anthropic settings).
+     */
+    spawnEnv(baseEnv = process.env) {
+      return claudeApiCliEnv(baseEnv, { apiKey, baseUrl });
+    },
+  };
+}

package/server/claude-api-worker/claude-api-session-worker.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Claude API session worker: the Claude session worker with its CLI on the
+// Anthropic API and the key saved in Settings → Providers → Claude API
+// (claude-api-backend.mjs). The relay's launch puts the key in
+// OAR_CLAUDE_API_KEY (through the owner-only secret file under tmux) and the
+// chat's model in CLAUDE_API_RELAY_MODEL. The CLI keeps the host's Claude
+// Code state directory: the chats are Claude chats, resumed and read where
+// the Claude worker reads them.
+import { installWorkerLogFile, installWorkerLogRedaction } from '../../shared/worker-runtime/worker-log-file.mjs';
+import { runClaudeSessionWorker } from '../claude-worker/claude-session-worker-main.mjs';
+import { CLAUDE_API_KEY_ENV, createClaudeApiClaudeBackend } from './claude-api-backend.mjs';
+
+installWorkerLogFile();
+// The key never shows in this worker's console or log, whatever the CLI or
+// the agent prints (installed after the log file, so its copy is redacted too).
+installWorkerLogRedaction({ secrets: [process.env[CLAUDE_API_KEY_ENV]] });
+
+const backend = createClaudeApiClaudeBackend({ env: process.env });
+
+runClaudeSessionWorker({
+  logTag: 'claude-api-worker',
+  workerName: 'claude-api-session-worker',
+  // None set: the CLI's own default, as for a Claude chat without a model.
+  defaultModel: String(process.env.CLAUDE_API_RELAY_MODEL || '').trim(),
+  backend,
+}).catch((error) => {
+  console.error('claude-api-session-worker fatal:', error?.stack || error?.message || error);
+  process.exit(1);
+});

package/server/claude-worker/claude-cli-pinned-env.mjs

@@ -0,0 +1,150 @@
+// The CLI's routing and trust variables a chat folder's settings must not
+// set, shared by the backends that run Claude Code on a key of the relay's
+// (DeepSeek, Claude API): each pins them in its live flag settings. And the
+// settings both spawn the CLI with: no hooks (CLAUDE_CLI_KEY_CHAT_SETTINGS).
+//
+// The list comes from the bundled CLI and only from it. On every SDK or CLI
+// bump, re-run both proofs (scripts/deepseek-cli-proof.mjs,
+// scripts/claude-api-cli-proof.mjs) and the env-name grep over that binary
+// (fixed names, grep -a, under timeout and nice; never a regex over the
+// whole binary), and update the list and its source line below.
+
+/**
+ * Every variable through which the env of the chat folder's settings
+ * (.claude/settings.json, settings.local.json) could send the CLI's requests,
+ * and with them the key, somewhere else, or change whom the CLI trusts on the
+ * way: the endpoints, the provider switches, the credentials, the proxies and
+ * the TLS trust. The DeepSeek and the Claude API backends pin each one in
+ * their live flag settings (liveFlagSettings), which the CLI applies over the
+ * folder's, to the value the CLI was spawned with: the worker's own, else the
+ * other case's for a proxy variable, else ''.
+ * '' is unset to the CLI for each of these (truthy or trimmed reads), except
+ * SSL_CERT_FILE and SSL_CERT_DIR: '' empties OpenSSL's and Node's system
+ * store, so those two are pinned only when the worker sets them.
+ *
+ * Source: the names Claude Code 2.1.304 (the bundled CLI) reads, by a grep
+ * of the binary; the CLI's own lists of endpoints (with their selection
+ * switches and companions) and credentials are in it as they are there. A
+ * deny-list, because a settings layer can only pin names known in advance.
+ * Left out, each for its reason: the model variables (same endpoint, same
+ * key), what the CLI already drops from a folder's settings or from all
+ * settings (CLAUDE_CONFIG_DIR, CLAUDE_CODE_CUSTOM_OAUTH_URL, the OTEL
+ * exporter endpoints, ANTHROPIC_UNIX_SOCKET, the host-managed provider
+ * switches, the file-descriptor credentials), a provider's own SDK settings
+ * (AWS_*, GOOGLE_*, AZURE_*, read only for the provider the switches here
+ * turn off), NODE_OPTIONS (at runtime the CLI reads only its system-CA
+ * flags, which add no CA), and what routes only other programs' traffic
+ * (NPM_CONFIG_*, GIT_*, the resolver's variables).
+ */
+export const CLAUDE_CLI_PINNED_ENV = Object.freeze([
+  // Endpoints: the CLI's list, its fallback and the headers sent with them.
+  'ANTHROPIC_BASE_URL',
+  '_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL',
+  'ANTHROPIC_CUSTOM_HEADERS',
+  'ANTHROPIC_BEDROCK_BASE_URL',
+  'ANTHROPIC_VERTEX_BASE_URL',
+  'ANTHROPIC_FOUNDRY_BASE_URL',
+  'ANTHROPIC_AWS_BASE_URL',
+  'ANTHROPIC_GOOGLE_CLOUD_BASE_URL',
+  'ANTHROPIC_BEDROCK_MANTLE_BASE_URL',
+  'CLAUDE_CODE_API_BASE_URL',
+  'CLAUDE_CODE_ARTIFACTS_API_BASE_URL',
+  'CLAUDE_CODE_ARTIFACTS_API_TOKEN',
+  'CLAUDE_CODE_ARTIFACT_ASSET_BASE_URL',
+  'CLAUDE_CODE_ARTIFACT_LIVE_BASE_URL',
+  'CLAUDE_CODE_ARTIFACT_SYNC_BASE_URL',
+  'CLAUDE_CODE_ARTIFACT_VIEWER_BASE_URL',
+  'CLAUDE_CODE_MEMORY_API_BASE_URL',
+  'CLAUDE_CODE_MEMORY_API_TOKEN',
+  // Provider switches.
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+  'CLAUDE_CODE_USE_ANTHROPIC_AWS',
+  'CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD',
+  'CLAUDE_CODE_USE_MANTLE',
+  'CLAUDE_CODE_USE_GATEWAY',
+  'CLAUDE_CODE_SKIP_BEDROCK_AUTH',
+  'CLAUDE_CODE_SKIP_VERTEX_AUTH',
+  'CLAUDE_CODE_SKIP_FOUNDRY_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_GOOGLE_CLOUD_AUTH',
+  'CLAUDE_CODE_SKIP_MANTLE_AUTH',
+  // Credentials: the CLI's list, the OAuth login, the federation profile and
+  // the proxy credential helper.
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'AWS_BEARER_TOKEN_BEDROCK',
+  'ANTHROPIC_FOUNDRY_API_KEY',
+  'ANTHROPIC_FOUNDRY_AUTH_TOKEN',
+  'ANTHROPIC_AWS_API_KEY',
+  'CLAUDE_CODE_OAUTH_REFRESH_TOKEN',
+  'CLAUDE_CODE_OAUTH_SCOPES',
+  'CLAUDE_CODE_OAUTH_CLIENT_ID',
+  'ANTHROPIC_PROFILE',
+  'ANTHROPIC_IDENTITY_TOKEN',
+  'ANTHROPIC_IDENTITY_TOKEN_FILE',
+  'ANTHROPIC_FEDERATION_RULE_ID',
+  'ANTHROPIC_ORGANIZATION_ID',
+  'ANTHROPIC_SERVICE_ACCOUNT_ID',
+  'ANTHROPIC_SCOPE',
+  'ANTHROPIC_WORKSPACE_ID',
+  'CLAUDE_CODE_ENABLE_PROXY_AUTH_HELPER',
+  // Proxies: the CLI reads both cases, the lower one first.
+  'HTTPS_PROXY',
+  'https_proxy',
+  'HTTP_PROXY',
+  'http_proxy',
+  'ALL_PROXY',
+  'all_proxy',
+  'NO_PROXY',
+  'no_proxy',
+  'CLAUDE_CODE_HTTPS_PROXY',
+  'CLAUDE_CODE_HTTP_PROXY',
+  // TLS trust and the client certificate.
+  'NODE_TLS_REJECT_UNAUTHORIZED',
+  'NODE_EXTRA_CA_CERTS',
+  'CLAUDE_CODE_CERT_STORE',
+  'CLAUDE_CODE_CLIENT_CERT',
+  'CLAUDE_CODE_CLIENT_KEY',
+  'CLAUDE_CODE_CLIENT_KEY_PASSPHRASE',
+  'SSL_CERT_FILE',
+  'SSL_CERT_DIR',
+]);
+// The two of CLAUDE_CLI_PINNED_ENV for which '' is not unset (see there).
+const PINNED_ONLY_WHEN_SET = new Set(['SSL_CERT_FILE', 'SSL_CERT_DIR']);
+// The proxy variables the CLI and the tools it runs read in either case.
+const OTHER_CASE = new Map(
+  ['HTTPS_PROXY', 'HTTP_PROXY', 'ALL_PROXY', 'NO_PROXY'].flatMap((name) => [
+    [name, name.toLowerCase()],
+    [name.toLowerCase(), name],
+  ]),
+);
+
+/**
+ * The settings both backends spawn every CLI with, on its command line (their
+ * flagSettings): no hooks and no statusLine command, neither the user's nor
+ * the chat folder's nor a plugin's. Those run as the relay's user with the
+ * CLI's environment, the key in it, and a folder's SessionStart hook would run
+ * before the live pins land. The SDK has the spawn settings in force before
+ * any hook (sdk.d.ts, Options.settings; scripts/claude-cli-hooks-proof.mjs
+ * shows it). Hooks in managed settings still run: those are the host admin's.
+ * OAR's Claude worker registers no SDK hooks of its own.
+ */
+export const CLAUDE_CLI_KEY_CHAT_SETTINGS = Object.freeze({ disableAllHooks: true });
+
+/**
+ * The pins of CLAUDE_CLI_PINNED_ENV for a CLI spawned with `cliEnv`: the
+ * value it was spawned with, else the other case's (a proxy the worker sets
+ * as https_proxy holds for HTTPS_PROXY as well), else ''.
+ */
+export function claudeCliPinnedEnv(cliEnv = {}) {
+  const pins = {};
+  for (const name of CLAUDE_CLI_PINNED_ENV) {
+    const own = cliEnv[name] ?? cliEnv[OTHER_CASE.get(name)];
+    if (own !== undefined) pins[name] = String(own);
+    else if (!PINNED_ONLY_WHEN_SET.has(name)) pins[name] = '';
+  }
+  return pins;
+}

package/server/claude-worker/claude-remote-relay-tool.mjs

@@ -1,8 +1,8 @@
 /**
- * The relay's `remote_relay` tool for the Claude worker, shaped as an SDK MCP
+ * The relay's `relay_tool` tool for the Claude worker, shaped as an SDK MCP
  * tool definition (`{ name, description, inputSchema, handler }`) so the
  * adapter can hand it to `createSdkMcpServer` next to the preview tool. On the
- * wire it is `mcp__relay__remote_relay`; the module never imports the SDK.
+ * wire it is `mcp__relay__relay_tool`; the module never imports the SDK.
  */
 
 import * as z from 'zod';
@@ -11,7 +11,6 @@ import {
   REMOTE_RELAY_ACTIONS,
   REMOTE_RELAY_IF_BUSY,
   REMOTE_RELAY_MODES,
-  REMOTE_RELAY_PROVIDERS,
   REMOTE_RELAY_SESSION_SCOPES,
   REMOTE_RELAY_THINKING_DISPLAYS,
 } from '../../shared/remote-relay-contract.mjs';
@@ -61,7 +60,8 @@ export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
   before: text('before'),
   include_activity: z.boolean().optional().describe(FIELDS.include_activity.description),
   max_chars: number('max_chars'),
-  provider: choice('provider', REMOTE_RELAY_PROVIDERS),
+  // Free text: the worker outlives relay updates, the relay checks the id.
+  provider: text('provider'),
   model: text('model'),
   cwd: text('cwd'),
   repo: text('repo'),
@@ -140,7 +140,7 @@ export function createRemoteRelayToolDefinition({ api, getConversationId = () =>
         // A tool exception would surface as a failed MCP call and can abort
         // the turn; a refusal the model can read cannot.
         const message = error?.message || String(error);
-        dbg('remote_relay tool failed', message);
+        dbg('relay_tool failed', message);
         result = { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: message };
       }
       return { content: [{ type: 'text', text: formatRemoteRelayToolResult(result) }] };

package/server/claude-worker/claude-sdk-adapter.mjs

@@ -11,7 +11,7 @@ import { CLAUDE_LIVE_FLAG_SETTINGS_CODE, CLAUDE_LIVE_FLAG_SETTINGS_GUIDANCE } fr
 export { CLAUDE_LIVE_FLAG_SETTINGS_CODE };
 
 // The name the in-process MCP server is registered under; it prefixes every
-// tool it carries on the wire (`mcp__relay__preview`, `mcp__relay__remote_relay`).
+// tool it carries on the wire (`mcp__relay__preview`, `mcp__relay__relay_tool`).
 export const RELAY_MCP_SERVER_NAME = 'relay';
 
 // The per-server tool-call timeout the CLI applies to the relay's tools.
@@ -19,7 +19,7 @@ export const RELAY_MCP_SERVER_NAME = 'relay';
 // value, else by the MCP_TOOL_TIMEOUT environment variable, else by 1e8 ms —
 // and SDK servers are exempt from the idle timeout. Pinning it here keeps a
 // host-wide MCP_TOOL_TIMEOUT (set for some other server) from cutting off a
-// remote_relay wait: those run up to wait_seconds (≤ 600 s) plus however long
+// relay_tool wait: those run up to wait_seconds (≤ 600 s) plus however long
 // an approval card sits unanswered.
 export const RELAY_MCP_TOOL_TIMEOUT_MS = REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS;
 
@@ -122,6 +122,23 @@ export function claudeSpawnSettings({ ultracode = false, autoCompactWindow = nul
   return Object.keys(settings).length ? settings : null;
 }
 
+/**
+ * The spawn's `settings` with a backend's flag settings on top: null when
+ * neither has anything, the relay's object untouched when the backend has
+ * nothing to add. `env` is merged by name, so neither side drops the other's
+ * variables.
+ */
+export function mergeSpawnSettings(spawnSettings, backendSettings) {
+  const own = spawnSettings && typeof spawnSettings === 'object' ? spawnSettings : null;
+  const extra = backendSettings && typeof backendSettings === 'object' && Object.keys(backendSettings).length
+    ? backendSettings
+    : null;
+  if (!extra) return own;
+  const merged = { ...(own || {}), ...extra };
+  if (own?.env || extra.env) merged.env = { ...(own?.env || {}), ...(extra.env || {}) };
+  return merged;
+}
+
 /**
  * Live twin of the attribution spawn setting, for a value (OAR or off). A
  * running CLI takes a new text through the flag layer (it arrives as a fresh
@@ -209,7 +226,7 @@ export function systemPromptForRelayMode(relayMode, { backgroundCommandLimitMs =
  * payload. `getConversationId` is called per tool call because a process
  * outlives the turn it was spawned for.
  *
- * `remote_relay` is the exception: it rides along only when the worker found
+ * `relay_tool` is the exception: it rides along only when the worker found
  * at least one paired remote (`remoteRelayTool`), because a tool that can do
  * nothing on a relay without remotes would only cost context on every turn.
  */
@@ -375,7 +392,7 @@ export function startClaudeSession({
   pathToClaudeCodeExecutable = '',
   api = null,
   getConversationId = () => '',
-  // Whether this process carries `remote_relay` (the worker's registration
+  // Whether this process carries `relay_tool` (the worker's registration
   // decision). Fixed for the process: the tool list is part of the spawn.
   remoteRelayTool = false,
   // Another endpoint for the CLI (null = Anthropic through the host's Claude
@@ -387,15 +404,24 @@ export function startClaudeSession({
   dbg = () => {},
 } = {}) {
   const normalizedModel = String(model || '').trim().toLowerCase();
-  const effort = backend ? '' : normalizeClaudeEffort(reasoningEffort);
+  // A backend on Claude's own models (the Claude API backend) takes the
+  // model and the effort exactly as Claude does; only another provider's
+  // backend maps them into its terms.
+  const modelBackend = backend && backend.claudeModels !== true ? backend : null;
+  const effort = modelBackend ? '' : normalizeClaudeEffort(reasoningEffort);
   const ultracode = effort === CLAUDE_ULTRACODE_EFFORT;
-  const effortOption = backend ? backend.effortOption(reasoningEffort) : (ultracode ? 'xhigh' : effort);
-  const cliModel = backend ? backend.cliModel(model) : String(model || '').trim();
+  const effortOption = modelBackend ? modelBackend.effortOption(reasoningEffort) : (ultracode ? 'xhigh' : effort);
+  const cliModel = modelBackend ? modelBackend.cliModel(model) : String(model || '').trim();
   // Spawn-time twin of the flag-settings helpers: the settings layer is the
   // only way to hand a fresh CLI the session-scoped ultracode flag, the
   // auto-compact window and the thinking pin, and all three share one
-  // `settings` object.
-  const spawnSettings = claudeSpawnSettings({ ultracode, autoCompactWindow, thinkingEnabled, attribution });
+  // `settings` object. A backend's own pins (no hooks for both, the Claude
+  // API backend's endpoint and blanked credentials) join them; theirs win a
+  // clash.
+  const spawnSettings = mergeSpawnSettings(
+    claudeSpawnSettings({ ultracode, autoCompactWindow, thinkingEnabled, attribution }),
+    typeof backend?.flagSettings === 'function' ? backend.flagSettings() : null,
+  );
   // Relay tools need the worker's authenticated API helper; a caller that
   // passes none (tests, probes) gets a session without them.
   const relayMcpServer = typeof api === 'function'