claude-spotter 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.3.0
+
+v0.2.1 で追跡課題として残していた **daemon 増殖問題の根本原因を特定** (実セッション 64 分の生ログ調査)。74 個生成された daemon のうち 51 個が Throughline (token-monitor) の `claude -p` 由来で、残り 23 個も同種の他ツール起動と推定された。
+
+5 層防御は **Spotter 自身の `claude -p` 再帰** と **Bell の Task subagent** はカバーするが、**他ツールが起動する `claude -p` 経由の SessionStart** には無防備だった。原因は v0.1.1 で導入した `npm postinstall` の `~/.claude/settings.json` (user-global) への自動 hook 登録 — システム全体のあらゆる Claude Code セッションが Spotter hook を読み込む構造になっていた。
+
+### 変更点
+
+- **`postinstall` の自動登録を撤回**: `npm install -g claude-spotter` は CLI を使える状態にするだけ。`~/.claude/settings.json` への書き込みは行わない (案内文を出すのみ)。
+- **`spotter install` が project-scoped に**: `<cwd>/.claude/settings.json` に hook を書き、同時に `<cwd>/.spotter/marker.json` を作成する。`--user` フラグで旧来の user-global 登録も可能だが非推奨。
+- **`spotter uninstall` も project-scoped がデフォルト**: project mode 時に `<cwd>/.spotter/marker.json` も削除する (`.spotter/` ディレクトリ自体は残す)。
+- **新ガード `isOutsideSpotterProject(input)`**: 5 つの hook の冒頭で hook input の `cwd` を起点に上向きに `.spotter/marker.json` を探し、見つからなければ `exit 0`。Throughline 等の他ツールが別 workdir で `claude -p` を呼んだ場合、そもそも Spotter hook 自体が無視される (実測の Throughline 由来 51 件のうち 49 件は別 workdir 起動なので、このガード単独で 96% を hook 側で完全遮断)。
+- **`preuninstall` を縮小**: legacy user-scope hook の cleanup は best-effort で残し、project-level hook は各プロジェクトでユーザーが明示 uninstall するよう案内する。
+
+### Breaking
+
+- `npm install -g claude-spotter` 後に各プロジェクトで `spotter install` を一度実行する必要がある (v0.1.1 / v0.2.x の自動登録は撤回された)。
+- 旧バージョンの user-global hook 登録は `npm uninstall` 時に preuninstall が cleanup を試みるが、各プロジェクトの hook 登録は手動 uninstall が必要。
+
+### 持ち越し
+
+- A-2 warmup の `--resume` 40+秒 timeout 問題 (v0.2.1 の追跡課題) は本リリースでは未対応 — 別枠で調査継続。
+
+## 0.2.1
+
+v0.2.0 の実セッション観測で `UserPromptSubmit` 経路に `E_HAIKU_TIMEOUT` が集中していることが判明 (20 分で 14 件、全て `handler error on user_input`)。Stop hook 側はタイムアウトゼロ。原因は初回 Haiku spawn (Windows: `cmd.exe /c claude.cmd -p --session-id ...`) のコールドスタートが 28s 超になるケースで、これが UserPromptSubmit hook のブロック中に直撃していた。
+
+- **Haiku 非同期ウォームアップ (A-2)**: `startDaemon({ warmup: true })` オプションを追加。`daemon-cmd.mjs` (SessionStart 経由のエントリ) で `true` を渡す。daemon は `server.listen` 完了直後に fire-and-forget で `buildWarmupPrompt` を Haiku に送信し、`--session-id` での新規会話作成とカタログ読み込みを前倒しする。SessionStart hook の readiness ping は `daemon listening` 確認のみで完了するためユーザー体感の起動遅延ゼロ。
+- **初回 `user_input` は `--resume` 経由**: ウォームアップ完了後、既存の `haikuChain` mutex が最初の real call に warmup の完了を待たせ、`isFirst=false` で `claude -p --resume` が走る。
+- **warmup 後の 10 秒ウィンドウリセット**: ウォームアップも `claude -p` spawn なので `lastHaikuCallAt` を更新するが、完了時 (成否問わず) に 0 にリセットして layer 5 が warmup 直後の合法的 `user_input` を silent pass にしないようにする。SPOTTER_PARENT_PID env 他のレイヤーで recursion は遮断済みなのでリセットは安全。
+- **`buildWarmupPrompt` 新設**: 既存の `buildFirstStagePrompt` を流用せず、Haiku に trivial pass (`{"pass":true,"missing_tools":[]}`) を返させる固定プロンプトを採用。`parseHaikuResponse` のスキーマチェックを通過する形で warmup が成功し、`haikuInitialized=true` が立つ。
+- **失敗時は従来動作**: warmup が失敗すると `haikuInitialized=false` のまま残り、次の real call が `--session-id` で仕切り直す。悪化なし。
+
+### 観測対象として残した課題 (v0.2.1 では未対応)
+
+- **20 分で 28 daemon 生成**: 実セッション観測で §18.4 の 5 層防御がすり抜けている疑い (状況的には別 VSCode の旧 daemon 残存も仮説)。A-2 とは独立の bug 調査として次タスク化。
+- **カタログのツール名抽象**: 実ツール名 (`current_time` カタログ記載 vs 実環境 `Bash:date`) のマッピング論点、v0.3 持ち越し。
+
 ## 0.2.0
 
 Fixes the v0.1.x daemon proliferation by adding multiple defence layers that together prevent any

package/bin/spotter.mjs

@@ -17,8 +17,15 @@ import { runSessionEnd } from '../src/hooks/session-end.mjs';
 const USAGE = `spotter — Claude Code tool-call auditor
 
 Usage:
-  spotter install [--user] [-y]         register hooks in .claude/settings.json
-  spotter uninstall [--user] [-y]       remove spotter hooks
+  spotter install [-y]                  register hooks in <cwd>/.claude/settings.json
+                                        and create <cwd>/.spotter/marker.json
+                                        (run inside each project you want audited)
+  spotter install --user [-y]           legacy: register globally in ~/.claude/settings.json
+                                        (NOT RECOMMENDED — fires for every Claude Code session
+                                         on the system, including unrelated \`claude -p\`)
+  spotter uninstall [-y]                remove spotter hooks from <cwd>/.claude/settings.json
+                                        and remove <cwd>/.spotter/marker.json
+  spotter uninstall --user [-y]         remove from ~/.claude/settings.json
   spotter catalog edit                  open tool catalog in $EDITOR
   spotter catalog lint                  validate catalog + run test_cases (Haiku live call)
   spotter status                        show running daemons

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {

package/scripts/postinstall.mjs

@@ -1,42 +1,29 @@
 // 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';
+// v0.3: auto-register has been removed. The previous behaviour (writing hooks to
+// ~/.claude/settings.json globally) caused daemon proliferation: every Claude Code
+// session anywhere on the system — including `claude -p` invocations from unrelated
+// tools like Throughline — fired the hooks and spawned a daemon. The fix is
+// project-scoped install: the user runs `spotter install` inside each project they
+// want audited, which writes hooks to that project's .claude/settings.json plus a
+// .spotter/marker.json that hooks check before doing any work.
+//
+// This script now only prints onboarding guidance.
 
 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;
-  }
+// Honor the legacy skip env var for parity with old guidance, but it's a no-op now.
+if (process.env[SKIP_ENV]) {
+  process.exit(0);
+}
 
-  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.');
-  }
+if (process.env.CI === 'true' || process.env.CI === '1') {
+  process.exit(0);
 }
 
-main().catch((err) => {
-  // Defensive: never let postinstall crash the install.
-  console.warn(`claude-spotter: postinstall unexpected error — ${err.message}`);
-});
+console.log('claude-spotter installed.');
+console.log('  Next step (per project you want audited):');
+console.log('    cd <your-project>');
+console.log('    spotter install');
+console.log('  This writes hooks to <project>/.claude/settings.json and a .spotter/');
+console.log('  marker so unrelated `claude -p` invocations do not trigger Spotter.');

package/scripts/preuninstall.mjs

@@ -1,5 +1,9 @@
 // Runs before `npm uninstall (-g) claude-spotter`.
-// Removes hooks from ~/.claude/settings.json so an uninstall leaves the system clean.
+//
+// v0.3: with project-scoped install (no global hook registration), preuninstall
+// has nothing global to clean. We do a best-effort cleanup of the legacy
+// ~/.claude/settings.json registration in case the user upgraded from <0.3, then
+// print guidance for project-level uninstall.
 //
 // Never fails the uninstall — on error we warn and exit 0.
 
@@ -7,8 +11,10 @@ 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.');
+  console.warn(`claude-spotter: legacy user-scope cleanup skipped — ${err.message}`);
 }
+
+console.log('claude-spotter: per-project hooks (in <project>/.claude/settings.json) are not removed automatically.');
+console.log('  To remove them, run `spotter uninstall` in each project before this uninstall completes,');
+console.log('  or edit <project>/.claude/settings.json manually after.');

package/src/cli/daemon-cmd.mjs

@@ -34,7 +34,7 @@ export async function runDaemonStart({ argv }) {
 
   let running;
   try {
-    running = await startDaemon({ sessionId, logFn: log });
+    running = await startDaemon({ sessionId, logFn: log, warmup: true });
   } catch (err) {
     if (err instanceof DaemonAlreadyRunningError) {
       // v0.2 PID-preexist layer: a sibling daemon already serves this session.

package/src/cli/install.mjs

@@ -1,12 +1,17 @@
 // `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.
+//
+// v0.3: also writes <cwd>/.spotter/marker.json (project mode) so hooks can detect
+// "this Claude Code session is rooted in a project where Spotter is installed" and
+// silently exit otherwise (prevents Throughline-style proliferation).
 
 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';
+import { version as SPOTTER_VERSION } from '../version.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
@@ -16,6 +21,8 @@ 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 MARKER_VERSION = '1';
+
 const HOOK_EVENTS = [
   { event: 'SessionStart', sub: 'session-start', timeout: 5 },
   { event: 'UserPromptSubmit', sub: 'user-prompt', timeout: 30 },
@@ -48,7 +55,28 @@ export async function runInstall({ target = 'project', autoYes = false, cwd = pr
     console.log(`  catalog already present at ${CATALOG_DEST} (not overwritten)`);
   }
 
-  // 3. compute desired settings.json with hooks
+  // 3. project marker (v0.3): hooks use this to detect installed projects.
+  //    Skipped in user-mode install — user-mode is a deprecated escape hatch and
+  //    intentionally has no marker, so all hooks would exit. (Existing user-mode
+  //    installs from <0.3 won't surprise-stop working only because of this — they
+  //    were already broken by daemon proliferation.)
+  //
+  //    Always overwritten so that `spotter install` after a version bump refreshes
+  //    `spotterVersion` / `installedAt` rather than leaving stale metadata.
+  if (target === 'project') {
+    const markerDir = join(cwd, '.spotter');
+    const markerPath = join(markerDir, 'marker.json');
+    await mkdir(markerDir, { recursive: true });
+    const marker = {
+      markerVersion: MARKER_VERSION,
+      spotterVersion: SPOTTER_VERSION,
+      installedAt: new Date().toISOString(),
+    };
+    await writeFile(markerPath, JSON.stringify(marker, null, 2) + '\n', 'utf8');
+    console.log(`  wrote ${markerPath}`);
+  }
+
+  // 4. compute desired settings.json with hooks
   const current = await loadSettings(settingsPath);
   const updated = mergeHooks(current);
   const diff = diffSettings(current, updated);

package/src/cli/uninstall.mjs

@@ -1,7 +1,11 @@
 // `spotter uninstall` — remove hook entries that reference this spotter installation.
 // Does NOT delete ~/.spotter/ (user data), just unregisters hooks.
+//
+// v0.3: in project mode also removes the .spotter/marker.json (so that hooks would
+// silently exit even if the settings.json removal somehow failed). The .spotter/
+// directory itself is left alone in case the user has additional content there.
 
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile, rm, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -13,6 +17,10 @@ export async function runUninstall({ target = 'project', autoYes = false, cwd =
 
   console.log(`spotter uninstall (settings: ${settingsPath})`);
 
+  if (target === 'project') {
+    await removeMarker(cwd);
+  }
+
   let current;
   try {
     current = JSON.parse(await readFile(settingsPath, 'utf8'));
@@ -73,3 +81,16 @@ export async function runUninstall({ target = 'project', autoYes = false, cwd =
   console.log(`wrote ${settingsPath}`);
   console.log('note: ~/.spotter/ (catalog, logs) was not removed. delete manually if no longer needed.');
 }
+
+async function removeMarker(cwd) {
+  const markerPath = join(cwd, '.spotter', 'marker.json');
+  try {
+    await stat(markerPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  await rm(markerPath, { force: true });
+  console.log(`  removed ${markerPath}`);
+  // Leave the .spotter/ directory itself in place — the user may keep other files there.
+}

package/src/daemon/daemon.mjs

@@ -21,6 +21,7 @@ import { createServer, ensureRuntimeDir, socketPath } from './transport.mjs';
 import {
   buildFirstStagePrompt,
   buildFinalStagePrompt,
+  buildWarmupPrompt,
   parseHaikuResponse,
   createHaikuCaller,
 } from './haiku-caller.mjs';
@@ -48,6 +49,7 @@ export async function startDaemon({
   haikuCaller,
   haikuSessionId,
   logFn = () => {},
+  warmup = false,
 } = {}) {
   if (!sessionId) {
     throw new TypeError('sessionId is required');
@@ -229,11 +231,37 @@ export async function startDaemon({
   const pidPath = pidFilePath(sessionId);
   await writeFile(pidPath, String(process.pid), 'utf8');
 
+  // A-2: fire-and-forget Haiku warmup. Pays the cold-start cost during SessionStart
+  // (while the user is still composing their first prompt) rather than blocking the
+  // first UserPromptSubmit. On success the Haiku conversation is ready for --resume
+  // and subsequent calls respond within the 28s timeout. On failure we log and leave
+  // haikuInitialized=false so the next real call retries as --session-id (no regression).
+  // haikuChain serialises this against any incoming event, preventing double-init.
+  //
+  // After warmup settles (success or failure) we reset lastHaikuCallAt so that the first
+  // real user_input is not spuriously silenced by the 10-second recursion window. The
+  // SPOTTER_PARENT_PID env var and agent_id gate already prevent genuine recursion from
+  // the warmup spawn, so this reset does not regress the defence.
+  let warmupPromise = null;
+  if (warmup) {
+    warmupPromise = callHaikuTracked(() => buildWarmupPrompt({ catalog })).then(
+      () => {
+        logFn('warmup: haiku session initialised');
+        lastHaikuCallAt = 0;
+      },
+      (err) => {
+        logFn(`warmup failed: ${err.code ?? 'E_INTERNAL'}: ${err.message}`);
+        lastHaikuCallAt = 0;
+      }
+    );
+  }
+
   return {
     server,
     path,
     pidPath,
     haikuSessionId: ownHaikuSessionId,
+    warmupPromise,
     stop: () => shutdown(server, sessionId, logFn),
   };
 }

package/src/daemon/haiku-caller.mjs

@@ -101,6 +101,30 @@ export function buildFinalStagePrompt({ catalog, userInput, usedTools, finalResp
   ].join('\n');
 }
 
+// Build a warmup prompt — fired by the daemon right after `server.listen` to pay the
+// Haiku cold-start cost before the first user_input arrives. Uses --session-id to create
+// the Haiku conversation with catalog + rules loaded; subsequent real calls hit --resume
+// and respond within the hook timeout.
+// The returned response is discarded by the caller; we instruct Haiku to return the trivial
+// pass object so that parseHaikuResponse does not throw on the warmup result.
+export function buildWarmupPrompt({ catalog }) {
+  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),
+    '',
+    '## ウォームアップ呼び出し',
+    'これはセッション開始直後のウォームアップ呼び出しです。実際のユーザー入力はまだありません。',
+    '以降の判定に備えて、上記カタログと判定ルールをコンテキストに保持してください。',
+    'この呼び出しでは必ず `{"pass": true, "missing_tools": []}` のみを返してください。',
+  ].join('\n');
+}
+
 function systemRules() {
   return [
     'あなたは Spotter — Claude (Bell) が呼び忘れているツールを検出する監査役です。',

package/src/hooks/lib.mjs

@@ -12,6 +12,14 @@
 // - 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).
+//
+// v0.3 gate (plan §18 daemon-proliferation root fix):
+// - findSpotterMarker(cwd): walk up from cwd looking for .spotter/marker.json.
+//   Hooks exit 0 when no marker is found, so other tools' `claude -p` invocations
+//   in unrelated workdirs (Throughline workdir etc.) never spawn a daemon.
+
+import { statSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
 
 export function isChildCall() {
   const v = process.env.SPOTTER_PARENT_PID;
@@ -25,6 +33,39 @@ export function isSubagentCall(input) {
       && input.agent_id.length > 0;
 }
 
+// Walk up from startCwd looking for .spotter/marker.json. Returns the project
+// root path containing the marker, or null if none was found before reaching
+// the filesystem root.
+//
+// Synchronous fs is intentional — hooks run on every Claude Code event and
+// must add minimal latency. statSync of one file per directory level is cheap.
+export function findSpotterMarker(startCwd) {
+  if (typeof startCwd !== 'string' || startCwd.length === 0) return null;
+  let dir = startCwd;
+  const root = parse(dir).root;
+  while (true) {
+    const marker = join(dir, '.spotter', 'marker.json');
+    try {
+      const st = statSync(marker);
+      if (st.isFile()) return dir;
+    } catch {
+      // marker missing at this level — keep walking up
+    }
+    if (dir === root) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// True when input.cwd does not sit inside a project that has been `spotter install`-ed.
+// Used by all 5 hooks to early-exit on unrelated `claude -p` invocations from other tools.
+export function isOutsideSpotterProject(input) {
+  const cwd = input?.cwd;
+  if (typeof cwd !== 'string' || cwd.length === 0) return true;
+  return findSpotterMarker(cwd) === null;
+}
+
 export async function readStdinJson() {
   let raw = '';
   process.stdin.setEncoding('utf8');

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

@@ -1,7 +1,7 @@
 // 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, isChildCall, isSubagentCall } from './lib.mjs';
+import { readStdinJson, requireString, exitCodeFor, die, isChildCall, isSubagentCall, isOutsideSpotterProject } from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
 const TIMEOUT_MS = 1_000;
@@ -10,6 +10,7 @@ export async function runPreToolUse() {
   if (isChildCall()) return;
   const input = await readStdinJson();
   if (isSubagentCall(input)) return;
+  if (isOutsideSpotterProject(input)) return;
 
   const sessionId = requireString(input, 'session_id');
   const toolName = requireString(input, 'tool_name');

package/src/hooks/session-end.mjs

@@ -1,7 +1,7 @@
 // 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, isChildCall, isSubagentCall } from './lib.mjs';
+import { readStdinJson, requireString, isChildCall, isSubagentCall, isOutsideSpotterProject } from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
 const TIMEOUT_MS = 2_000;
@@ -10,6 +10,7 @@ export async function runSessionEnd() {
   if (isChildCall()) return;
   const input = await readStdinJson();
   if (isSubagentCall(input)) return;
+  if (isOutsideSpotterProject(input)) return;
 
   const sessionId = requireString(input, 'session_id');
 

package/src/hooks/session-start.mjs

@@ -7,12 +7,16 @@
 //   - 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)
+//
+// v0.3 gate:
+//   - isOutsideSpotterProject: cwd has no .spotter/marker.json above it → exit 0
+//     (Throughline workdir etc. — `claude -p` from tools outside any installed project)
 
 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, isChildCall, isSubagentCall } from './lib.mjs';
+import { readStdinJson, requireString, die, isChildCall, isSubagentCall, isOutsideSpotterProject } from './lib.mjs';
 import { sendRequest, TransportError } from '../daemon/transport.mjs';
 
 const READINESS_TIMEOUT_MS = 3_000;
@@ -30,6 +34,10 @@ export async function runSessionStart({ argv = process.argv, now = Date.now } =
   // Gate 3: non-startup sources (resume/compact/clear) don't spawn a new daemon.
   if (input.source !== 'startup') return;
 
+  // Gate 4 (v0.3): cwd is not inside any project that has been `spotter install`-ed.
+  // Other tools (Throughline etc.) launching `claude -p` in unrelated workdirs land here.
+  if (isOutsideSpotterProject(input)) return;
+
   const sessionId = requireString(input, 'session_id');
 
   spawnDaemon(sessionId, argv);

package/src/hooks/stop.mjs

@@ -11,6 +11,7 @@ import {
   formatTransparentBlockReason,
   isChildCall,
   isSubagentCall,
+  isOutsideSpotterProject,
 } from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
@@ -20,6 +21,7 @@ export async function runStop() {
   if (isChildCall()) return;
   const input = await readStdinJson();
   if (isSubagentCall(input)) return;
+  if (isOutsideSpotterProject(input)) return;
 
   const sessionId = requireString(input, 'session_id');
   const stopHookActive = input.stop_hook_active === true;

package/src/hooks/user-prompt.mjs

@@ -9,6 +9,7 @@ import {
   formatTransparentContext,
   isChildCall,
   isSubagentCall,
+  isOutsideSpotterProject,
 } from './lib.mjs';
 import { sendRequest } from '../daemon/transport.mjs';
 
@@ -18,6 +19,7 @@ export async function runUserPrompt() {
   if (isChildCall()) return;
   const input = await readStdinJson();
   if (isSubagentCall(input)) return;
+  if (isOutsideSpotterProject(input)) return;
 
   const sessionId = requireString(input, 'session_id');
   const prompt = requireString(input, 'prompt');

package/src/version.mjs

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