Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

5.7 KB
Raw Blame
/**
 * Code mode for `openai-codex`: the user's setting.
 *
 * Precedence: `--code-mode <auto|on|off>` > `CLAUDISH_CODE_MODE` > `codeMode`
 * in the project `.claudish.json` > `codeMode` in the global config > the
 * default, `auto`: on where the Codex `/models` endpoint reports
 * `tool_mode: code_mode_only`, and only for `openai-codex` on the OAuth arm
 * with tools declared. `off` turns it off everywhere.
 *
 * Pure: no runtime imports from the request path (types only), so the CLI can
 * read it without loading anything else of code mode.
 */

import type { CredentialArm } from "../auth/credentials/types.js";
import type { ClaudeToolChoice } from "../handlers/shared/format/openai-tools.js";
import type { CodexModelInfo } from "../providers/codex-models-discovery.js";
import type { WireApi } from "../providers/connection-wire.js";

/** `auto`: on where discovery says so; `on`: forced; `off`: never. */
export type CodeModeSetting = "auto" | "on" | "off";

/** Every accepted value, for parsing and for messages. */
export const CODE_MODE_SETTINGS: readonly CodeModeSetting[] = ["auto", "on", "off"];

/** The setting when nothing states one. */
export const DEFAULT_CODE_MODE_SETTING: CodeModeSetting = "auto";

/** The env var that sets code mode when no flag does. */
export const CODE_MODE_ENV_VAR = "CLAUDISH_CODE_MODE";

/**
 * `value` as a setting (trimmed, case-insensitive), or undefined when it is
 * not one of `auto`, `on`, `off`.
 */
export function parseCodeModeSetting(value: unknown): CodeModeSetting | undefined {
  if (typeof value !== "string") return undefined;
  const v = value.trim().toLowerCase();
  return (CODE_MODE_SETTINGS as readonly string[]).includes(v) ? (v as CodeModeSetting) : undefined;
}

/** The `tool_mode` value `/models` publishes for models the official client drives in code mode. */
export const CODE_MODE_ONLY_TOOL_MODE = "code_mode_only";

/** Why a request is or is not in code mode. */
export type CodeModeDecision =
  | {
      on: false;
      reason:
        | "not-openai-codex"
        | "metered-arm"
        | "no-account-id"
        | "not-responses"
        | "no-tools"
        | "forced-tool-choice"
        | "no-session-id"
        | "setting-off"
        | "discovery-unknown"
        | "classic-by-discovery"
        | "sandbox-unavailable";
    }
  | { on: true; shape: "lite" | "classic"; reason: "discovery" | "forced" | "pinned" };

export interface CodeModeDecisionInput {
  providerName: string;
  /** From THIS request's auth binding. */
  arm: CredentialArm | undefined;
  /** `accountKeyFromBinding`; undefined when the login has no account id. */
  accountKey: string | undefined;
  api: WireApi | undefined;
  hasTools: boolean;
  toolChoice: ClaudeToolChoice | null | undefined;
  hasSessionId: boolean;
  setting: CodeModeSetting;
  modelInfo?: CodexModelInfo;
  /** This session already relayed an exec (its arm is still OAuth). */
  pinned: boolean;
  sandboxAvailable: boolean;
  /** A lite request was rejected for this model within the discovery TTL. */
  liteFallbackActive: boolean;
}

/** `tool_choice` absent or `auto`: the only choices code mode honours exactly. */
function isAutoToolChoice(choice: ClaudeToolChoice | null | undefined): boolean {
  return !choice || choice.type === undefined || choice.type === "auto";
}

/**
 * The code-mode decision for one request (architecture §5.1).
 *
 * On only if all hold: claudish provider `openai-codex`; the setting is not
 * `off`; the binding's arm is `oauth`; an account key exists; the wire API is
 * Responses; the request declares ≥ 1 tool; `tool_choice` is absent or `auto`
 * (a named tool, `any` or `none` stays classic, which honours it exactly); the
 * request carries a Claude Code session id; the sandbox loads. Then `on`
 * forces; `auto` needs discovery's `tool_mode: code_mode_only`, or a pinned
 * session (one that already relayed an exec, so a later discovery failure
 * cannot flip a code-mode conversation back). The shape is `lite` iff
 * discovery says `use_responses_lite` and no lite rejection is remembered.
 */
export function decideCodeMode(i: CodeModeDecisionInput): CodeModeDecision {
  if (i.providerName !== "openai-codex") return { on: false, reason: "not-openai-codex" };
  if (i.setting === "off") return { on: false, reason: "setting-off" };
  if (i.arm !== "oauth") return { on: false, reason: "metered-arm" };
  if (!i.accountKey) return { on: false, reason: "no-account-id" };
  if (i.api !== "responses") return { on: false, reason: "not-responses" };
  if (!i.hasTools) return { on: false, reason: "no-tools" };
  if (!isAutoToolChoice(i.toolChoice)) return { on: false, reason: "forced-tool-choice" };
  if (!i.hasSessionId) return { on: false, reason: "no-session-id" };
  if (!i.sandboxAvailable) return { on: false, reason: "sandbox-unavailable" };

  const shape: "lite" | "classic" =
    i.modelInfo?.useResponsesLite === true && !i.liteFallbackActive ? "lite" : "classic";
  if (i.setting === "on") return { on: true, shape, reason: "forced" };
  if (i.modelInfo?.toolMode === CODE_MODE_ONLY_TOOL_MODE) {
    return { on: true, shape, reason: "discovery" };
  }
  if (i.pinned) return { on: true, shape, reason: "pinned" };
  if (!i.modelInfo) return { on: false, reason: "discovery-unknown" };
  return { on: false, reason: "classic-by-discovery" };
}

/** `[CodeMode] on (lite, discovery: code_mode_only)` / `[CodeMode] off (<reason>)`. */
export function describeCodeModeDecision(
  decision: CodeModeDecision,
  modelInfo: CodexModelInfo | undefined
): string {
  if (!decision.on) return `[CodeMode] off (${decision.reason})`;
  const why =
    decision.reason === "discovery"
      ? `discovery: ${modelInfo?.toolMode ?? CODE_MODE_ONLY_TOOL_MODE}`
      : decision.reason;
  return `[CodeMode] on (${decision.shape}, ${why})`;
}