claude-spotter 0.13.2 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 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 は参照していないため修正が届かない、という構造問題になる。
+
+### 変更点
+
+- **編集 [src/daemon/haiku-caller.mjs](src/daemon/haiku-caller.mjs)**: `SHARED_HEADER` に「name は**カタログに列挙されたツール名そのまま**のみ許可」ルールを明記。カタログ外 (Skill(xxx) / 任意スラッシュコマンド / 記憶した既知ツール) は禁止、該当なければ pass:true
+- **編集 [src/daemon/haiku-caller.mjs](src/daemon/haiku-caller.mjs)**: `filterCatalogMisses(parsed, catalogNames)` を export。parse 後の post-filter として、`missing_tools[].name` がカタログ外のエントリを drop する。全削除なら `pass=true, reason='hallucination_filtered'` に flip、部分削除なら valid 分だけ残し `pass=false` 維持
+- **編集 [src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: `startDaemon` が tool-db ロード時に `catalogNames = new Set(toolList.map(t => t.name))` を構築、`runHaikuJudgment` で `parseHaikuResponse` 後に filter を適用。drop した name はログに残す (`dropped catalog-external names: ...`)
+- **テスト追加**: `filterCatalogMisses` の 4 ケース (passthrough / 全 drop / 部分 drop / array 形式 catalog) + preamble 文言 smoke test + daemon 統合 2 ケース (全ハルシ → pass flip / 混在 → valid 残し)
+
+### 設計判断
+
+- **prompt + filter の二重化**: prompt だけだと Haiku が従わない場合に素通りする。filter だけだと今後 preamble をいじる人が rule を外しても気付けない。両方ある方が安全
+- **pass flip のセマンティクス**: 全 drop 時に pass:false のまま空配列を返すと v0.5.x で導入した schema 整合性チェック (`pass:false かつ missing_tools 空は inconsistent`) に引っかかる。`pass:true, reason='hallucination_filtered'` が正解
+- **§0 silent fallback 禁止との関係**: これは「想定外を黙って潰す」ではなく「想定内の誤検出 = 記録 + 正常リターン」。dropped name はログに必ず残る
+
+### 残課題
+
+- v0.13.0 新軸の**カタログ内過検出** (Read 乱発 / caveat 誤爆等) は別問題。[docs/open-issues.md](docs/open-issues.md) の P0 観測タスクとして継続
+- few-shot 例の `current_time` は現 tool-db に無い名前。Haiku が cargo-cult するリスクを filter で潰したが、例そのものを実在ツールに差し替えるかは要検討 (ただし例の抽象性が失われる tradeoff あり)
+
 ## 0.13.2
 
 **Daemon の死因を必ずログに残す診断インフラ + Haiku 子プロセス stdio の防御的 error listener**。v0.13.1 までは daemon が `uncaughtException` / `unhandledRejection` で死ぬと痕跡ゼロで消えていた ([daemon-80b5c0af.log](../../.spotter/logs/daemon-80b5c0af-700f-47af-a3ac-796144823a7d.log) line 15 → line 16 で shutdown ログなしに再起動)。次に同じことが起きた時に真因を必ず捕まえられるよう、診断 handler を導入。

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.2",
+  "version": "1.0.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/daemon/daemon.mjs

@@ -38,6 +38,7 @@ import {
   buildFinalStagePrompt,
   buildPreamble,
   parseHaikuResponse,
+  filterCatalogMisses,
   createHaikuCaller,
   HaikuError,
 } from './haiku-caller.mjs';
@@ -103,6 +104,11 @@ export async function startDaemon({
   }
   logFn(`tool-db loaded: ${toolList.length} tools` + (projectRoot ? ` (project=${projectRoot})` : ''));
 
+  // v0.13.3: Haiku occasionally hallucinates tool names outside the catalog (training-memory
+  // leakage / few-shot cargo-cult). We filter these post-parse; entries not in this set are
+  // dropped. See filterCatalogMisses for the pass-flip semantics.
+  const catalogNames = new Set(toolList.map((t) => t.name));
+
   // 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.
@@ -133,8 +139,9 @@ export async function startDaemon({
   // Other Haiku errors (timeout, spawn failure) still propagate — §14 unexpected → throw.
   const runHaikuJudgment = async (stage, prompt) => {
     const { raw, meta } = await callHaikuTracked(prompt);
+    let parsed;
     try {
-      return { parsed: parseHaikuResponse(raw), meta };
+      parsed = parseHaikuResponse(raw);
     } catch (err) {
       if (err instanceof HaikuError && err.code === 'E_HAIKU_SCHEMA') {
         logFn(`${stage}: role collapse detected, session reset: ${err.message}`);
@@ -145,6 +152,11 @@ export async function startDaemon({
       }
       throw err;
     }
+    const { parsed: filtered, dropped } = filterCatalogMisses(parsed, catalogNames);
+    if (dropped.length > 0) {
+      logFn(`${stage}: dropped catalog-external names: ${dropped.join(',')}`);
+    }
+    return { parsed: filtered, meta };
   };
 
   // v0.12.0: heartbeat. Reset on every envelope; if no event arrives within

package/src/daemon/haiku-caller.mjs

@@ -51,6 +51,9 @@ const SHARED_HEADER = [
   '{"pass": <true|false>, "missing_tools": [{"name": "<カタログ名>", "reason": "<一文の日本語>"}]}',
   '- pass:true なら missing_tools は空、pass:false なら 1 件以上',
   '- JSON のみ。前置き・コードフェンス禁止',
+  '- **name は後述「## カタログ」に列挙されたツール名そのまま**のみ許可。',
+  '  カタログ外の名前 (Skill(xxx) / 任意のスラッシュコマンド / 記憶した既知ツール等) は禁止。',
+  '  該当するツールがカタログに見当たらなければ、無理に挙げず pass:true を返す。',
   '',
   '## 判定対象',
   '各ターン、以下いずれかの stage で判定リクエストを受けます:',
@@ -179,6 +182,33 @@ export function parseHaikuResponse(raw) {
   return parsed;
 }
 
+// v0.13.3: post-parse defence against catalog-external hallucinations. Haiku occasionally
+// proposes tool names that are not in the catalog — training-memory leakage or few-shot
+// cargo-culting. The SHARED_HEADER now forbids this explicitly, but we also filter
+// defensively: entries whose name is not in `catalogNames` are dropped. If all entries are
+// dropped, pass is flipped to true with reason='hallucination_filtered'. Mixed cases keep
+// the valid entries and stay pass=false.
+//
+// Returns { parsed, dropped } where `dropped` is the list of filtered-out names (for
+// observability / logging).
+export function filterCatalogMisses(parsed, catalogNames) {
+  const names = catalogNames instanceof Set ? catalogNames : new Set(catalogNames);
+  const kept = [];
+  const dropped = [];
+  for (const m of parsed.missing_tools) {
+    if (names.has(m.name)) kept.push(m);
+    else dropped.push(m.name);
+  }
+  if (dropped.length === 0) return { parsed, dropped };
+  if (kept.length === 0) {
+    return {
+      parsed: { pass: true, missing_tools: [], reason: 'hallucination_filtered' },
+      dropped,
+    };
+  }
+  return { parsed: { ...parsed, missing_tools: kept }, dropped };
+}
+
 function stripFence(text) {
   const fenceMatch = text.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
   return fenceMatch ? fenceMatch[1] : text;

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