feat(ai): claude CLI subprocess driver (subscription auth, stream-json)

Implements runClaudeTurn() — spawns the claude CLI for a single companion
turn using subscription/OAuth auth (strips ANTHROPIC_API_KEY +
ANTHROPIC_AUTH_TOKEN from child env), streaming normalised events (delta,
tool, tool_result, result, error) via onEvent callback.

Includes hermetic test + fake-claude.js fixture that mimics real 2.1.159
stream-json output; zero network/CLI calls in the test suite.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/ai/claude_cli.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { runClaudeTurn } from '../../lib/ai/claude_cli.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FAKE_CLAUDE = path.resolve(__dirname, '../fixtures/fake-claude.js');
+
+// ---------------------------------------------------------------------------
+// Hermetic tests: fake-claude.js emits known stream-json lines; we assert the
+// driver normalises them correctly.  NO real claude, NO network.
+// ---------------------------------------------------------------------------
+
+describe('runClaudeTurn', () => {
+  it('normalises text deltas, tool events, and tool_result from fake-claude output', async () => {
+    const collected = [];
+    const onEvent = (ev) => collected.push(ev);
+
+    const result = await runClaudeTurn({
+      claudeExe: FAKE_CLAUDE,
+      sessionId: 'test-session-uuid-0001',
+      systemPrompt: 'You are a test assistant.',
+      userText: 'hi',
+      onEvent,
+      timeoutMs: 10_000,
+    });
+
+    // --- Collected event assertions ---
+
+    // delta events whose texts concat to 'Hello'
+    const deltas = collected.filter(e => e.type === 'delta');
+    expect(deltas.length).toBeGreaterThanOrEqual(1);
+    expect(deltas.map(e => e.text).join('')).toBe('Hello');
+
+    // tool event for propose_change
+    const toolEvents = collected.filter(e => e.type === 'tool');
+    expect(toolEvents.length).toBeGreaterThanOrEqual(1);
+    expect(toolEvents[0].tool).toBe('propose_change');
+
+    // tool_result event
+    const toolResults = collected.filter(e => e.type === 'tool_result');
+    expect(toolResults.length).toBe(1);
+    expect(toolResults[0].name).toBe('propose_change');
+    expect(toolResults[0].result).toBeDefined();
+
+    // result event
+    const resultEvents = collected.filter(e => e.type === 'result');
+    expect(resultEvents.length).toBe(1);
+    expect(resultEvents[0].usage).toBeDefined();
+    expect(typeof resultEvents[0].cost).toBe('number');
+
+    // no error events
+    const errorEvents = collected.filter(e => e.type === 'error');
+    expect(errorEvents).toHaveLength(0);
+
+    // --- Return value assertions ---
+    expect(result.text).toBe('Hello');
+    expect(result.usage).toBeDefined();
+    expect(result.usage.input_tokens).toBe(100);
+
+    // toolTrace must include propose_change
+    expect(result.toolTrace).toBeDefined();
+    const proposeEntry = result.toolTrace.find(t => t.tool === 'propose_change');
+    expect(proposeEntry).toBeDefined();
+  });
+
+  it('resolves cleanly on non-zero exit (emits error event, does not throw)', async () => {
+    // Use a fake script that exits 1 immediately
+    const collected = [];
+
+    const result = await runClaudeTurn({
+      claudeExe: 'node',
+      // Pass a tiny inline script that exits 1.  We override claudeExe='node'
+      // and prepend the inline arg via a wrapper... but the API doesn't support
+      // extra args.  Instead we'll use a shell -c workaround via /bin/sh.
+      // Simpler: just test via sessionId, and use a real bad path.
+      // Actually: claudeExe itself is the executable; let's just use a path
+      // that doesn't exist to trigger spawn error.
+      sessionId: 'bad-session',
+      systemPrompt: 'x',
+      userText: 'hi',
+      onEvent: (ev) => collected.push(ev),
+      timeoutMs: 5_000,
+    });
+
+    // Should resolve (not throw) and include an error event
+    const errorEvents = collected.filter(e => e.type === 'error');
+    expect(errorEvents.length).toBeGreaterThanOrEqual(1);
+    // result.text may be empty string on error
+    expect(typeof result.text).toBe('string');
+  });
+});

tests/fixtures/fake-claude.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Fake claude CLI for hermetic tests.
+ *
+ * Mimics the stream-json output format of claude CLI 2.1.159:
+ * top-level events are either bare objects (system, assistant, result) or
+ * wrapped in {type:"stream_event", event:{...}}.
+ *
+ * Writes to stdout and exits 0.
+ */
+
+const lines = [
+  // system init (ignored by driver)
+  { type: 'system', subtype: 'init', session_id: 'fake-session-001', tools: [], cwd: '/tmp' },
+
+  // content_block_start: text block
+  { type: 'stream_event', event: { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } } },
+
+  // text deltas — together they spell "Hello"
+  { type: 'stream_event', event: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'Hel' } } },
+  { type: 'stream_event', event: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'lo' } } },
+
+  // assistant snapshot (should be ignored by driver to avoid duplication)
+  { type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'Hello' }] } },
+
+  // content_block_stop for text
+  { type: 'stream_event', event: { type: 'content_block_stop', index: 0 } },
+
+  // content_block_start: tool_use
+  { type: 'stream_event', event: { type: 'content_block_start', index: 1, content_block: { type: 'tool_use', id: 'toolu_fake01', name: 'propose_change', input: {} } } },
+
+  // tool input delta
+  { type: 'stream_event', event: { type: 'content_block_delta', index: 1, delta: { type: 'input_json_delta', partial_json: '{"file":"/tmp/x.js","content":"console.log(1)"}' } } },
+
+  // assistant snapshot for tool_use (ignored)
+  { type: 'assistant', message: { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_fake01', name: 'propose_change', input: { file: '/tmp/x.js', content: 'console.log(1)' } }] } },
+
+  // content_block_stop for tool
+  { type: 'stream_event', event: { type: 'content_block_stop', index: 1 } },
+
+  // tool_result event
+  { type: 'tool_result', tool_use_id: 'toolu_fake01', content: [{ type: 'text', text: 'change staged' }] },
+
+  // final result
+  {
+    type: 'result',
+    subtype: 'success',
+    is_error: false,
+    result: 'Hello',
+    stop_reason: 'end_turn',
+    session_id: 'fake-session-001',
+    total_cost_usd: 0.001234,
+    usage: {
+      input_tokens: 100,
+      output_tokens: 10,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    },
+  },
+];
+
+for (const line of lines) {
+  process.stdout.write(JSON.stringify(line) + '\n');
+}
+
+process.exit(0);