Add opt-in Claude agent backend (#28)

docs/config.md

@@ -36,6 +36,48 @@ Set `auth = "api-key"` to bill through an OpenAI API key read from
 from `CODEX_HOME/auth.json`; optional `config_dir` points one generated agent
 at a specific Codex config directory.
 
+## Claude agent
+
+`ultrafuzz init` also generates a `ClaudeAgent`, backed by the Claude Code CLI
+(`claude --print`). It is available as an opt-in profile; the default profile
+stays on `CodexAgent`:
+
+```toml
+[models.claude]
+agent = "ClaudeAgent"
+model = "claude-opus-4-8"
+
+[agents.ClaudeAgent]
+auth = "subscription"
+```
+
+Select it per node or group in `.ultrafuzz/topology.yml`
+(`model_profiles = ["claude"]`). `--agent` and `--model` override fields of the
+default profile rather than selecting a profile by id, so a one-off Claude run
+is `ultrafuzz run --agent ClaudeAgent`; add `--model claude-sonnet-5` to pin a
+model, otherwise the Claude CLI default is used.
+
+Set `auth = "subscription"` to run against your logged-in Claude Code CLI
+session with no API key — `ClaudeAgent` clears `ANTHROPIC_API_KEY` so the
+subscription is used; optional `config_dir` sets an isolated `CLAUDE_CONFIG_DIR`
+for running multiple Claude subscriptions side by side. Set `auth = "api-key"`
+to bill against the Anthropic API using the key read from `api_key_env`
+(default `ANTHROPIC_API_KEY`). Both modes drive the `claude` CLI, so it must be
+installed either way; `auth` only changes how that CLI authenticates.
+
+Unlike `CodexAgent`, the Claude Code CLI exposes no reasoning-effort control, so
+a `reasoning` value on a Claude profile is ignored. Pin the model through the
+profile's `model` field rather than under `[agents.ClaudeAgent]`.
+
+`ClaudeAgent` runs every task with Claude Code's permission checks bypassed
+(`--permission-mode bypassPermissions`): the agent has unattended access to the
+filesystem and shell inside its worktree, because no operator is present to
+answer a permission prompt. This follows `permissions.trust_model =
+"skip-permissions"`, the only trust model ultrafuzz accepts, and matches how
+`CodexAgent` already runs. It is fixed rather than configurable per agent — a
+project that needs stricter behaviour must edit the generated
+`.smithers/agents/claude.ts`.
+
 Default triage requires quorum `3` from a panel size of `4`:
 
 ```toml

packages/config/src/model-profiles.ts

@@ -2,6 +2,11 @@ import { z, type ZodIssue } from "zod/v4";
 import { DEFAULT_MODEL_PROFILE_ID, synthesizeDefaultModelProfile } from "./defaults.js";
 import { diagnostic, type ConfigDiagnostic, type ResolvedConfig } from "./types.js";
 
+export interface DefaultProfileOverrides {
+  agent?: string;
+  model?: string;
+}
+
 const MODEL_TIMEOUT_SECONDS = 86_400;
 const PROFILE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const SAFE_AGENT_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_.:-]{0,127}$/;
@@ -89,6 +94,28 @@ export function validProfileId(id: string): boolean {
   return profileIdSchema.safeParse(id).success;
 }
 
+export function applyDefaultProfileOverrides(config: ResolvedConfig, overrides: DefaultProfileOverrides): void {
+  if (overrides.agent === undefined && overrides.model === undefined) {
+    return;
+  }
+  const profile = config.models.profiles[config.models.default];
+  if (profile === undefined) {
+    return;
+  }
+  // A profile's model and reasoning are chosen for its agent, so switching the
+  // agent without naming a model must not hand one backend's model to another.
+  if (overrides.agent !== undefined && overrides.agent !== profile.agent && overrides.model === undefined) {
+    delete profile.model;
+    delete profile.reasoning;
+  }
+  if (overrides.agent !== undefined) {
+    profile.agent = overrides.agent;
+  }
+  if (overrides.model !== undefined) {
+    profile.model = overrides.model;
+  }
+}
+
 function schemaIssues(schema: z.ZodType, value: unknown): ZodIssue[] {
   const parsed = schema.safeParse(value);
   return parsed.success ? [] : parsed.error.issues;

packages/runtime/src/init.ts

@@ -8,11 +8,17 @@ import { builtInPromptRelativePaths, scaffoldPrompts } from "@ultrafuzz/prompts"
 import { defaultReferenceCatalogYaml } from "@ultrafuzz/references";
 import { loadRuntimeTemplate } from "./runtime-template.js";
 import { renderSmithersPackageJson } from "./smithers-package.js";
-import type { InitProjectInput, InitProjectResult } from "./types.js";
+import type { InitProjectInput, InitProjectResult, RuntimeDiagnostic } from "./types.js";
 import { configDiagnostics, runtimeFailure, runtimeResult, toProjectRelative } from "./utils.js";
 
 const DEFAULT_TOPOLOGY = loadDefaultTopology();
 
+const AGENT_REGISTRY_FILE = ".smithers/agents/index.ts";
+const AGENT_TEMPLATES = [
+  { file: "claude.ts", template: "smithers/agents/claude.tsx", ref: "ClaudeAgent" },
+  { file: "codex.ts", template: "smithers/agents/codex.tsx", ref: "CodexAgent" }
+] as const;
+
 export function initProject(input: InitProjectInput) {
   const projectRoot = path.resolve(input.projectRoot);
   const created: string[] = [];
@@ -104,13 +110,24 @@ export function initProject(input: InitProjectInput) {
     );
     writeProjectFile(
       projectRoot,
-      ".smithers/agents/codex.ts",
-      loadRuntimeTemplate("smithers/agents/codex.tsx"),
+      ".smithers/agents/toml.ts",
+      loadRuntimeTemplate("smithers/agents/toml.tsx"),
       input.force === true,
       created,
       preserved,
       overwritten
     );
+    for (const agent of AGENT_TEMPLATES) {
+      writeProjectFile(
+        projectRoot,
+        `.smithers/agents/${agent.file}`,
+        loadRuntimeTemplate(agent.template),
+        input.force === true,
+        created,
+        preserved,
+        overwritten
+      );
+    }
   } catch {
     return runtimeFailure<InitProjectResult>([
       {
@@ -152,12 +169,48 @@ export function initProject(input: InitProjectInput) {
     preserved.push(toProjectRelative(projectRoot, absolutePath));
   }
 
-  return runtimeResult(true, {
-    project_root: projectRoot,
-    created: publicInitPaths(created),
-    preserved: publicInitPaths(preserved),
-    overwritten: publicInitPaths(overwritten)
-  });
+  return runtimeResult(
+    true,
+    {
+      project_root: projectRoot,
+      created: publicInitPaths(created),
+      preserved: publicInitPaths(preserved),
+      overwritten: publicInitPaths(overwritten)
+    },
+    staleAgentRegistryDiagnostics(projectRoot)
+  );
+}
+
+// init preserves project-owned files, so a project scaffolded before an agent
+// was added keeps its old registry: the new adapter lands on disk but nothing
+// exports it, and the agent is only rejected later, at launch. Report it here
+// instead of leaving the mismatch silent.
+function staleAgentRegistryDiagnostics(projectRoot: string): RuntimeDiagnostic[] {
+  const registryPath = path.join(projectRoot, AGENT_REGISTRY_FILE);
+  if (!fs.existsSync(registryPath)) {
+    return [];
+  }
+  const registryText = fs.readFileSync(registryPath, "utf8");
+  return AGENT_TEMPLATES.filter(
+    (agent) =>
+      fs.existsSync(path.join(projectRoot, ".smithers", "agents", agent.file)) &&
+      !registersAgentFactory(registryText, agent.ref)
+  ).map((agent) => ({
+    code: "INIT_AGENT_REGISTRY_STALE",
+    message: `${AGENT_REGISTRY_FILE} does not register ${agent.ref} in agentFactories, so runs cannot select it; rerun ultrafuzz init --force to regenerate the registry, or add the entry by hand`,
+    severity: "warning" as const,
+    source: "runtime",
+    path: AGENT_REGISTRY_FILE
+  }));
+}
+
+// Generated adapters export only their factory, so agentFactories is the sole
+// path that resolves them. Merely naming the agent elsewhere in the registry --
+// an `export { ClaudeAgent }` left over from an older adapter, say -- does not
+// make it selectable, so match the factory entry rather than the bare name.
+function registersAgentFactory(registryText: string, ref: string): boolean {
+  const factories = /agentFactories\s*=\s*\{([^}]*)\}/u.exec(registryText);
+  return factories === null ? false : new RegExp(`\\b${ref}\\s*:`, "u").test(factories[1] ?? "");
 }
 
 function writeProjectFile(

packages/runtime/src/plan-run.ts

@@ -11,7 +11,11 @@ import {
   type NodeStateInput,
   type RunLayout
 } from "@ultrafuzz/artifacts";
-import { redactResolvedConfig, serializeRedactedResolvedConfigToml } from "@ultrafuzz/config";
+import {
+  applyDefaultProfileOverrides,
+  redactResolvedConfig,
+  serializeRedactedResolvedConfigToml
+} from "@ultrafuzz/config";
 import {
   loadPromptCatalog,
   renderPrompt,
@@ -398,19 +402,7 @@ function renderPromptsForPlan(input: {
 }
 
 function applyWorkflowRunOverrides(config: PlanRunValue["resolved_config"], input: PlanRunInput): void {
-  if (input.agent === undefined && input.model === undefined) {
-    return;
-  }
-  const profile = config.models.profiles[config.models.default];
-  if (profile === undefined) {
-    return;
-  }
-  if (input.agent !== undefined) {
-    profile.agent = input.agent;
-  }
-  if (input.model !== undefined) {
-    profile.model = input.model;
-  }
+  applyDefaultProfileOverrides(config, { agent: input.agent, model: input.model });
 }
 
 function promptLogicalNodes(graph: PlannedGraph, layout: PlanRunValue["layout"]): PromptGraphNode[] {

packages/runtime/src/templates/smithers/agents/claude.tsx

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { ClaudeCodeAgent as SmithersClaudeCodeAgent } from "smithers-orchestrator";
+import { readStringTable, stringField } from "./toml";
+
+type ClaudeAuthConfig = { auth?: string; api_key_env?: string; config_dir?: string };
+type ClaudeAuthOptions = { apiKey?: string; configDir?: string };
+// reasoningEffort is part of the shared agent factory contract but has no
+// ClaudeCodeAgent equivalent, so it is accepted and ignored.
+export type ClaudeTaskOptions = { model?: string; reasoningEffort?: string };
+
+export function createClaudeAgent(options: ClaudeTaskOptions = {}): SmithersClaudeCodeAgent {
+  return new SmithersClaudeCodeAgent({
+    ...(options.model === undefined ? {} : { model: options.model }),
+    // Every task runs with Claude Code's permission checks off: agents work
+    // unattended in a throwaway worktree, so there is nobody to answer a
+    // prompt. This mirrors permissions.trust_model = "skip-permissions" in
+    // ultrafuzz.toml, which is the only trust model ultrafuzz accepts, and is
+    // deliberately not configurable per agent -- edit this generated file if a
+    // project needs otherwise.
+    permissionMode: "bypassPermissions",
+    ...claudeAuthOptions()
+  });
+}
+
+function claudeAuthOptions(): ClaudeAuthOptions {
+  const config = readClaudeAuthConfig();
+  const auth = config.auth ?? "subscription";
+  if (auth === "api-key") {
+    return { apiKey: requiredEnv(config.api_key_env ?? "ANTHROPIC_API_KEY") };
+  }
+  if (auth === "subscription") {
+    // ClaudeCodeAgent clears ANTHROPIC_API_KEY itself so the logged-in
+    // Claude subscription (`claude -p`) is used; we only forward an
+    // isolated config directory when one is configured.
+    return config.config_dir === undefined ? {} : { configDir: resolveConfigDir(config.config_dir) };
+  }
+  throw new Error(`unsupported ClaudeAgent auth mode in ultrafuzz.toml: ${auth}`);
+}
+
+function readClaudeAuthConfig(): ClaudeAuthConfig {
+  const configPath = path.join(process.cwd(), "ultrafuzz.toml");
+  const claude = readStringTable(readFileSync(configPath, "utf8"), "agents.ClaudeAgent");
+  return {
+    auth: stringField(claude, "auth"),
+    api_key_env: stringField(claude, "api_key_env"),
+    config_dir: stringField(claude, "config_dir")
+  };
+}
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value.trim() === "") {
+    throw new Error(`agents.ClaudeAgent auth is api-key, but ${name} is not set`);
+  }
+  return value;
+}
+
+function resolveConfigDir(value: string): string {
+  if (value.trim() === "") {
+    throw new Error("agents.ClaudeAgent.config_dir cannot be empty");
+  }
+  return path.isAbsolute(value) ? value : path.resolve(process.cwd(), value);
+}

packages/runtime/src/templates/smithers/agents/codex.tsx

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { CodexAgent as SmithersCodexAgent } from "smithers-orchestrator";
+import { readStringTable, stringField } from "./toml";
 
 type CodexAuthConfig = { auth?: string; api_key_env?: string; config_dir?: string };
 type CodexAuthOptions = { apiKey?: string; configDir?: string; env?: Record<string, string> };
@@ -15,8 +16,6 @@ export function createCodexAgent(options: CodexTaskOptions = {}): SmithersCodexA
   });
 }
 
-export const CodexAgent = createCodexAgent();
-
 function codexAuthOptions(): CodexAuthOptions {
   const config = readCodexAuthConfig();
   const auth = config.auth ?? "subscription";
@@ -42,38 +41,6 @@ function readCodexAuthConfig(): CodexAuthConfig {
   };
 }
 
-function readStringTable(text: string, tableName: string): Record<string, string> {
-  const fields: Record<string, string> = {};
-  let inTable = false;
-  for (const rawLine of text.split(/\r?\n/u)) {
-    const line = rawLine.trim();
-    if (line === "" || line.startsWith("#")) {
-      continue;
-    }
-    const table = /^\[([^\]]+)\]$/u.exec(line);
-    if (table) {
-      inTable = table[1]?.trim() === tableName;
-      continue;
-    }
-    if (!inTable) {
-      continue;
-    }
-    const assignment = /^([A-Za-z0-9_-]+)\s*=\s*"((?:\\.|[^"\\])*)"\s*(?:#.*)?$/u.exec(line);
-    if (assignment?.[1] && assignment[2] !== undefined) {
-      fields[assignment[1]] = JSON.parse(`"${assignment[2]}"`) as string;
-    }
-  }
-  return fields;
-}
-
-function stringField(table: Record<string, string>, key: string): string | undefined {
-  const value = table[key];
-  if (value === undefined) {
-    return undefined;
-  }
-  return value;
-}
-
 function requiredEnv(name: string): string {
   const value = process.env[name];
   if (value === undefined || value.trim() === "") {

packages/runtime/src/templates/smithers/agents/index.tsx

@@ -1,4 +1,10 @@
+import { createClaudeAgent } from "./claude";
 import { createCodexAgent } from "./codex";
 
-export { CodexAgent, createCodexAgent } from "./codex";
-export const agentFactories = { CodexAgent: createCodexAgent };
+export { createClaudeAgent } from "./claude";
+export { createCodexAgent } from "./codex";
+
+// Agents are constructed per task from the selected model profile, never at
+// import time: an agent's auth is only read when that agent is actually used,
+// so a project running one backend does not need the other's credentials.
+export const agentFactories = { ClaudeAgent: createClaudeAgent, CodexAgent: createCodexAgent };