claude-spotter 0.1.0

package/src/cli/install.mjs

@@ -0,0 +1,126 @@
+// `spotter install` — create ~/.spotter/, place template catalog, register hooks in .claude/settings.json.
+//
+// Per plan §15.4, this shows a diff and asks for confirmation before touching settings.json.
+
+import { mkdir, writeFile, readFile, access, copyFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(HERE, '..', '..');
+const TEMPLATE_CATALOG = join(PACKAGE_ROOT, 'templates', 'tools.yaml');
+const SPOTTER_BIN = join(PACKAGE_ROOT, 'bin', 'spotter.mjs');
+
+const SPOTTER_HOME = join(homedir(), '.spotter');
+const CATALOG_DEST = join(SPOTTER_HOME, 'tool-catalog', 'tools.yaml');
+
+const HOOK_EVENTS = [
+  { event: 'SessionStart', sub: 'session-start', timeout: 5 },
+  { event: 'UserPromptSubmit', sub: 'user-prompt', timeout: 30 },
+  { event: 'PreToolUse', sub: 'pre-tool-use', timeout: 2 },
+  { event: 'Stop', sub: 'stop', timeout: 15 },
+  { event: 'SessionEnd', sub: 'session-end', timeout: 3 },
+];
+
+export async function runInstall({ target = 'project', autoYes = false, cwd = process.cwd() } = {}) {
+  const settingsPath = target === 'user'
+    ? join(homedir(), '.claude', 'settings.json')
+    : join(cwd, '.claude', 'settings.json');
+
+  console.log('spotter install');
+  console.log(`  package: ${PACKAGE_ROOT}`);
+  console.log(`  settings: ${settingsPath}`);
+
+  // 1. create directories
+  await mkdir(SPOTTER_HOME, { recursive: true });
+  await mkdir(join(SPOTTER_HOME, 'tool-catalog'), { recursive: true });
+  await mkdir(join(SPOTTER_HOME, 'runtime'), { recursive: true });
+  await mkdir(join(SPOTTER_HOME, 'workdir'), { recursive: true });
+  await mkdir(join(SPOTTER_HOME, 'logs'), { recursive: true });
+
+  // 2. place catalog template if missing
+  if (!(await exists(CATALOG_DEST))) {
+    await copyFile(TEMPLATE_CATALOG, CATALOG_DEST);
+    console.log(`  wrote ${CATALOG_DEST}`);
+  } else {
+    console.log(`  catalog already present at ${CATALOG_DEST} (not overwritten)`);
+  }
+
+  // 3. compute desired settings.json with hooks
+  const current = await loadSettings(settingsPath);
+  const updated = mergeHooks(current);
+  const diff = diffSettings(current, updated);
+
+  if (diff === null) {
+    console.log('  hooks already registered — nothing to change');
+    return;
+  }
+
+  console.log('\n--- proposed .claude/settings.json changes ---');
+  console.log(diff);
+  console.log('---------------------------------------------\n');
+
+  if (!autoYes) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question('apply these changes? [y/N] ');
+    rl.close();
+    if (!/^y(es)?$/i.test(answer.trim())) {
+      console.log('aborted.');
+      return;
+    }
+  }
+
+  await mkdir(dirname(settingsPath), { recursive: true });
+  await writeFile(settingsPath, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+  console.log(`wrote ${settingsPath}`);
+  console.log('\nnext: reload Claude Code (or open a new session) to activate Spotter.');
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadSettings(path) {
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+function mergeHooks(current) {
+  const next = structuredClone(current);
+  next.hooks = next.hooks ?? {};
+
+  for (const { event, sub, timeout } of HOOK_EVENTS) {
+    const command = `node "${SPOTTER_BIN}" hook ${sub}`;
+    const hookEntry = { type: 'command', command, timeout };
+    const groups = next.hooks[event] = next.hooks[event] ?? [];
+
+    // Dedup: skip if an identical spotter command is already present
+    const alreadyHas = groups.some((g) =>
+      Array.isArray(g.hooks) &&
+      g.hooks.some((h) => h?.type === 'command' && h?.command?.includes('spotter.mjs') && h?.command?.includes(`hook ${sub}`))
+    );
+    if (alreadyHas) continue;
+
+    groups.push({ hooks: [hookEntry] });
+  }
+  return next;
+}
+
+function diffSettings(current, updated) {
+  const a = JSON.stringify(current, null, 2);
+  const b = JSON.stringify(updated, null, 2);
+  if (a === b) return null;
+  return `BEFORE:\n${a}\n\nAFTER:\n${b}`;
+}

package/src/cli/status.mjs

@@ -0,0 +1,62 @@
+// `spotter status` — show running daemons (by PID file) and their socket state.
+
+import { readdir, readFile, access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { sendRequest, TransportError } from '../daemon/transport.mjs';
+
+const RUNTIME_DIR = join(homedir(), '.spotter', 'runtime');
+
+export async function runStatus() {
+  console.log('spotter status');
+
+  let entries;
+  try {
+    entries = await readdir(RUNTIME_DIR);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.log('  no runtime directory yet — run `spotter install` first');
+      return;
+    }
+    throw err;
+  }
+
+  const pidFiles = entries.filter((n) => n.endsWith('.pid'));
+  if (pidFiles.length === 0) {
+    console.log('  no daemons registered');
+    return;
+  }
+
+  for (const pidFile of pidFiles) {
+    const sessionId = pidFile.replace(/^session-/, '').replace(/\.pid$/, '');
+    const pid = await readPid(join(RUNTIME_DIR, pidFile));
+    const alive = isProcessAlive(pid);
+    let socketState = '?';
+    try {
+      const resp = await sendRequest({ sessionId, event: 'readiness', timeoutMs: 500 });
+      socketState = resp.ok === true ? 'ready' : 'error';
+    } catch (err) {
+      if (err instanceof TransportError) socketState = err.code;
+      else socketState = 'unknown';
+    }
+    console.log(`  session=${sessionId} pid=${pid} process=${alive ? 'alive' : 'dead'} socket=${socketState}`);
+  }
+}
+
+async function readPid(path) {
+  try {
+    return parseInt((await readFile(path, 'utf8')).trim(), 10);
+  } catch {
+    return NaN;
+  }
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isFinite(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}

package/src/cli/uninstall.mjs

@@ -0,0 +1,75 @@
+// `spotter uninstall` — remove hook entries that reference this spotter installation.
+// Does NOT delete ~/.spotter/ (user data), just unregisters hooks.
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+export async function runUninstall({ target = 'project', autoYes = false, cwd = process.cwd() } = {}) {
+  const settingsPath = target === 'user'
+    ? join(homedir(), '.claude', 'settings.json')
+    : join(cwd, '.claude', 'settings.json');
+
+  console.log(`spotter uninstall (settings: ${settingsPath})`);
+
+  let current;
+  try {
+    current = JSON.parse(await readFile(settingsPath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.log('  no settings.json present — nothing to uninstall');
+      return;
+    }
+    throw err;
+  }
+
+  if (!current.hooks) {
+    console.log('  no hooks block present — nothing to uninstall');
+    return;
+  }
+
+  const updated = structuredClone(current);
+  let removed = 0;
+  for (const [event, groups] of Object.entries(updated.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = [];
+    for (const g of groups) {
+      if (!Array.isArray(g?.hooks)) { kept.push(g); continue; }
+      const filtered = g.hooks.filter((h) => !(h?.type === 'command' && h?.command?.includes('spotter.mjs')));
+      if (filtered.length > 0) {
+        kept.push({ ...g, hooks: filtered });
+      } else {
+        removed += g.hooks.length;
+      }
+    }
+    if (kept.length > 0) {
+      updated.hooks[event] = kept;
+    } else {
+      delete updated.hooks[event];
+    }
+  }
+  if (Object.keys(updated.hooks).length === 0) {
+    delete updated.hooks;
+  }
+
+  if (JSON.stringify(current) === JSON.stringify(updated)) {
+    console.log('  no spotter hooks found — nothing to remove');
+    return;
+  }
+
+  console.log(`  will remove ${removed} spotter hook entries`);
+  if (!autoYes) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question('apply? [y/N] ');
+    rl.close();
+    if (!/^y(es)?$/i.test(answer.trim())) {
+      console.log('aborted.');
+      return;
+    }
+  }
+
+  await writeFile(settingsPath, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+  console.log(`wrote ${settingsPath}`);
+  console.log('note: ~/.spotter/ (catalog, logs) was not removed. delete manually if no longer needed.');
+}

package/src/daemon/daemon.mjs

@@ -0,0 +1,198 @@
+// Session-scoped daemon — receives hook events, dispatches to handlers,
+// calls Haiku on user_input / turn_end, keeps used_tools in process memory.
+//
+// §5.4: Claude calls are stateless per turn; process memory holds only lightweight state.
+// §5.7: event dispatch is defined per the envelope contract.
+// §14: unexpected errors are thrown; hooks convert them to exit codes.
+
+import { createServer, ensureRuntimeDir, socketPath } from './transport.mjs';
+import {
+  buildFirstStagePrompt,
+  buildFinalStagePrompt,
+  parseHaikuResponse,
+  createHaikuCaller,
+} from './haiku-caller.mjs';
+import { loadCatalog } from '../catalog/loader.mjs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { writeFile, unlink } from 'node:fs/promises';
+
+const DEFAULT_CATALOG_PATH = join(homedir(), '.spotter', 'tool-catalog', 'tools.yaml');
+
+export async function startDaemon({
+  sessionId,
+  catalogPath = DEFAULT_CATALOG_PATH,
+  haikuCaller,
+  logFn = () => {},
+} = {}) {
+  if (!sessionId) {
+    throw new TypeError('sessionId is required');
+  }
+
+  await ensureRuntimeDir();
+
+  // Load catalog up front — daemon cannot run without it (§14.1).
+  const catalog = await loadCatalog(catalogPath);
+  logFn(`catalog loaded: ${catalog.tools.length} tools from ${catalogPath}`);
+
+  // Default Haiku caller: timeout below the hook timeout for user_input/turn_end (§5.7).
+  const callHaiku = haikuCaller ?? createHaikuCaller({ timeoutMs: 28_000 });
+
+  // Per-turn state, reset on turn_end.
+  const state = {
+    usedTools: [],
+    lastUserInput: null,
+  };
+
+  const handler = async (envelope) => {
+    if (!envelope || typeof envelope !== 'object') {
+      const err = new Error('invalid envelope');
+      err.code = 'E_INTERNAL';
+      throw err;
+    }
+    if (envelope.session_id !== sessionId) {
+      const err = new Error(`session_id mismatch: daemon=${sessionId}, event=${envelope.session_id}`);
+      err.code = 'E_INTERNAL';
+      throw err;
+    }
+    switch (envelope.event) {
+      case 'readiness':
+        return { ready: true };
+      case 'user_input':
+        return handleUserInput(envelope.payload ?? {});
+      case 'tool_used':
+        return handleToolUsed(envelope.payload ?? {});
+      case 'turn_end':
+        return handleTurnEnd(envelope.payload ?? {});
+      case 'shutdown':
+        setImmediate(() => shutdown(server, sessionId, logFn));
+        return { stopping: true };
+      default: {
+        const err = new Error(`unknown event: ${envelope.event}`);
+        err.code = 'E_INTERNAL';
+        throw err;
+      }
+    }
+  };
+
+  async function handleUserInput(payload) {
+    const userInput = payload.user_input;
+    if (typeof userInput !== 'string') {
+      const err = new Error('user_input payload must include user_input string');
+      err.code = 'E_INTERNAL';
+      throw err;
+    }
+    state.lastUserInput = userInput;
+    state.usedTools = []; // reset tools for this turn
+
+    const prompt = buildFirstStagePrompt({ catalog, userInput });
+    const raw = await callHaiku(prompt);
+    const parsed = parseHaikuResponse(raw);
+    logFn(`user_input: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}`);
+    return parsed;
+  }
+
+  function handleToolUsed(payload) {
+    const name = payload.tool_name;
+    if (typeof name !== 'string' || name.length === 0) {
+      const err = new Error('tool_used payload must include non-empty tool_name');
+      err.code = 'E_INTERNAL';
+      throw err;
+    }
+    state.usedTools.push(name);
+    logFn(`tool_used: ${name} (cumulative=${state.usedTools.length})`);
+    return { recorded: true };
+  }
+
+  async function handleTurnEnd(payload) {
+    const finalResponse = payload.final_response;
+    if (typeof finalResponse !== 'string') {
+      const err = new Error('turn_end payload must include final_response string');
+      err.code = 'E_INTERNAL';
+      throw err;
+    }
+    if (payload.stop_hook_active === true) {
+      // Spotter already intervened this turn — §7.5/§8.1 max-1-loop guarantee.
+      logFn('turn_end: stop_hook_active=true, passing');
+      state.usedTools = [];
+      state.lastUserInput = null;
+      return { pass: true, missing_tools: [], reason: 'stop_hook_active' };
+    }
+    if (state.lastUserInput === null) {
+      // No user_input seen this turn — nothing to audit against. Pass quietly.
+      logFn('turn_end: no user_input observed, passing');
+      return { pass: true, missing_tools: [], reason: 'no_user_input' };
+    }
+
+    const prompt = buildFinalStagePrompt({
+      catalog,
+      userInput: state.lastUserInput,
+      usedTools: state.usedTools,
+      finalResponse,
+    });
+    const raw = await callHaiku(prompt);
+    const parsed = parseHaikuResponse(raw);
+    logFn(`turn_end: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}`);
+
+    state.usedTools = [];
+    state.lastUserInput = null;
+    return parsed;
+  }
+
+  const onErrorFn = (err, envelope) => {
+    const evt = envelope?.event ?? '(pre-parse)';
+    logFn(`handler error on ${evt}: ${err.code ?? 'E_INTERNAL'}: ${err.message}`);
+  };
+
+  const { server, path } = createServer({ sessionId, handler, onError: onErrorFn });
+
+  await new Promise((resolve, reject) => {
+    server.on('error', (err) => reject(err));
+    server.listen(path, () => {
+      logFn(`daemon listening on ${path}`);
+      resolve();
+    });
+  });
+
+  // Write PID file so uninstall/doctor can reason about liveness (§15.3 doctor).
+  const pidPath = pidFilePath(sessionId);
+  await writeFile(pidPath, String(process.pid), 'utf8');
+
+  return {
+    server,
+    path,
+    pidPath,
+    stop: () => shutdown(server, sessionId, logFn),
+  };
+}
+
+async function shutdown(server, sessionId, logFn) {
+  try {
+    await new Promise((resolve) => server.close(resolve));
+  } catch (err) {
+    // SessionEnd cleanup failures are §14.1 exceptions — warn only.
+    logFn(`shutdown: server.close failed: ${err.message}`);
+  }
+  // On Unix, remove the socket file. On Windows, Named Pipes are auto-cleaned.
+  if (process.platform !== 'win32') {
+    try {
+      await unlink(socketPath(sessionId));
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        logFn(`shutdown: unlink socket failed: ${err.message}`);
+      }
+    }
+  }
+  try {
+    await unlink(pidFilePath(sessionId));
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      logFn(`shutdown: unlink pid failed: ${err.message}`);
+    }
+  }
+  logFn('daemon stopped');
+}
+
+export function pidFilePath(sessionId) {
+  return join(homedir(), '.spotter', 'runtime', `session-${sessionId}.pid`);
+}

package/src/daemon/haiku-caller.mjs

@@ -0,0 +1,217 @@
+// claude -p --model claude-haiku-4-5-* wrapper.
+// §5.5: structured JSON I/O, no retries, schema violations throw.
+
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+const HAIKU_MODEL = 'claude-haiku-4-5-20251001';
+const WORKDIR = join(homedir(), '.spotter', 'workdir');
+
+export class HaikuError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'HaikuError';
+    this.code = code;
+  }
+}
+
+export async function ensureWorkdir() {
+  // §5.2: the workdir is isolated. No CLAUDE.md here.
+  await mkdir(WORKDIR, { recursive: true });
+  return WORKDIR;
+}
+
+// Build the first-stage prompt — projection of catalog purpose/when_to_use only.
+export function buildFirstStagePrompt({ catalog, userInput }) {
+  const toolsProjection = catalog.tools.map((t) => ({
+    name: t.name,
+    purpose: t.purpose,
+    when_to_use: t.when_to_use,
+  }));
+  return [
+    systemRules(),
+    '## ツールカタログ',
+    JSON.stringify(toolsProjection, null, 2),
+    '',
+    '## ユーザー入力',
+    userInput,
+    '',
+    '## 判定',
+    'ユーザーの入力内容から、上記カタログのうち「呼ぶべきだったのに Bell が呼び忘れるリスクのあるツール」を全て列挙してください。',
+    '該当するツールが 1 件もない場合は `pass: true` にしてください。',
+    '必ず指定スキーマの JSON オブジェクトのみを返してください。他のテキストは一切含めないでください。',
+  ].join('\n');
+}
+
+// Build the final-stage prompt — Stop hook, after Bell's response.
+export function buildFinalStagePrompt({ catalog, userInput, usedTools, finalResponse }) {
+  const toolsProjection = catalog.tools.map((t) => ({
+    name: t.name,
+    purpose: t.purpose,
+    when_to_use: t.when_to_use,
+  }));
+  return [
+    systemRules(),
+    '## ツールカタログ',
+    JSON.stringify(toolsProjection, null, 2),
+    '',
+    '## ユーザー入力',
+    userInput,
+    '',
+    '## Bell が既に使用したツール',
+    usedTools.length > 0 ? usedTools.map((t) => `- ${t}`).join('\n') : '(なし)',
+    '',
+    '## Bell の最終応答',
+    finalResponse,
+    '',
+    '## 判定',
+    'ユーザーの入力と Bell の最終応答を見て、呼ぶべきだったのに呼ばれていないツールを列挙してください。',
+    '「既に使用したツール」に含まれるものは除外してください (同じツールを二重に指摘しないため)。',
+    '該当するツールが 1 件もない場合は `pass: true` にしてください。',
+    '必ず指定スキーマの JSON オブジェクトのみを返してください。他のテキストは一切含めないでください。',
+  ].join('\n');
+}
+
+function systemRules() {
+  return [
+    'あなたは Spotter — Claude (Bell) が呼び忘れているツールを検出する監査役です。',
+    '',
+    '## 出力スキーマ (厳守)',
+    '```json',
+    '{',
+    '  "pass": <boolean>,',
+    '  "missing_tools": [',
+    '    { "name": "<tool_name>", "reason": "<一文の日本語>" }',
+    '  ]',
+    '}',
+    '```',
+    '',
+    '- `pass: true` なら `missing_tools: []`',
+    '- `pass: false` なら `missing_tools` は 1 件以上、`name` はカタログに存在するツール名',
+    '- JSON オブジェクトのみ出力。説明文・前置き・```json``` フェンス禁止',
+  ].join('\n');
+}
+
+// Parse Haiku's response. Throws HaikuError on schema violation.
+export function parseHaikuResponse(raw) {
+  const trimmed = raw.trim();
+  // Be tolerant of a surrounding code fence, which Haiku sometimes adds despite the prompt.
+  const unfenced = stripFence(trimmed);
+  let parsed;
+  try {
+    parsed = JSON.parse(unfenced);
+  } catch (err) {
+    throw new HaikuError('E_HAIKU_SCHEMA', `haiku output is not valid JSON: ${err.message} :: raw=${truncate(raw)}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new HaikuError('E_HAIKU_SCHEMA', `haiku output root is not an object :: ${truncate(raw)}`);
+  }
+  if (typeof parsed.pass !== 'boolean') {
+    throw new HaikuError('E_HAIKU_SCHEMA', `haiku "pass" must be boolean :: ${truncate(raw)}`);
+  }
+  if (!Array.isArray(parsed.missing_tools)) {
+    throw new HaikuError('E_HAIKU_SCHEMA', `haiku "missing_tools" must be array :: ${truncate(raw)}`);
+  }
+  parsed.missing_tools.forEach((m, i) => {
+    if (m === null || typeof m !== 'object' || Array.isArray(m)) {
+      throw new HaikuError('E_HAIKU_SCHEMA', `missing_tools[${i}] not an object`);
+    }
+    if (typeof m.name !== 'string' || m.name.length === 0) {
+      throw new HaikuError('E_HAIKU_SCHEMA', `missing_tools[${i}].name must be non-empty string`);
+    }
+    if (typeof m.reason !== 'string' || m.reason.length === 0) {
+      throw new HaikuError('E_HAIKU_SCHEMA', `missing_tools[${i}].reason must be non-empty string`);
+    }
+  });
+  // Cross-field: pass: true implies missing_tools empty.
+  if (parsed.pass === true && parsed.missing_tools.length > 0) {
+    throw new HaikuError(
+      'E_HAIKU_SCHEMA',
+      `pass: true with non-empty missing_tools is inconsistent :: ${truncate(raw)}`
+    );
+  }
+  if (parsed.pass === false && parsed.missing_tools.length === 0) {
+    throw new HaikuError(
+      'E_HAIKU_SCHEMA',
+      `pass: false with empty missing_tools is inconsistent :: ${truncate(raw)}`
+    );
+  }
+  return parsed;
+}
+
+function stripFence(text) {
+  const fenceMatch = text.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
+  return fenceMatch ? fenceMatch[1] : text;
+}
+
+function truncate(s, n = 300) {
+  if (s.length <= n) return s;
+  return s.slice(0, n) + '...';
+}
+
+// On Windows, the `claude` entry is typically a .cmd shim which Node's spawn
+// cannot locate without going through the shell. We use cmd.exe /c explicitly
+// rather than spawn({ shell: true }) because the latter triggers DEP0190 on Node 24+.
+function buildSpawnArgs(claudeBin, model) {
+  const args = ['-p', '--model', model];
+  if (process.platform === 'win32') {
+    return { cmd: 'cmd.exe', cmdArgs: ['/c', claudeBin, ...args] };
+  }
+  return { cmd: claudeBin, cmdArgs: args };
+}
+
+// Invoke `claude -p` in the isolated workdir. Returns raw stdout.
+// §5.5: no retry on failure. §14.1: silent fallback forbidden.
+export function createHaikuCaller({ timeoutMs, claudeBin = 'claude', model = HAIKU_MODEL, env = process.env }) {
+  if (typeof timeoutMs !== 'number' || timeoutMs <= 0) {
+    throw new TypeError('timeoutMs must be a positive number');
+  }
+
+  return async function callHaiku(prompt) {
+    await ensureWorkdir();
+    return new Promise((resolve, reject) => {
+      const { cmd, cmdArgs } = buildSpawnArgs(claudeBin, model);
+      const child = spawn(cmd, cmdArgs, {
+        cwd: WORKDIR,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      let stdout = '';
+      let stderr = '';
+      let settled = false;
+
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        child.kill();
+        reject(new HaikuError('E_HAIKU_TIMEOUT', `haiku did not respond within ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      child.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+      child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+
+      child.on('error', (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(new HaikuError('E_INTERNAL', `failed to spawn ${claudeBin}: ${err.message}`));
+      });
+
+      child.on('close', (code) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (code !== 0) {
+          reject(new HaikuError('E_INTERNAL', `haiku exited with code ${code}: ${truncate(stderr)}`));
+          return;
+        }
+        resolve(stdout);
+      });
+
+      child.stdin.end(prompt, 'utf8');
+    });
+  };
+}