@a-t-h-i/bot-lobby 0.6.55 → 0.6.57

package/src/harness/catalog.ts

@@ -0,0 +1,257 @@
+/**
+ * What Bot Lobby knows about each third-party harness: how to start it, which
+ * models it serves and which effort levels each model takes.
+ *
+ * The model list is T3 Code's model manifest
+ * (`apps/server/src/provider/model-manifest.json`), copied as is into
+ * `model-manifest.json` next to this file; the effort descriptors and CLI
+ * effort maps are read the way T3 Code's `ClaudeModelCatalog.ts` reads them.
+ * The Antigravity launch details follow T3 Code's
+ * `antigravityAuthSupport.ts` (`buildAntigravityAcpSpawnInput`).
+ */
+import { readFileSync } from "node:fs";
+import { THINKING_LEVELS, type ThinkingLevelName } from "../schemas/configuration.ts";
+import type { HarnessId, HarnessProtocol, HarnessSettings } from "../schemas/harness.ts";
+import { tokenizeCliArgs } from "./cli-args.ts";
+
+export interface HarnessInfo {
+  id: HarnessId;
+  label: string;
+  protocol: HarnessProtocol;
+  /** The command when the settings name no binary; empty when the user must give one. */
+  command: string;
+  /** Arguments that put the command into the mode Bot Lobby speaks (ACP), before the user's launch arguments. */
+  args: readonly string[];
+  /** The environment variable the home path setting sets. */
+  homeEnv?: string;
+  /** Model providers the settings offer (`value` "" keeps the harness's own). */
+  providers: ReadonlyArray<{ value: string; label: string }>;
+  /** Where the effort level goes: a CLI flag, the model variant (Antigravity) or the agent's own session option (ACP). */
+  effort: "flag" | "variant" | "session";
+  /** One line for the settings page. */
+  blurb: string;
+}
+
+const WINDOWS = process.platform === "win32";
+
+export const HARNESSES: Record<HarnessId, HarnessInfo> = {
+  codex: {
+    id: "codex",
+    label: "Codex CLI",
+    protocol: "codex-exec",
+    command: "codex",
+    args: [],
+    homeEnv: "CODEX_HOME",
+    providers: [
+      { value: "", label: "Codex's own" },
+      { value: "openai", label: "OpenAI" },
+      { value: "ollama", label: "Ollama (local)" },
+      { value: "lmstudio", label: "LM Studio (local)" },
+    ],
+    effort: "flag",
+    blurb: "OpenAI's coding agent, run headless with codex exec.",
+  },
+  claude: {
+    id: "claude",
+    label: "Claude Code",
+    protocol: "claude-stream",
+    command: "claude",
+    args: [],
+    homeEnv: "CLAUDE_CONFIG_DIR",
+    providers: [
+      { value: "", label: "Anthropic" },
+      { value: "bedrock", label: "Amazon Bedrock" },
+      { value: "vertex", label: "Google Vertex AI" },
+    ],
+    effort: "flag",
+    blurb: "Anthropic's coding agent, driven through the Claude Agent SDK.",
+  },
+  antigravity: {
+    id: "antigravity",
+    label: "Antigravity",
+    protocol: "acp",
+    command: WINDOWS ? "agy_acp_server.exe" : "agy_acp_server.par",
+    args: process.platform === "linux" ? ["--uid="] : [],
+    providers: [],
+    effort: "variant",
+    blurb: "Google's Antigravity agent through its ACP server, signed in with your Antigravity account.",
+  },
+  gemini: {
+    id: "gemini",
+    label: "Gemini CLI",
+    protocol: "acp",
+    command: "gemini",
+    args: ["--acp"],
+    providers: [],
+    effort: "session",
+    blurb: "Google's Gemini CLI in ACP mode.",
+  },
+  opencode: {
+    id: "opencode",
+    label: "OpenCode",
+    protocol: "acp",
+    command: "opencode",
+    args: ["acp"],
+    providers: [],
+    effort: "session",
+    blurb: "OpenCode in ACP mode; models are named provider/model.",
+  },
+  acp: {
+    id: "acp",
+    label: "Custom ACP agent",
+    protocol: "acp",
+    command: "",
+    args: [],
+    providers: [],
+    effort: "session",
+    blurb: "Any agent that speaks the Agent Client Protocol: give its command and arguments.",
+  },
+};
+
+/** The command and arguments one run starts, with the user's launch arguments last. */
+export function harnessCommand(id: HarnessId, settings: HarnessSettings): { command: string; args: string[] } {
+  const info = HARNESSES[id];
+  return { command: settings.binaryPath || info.command, args: [...info.args, ...tokenizeCliArgs(settings.launchArgs)] };
+}
+
+export interface HarnessModel {
+  id: string;
+  label: string;
+  /** False for the manifest's older models, listed after the current ones. */
+  current: boolean;
+  /** Effort levels (pi's names) the model takes; empty when the harness picks its own. */
+  efforts: ThinkingLevelName[];
+  /** The level the harness uses when none is chosen. */
+  defaultEffort?: ThinkingLevelName;
+  custom?: boolean;
+}
+
+interface ManifestModel {
+  slug: string;
+  name: string;
+  status?: string;
+  profile?: string;
+}
+
+interface ManifestOption {
+  id: string;
+  type?: string;
+  options?: Array<{ id: string; isDefault?: boolean }>;
+}
+
+interface ManifestProfile {
+  capabilities?: { optionDescriptors?: ManifestOption[] };
+  adapter?: { claudeCode?: { effortMap?: Record<string, string | null> } };
+}
+
+interface Manifest {
+  providers: Record<string, { models: ManifestModel[]; profiles?: Record<string, ManifestProfile> }>;
+}
+
+let manifest: Manifest | undefined;
+
+function readManifest(): Manifest {
+  manifest ??= JSON.parse(readFileSync(new URL("./model-manifest.json", import.meta.url), "utf8")) as Manifest;
+  return manifest;
+}
+
+const MANIFEST_KEYS: Partial<Record<HarnessId, string>> = { codex: "codex", claude: "claudeAgent", antigravity: "antigravity" };
+
+/** Codex's reasoning efforts, as T3 Code's `CodexProvider.ts` labels them. */
+const CODEX_EFFORTS: ThinkingLevelName[] = ["minimal", "low", "medium", "high", "xhigh"];
+
+const isLevel = (value: string): value is ThinkingLevelName => (THINKING_LEVELS as readonly string[]).includes(value);
+
+function claudeEfforts(profile: ManifestProfile | undefined): { efforts: ThinkingLevelName[]; defaultEffort?: ThinkingLevelName } {
+  const option = profile?.capabilities?.optionDescriptors?.find((entry) => entry.id === "effort");
+  if (!option?.options) return { efforts: [] };
+  const map = profile?.adapter?.claudeCode?.effortMap ?? {};
+  const efforts = option.options.map((entry) => entry.id).filter((id): id is ThinkingLevelName => isLevel(id) && map[id] !== null);
+  const fallback = option.options.find((entry) => entry.isDefault)?.id;
+  return { efforts, ...(fallback && isLevel(fallback) ? { defaultEffort: fallback } : {}) };
+}
+
+/** Antigravity sells one model per effort (`…-flash-high`); the settings show one model with an effort slider. */
+const VARIANT = /^(.*)-(low|medium|high)$/;
+const VARIANT_LABEL = / \((Low|Medium|High)\)$/;
+
+function antigravityModels(models: ManifestModel[]): HarnessModel[] {
+  const families = new Map<string, HarnessModel>();
+  const out: HarnessModel[] = [];
+  for (const model of models) {
+    const match = VARIANT.exec(model.slug);
+    if (!match) {
+      out.push({ id: model.slug, label: model.name, current: model.status === "current", efforts: [] });
+      continue;
+    }
+    const [, base, level] = match as unknown as [string, string, ThinkingLevelName];
+    let family = families.get(base);
+    if (!family) {
+      family = { id: base, label: model.name.replace(VARIANT_LABEL, ""), current: model.status === "current", efforts: [], defaultEffort: "high" };
+      families.set(base, family);
+      out.push(family);
+    }
+    family.efforts.push(level);
+  }
+  for (const family of families.values()) family.efforts.sort((a, b) => THINKING_LEVELS.indexOf(a) - THINKING_LEVELS.indexOf(b));
+  return out;
+}
+
+/** The models a harness offers: the manifest's current ones, its older ones, then the ones typed into settings. */
+export function harnessModels(id: HarnessId, settings: HarnessSettings): HarnessModel[] {
+  const key = MANIFEST_KEYS[id];
+  const entry = key ? readManifest().providers[key] : undefined;
+  let models: HarnessModel[] = [];
+  if (entry && id === "antigravity") models = antigravityModels(entry.models);
+  else if (entry) {
+    models = entry.models.map((model) => {
+      const efforts = id === "codex" ? { efforts: CODEX_EFFORTS, defaultEffort: "medium" as const } : claudeEfforts(model.profile ? entry.profiles?.[model.profile] : undefined);
+      return { id: model.slug, label: model.name, current: model.status === "current", ...efforts };
+    });
+  }
+  models.sort((a, b) => Number(b.current) - Number(a.current));
+  const known = new Set(models.map((model) => model.id));
+  const fallbackEfforts = id === "codex" ? CODEX_EFFORTS : id === "claude" ? (["low", "medium", "high", "xhigh", "max"] as ThinkingLevelName[]) : [];
+  for (const custom of settings.customModels) {
+    if (!known.has(custom)) models.push({ id: custom, label: custom, current: true, efforts: fallbackEfforts, custom: true });
+  }
+  return models;
+}
+
+/** The nearest level at or below `level` that `efforts` holds, else the lowest one above it. */
+export function nearestEffort(efforts: readonly ThinkingLevelName[], level: string): ThinkingLevelName | undefined {
+  if (efforts.length === 0) return undefined;
+  const at = THINKING_LEVELS.indexOf(isLevel(level) ? level : "medium");
+  const below = efforts.filter((effort) => THINKING_LEVELS.indexOf(effort) <= at);
+  return below.length > 0 ? below[below.length - 1] : efforts[0];
+}
+
+/**
+ * What the harness is told for an agent's effort: Codex's `model_reasoning_effort`,
+ * Claude Code's `--effort` (through the model's effort map) or Antigravity's
+ * model variant. Undefined leaves it to the harness (and to ACP session options).
+ */
+export function harnessEffort(id: HarnessId, settings: HarnessSettings, model: string, level: string): string | undefined {
+  const info = HARNESSES[id];
+  if (info.effort === "session") return undefined;
+  const known = harnessModels(id, settings).find((entry) => entry.id === model);
+  if (id === "codex") return nearestEffort(known?.efforts.length ? known.efforts : CODEX_EFFORTS, level);
+  if (id === "claude") {
+    const efforts = known?.efforts.length ? known.efforts : (["low", "medium", "high", "xhigh", "max"] as ThinkingLevelName[]);
+    const chosen = nearestEffort(efforts, level);
+    if (!chosen) return undefined;
+    const key = MANIFEST_KEYS.claude!;
+    const manifestModel = readManifest().providers[key]?.models.find((entry) => entry.slug === model);
+    const profile = manifestModel?.profile ? readManifest().providers[key]?.profiles?.[manifestModel.profile] : undefined;
+    const mapped = profile?.adapter?.claudeCode?.effortMap?.[chosen];
+    return typeof mapped === "string" ? mapped : chosen;
+  }
+  return known?.efforts.length ? nearestEffort(known.efforts, level) : undefined;
+}
+
+/** The model id a run passes to the harness: Antigravity's variant slug carries the effort. */
+export function harnessModelId(id: HarnessId, settings: HarnessSettings, model: string, level: string): string {
+  if (!model || HARNESSES[id].effort !== "variant") return model;
+  const effort = harnessEffort(id, settings, model, level);
+  return effort ? `${model}-${effort}` : model;
+}

package/src/harness/claude-sdk.ts

@@ -0,0 +1,169 @@
+/**
+ * Claude Code through the Claude Agent SDK, Anthropic's supported way for an
+ * app to drive it (and to run on a Claude plan's Agent SDK credit). The SDK
+ * starts the installed `claude` when there is one (or the one set in
+ * Settings > Harnesses), else its own bundled build, and hands back the same
+ * messages as `claude -p --output-format stream-json`, so `claudeEvents`
+ * maps them. When the SDK is not installed, Bot Lobby falls back to the CLI.
+ *
+ * The options follow T3 Code's Claude adapter (`apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts`):
+ * the `claude_code` system prompt preset with Bot Lobby's instructions
+ * appended, the effort, the executable path, extra arguments and the
+ * permission mode.
+ */
+import type { Options, Query, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { PiStreamEvent } from "../execution/pi-runner.ts";
+import { claudeCompactSettings, claudeEnv, claudeEvents, claudeTools, type ClaudeEvent } from "./claude.ts";
+import type { HarnessOutcome, HarnessProcessOptions } from "./process.ts";
+import type { HarnessAccess, HarnessCollector, HarnessPlan } from "./runner.ts";
+import { findCommand } from "./status.ts";
+
+type QueryFn = (params: { prompt: AsyncIterable<SDKUserMessage>; options?: Options }) => Query;
+
+let loader: () => Promise<QueryFn | undefined> = async () => {
+  try {
+    return (await import("@anthropic-ai/claude-agent-sdk")).query as QueryFn;
+  } catch {
+    return undefined;
+  }
+};
+
+/** The SDK's `query`, or undefined when the package is not installed. */
+export function loadClaudeSdk(): Promise<QueryFn | undefined> {
+  return loader();
+}
+
+/** Tests swap the SDK for a fake. */
+export function setClaudeSdkLoader(next: () => Promise<QueryFn | undefined>): void {
+  loader = next;
+}
+
+/** Launch arguments as the SDK's `extraArgs`: `--flag value` pairs, a bare flag as null. */
+export function extraArgsOf(tokens: readonly string[]): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index]!;
+    if (!token.startsWith("-")) continue;
+    const [name, inline] = token.replace(/^-+/, "").split(/=(.*)/s, 2) as [string, string | undefined];
+    const next = tokens[index + 1];
+    if (inline !== undefined) out[name] = inline;
+    else if (next !== undefined && !next.startsWith("-")) {
+      out[name] = next;
+      index++;
+    } else out[name] = null;
+  }
+  return out;
+}
+
+export function claudeSdkOptions(plan: HarnessPlan, access: HarnessAccess, input: { cwd: string; env: Record<string, string | undefined>; launchArgs: string[]; abort: AbortController; stderr: (data: string) => void }): Options {
+  const { settings } = plan.harness;
+  const executable = settings.binaryPath || findCommand("claude");
+  const options: Options = {
+    cwd: input.cwd,
+    abortController: input.abort,
+    persistSession: false,
+    env: { ...input.env, ...claudeEnv(plan), CLAUDE_AGENT_SDK_CLIENT_APP: "bot-lobby" },
+    stderr: input.stderr,
+    ...(executable ? { pathToClaudeCodeExecutable: executable } : {}),
+    ...(plan.model ? { model: plan.model } : {}),
+    ...(plan.effort ? { effort: plan.effort as NonNullable<Options["effort"]> } : {}),
+    ...(plan.instructions ? { systemPrompt: { type: "preset", preset: "claude_code", append: plan.instructions } } : {}),
+    ...(input.launchArgs.length > 0 ? { extraArgs: extraArgsOf(input.launchArgs) } : {}),
+  };
+  const compact = claudeCompactSettings(plan);
+  if (compact) options.settings = compact as Options["settings"];
+  if (access.writes) {
+    options.permissionMode = "bypassPermissions";
+    options.allowDangerouslySkipPermissions = true;
+  } else {
+    const tools = claudeTools(access.tools ?? []);
+    options.tools = tools;
+    options.allowedTools = tools;
+    options.permissionMode = "dontAsk";
+  }
+  return options;
+}
+
+/** The user's messages as the SDK takes them: the prompt, then any steer, until the turn's result. */
+function inputQueue(): { stream: AsyncIterable<SDKUserMessage>; push(text: string): void; end(): void } {
+  const waiting: Array<(result: IteratorResult<SDKUserMessage>) => void> = [];
+  const queued: SDKUserMessage[] = [];
+  let ended = false;
+  const message = (text: string): SDKUserMessage => ({ type: "user", message: { role: "user", content: [{ type: "text", text }] }, parent_tool_use_id: null });
+  return {
+    stream: {
+      [Symbol.asyncIterator]: () => ({
+        next: () => {
+          const item = queued.shift();
+          if (item) return Promise.resolve({ value: item, done: false });
+          if (ended) return Promise.resolve({ value: undefined, done: true });
+          return new Promise((resolve) => waiting.push(resolve));
+        },
+      }),
+    },
+    push(text) {
+      if (ended) return;
+      const item = message(text);
+      const resolve = waiting.shift();
+      if (resolve) resolve({ value: item, done: false });
+      else queued.push(item);
+    },
+    end() {
+      ended = true;
+      for (const resolve of waiting.splice(0)) resolve({ value: undefined, done: true });
+    },
+  };
+}
+
+const MAX_STDERR = 64_000;
+
+/** One turn on Claude Code through the SDK, watched like a harness process (stall, cancel, steer). */
+export async function runClaudeSdk(query: QueryFn, plan: HarnessPlan, access: HarnessAccess, input: { cwd: string; env: Record<string, string | undefined>; launchArgs: string[]; prompt: string }, collected: HarnessCollector, options: HarnessProcessOptions): Promise<HarnessOutcome> {
+  const abort = new AbortController();
+  const queue = inputQueue();
+  let stderr = "";
+  let lastOutput = Date.now();
+  let toolsInFlight = 0;
+  let killed = false;
+  let stalled = false;
+  const emit = (event: PiStreamEvent) => {
+    lastOutput = Date.now();
+    if (event.type === "tool_execution_start") toolsInFlight += 1;
+    if (event.type === "tool_execution_end") toolsInFlight = Math.max(0, toolsInFlight - 1);
+    options.onEvent?.(event);
+  };
+  const handle = claudeEvents({ emit, closeInput: () => queue.end() }, collected);
+  const onAbort = () => {
+    killed = true;
+    queue.end();
+    abort.abort();
+  };
+  const watch = setInterval(() => {
+    const limit = toolsInFlight > 0 ? options.toolStallTimeoutMs : options.stallTimeoutMs;
+    if (!killed && limit && limit > 0 && Date.now() - lastOutput >= limit) {
+      stalled = true;
+      onAbort();
+    }
+  }, 1000);
+  watch.unref();
+  if (options.signal?.aborted) onAbort();
+  else options.signal?.addEventListener("abort", onAbort, { once: true });
+  queue.push(input.prompt);
+  options.onStart?.({ steer: (text) => queue.push(text) });
+  let exitCode = 0;
+  try {
+    const sdkOptions = claudeSdkOptions(plan, access, { ...input, abort, stderr: (data) => { lastOutput = Date.now(); if (stderr.length < MAX_STDERR) stderr += data; } });
+    for await (const message of query({ prompt: queue.stream, options: sdkOptions })) {
+      lastOutput = Date.now();
+      handle(message as unknown as ClaudeEvent);
+    }
+  } catch (error) {
+    exitCode = 1;
+    if (!killed && !collected.error) collected.error = (error as Error).message;
+  } finally {
+    clearInterval(watch);
+    queue.end();
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+  return { exitCode, stderr, killed, stalled };
+}

package/src/harness/claude.ts

@@ -0,0 +1,188 @@
+/**
+ * Claude Code: `claude -p` with stream-json in and out, so a steering message
+ * can be sent while the agent works. Bot Lobby's instructions are appended to
+ * Claude Code's own system prompt from a file; read-only roles get only the
+ * matching tools and `dontAsk`, so anything else is refused.
+ *
+ * The flag set follows T3 Code's `apps/server/src/textGeneration/ClaudeTextGeneration.ts`
+ * (`--tools`, `--allowedTools`, `--permission-mode dontAsk`, `--effort`,
+ * `--settings`) and the auto-compact window of
+ * `apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts`.
+ */
+import type { HarnessDriver, HarnessIO } from "./process.ts";
+import type { HarnessAccess, HarnessCollector, HarnessPlan } from "./runner.ts";
+
+/** pi's tool names and Claude Code's for the same job. */
+const CLAUDE_TOOLS: Record<string, string> = {
+  read: "Read",
+  grep: "Grep",
+  find: "Glob",
+  ls: "Glob",
+  bash: "Bash",
+  edit: "Edit",
+  write: "Write",
+  web_search: "WebSearch",
+  fetch_content: "WebFetch",
+};
+
+/** Claude Code's tool names as pi's, for the activity line and the edit log. */
+const PI_NAMES: Record<string, string> = {
+  Read: "read",
+  Grep: "grep",
+  Glob: "find",
+  LS: "ls",
+  Bash: "bash",
+  Edit: "edit",
+  MultiEdit: "edit",
+  Write: "write",
+  NotebookEdit: "edit",
+  WebSearch: "web_search",
+  WebFetch: "fetch_content",
+};
+
+/** The Claude Code tools a read-only role may use, from its pi allowlist. */
+export function claudeTools(tools: readonly string[]): string[] {
+  return [...new Set(tools.map((tool) => CLAUDE_TOOLS[tool]).filter((tool): tool is string => Boolean(tool)))];
+}
+
+export function claudeArgs(plan: HarnessPlan, access: HarnessAccess, launchArgs: string[], promptFile: string | undefined): { args: string[]; env: Record<string, string> } {
+  const args = ["-p", "--output-format", "stream-json", "--input-format", "stream-json", "--verbose", "--no-session-persistence", ...launchArgs];
+  if (plan.model) args.push("--model", plan.model);
+  if (plan.effort) args.push("--effort", plan.effort);
+  if (promptFile) args.push("--append-system-prompt-file", promptFile);
+  if (access.writes) args.push("--permission-mode", "bypassPermissions");
+  else {
+    const tools = claudeTools(access.tools ?? []).join(",");
+    args.push("--tools", tools, "--allowedTools", tools, "--permission-mode", "dontAsk");
+  }
+  const compact = claudeCompactSettings(plan);
+  if (compact) args.push("--settings", JSON.stringify(compact));
+  return { args, env: claudeEnv(plan) };
+}
+
+/** Claude Code's compaction window, when the settings give one and the agent compacts. */
+export function claudeCompactSettings(plan: HarnessPlan): { autoCompactWindow: number } | undefined {
+  return plan.autoCompact !== false && plan.harness.settings.compactAt > 0 ? { autoCompactWindow: plan.harness.settings.compactAt } : undefined;
+}
+
+/** The environment Claude Code runs with: compaction off and the model provider. */
+export function claudeEnv(plan: HarnessPlan): Record<string, string> {
+  const { settings } = plan.harness;
+  const env: Record<string, string> = {};
+  if (plan.autoCompact === false) env.DISABLE_AUTO_COMPACT = "1";
+  if (settings.modelProvider === "bedrock") env.CLAUDE_CODE_USE_BEDROCK = "1";
+  if (settings.modelProvider === "vertex") env.CLAUDE_CODE_USE_VERTEX = "1";
+  return env;
+}
+
+interface ContentBlock {
+  type?: string;
+  text?: string;
+  thinking?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  is_error?: boolean;
+}
+
+export interface ClaudeEvent {
+  type?: string;
+  subtype?: string;
+  model?: string;
+  message?: { id?: string; model?: string; content?: ContentBlock[] | string };
+  result?: string;
+  is_error?: boolean;
+  total_cost_usd?: number;
+  usage?: { input_tokens?: number; output_tokens?: number; cache_read_input_tokens?: number; cache_creation_input_tokens?: number };
+  errors?: string[];
+}
+
+function userMessage(text: string): string {
+  return JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } });
+}
+
+function toolArgs(input: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!input) return {};
+  const path = input.file_path ?? input.notebook_path ?? input.path;
+  return { ...input, ...(typeof path === "string" ? { path } : {}) };
+}
+
+/** What the Claude Code event handler needs: the stream to emit on, and how to end the turn's input. */
+export interface ClaudeSink {
+  emit: HarnessIO["emit"];
+  closeInput(): void;
+}
+
+/**
+ * Claude Code's messages as pi's stream events. The CLI's stream-json lines
+ * and the Agent SDK's messages are the same objects.
+ */
+export function claudeEvents(io: ClaudeSink, collector: HarnessCollector): (event: ClaudeEvent) => void {
+  const tools = new Map<string, string>();
+  let message: string | undefined;
+  return (event) => {
+    if (event.type === "system" && event.subtype === "init" && event.model) collector.model = event.model;
+    else if (event.type === "system" && event.subtype === "compact_boundary") {
+      io.emit({ type: "compaction" });
+      io.emit({ type: "compaction_end" });
+    } else if (event.type === "assistant" && Array.isArray(event.message?.content)) {
+      if (event.message.id && event.message.id !== message) {
+        message = event.message.id;
+        io.emit({ type: "turn_start" });
+      }
+      if (event.message.model) collector.model = event.message.model;
+      for (const block of event.message.content) {
+        if (block.type === "thinking" && block.thinking?.trim()) io.emit({ type: "thought", text: block.thinking.trim().slice(0, 1500) });
+        else if (block.type === "text" && block.text?.trim()) {
+          io.emit({ type: "writing" });
+          collector.text = block.text;
+        } else if (block.type === "tool_use" && block.id && block.name) {
+          const name = PI_NAMES[block.name] ?? block.name;
+          tools.set(block.id, name);
+          io.emit({ type: "tool_execution_start", toolName: name, args: toolArgs(block.input) });
+        }
+      }
+    } else if (event.type === "user" && Array.isArray(event.message?.content)) {
+      for (const block of event.message.content) {
+        if (block.type !== "tool_result" || !block.tool_use_id) continue;
+        const name = tools.get(block.tool_use_id);
+        if (!name) continue;
+        tools.delete(block.tool_use_id);
+        io.emit({ type: "tool_execution_end", toolName: name, isError: block.is_error === true });
+      }
+    } else if (event.type === "result") {
+      const usage = event.usage ?? {};
+      const input = (usage.input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
+      const output = usage.output_tokens ?? 0;
+      const cost = event.total_cost_usd ?? 0;
+      collector.addUsage(input, output, cost, collector.model);
+      io.emit({ type: "usage", input, output, cost, ...(collector.model ? { model: collector.model } : {}) });
+      if (event.is_error || (event.subtype && event.subtype !== "success")) collector.error = event.result?.trim() || event.errors?.join("; ") || `Claude Code stopped: ${event.subtype ?? "error"}`;
+      else if (typeof event.result === "string" && event.result.trim()) collector.text = event.result;
+      // Claude Code exits once its input is closed and nothing it was sent is left to answer.
+      io.closeInput();
+    }
+  };
+}
+
+export function claudeDriver(io: HarnessIO, prompt: string, collector: HarnessCollector): HarnessDriver {
+  const handle = claudeEvents(io, collector);
+  return {
+    start() {
+      io.write(userMessage(prompt));
+    },
+    steer(text) {
+      io.write(userMessage(text));
+    },
+    line(text) {
+      let event: ClaudeEvent;
+      try {
+        event = JSON.parse(text) as ClaudeEvent;
+      } catch {
+        return;
+      }
+      handle(event);
+    },
+  };
+}

package/src/harness/cli-args.ts

@@ -0,0 +1,62 @@
+/**
+ * Splits a launch-arguments setting into argv the way a POSIX shell would
+ * (quotes, backslash escapes), without running a shell.
+ *
+ * Adapted from T3 Code, `packages/shared/src/cliArgs.ts` (`tokenizeCliArgs`).
+ */
+export function tokenizeCliArgs(args?: string): ReadonlyArray<string> {
+  const input = args?.trim();
+  if (!input) return [];
+
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  let quoted = false;
+
+  for (let index = 0; index < input.length; index++) {
+    const char = input[index];
+    if (char === undefined) continue;
+
+    if (quote) {
+      if (char === quote) {
+        quote = undefined;
+        quoted = true;
+      } else if (char === "\\" && quote === '"') {
+        const next = input[index + 1];
+        if (next !== undefined && ['"', "\\", "$", "`"].includes(next)) {
+          current += next;
+          index++;
+        } else {
+          current += char;
+        }
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      quoted = true;
+    } else if (/\s/.test(char)) {
+      if (current || quoted) {
+        tokens.push(current);
+        current = "";
+        quoted = false;
+      }
+    } else if (char === "\\") {
+      const next = input[index + 1];
+      if (next !== undefined && /[\s'"]/.test(next)) {
+        current += next;
+        index++;
+      } else {
+        current += char;
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current || quoted) tokens.push(current);
+  return tokens;
+}