claude-spotter 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # 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 が永久に残る問題への対処。

package/README.md

@@ -1,6 +1,6 @@
 # Spotter
 
-> **v0.6.2 released 2026-04-19**. v0.4 で stateless に回帰したが cold-start レイテンシ (毎ターン 30 秒前後の待ち) が運用で問題化したため、v0.5.0 で **session-scoped Haiku を「JSON パース失敗検知 → session renew + silent pass」の事後回復機構付き**で復活。v0.6.0 で **preamble (role + schema + catalog + few-shot) を初回のみ送信** する形 (preamble-once) に変更して `--resume` 経由の resumed 呼び出しが first より遅くなる v0.5.x の逆転現象を解消。v0.6.2 で **親プロセス (Claude Code) の死を 5 秒間隔で検知して daemon を自動 shutdown** する watch を追加し、SessionEnd が発火しない経路 (crash / kill / IDE reload) での孤児 daemon 残存を解消。詳細は [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) が**ツールを呼び忘れたとき**に指摘する監査役です。
 
@@ -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 は残す)
 ```
 

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.2",
+  "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,7 +6,7 @@ import { join } from 'node:path';
 import { open } from 'node:fs/promises';
 
 function parseArgs(argv) {
-  const out = { sessionId: null, parentPid: 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];
@@ -15,17 +15,24 @@ function parseArgs(argv) {
       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, parentPid } = 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`),
@@ -44,7 +51,8 @@ export async function runDaemonStart({ argv }) {
     // 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).
-    running = await startDaemon({ sessionId, parentPid, logFn: log });
+    // 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,12 +35,10 @@ 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
@@ -64,7 +62,8 @@ export class DaemonAlreadyRunningError extends Error {
 
 export async function startDaemon({
   sessionId,
-  catalogPath = DEFAULT_CATALOG_PATH,
+  projectRoot,
+  tools,
   haikuCaller,
   logFn = () => {},
   haikuCallWindowMs = DEFAULT_HAIKU_CALL_WINDOW_MS,
@@ -84,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.

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();

package/src/hooks/session-start.mjs

@@ -16,7 +16,7 @@ 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, isOutsideSpotterProject } from './lib.mjs';
+import { readStdinJson, requireString, die, isChildCall, isSubagentCall, isOutsideSpotterProject, findSpotterMarker } from './lib.mjs';
 import { sendRequest, TransportError } from '../daemon/transport.mjs';
 
 const READINESS_TIMEOUT_MS = 3_000;
@@ -39,8 +39,12 @@ export async function runSessionStart({ argv = process.argv, now = Date.now } =
   if (isOutsideSpotterProject(input)) return;
 
   const sessionId = requireString(input, 'session_id');
+  const projectRoot = findSpotterMarker(input.cwd);
+  if (!projectRoot) {
+    die(`SessionStart: failed to locate project root from cwd=${input.cwd}`, 2);
+  }
 
-  spawnDaemon(sessionId, argv);
+  spawnDaemon(sessionId, projectRoot, argv);
 
   const deadline = now() + READINESS_TIMEOUT_MS;
   while (now() < deadline) {
@@ -65,14 +69,20 @@ export async function runSessionStart({ argv = process.argv, now = Date.now } =
   die(`daemon did not reach readiness within ${READINESS_TIMEOUT_MS}ms for session ${sessionId}`, 2);
 }
 
-function spawnDaemon(sessionId, argv) {
+function spawnDaemon(sessionId, projectRoot, argv) {
   // Invoke `node <spotter-bin> daemon start --session-id ...` detached.
   // v0.6.2: pass --parent-pid so the daemon can self-terminate when Claude Code dies
   // without firing SessionEnd. process.ppid here is Claude Code (this hook's parent).
+  // v0.7.0: pass --project-root for tool-db loading.
   const spotterBin = resolveSpotterBin(argv);
   const child = spawn(
     process.execPath,
-    [spotterBin, 'daemon', 'start', '--session-id', sessionId, '--parent-pid', String(process.ppid)],
+    [
+      spotterBin, 'daemon', 'start',
+      '--session-id', sessionId,
+      '--parent-pid', String(process.ppid),
+      '--project-root', projectRoot,
+    ],
     {
       detached: true,
       stdio: 'ignore',

package/src/index.mjs

@@ -13,7 +13,9 @@ export {
   createHaikuCaller,
   HaikuError,
 } from './daemon/haiku-caller.mjs';
-export { loadCatalog, CatalogLoadError, CatalogSchemaError } from './catalog/loader.mjs';
-export { validateCatalog } from './catalog/schema.mjs';
-export { runLint } from './catalog/lint.mjs';
+export { loadDb, saveDb, emptyDb, ToolDbSchemaError, globalDbPath, localDbPath } from './tool-db/loader.mjs';
+export { resolveAll } from './tool-db/lookup.mjs';
+export { refresh, readMerged, buildInvestigationSnapshot } from './tool-db/refresh.mjs';
+export { listMcpServers, listMcpToolsAll, bellVisibleName, McpInvestigationError } from './tool-db/investigate-mcp.mjs';
+export { DEFERRED_TOOL_BASELINE, getDeferredDescription, listDeferredNames } from './tool-db/deferred-baseline.mjs';
 export { version } from './version.mjs';

package/src/tool-db/deferred-baseline.mjs

@@ -0,0 +1,49 @@
+// Hand-curated descriptions for Claude Code built-in deferred tools.
+//
+// Why hardcoded: Claude Code's built-in tools cannot be queried introspectively from a
+// daemon process (they're internal to the Claude binary, not exposed via MCP). The list
+// is small and stable; we maintain it here and update on Claude Code releases.
+//
+// `spotter db refresh` merges this baseline into the global DB. Users can override
+// per-project by editing their local DB (per docs/catalog-design-deferred-mcp.md).
+
+export const DEFERRED_TOOL_BASELINE = {
+  // Reasoning / dialogue
+  'AskUserQuestion': 'Ask the user a clarifying question with multi-choice or free-text answer when requirements are ambiguous; preferable to guessing.',
+  'TodoWrite': 'Create or update a structured task list to plan and track multi-step work; surfaces progress to the user and to future turns.',
+  'EnterPlanMode': 'Enter Plan Mode: Claude proposes a plan first and waits for user approval before doing the work.',
+  'ExitPlanMode': 'Exit Plan Mode after the user has approved the proposed plan.',
+
+  // Web access
+  'WebSearch': 'Search the web for up-to-date information (news, prices, releases, events that postdate training).',
+  'WebFetch': 'Fetch the contents of a specific URL to read its body (HTML/Markdown/JSON), e.g. when the user pastes a link.',
+
+  // Notebook
+  'NotebookEdit': 'Edit cells in a Jupyter notebook (.ipynb) — insert, replace, or delete cells.',
+
+  // Worktree / isolated execution
+  'EnterWorktree': 'Create a temporary git worktree to isolate experimental edits from the main checkout.',
+  'ExitWorktree': 'Tear down a previously-created worktree.',
+
+  // Background processes / monitoring
+  'Monitor': 'Stream events from a long-running background process; receives a notification per stdout line.',
+  'PushNotification': 'Send a push notification to the user (e.g. on long task completion).',
+
+  // Scheduling / cron
+  'CronCreate': 'Schedule a recurring agent (cron-style trigger) that runs Claude Code on an interval.',
+  'CronDelete': 'Delete a scheduled cron trigger by id.',
+  'CronList': 'List all currently configured cron triggers.',
+  'RemoteTrigger': 'Create or run a remote trigger (one-shot or recurring scheduled agent).',
+
+  // Sub-agent / task control
+  'TaskOutput': 'Read the latest output from a running background sub-agent.',
+  'TaskStop': 'Stop a running background sub-agent.',
+};
+
+export function getDeferredDescription(name) {
+  return DEFERRED_TOOL_BASELINE[name] ?? null;
+}
+
+export function listDeferredNames() {
+  return Object.keys(DEFERRED_TOOL_BASELINE);
+}