claude-spotter 0.13.3 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 1.1.0
+
+**`spotter install` が tool-db を自動構築 + SessionStart hook がバックグラウンド refresh**。install 直後から audit 対象が揃うようになり、以降の session でも MCP / スキル / サブエージェントの追加・削除が自動追従する。
+
+### 背景
+
+v1.0.0 以前は `spotter install` が hook 登録だけで tool-db を作らず、別途 `spotter db refresh` を手動実行する必要があった。初回セッションで daemon が空 DB を掴むと Haiku に preamble が届かず audit が機能しない状態で起動してしまう。また、install 後に MCP や スキルを追加しても rebuild/refresh を手動で叩くまで視野に入らず、drift が常に発生していた。
+
+### 変更点
+
+- **編集 [src/cli/install.mjs](src/cli/install.mjs)**: settings.json 書き込み後に project-mode で `refresh({projectRoot})` を同期実行し tool-db を seed。失敗時は §0 準拠で throw (hook だけ登録されて DB が無い中途半端な状態を残さない)。`skipRefresh` オプションを新設 (既存テストが user 環境をスキャンしないように)。"next steps" メッセージから `spotter db refresh` の手動実行指示を削除
+- **編集 [src/hooks/session-start.mjs](src/hooks/session-start.mjs)**: daemon readiness 確立後に `spawnRefreshDetached({projectRoot})` を発火。hook 自体は即 return、refresh は detached child として bg 実行。**現セッションの daemon は起動時の tool-db で固定**のため反映は次セッション以降
+- **編集 [src/hooks/spawn-daemon.mjs](src/hooks/spawn-daemon.mjs)**: `spawnRefreshDetached` を追加 export。`node <spotterBin> db refresh` を `detached: true, stdio: 'ignore', unref()` で起動、hook を遅延させない
+- **テスト更新 [test/install.test.mjs](test/install.test.mjs)**: 全 6 件が `skipRefresh: true` を渡すよう更新
+
+### 設計判断
+
+- **rebuild ではなく refresh を採用**: 当初 user 指示は rebuild (local+global wipe + 全再スキャン) だったが、(1) 既適用プロジェクトの global キャッシュを毎 SessionStart で破壊するのは副作用が大きい、(2) 並列セッション (Project A rebuild 中に Project B SessionStart) で書き込み競合が発生する、の 2 点から refresh に変更。差分更新でも新規・削除の drift 追従は効く。description drift (同一名の description 更新) のみ取りこぼすが、これは `spotter db rebuild` の手動実行でカバー
+- **SessionStart の refresh は bg detached**: session-start hook の timeout は 5s で、MCP 全サーバー spawn + skills 181 件スキャンは秒単位かかるため同期実行は不可能。detached + unref で hook を遅延させない代わりに、反映は次セッション以降 (現セッションの daemon は既に古い tool-db をロード済みで、実行中の差し替えはしない)
+- **install 時の refresh 失敗は throw**: "hook 登録済みだが DB なし" という中途半端な状態を残すくらいなら install 自体を失敗扱いにするほうがクリーン。再試行は `spotter install` の再実行で、hook 登録は `nothing to change` で skip され refresh だけ走る
+
+### 破壊変更
+
+なし (skipRefresh オプションはデフォルト false で既存挙動より機能追加、CLI 利用者には透過)。
+
+### 影響範囲
+
+- 新規 `spotter install` 実行時は MCP/skills/agents の discover でセットアップ時間が数秒〜10 秒増える
+- 毎 SessionStart でバックグラウンド `spotter db refresh` プロセスが 1 つ発火 (bg unref なので UX 影響なし)
+- global tool-db への書き込みが session 起動ごとに発生 (atomic write なので corruption リスクなし、last-write-wins の並列 race は idempotent なので次 refresh で収束)
+
+## 1.0.0
+
+**監査対象をユーザー追加分 (MCP / スキル / サブエージェント) に絞り込み**。Claude Code 本体が提供するツール (即時 + 遅延) は監査カタログから全面除外。設計転換の major bump。
+
+### 背景
+
+v0.13.x までは「Claude Code 組込みの遅延ツール (WebSearch / TodoWrite 等 17 件) は Bell が呼び忘れやすい」という仮定で手書き baseline を保持していた。今回の設計会議で 2 点が判明し、前提自体を撤回:
+
+1. **Bell は本体側ツールを使いこなしている**。WebSearch / WebFetch / NotebookEdit / Cron 系 / Worktree / 通知は自発率が十分高く、Spotter が提案すべき呼び忘れ対象ではない
+2. **即時 / 遅延の境界は Claude Code バージョンで動的に変わる**。現セッションの実測で、`AskUserQuestion` / `TodoWrite` / `EnterPlanMode` / `ExitPlanMode` / `TaskOutput` / `TaskStop` は baseline に「遅延」と書かれているが実際には **即時ツール**として扱われていた。手書き baseline は構造的に drift するので追従は不可能
+
+Spotter の役割は「Bell にとって**言われないと思い出さない** MCP / スキル / サブエージェントを視野に入れさせる」こと。本体側は Bell の手中にある。
+
+### 変更点
+
+- **削除 [src/tool-db/deferred-baseline.mjs](src/tool-db/deferred-baseline.mjs)**: 手書き 17 件の baseline を撤去。`DEFERRED_TOOL_BASELINE` / `getDeferredDescription` / `listDeferredNames` の export も削除 (破壊変更)
+- **新規 [src/tool-db/frontmatter.mjs](src/tool-db/frontmatter.mjs)**: SKILL.md / agent .md の YAML frontmatter から `name` + `description` を抽出する最小パーサー (ゼロ依存)
+- **新規 [src/tool-db/investigate-skills.mjs](src/tool-db/investigate-skills.mjs)**: スキルを 3 scope (user / project / 有効化プラグイン) から収集。プラグイン由来は `<plugin>:<skill>` に名前空間化、ユーザー / プロジェクト由来は素の名前。`enabledPlugins` の有効化判定は user scope + project scope の union、`~/.claude/plugins/installed_plugins.json` の `installPath` から実体にアクセス
+- **新規 [src/tool-db/investigate-agents.mjs](src/tool-db/investigate-agents.mjs)**: サブエージェントを同じく 3 scope から収集。名前は素の名前、衝突は project > user > plugin の優先順で解決
+- **編集 [src/tool-db/refresh.mjs](src/tool-db/refresh.mjs)**: `buildInvestigationSnapshot` から deferred 経路を削除、スキル / サブエージェント経路を追加。MCP live fetch + `claude.ai` baseline (Gmail / Calendar / Drive) は維持
+- **編集 [src/cli/db-cmd.mjs](src/cli/db-cmd.mjs)**: `spotter db rebuild` が local DB に加えて **global DB も wipe** するように仕様変更。旧バージョンから上がってきたユーザーが古い deferred エントリを抱えたままにならないため
+- **編集 [src/index.mjs](src/index.mjs)**: `listSkillsAll` / `listActivePlugins` / `listAgentsAll` の export 追加
+- **リネーム [docs/catalog-design-deferred-mcp.md](docs/catalog-design.md) → [docs/catalog-design.md](docs/catalog-design.md)**: 大幅書き直し。対象範囲・分類軸・収集経路を v1.0.0 仕様で更新
+- **テスト更新 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: deferred baseline テスト 3 件削除、frontmatter テスト 3 件 + skill テスト 2 件 + agent テスト 2 件を追加。計 32 件全通過
+
+### 結果
+
+本プロジェクトで `buildInvestigationSnapshot` を走らせると **268 件 resolved**:
+
+- MCP: 40 件 (caveat 6 + claude.ai Gmail/Calendar/Drive 25 + x-api 9)
+- スキル (名前空間付き): 181 件 (ECC が大半)
+- サブエージェント + bare スキル: 47 件 (ECC 38 agents + 他)
+
+preamble 初回送信サイズ推定 15-25K tokens (Haiku 4.5 の 200K コンテキストに対し 12% 程度)。v0.6.0 preamble-once で 2 回目以降は per-turn delta のみ、セッション 1 回あたりの追加コストは初回のみ。
+
+### 設計判断
+
+- **ECC プラグインの全スキル (181 件) をそのまま投入**: 「使う可能性があるなら視野に入れる」が Spotter の本旨。description の semantic 判定は Haiku に任せる (preamble 肥大より recall 優先)
+- **learned/ などの空ディレクトリは silent に素通り**: SKILL.md が無ければスキルではない、ENOENT だけログを抑制
+- **名前衝突の解決**: スキルは `<plugin>:<name>` で namespace 分離されるので衝突せず。サブエージェントは bare name なので project > user > plugin 優先で Map 上書き
+- **破壊変更を major bump で明示**: カタログ契約が変わる + 公開 export 削除 + db rebuild 仕様変更、の 3 点で semver major
+
+### 残課題
+
+- **初回 Haiku latency の観測**: 268 件 preamble で `duration_ms` が 45s timeout に接近しないか実運用で確認。超えるようなら再緩和か件数絞り込みを再検討
+- **baseline 自動追従機構**: `claude.ai` MCP baseline は手書きのまま。Claude 側で追加があっても検知できない。長期的には監視機構が必要 ([docs/open-issues.md](docs/open-issues.md) P1 継続)
+- **v0.13.0 新軸の過検出**: turn_end 軸 (ツール適用機会監査) の誤爆パターンは別問題、継続観測
+
 ## 0.13.3
 
 **カタログ外ツール名の推奨を遮断 (prompt 明示 + 事後 filter の二重防御)**。v0.13.2 リリース直後の実セッション ([daemon-f047521c.log](../../.spotter/logs/daemon-f047521c-9cce-4822-9555-90b206b8341e.log) line 9) で `turn_end: pass=false, missing=Skill(tl)` を観測。**`Skill(tl)` はカタログ (tool-db.json 57 件) に存在しない**。Haiku が training 記憶 or few-shot の `current_time` / `Skill` 表記から cargo-cult してカタログ外名を提案していた。これが恒常化するとユーザーが無効な推奨に混乱する + /tl など description を直しても Haiku は参照していないため修正が届かない、という構造問題になる。

package/README.md

@@ -1,6 +1,6 @@
 # Spotter
 
-> **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)。
+> **v1.0.0 released 2026-04-20**. **監査対象をユーザー追加分 (MCP / スキル / サブエージェント) に絞り込み**。Claude Code 本体が提供するツールは監査から外す — Bell は本体側を使いこなしており呼び忘れ率が低い、また即時 / 遅延の境界がバージョンで動的に変わり手書き baseline が追従できない、の 2 点による設計転換。新規にスキル (SKILL.md frontmatter) とサブエージェント (.md frontmatter) の自動収集を追加、ECC プラグイン有効化状態から 181 skills + 38 agents を live 取得。設計思想は [docs/catalog-design.md](docs/catalog-design.md)、変更詳細は [CHANGELOG](CHANGELOG.md)。
 
 **気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
 

package/package.json

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

package/src/cli/db-cmd.mjs

@@ -35,7 +35,7 @@ export async function runDbList() {
 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...');
+  log('discovering MCP servers, skills, and sub-agents...');
   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;
@@ -48,8 +48,12 @@ export async function runDbRefresh() {
 
 export async function runDbRebuild() {
   const projectRoot = requireProjectRoot();
-  // Wipe local DB so every tool's resolution falls through to global → investigate.
+  // v1.0.0: wipe BOTH local and global DB. Rationale: the catalog scope changed in
+  // v1.0.0 (Claude Code built-ins removed; skills + sub-agents added). Stale entries
+  // from older versions would otherwise linger in the global DB since `refresh` only
+  // touches names currently produced by investigation. Users need a clean slate.
   await saveDb(localDbPath(projectRoot), emptyDb());
-  process.stderr.write(`spotter db rebuild: cleared local DB, refreshing...\n`);
+  await saveDb(globalDbPath(), emptyDb());
+  process.stderr.write(`spotter db rebuild: cleared local + global DB, refreshing...\n`);
   await runDbRefresh();
 }

package/src/cli/install.mjs

@@ -7,8 +7,9 @@
 // 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.
+// servers, skills, sub-agents — see docs/catalog-design.md for v1.0.0 scope).
+// Install seeds the DB automatically via `refresh` (project-mode only — user-mode
+// has no projectRoot so DB seeding is skipped there).
 
 import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -16,6 +17,8 @@ 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';
+import { refresh } from '../tool-db/refresh.mjs';
+import { localDbPath, globalDbPath } from '../tool-db/loader.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
@@ -33,7 +36,7 @@ const HOOK_EVENTS = [
   { event: 'SessionEnd', sub: 'session-end', timeout: 3 },
 ];
 
-export async function runInstall({ target = 'project', autoYes = false, cwd = process.cwd() } = {}) {
+export async function runInstall({ target = 'project', autoYes = false, cwd = process.cwd(), skipRefresh = false } = {}) {
   const settingsPath = target === 'user'
     ? join(homedir(), '.claude', 'settings.json')
     : join(cwd, '.claude', 'settings.json');
@@ -96,9 +99,21 @@ 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}`);
+
+  // Seed the tool-db so the first session has something to audit against.
+  // Skipped for user-mode (deprecated — no projectRoot) and when caller opts out
+  // (tests set skipRefresh=true to avoid scanning the real user environment).
+  if (target === 'project' && !skipRefresh) {
+    console.log('\ndiscovering MCP servers, skills, and sub-agents...');
+    const log = (msg) => process.stderr.write(`  ${msg}\n`);
+    const resolved = await refresh({ projectRoot: cwd, logFn: log });
+    console.log(`  ${resolved.size} tool(s) resolved`);
+    console.log(`  local DB:  ${localDbPath(cwd)}`);
+    console.log(`  global DB: ${globalDbPath()}`);
+  }
+
   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');
+  console.log('  reload Claude Code (or open a new session) to activate Spotter');
 }
 
 async function exists(path) {

package/src/hooks/session-start.mjs

@@ -17,7 +17,7 @@
 // now heartbeat-based inside the daemon.
 
 import { readStdinJson, requireString, die, isChildCall, isSubagentCall, isOutsideSpotterProject, findSpotterMarker } from './lib.mjs';
-import { spawnDaemonAndWaitReady } from './spawn-daemon.mjs';
+import { spawnDaemonAndWaitReady, spawnRefreshDetached } from './spawn-daemon.mjs';
 
 export async function runSessionStart({ now = Date.now } = {}) {
   if (isChildCall()) return;
@@ -35,6 +35,7 @@ export async function runSessionStart({ now = Date.now } = {}) {
   }
 
   await spawnDaemonAndWaitReady({ sessionId, projectRoot, now });
+  spawnRefreshDetached({ projectRoot });
 }
 
 if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {

package/src/hooks/spawn-daemon.mjs

@@ -66,6 +66,27 @@ function spawnDaemon(sessionId, projectRoot) {
   child.unref();
 }
 
+// Fire-and-forget `spotter db refresh`. The daemon in THIS session already loaded the
+// pre-refresh tool-db, so any updates land in time for the NEXT session. Detached so
+// the hook doesn't wait for MCP/skill/agent discovery to finish.
+export function spawnRefreshDetached({ projectRoot }) {
+  const spotterBin = resolveSpotterBin();
+  const child = spawn(
+    process.execPath,
+    [spotterBin, 'db', 'refresh'],
+    {
+      cwd: projectRoot,
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    }
+  );
+  child.on('error', (err) => {
+    process.stderr.write(`spotter-hook: refresh spawn error: ${err.message}\n`);
+  });
+  child.unref();
+}
+
 function resolveSpotterBin() {
   const here = dirname(fileURLToPath(import.meta.url));
   return resolve(here, '..', '..', 'bin', 'spotter.mjs');

package/src/index.mjs

@@ -17,5 +17,6 @@ export { loadDb, saveDb, emptyDb, ToolDbSchemaError, globalDbPath, localDbPath }
 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 { listSkillsAll, listActivePlugins } from './tool-db/investigate-skills.mjs';
+export { listAgentsAll } from './tool-db/investigate-agents.mjs';
 export { version } from './version.mjs';

package/src/tool-db/frontmatter.mjs

@@ -0,0 +1,45 @@
+// Minimal YAML frontmatter parser for Claude Code skill / agent `.md` files.
+//
+// We only need to read top-level scalar string fields (`name`, `description`). No nesting,
+// no arrays, no multi-line strings. Anything more complex is ignored safely. Zero deps by
+// design — the Spotter project goal forbids a YAML library for this small need.
+//
+// Supported input:
+//   ---
+//   name: council
+//   description: Convene a four-voice council ...
+//   origin: ECC
+//   ---
+//   <body...>
+//
+// Returns an object of frontmatter fields; unparseable / absent frontmatter → {}.
+
+import { readFile } from 'node:fs/promises';
+
+const FENCE = '---';
+
+export async function readFrontmatter(path) {
+  const text = await readFile(path, 'utf8');
+  return parseFrontmatter(text);
+}
+
+export function parseFrontmatter(text) {
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== FENCE) return {};
+  const out = {};
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === FENCE) break;
+    const colonIdx = line.indexOf(':');
+    if (colonIdx <= 0) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    if (value.length === 0) continue;
+    // Strip surrounding quotes if present.
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}

package/src/tool-db/investigate-agents.mjs

@@ -0,0 +1,75 @@
+// Sub-agent investigation: collect agents from user scope, project scope, and enabled
+// plugins.
+//
+// Agent file layout (per Claude Code convention):
+//   <root>/agents/<agent-name>.md         (single .md with frontmatter)
+// where <root> is:
+//   - user scope   : ~/.claude
+//   - project scope: <projectRoot>/.claude
+//   - plugin scope : <installPath>
+//
+// Bell-visible name: just `<agent-name>` — sub-agents are NOT namespaced the way skills
+// are. Name collisions (e.g. both ECC and a user dotfile defining `code-reviewer`) are
+// resolved by precedence: project > user > plugin. Later writes to the Map override.
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readFrontmatter } from './frontmatter.mjs';
+import { listActivePlugins } from './investigate-skills.mjs';
+
+export async function listAgentsAll({ logFn = () => {}, projectRoot } = {}) {
+  const out = new Map(); // Bell-visible name → description
+
+  // Plugin scope first (lowest precedence)
+  const plugins = await listActivePlugins({ projectRoot, logFn });
+  for (const plugin of plugins) {
+    const pluginAgents = await scanAgentsDir(join(plugin.installPath, 'agents'), logFn);
+    for (const [name, description] of pluginAgents) {
+      out.set(name, description);
+    }
+  }
+
+  // User scope (overrides plugin)
+  const userAgents = await scanAgentsDir(join(homedir(), '.claude', 'agents'), logFn);
+  for (const [name, description] of userAgents) {
+    out.set(name, description);
+  }
+
+  // Project scope (highest precedence)
+  if (projectRoot) {
+    const projectAgents = await scanAgentsDir(join(projectRoot, '.claude', 'agents'), logFn);
+    for (const [name, description] of projectAgents) {
+      out.set(name, description);
+    }
+  }
+
+  return out;
+}
+
+// Scan `<dir>/<name>.md` files. Returns Map<agent-name, description>. Missing directories
+// or malformed agents are skipped silently.
+async function scanAgentsDir(dir, logFn) {
+  const out = new Map();
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    const agentFile = join(dir, entry.name);
+    try {
+      const fm = await readFrontmatter(agentFile);
+      const name = fm.name ?? entry.name.replace(/\.md$/, '');
+      const description = fm.description;
+      if (typeof description !== 'string' || description.length === 0) continue;
+      out.set(name, description);
+    } catch (err) {
+      logFn(`agent read failed at ${agentFile}: ${err.message}`);
+    }
+  }
+  return out;
+}

package/src/tool-db/investigate-skills.mjs

@@ -0,0 +1,129 @@
+// Skill investigation: collect skills from user scope, project scope, and enabled plugins.
+//
+// Skill file layout (per Claude Code convention):
+//   <root>/skills/<skill-name>/SKILL.md
+// where <root> is:
+//   - user scope   : ~/.claude
+//   - project scope: <projectRoot>/.claude
+//   - plugin scope : <installPath> (from ~/.claude/plugins/installed_plugins.json)
+//
+// Bell-visible name:
+//   - plugin-provided : `<plugin-prefix>:<skill-name>`   (e.g. `ecc:council`)
+//   - user / project  : `<skill-name>`                   (e.g. `council`)
+//
+// Plugin prefix is the part before `@` in the plugin id (`ecc@ecc` → `ecc`).
+//
+// Plugins are considered active if either user-scope `~/.claude/settings.json` or
+// project-scope `<projectRoot>/.claude/settings.local.json` sets
+// `enabledPlugins[<plugin-id>] = true`, AND the plugin is listed in
+// `~/.claude/plugins/installed_plugins.json`.
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readFrontmatter } from './frontmatter.mjs';
+
+export async function listSkillsAll({ logFn = () => {}, projectRoot } = {}) {
+  const out = new Map(); // Bell-visible name → description
+
+  // Plugin scope
+  const plugins = await listActivePlugins({ projectRoot, logFn });
+  for (const plugin of plugins) {
+    const pluginSkills = await scanSkillsDir(join(plugin.installPath, 'skills'), logFn);
+    for (const [skillName, description] of pluginSkills) {
+      out.set(`${plugin.prefix}:${skillName}`, description);
+    }
+  }
+
+  // User scope (override plugin-same-name? No — plugin-namespaced names never collide
+  // with bare names, so no resolution needed.)
+  const userSkills = await scanSkillsDir(join(homedir(), '.claude', 'skills'), logFn);
+  for (const [skillName, description] of userSkills) {
+    out.set(skillName, description);
+  }
+
+  // Project scope (overrides user-scope with the same bare name)
+  if (projectRoot) {
+    const projectSkills = await scanSkillsDir(join(projectRoot, '.claude', 'skills'), logFn);
+    for (const [skillName, description] of projectSkills) {
+      out.set(skillName, description);
+    }
+  }
+
+  return out;
+}
+
+// Scan `<dir>/<name>/SKILL.md` files. Returns Map<skill-name, description>. Missing
+// directories or malformed skills are skipped silently.
+async function scanSkillsDir(dir, logFn) {
+  const out = new Map();
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = join(dir, entry.name, 'SKILL.md');
+    try {
+      const fm = await readFrontmatter(skillFile);
+      const name = fm.name ?? entry.name;
+      const description = fm.description;
+      if (typeof description !== 'string' || description.length === 0) continue;
+      out.set(name, description);
+    } catch (err) {
+      // Directory without SKILL.md (e.g. `skills/learned/` placeholder) is normal —
+      // it simply isn't a skill. Only report unexpected errors.
+      if (err.code !== 'ENOENT') {
+        logFn(`skill read failed at ${skillFile}: ${err.message}`);
+      }
+    }
+  }
+  return out;
+}
+
+// Return the list of plugins that are (a) installed and (b) enabled in user or project
+// scope. Each entry: {id, prefix, installPath}.
+export async function listActivePlugins({ projectRoot, logFn = () => {} } = {}) {
+  const [installed, userEnabled, projectEnabled] = await Promise.all([
+    readInstalledPlugins(logFn),
+    readEnabledPlugins(join(homedir(), '.claude', 'settings.json')),
+    projectRoot
+      ? readEnabledPlugins(join(projectRoot, '.claude', 'settings.local.json'))
+      : Promise.resolve({}),
+  ]);
+
+  const out = [];
+  for (const [id, entries] of Object.entries(installed)) {
+    const isEnabled = userEnabled[id] === true || projectEnabled[id] === true;
+    if (!isEnabled) continue;
+    const entry = entries?.[0];
+    if (!entry?.installPath) continue;
+    const prefix = id.split('@')[0];
+    out.push({ id, prefix, installPath: entry.installPath });
+  }
+  return out;
+}
+
+async function readInstalledPlugins(logFn) {
+  const path = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
+  try {
+    const text = await readFile(path, 'utf8');
+    const parsed = JSON.parse(text);
+    return parsed.plugins ?? {};
+  } catch (err) {
+    logFn(`installed_plugins.json read failed: ${err.message}`);
+    return {};
+  }
+}
+
+async function readEnabledPlugins(settingsPath) {
+  try {
+    const text = await readFile(settingsPath, 'utf8');
+    const parsed = JSON.parse(text);
+    return parsed.enabledPlugins ?? {};
+  } catch {
+    return {};
+  }
+}

package/src/tool-db/lookup.mjs

@@ -1,6 +1,6 @@
 // tool-db: 3-tier lookup with write-through and drift correction.
 //
-// Per docs/catalog-design-deferred-mcp.md:
+// Per docs/catalog-design.md:
 //   1. local DB hit       → use it
 //   2. local miss, global hit → use it AND write-through to local
 //   3. both miss          → investigate, write to BOTH

package/src/tool-db/refresh.mjs

@@ -1,30 +1,32 @@
 // Discover available tools and ensure the tool-db has descriptions for all of them.
 //
-// Flow per docs/catalog-design-deferred-mcp.md:
-//   1. enumerate available tool names (MCP server tools + deferred Claude Code built-ins)
+// Flow per docs/catalog-design.md:
+//   1. enumerate available tool names (MCP + skills + sub-agents, user-addable only)
 //   2. for each, look up local → global → investigate (write-through; drift-correct)
 //   3. write back any updates atomically
+//
+// v1.0.0: Claude Code built-in tools (both immediate and deferred) are no longer in the
+// catalog. The working assumption is Bell uses built-ins fluently without reminding.
+// Spotter's audit surface is the tools the user actively adds: MCP servers, skills, and
+// sub-agents.
 
 import { resolveAll } from './lookup.mjs';
 import { listMcpToolsAll, bellVisibleName } from './investigate-mcp.mjs';
-import { getDeferredDescription, listDeferredNames } from './deferred-baseline.mjs';
 import { getClaudeAiDescription, listClaudeAiNames } from './claude-ai-baseline.mjs';
+import { listSkillsAll } from './investigate-skills.mjs';
+import { listAgentsAll } from './investigate-agents.mjs';
 import { localDbPath, globalDbPath } from './loader.mjs';
 
-// Build the (name → description) map for an investigation pass:
-// - MCP: from `claude mcp list` + per-server `tools/list`, names rewritten to
-//   `mcp__<server-id>__<tool-name>` (Bell-visible form)
-// - Deferred: from the hardcoded baseline
+// Build the (name → description) map for an investigation pass across all sources:
+//   - claude.ai MCP baseline (Gmail / Calendar / Drive — OAuth, not locally introspectable)
+//   - MCP servers via stdio + HTTP/SSE (user + project .mcp.json, live fetched)
+//   - Skills from user scope, project scope, and enabled plugins
+//   - Sub-agents from user scope, project scope, and enabled plugins
 //
 // Returns an in-memory snapshot the caller can use as the investigate() backend.
 export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin = 'claude', projectRoot } = {}) {
   const snapshot = new Map();
 
-  // Deferred built-ins (Claude Code deferred tools like WebFetch, TodoWrite, etc.).
-  for (const name of listDeferredNames()) {
-    snapshot.set(name, getDeferredDescription(name));
-  }
-
   // Anthropic-provided `claude.ai ...` MCP servers — hardcoded because the OAuth proxy
   // is not reachable without reading ~/.claude/.credentials.json (deliberately avoided).
   // If a live HTTP investigate for the same name later succeeds below, it overrides.
@@ -42,6 +44,18 @@ export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin =
     }
   }
 
+  // Skills (plugin-namespaced as `<plugin>:<name>`, or bare for user/project scope).
+  const skills = await listSkillsAll({ logFn, projectRoot });
+  for (const [name, description] of skills) {
+    snapshot.set(name, description);
+  }
+
+  // Sub-agents (bare name; project > user > plugin precedence resolved internally).
+  const agents = await listAgentsAll({ logFn, projectRoot });
+  for (const [name, description] of agents) {
+    snapshot.set(name, description);
+  }
+
   return snapshot;
 }
 

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

@@ -1,49 +0,0 @@
-// 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);
-}