claude-spotter 1.1.6 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.2.0
+
+**当該プロジェクトで使えないツールが提案される回帰を構造的に修正**。daemon が監査に使うカタログを **ローカル DB のみ** に変更し、グローバル DB は他プロジェクトでの description 再利用のためのキャッシュ層に役割を限定。同時に `resolveAll` で「現プロジェクトの discovery 結果に含まれないローカルエントリ」を prune するよう変更し、過去にインストールされていた MCP / スキル / サブエージェントが local に居座って Haiku 視野に残る経路を塞いだ。
+
+### 変更点
+
+- **編集 [src/tool-db/refresh.mjs](src/tool-db/refresh.mjs)**: `readMerged` を `readLocal` にリネーム + 実装を local DB 限定に変更。global DB を一切混ぜない。コメントで「他プロジェクトの幻ツール混入」が起きていた経路を明示
+- **編集 [src/tool-db/lookup.mjs](src/tool-db/lookup.mjs)**: `resolveAll` 末尾に prune ループ追加。`toolNames` (現プロジェクトの discovery 結果) に含まれない既存ローカルエントリを削除。investigate が null を返した (transient failure) ツールは toolNames に含まれている限り既存値を保持して prune しない (auth / network / quota の一過性失敗で audit 範囲を縮めない防御)
+- **編集 [src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: tool-db 読み込みを `readLocal` に切り替え、コメントで設計意図を明記
+- **編集 [src/cli/db-cmd.mjs](src/cli/db-cmd.mjs)**: `spotter db list` も local DB 限定に変更 (daemon と表示の整合)
+- **編集 [src/index.mjs](src/index.mjs)**: 公開 export を `readMerged` → `readLocal` にリネーム (programmatic API の破壊変更 = minor bump)
+- **編集 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: 回帰テスト 3 件追加 — (1) prune 挙動 (snapshot に無いツールは local から消える、global は append-only で残る)、(2) investigate 失敗時の保持 (toolNames に含まれている限り既存値を残す)、(3) `readLocal` 単独動作 (global DB の中身が leak しない)
+
+### 背景
+
+#### 何が起きていたか
+
+`readMerged` は `{ ...global.tools, ...local.tools }` で local-wins マージしたツール一覧を daemon の preamble (Haiku のカタログ) に渡していた。local に**ない**が global に**ある**ツール (= 過去の別プロジェクトで discover したが現プロジェクトでは未インストール) が Haiku 視野に入り、Haiku が「Gmail の検索を提案」「別プロジェクトの skill を推奨」等を出す症状を生んでいた。
+
+加えて `resolveAll` は snapshot ベースで write-through するだけで、過去 discover されて local に残った後に削除された MCP / skill / agent を local DB から取り除く機構が無かった。両者が組み合わさって「一度 local に書き込まれた幽霊が居座り続ける」状態が定着していた。
+
+#### なぜ global DB は残すか
+
+global DB を廃止せず「他プロジェクト用キャッシュ」に格下げした理由: 同じ MCP サーバー / 同じスキル / 同じサブエージェントを別プロジェクトでも使うとき、global にヒットすれば live fetch (MCP の `tools/list` JSON-RPC、frontmatter パース) を skip できる。`resolveAll` の 3-tier (local → global → investigate) フローはそのために残し、daemon の audit 入力からだけ global を切り離した。
+
+#### 自動追従の経路
+
+既に Spotter を導入済みのプロジェクトは npm の global update 後、次の Claude Code SessionStart で v1.1.0 機構の `spawnRefreshDetached` が走り、その refresh が prune ループ入りの `resolveAll` を実行する。**次の次のセッション**から幽霊が消えた状態で daemon が起動する (detached の仕様)。即時反映したい場合は `spotter db refresh` を手動実行する逃げ道は既存。
+
+### 設計判断
+
+- **global を完全廃止しなかった**: live fetch コストが軽くないため (MCP stdio spawn 数百ミリ秒〜秒、HTTP MCP も auth 込みでそれ以上)、初回 refresh の体感を損ねない
+- **prune を `resolveAll` 末尾に置いた理由**: snapshot 構築 (buildInvestigationSnapshot) と prune を別関数に分けると「snapshot に基づいて local を upsert する」契約が複数箇所に散る。Single source of truth として `resolveAll` 内で完結させた
+- **investigate failure 時の prune skip**: live fetch が失敗したからといって audit 範囲を縮めると、auth が一時的に通らない / MCP サーバーが一時的に応答しない場合に Haiku 視野が穴だらけになる。toolNames (= 現プロジェクトに**実在する**サーバー / skill / agent の name 一覧) に含まれているなら local の既存 description を保持し、次回成功時に上書きする方が頑健
+- **public API の minor bump**: `readMerged` → `readLocal` は import 名の変更を含むので破壊変更扱い。programmatic に Spotter を埋め込んでいる第三者が居る前提 (内部利用想定でも安全側に倒す)
+
 ## 1.1.6
 
 **Bell の isolated `CLAUDE_CONFIG_DIR` が Spotter haiku の auth を破壊する bug を修正**。bellbot 等で CLAUDE_CONFIG_DIR を分離する運用 (user scope MCP を流入させない隔離設計、credentials 非共有) のとき、hook → daemon → haiku の spawn 連鎖で Bell の isolated config が継承され、Spotter haiku が credentials 不在の config を読みに行き exit 1。その後同じ session-id が claude CLI 側で "already in use" と判定されて失敗が固定化し、user_input hook が非 0 exit し続けてベル本体のプロンプト処理が破綻していた。

package/README.md

@@ -1,6 +1,6 @@
 # Spotter
 
-> **v1.1.4 released 2026-04-20**. **MCP 投資経路の 2 件の silent mismatch を修正**。(1) `claude mcp list / get` spawn 時の `cwd: projectRoot` 未指定、(2) claude.ai baseline (Gmail/Calendar/Drive 25 件) の無条件注入 — `claude mcp list` の実在確認を入れ、隔離 `CLAUDE_CONFIG_DIR` / 未連携環境で最大 25 件の幻ツールが catalog に残っていた状態を解消 (Bell 側実環境で 25 件消失を実測確認済み)。v1.1.0 からの柱 (install 時 tool-db 自動構築 + SessionStart での drift 自動追従) は継続、手動 `spotter db refresh` は通常不要。監査対象は v1.0.0 でユーザー追加分 (MCP / スキル / サブエージェント) に絞り込み済み、本プロジェクトでの実測で 268 件 resolved (MCP 40 + skills 181 + agents/bare 47)。設計思想は [docs/catalog-design.md](docs/catalog-design.md)、変更詳細は [CHANGELOG](CHANGELOG.md)。
+> **v1.2.0 released 2026-04-26**. **当該プロジェクトで使えないツールが提案される回帰を構造的に修正**。daemon が監査に使うカタログを**ローカル DB のみ**に変更し、グローバル DB は他プロジェクトでの description 再利用キャッシュに役割を限定。`resolveAll` 末尾に prune ループ追加で、現プロジェクトの discovery 結果に含まれない既存ローカルエントリを削除 (= 過去の別プロジェクトで discover された MCP / スキル / サブエージェントが居座る経路を遮断)。既 install プロジェクトは npm global update 後、次の SessionStart で自動 refresh が走り、次の次のセッションから幽霊が消える (即時反映は `spotter db refresh` 手動)。v1.1.0 からの柱 (install 時 tool-db 自動構築 + SessionStart での drift 自動追従) は継続。監査対象は v1.0.0 でユーザー追加分 (MCP / スキル / サブエージェント) に絞り込み済み。設計思想は [docs/catalog-design.md](docs/catalog-design.md)、変更詳細は [CHANGELOG](CHANGELOG.md)。
 
 **気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
 
@@ -44,7 +44,9 @@ Stop hook → Spotter が応答と使用済みツールを見て最終チェッ
 見落としあれば差し戻し (max 1 回、Claude Code の stop_hook_active で自動担保)
 ```
 
-監査対象のツール (name + description) は `~/.spotter/tool-db.json` (グローバル) と `<project>/.spotter/tool-db.json` (ローカル) に格納されます。**v1.1.0 以降、`spotter install` が初回 seed を自動実行し、Claude Code セッション起動ごとに SessionStart hook が bg で `spotter db refresh` を走らせる**ため、通常の運用で手動コマンドを叩く必要はありません。収集経路は (1) MCP サーバー: user/project scope の `.mcp.json` + `claude mcp list` で列挙、各サーバーの `tools/list` を JSON-RPC で取得、HTTP/SSE transport にも対応、(2) スキル: user/project/プラグインの SKILL.md frontmatter から `{name, description}` を抽出、(3) サブエージェント: user/project/プラグインの agent .md frontmatter から抽出、(4) claude.ai baseline: OAuth proxy 経由の Gmail/Calendar/Drive 25 件は手書き baseline で補完 (v1.1.4 以降、`claude mcp list` に該当サーバーが存在する環境でのみ注入)。**手書きでツールリストを管理する必要はありません**。
+監査対象のツール (name + description) は `<project>/.spotter/tool-db.json` (ローカル) に格納されます。**daemon が監査に使うのはローカル DB のみ** (v1.2.0 以降) で、グローバル DB `~/.spotter/tool-db.json` は他プロジェクトでの description 再利用キャッシュとしてのみ機能します (live fetch コスト削減のため初回 refresh で参照、結果は local に write-through)。各プロジェクトの local DB は **そのプロジェクトの現時点の discovery 結果と一致** (refresh 時に prune される) ため、過去にインストールしていた MCP / スキル / サブエージェントが他プロジェクトに混入することはありません。
+
+**v1.1.0 以降、`spotter install` が初回 seed を自動実行し、Claude Code セッション起動ごとに SessionStart hook が bg で `spotter db refresh` を走らせる**ため、通常の運用で手動コマンドを叩く必要はありません。収集経路は (1) MCP サーバー: user/project scope の `.mcp.json` + `claude mcp list` で列挙、各サーバーの `tools/list` を JSON-RPC で取得、HTTP/SSE transport にも対応、(2) スキル: user/project/プラグインの SKILL.md frontmatter から `{name, description}` を抽出、(3) サブエージェント: user/project/プラグインの agent .md frontmatter から抽出、(4) claude.ai baseline: OAuth proxy 経由の Gmail/Calendar/Drive 25 件は手書き baseline で補完 (v1.1.4 以降、`claude mcp list` に該当サーバーが存在する環境でのみ注入)。**手書きでツールリストを管理する必要はありません**。
 
 ## Throughline との関係
 
@@ -61,7 +63,7 @@ Stop hook → Spotter が応答と使用済みツールを見て最終チェッ
 ## よく使うコマンド
 
 ```bash
-spotter db list          # 現在の tool-db (local + global merged) を表示
+spotter db list          # 現在のローカル tool-db (daemon が実際に audit に使う) を表示
 spotter db refresh       # MCP / スキル / サブエージェントから description を収集して DB 更新
                          # (v1.1.0 以降、install 時と SessionStart 時に自動実行されるので通常は不要)
 spotter db rebuild       # local + global DB を両方消してから refresh (カタログ設計変更時のクリーン用)

package/package.json

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

package/src/cli/db-cmd.mjs

@@ -1,13 +1,13 @@
 // `spotter db` — manage the tool-db.
 //
-//   spotter db list             — print merged tool-db (local overrides global)
+//   spotter db list             — print the LOCAL tool-db (what the daemon actually audits)
 //   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 { refresh, readLocal } from '../tool-db/refresh.mjs';
 import { localDbPath, globalDbPath, loadDb, saveDb, emptyDb } from '../tool-db/loader.mjs';
 import { writeFile } from 'node:fs/promises';
 
@@ -22,7 +22,7 @@ function requireProjectRoot() {
 
 export async function runDbList() {
   const projectRoot = requireProjectRoot();
-  const tools = await readMerged({ projectRoot });
+  const tools = await readLocal({ projectRoot });
   if (tools.length === 0) {
     process.stdout.write('(empty — run `spotter db refresh` to populate)\n');
     return;

package/src/daemon/daemon.mjs

@@ -42,7 +42,7 @@ import {
   createHaikuCaller,
   HaikuError,
 } from './haiku-caller.mjs';
-import { readMerged } from '../tool-db/refresh.mjs';
+import { readLocal } from '../tool-db/refresh.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { writeFile, unlink } from 'node:fs/promises';
@@ -90,9 +90,11 @@ export async function startDaemon({
   // a sibling daemon is already serving this session_id — throw so the caller can exit.
   await assertNoLiveDaemon(sessionId);
 
-  // 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.
+  // v1.2.0: tool list comes from the LOCAL tool-db only. The audit must reflect what
+  // this specific project can use — mixing in the global DB caused phantom suggestions
+  // from previously-visited projects (Gmail tools popping up in projects with no Gmail
+  // MCP, etc.). For tests, the caller can pass `tools` directly. For production,
+  // projectRoot drives the load from <projectRoot>/.spotter/tool-db.json.
   let toolList;
   if (Array.isArray(tools)) {
     toolList = tools;
@@ -100,7 +102,7 @@ export async function startDaemon({
     if (!projectRoot) {
       throw new TypeError('startDaemon: either `tools` or `projectRoot` must be provided');
     }
-    toolList = await readMerged({ projectRoot });
+    toolList = await readLocal({ projectRoot });
   }
   logFn(`tool-db loaded: ${toolList.length} tools` + (projectRoot ? ` (project=${projectRoot})` : ''));
 

package/src/index.mjs

@@ -15,7 +15,7 @@ export {
 } from './daemon/haiku-caller.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 { refresh, readLocal, buildInvestigationSnapshot } from './tool-db/refresh.mjs';
 export { listMcpServers, listMcpToolsAll, bellVisibleName, McpInvestigationError } from './tool-db/investigate-mcp.mjs';
 export { listSkillsAll, listActivePlugins } from './tool-db/investigate-skills.mjs';
 export { listAgentsAll } from './tool-db/investigate-agents.mjs';

package/src/tool-db/lookup.mjs

@@ -6,6 +6,12 @@
 //   3. both miss          → investigate, write to BOTH
 //   * local≠global hit    → re-investigate (MCP server is source of truth), overwrite BOTH
 //
+// Local DB pruning: after resolution, any tool currently in the local DB but NOT in
+// `toolNames` (i.e. no longer discoverable in this project — server uninstalled, skill
+// deleted, agent moved away) is removed. The local DB MUST mirror "what this project
+// can use right now" since it is the sole input to the audit. Global DB is the
+// long-term knowledge store and is never pruned.
+//
 // `investigate(name)` is supplied by the caller. Returns description string, or null
 // if the tool cannot be resolved (keep going, don't throw).
 
@@ -72,6 +78,18 @@ export async function resolveAll({ toolNames, localPath, globalPath, investigate
     resolved.set(name, { description: fresh, source: 'investigated' });
   }
 
+  // Prune local entries no longer present in this project's discovery.
+  // Skip names that were requested but failed to resolve (investigation may be a
+  // transient failure — keep the existing description rather than blanking the audit).
+  const requested = new Set(toolNames);
+  for (const name of Object.keys(local.tools)) {
+    if (!requested.has(name)) {
+      delete local.tools[name];
+      localDirty = true;
+      logFn(`pruned local entry "${name}" (no longer in this project's discovery)`);
+    }
+  }
+
   if (localDirty) await saveDb(localPath, local);
   if (globalDirty) await saveDb(globalPath, global);
 

package/src/tool-db/refresh.mjs

@@ -97,13 +97,13 @@ export async function refresh({ projectRoot, logFn = () => {}, claudeBin = 'clau
   });
 }
 
-// Read-only: load the current tool-db (local + global merged with local-wins) for use
-// by daemon at session start. Does NOT perform discovery or write — that's `refresh`'s
-// job, run via CLI or install hook.
-export async function readMerged({ projectRoot }) {
+// Read-only: load the LOCAL tool-db only — the daemon's audit must reflect what this
+// specific project can actually use. The global DB is a knowledge store written by
+// `refresh` (so other projects can pick up descriptions cheaply) but is NEVER mixed
+// into the daemon's audit catalog. Mixing global in caused phantom-tool suggestions
+// from previously-visited projects bleeding into unrelated ones.
+export async function readLocal({ projectRoot }) {
   const { loadDb } = await import('./loader.mjs');
   const local = await loadDb(localDbPath(projectRoot));
-  const global = await loadDb(globalDbPath());
-  const merged = { ...global.tools, ...local.tools }; // local overrides
-  return Object.entries(merged).map(([name, description]) => ({ name, description }));
+  return Object.entries(local.tools).map(([name, description]) => ({ name, description }));
 }