copperhead 0.4.0 → 0.6.0

package/dist/memory/scaffold.js

@@ -99,7 +99,8 @@ Generated by \`copperhead init\`; regenerated on re-runs (do not hand-edit).
 
 - \`schematic\` / \`board\`: repo-relative paths to the KiCad files copperhead operates on (currently: ${config.schematic ?? 'none'} / ${config.board ?? 'none'})
 - \`docs\`: design docs directory (docs-as-memory), default \`docs/\`
-- \`model\`: default model (\`gpt-5\` or \`claude\`); overridden by \`--model\` and \`COPPERHEAD_MODEL\`
+- \`model\`: default provider/model (\`codex\`, \`gpt-5\`, or \`claude\`); overridden by \`--model\` and \`COPPERHEAD_MODEL\`
+- local Codex uses the saved \`codex login\`; set \`COPPERHEAD_CODEX_PATH\` only when the executable is not on \`PATH\`
 - \`maxTurns\`: agent loop turn budget per run (default 40)
 - \`maxRepairCycles\`: ERC/DRC repair attempts before rollback (default 5)
 - \`budgets\`: free-form hard constraints (e.g. \`"sleep_current_uA": 25\`); surfaced verbatim into every run's system prompt

package/dist/memory/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../src/memory/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,OAAO,EAAqC,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAyB,MAAM,cAAc,CAAC;AAE7E,MAAM,OAAO,SAAU,SAAQ,KAAK;CAAG;AAQvC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEhF,KAAK,UAAU,cAAc,CAAC,UAAkB;IAC9C,IAAI,GAAG,GAAkB,IAAI,CAAC;IAC9B,IAAI,GAAG,GAAkB,IAAI,CAAC;IAC9B,KAAK,UAAU,IAAI,CAAC,GAAW;QAC7B,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YAChE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc;gBAAE,SAAS;YAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;iBACpC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG;gBAAE,GAAG,GAAG,GAAG,CAAC;iBACzD,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG;gBAAE,GAAG,GAAG,GAAG,CAAC;QAChE,CAAC;IACH,CAAC;IACD,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,QAAQ,CAAC,OAA0B;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CACtB,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,SAAS,+DAA+D,CAC/G,CAAC;IACF,OAAO,CAAC,kDAAkD,EAAE,uBAAuB,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3G,CAAC;AAED,SAAS,WAAW,CAAC,IAAc;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IAChG,OAAO,CAAC,uCAAuC,EAAE,uBAAuB,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChG,CAAC;AAED,SAAS,YAAY,CACnB,WAAmB,EACnB,OAA0B,EAC1B,IAAc;IAEd,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxF,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,OAAO;QACL,SAAS,EAAE,KAAK,WAAW;;;;;;;;;;;;CAY9B;QACG,QAAQ,EAAE;;;;;EAKZ,QAAQ,CAAC,OAAO,CAAC;CAClB;QACG,WAAW,EAAE;;;;;EAKf,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;CAC7C;QACG,eAAe,EAAE;;;;EAInB,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,KAAK,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;CAC1L;QACG,WAAW,EAAE;;;;;;;CAOhB;QACG,cAAc,EAAE;;;;CAInB;QACG,cAAc,EAAE;;;CAGnB;KACE,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAwB;IAChD,OAAO;;;;;;yGAMgG,MAAM,CAAC,SAAS,IAAI,MAAM,MAAM,MAAM,CAAC,KAAK,IAAI,MAAM;;;;;;;;;;;;;;;;;;;;;CAqB9J,CAAC;AACF,CAAC;AAED,MAAM,WAAW,GAAG,gCAAgC,CAAC;AAErD,KAAK,UAAU,oBAAoB,CAAC,QAAgB;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACnD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAClD,IAAI,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,aAAa;QAC9D,OAAO,IAAI,CAAC,CAAC,kCAAkC;IACjD,CAAC;IACD,MAAM,MAAM,GAAG;EACf,WAAW;;;CAGZ,CAAC;IACA,MAAM,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC7B,OAAO,QAAQ,CAAC;AAClB,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAiB;IAC7C,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC1B,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;IAClE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,cAAc,CAAC,UAAU,CAAC,CAAC;IACtD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,SAAS,CACjB,6BAA6B,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,GAAG,uEAAuE,CAC/I,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAChD,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAEtD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,MAAM,MAAM,GAAe,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACrE,MAAM,MAAM,GAA2B,EAAE,GAAG,CAAC,MAAM,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,CAAC;IAC7E,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC;IAE7D,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YACnB,MAAM,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,yCAAyC;YACnE,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBACxB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;iBAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACtB,MAAM,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;gBACpC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC5B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,wEAAwE;gBACxE,MAAM,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;gBACpC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC5B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;aAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,MAAM,CAAC,eAAe,GAAG,MAAM,CAAC;IAChC,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACzE,yDAAyD;IACzD,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAEnG,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,IAAI;YAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../src/memory/scaffold.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copperhead",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Cursor for circuit boards: an AI agent that designs, documents, and validates real PCBs on KiCad repositories",
   "license": "Apache-2.0",
   "author": "Animesh Chouhan <animeshchouhan@outlook.com>",
@@ -48,6 +48,7 @@
     "prepublishOnly": "npm run typecheck && npm run build",
     "dev": "tsx src/cli.ts",
     "demo:simple": "bash scripts/demo-simple.sh",
+    "lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules/**\" \"#**/node_modules/**\" \"#dist/**\" \"#**/dist/**\" \"#docs/.astro/**\" \"#demo-runs/**\" \"#.copperhead/runs/**\" \"#_site/**\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -56,20 +57,34 @@
     "docs:preview": "npm --prefix docs run preview"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
+    "@anthropic-ai/sdk": "^0.113.0",
     "commander": "^12.1.0",
     "execa": "^9.5.2",
     "openai": "^4.87.3"
   },
   "optionalDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.217",
     "@maximem/synap-js-sdk": "^0.3.0"
   },
+  "overrides": {
+    "zod": "^4.0.0"
+  },
   "devDependencies": {
+    "@openai/codex-sdk": "^0.144.6",
     "@types/node": "^22.13.10",
+    "markdownlint-cli2": "0.22.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
     "vitest": "^3.0.8"
   },
+  "peerDependencies": {
+    "@openai/codex-sdk": "^0.144.6"
+  },
+  "peerDependenciesMeta": {
+    "@openai/codex-sdk": {
+      "optional": true
+    }
+  },
   "allowScripts": {
     "esbuild@0.28.1": true,
     "esbuild@0.21.5": true

package/src/agent/loop.ts

@@ -16,6 +16,8 @@ import { openspecArchive } from '../openspec/cli.js';
 import { existsSync } from 'node:fs';
 import { OpenAIProvider } from './providers/openai.js';
 import { AnthropicProvider } from './providers/anthropic.js';
+import { CodexProvider } from './providers/codex.js';
+import { ClaudeCodeProvider } from './providers/claude-code.js';
 import { openSynapMemory, type RunRecord, type SynapMemory } from '../memory/synap.js';
 
 /** What the user sees at the moment they decide whether to keep going. */
@@ -63,7 +65,34 @@ export interface RunResult {
   commit: string | null;
 }
 
-export function makeProvider(model: string): Provider {
+export async function makeProvider(model: string): Promise<Provider> {
+  if (model === 'codex' || model.startsWith('codex:')) {
+    const codexModel = model.startsWith('codex:') ? model.slice('codex:'.length) : undefined;
+    if (codexModel === '') throw new Error('codex model override cannot be empty; use "codex" or "codex:<model-id>"');
+    const { Codex } = await import('@openai/codex-sdk').catch((err: unknown) => {
+      throw new Error(
+        'Codex provider requires the optional @openai/codex-sdk package; install it alongside Copperhead before using --model codex',
+        { cause: err },
+      );
+    });
+    return new CodexProvider({
+      ...(codexModel ? { model: codexModel } : {}),
+      client: new Codex({
+        // Use the user's installed CLI and its saved login rather than a model API key.
+        codexPathOverride: process.env.COPPERHEAD_CODEX_PATH || 'codex',
+      }),
+    });
+  }
+  // Match claude-code before the `claude*` prefix: both `claude-code` and
+  // `claude-code:<id>` start with `claude` and would otherwise route to the
+  // Anthropic API provider.
+  if (model === 'claude-code' || model.startsWith('claude-code:')) {
+    const claudeCodeModel = model.startsWith('claude-code:') ? model.slice('claude-code:'.length) : undefined;
+    if (claudeCodeModel === '') {
+      throw new Error('claude-code model override cannot be empty; use "claude-code" or "claude-code:<model-id>"');
+    }
+    return new ClaudeCodeProvider(claudeCodeModel);
+  }
   if (model === 'claude' || model.startsWith('claude')) {
     return new AnthropicProvider(model === 'claude' ? undefined : model);
   }
@@ -71,6 +100,8 @@ export function makeProvider(model: string): Provider {
 }
 
 function otherProvider(current: Provider): Provider | null {
+  // Only the two keyed providers fail over to each other. A rate-limited
+  // 'claude-code' run returns null here (no silent fallback to a paid API).
   if (current.name === 'openai' && process.env.ANTHROPIC_API_KEY) return new AnthropicProvider();
   if (current.name === 'anthropic' && process.env.OPENAI_API_KEY) return new OpenAIProvider();
   return null;
@@ -117,14 +148,26 @@ async function appendChangelog(
  */
 export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
   const memory = await openSynapMemory({ repoRoot: opts.repoRoot, log: opts.log });
+  const providers = new Set<Provider>();
   try {
-    return await runWithMemory(opts, memory);
+    return await runWithMemory(opts, memory, providers);
   } finally {
+    for (const provider of providers) {
+      try {
+        await provider.close?.();
+      } catch (err) {
+        opts.log?.(`warning: ${provider.name} provider cleanup failed (${(err as Error).message})`);
+      }
+    }
     await memory?.close();
   }
 }
 
-async function runWithMemory(opts: RunOptions, memory: SynapMemory | null): Promise<RunResult> {
+async function runWithMemory(
+  opts: RunOptions,
+  memory: SynapMemory | null,
+  providers: Set<Provider>,
+): Promise<RunResult> {
   const r = opts.renderer ?? plainRenderer(opts.log ?? ((l: string) => console.log(l)));
   const log = (l: string): void => r.log(l);
   const repoRoot = opts.repoRoot;
@@ -155,7 +198,8 @@ async function runWithMemory(opts: RunOptions, memory: SynapMemory | null): Prom
     finishRequest: null,
   };
 
-  let provider = opts.provider ?? makeProvider(opts.model);
+  let provider = opts.provider ?? (await makeProvider(opts.model));
+  providers.add(provider);
 
   // Deterministic, LLM-free metadata block: collected once, rendered onto all
   // three surfaces (run-start event, summary ## Environment, CLI header) so
@@ -359,6 +403,7 @@ async function runWithMemory(opts: RunOptions, memory: SynapMemory | null): Prom
           log(`failing over ${provider.name} → ${fallback.name}`);
           await transcript.event('provider-failover', { from: provider.name, to: fallback.name });
           provider = fallback;
+          providers.add(provider);
           turn--;
           continue;
         }

package/src/agent/providers/claude-code.ts

@@ -0,0 +1,367 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { ChatOpts, Msg, Provider, ToolCall, ToolSchema, Turn } from '../types.js';
+
+/**
+ * Saved-login provider: drives Claude Code through the Claude Agent SDK
+ * (`@anthropic-ai/claude-agent-sdk`) and reuses its saved login (the
+ * `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`, or a logged-in CLI), so a
+ * Claude subscription user runs copperhead with no ANTHROPIC_API_KEY. What is
+ * reused is the login, not necessarily a separately-installed `claude` binary:
+ * the SDK ships its own. See the `add-claude-code-provider` change (D1–D6).
+ *
+ * It is a REASONING-ONLY backend. The Agent SDK is built to run its own
+ * autonomous multi-turn tool loop, which conflicts with copperhead's contract
+ * that `loop.ts` is the single driver and every mutation flows through the
+ * capability-filtered tools, obligations ledger, ERC/DRC gates, snapshot, and
+ * commit gate. So each `chat()` issues exactly ONE `query()` with no SDK tools
+ * registered and built-ins disabled, in an isolated cwd — the SDK executes
+ * nothing. copperhead's tools are advertised to the model as a text protocol;
+ * the model replies with a JSON tool-call block that we parse back into
+ * `Turn.toolCalls`. The spec-gated-in invariant stays structural: we advertise
+ * exactly the tools `availableTools(ctx)` returned for the turn.
+ *
+ * Auth stays external (D2): the constructor performs no API-key check and the
+ * provider never reads, copies, or logs the credential — the SDK resolves
+ * CLAUDE_CODE_OAUTH_TOKEN / the logged-in CLI itself.
+ */
+
+/** Structural subset of the Agent SDK's `query` surface we depend on. Declared
+ * locally rather than `import type`d from the SDK on purpose: the SDK is an
+ * undeclared optional dependency (design D3), so importing its types would force
+ * it to be installed for `tsc` to pass — the exact coupling `codex.ts` now has.
+ * Naming the options here still compile-checks our option keys (e.g. `tools`),
+ * which is the safety the review asked for without the packaging cost. */
+export type DenyResult = { behavior: 'deny'; message: string; interrupt?: boolean };
+export type AllowResult = { behavior: 'allow'; updatedInput?: Record<string, unknown> };
+export type CanUseToolLike = (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<DenyResult | AllowResult>;
+
+export interface QueryOptions {
+  systemPrompt?: string;
+  model?: string;
+  /** `[]` disables all built-in tools (Agent SDK 0.3.x). */
+  tools?: string[];
+  disallowedTools?: string[];
+  /** Called before any tool executes; we deny everything (reasoning-only). */
+  canUseTool?: CanUseToolLike;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  maxTurns?: number;
+}
+export interface QueryArgs {
+  prompt: string;
+  options?: QueryOptions;
+}
+export interface QueryMessage {
+  type: string;
+  subtype?: string;
+  message?: { content?: Array<{ type: string; text?: string }> };
+  usage?: { input_tokens?: number; output_tokens?: number };
+}
+export type QueryLike = (args: QueryArgs) => AsyncIterable<QueryMessage>;
+
+/** Injectable dynamic import of the optional SDK. Exists so the
+ * missing-dependency path stays testable now that the SDK is a declared
+ * optional dependency (installed in a normal/CI install). The default keeps the
+ * specifier non-literal so tsc never resolves the optional dep at build time. */
+export type ImportLike = (specifier: string) => Promise<unknown>;
+
+/** Explicit deny list, belt-and-suspenders on top of the empty `tools` allowlist.
+ * `'*'` is the documented wildcard; the named entries stay for clarity and in
+ * case a given SDK build does not honor the wildcard. */
+const DISALLOWED_BUILTINS = [
+  '*',
+  'Bash',
+  'Edit',
+  'MultiEdit',
+  'Write',
+  'Read',
+  'Glob',
+  'Grep',
+  'NotebookEdit',
+  'WebFetch',
+  'WebSearch',
+  'Task',
+  'TodoWrite',
+];
+
+export class ClaudeCodeProvider implements Provider {
+  readonly name = 'claude-code';
+  private callSeq = 0;
+  private cwdPromise?: Promise<string>;
+
+  constructor(
+    private readonly model?: string,
+    private readonly injectedQuery?: QueryLike,
+    private readonly importSdk: ImportLike = (specifier) => import(specifier),
+  ) {}
+
+  // `_opts.maxTokens` is intentionally ignored: the Agent SDK drives the Claude
+  // Code subprocess and exposes no per-call max-tokens knob. loop.ts calls
+  // chat() without opts today; noted so a future opts pass is not a surprise.
+  async chat(messages: Msg[], tools: ToolSchema[], _opts: ChatOpts = {}): Promise<Turn> {
+    const query = await this.resolveQuery();
+
+    const system = messages
+      .filter((m) => m.role === 'system')
+      .map((m) => m.content)
+      .join('\n\n');
+    const systemPrompt = [system, renderToolProtocol(tools)].filter(Boolean).join('\n\n');
+    const prompt = renderConversation(messages);
+    const catalog = new Set(tools.map((t) => t.name));
+    const cwd = await this.ensureCwd();
+
+    let text: string | null = null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    try {
+      for await (const msg of query({
+        prompt,
+        options: {
+          systemPrompt,
+          ...(this.model ? { model: this.model } : {}),
+          // Layered "the SDK executes nothing" defense (D1/D5):
+          //  1. `tools: []` disables ALL built-in tools (Agent SDK 0.3.x docs:
+          //     "[] (empty array) - Disable all built-in tools").
+          //  2. `disallowedTools` denies by name, with a wildcard, as a backstop.
+          //  3. `canUseTool` denies every tool BEFORE it runs — the permission
+          //     analog to Codex's read-only sandbox — so even an unrecognized
+          //     future tool cannot execute.
+          //  4. The tool_use tripwire below fails the run loudly if one is
+          //     emitted anyway. Any single layer failing is caught by the next.
+          tools: [],
+          disallowedTools: DISALLOWED_BUILTINS,
+          canUseTool: async (toolName) => ({
+            behavior: 'deny',
+            message: `copperhead claude-code is reasoning-only; the SDK must not execute tools (blocked ${toolName}).`,
+            interrupt: true,
+          }),
+          cwd,
+          // The SDK's `env` REPLACES the subprocess environment entirely, so
+          // inherit process.env and strip the billed API keys: a claude-code run
+          // must use the saved login and never silently a paid ANTHROPIC_API_KEY
+          // / OPENAI_API_KEY, even when one is also set (D2).
+          env: { ...process.env, ANTHROPIC_API_KEY: undefined, OPENAI_API_KEY: undefined },
+          maxTurns: 1,
+        },
+      })) {
+        if (msg.type === 'assistant') {
+          for (const block of msg.message?.content ?? []) {
+            if (block.type === 'text' && block.text) {
+              text = (text ?? '') + block.text;
+            } else if (block.type === 'tool_use') {
+              // Load-bearing invariant (D1): the SDK must execute nothing, so it
+              // must never emit a tool_use block. If it does, `tools: []` was not
+              // honored — fail loudly rather than let an edit bypass copperhead's
+              // snapshot / verify / commit gates.
+              throw new Error(
+                'claude-code: the Agent SDK emitted a tool_use block, but its tools are ' +
+                  'disabled — the reasoning-only invariant was violated (SDK option drift?). ' +
+                  'Refusing to continue.',
+              );
+            }
+          }
+        } else if (msg.type === 'result') {
+          if (typeof msg.usage?.input_tokens === 'number') inputTokens = msg.usage.input_tokens;
+          if (typeof msg.usage?.output_tokens === 'number') outputTokens = msg.usage.output_tokens;
+        }
+      }
+    } catch (err) {
+      // Auth failures get an actionable message (non-retryable); everything else
+      // — crucially a 429 — is re-thrown untouched so its status survives for
+      // withRetry/isRateLimit (D4). We never fall back to a keyed provider: the
+      // distinct `name` makes otherProvider() return null for us.
+      if (isAuthError(err)) throw new Error(authHint((err as Error).message));
+      throw err;
+    }
+
+    const parsed = parseToolCalls(text, () => `cc-${++this.callSeq}`, catalog);
+    return { text: parsed.text, toolCalls: parsed.toolCalls, usage: { inputTokens, outputTokens } };
+  }
+
+  /** Remove the scratch cwd. loop.ts calls this on every provider in a finally,
+   * so the one temp dir this instance created does not leak past the run. */
+  async close(): Promise<void> {
+    const pending = this.cwdPromise;
+    this.cwdPromise = undefined;
+    if (!pending) return;
+    try {
+      await rm(await pending, { recursive: true, force: true });
+    } catch {
+      // best effort: a leftover empty dir in the OS tmpdir is harmless
+    }
+  }
+
+  /** One isolated scratch cwd per provider instance, created once and reused
+   * across turns so a long run does not leak a temp dir per turn. Even with
+   * tools disabled this guarantees the SDK has no path into the repo (D5). */
+  private ensureCwd(): Promise<string> {
+    if (!this.cwdPromise) this.cwdPromise = mkdtemp(path.join(os.tmpdir(), 'copperhead-cc-'));
+    return this.cwdPromise;
+  }
+
+  private async resolveQuery(): Promise<QueryLike> {
+    if (this.injectedQuery) return this.injectedQuery;
+    let mod: { query?: QueryLike; default?: { query?: QueryLike } };
+    try {
+      // importSdk defaults to a non-literal `import()`, so tsc never resolves the
+      // optional dependency at build time and it may legitimately be absent (D3).
+      mod = (await this.importSdk('@anthropic-ai/claude-agent-sdk')) as {
+        query?: QueryLike;
+        default?: { query?: QueryLike };
+      };
+    } catch (err) {
+      // Only a genuinely-absent module gets the "install it" message; a present
+      // but broken install surfaces its real error rather than being mislabeled.
+      const code = (err as { code?: string }).code;
+      if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') {
+        throw new Error(
+          'the claude-code provider needs the optional dependency @anthropic-ai/claude-agent-sdk; ' +
+            'install it with `npm i @anthropic-ai/claude-agent-sdk`',
+        );
+      }
+      throw err;
+    }
+    const query = mod.query ?? mod.default?.query;
+    if (!query) {
+      throw new Error(
+        '@anthropic-ai/claude-agent-sdk did not export `query`; the installed version may be incompatible',
+      );
+    }
+    return query;
+  }
+}
+
+function renderToolProtocol(tools: ToolSchema[]): string {
+  if (!tools.length) return '';
+  const lines = [
+    '# Tool protocol',
+    '',
+    'You are the reasoning half of a tool-driven workflow; you cannot run anything yourself.',
+    'To take an action, reply with EXACTLY ONE JSON object and nothing else, wrapped in a',
+    '```json fenced code block:',
+    '',
+    '```json',
+    '{"tool": "<tool_name>", "args": { ... }}',
+    '```',
+    '',
+    'Use only the tools listed below, with `args` matching the tool\'s JSON Schema. If you have',
+    'no tool to call and only want to say something, reply with plain prose and no JSON block.',
+    '',
+    '## Available tools',
+  ];
+  for (const t of tools) {
+    lines.push(
+      '',
+      `### ${t.name}`,
+      t.description,
+      `Parameters (JSON Schema): ${JSON.stringify(t.parameters)}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+function renderConversation(messages: Msg[]): string {
+  const idToName = new Map<string, string>();
+  const parts: string[] = [];
+  for (const m of messages) {
+    if (m.role === 'system') continue;
+    if (m.role === 'user') {
+      parts.push(`[user]\n${m.content}`);
+    } else if (m.role === 'assistant') {
+      if (m.content) parts.push(`[assistant]\n${m.content}`);
+      for (const call of m.toolCalls ?? []) {
+        idToName.set(call.id, call.name);
+        parts.push(
+          `[assistant tool call]\n\`\`\`json\n${JSON.stringify({ tool: call.name, args: call.args })}\n\`\`\``,
+        );
+      }
+    } else {
+      const name = idToName.get(m.toolCallId) ?? m.toolCallId;
+      parts.push(`[result of ${name}]\n${m.content}`);
+    }
+  }
+  return parts.join('\n\n');
+}
+
+interface Parsed {
+  text: string | null;
+  toolCalls: ToolCall[];
+}
+
+/**
+ * Extract tool-call JSON from the model's reply. Tolerant by design (D1):
+ * unparseable output is returned as plain text with no tool calls rather than
+ * throwing, so a non-conforming turn degrades to the loop's stall/nudge path.
+ * A parsed block only counts as a tool call when its name is in the current
+ * turn's catalog (`availableTools(ctx)`): a hallucinated or locked tool name is
+ * left as prose so the loop nudges, rather than dispatching a bogus call.
+ */
+function parseToolCalls(text: string | null, nextId: () => string, catalog: Set<string>): Parsed {
+  if (!text) return { text: null, toolCalls: [] };
+  const toolCalls: ToolCall[] = [];
+  let prose = text;
+
+  const fence = /```(?:json)?\s*([\s\S]*?)```/gi;
+  let match: RegExpExecArray | null;
+  const consumed: string[] = [];
+  while ((match = fence.exec(text)) !== null) {
+    const call = toToolCall(match[1], nextId, catalog);
+    if (call) {
+      toolCalls.push(call);
+      consumed.push(match[0]);
+    }
+  }
+  for (const block of consumed) prose = prose.replace(block, '');
+
+  // No fenced tool block: maybe the whole reply is a bare JSON object.
+  if (!toolCalls.length) {
+    const call = toToolCall(text, nextId, catalog);
+    if (call) return { text: null, toolCalls: [call] };
+  }
+
+  const trimmed = prose.trim();
+  return { text: trimmed.length ? trimmed : null, toolCalls };
+}
+
+function toToolCall(raw: string | undefined, nextId: () => string, catalog: Set<string>): ToolCall | null {
+  if (!raw) return null;
+  let obj: unknown;
+  try {
+    obj = JSON.parse(raw.trim());
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== 'object') return null;
+  const rec = obj as Record<string, unknown>;
+  if (typeof rec.tool !== 'string') return null;
+  // Only accept names the turn actually advertised. An empty catalog means the
+  // turn offered no tools, so nothing parses as a call.
+  if (!catalog.has(rec.tool)) return null;
+  const args = rec.args && typeof rec.args === 'object' ? (rec.args as Record<string, unknown>) : {};
+  return { id: nextId(), name: rec.tool, args };
+}
+
+function isAuthError(err: unknown): boolean {
+  const status = (err as { status?: number; statusCode?: number })?.status
+    ?? (err as { statusCode?: number })?.statusCode;
+  // A present status is authoritative: only 401/403 are auth failures, so a 429
+  // (or anything else) is NOT treated as auth and is re-thrown untouched — its
+  // status must survive for withRetry/isRateLimit even if the message mentions
+  // "oauth token". Only when there is no status do we fall back to a narrow
+  // message heuristic.
+  if (typeof status === 'number') return status === 401 || status === 403;
+  const m = ((err as Error)?.message ?? '').toLowerCase();
+  return /unauthenticat|unauthoriz|not logged in|please log in|invalid api key|oauth token|setup-token/.test(m);
+}
+
+function authHint(detail: string): string {
+  return (
+    'claude-code is not authenticated: log in to Claude Code, or run `claude setup-token` and ' +
+    `set CLAUDE_CODE_OAUTH_TOKEN. copperhead never reads your credential itself (original error: ${detail})`
+  );
+}