@bitkyc08/opencodex 2.7.8 → 2.7.9-preview.20260712

package/src/claude/outbound.ts

@@ -0,0 +1,487 @@
+/**
+ * Claude Code outbound: internal /v1/responses output -> Anthropic Messages API shapes.
+ *
+ * Wire contract pinned in devlog/260711_claude_inbound/003_evidence.md (all Tier 2):
+ *  - SSE order: message_start -> (content_block_start -> deltas -> content_block_stop)*
+ *    -> message_delta -> message_stop; any number of `ping`.
+ *  - thinking blocks get thinking_delta(s) then ONE synthetic signature_delta just
+ *    before content_block_stop (CCR precedent: Claude Code does not verify signatures).
+ *  - message_delta.usage is cumulative; message_start embeds a full message snapshot.
+ *  - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200.
+ */
+
+type Rec = Record<string, unknown>;
+
+function isRec(v: unknown): v is Rec {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function uuid(): string {
+  return crypto.randomUUID().replace(/-/g, "");
+}
+
+/** HTTP status -> Anthropic error taxonomy (010 amendment #4; full official table per devlog 100). */
+export function anthropicErrorType(status: number): string {
+  switch (status) {
+    case 400: return "invalid_request_error";
+    case 401: return "authentication_error";
+    case 402: return "billing_error";
+    case 403: return "permission_error";
+    case 404: return "not_found_error";
+    case 409: return "conflict_error";
+    case 413: return "request_too_large";
+    case 429: return "rate_limit_error";
+    case 504: return "timeout_error";
+    case 529: return "overloaded_error";
+    default: return status >= 500 ? "api_error" : "invalid_request_error";
+  }
+}
+
+export function anthropicErrorBody(status: number, message: string, type?: string): Rec {
+  return { type: "error", error: { type: type ?? anthropicErrorType(status), message } };
+}
+
+export function anthropicErrorResponse(status: number, message: string, type?: string): Response {
+  return new Response(JSON.stringify(anthropicErrorBody(status, message, type)), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/**
+ * Responses usage -> Anthropic usage. Responses `input_tokens` is INCLUSIVE of cache
+ * read+write (types.ts convention); Anthropic `input_tokens` excludes both, so
+ * subtract the full cache detail (devlog 070 — subtracting reads only inflated the
+ * non-cached input Claude Code displays by the write share).
+ */
+export function anthropicUsage(usage: unknown): Rec {
+  const u = isRec(usage) ? usage : {};
+  const details = isRec(u.input_tokens_details) ? u.input_tokens_details : {};
+  const cached = typeof details.cached_tokens === "number" ? details.cached_tokens : 0;
+  const cacheWrite = typeof details.cache_write_tokens === "number" ? details.cache_write_tokens : 0;
+  const input = typeof u.input_tokens === "number" ? u.input_tokens : 0;
+  const output = typeof u.output_tokens === "number" ? u.output_tokens : 0;
+  return {
+    input_tokens: Math.max(0, input - cached - cacheWrite),
+    output_tokens: output,
+    cache_read_input_tokens: cached,
+    cache_creation_input_tokens: cacheWrite,
+  };
+}
+
+function sseFrame(name: string, data: Rec): string {
+  return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+function messageSnapshot(model: string): Rec {
+  return {
+    id: `msg_${uuid()}`,
+    type: "message",
+    role: "assistant",
+    content: [],
+    model,
+    stop_reason: null,
+    stop_sequence: null,
+    usage: { input_tokens: 0, output_tokens: 0 },
+  };
+}
+
+interface OpenBlock {
+  kind: "text" | "thinking" | "tool_use";
+  index: number;
+  /** Responses item_id (tool calls) so output_item.done can match. */
+  itemId?: string;
+}
+
+/** Streaming: Responses SSE bytes -> Anthropic Messages SSE bytes. */
+export function responsesSseToAnthropicSse(
+  upstream: ReadableStream<Uint8Array>,
+  model: string,
+  opts?: { pingIntervalMs?: number },
+): ReadableStream<Uint8Array> {
+  const pingIntervalMs = opts?.pingIntervalMs ?? 20_000;
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buffer = "";
+  let started = false;
+  let terminated = false;
+  let blockIndex = 0;
+  let open: OpenBlock | null = null;
+  let sawToolUse = false;
+  let pingTimer: ReturnType<typeof setInterval> | undefined;
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const emit = (name: string, data: Rec) => controller.enqueue(encoder.encode(sseFrame(name, data)));
+      const ensureStarted = () => {
+        if (started) return;
+        started = true;
+        emit("message_start", { type: "message_start", message: messageSnapshot(model) });
+        emit("ping", { type: "ping" });
+      };
+      // Idle keepalive (devlog 100): real Anthropic streams may interleave pings anywhere;
+      // synthesizing one during upstream silence protects remote deployments behind
+      // LB/NAT idle timeouts and covers slow first tokens. Cheap and spec-legal.
+      if (pingIntervalMs > 0) {
+        pingTimer = setInterval(() => {
+          if (terminated) return;
+          try {
+            ensureStarted();
+            emit("ping", { type: "ping" });
+          } catch { /* controller torn down; the read loop is ending anyway */ }
+        }, pingIntervalMs);
+      }
+      const closeOpenBlock = () => {
+        if (!open) return;
+        if (open.kind === "thinking") {
+          // Synthetic signature: Claude Code accepts it (003 E6); inbound drops replays anyway.
+          emit("content_block_delta", {
+            type: "content_block_delta", index: open.index,
+            delta: { type: "signature_delta", signature: `ocx${Date.now()}` },
+          });
+        }
+        emit("content_block_stop", { type: "content_block_stop", index: open.index });
+        open = null;
+      };
+      const ensureBlock = (kind: "text" | "thinking") => {
+        ensureStarted();
+        if (open && open.kind === kind) return;
+        closeOpenBlock();
+        const index = blockIndex++;
+        const contentBlock: Rec = kind === "text"
+          ? { type: "text", text: "" }
+          : { type: "thinking", thinking: "", signature: "" };
+        emit("content_block_start", { type: "content_block_start", index, content_block: contentBlock });
+        open = { kind, index };
+      };
+      const finish = (stopReason: string, usage: unknown) => {
+        if (terminated) return;
+        terminated = true;
+        ensureStarted();
+        closeOpenBlock();
+        emit("message_delta", {
+          type: "message_delta",
+          delta: { stop_reason: stopReason, stop_sequence: null },
+          usage: anthropicUsage(usage),
+        });
+        emit("message_stop", { type: "message_stop" });
+      };
+      const fail = (status: number, message: string) => {
+        if (terminated) return;
+        terminated = true;
+        ensureStarted();
+        closeOpenBlock();
+        emit("error", anthropicErrorBody(status, message));
+      };
+
+      const handleFrame = (eventName: string, data: Rec) => {
+        switch (eventName) {
+          case "response.created":
+            ensureStarted();
+            break;
+          case "response.heartbeat":
+            ensureStarted();
+            emit("ping", { type: "ping" });
+            break;
+          case "response.output_text.delta": {
+            if (typeof data.delta !== "string" || data.delta.length === 0) break;
+            ensureBlock("text");
+            emit("content_block_delta", {
+              type: "content_block_delta", index: open!.index,
+              delta: { type: "text_delta", text: data.delta },
+            });
+            break;
+          }
+          case "response.reasoning_summary_text.delta":
+          case "response.reasoning_text.delta": {
+            if (typeof data.delta !== "string" || data.delta.length === 0) break;
+            ensureBlock("thinking");
+            emit("content_block_delta", {
+              type: "content_block_delta", index: open!.index,
+              delta: { type: "thinking_delta", thinking: data.delta },
+            });
+            break;
+          }
+          case "response.output_item.added": {
+            const item = isRec(data.item) ? data.item : null;
+            if (!item || item.type !== "function_call") break;
+            ensureStarted();
+            closeOpenBlock();
+            sawToolUse = true;
+            const index = blockIndex++;
+            emit("content_block_start", {
+              type: "content_block_start", index,
+              content_block: {
+                type: "tool_use",
+                id: typeof item.call_id === "string" ? item.call_id : `toolu_${uuid()}`,
+                name: typeof item.name === "string" ? item.name : "",
+                input: {},
+              },
+            });
+            open = { kind: "tool_use", index, itemId: typeof item.id === "string" ? item.id : undefined };
+            break;
+          }
+          case "response.function_call_arguments.delta": {
+            if (typeof data.delta !== "string" || data.delta.length === 0) break;
+            if (!open || open.kind !== "tool_use") break;
+            emit("content_block_delta", {
+              type: "content_block_delta", index: open.index,
+              delta: { type: "input_json_delta", partial_json: data.delta },
+            });
+            break;
+          }
+          case "response.output_item.done": {
+            const item = isRec(data.item) ? data.item : null;
+            if (!open || !item) break;
+            // Close the matching open block (message/reasoning items close implicitly on
+            // the next block; function_call items must close here so tool input parses).
+            if (open.kind === "tool_use" && item.type === "function_call") closeOpenBlock();
+            else if (open.kind === "text" && item.type === "message") closeOpenBlock();
+            else if (open.kind === "thinking" && item.type === "reasoning") closeOpenBlock();
+            break;
+          }
+          case "response.completed": {
+            const response = isRec(data.response) ? data.response : {};
+            finish(sawToolUse ? "tool_use" : "end_turn", response.usage);
+            break;
+          }
+          case "response.incomplete": {
+            const response = isRec(data.response) ? data.response : {};
+            const details = isRec(response.incomplete_details) ? response.incomplete_details : {};
+            const reason = details.reason === "max_output_tokens" ? "max_tokens"
+              : details.reason === "content_filter" ? "refusal"
+              : sawToolUse ? "tool_use" : "end_turn";
+            finish(reason, response.usage);
+            break;
+          }
+          case "response.failed": {
+            const response = isRec(data.response) ? data.response : {};
+            const error = isRec(response.error) ? response.error : {};
+            const message = typeof error.message === "string" ? error.message : "upstream request failed";
+            const status = typeof error.status === "number" ? error.status : 500;
+            fail(status, message);
+            break;
+          }
+          default:
+            break; // web_search_call / custom_tool_call / content_part frames: ignored v1
+        }
+      };
+
+      const reader = upstream.getReader();
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let sep: number;
+          while ((sep = buffer.indexOf("\n\n")) !== -1) {
+            const rawFrame = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            let eventName = "";
+            let dataLine = "";
+            for (const line of rawFrame.split("\n")) {
+              if (line.startsWith("event: ")) eventName = line.slice(7).trim();
+              else if (line.startsWith("data: ")) dataLine += line.slice(6);
+            }
+            if (!eventName || !dataLine) continue;
+            let data: unknown;
+            try { data = JSON.parse(dataLine); } catch { continue; }
+            if (!isRec(data)) continue;
+            if (terminated) continue;
+            handleFrame(eventName, data);
+          }
+        }
+        // EOF without a terminal frame is a TRUNCATION, not success (devlog 100:
+        // gateways that close such streams politely hand Claude Code an empty/partial
+        // turn with no retryable error — CLIProxyAPI#2189 failure pattern). Fail closed
+        // with a mid-stream Anthropic error event so the client can retry.
+        fail(502, "upstream stream ended before a terminal frame (truncated response)");
+      } catch (err) {
+        fail(500, err instanceof Error ? err.message : String(err));
+      } finally {
+        if (pingTimer !== undefined) clearInterval(pingTimer);
+        reader.releaseLock();
+        controller.close();
+      }
+    },
+    cancel(reason) {
+      if (pingTimer !== undefined) clearInterval(pingTimer);
+      return upstream.cancel(reason);
+    },
+  });
+}
+
+/** Non-streaming: /v1/responses JSON -> Anthropic message JSON. */
+export function responsesJsonToAnthropicMessage(json: unknown, model: string): Rec {
+  const body = isRec(json) ? json : {};
+  const output = Array.isArray(body.output) ? body.output : [];
+  const content: Rec[] = [];
+  let sawToolUse = false;
+
+  for (const raw of output) {
+    if (!isRec(raw)) continue;
+    switch (raw.type) {
+      case "message": {
+        if (!Array.isArray(raw.content)) break;
+        for (const part of raw.content) {
+          if (isRec(part) && part.type === "output_text" && typeof part.text === "string" && part.text.length > 0) {
+            content.push({ type: "text", text: part.text });
+          }
+        }
+        break;
+      }
+      case "reasoning": {
+        const parts: string[] = [];
+        if (Array.isArray(raw.summary)) {
+          for (const s of raw.summary) {
+            if (isRec(s) && typeof s.text === "string" && s.text.length > 0) parts.push(s.text);
+          }
+        }
+        if (Array.isArray(raw.content)) {
+          for (const s of raw.content) {
+            if (isRec(s) && typeof s.text === "string" && s.text.length > 0) parts.push(s.text);
+          }
+        }
+        if (parts.length > 0) {
+          content.push({ type: "thinking", thinking: parts.join("\n\n"), signature: `ocx${Date.now()}` });
+        }
+        break;
+      }
+      case "function_call": {
+        sawToolUse = true;
+        let input: unknown = {};
+        if (typeof raw.arguments === "string" && raw.arguments.length > 0) {
+          try { input = JSON.parse(raw.arguments); } catch { input = {}; }
+        }
+        content.push({
+          type: "tool_use",
+          id: typeof raw.call_id === "string" ? raw.call_id : `toolu_${uuid()}`,
+          name: typeof raw.name === "string" ? raw.name : "",
+          input,
+        });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const details = isRec(body.incomplete_details) ? body.incomplete_details : {};
+  const stopReason = body.status === "incomplete" && details.reason === "max_output_tokens"
+    ? "max_tokens"
+    : sawToolUse ? "tool_use" : "end_turn";
+
+  return {
+    id: `msg_${uuid()}`,
+    type: "message",
+    role: "assistant",
+    content,
+    model,
+    stop_reason: stopReason,
+    stop_sequence: null,
+    usage: anthropicUsage(body.usage),
+  };
+}
+
+/**
+ * Fold an Anthropic SSE stream (our own emission vocabulary) into a message JSON.
+ * Used for non-streaming client requests: the internal replay always streams
+ * (routed adapters do not support non-stream turns), so the translated stream is
+ * aggregated here instead of translating a JSON body.
+ */
+export async function collectAnthropicMessage(stream: ReadableStream<Uint8Array>, model: string): Promise<Rec> {
+  const decoder = new TextDecoder();
+  const reader = stream.getReader();
+  let buffer = "";
+  const content: Rec[] = [];
+  let openBlock: Rec | null = null;
+  let toolJson = "";
+  let stopReason: string | null = "end_turn";
+  let usage: Rec = anthropicUsage(undefined);
+  let error: Rec | null = null;
+
+  const closeBlock = () => {
+    if (!openBlock) return;
+    if (openBlock.type === "tool_use") {
+      try { openBlock.input = toolJson.length > 0 ? JSON.parse(toolJson) : {}; } catch { openBlock.input = {}; }
+    }
+    content.push(openBlock);
+    openBlock = null;
+    toolJson = "";
+  };
+
+  const handle = (name: string, data: Rec) => {
+    switch (name) {
+      case "content_block_start":
+        closeBlock();
+        if (isRec(data.content_block)) openBlock = { ...data.content_block };
+        break;
+      case "content_block_delta": {
+        const delta = isRec(data.delta) ? data.delta : {};
+        if (!openBlock) break;
+        if (delta.type === "text_delta" && typeof delta.text === "string") {
+          openBlock.text = `${openBlock.text ?? ""}${delta.text}`;
+        } else if (delta.type === "thinking_delta" && typeof delta.thinking === "string") {
+          openBlock.thinking = `${openBlock.thinking ?? ""}${delta.thinking}`;
+        } else if (delta.type === "signature_delta" && typeof delta.signature === "string") {
+          openBlock.signature = delta.signature;
+        } else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
+          toolJson += delta.partial_json;
+        }
+        break;
+      }
+      case "content_block_stop":
+        closeBlock();
+        break;
+      case "message_delta": {
+        const delta = isRec(data.delta) ? data.delta : {};
+        if (typeof delta.stop_reason === "string") stopReason = delta.stop_reason;
+        if (isRec(data.usage)) usage = data.usage;
+        break;
+      }
+      case "error":
+        error = data;
+        break;
+      default:
+        break;
+    }
+  };
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let sep: number;
+      while ((sep = buffer.indexOf("\n\n")) !== -1) {
+        const rawFrame = buffer.slice(0, sep);
+        buffer = buffer.slice(sep + 2);
+        let eventName = "";
+        let dataLine = "";
+        for (const line of rawFrame.split("\n")) {
+          if (line.startsWith("event: ")) eventName = line.slice(7).trim();
+          else if (line.startsWith("data: ")) dataLine += line.slice(6);
+        }
+        if (!eventName || !dataLine) continue;
+        let data: unknown;
+        try { data = JSON.parse(dataLine); } catch { continue; }
+        if (isRec(data)) handle(eventName, data);
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  closeBlock();
+
+  if (error) return error;
+  return {
+    id: `msg_${uuid()}`,
+    type: "message",
+    role: "assistant",
+    content,
+    model,
+    stop_reason: stopReason,
+    stop_sequence: null,
+    usage,
+  };
+}

package/src/cli/claude.ts

@@ -0,0 +1,157 @@
+/**
+ * `ocx claude [claude args...]` — launch Claude Code wired to the local proxy.
+ *
+ * Mirrors `ccr code` UX (devlog/260711_claude_inbound/020, 003 E1/E2/E5/G1):
+ * ensures the proxy is running, injects the Anthropic env slots, then execs the
+ * `claude` CLI with stdio inherited. User-exported env always wins.
+ */
+import { spawn } from "node:child_process";
+import { loadConfig } from "../config";
+import { injectClaudeAgentDefs } from "../claude/agents-inject";
+import { effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
+import { refreshGatewayModelCacheFromProxy } from "../claude/gateway-cache";
+import { findLiveProxy } from "../server/proxy-liveness";
+import type { OcxConfig } from "../types";
+
+export interface ClaudeLaunchEnv {
+  [key: string]: string | undefined;
+}
+
+/**
+ * Pure env assembly (unit-tested): never sets ANTHROPIC_API_KEY (setting both
+ * token vars triggers Claude Code's auth-conflict warning, 003 E1), and never
+ * overrides variables the user already exported.
+ */
+export function buildClaudeEnv(config: OcxConfig, port: number, base: ClaudeLaunchEnv, contextWindows: Record<string, number> = {}): ClaudeLaunchEnv {
+  const env: ClaudeLaunchEnv = { ...base };
+  const setDefault = (name: string, value: string | undefined) => {
+    if (value === undefined || value.length === 0) return;
+    if (env[name] !== undefined && env[name] !== "") return; // user wins
+    env[name] = value;
+  };
+  setDefault("ANTHROPIC_BASE_URL", `http://127.0.0.1:${port}`);
+  // Subscription-preserving default (teamclaude --no-mitm / Vercel gateway pattern):
+  // setting ANTHROPIC_AUTH_TOKEN/API_KEY disables claude.ai connectors and overrides
+  // the user's Claude login. Only inject a token when the proxy actually requires an
+  // admission key; otherwise Claude Code keeps its own OAuth and sends it to us —
+  // native claude models then pass through verbatim (see server/claude-messages.ts).
+  if ((config.apiKeys?.length ?? 0) > 0) {
+    setDefault("ANTHROPIC_AUTH_TOKEN", config.apiKeys![0].key);
+  }
+  // NOTE: do NOT set _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL here. While it enables
+  // Design/Remote Control, it DISABLES gateway model discovery (Claude Code's eligibility
+  // check returns false when isFirstPartyBaseUrl() is true). Model routing through the
+  // proxy is essential; Design/Remote Control are secondary features.
+  // Connectors still work because they check OAuth state ($o()), not base URL (Gd()).
+  // Native /model picker discovery ("From gateway", Claude Code >= 2.1.129).
+  setDefault("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1");
+  // Opt-in effort forcing (devlog 136 B6): opus-shaped aliases already carry
+  // output_config.effort, so this is OFF unless the user enables it in config.
+  if (config.claudeCode?.alwaysEnableEffort === true) {
+    setDefault("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
+  }
+  // Context-window override: the official pair — MAX_CONTEXT_TOKENS alone is ignored
+  // for recognized claude-shaped ids unless DISABLE_COMPACT=1 rides along (devlog 135).
+  const maxCtx = config.claudeCode?.maxContextTokens;
+  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
+    setDefault("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx)));
+    setDefault("DISABLE_COMPACT", "1");
+  }
+  // Auto-context (devlog 260712 020): min(believed window, env) inside the CLI means
+  // one global env acts as a per-model floor — [1m]-marked models compact here while
+  // unmarked (200k-accounted) models keep their default behavior. Inert when the
+  // legacy maxContextTokens pair above is set (resolveAutoContext handles that).
+  // A user-exported value drives the marking predicate too (audit 021 #2) so the
+  // [1m] marker and the compaction threshold can never separate.
+  const userAutoCompact = typeof base.CLAUDE_CODE_AUTO_COMPACT_WINDOW === "string" && base.CLAUDE_CODE_AUTO_COMPACT_WINDOW !== ""
+    ? base.CLAUDE_CODE_AUTO_COMPACT_WINDOW
+    : undefined;
+  const auto = resolveAutoContext(config.claudeCode, userAutoCompact);
+  if (auto.enabled) {
+    setDefault("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(auto.compactWindow));
+  }
+  // Model slots (devlog 260712 B2): default + four tier defaults + legacy small-fast,
+  // with automatic [1m] context-variant marking when the slot's target model has an
+  // authoritative >=1M window (Claude Code then accounts 1M, compaction preserved).
+  for (const [name, value] of Object.entries(effectiveModelEnv(config.claudeCode, contextWindows, auto))) {
+    setDefault(name, value);
+  }
+  return env;
+}
+
+/**
+ * Context-window map from the RUNNING proxy's management API (warm TTL cache; the
+ * daemon registers every selector form — audit R3#1). 3s bound + auth header
+ * (OPENCODEX_API_AUTH_TOKEN first, config key fallback — audit R4#1). Failure → {}
+ * (no [1m] marking, conservative).
+ */
+export async function fetchClaudeContextWindows(config: OcxConfig, port: number, timeoutMs = 3_000): Promise<Record<string, number>> {
+  try {
+    const headers = new Headers();
+    const token = process.env.OPENCODEX_API_AUTH_TOKEN || config.apiKeys?.[0]?.key;
+    if (token) headers.set("x-opencodex-api-key", token);
+    const res = await fetch(`http://127.0.0.1:${port}/api/claude-code`, {
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return {};
+    const body = await res.json() as { contextWindows?: Record<string, number> };
+    return body.contextWindows && typeof body.contextWindows === "object" ? body.contextWindows : {};
+  } catch {
+    console.error("⚠ 모델 컨텍스트 정보를 불러오지 못했습니다 — 1M 자동 표시는 이번 실행에서 생략됩니다.");
+    return {};
+  }
+}
+
+async function ensureProxyForClaude(): Promise<number | null> {
+  const live = await findLiveProxy();
+  if (live) return live.port;
+  const child = spawn(process.execPath, [process.argv[1], "start"], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: { ...process.env, OCX_SERVICE: "1" },
+  });
+  child.unref();
+  const deadline = Date.now() + 8_000;
+  while (Date.now() < deadline) {
+    const started = await findLiveProxy();
+    if (started) return started.port;
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  return null;
+}
+
+export async function cmdClaude(args: string[]): Promise<number> {
+  const config = loadConfig();
+  if (config.claudeCode?.enabled === false) {
+    console.error("Claude inbound is disabled (config.claudeCode.enabled=false — flip the Claude ON toggle in the GUI or edit config).");
+    return 1;
+  }
+  const port = await ensureProxyForClaude();
+  if (!port) {
+    console.error("❌ Proxy did not become healthy after starting.");
+    return 1;
+  }
+  const contextWindows = await fetchClaudeContextWindows(config, port);
+  const env = buildClaudeEnv(config, port, process.env, contextWindows);
+  // Pre-write the CLI's gateway-model cache (devlog 030): without a token the CLI
+  // never refreshes it, so the picker would keep showing yesterday's aliases.
+  await refreshGatewayModelCacheFromProxy(port);
+  // Sync roster agents (devlog 070): subagentModels + self -> ~/.claude/agents/ocx-*.md.
+  injectClaudeAgentDefs(config, contextWindows);
+  return await new Promise<number>(resolve => {
+    const child = spawn("claude", args, { stdio: "inherit", env: env as NodeJS.ProcessEnv });
+    child.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "ENOENT") {
+        console.error("❌ `claude` CLI not found. Install it first: npm install -g @anthropic-ai/claude-code");
+      } else {
+        console.error(`❌ Failed to launch claude: ${err.message}`);
+      }
+      resolve(1);
+    });
+    child.on("exit", (code, signal) => {
+      resolve(signal ? 1 : code ?? 0);
+    });
+  });
+}

package/src/cli/help.ts

@@ -84,6 +84,17 @@ const helpEntries: Record<string, HelpEntry> = {
     summary: "List available models from configured providers.",
     details: ["Shows statically configured models. Providers with liveModels may have additional models at runtime."],
   },
+  claude: {
+    usage: "ocx claude [claude args...]",
+    summary: "Launch Claude Code wired to the proxy (env injection + gateway model discovery).",
+    details: [
+      "Ensures the proxy is running, then execs `claude` with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN,",
+      "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and model slots from config.claudeCode.",
+      "Routed models appear in the native /model picker as claude-ocx-<provider>--<model> (Claude Code >= 2.1.129).",
+      "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
+      "User-exported ANTHROPIC_* variables always take precedence.",
+    ],
+  },
   restart: {
     usage: "ocx restart",
     summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
@@ -134,6 +145,7 @@ Usage:
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
   ocx provider <sub>          Manage providers (list|add|remove|show|set-default)
   ocx models [--json]         List available models from configured providers
+  ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx help [command]          Show help
   ocx --version | -v          Print version