claude-spotter 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,57 @@
 # Changelog
 
-## 0.1.0 (Unreleased)
+## 0.2.0
+
+Fixes the v0.1.x daemon proliferation by adding multiple defence layers that together prevent any
+non-parent-session hook from re-entering the daemon spawn path.
+
+- **Env-var gate (`SPOTTER_PARENT_PID`)**: the daemon injects its own PID when spawning `claude -p`
+  for Haiku. Every hook checks this on startup and exits immediately when present — the primary
+  fix for Spotter's own subprocess recursion.
+- **`agent_id` gate**: hooks fired inside a Task subagent carry `agent_id` per the Claude Code
+  hook contract. The hook entry-points exit on seeing this field, so subagent activity is never
+  audited (matches v0.2's scope: top-level parent sessions only).
+- **`source === 'startup'` gate on SessionStart**: `/compact`, `/clear`, `--resume`, `--continue`
+  all fire SessionStart with a fresh session_id; without this gate they used to spawn a new
+  daemon. Now they no-op.
+- **PID-preexist check**: `startDaemon` asserts no live daemon already serves the session_id,
+  throwing `DaemonAlreadyRunningError` so the caller exits cleanly.
+- **10-second call window**: the daemon ignores `user_input` / `turn_end` events that arrive
+  within 10 s of its own Haiku spawn. Final safety net; documented trade-off (a brief window of
+  legitimate parent events may also be skipped).
+- **Session-scoped Haiku conversation**: the daemon now generates one `haikuSessionId` UUID at
+  startup. The first Haiku call uses `claude -p --session-id <uuid>`; subsequent calls use
+  `--resume <uuid>`. The catalog is therefore sent to Haiku exactly once per parent session,
+  realising plan §5.4's original economic intent. Prompts now distinguish first vs incremental
+  form.
+- **Mutex on Haiku calls**: a Promise chain serialises `callHaiku` so concurrent events cannot
+  race on the `haikuInitialized` flag and double-send the catalog.
+
+### Breaking
+
+- `createHaikuCaller` now requires `haikuSessionId` (will throw without it).
+- The returned `callHaiku` accepts `(prompt, { isFirst })`; callers that used `callHaiku(prompt)`
+  should pass `{ isFirst: true }` (the lint flow does this).
+- `buildFirstStagePrompt` / `buildFinalStagePrompt` accept `isFirst` (defaults to true, so
+  existing callers that want full prompts continue working).
+
+### Experimental-flag note
+
+`claude -p --bare` was evaluated as a fifth layer but errors with "Not logged in" because it
+skips auth auto-discovery. `--bare` is therefore NOT used. The env-var gate plus the other four
+layers cover the same proliferation cases.
+
+## 0.1.1 — ⚠️ DEPRECATED 2026-04-19
+
+**Do not install this version.** Real-world testing against a live Claude Code session revealed that the "one daemon per session" model is based on a wrong assumption — `SessionStart` hooks fire per subagent (Task tool invocation), not only at top-level session startup. Within 41 seconds of install, 213 orphan daemons accumulated and Haiku API calls uniformly timed out. `npm uninstall -g` also did not execute `preuninstall`, leaving hook entries in `~/.claude/settings.json`. See [docs/spotter-plan.md §18](https://github.com/kitepon-rgb/Spotter/blob/main/docs/spotter-plan.md#18) for details and the v0.2 redesign plan.
+
+## 0.1.1 (pre-deprecation notes)
+
+- `npm install -g claude-spotter` now registers hooks at user level automatically via the `postinstall` lifecycle — no separate `spotter install` step needed
+- `npm uninstall -g claude-spotter` removes hook entries from `~/.claude/settings.json` via `preuninstall`
+- Opt-out: set `CLAUDE_SPOTTER_NO_AUTO_INSTALL=1` before install, or install in an environment where `CI=true` (CI is auto-skipped)
+
+## 0.1.0
 
 Initial release.
 

package/README.md

@@ -1,5 +1,7 @@
 # Spotter
 
+> **v0.2.0 released 2026-04-19**. v0.1.x had a daemon-proliferation defect caused by hook re-entry from Spotter's own `claude -p` invocations. v0.2 adds five independent gates (env-var PID, `agent_id`, `source=startup`, PID-preexist, 10 s call window) plus session-scoped Haiku via `--session-id` / `--resume` to prevent this. See [CHANGELOG](CHANGELOG.md) and [docs/spotter-plan.md §18](docs/spotter-plan.md) for the full post-mortem.
+
 **気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
 
 > Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。現在時刻を推測で答える、web_search を呼ばずに古い情報で応答する、read_file を使わずにファイルの中身を推測する — 「分からないと自覚できない」から、ツールを取りに行けない。
@@ -10,10 +12,11 @@ Spotter は、ツールカタログを完全に把握した別エージェント
 
 ```bash
 npm install -g claude-spotter
-spotter install     # .claude/settings.json に hook を登録 (diff を見せて確認)
 ```
 
-次回 Claude Code セッションから自動で有効になります。
+これだけで `~/.claude/settings.json` に hook が自動登録され、次回 Claude Code セッションから全プロジェクトで有効になります (`postinstall` ライフサイクルが `spotter install --user` を自動実行します)。
+
+自動登録を止めたい場合は `CLAUDE_SPOTTER_NO_AUTO_INSTALL=1 npm install -g claude-spotter` と打てばスキップされ、あとから `spotter install` / `spotter install --user` を好きなタイミングで手動実行できます。CI 環境 (`CI=true`) では自動的にスキップされます。
 
 ## 動作要件
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {
@@ -10,7 +10,9 @@
     ".": "./src/index.mjs"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "postinstall": "node scripts/postinstall.mjs",
+    "preuninstall": "node scripts/preuninstall.mjs"
   },
   "keywords": [
     "claude",
@@ -40,6 +42,7 @@
   "files": [
     "bin",
     "src",
+    "scripts",
     "templates",
     "README.md",
     "LICENSE",

package/scripts/postinstall.mjs

@@ -0,0 +1,42 @@
+// Runs after `npm install (-g) claude-spotter`.
+// Registers hooks at user level so Spotter is active across all projects
+// without requiring a separate `spotter install` step.
+//
+// Never fails npm install — on any error we warn and exit 0 so the user's
+// node_modules/global bin is still usable. They can re-run `spotter install --user`
+// manually if needed.
+
+import { runInstall } from '../src/cli/install.mjs';
+
+const SKIP_ENV = 'CLAUDE_SPOTTER_NO_AUTO_INSTALL';
+
+async function main() {
+  if (process.env[SKIP_ENV]) {
+    console.log(`claude-spotter: auto-install skipped (${SKIP_ENV} set).`);
+    console.log('  run `spotter install --user` later to register hooks.');
+    return;
+  }
+
+  // Skip in well-known CI environments — CI builds shouldn't silently modify
+  // ~/.claude/settings.json of whatever runner user this is.
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    console.log('claude-spotter: auto-install skipped (CI detected).');
+    console.log('  run `spotter install --user` on your dev machine.');
+    return;
+  }
+
+  try {
+    await runInstall({ target: 'user', autoYes: true });
+    console.log('\nclaude-spotter: hooks registered at user level (~/.claude/settings.json).');
+    console.log('  Open a new Claude Code session to activate.');
+    console.log(`  To skip this next time: set ${SKIP_ENV}=1 before npm install.`);
+  } catch (err) {
+    console.warn(`claude-spotter: auto-install skipped — ${err.message}`);
+    console.warn('  run `spotter install --user` to register hooks manually.');
+  }
+}
+
+main().catch((err) => {
+  // Defensive: never let postinstall crash the install.
+  console.warn(`claude-spotter: postinstall unexpected error — ${err.message}`);
+});

package/scripts/preuninstall.mjs

@@ -0,0 +1,14 @@
+// Runs before `npm uninstall (-g) claude-spotter`.
+// Removes hooks from ~/.claude/settings.json so an uninstall leaves the system clean.
+//
+// Never fails the uninstall — on error we warn and exit 0.
+
+import { runUninstall } from '../src/cli/uninstall.mjs';
+
+try {
+  await runUninstall({ target: 'user', autoYes: true });
+  console.log('claude-spotter: hooks removed from ~/.claude/settings.json.');
+} catch (err) {
+  console.warn(`claude-spotter: hook cleanup skipped — ${err.message}`);
+  console.warn('  you may need to edit ~/.claude/settings.json manually.');
+}

package/src/catalog/lint.mjs

@@ -24,11 +24,13 @@ export async function runLint({ catalogPath, haikuCaller, writeLine }) {
   for (const tool of catalog.tools) {
     if (!Array.isArray(tool.test_cases)) continue;
     for (const tc of tool.test_cases) {
+      // Each test case is an independent judgement, so isFirst=true always.
       const prompt = buildFirstStagePrompt({
         catalog,
         userInput: tc.user_input,
+        isFirst: true,
       });
-      const rawResponse = await haikuCaller(prompt);
+      const rawResponse = await haikuCaller(prompt, { isFirst: true });
       const parsed = parseHaikuResponse(rawResponse);
       const detectedNames = parsed.missing_tools.map((m) => m.name);
       const hit = detectedNames.includes(tc.expected_tool);

package/src/cli/catalog.mjs

@@ -6,6 +6,7 @@
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { runLint } from '../catalog/lint.mjs';
 import { createHaikuCaller } from '../daemon/haiku-caller.mjs';
 
@@ -25,7 +26,16 @@ function defaultEditor() {
 }
 
 export async function runCatalogLint({ catalogPath = CATALOG_PATH } = {}) {
-  const haikuCaller = createHaikuCaller({ timeoutMs: 30_000 });
+  // Each test case must be independent, so generate a fresh Haiku session per call.
+  // (Reusing one session-id across cases would have Haiku's context carry judgements
+  // from earlier cases, contaminating later ones.)
+  const haikuCaller = async (prompt, opts = {}) => {
+    const caller = createHaikuCaller({
+      timeoutMs: 30_000,
+      haikuSessionId: randomUUID(),
+    });
+    return await caller(prompt, { ...opts, isFirst: true });
+  };
   const result = await runLint({
     catalogPath,
     haikuCaller,

package/src/cli/daemon-cmd.mjs

@@ -1,6 +1,6 @@
 // `spotter daemon start|stop` — internal commands invoked by SessionStart/SessionEnd hooks.
 
-import { startDaemon } from '../daemon/daemon.mjs';
+import { startDaemon, DaemonAlreadyRunningError } from '../daemon/daemon.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { open } from 'node:fs/promises';
@@ -32,7 +32,19 @@ export async function runDaemonStart({ argv }) {
     logFile.write(line).catch(() => {});
   };
 
-  const running = await startDaemon({ sessionId, logFn: log });
+  let running;
+  try {
+    running = await startDaemon({ sessionId, logFn: log });
+  } catch (err) {
+    if (err instanceof DaemonAlreadyRunningError) {
+      // v0.2 PID-preexist layer: a sibling daemon already serves this session.
+      // Exit cleanly so the hook's readiness poll finds the existing one.
+      log(`startup skipped: ${err.message}`);
+      await logFile.close();
+      process.exit(0);
+    }
+    throw err;
+  }
   log(`started on ${running.path}`);
 
   // Keep process alive; SessionEnd → shutdown event triggers server.close() which resolves the await.

package/src/daemon/daemon.mjs

@@ -1,10 +1,22 @@
 // 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.
+// §5.4: the Haiku conversation is session-scoped (one per parent session), realised via
+//       --session-id (first call) and --resume (subsequent). The catalog is therefore
+//       transmitted once in the first Haiku call; later calls only send incremental info.
+// §5.7: event dispatch follows the envelope contract.
+// §14:  unexpected errors are thrown; hooks convert them to exit codes.
+//
+// v0.2 defence layers against daemon proliferation (see plan §18 / C2 verification log):
+//   - SPOTTER_PARENT_PID env var (set by haiku-caller when spawning claude -p; hooks skip on presence)
+//   - agent_id gate (subagent hooks exit 0 before reaching the daemon)
+//   - source='startup' gate (session-start hook only spawns daemon for startup sources)
+//   - PID preexist check (if a live daemon already serves this session_id, new attempt exits)
+//   - 10-second call window (inside the daemon, ignore Haiku-invoking events that arrived within
+//     10s of our own claude -p spawn — final safety net against any recursion that slipped past
+//     the env-var gate)
 
+import { readFile } from 'node:fs/promises';
 import { createServer, ensureRuntimeDir, socketPath } from './transport.mjs';
 import {
   buildFirstStagePrompt,
@@ -16,13 +28,25 @@ import { loadCatalog } from '../catalog/loader.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { writeFile, unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
 
 const DEFAULT_CATALOG_PATH = join(homedir(), '.spotter', 'tool-catalog', 'tools.yaml');
+const HAIKU_CALL_WINDOW_MS = 10_000;
+
+export class DaemonAlreadyRunningError extends Error {
+  constructor(sessionId, pid) {
+    super(`daemon for session ${sessionId} already running (pid=${pid})`);
+    this.name = 'DaemonAlreadyRunningError';
+    this.sessionId = sessionId;
+    this.pid = pid;
+  }
+}
 
 export async function startDaemon({
   sessionId,
   catalogPath = DEFAULT_CATALOG_PATH,
   haikuCaller,
+  haikuSessionId,
   logFn = () => {},
 } = {}) {
   if (!sessionId) {
@@ -31,12 +55,22 @@ export async function startDaemon({
 
   await ensureRuntimeDir();
 
+  // Layer: preexisting-daemon detection. If a PID file exists AND that process is alive,
+  // a sibling daemon is already serving this session_id — throw so the caller can exit.
+  await assertNoLiveDaemon(sessionId);
+
   // 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-daemon Haiku conversation id. Same UUID is used for --session-id (first)
+  // and --resume (subsequent), so Haiku retains the catalog/rules across calls.
+  const ownHaikuSessionId = haikuSessionId ?? randomUUID();
+
+  const callHaiku = haikuCaller ?? createHaikuCaller({
+    timeoutMs: 28_000,
+    haikuSessionId: ownHaikuSessionId,
+  });
 
   // Per-turn state, reset on turn_end.
   const state = {
@@ -44,6 +78,30 @@ export async function startDaemon({
     lastUserInput: null,
   };
 
+  // Haiku call serialisation + bookkeeping.
+  // Serialisation prevents two concurrent incoming events from both computing isFirst=true
+  // and double-sending the catalog (audit H2).
+  let haikuInitialized = false;
+  let lastHaikuCallAt = 0;
+  let haikuChain = Promise.resolve();
+
+  const callHaikuTracked = (buildPrompt) => {
+    const run = async () => {
+      lastHaikuCallAt = Date.now();
+      const isFirst = !haikuInitialized;
+      const prompt = buildPrompt({ isFirst });
+      const raw = await callHaiku(prompt, { isFirst });
+      // Only flip to initialised after a successful call so a failed first call is retried
+      // (still as first) rather than leaving Haiku with no catalog/rules in its context.
+      haikuInitialized = true;
+      return raw;
+    };
+    // Chain onto the previous call; whether it resolved or rejected, we run next.
+    const next = haikuChain.then(run, run);
+    haikuChain = next.catch(() => {}); // swallow so chain survives rejections
+    return next;
+  };
+
   const handler = async (envelope) => {
     if (!envelope || typeof envelope !== 'object') {
       const err = new Error('invalid envelope');
@@ -55,6 +113,16 @@ export async function startDaemon({
       err.code = 'E_INTERNAL';
       throw err;
     }
+
+    // 10-second window safety net: events that would invoke Haiku within 10s of our own
+    // claude -p spawn are likely recursive noise; pass them quietly.
+    const needsHaiku = envelope.event === 'user_input' || envelope.event === 'turn_end';
+    const sinceLast = Date.now() - lastHaikuCallAt;
+    if (needsHaiku && lastHaikuCallAt > 0 && sinceLast < HAIKU_CALL_WINDOW_MS) {
+      logFn(`${envelope.event} skipped: within ${sinceLast}ms of own haiku call`);
+      return { pass: true, missing_tools: [], reason: 'within_haiku_call_window' };
+    }
+
     switch (envelope.event) {
       case 'readiness':
         return { ready: true };
@@ -85,8 +153,9 @@ export async function startDaemon({
     state.lastUserInput = userInput;
     state.usedTools = []; // reset tools for this turn
 
-    const prompt = buildFirstStagePrompt({ catalog, userInput });
-    const raw = await callHaiku(prompt);
+    const raw = await callHaikuTracked(({ isFirst }) =>
+      buildFirstStagePrompt({ catalog, userInput, isFirst })
+    );
     const parsed = parseHaikuResponse(raw);
     logFn(`user_input: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}`);
     return parsed;
@@ -112,25 +181,27 @@ export async function startDaemon({
       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 savedUserInput = state.lastUserInput;
+    const savedUsedTools = state.usedTools.slice();
+    const raw = await callHaikuTracked(({ isFirst }) =>
+      buildFinalStagePrompt({
+        catalog,
+        userInput: savedUserInput,
+        usedTools: savedUsedTools,
+        finalResponse,
+        isFirst,
+      })
+    );
     const parsed = parseHaikuResponse(raw);
     logFn(`turn_end: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}`);
 
@@ -149,7 +220,7 @@ export async function startDaemon({
   await new Promise((resolve, reject) => {
     server.on('error', (err) => reject(err));
     server.listen(path, () => {
-      logFn(`daemon listening on ${path}`);
+      logFn(`daemon listening on ${path} (haikuSessionId=${ownHaikuSessionId})`);
       resolve();
     });
   });
@@ -162,18 +233,41 @@ export async function startDaemon({
     server,
     path,
     pidPath,
+    haikuSessionId: ownHaikuSessionId,
     stop: () => shutdown(server, sessionId, logFn),
   };
 }
 
+async function assertNoLiveDaemon(sessionId) {
+  const pidPath = pidFilePath(sessionId);
+  let raw;
+  try {
+    raw = await readFile(pidPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  const pid = parseInt(raw.trim(), 10);
+  if (!Number.isFinite(pid)) return; // stale/malformed — treat as absent
+  try {
+    process.kill(pid, 0);
+  } catch (err) {
+    if (err.code === 'ESRCH') return; // process gone; stale PID file is fine
+    if (err.code === 'EPERM') {
+      // running under another user — still counts as live
+      throw new DaemonAlreadyRunningError(sessionId, pid);
+    }
+    return;
+  }
+  throw new DaemonAlreadyRunningError(sessionId, pid);
+}
+
 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));

package/src/daemon/haiku-caller.mjs

@@ -24,7 +24,17 @@ export async function ensureWorkdir() {
 }
 
 // Build the first-stage prompt — projection of catalog purpose/when_to_use only.
-export function buildFirstStagePrompt({ catalog, userInput }) {
+// When `isFirst` is true, includes system rules + full catalog (used with --session-id).
+// When false, sends only incremental input (used with --resume; Haiku already has catalog/rules).
+export function buildFirstStagePrompt({ catalog, userInput, isFirst = true }) {
+  if (!isFirst) {
+    return [
+      '## 新しいユーザー入力',
+      userInput,
+      '',
+      '既に共有済みの判定ルール・カタログに従い、同一 JSON スキーマで結果を返してください。',
+    ].join('\n');
+  }
   const toolsProjection = catalog.tools.map((t) => ({
     name: t.name,
     purpose: t.purpose,
@@ -46,7 +56,24 @@ export function buildFirstStagePrompt({ catalog, userInput }) {
 }
 
 // Build the final-stage prompt — Stop hook, after Bell's response.
-export function buildFinalStagePrompt({ catalog, userInput, usedTools, finalResponse }) {
+// Incremental form (isFirst=false) omits the catalog since Haiku's resumed session already has it.
+export function buildFinalStagePrompt({ catalog, userInput, usedTools, finalResponse, isFirst = true }) {
+  if (!isFirst) {
+    return [
+      '## ターン終了判定',
+      '',
+      '### 対象ユーザー入力',
+      userInput,
+      '',
+      '### Bell が既に使用したツール',
+      usedTools.length > 0 ? usedTools.map((t) => `- ${t}`).join('\n') : '(なし)',
+      '',
+      '### Bell の最終応答',
+      finalResponse,
+      '',
+      '既に共有済みのルールに従い、使用済みツールは除外した上で同一 JSON スキーマで結果を返してください。',
+    ].join('\n');
+  }
   const toolsProjection = catalog.tools.map((t) => ({
     name: t.name,
     purpose: t.purpose,
@@ -154,8 +181,14 @@ function truncate(s, n = 300) {
 // 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];
+//
+// v0.2: For the first call of a daemon's lifetime, spawn with `--session-id <haikuSessionId>`
+// to create a new Haiku conversation. For subsequent calls, spawn with `--resume <haikuSessionId>`
+// to continue that same conversation (so catalog/system rules persist in Haiku's context).
+// Note: `--bare` was tried but fails with "Not logged in" — it is intentionally NOT used.
+function buildSpawnArgs(claudeBin, model, haikuSessionId, isFirstCall) {
+  const sessionFlag = isFirstCall ? '--session-id' : '--resume';
+  const args = ['-p', sessionFlag, haikuSessionId, '--model', model];
   if (process.platform === 'win32') {
     return { cmd: 'cmd.exe', cmdArgs: ['/c', claudeBin, ...args] };
   }
@@ -164,18 +197,25 @@ function buildSpawnArgs(claudeBin, model) {
 
 // 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 }) {
+//
+// v0.2: `haikuSessionId` is required — used for --session-id (first call) / --resume (subsequent).
+// The SPOTTER_PARENT_PID env var is always injected so hooks firing inside the spawned claude
+// exit early via isChildCall() (prevents daemon-spawn recursion).
+export function createHaikuCaller({ timeoutMs, haikuSessionId, claudeBin = 'claude', model = HAIKU_MODEL, env = process.env }) {
   if (typeof timeoutMs !== 'number' || timeoutMs <= 0) {
     throw new TypeError('timeoutMs must be a positive number');
   }
+  if (typeof haikuSessionId !== 'string' || haikuSessionId.length === 0) {
+    throw new TypeError('haikuSessionId is required (non-empty string)');
+  }
 
-  return async function callHaiku(prompt) {
+  return async function callHaiku(prompt, { isFirst = true } = {}) {
     await ensureWorkdir();
     return new Promise((resolve, reject) => {
-      const { cmd, cmdArgs } = buildSpawnArgs(claudeBin, model);
+      const { cmd, cmdArgs } = buildSpawnArgs(claudeBin, model, haikuSessionId, isFirst);
       const child = spawn(cmd, cmdArgs, {
         cwd: WORKDIR,
-        env,
+        env: { ...env, SPOTTER_PARENT_PID: String(process.pid) },
         stdio: ['pipe', 'pipe', 'pipe'],
         windowsHide: true,
       });

package/src/hooks/lib.mjs

@@ -6,6 +6,24 @@
 //   2 = unexpected (propagate to Claude Code transcript)
 //
 // Silent fallback (exit 0 with missing behaviour) is forbidden. See §14.1.
+//
+// v0.2 gate helpers (plan §18 / C:\Users\kite_\.claude\plans\10-cuddly-codd.md):
+// - isChildCall(): env-var gate for Spotter's own claude -p invocations
+// - isSubagentCall(input): agent_id gate for Bell's Task subagent hooks
+// Combined with session-start's source='startup' check, these prevent daemon
+// proliferation (v0.1 postmortem §18.2).
+
+export function isChildCall() {
+  const v = process.env.SPOTTER_PARENT_PID;
+  return typeof v === 'string' && v.length > 0;
+}
+
+export function isSubagentCall(input) {
+  return input !== null
+      && typeof input === 'object'
+      && typeof input.agent_id === 'string'
+      && input.agent_id.length > 0;
+}
 
 export async function readStdinJson() {
   let raw = '';

package/src/hooks/pre-tool-use.mjs

@@ -1,12 +1,16 @@
 // PreToolUse hook — record tool usage in daemon (lightweight, no Haiku call). §9.1 v0.1.
+// v0.2 gates: see src/hooks/session-start.mjs comment.
 
-import { readStdinJson, requireString, exitCodeFor, die } from './lib.mjs';
+import { readStdinJson, requireString, exitCodeFor, die, isChildCall, isSubagentCall } from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
 const TIMEOUT_MS = 1_000;
 
 export async function runPreToolUse() {
+  if (isChildCall()) return;
   const input = await readStdinJson();
+  if (isSubagentCall(input)) return;
+
   const sessionId = requireString(input, 'session_id');
   const toolName = requireString(input, 'tool_name');
 

package/src/hooks/session-end.mjs

@@ -1,12 +1,16 @@
 // SessionEnd hook — best-effort shutdown notice. §14.1 exception: cleanup failures warn only.
+// v0.2 gates: see src/hooks/session-start.mjs comment.
 
-import { readStdinJson, requireString } from './lib.mjs';
+import { readStdinJson, requireString, isChildCall, isSubagentCall } from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
 const TIMEOUT_MS = 2_000;
 
 export async function runSessionEnd() {
+  if (isChildCall()) return;
   const input = await readStdinJson();
+  if (isSubagentCall(input)) return;
+
   const sessionId = requireString(input, 'session_id');
 
   try {

package/src/hooks/session-start.mjs

@@ -1,19 +1,35 @@
 // SessionStart hook — spawn daemon detached, wait up to 3s for readiness (§9.1).
 //
 // §14.3 classifies readiness failure as unexpected (exit 2). §14.1 forbids silent fallback.
+//
+// v0.2 gates (plan §18, C:\Users\kite_\.claude\plans\10-cuddly-codd.md):
+//   - isChildCall: Spotter's own claude -p subprocess → exit 0 (prevents recursion)
+//   - isSubagentCall: Bell's Task subagent → exit 0 (not audited in v0.2)
+//   - source !== 'startup': /compact, /clear, --resume, --continue → exit 0
+//     (these continue an existing parent session; v0.2 does not migrate daemon state)
 
 import { spawn } from 'node:child_process';
 import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
-import { readStdinJson, requireString, die } from './lib.mjs';
+import { readStdinJson, requireString, die, isChildCall, isSubagentCall } from './lib.mjs';
 import { sendRequest, TransportError } from '../daemon/transport.mjs';
 
 const READINESS_TIMEOUT_MS = 3_000;
 const POLL_INTERVAL_MS = 100;
 
 export async function runSessionStart({ argv = process.argv, now = Date.now } = {}) {
+  // Gate 1 (pre-stdin): Spotter's own claude -p subprocess — exit without reading stdin.
+  if (isChildCall()) return;
+
   const input = await readStdinJson();
+
+  // Gate 2: Task subagent — skip audit.
+  if (isSubagentCall(input)) return;
+
+  // Gate 3: non-startup sources (resume/compact/clear) don't spawn a new daemon.
+  if (input.source !== 'startup') return;
+
   const sessionId = requireString(input, 'session_id');
 
   spawnDaemon(sessionId, argv);

package/src/hooks/stop.mjs

@@ -1,5 +1,6 @@
 // Stop hook — send turn_end, return decision:"block" on miss (§12.3 transparent).
 // `stop_hook_active: true` → daemon returns pass automatically (§7.5 max-1-loop).
+// v0.2 gates: see src/hooks/session-start.mjs comment.
 
 import {
   readStdinJson,
@@ -8,13 +9,18 @@ import {
   exitCodeFor,
   die,
   formatTransparentBlockReason,
+  isChildCall,
+  isSubagentCall,
 } from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
 const TIMEOUT_MS = 15_000;
 
 export async function runStop() {
+  if (isChildCall()) return;
   const input = await readStdinJson();
+  if (isSubagentCall(input)) return;
+
   const sessionId = requireString(input, 'session_id');
   const stopHookActive = input.stop_hook_active === true;
   // Claude Code passes the transcript path; the final response is read from there or provided inline.

package/src/hooks/user-prompt.mjs

@@ -1,12 +1,24 @@
 // UserPromptSubmit hook — send user_input to daemon, inject additionalContext (§12.2 transparent).
-
-import { readStdinJson, requireString, exitCodeFor, die, formatTransparentContext } from './lib.mjs';
+// v0.2 gates: see src/hooks/session-start.mjs comment.
+
+import {
+  readStdinJson,
+  requireString,
+  exitCodeFor,
+  die,
+  formatTransparentContext,
+  isChildCall,
+  isSubagentCall,
+} from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
 const TIMEOUT_MS = 30_000;
 
 export async function runUserPrompt() {
+  if (isChildCall()) return;
   const input = await readStdinJson();
+  if (isSubagentCall(input)) return;
+
   const sessionId = requireString(input, 'session_id');
   const prompt = requireString(input, 'prompt');
 

package/src/version.mjs

@@ -1 +1 @@
-export const version = '0.1.0';
+export const version = '0.2.0';