claude-spotter 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 0.7.0
+
+**カタログを tool-db に置き換え**。手書きの `tools.yaml` (5 つの抽象ツール) を捨て、**実際にセッションで使えるツール (MCP + Claude Code 組込み 遅延ツール) の name + description を自動収集してキャッシュする** 仕組みに置き換え。
+
+### 事の発端
+
+Haiku が「Bell が呼び忘れているツール」を判定するには、Bell が今のセッションで実際に呼べるツールを知っている必要がある。v0.6.x までのカタログは `current_time` / `web_search` / `read_file` のような **抽象的な汎用ツール 5 件** を手書きしていただけで、Caveat や Gmail のような MCP ツール、TodoWrite や WebSearch のような Claude Code 組込みの遅延ツールは Haiku の視野に入っていなかった。結果、ユーザーが「過去に解決したナレッジを残したい」と言っても Spotter は Caveat を推奨できないという的外れな状態だった。
+
+設計思想は [docs/catalog-design-deferred-mcp.md](docs/catalog-design-deferred-mcp.md) に集約。要点:
+
+- **Haiku に渡すのは name + description のペアだけ**。schema は不要 — どう呼ぶかは Bell が ToolSearch で解決する責任 (役割分業)
+- **MCP ツールの description は MCP サーバーから直接取得**。Spotter は中継者に徹し、手書きで言い換えない (single source of truth = MCP server)
+- **3 段階キャッシュ DB**: ローカル (プロジェクト) → グローバル (`~`) → 「調べる」(調査結果は両方に書き込む)
+- **drift 補正**: ローカル ≠ グローバルなら再調査して MCP server の現在値で両方上書き
+- **明示的な無効化機構なし**: drift 補正が間接無効化として機能、TTL なし
+
+### 変更点
+
+- **新規 [src/tool-db/loader.mjs](src/tool-db/loader.mjs)**: JSON DB の atomic 読み書き、`{version, tools: {name → description}}` スキーマ検証
+- **新規 [src/tool-db/lookup.mjs](src/tool-db/lookup.mjs)**: 3 段階 lookup + write-through + drift 補正
+- **新規 [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs)**: `claude mcp list` / `claude mcp get` で MCP サーバー列挙、stdio サーバーに JSON-RPC で `initialize` + `tools/list` を実行して description 取得
+- **新規 [src/tool-db/deferred-baseline.mjs](src/tool-db/deferred-baseline.mjs)**: Claude Code 組込み 遅延ツール (WebSearch / TodoWrite / 等 17 件) の手書き description ベースライン (Claude Code 自体は MCP 経由で query できないため)
+- **新規 [src/tool-db/refresh.mjs](src/tool-db/refresh.mjs)**: 投資 = 利用可能ツール一覧取得 + 各ツールを 3 段階解決 + DB 書き戻し
+- **新規 [src/cli/db-cmd.mjs](src/cli/db-cmd.mjs)**: `spotter db list` / `refresh` / `rebuild`
+- **編集 [src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: `loadCatalog` 廃止、`startDaemon({ projectRoot })` で tool-db を読み込み (テスト用に `tools` 直接指定も可)
+- **編集 [src/daemon/haiku-caller.mjs](src/daemon/haiku-caller.mjs)**: `buildPreamble({ catalog })` → `buildPreamble({ tools })`、tools は `[{name, description}]`
+- **編集 [src/cli/daemon-cmd.mjs](src/cli/daemon-cmd.mjs)**, **[src/hooks/session-start.mjs](src/hooks/session-start.mjs)**: `--project-root` を hook → daemon に伝達
+- **編集 [src/cli/install.mjs](src/cli/install.mjs)**: `tool-catalog/` 作成と template コピー削除、install 完了時に `spotter db refresh` 実行を案内
+- **編集 [src/cli/doctor.mjs](src/cli/doctor.mjs)**: catalog チェック → tool-db (global + local) のチェック
+- **編集 [bin/spotter.mjs](bin/spotter.mjs)**: `spotter catalog edit/lint` を `spotter db list/refresh/rebuild` に置換
+- **削除**: [src/catalog/](src/catalog/), [src/cli/catalog.mjs](src/cli/catalog.mjs), `templates/tools.yaml`, `test/catalog.test.mjs`, `test/loader.test.mjs`
+- **新規 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: 21 件 (loader/lookup/investigate-mcp/deferred-baseline)
+
+### Breaking
+
+- `~/.spotter/tool-catalog/tools.yaml` は読まれなくなる。install 後 `spotter db refresh` を実行して `~/.spotter/tool-db.json` (グローバル) と `<project>/.spotter/tool-db.json` (ローカル) を populate する必要がある
+- `spotter catalog edit/lint` コマンド廃止 → `spotter db list/refresh/rebuild`
+- `startDaemon` シグネチャ変更: `catalogPath` 廃止、`tools` または `projectRoot` のいずれか必須
+- `buildPreamble({ catalog })` → `buildPreamble({ tools })`
+- `src/index.mjs` から `loadCatalog`, `validateCatalog`, `runLint` 等を削除、tool-db API を export
+- `claude mcp list` のエラー / SSE/HTTP transport 未対応のため、これらサーバーの description は取れない (今後の課題)
+
+### 既知の制約
+
+- HTTP/SSE transport の MCP サーバーは investigate でスキップ (将来 HTTP MCP クライアント実装で対応)
+- Claude Code の遅延ツール一覧は hardcoded baseline のみ。Claude Code が新しい built-in を追加したら baseline 更新が必要
+- `claude mcp list` の出力フォーマット変更には脆い (parse 依存)。JSON 出力モードが将来追加されたらそちらに切り替えたい
+
+## 0.6.2
+
+**親プロセス watch による孤児 daemon 自動回収**。SessionEnd が発火しない経路 (Claude Code crash, kill -9, IDE reload) で daemon が永久に残る問題への対処。
+
+### 事の発端
+
+実運用で `spotter status` を見ると、現セッション以外に複数の daemon が `process=alive` で残存している状態が頻発していた。今回の観測では 9 個中 8 個が孤児で、手動 `taskkill` + `.pid` ファイル削除で掃除する必要があった。原因は SessionEnd hook が**正常終了経路でしか発火しない**こと。Claude Code の crash、強制終了、VSCode リロード等のいずれかで daemon は親を失っても生き続ける。v0.2 スコープに「孤児 cleanup」と書いてあったが未実装のままだった。
+
+### 変更点
+
+- **[src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: `startDaemon({ parentPid, parentWatchIntervalMs })` を追加。`parentPid` が指定されると 5 秒間隔 (default) で `process.kill(parentPid, 0)` を ping し、ESRCH を検知したら自身を shutdown。`parentWatchIntervalMs` はテスト用に短縮可能。`parentPid !== null && (!Number.isInteger || <= 0)` は TypeError で reject。
+- **[src/cli/daemon-cmd.mjs](src/cli/daemon-cmd.mjs)**: `--parent-pid <N>` 引数をパースして `startDaemon` に渡す。
+- **[src/hooks/session-start.mjs](src/hooks/session-start.mjs)**: daemon spawn 時に `--parent-pid <process.ppid>` を付与。`process.ppid` は SessionStart hook から見た親 = Claude Code 本体。
+- **[test/daemon.test.mjs](test/daemon.test.mjs)**: 子プロセスを fake parent として spawn → daemon 起動 → 子を SIGKILL → daemon の `server.on('close')` が発火することを検証する E2E テストを追加。`parentPid: 0` / `1.5` が TypeError になることのバリデーションテストも追加。
+
+### 効果
+
+- 通常運用 (SessionEnd 発火経路) では従来どおり graceful shutdown
+- 異常終了経路 (crash, kill, reload) では親消滅を最大 5 秒で検知して自殺
+- 観測コスト: `process.kill(pid, 0)` の syscall が 5 秒に 1 回。idle CPU 影響は無視できる程度
+
+### 既知の制約
+
+- 親 PID を持たない経路 (手動 `spotter daemon start --session-id ...`) では watch が動かない (parentPid が null)。これは debug 用なので許容。
+- Claude Code が中間プロセス (cmd.exe / sh wrapper) 越しに hook を起動している場合、`process.ppid` が wrapper を指す可能性あり。今回の Windows 環境では実測で Claude Code 本体を指していたが、将来的に環境差で問題が出れば PID 取得方法を再検討。
+- 5 秒間隔のため、kill 直後の最大 5 秒は孤児状態が残る。これ以上短縮するなら polling コストとのトレードオフ再評価。
+
 ## 0.6.1
 
 **v0.6.0 で `src/version.mjs` を更新し忘れた trivia fix**。`spotter --version` が古い `0.5.2` を返していた。挙動差はない。

package/README.md

@@ -1,12 +1,12 @@
 # Spotter
 
-> **v0.4.3 released 2026-04-19**. v0.2.0 で追加した session-scoped Haiku は Spotter 本体プロジェクトでの長時間運用中に role collapse (Haiku が Bell 人格に drift) を起こしたため、v0.4.0 で stateless に回帰。v0.4.2 で stateless 化の副作用として発生した cold-start timeout 問題に対処 (timeout 28s→60s + stateless-safe warmup)、v0.4.3 で過剰になっていたプロンプトを 30-40% 削減。詳細は [CHANGELOG](CHANGELOG.md)。
+> **v0.7.0 released 2026-04-19**. **カタログを tool-db に置き換え**: 手書きの抽象ツール 5 件カタログを廃止し、`claude mcp list` + JSON-RPC `tools/list` で MCP ツールの description を自動取得、Claude Code 組込み 遅延ツール (WebSearch/TodoWrite 等) は hardcoded baseline からカバー、3 段階キャッシュ DB (ローカル → グローバル → 調査して両方に追記) で 2 回目以降は通信ゼロ。これで Caveat や Gmail のような MCP ツールが初めて Haiku の視野に入る。設計思想は [docs/catalog-design-deferred-mcp.md](docs/catalog-design-deferred-mcp.md)、変更詳細は [CHANGELOG](CHANGELOG.md)。
 
 **気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
 
 > Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。現在時刻を推測で答える、web_search を呼ばずに古い情報で応答する、read_file を使わずにファイルの中身を推測する — 「分からないと自覚できない」から、ツールを取りに行けない。
 
-Spotter は、ツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎にプロセスとして常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると、透明化された指摘として Bell に届け、補正応答を促します。Haiku 呼び出しは毎ターン stateless (fresh `--session-id`) で実行されるため、長時間運用しても会話履歴による persona drift を構造的に防ぎます。
+Spotter は、ツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎にプロセスとして常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると、透明化された指摘として Bell に届け、補正応答を促します。Haiku 呼び出しは session-scoped (`--resume`) で同一セッションに再接続して cold-start を削減し、初回のみ preamble を送って以降は per-turn delta だけ送ることで session 肥大化を防ぎます。role collapse (persona drift で JSON 契約破棄) は構造的に予防せず、検知した瞬間に session を切り直して fresh state から再開する事後回復機構で長時間運用に耐えます。
 
 ## インストール
 
@@ -44,7 +44,7 @@ Stop hook → Spotter が応答と使用済みツールを見て最終チェッ
 見落としあれば差し戻し (max 1 回、Claude Code の stop_hook_active で自動担保)
 ```
 
-`~/.spotter/tool-catalog/tools.yaml` に監査対象のツール用途を記述します。`current_time` / `web_search` / `read_file` / `list_directory` / `run_command` の雛形付き。
+監査対象のツール (name + description) は `~/.spotter/tool-db.json` (グローバル) と `<project>/.spotter/tool-db.json` (ローカル) に格納されます。install 後に `spotter db refresh` を実行すると、`claude mcp list` で MCP サーバーを列挙し、各サーバーの `tools/list` を JSON-RPC で叩いて description を収集、Claude Code 組込み 遅延ツール (WebSearch / TodoWrite 等) は同梱の baseline からカバーします。**手書きでツールリストを管理する必要はありません**。
 
 ## Throughline との関係
 
@@ -61,10 +61,11 @@ Stop hook → Spotter が応答と使用済みツールを見て最終チェッ
 ## よく使うコマンド
 
 ```bash
-spotter catalog edit     # ツールカタログを $EDITOR で開く
-spotter catalog lint     # YAML 検証 + test_cases を Haiku 実呼びで検証
+spotter db list          # 現在の tool-db (local + global merged) を表示
+spotter db refresh       # MCP サーバーと組込み 遅延ツールから description を収集して DB 更新
+spotter db rebuild       # ローカル DB を消してから refresh (強制再投資)
 spotter status           # 稼働中の daemon 一覧
-spotter doctor           # 環境診断 (Node / claude CLI / カタログ整合性)
+spotter doctor           # 環境診断 (Node / claude CLI / tool-db 整合性)
 spotter uninstall        # hook 登録を解除 (~/.spotter は残す)
 ```
 
@@ -75,7 +76,7 @@ spotter uninstall        # hook 登録を解除 (~/.spotter は残す)
 ## 既知の制約
 
 - Stop hook は Bell の最初の応答が**出力された後**に発火するため、Spotter が Stop で差し戻した場合、ユーザーは「最初の応答 + 補正応答」の 2 連続を見ます (Claude Code の hook 仕様による制約)。UserPromptSubmit 段階での先回り検出を精度の軸にしています
-- JSON スキーマ違反・Haiku timeout はリトライせず即 throw します (§14.1 silent fallback 禁止の帰結)。UserPromptSubmit がブロックされユーザー入力が Bell に届かない症状として顕在化します。cold-start 対策として v0.4.2 で timeout 60s + warmup を導入しましたが、fail-open 化 (timeout を pass 扱い) は §0 改訂とセットで今後検討
+- **JSON スキーマ違反は v0.5.0 以降「想定済み異常」として silent pass + session renew で回復**します (role collapse 検知パス、daemon ログに `role_collapse_reset` を残す)。一方 **Haiku timeout は引き続き throw** され、UserPromptSubmit がブロックされてユーザー入力が Bell に届かない症状として顕在化します (timeout は v0.5.0 で 30s に短縮)。timeout の fail-open 化 (pass 扱い) は §0 改訂とセットで今後検討
 
 ## ライセンス
 

package/bin/spotter.mjs

@@ -6,7 +6,7 @@ import { runInstall } from '../src/cli/install.mjs';
 import { runUninstall } from '../src/cli/uninstall.mjs';
 import { runDoctor } from '../src/cli/doctor.mjs';
 import { runStatus } from '../src/cli/status.mjs';
-import { runCatalogEdit, runCatalogLint } from '../src/cli/catalog.mjs';
+import { runDbList, runDbRefresh, runDbRebuild } from '../src/cli/db-cmd.mjs';
 import { runDaemonStart } from '../src/cli/daemon-cmd.mjs';
 import { runSessionStart } from '../src/hooks/session-start.mjs';
 import { runUserPrompt } from '../src/hooks/user-prompt.mjs';
@@ -26,8 +26,9 @@ Usage:
   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 db list                       show merged tool-db (local + global)
+  spotter db refresh                    discover MCP / deferred tools and update DB
+  spotter db rebuild                    wipe local DB then refresh
   spotter status                        show running daemons
   spotter doctor                        environment diagnostic
   spotter daemon start --session-id ID  (internal) run session daemon
@@ -64,11 +65,12 @@ async function main() {
       await runUninstall({ target, autoYes });
       return;
     }
-    case 'catalog': {
+    case 'db': {
       const sub = rest[0];
-      if (sub === 'edit') { await runCatalogEdit(); return; }
-      if (sub === 'lint') { await runCatalogLint(); return; }
-      process.stderr.write(`unknown catalog subcommand: ${sub}\n${USAGE}`);
+      if (sub === 'list') { await runDbList(); return; }
+      if (sub === 'refresh') { await runDbRefresh(); return; }
+      if (sub === 'rebuild') { await runDbRebuild(); return; }
+      process.stderr.write(`unknown db subcommand: ${sub}\n${USAGE}`);
       process.exit(2);
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {
@@ -43,7 +43,6 @@
     "bin",
     "src",
     "scripts",
-    "templates",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/src/cli/daemon-cmd.mjs

@@ -6,22 +6,33 @@ import { join } from 'node:path';
 import { open } from 'node:fs/promises';
 
 function parseArgs(argv) {
-  const out = { sessionId: null };
+  const out = { sessionId: null, parentPid: null, projectRoot: null };
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === '--session-id') {
       out.sessionId = argv[i + 1];
       i += 1;
+    } else if (argv[i] === '--parent-pid') {
+      const n = parseInt(argv[i + 1], 10);
+      if (Number.isInteger(n) && n > 0) out.parentPid = n;
+      i += 1;
+    } else if (argv[i] === '--project-root') {
+      out.projectRoot = argv[i + 1];
+      i += 1;
     }
   }
   return out;
 }
 
 export async function runDaemonStart({ argv }) {
-  const { sessionId } = parseArgs(argv);
+  const { sessionId, parentPid, projectRoot } = parseArgs(argv);
   if (!sessionId) {
     process.stderr.write('spotter daemon start: --session-id is required\n');
     process.exit(2);
   }
+  if (!projectRoot) {
+    process.stderr.write('spotter daemon start: --project-root is required (the path containing .spotter/marker.json)\n');
+    process.exit(2);
+  }
 
   const logFile = await open(
     join(homedir(), '.spotter', 'logs', `daemon-${sessionId}.log`),
@@ -37,7 +48,11 @@ export async function runDaemonStart({ argv }) {
     // v0.5.0: no warmup. Session-scoped Haiku (--resume on follow-ups) pays cold-start
     // only on the first real call; warmup added complexity for marginal benefit and is
     // removed along with the stateless regime that required it.
-    running = await startDaemon({ sessionId, logFn: log });
+    // v0.6.2: parentPid (Claude Code PID, captured by SessionStart hook as process.ppid)
+    // is threaded in so the daemon self-terminates when the parent dies without
+    // SessionEnd (crash / kill / IDE reload).
+    // v0.7.0: projectRoot drives tool-db loading (replaces the old tools.yaml catalog).
+    running = await startDaemon({ sessionId, projectRoot, parentPid, logFn: log });
   } catch (err) {
     if (err instanceof DaemonAlreadyRunningError) {
       // v0.2 PID-preexist layer: a sibling daemon already serves this session.

package/src/cli/db-cmd.mjs

@@ -0,0 +1,55 @@
+// `spotter db` — manage the tool-db.
+//
+//   spotter db list             — print merged tool-db (local overrides global)
+//   spotter db refresh          — discover available tools and update DB (3-tier resolve)
+//   spotter db rebuild          — wipe local DB then refresh (forces re-investigation)
+//
+// Run inside a project that has been `spotter install`-ed.
+
+import { findSpotterMarker } from '../hooks/lib.mjs';
+import { refresh, readMerged } from '../tool-db/refresh.mjs';
+import { localDbPath, globalDbPath, loadDb, saveDb, emptyDb } from '../tool-db/loader.mjs';
+import { writeFile } from 'node:fs/promises';
+
+function requireProjectRoot() {
+  const root = findSpotterMarker(process.cwd());
+  if (!root) {
+    process.stderr.write('spotter db: no .spotter/marker.json found in or above cwd. Run `spotter install` first.\n');
+    process.exit(2);
+  }
+  return root;
+}
+
+export async function runDbList() {
+  const projectRoot = requireProjectRoot();
+  const tools = await readMerged({ projectRoot });
+  if (tools.length === 0) {
+    process.stdout.write('(empty — run `spotter db refresh` to populate)\n');
+    return;
+  }
+  for (const { name, description } of tools) {
+    process.stdout.write(`${name}\n  ${description}\n\n`);
+  }
+}
+
+export async function runDbRefresh() {
+  const projectRoot = requireProjectRoot();
+  const log = (msg) => process.stderr.write(`spotter db refresh: ${msg}\n`);
+  log('discovering MCP servers and built-in deferred tools...');
+  const resolved = await refresh({ projectRoot, logFn: log });
+  const counts = { local: 0, global: 0, investigated: 0 };
+  for (const { source } of resolved.values()) counts[source] = (counts[source] ?? 0) + 1;
+  process.stdout.write(
+    `${resolved.size} tool(s) resolved (local=${counts.local}, global=${counts.global}, investigated=${counts.investigated})\n`
+      + `local DB:  ${localDbPath(projectRoot)}\n`
+      + `global DB: ${globalDbPath()}\n`
+  );
+}
+
+export async function runDbRebuild() {
+  const projectRoot = requireProjectRoot();
+  // Wipe local DB so every tool's resolution falls through to global → investigate.
+  await saveDb(localDbPath(projectRoot), emptyDb());
+  process.stderr.write(`spotter db rebuild: cleared local DB, refreshing...\n`);
+  await runDbRefresh();
+}

package/src/cli/doctor.mjs

@@ -5,7 +5,8 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { loadCatalog } from '../catalog/loader.mjs';
+import { loadDb, globalDbPath, localDbPath } from '../tool-db/loader.mjs';
+import { findSpotterMarker } from '../hooks/lib.mjs';
 
 const execFileP = promisify(execFile);
 
@@ -37,23 +38,41 @@ export async function runDoctor() {
 
   // ~/.spotter directories
   const home = join(homedir(), '.spotter');
-  for (const sub of ['tool-catalog', 'runtime', 'workdir', 'logs']) {
+  for (const sub of ['runtime', 'workdir', 'logs']) {
     const path = join(home, sub);
     const ok = await exists(path);
     mark(ok, `dir ${path}`);
     if (!ok) warnings += 1;
   }
 
-  // catalog
-  const catalogPath = join(home, 'tool-catalog', 'tools.yaml');
+  // tool-db (global)
   try {
-    const cat = await loadCatalog(catalogPath);
-    mark(true, `catalog: ${cat.tools.length} tools at ${catalogPath}`);
+    const global = await loadDb(globalDbPath());
+    const count = Object.keys(global.tools).length;
+    if (count === 0) {
+      mark(false, `global tool-db: empty (run \`spotter db refresh\`)`);
+      warnings += 1;
+    } else {
+      mark(true, `global tool-db: ${count} tools at ${globalDbPath()}`);
+    }
   } catch (err) {
-    mark(false, 'catalog', err.message);
+    mark(false, 'global tool-db', err.message);
     failures += 1;
   }
 
+  // tool-db (local) if cwd is inside a Spotter project
+  const projectRoot = findSpotterMarker(process.cwd());
+  if (projectRoot) {
+    try {
+      const local = await loadDb(localDbPath(projectRoot));
+      const count = Object.keys(local.tools).length;
+      mark(true, `local tool-db: ${count} tools at ${localDbPath(projectRoot)}`);
+    } catch (err) {
+      mark(false, 'local tool-db', err.message);
+      failures += 1;
+    }
+  }
+
   console.log('');
   if (failures > 0) {
     console.log(`result: ${failures} failure(s), ${warnings} warning(s)`);

package/src/cli/install.mjs

@@ -1,12 +1,16 @@
-// `spotter install` — create ~/.spotter/, place template catalog, register hooks in .claude/settings.json.
+// `spotter install` — create ~/.spotter/, 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).
+//
+// v0.7.0: tool catalog (the old YAML) is replaced by tool-db.json (auto-discovered MCP
+// + hardcoded built-in deferred). Install no longer seeds a template — user runs
+// `spotter db refresh` after install to populate.
 
-import { mkdir, writeFile, readFile, access, copyFile } from 'node:fs/promises';
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,11 +19,9 @@ import { version as SPOTTER_VERSION } from '../version.mjs';
 
 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 MARKER_VERSION = '1';
 
@@ -42,20 +44,11 @@ export async function runInstall({ target = 'project', autoYes = false, cwd = pr
 
   // 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. project marker (v0.3): hooks use this to detect installed projects.
+  // 2. 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
@@ -103,7 +96,9 @@ export async function runInstall({ target = 'project', autoYes = false, cwd = pr
   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.');
+  console.log('\nnext steps:');
+  console.log('  1. run `spotter db refresh` to discover available MCP/deferred tools');
+  console.log('  2. reload Claude Code (or open a new session) to activate Spotter');
 }
 
 async function exists(path) {

package/src/cli/uninstall.mjs

@@ -79,7 +79,7 @@ export async function runUninstall({ target = 'project', autoYes = false, cwd =
 
   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.');
+  console.log('note: ~/.spotter/ (tool-db, logs) was not removed. delete manually if no longer needed.');
 }
 
 async function removeMarker(cwd) {

package/src/daemon/daemon.mjs

@@ -35,18 +35,21 @@ import {
   createHaikuCaller,
   HaikuError,
 } from './haiku-caller.mjs';
-import { loadCatalog } from '../catalog/loader.mjs';
+import { readMerged } from '../tool-db/refresh.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');
 const DEFAULT_HAIKU_CALL_WINDOW_MS = 10_000;
 // v0.5.0: lowered 60s → 30s. Session-scoped (--resume) means the first call still pays
 // cold-start but subsequent calls skip it. 30s covers the first-call cold path without
 // being excessive, and a role-collapse recovery cycle (reset → next call is effectively
 // a cold start again) stays within budget.
 const DEFAULT_HAIKU_TIMEOUT_MS = 30_000;
+// v0.6.2: parent-process watch interval. SessionStart hook passes the Claude Code PID;
+// the daemon polls it so it can self-terminate when Claude Code dies without firing
+// SessionEnd (crash, kill -9, IDE reload). 5s is a balance between responsiveness and
+// idle CPU cost — well below the cost of an orphan daemon staying up indefinitely.
+const DEFAULT_PARENT_WATCH_INTERVAL_MS = 5_000;
 
 export class DaemonAlreadyRunningError extends Error {
   constructor(sessionId, pid) {
@@ -59,14 +62,20 @@ export class DaemonAlreadyRunningError extends Error {
 
 export async function startDaemon({
   sessionId,
-  catalogPath = DEFAULT_CATALOG_PATH,
+  projectRoot,
+  tools,
   haikuCaller,
   logFn = () => {},
   haikuCallWindowMs = DEFAULT_HAIKU_CALL_WINDOW_MS,
+  parentPid = null,
+  parentWatchIntervalMs = DEFAULT_PARENT_WATCH_INTERVAL_MS,
 } = {}) {
   if (!sessionId) {
     throw new TypeError('sessionId is required');
   }
+  if (parentPid !== null && (!Number.isInteger(parentPid) || parentPid <= 0)) {
+    throw new TypeError('parentPid must be a positive integer or null');
+  }
 
   await ensureRuntimeDir();
 
@@ -74,14 +83,24 @@ export async function startDaemon({
   // 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}`);
+  // v0.7.0: tool list comes from tool-db (local + global merged with local-wins).
+  // For tests, the caller can pass `tools` directly. For production, projectRoot drives
+  // the load from <projectRoot>/.spotter/tool-db.json + ~/.spotter/tool-db.json.
+  let toolList;
+  if (Array.isArray(tools)) {
+    toolList = tools;
+  } else {
+    if (!projectRoot) {
+      throw new TypeError('startDaemon: either `tools` or `projectRoot` must be provided');
+    }
+    toolList = await readMerged({ projectRoot });
+  }
+  logFn(`tool-db loaded: ${toolList.length} tools` + (projectRoot ? ` (project=${projectRoot})` : ''));
 
   // v0.6.0: preamble (role + schema + catalog) is built once and threaded into the Haiku
   // caller. The caller prepends it on the first call only; --resume keeps it in session
   // history for all subsequent calls.
-  const preamble = buildPreamble({ catalog });
+  const preamble = buildPreamble({ tools: toolList });
   const callHaiku = haikuCaller ?? createHaikuCaller({ preamble, timeoutMs: DEFAULT_HAIKU_TIMEOUT_MS });
 
   // Per-turn state, reset on turn_end.
@@ -158,7 +177,7 @@ export async function startDaemon({
       case 'turn_end':
         return handleTurnEnd(envelope.payload ?? {});
       case 'shutdown':
-        setImmediate(() => shutdown(server, sessionId, logFn));
+        setImmediate(() => stop());
         return { stopping: true };
       default: {
         const err = new Error(`unknown event: ${envelope.event}`);
@@ -257,14 +276,53 @@ export async function startDaemon({
   const pidPath = pidFilePath(sessionId);
   await writeFile(pidPath, String(process.pid), 'utf8');
 
+  // v0.6.2: parent-process watch. SessionEnd is a graceful path; if Claude Code dies
+  // without it (crash, kill, IDE reload), nothing else cleans us up. Poll the parent
+  // PID and self-terminate on its disappearance.
+  let parentWatchHandle = null;
+  if (parentPid !== null) {
+    logFn(`watching parent pid=${parentPid} (interval=${parentWatchIntervalMs}ms)`);
+    parentWatchHandle = setInterval(() => {
+      if (!isProcessAlive(parentPid)) {
+        logFn(`parent pid=${parentPid} gone, shutting down`);
+        clearInterval(parentWatchHandle);
+        parentWatchHandle = null;
+        shutdown(server, sessionId, logFn).catch((err) => {
+          logFn(`parent-watch shutdown error: ${err.message}`);
+        });
+      }
+    }, parentWatchIntervalMs);
+    parentWatchHandle.unref();
+  }
+
+  const stop = async () => {
+    if (parentWatchHandle !== null) {
+      clearInterval(parentWatchHandle);
+      parentWatchHandle = null;
+    }
+    return shutdown(server, sessionId, logFn);
+  };
+
   return {
     server,
     path,
     pidPath,
-    stop: () => shutdown(server, sessionId, logFn),
+    stop,
   };
 }
 
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === 'ESRCH') return false;
+    if (err.code === 'EPERM') return true; // exists but owned by another user
+    // Unknown errno — be conservative and assume alive (don't auto-kill on transient).
+    return true;
+  }
+}
+
 async function assertNoLiveDaemon(sessionId) {
   const pidPath = pidFilePath(sessionId);
   let raw;

package/src/daemon/haiku-caller.mjs

@@ -62,12 +62,21 @@ const SHARED_HEADER = [
 // output contract, few-shot examples, and the tool catalog. The Anthropic session
 // retains this in history so subsequent --resume calls can judge with only a small
 // per-turn payload.
-export function buildPreamble({ catalog }) {
+//
+// v0.7.0: `tools` is an array of {name, description} pairs (the new tool-db format).
+// `description` is the natural-language explanation supplied by the MCP server (or the
+// hardcoded baseline for Claude Code built-in deferred tools). No schema, no usage —
+// Haiku only needs to decide whether the tool should be called; "how to call" is Bell's
+// responsibility (via ToolSearch).
+export function buildPreamble({ tools }) {
+  if (!Array.isArray(tools)) {
+    throw new TypeError('buildPreamble: tools must be an array of {name, description}');
+  }
   return [
     SHARED_HEADER,
     '',
     '## カタログ',
-    JSON.stringify(projectCatalog(catalog), null, 2),
+    JSON.stringify(tools, null, 2),
   ].join('\n');
 }
 
@@ -99,14 +108,6 @@ export function buildFinalStagePrompt({ userInput, usedTools, finalResponse }) {
   ].join('\n');
 }
 
-function projectCatalog(catalog) {
-  return catalog.tools.map((t) => ({
-    name: t.name,
-    purpose: t.purpose,
-    when_to_use: t.when_to_use,
-  }));
-}
-
 // Parse Haiku's response. Throws HaikuError on schema violation.
 export function parseHaikuResponse(raw) {
   const trimmed = raw.trim();