Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
38.1 KB
Raw Blame
/**
 * ai-sdk LanguageModelV2 implementation that dispatches via the `claude --print`
 * CLI subprocess. Used by the `claude-cli` recipe to route gateway.toolLoop /
 * gateway.chat calls through Claude Code's OAuth session instead of the
 * Anthropic SDK + ANTHROPIC_API_KEY.
 *
 * Per-call routing is the contract: the gateway resolves the model string
 * to this recipe based on the `claude-cli:` prefix, instantiates one of
 * these objects per modelId, and dispatches doGenerate. Sibling subagent
 * jobs with `litellm:gpt-5.4` continue routing through litellm-proxy in
 * the same worker; no env-var switch, no global state.
 *
 * Tool use is supported via system-prompt-instructed JSON emission:
 *   The recipe injects a fenced instruction block into the system prompt
 *   that teaches the model the `<use_tools>[{name,input}, ...]</use_tools>`
 *   emission format (ids are gbrain-minted, never model-authored — #4155). The adapter parses those blocks back into ai-sdk
 *   `tool-call` content parts. Parallel tool calls (multiple entries in
 *   the JSON array) round-trip cleanly — this is the case that breaks
 *   on the codex-proxy / litellm GPT-5.x bridge today.
 *
 * Context isolation:
 *   The subprocess is spawned from a dedicated tmpdir so claude-cli's
 *   CLAUDE.md auto-discovery has no local files to find. `--system-prompt`
 *   replaces the default system prompt; `--disable-slash-commands` skips
 *   skill resolution. On a CLI at SETTING_SOURCES_MIN_VERSION or newer,
 *   `--setting-sources ""` keeps user-level ~/.claude/CLAUDE.md, memory and
 *   settings out of the child (#8342) without `--bare`, which forces
 *   ANTHROPIC_API_KEY auth; an older CLI still loads them, and
 *   GBRAIN_CLAUDE_CLI_USER_SETTINGS=1 loads them again. #4119: to isolate
 *   the whole config dir (SkillOpt rollouts), set
 *   GBRAIN_CLAUDE_CLI_HERMETIC_CONFIG — see resolveHermeticConfigDir.
 *
 * doStream is not yet implemented; the model declares no streaming. Callers
 * (gateway.toolLoop primarily) use doGenerate.
 */
import { randomUUIDv7 } from 'bun';
import { spawn, spawnSync } from '../../spawn.ts';
import { mkdirSync } from 'node:fs';
import {
  claudeCliConfigDir,
  claudeCliCwdDir,
  sweepDeadClaudeCliScratchDirs,
} from './claude-cli-scratch.ts';
import { continuationUnprovenMetadata, resolveClaudeCliAnswer } from './claude-cli-continuation.ts';
import type {
  LanguageModelV2,
  LanguageModelV2CallOptions,
  LanguageModelV2Content,
  LanguageModelV2FunctionTool,
  LanguageModelV2Prompt,
  LanguageModelV2Message,
  LanguageModelV2ProviderDefinedTool,
  SharedV2ProviderMetadata,
} from '@ai-sdk/provider';

function claudeBin(): string {
  return process.env.GBRAIN_CLAUDE_CLI_BIN ?? 'claude';
}
// #4472: the per-PID dir names + the transcript-fingerprint predicate live in
// claude-cli-scratch.ts so transcript discovery can exclude the sessions these
// subprocess cwds mint under ~/.claude/projects/ without importing this module.
const CLAUDE_CWD = claudeCliCwdDir();
let cwdEnsured = false;
function ensureCleanCwd(): string {
  if (!cwdEnsured) {
    // #4472: the per-PID naming leaks one scratch dir per crashed/killed
    // gbrain process forever — sweep dead-PID leftovers once per process at
    // provider init. Best-effort: a sweep failure never breaks a chat call.
    try { sweepDeadClaudeCliScratchDirs(); } catch { /* best-effort */ }
    mkdirSync(CLAUDE_CWD, { recursive: true });
    cwdEnsured = true;
  }
  return CLAUDE_CWD;
}

// #4119 — opt-in hermetic config dir for the child. See resolveHermeticConfigDir.
const CLAUDE_HERMETIC_CONFIG = claudeCliConfigDir();
let hermeticEnsured = false;
/**
 * Resolve the CLAUDE_CONFIG_DIR the child should run with when
 * GBRAIN_CLAUDE_CLI_HERMETIC_CONFIG is set (#4119). Returns null when the
 * knob is unset/off — the child then inherits the user's real config dir
 * (today's behavior). `1`/`true` → a per-process empty tmpdir; any other
 * non-empty value is used verbatim as the config-dir path.
 *
 * Opt-in, NOT default: the config dir also holds the CLI's session
 * credentials, so the empty-dir form logs the child out wherever the CLI
 * reads its session from the config dir (observed on macOS with Claude Code
 * 2.1.x too — #4741; nothing here seeds or looks up credential material).
 * For hermetic-with-auth use the explicit-path form with a pre-seeded config.
 * SkillOpt runs that need hermetic measurements (no user-level CLAUDE.md /
 * settings.json / hooks bleeding into rollouts) flip it deliberately — see
 * docs/guides/skillopt.md, "Hermetic claude-cli rollouts".
 */
export function resolveHermeticConfigDir(
  raw: string | undefined = process.env.GBRAIN_CLAUDE_CLI_HERMETIC_CONFIG,
): string | null {
  const v = raw?.trim();
  if (!v || v === '0' || v.toLowerCase() === 'false') return null;
  if (v === '1' || v.toLowerCase() === 'true') {
    if (!hermeticEnsured) {
      mkdirSync(CLAUDE_HERMETIC_CONFIG, { recursive: true });
      hermeticEnsured = true;
    }
    return CLAUDE_HERMETIC_CONFIG;
  }
  return v;
}

/** Parsed shape of the result event `claude --print` emits. */
interface ClaudeJsonResult {
  type: 'result';
  subtype: 'success' | string;
  is_error: boolean;
  result: string;
  stop_reason: string | null;
  session_id: string;
  num_turns: number;
  /** HTTP status of the underlying API failure (e.g. 429 on a spend/rate limit); Claude Code 2.1.305+ sends null when there is none. */
  api_error_status?: number | null;
  usage?: {
    input_tokens?: number;
    output_tokens?: number;
    cache_read_input_tokens?: number;
    cache_creation_input_tokens?: number;
  };
}

/**
 * Typed failure for a `claude --print` run that reported an error. Carries the
 * API HTTP status (`apiErrorStatus`, e.g. 429 on a spend/rate limit) and the
 * subprocess exit code so callers can branch on the failure class instead of
 * regexing a raw stderr/stdout blob.
 */
export class ClaudeCliProcessError extends Error {
  readonly apiErrorStatus: number | undefined;
  readonly exitCode: number | undefined;

  constructor(message: string, opts: { apiErrorStatus?: number; exitCode?: number } = {}) {
    super(message);
    this.name = 'ClaudeCliProcessError';
    this.apiErrorStatus = opts.apiErrorStatus;
    this.exitCode = opts.exitCode;
  }
}

/** The result envelope plus the session's event array when stdout carried one (`--verbose`, #6791). */
type ClaudeRun = ClaudeJsonResult & { events: readonly unknown[] | null };

type EnvelopeParse =
  | { ok: true; envelope: ClaudeRun }
  | { ok: false; reason: 'not-json'; error: unknown }
  | { ok: false; reason: 'no-result-event' };

/**
 * Unwrap the CLI's stdout into the result envelope and the event array it came
 * in. `runClaude` passes `--output-format stream-json --verbose` (#7352,
 * #6791), so the CLI prints one event per line: {type:"system",...}, the
 * assistant messages, then {type:"result",...}; verified on CLI 2.0.60 and
 * 2.1.319. A single JSON document (the `--output-format json` event array, or
 * a bare result object with events null) is still accepted.
 */
function parseResultEnvelope(stdout: string): EnvelopeParse {
  let parsed: unknown;
  try {
    parsed = JSON.parse(stdout);
  } catch (error) {
    try {
      const lines = stdout.split('\n').filter(line => line.trim().length > 0);
      if (lines.length < 2) return { ok: false, reason: 'not-json', error };
      parsed = lines.map(line => JSON.parse(line));
    } catch {
      return { ok: false, reason: 'not-json', error };
    }
  }
  const events = Array.isArray(parsed) ? parsed : null;
  if (Array.isArray(parsed)) {
    const resultEvent = parsed.find(
      (ev): ev is ClaudeJsonResult =>
        !!ev && typeof ev === 'object' && (ev as { type?: unknown }).type === 'result',
    );
    if (!resultEvent) {
      return { ok: false, reason: 'no-result-event' };
    }
    parsed = resultEvent;
  }
  // JSON.parse accepts bare primitives (null / numbers / strings); none of
  // them is a result envelope, and letting one through would make the
  // envelope field reads throw inside the subprocess close callback.
  if (!parsed || typeof parsed !== 'object') {
    return { ok: false, reason: 'not-json', error: new Error('top-level JSON value is not an object') };
  }
  return { ok: true, envelope: { ...(parsed as ClaudeJsonResult), events } };
}

/**
 * Build the ClaudeCliProcessError for an error-reporting result envelope,
 * surfacing `api_error_status` + the human-readable `result` message instead of
 * an opaque blob.
 */
/**
 * #6523: Claude Code reports a response that hit CLAUDE_CODE_MAX_OUTPUT_TOKENS
 * (the cap #6424 forwards, or the CLI's own default) as an error envelope,
 * not as a success with `stop_reason: 'max_tokens'`:
 *   "API Error: Claude's response exceeded the 2048 output token maximum. To
 *    configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS
 *    environment variable."
 * Rejecting on it hid the cap from every caller that escalates on `length`
 * (loops_extract 2048 → 8192, facts/extract 1× → 2×), so the minion queue
 * retried the same capped call and the job died. The match is the anchored
 * prefix only: the trailing advice has already changed wording once, the
 * reported cap may be the default rather than the forwarded one, and the exit
 * code varies by CLI version. A quoted prefix mid-answer, a success envelope,
 * a non-string result or an envelope carrying an API status never match. No
 * status means the key is absent or null (#7273: newer CLIs send null).
 */
const OUTPUT_CAP_RE = /^API Error: Claude's response exceeded the \d+ output token maximum\b/;

function isOutputCapEnvelope(envelope: ClaudeJsonResult): boolean {
  return envelope.type === 'result'
    && envelope.is_error === true
    && (envelope.api_error_status === undefined || envelope.api_error_status === null)
    && typeof envelope.result === 'string'
    && OUTPUT_CAP_RE.test(envelope.result);
}

/** The cap envelope as the success the API would have returned: no text, `max_tokens`, usage as reported. */
function outputCapAsLength<T extends ClaudeJsonResult>(envelope: T): T {
  return { ...envelope, is_error: false, result: '', stop_reason: 'max_tokens' };
}

function envelopeError(envelope: ClaudeJsonResult, exitCode: number | undefined): ClaudeCliProcessError {
  const status = typeof envelope.api_error_status === 'number' ? envelope.api_error_status : undefined;
  const detail = envelope.result || envelope.subtype;
  const message = status !== undefined
    ? `claude-cli API error ${status}: ${detail}`
    : `claude-cli reported error: ${detail}`;
  return new ClaudeCliProcessError(message, { apiErrorStatus: status, exitCode });
}

/**
 * Build the system-prompt addendum that teaches the model the
 * `<use_tools>...</use_tools>` emission format. Returns the empty string
 * when no tools are registered for this turn so the model gets a normal
 * text-completion prompt without protocol noise.
 */
function buildToolUseInstructions(
  tools: ReadonlyArray<LanguageModelV2FunctionTool | LanguageModelV2ProviderDefinedTool> | undefined,
): string {
  if (!tools || tools.length === 0) return '';

  const functionTools = tools.filter((t): t is LanguageModelV2FunctionTool => t.type === 'function');
  if (functionTools.length === 0) return '';

  const toolSpecs = functionTools.map(t => ({
    name: t.name,
    description: t.description ?? '',
    input_schema: t.inputSchema ?? { type: 'object', properties: {} },
  }));

  return [
    '',
    '## Tool Use Protocol',
    '',
    'You have access to these tools:',
    '',
    '```json',
    JSON.stringify(toolSpecs, null, 2),
    '```',
    '',
    'To call one or more tools in this turn, emit EXACTLY ONE block of this form, ' +
      'with no other text outside the block on its own lines:',
    '',
    '<use_tools>',
    '[',
    '  {"name": "<tool name>", "input": <input object matching the tool\'s input_schema>}',
    ']',
    '</use_tools>',
    '',
    'Multiple tool calls go in the array. Tool results are returned to you on the ' +
      'next turn as [tool_result <text>] entries. You may then call more tools or emit a final response.',
    '',
    'When you are ready to give a final answer instead of calling tools, respond with prose text only — ' +
      'do not include a <use_tools> block in that case.',
    '',
  ].join('\n');
}

/**
 * Render the ai-sdk message array into one text block per conversation message
 * for `claude --print` stdin (#7352: the CLI's prompt cache matches at block
 * boundaries, so a tool loop's next turn reads this turn's cache only when this
 * turn's blocks are an unchanged prefix of it). System messages are extracted
 * up-front and concatenated into the `--system-prompt` flag value. Tool calls and tool results are rendered as
 * placeholders so the model sees the conversation in a coherent shape even
 * though the adapter does not natively round-trip tool calls through claude-cli.
 */
function renderPrompt(prompt: LanguageModelV2Prompt): { systemText: string; userBlocks: string[] } {
  const systemParts: string[] = [];
  const convo: string[] = [];

  for (const msg of prompt as ReadonlyArray<LanguageModelV2Message>) {
    if (msg.role === 'system') {
      systemParts.push(msg.content);
      continue;
    }
    if (msg.role === 'user') {
      const text = msg.content
        .map(p => {
          if (p.type === 'text') return p.text;
          // File parts get a stub — multimodal is not supported via subprocess yet.
          if (p.type === 'file') return `[file ${p.mediaType ?? 'unknown'}]`;
          return '';
        })
        .filter(s => s.length > 0)
        .join('\n');
      if (text) convo.push(`User: ${text}`);
      continue;
    }
    if (msg.role === 'assistant') {
      const rendered = msg.content
        .map(p => {
          if (p.type === 'text') return p.text;
          if (p.type === 'reasoning') return ''; // dropped on replay
          if (p.type === 'tool-call') {
            // #6236: the V2 prompt's input is an object; a template literal rendered it as [object Object].
            return `[tool_use ${p.toolName}(${typeof p.input === 'string' ? p.input : JSON.stringify(p.input)})]`;
          }
          if (p.type === 'tool-result') {
            const out = typeof p.output === 'string' ? p.output : JSON.stringify(p.output);
            return `[tool_result ${out}]`;
          }
          return '';
        })
        .filter(s => s.length > 0)
        .join('\n');
      if (rendered) convo.push(`Assistant: ${rendered}`);
      continue;
    }
    if (msg.role === 'tool') {
      const rendered = msg.content
        .map(p => {
          const out = typeof p.output === 'string' ? p.output : JSON.stringify(p.output);
          return `[tool_result ${out}]`;
        })
        .join('\n');
      if (rendered) convo.push(`User: ${rendered}`);
      continue;
    }
  }

  return { systemText: systemParts.join('\n'), userBlocks: convo };
}

/** Oldest claude CLI that accepts every flag `runClaude` passes (probed:
 * 2.0.59 rejects `--disable-slash-commands`, 2.0.60 accepts the full argv). */
export const MIN_CLAUDE_CLI_VERSION = '2.0.60';

/** The CLI's argument parser rejected a flag (`error: unknown option '--x'`). */
export function isUnknownOptionError(stderr: string): boolean {
  return /\bunknown option\b/i.test(stderr);
}

export function oldClaudeCliMessage(version: string | null): string {
  return `claude CLI ${MIN_CLAUDE_CLI_VERSION} or newer required (found ${version ?? 'an unknown version'}); upgrade Claude Code`;
}

/** `claude --version`'s version number, or null, run like a real call (clean
 * cwd, scrubbed env) and killed outright after 5 s. */
function claudeCliVersion(env: NodeJS.ProcessEnv): { version: string | null; settled: boolean } {
  const r = spawnSync(claudeBin(), ['--version'], { encoding: 'utf8', timeout: 5_000, killSignal: 'SIGKILL', cwd: ensureCleanCwd(), env });
  const version = /\d+\.\d+\.\d+/.exec(typeof r.stdout === 'string' ? r.stdout : '')?.[0] ?? null;
  return { version, settled: version !== null || r.status === 0 || r.signal !== null };
}

/** Oldest claude CLI that gets `--setting-sources ""` (#8342): 2.1.314 fixed
 * an excluded settings file still supplying some settings. Older CLIs keep
 * the argv above. */
export const SETTING_SOURCES_MIN_VERSION = '2.1.314';

const settingSourcesByBin = new Map<string, boolean>();

/** Whether the configured CLI is SETTING_SOURCES_MIN_VERSION or newer: one
 * `claude --version` per binary per process, false when it cannot be read.
 * A probe that failed to start or exited non-zero is not remembered, so the
 * next call probes again; one that hung to the 5 s kill is, so a stuck CLI
 * costs that wait once. */
function takesNoSettingSources(env: NodeJS.ProcessEnv): boolean {
  const bin = claudeBin();
  const known = settingSourcesByBin.get(bin);
  if (known !== undefined) return known;
  const { version, settled } = claudeCliVersion(env);
  const found = version?.split('.').map(Number);
  const min = SETTING_SOURCES_MIN_VERSION.split('.').map(Number);
  const takes = !!found && (found[0]! - min[0]! || found[1]! - min[1]! || found[2]! - min[2]!) >= 0;
  if (settled) settingSourcesByBin.set(bin, takes);
  return takes;
}

/**
 * #6918: Claude Code thinks by default on Claude 5 models, and the API needs
 * thinking.budget_tokens of at least 1024 and below max_tokens, so a call
 * capped at 1024 output tokens or fewer runs with thinking off.
 */
export const CLAUDE_THINKING_BUDGET_FLOOR = 1024;

export function thinkingDisabledBelowFloor(maxOutputTokens: number | undefined): boolean {
  return typeof maxOutputTokens === 'number' && Number.isInteger(maxOutputTokens) && maxOutputTokens > 0
    && maxOutputTokens <= CLAUDE_THINKING_BUDGET_FLOOR;
}

/**
 * Spawn `claude --print` with the contamination-suppression flags and return
 * the parsed result envelope. Aborts propagate to SIGTERM on
 * the child.
 */
function runClaude(
  systemPrompt: string,
  userBlocks: string[],
  model: string,
  signal?: AbortSignal,
  maxOutputTokens?: number,
): Promise<ClaudeRun> {
  return new Promise((resolve, reject) => {
    // #6424: forward the call's output cap. The inline --settings env sits
    // above the user's settings.json env block, so both carry it.
    const outputCap = typeof maxOutputTokens === 'number' && Number.isInteger(maxOutputTokens) && maxOutputTokens > 0
      ? String(maxOutputTokens)
      : undefined;
    const thinkingOff = thinkingDisabledBelowFloor(maxOutputTokens);
    const settings = outputCap
      ? JSON.stringify({ disableAllHooks: true, env: { CLAUDE_CODE_MAX_OUTPUT_TOKENS: outputCap, ...(thinkingOff ? { MAX_THINKING_TOKENS: '0' } : {}) } })
      : '{"disableAllHooks":true}';
    const args = [
      '--print',
      // #7352: one user message whose content blocks are the conversation's
      // messages, read as stream-json; the CLI then answers in stream-json.
      // #6791: --verbose keeps the session's events in that output, the only
      // record of the segments before an automatic continuation (the
      // envelope's result holds the last one).
      '--input-format', 'stream-json',
      '--output-format', 'stream-json', '--verbose',
      '--model', model,
      '--disable-slash-commands',
      // Agent isolation: this subprocess must behave like a raw LLM, not a
      // full Claude Code agent. `--tools ""` disables every built-in tool
      // (Bash/Read/WebSearch/...); `--strict-mcp-config` ignores all user-level
      // MCP servers (without it, each call would boot the user's MCP servers —
      // including gbrain's own MCP → recursion + PGLite single-writer lock
      // contention). Verified against claude CLI 2.1.145 --help.
      '--tools', '',
      '--strict-mcp-config',
      // #5820: the child must not run the user's Claude Code hooks — gbrain's
      // own Stop hook would bank this call's prompt as a "conversation" and
      // extracting it spawns another call. Unlike --bare this keeps the
      // subscription login (credentials are not settings). Accepted by every
      // CLI that accepts the flags above.
      '--settings', settings,
    ];
    if (systemPrompt) {
      args.push('--system-prompt', systemPrompt);
    }
    // Env scrub: guarantee the CLI authenticates via its own OAuth session
    // (subscription), never via an inherited API key. Without this, an
    // ANTHROPIC_API_KEY in gbrain's env (the exact setup this recipe is meant
    // to replace) silently flips billing to per-token API usage.
    //
    // Also scrub the CLAUDE_CODE_USE_* backend-switch flags: Bedrock, Vertex
    // AI, Mantle, Microsoft Foundry, and Claude Platform on AWS are each
    // gated by one of these, take priority over subscription OAuth when set,
    // and route billing through a cloud account instead. Clearing the switch
    // is sufficient — provider-specific creds (AWS_*, ANTHROPIC_VERTEX_*,
    // ANTHROPIC_FOUNDRY_*, ANTHROPIC_AWS_*, ...) are inert without it.
    const env = { ...process.env };
    delete env.ANTHROPIC_API_KEY;
    delete env.ANTHROPIC_AUTH_TOKEN;
    delete env.ANTHROPIC_BASE_URL;
    // Prefix wipe, not a denylist (review hardening): the backend-switch
    // family grows one CLAUDE_CODE_USE_* flag per new cloud backend, and any
    // future switch inherited from gbrain's env would silently re-route the
    // child's billing. Subscription-only is the recipe's contract.
    for (const k of Object.keys(env)) {
      if (k.startsWith('CLAUDE_CODE_USE_')) delete env[k];
    }
    // #4119 opt-in hermetic config: point the child's CLAUDE_CONFIG_DIR at an
    // isolated directory so user-level ~/.claude state (CLAUDE.md memory,
    // settings.json, hooks) can't leak into measurements. Off by default —
    // see resolveHermeticConfigDir for the auth caveat that makes it opt-in.
    const hermeticConfigDir = resolveHermeticConfigDir();
    if (hermeticConfigDir) env.CLAUDE_CONFIG_DIR = hermeticConfigDir;
    if (outputCap) env.CLAUDE_CODE_MAX_OUTPUT_TOKENS = outputCap;
    if (thinkingOff) env.MAX_THINKING_TOKENS = '0';
    // #8342: load no settings source, so the user's own ~/.claude/CLAUDE.md,
    // memory and settings.json never steer this call. Unlike --bare this
    // keeps the subscription login. GBRAIN_CLAUDE_CLI_USER_SETTINGS=1 opts
    // back in (no flag, no version probe).
    if (process.env.GBRAIN_CLAUDE_CLI_USER_SETTINGS !== '1' && takesNoSettingSources(env)) args.push('--setting-sources', '');
    const child = spawn(claudeBin(), args, {
      stdio: ['pipe', 'pipe', 'pipe'],
      cwd: ensureCleanCwd(),
      env,
    });

    let stdout = '';
    let stderr = '';
    child.stdout.on('data', chunk => { stdout += String(chunk); });
    child.stderr.on('data', chunk => { stderr += String(chunk); });

    const onAbort = () => {
      child.kill('SIGTERM');
      reject(signal?.reason instanceof Error && signal.reason.name === 'TimeoutError' ? signal.reason : new Error('claude-cli adapter aborted'));
    };
    if (signal) {
      if (signal.aborted) {
        onAbort();
        return;
      }
      signal.addEventListener('abort', onAbort, { once: true });
    }

    child.on('error', err => {
      if (signal) signal.removeEventListener('abort', onAbort);
      reject(new Error(`claude-cli spawn failed: ${err instanceof Error ? err.message : String(err)}`));
    });

    child.on('close', code => {
      if (signal) signal.removeEventListener('abort', onAbort);
      if (code !== 0) {
        // Even on a non-zero exit the CLI writes a formatted result envelope
        // to stdout (e.g. an API 429 arrives as {is_error:true,
        // api_error_status:429, result:"<human-readable message>", ...}).
        // Surface that as a typed error instead of burying the status inside
        // a raw blob. Only an error-reporting envelope qualifies: a SUCCESS
        // envelope followed by a non-zero exit is a process failure whose
        // reason lives in stderr, so it falls through to the blob fallback
        // (as does any stdout without a parseable envelope).
        const attempt = parseResultEnvelope(stdout);
        if (attempt.ok && isOutputCapEnvelope(attempt.envelope)) {
          resolve(outputCapAsLength(attempt.envelope));
          return;
        }
        if (attempt.ok && attempt.envelope.type === 'result' && attempt.envelope.is_error === true) {
          reject(envelopeError(attempt.envelope, code ?? undefined));
          return;
        }
        // The blob goes AFTER the `--- raw ---` marker: it can carry
        // model/page-derived text, and classifyGlobalLlmError's phrase
        // regexes only scan text before the marker (an auth-looking essay in
        // stdout must never read as a whole-run auth outage).
        const headline = isUnknownOptionError(stderr)
          ? oldClaudeCliMessage(claudeCliVersion(env).version)
          : `claude-cli exited ${code}`;
        reject(new ClaudeCliProcessError(
          `${headline}\n--- raw ---\n${stderr.trim() || stdout.trim()}`,
          { exitCode: code ?? undefined },
        ));
        return;
      }
      const attempt = parseResultEnvelope(stdout);
      if (!attempt.ok) {
        if (attempt.reason === 'no-result-event') {
          reject(new Error(`claude-cli JSON event array had no "result" event\n--- raw ---\n${stdout.slice(0, 500)}`));
          return;
        }
        const e = attempt.error;
        reject(new Error(`claude-cli output not JSON: ${e instanceof Error ? e.message : String(e)}\n--- raw ---\n${stdout.slice(0, 500)}`));
        return;
      }
      const envelope = attempt.envelope;
      if (isOutputCapEnvelope(envelope)) {
        resolve(outputCapAsLength(envelope));
        return;
      }
      if (envelope.is_error) {
        reject(envelopeError(envelope, 0));
        return;
      }
      resolve(envelope);
    });

    // stdin error handler: if the binary does not exist (ENOENT) or the child
    // dies before draining stdin, write/end can emit an unhandled 'error'
    // (EPIPE) that would crash the worker. The spawn-level 'error' / non-zero
    // 'close' handlers above already surface the real failure, so the stdin
    // error itself is safe to swallow.
    child.stdin.on('error', () => { /* surfaced via child 'error'/'close' */ });
    try {
      child.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: userBlocks.map(text => ({ type: 'text', text: text.toWellFormed() })) } }) + '\n');
      child.stdin.end();
    } catch (e) {
      if (signal) signal.removeEventListener('abort', onAbort);
      reject(new Error(`claude-cli stdin write failed (is the claude binary installed?): ${e instanceof Error ? e.message : String(e)}`));
    }
  });
}

interface ParsedToolCall {
  id: string;
  name: string;
  /** Stringified JSON, matching the ai-sdk LanguageModelV2ToolCall.input contract. */
  input: string;
}

/**
 * Keys the `<use_tools>` protocol reserves on an entry. `type: "tool_use"`
 * and a `toolu_*` `id` are tolerated leftovers of the Anthropic tool_use
 * shape; nothing reads them. Any OTHER `type`/`id` value is a real tool
 * argument (e.g. the allowlisted `list_pages` op's `type` filter) and stays.
 */
function isReservedEntryKey(k: string, v: unknown): boolean {
  if (k === 'name' || k === 'input') return true;
  if (k === 'type') return v === 'tool_use';
  if (k === 'id') return typeof v === 'string' && v.startsWith('toolu_');
  return false;
}

/**
 * Resolve the tool input of one `<use_tools>` entry. The protocol asks for
 * `{name, input}`, but the model sometimes emits the arguments flat on the
 * entry itself (`{"name": "brain_search", "query": "..."}`), the Anthropic
 * tool_use shape with the `input` wrapper dropped. Reading only `e.input`
 * turned every such call into `{}`, and the tool then failed on its missing
 * required parameter with nothing the model could act on. When `input` is
 * absent, the entry's non-reserved keys ARE the input; when it is present
 * it wins verbatim, stray sibling keys ignored.
 */
function resolveEntryInput(e: Record<string, unknown>): unknown {
  if (e.input !== undefined && e.input !== null) return e.input;
  const flat: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(e)) {
    if (!isReservedEntryKey(k, v)) flat[k] = v;
  }
  return flat;
}

/** The model's native tool-call elements, which this protocol never asks for and never dispatches. */
const NATIVE_TOOL_MARKUP = /<(?:antml:)?(?:invoke\s+name=|function_calls>)/;

/**
 * Locate and parse the `<use_tools>...</use_tools>` block in the assistant's
 * raw text response. Returns the parsed tool calls plus whatever prose
 * surrounded the block. Returns an empty `toolCalls` array when no block is
 * present, malformed, or unterminated — the caller then treats the full
 * raw text as a final text response.
 */
function extractToolCalls(raw: string): {
  toolCalls: ParsedToolCall[];
  beforeText: string;
  afterText: string;
  /** No block parsed, but the reply holds the model's native tool-call markup (#9085). */
  nativeMarkup?: boolean;
} {
  const openTag = '<use_tools>';
  const closeTag = '</use_tools>';
  // No single anchoring rule survives every shape the model emits: a prose
  // mention of `<use_tools>` BEFORE the block ("Let me use the correct
  // `<use_tools>` format:") breaks anchoring on the first open tag; a prose
  // mention of `</use_tools>` before the block breaks anchoring on the first
  // close tag; and a LITERAL tag inside a JSON string argument (a page body
  // being written that documents the protocol) breaks "last open tag before
  // the close" — the inner tag wins, the slice is truncated JSON, and a
  // valid call is discarded as prose. So: enumerate the (open, close) pairs
  // outermost-first (earliest open, then each later close) and accept the
  // first slice that parses as a JSON array. Tags inside argument strings
  // sit inside an accepted slice or produce a rejected one; they never anchor.
  // ponytail: O(opens × closes) JSON.parse attempts — tags are a handful per
  // response; a linear scanner is the upgrade if a payload ever has hundreds.
  const opens: number[] = [];
  for (let i = raw.indexOf(openTag); i !== -1; i = raw.indexOf(openTag, i + 1)) opens.push(i);
  const closes: number[] = [];
  for (let i = raw.indexOf(closeTag); i !== -1; i = raw.indexOf(closeTag, i + 1)) closes.push(i);

  let parsed: unknown[] | null = null;
  let openIdx = -1;
  let closeIdx = -1;
  let firstError: string | null = null;
  outer: for (const o of opens) {
    for (const c of closes) {
      if (c < o + openTag.length) continue;
      let inner = raw.slice(o + openTag.length, c).trim();
      if (inner.startsWith('```')) {
        inner = inner.replace(/^```(?:json|JSON)?\s*\n?/, '').replace(/\n?```$/, '').trim();
      }
      try {
        const v: unknown = JSON.parse(inner);
        if (Array.isArray(v)) { parsed = v; openIdx = o; closeIdx = c; break outer; }
      } catch (e) {
        firstError ??= e instanceof Error ? e.message : String(e);
      }
    }
  }
  if (parsed === null) {
    // A malformed block is a LOST tool call — the caller sees prose and the
    // turn ends as if the model never called anything. Say so on stderr.
    // (No pair at all — unterminated, absent, or only orphan close tags — and
    // a non-array payload both recover silently as before.)
    if (firstError !== null) {
      process.stderr.write(`[claude-cli] <use_tools> block failed to parse — tool call discarded: ${firstError}\n`);
    }
    return { toolCalls: [], beforeText: raw.trim(), afterText: '', nativeMarkup: NATIVE_TOOL_MARKUP.test(raw.replace(/```[\s\S]*?```/g, '').replace(/`[^`\n]*`/g, '')) };
  }

  const beforeText = raw.slice(0, openIdx).trim();
  const afterText = raw.slice(closeIdx + closeTag.length).trim();

  const toolCalls: ParsedToolCall[] = [];
  for (const entry of parsed) {
    if (!entry || typeof entry !== 'object') continue;
    const e = entry as Record<string, unknown>;
    const name = typeof e.name === 'string' ? e.name : null;
    if (!name) continue;
    // #4155: ALWAYS mint — never trust a model-authored id. Each doGenerate
    // is a fresh subprocess replayed from an id-stripped transcript
    // (renderPrompt), so the model structurally CANNOT keep ids unique
    // across turns; it echoed the prompt's example entropy-free (toolu_01,
    // toolu_02 every turn) and collided real dream jobs to death before the
    // job-wide unique constraint was retired (migration v131). The prompt no
    // longer asks for an id; a stray `id` field from older cached behavior
    // is deliberately ignored — nothing round-trips it (renderPrompt strips
    // ids on replay; the loop pairs results in-memory within one turn).
    const id = `toolu_claude_cli_${randomUUIDv7()}`;
    const inputJson = JSON.stringify(resolveEntryInput(e));
    toolCalls.push({ id, name, input: inputJson });
  }

  return { toolCalls, beforeText, afterText };
}

// Module-scoped so the counter survives the fresh ClaudeCliLanguageModel
// instance created for every doGenerate call (gateway resolves the provider
// per-call). Keeps the historical `toolu_claude_cli_` prefix — one grep target.

/**
 * Strip provider prefixes (`anthropic:`, `litellm:`, `claude-cli:`) that the
 * underlying CLI does not understand. The gateway hands us a bare model id
 * via `recipe.aliases` resolution, but defensive normalization here keeps
 * direct LanguageModelV2 construction (in tests, for example) ergonomic.
 */
function normalizeModel(model: string): string {
  const idx = model.indexOf(':');
  return idx >= 0 ? model.slice(idx + 1) : model;
}

/**
 * #6260: the CLI's own `stop_reason` decides the finish reason, so a response
 * cut off at the output cap reads as `length` and a refusal as
 * `content-filter`; callers that refuse to commit a clipped answer can only
 * see it this way. Tool calls parsed from the text finish as `tool-calls`
 * unless the answer was cut off. A missing or unknown reason stays `stop`.
 */
export function claudeCliFinishReason(stopReason: string | null | undefined, hasToolCalls: boolean): 'stop' | 'length' | 'content-filter' | 'tool-calls' {
  if (stopReason === 'max_tokens') return 'length';
  if (stopReason === 'refusal') return 'content-filter';
  return hasToolCalls ? 'tool-calls' : 'stop';
}

export class ClaudeCliLanguageModel implements LanguageModelV2 {
  readonly specificationVersion = 'v2' as const;
  readonly provider = 'claude-cli';
  readonly modelId: string;
  readonly supportedUrls = {};

  constructor(modelId: string) {
    this.modelId = normalizeModel(modelId);
  }

  async doGenerate(options: LanguageModelV2CallOptions): Promise<{
    content: LanguageModelV2Content[];
    finishReason: 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other' | 'unknown';
    usage: {
      inputTokens: number | undefined;
      outputTokens: number | undefined;
      totalTokens: number | undefined;
      cachedInputTokens: number | undefined;
    };
    providerMetadata?: SharedV2ProviderMetadata;
    warnings: never[];
  }> {
    const { systemText, userBlocks } = renderPrompt(options.prompt);
    const toolInstructions = buildToolUseInstructions(options.tools);
    const systemPrompt = [systemText, toolInstructions].filter(s => s.length > 0).join('\n');

    const result = await runClaude(systemPrompt, userBlocks, this.modelId, options.abortSignal, options.maxOutputTokens);
    // The CLI reports Anthropic's separate buckets; LanguageModelV2Usage wants
    // the TOTAL input with the cache read as a subset (what every SDK provider
    // reports), so the gateway prices cache tokens once. Cache creation has no
    // V2 field: it stays inside the total at the input rate.
    const cachedInputTokens =
      result.usage?.cache_read_input_tokens !== undefined
        ? Number(result.usage.cache_read_input_tokens)
        : undefined;
    const inputTokens = result.usage?.input_tokens === undefined ? undefined
      : result.usage.input_tokens + (cachedInputTokens ?? 0) + Number(result.usage.cache_creation_input_tokens ?? 0);
    const outputTokens = result.usage?.output_tokens;
    const totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
    const usage = {
      inputTokens,
      outputTokens,
      totalTokens: inputTokens !== undefined && outputTokens !== undefined ? totalTokens : undefined,
      cachedInputTokens,
    };

    // #6791: a continued answer is rebuilt from its segments, or refused
    // before any tool block in its tail can be parsed and dispatched.
    const thinking = thinkingDisabledBelowFloor(options.maxOutputTokens) ? { thinking: 'disabled_below_floor' } : null;
    const answer = resolveClaudeCliAnswer(result, options.maxOutputTokens);
    if (answer.kind === 'unproven') {
      return {
        content: [{ type: 'text', text: '' }],
        finishReason: 'length',
        usage,
        providerMetadata: { 'claude-cli': { ...continuationUnprovenMetadata(answer.reason)['claude-cli'], ...thinking } },
        warnings: [],
      };
    }
    const { toolCalls, beforeText, afterText, nativeMarkup } = extractToolCalls(answer.text);
    // #9085: a turn that called tools in the model's native markup is not a clean answer; read as prose it ends the
    // loop with no writes. Fail the turn (a transient error, so the job's attempt limit bounds the retries).
    if (nativeMarkup && options.tools?.length) {
      process.stderr.write('[claude-cli] reply carried tool-call markup with no parsable <use_tools> block — turn failed for retry\n');
      throw new Error('claude-cli reply carried tool-call markup with no parsable <use_tools> block; the tool calls were not run');
    }

    const content: LanguageModelV2Content[] = [];
    if (beforeText) content.push({ type: 'text', text: beforeText });
    for (const call of toolCalls) {
      content.push({
        type: 'tool-call',
        toolCallId: call.id,
        toolName: call.name,
        input: call.input,
      });
    }
    if (afterText) content.push({ type: 'text', text: afterText });
    if (content.length === 0) {
      // Empty response — still hand the caller a well-formed content array.
      content.push({ type: 'text', text: answer.text ?? '' });
    }

    return {
      content,
      finishReason: claudeCliFinishReason(result.stop_reason, toolCalls.length > 0),
      usage,
      ...(thinking ? { providerMetadata: { 'claude-cli': thinking } } : {}),
      warnings: [],
    };
  }

  async doStream(): Promise<never> {
    throw new Error(
      'claude-cli LanguageModel does not support streaming. Use doGenerate or set ' +
      'the model on a non-streaming chat surface (gateway.toolLoop is non-streaming).',
    );
  }
}