claude-spotter 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 1.2.2
+
+**Windows で npm-global の `.cmd` 配布 MCP サーバ (例: `claude-mermaid`) が investigate 時に ENOENT で落ちる回帰を修正**。`spotter db refresh` の MCP investigate 経路で `spawn error: spawn claude-mermaid ENOENT` が出て、当該 MCP のツールがカタログに投入されない症状。`.exe` 配布の MCP (例: `openai-image`) や `claude-mermaid.cmd` のように拡張子を明示した登録は影響を受けない、ピンポイントな bug。
+
+### 変更点
+
+- **編集 [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs)**: `buildStdioSpawn` の Windows ブランチ条件を `/\.(cmd|bat)$/i` から「絶対 `.exe` パス以外は `cmd.exe /c` で包む」に拡張。`export` を追加してユニットテスト可能に
+- **編集 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: 4 件追加 — POSIX パススルー / Windows 裸名の wrap (`claude-mermaid` で v1.2.1 の症状を直接再現) / Windows `.cmd`・`.bat` の wrap / Windows 絶対 `.exe` パスは un-wrap (空白入りパスでの cmd.exe quoting リスク回避)
+
+### 背景
+
+#### 何が起きていたか
+
+Windows の npm global は CLI を `<name>.cmd` バッチラッパーとして配布する (npm 標準仕様)。Node.js の `child_process.spawn(name, args)` は `shell: true` 無しでは Windows `CreateProcess` をそのまま呼び、`CreateProcess` は `.exe` を直接実行するが PATHEXT で `.cmd` を解決しない。結果、`spawn('claude-mermaid', [])` は `claude-mermaid.cmd` が PATH 上にあっても ENOENT で即落ちる。これは Spotter v0.7.0 → v0.8.0 で claude CLI 起動時に踏んで自分で直した bug の再来 (own caveat: `windows-node-spawn-claude-fails-with-enoent-because-claude-is-a-cmd-wrapper`) で、修正パターン (Windows なら `cmd.exe /c <command>` で包む) は既に Spotter 内に存在していた (`execClaude` / haiku-caller の `buildSpawnArgs`)。**穴は MCP サーバ起動経路にこのパターンが横展開されていなかったこと**。
+
+#### v1.2.1 までのコード
+
+```js
+function buildStdioSpawn(command, args) {
+  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(command)) {
+    return { cmd: 'cmd.exe', cmdArgs: ['/c', command, ...args] };
+  }
+  return { cmd: command, cmdArgs: args };
+}
+```
+
+`/\.(cmd|bat)$/i` は「コマンド名が `.cmd`/`.bat` で**終わっている**」場合のみ wrap する。ところが MCP サーバの登録名 (`claude mcp add` から `~/.claude.json` 直下 `mcpServers` に書かれる、または `.mcp.json` に書かれる) は通常**拡張子を付けない裸名** (`claude-mermaid`)。そのため Windows ブランチが発火せず、wrap 抜きで `spawn('claude-mermaid')` してENOENT。`.exe` 配布だと `CreateProcess` が直接実行できるので症状が出ない。`.cmd` を明示的に書いた登録 (`claude-mermaid.cmd`) も既存ロジックでセーフ。**裸名 + `.cmd` 実体の組合せだけが silent に脱落していた**。
+
+### 設計判断
+
+- **絶対 `.exe` パスは un-wrap のまま**: `C:\Program Files\nodejs\node.exe` のような空白入りパスを `cmd.exe /c` で包むと cmd.exe の `/c` 引数解釈ルール (最初の char が `"` のときの outer-quote strip 等) のリスクに晒される。`.exe` は `CreateProcess` が直接実行できるので包む必要がないし、包まないことで quoting リスクをゼロにできる。`.cmd` パスはどのみち cmd.exe 経由でしか走らないので包む必要があり、quoting リスクは織り込み済み (既存挙動から退化なし)
+- **`shell: true` を使わない理由**: Node 24+ で DEP0190 が出るし、引数 quoting が cmd.exe の rules に丸投げされて `&` `|` `>` 等の metacharacter 処理リスクが復活する。caveat の Resolution と既存 (`execClaude` / `buildSpawnArgs`) の選択を踏襲
+- **裸名を全部 wrap する選択 (= 「`.exe` 以外は wrap」)**: `node` のような既知の `.exe` 配布も Windows では cmd.exe 経由になるが、cmd.exe が PATHEXT で正しく解決するので動作影響なし。コードのシンプルさ (extension の case sensitivity / 配布形態の事前知識を不要にする) を優先
+- **patch bump (fix)**: API 変更なし、`buildStdioSpawn` の export 追加は純粋に additive。Windows での挙動が「ENOENT で死ぬ」→「正しく動く」方向の修正なので破壊変更なし
+
+### 自動追従の経路
+
+既に Spotter を導入済みのプロジェクトは npm global update (`npm i -g claude-spotter@1.2.2`) 後、次の Claude Code SessionStart で v1.1.0 機構の `spawnRefreshDetached` が走り、新 `buildStdioSpawn` で MCP investigate を再実行。これまで wrap 抜きで spawn して即 ENOENT だった `.cmd` 配布 MCP が live fetch に成功し、**次の次のセッション**から該当ツールがカタログに復活する (detached の仕様)。即時反映したい場合は `spotter db refresh` を手動実行 (環境によっては既にカタログに残っている古いエントリは prune される / live fetch 成功で description が上書きされる)。
+
+## 1.2.1
+
+**Claude Code 公式の MCP scope 3 段 (User / Project / Local) に完全対応**。v1.2.0 までの `readMcpServers` は project スコープ (`<projectRoot>/.mcp.json`) と非公式の legacy `~/.claude/.mcp.json` しか読んでおらず、公式 3 スコープのうち 2 つ (User: `~/.claude.json` 直下 `mcpServers` / Local: `~/.claude.json` `projects[<root>].mcpServers`) を読み損ねていた。結果、`claude mcp add -s user -e KEY=val -- ...` で登録した MCP サーバーは `claude mcp list` で発見されるが env が拾えず、HTTP 系は 401、stdio 系は API キー無しで spawn → tools/list が空 → `resolveAll` の prune ループでカタログから削除、という silent な脱落が発生していた。
+
+### 変更点
+
+- **編集 [src/tool-db/mcp-config.mjs](src/tool-db/mcp-config.mjs)**: `readMcpServers` を 4 ソース merge に拡張 — `legacy < user < project < local` の優先順 (公式仕様 Local > Project > User と整合、legacy `~/.claude/.mcp.json` は最下位の互換扱い)。新規 export: `userClaudeJsonPath`、`legacyUserMcpConfigPath`、`normalizeProjectPath`、`extractUserScopeServers`、`findLocalScopeServers`。`readMcpServers` に `claudeJsonPath` / `legacyUserPath` の DI パラメータを追加 (テスト用、デフォルトは実 homedir)。冒頭コメントを公式仕様 ([https://code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp)) に揃えて書き直し、legacy ソースの位置付けを明記
+- **編集 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: 13 件追加 — user/local 単独 / 4 段優先順位 / `~/.claude.json` 不在・malformed・キー欠損 / `extractUserScopeServers` の null 耐性 / `normalizeProjectPath` (separator・trailing slash・Windows case) / `findLocalScopeServers` (exact / 正規化マッチ / 非マッチ時の no-fuzzy / null 入力)
+
+### 設計判断
+
+- **`projects[]` キーの照合に正規化を入れた理由**: Claude Code が `~/.claude.json` に書く絶対パスの表記は環境と書き込みタイミングで揺れる (Windows ではドライブレターの大小、separator (`\` vs `/`)、末尾スラッシュ)。正確一致が外れると Local スコープが silent に脱落する = 今回直そうとしている bug の Windows 版が再発する。`normalizeProjectPath` で separator 統一 + 末尾 `/` 除去 + Windows 限定の lower-case を施し、exact 一致が無いときだけ正規化フォールバックする 2 段照合に
+- **fuzzy / prefix マッチを意図的に外した理由**: `/home/u/proj` のキーから `/home/u/other-project` の照合に `mcpServers` を引き渡すと、別プロジェクトの secrets を spotter の audit に混ぜることになる。projectRoot は識別子であって階層ではないので、normalize 後の完全一致のみ採用 (タスク指示の「投機的なファジーマッチはしない」と整合)
+- **`~/.claude.json` の malformed を throw せず空扱い**: このファイルは Claude Code 本体が管理する状態ファイルで、書き込み中に他プロセスが読みに行けば transient corruption に見える可能性がある。Spotter が落ちる方が実害が大きいので寛容に扱う (`.mcp.json` 系 = ユーザー手書きはこれまで通り throw、bug 表面化を優先)
+- **fix 扱いの patch bump**: public API (`readMcpServers` のシグネチャ) は引数が optional 追加のみで後方互換、merge 結果が「漏れてた scope を拾う」方向に増えるだけで既存挙動の縮退なし。programmatic API の破壊変更ではないので minor bump 不要
+- **legacy `~/.claude/.mcp.json` を残した理由**: 仕様外であることは認めるが、現に Spotter で投入されているサンプルや既存ユーザー環境の依存を切ると静かにツールが消える。最下位優先で残しつつ、コメントで「legacy / 公式仕様外 / 互換維持」を明記。撤去は別 PR
+
+### 自動追従の経路
+
+既に Spotter を導入済みのプロジェクトは npm の global update 後、次の Claude Code SessionStart で v1.1.0 機構の `spawnRefreshDetached` が走り、その refresh が新 `readMcpServers` で User / Local スコープの env を拾い直す。これまで env 抜きで spawn して tools/list が空だった MCP サーバーが live fetch に成功するようになり、**次の次のセッション**から該当ツールがカタログに復活する (detached の仕様)。即時反映したい場合は `spotter db refresh` を手動実行。
+
 ## 1.2.0
 
 **当該プロジェクトで使えないツールが提案される回帰を構造的に修正**。daemon が監査に使うカタログを **ローカル DB のみ** に変更し、グローバル DB は他プロジェクトでの description 再利用のためのキャッシュ層に役割を限定。同時に `resolveAll` で「現プロジェクトの discovery 結果に含まれないローカルエントリ」を prune するよう変更し、過去にインストールされていた MCP / スキル / サブエージェントが local に居座って Haiku 視野に残る経路を塞いだ。

package/README.ja.md

@@ -0,0 +1,123 @@
+<p align="center">
+  <img src=".github/og.svg" alt="Spotter — Audit agent for Claude Code" width="100%">
+</p>
+
+# Spotter
+
+[![npm version](https://img.shields.io/npm/v/claude-spotter.svg?style=flat-square)](https://www.npmjs.com/package/claude-spotter)
+[![CI](https://github.com/kitepon-rgb/Spotter/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/Spotter/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/claude-spotter.svg?style=flat-square)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+
+**[English](README.md) · 日本語**
+
+> **気づく役と実行する役を分離する。** Claude Code の横で並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**だけ静かに指摘する監査役。
+
+Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。現在時刻を推測で答える、`web_search` を呼ばずに古い情報で応答する、`read_file` を使わずにファイルの中身を推測する — **「分からないと自覚できない」から、ツールを取りに行けない**。
+
+Spotter はツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎に常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると透明化された指摘として Bell に届け、補正応答を促します。**Bell が自覚して呼ぶ**設計は本プロダクトの存在意義を破壊するため、Bell から呼ぶのではなく hook 経由で Bell の意思と独立に検出する構造を取っています。
+
+## 30 秒で見るポイント
+
+Spotter が拾うのは、たとえばこういう瞬間です。
+
+| 状況 | Bell の応答 | Spotter の指摘 |
+|---|---|---|
+| 「今日の天気を教えて」 | 推測で答えようとする | `web_search` の使用機会 |
+| 「この設定ファイルの中身は？」 | 名前から推測で説明 | `read_file` の使用機会 |
+| 「今何時？」 | 学習時点の情報で答える | `current_time` の使用機会 |
+| 事実の断定 | 裏付けなしで「〜です」 | 検証用ツールの差し込み余地 |
+
+判定軸は 2 段階:
+
+- **入力時 (`stage=user_input`)**: ユーザー要請に対し、`when_to_use` の条件に明確に該当するツールを列挙する **要請充足チェック**
+- **応答後 (`stage=turn_end`)**: Bell の最終応答に対し、事実の断定 / 記録すべき新情報 / 既知情報の参照それぞれに、カタログ上のツール (検証 / 登録 / 照会) を差し込める余地がないかを問う **ツール適用機会の監査**
+
+## インストール
+
+```bash
+npm install -g claude-spotter
+cd your-project
+spotter install
+```
+
+`v0.3.0` 以降は**プロジェクト単位の明示的 install** を採用しています (v0.2 までの `postinstall` 自動登録はデーモン増殖の主因だったため撤回)。各プロジェクトの `.claude/settings.json` に hook を登録し、そのプロジェクトでの Claude Code セッションのみで有効になります。
+
+```bash
+spotter uninstall        # このプロジェクトの hook 登録を解除
+```
+
+## 動作要件
+
+- **Node.js 22.5 以上**
+- **Claude Code 2.0 以上**
+- **Claude Max プラン** (`claude -p` で Haiku を起動するため)
+
+## アーキテクチャ
+
+```
+User 発話
+  ↓
+UserPromptSubmit hook → Spotter がカタログと発話を見て一次判定
+  ↓
+Bell Thinking (Spotter の推奨を additionalContext で受け取る)
+  ↓
+Bell 最終応答
+  ↓
+Stop hook → Spotter が応答と使用済みツールを見て最終チェック
+  ↓
+見落としあれば差し戻し (max 1 回、Claude Code の stop_hook_active で自動担保)
+```
+
+監査対象のツール (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 サーバー: `claude mcp list` で集合を確定し、env / headers は Claude Code 公式 3 スコープ — User (`~/.claude.json` 直下 `mcpServers`) / Project (`<projectRoot>/.mcp.json`) / Local (`~/.claude.json` `projects[<root>].mcpServers`) — を precedence Local > Project > User で merge して取得 (v1.2.1 以降、互換のため legacy `~/.claude/.mcp.json` も最下位で参照)、各サーバーの `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 との関係
+
+[Throughline](https://github.com/kitepon-rgb/Throughline) と Spotter は同じ作者が作った、**哲学を共有する別プロダクト**です。
+
+|  | Throughline | Spotter |
+|---|---|---|
+| 思想 | 引き算 (要らないものを退避) | 足し算 (足りない動作に気づかせる) |
+| 対象 | コンテキスト肥大化 | ツール取りこぼし |
+| 仕組み | hook で記憶退避 | hook でサブエージェント並走 |
+
+両者に共通するのは **「主体 (Bell) に頼らない仕組み」**。併用できます。
+
+## よく使うコマンド
+
+```bash
+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 (カタログ設計変更時のクリーン用)
+spotter status           # 稼働中の daemon 一覧
+spotter doctor           # 環境診断 (Node / claude CLI / tool-db 整合性)
+spotter uninstall        # hook 登録を解除 (~/.spotter は残す)
+```
+
+## 設計ドキュメント
+
+- **現行設計 (カタログ / 収集経路 / 分類軸)**: [docs/catalog-design.md](docs/catalog-design.md) — v1.0.0 以降の真実源
+- **現時点で塞がっていない穴 + 実測未検証の懸念**: [docs/open-issues.md](docs/open-issues.md) — 新規作業に入る前に必読
+- **実装規範と不変条件 (§0)**: [CLAUDE.md](CLAUDE.md) — フォールバック禁止 / silent fallback 禁止 / 暫定コード禁止
+- **歴史記録 (v0.1 時点の設計議事録)**: [docs/spotter-plan.md](docs/spotter-plan.md) — 作成時点で固定された議論過程のスナップショット、現行設計は上記 3 点を参照
+
+## 既知の制約
+
+- Stop hook は Bell の最初の応答が**出力された後**に発火するため、Spotter が Stop で差し戻した場合、ユーザーは「最初の応答 + 補正応答」の 2 連続を見ます (Claude Code の hook 仕様による制約)。UserPromptSubmit 段階での先回り検出を精度の軸にしています
+- **JSON スキーマ違反は v0.5.0 以降「想定済み異常」として silent pass + session renew で回復**します (role collapse 検知パス、daemon ログに `role_collapse_reset` を残す)。一方 **Haiku timeout は引き続き throw** され、UserPromptSubmit がブロックされてユーザー入力が Bell に届かない症状として顕在化します (timeout は v0.5.0 で 30s、v0.13.1 で 45s に拡張)。timeout の fail-open 化 (pass 扱い) は §0 改訂とセットで今後検討
+
+<details>
+<summary><strong>📋 v1.2.0 リリースノート (2026-04-26)</strong></summary>
+
+**当該プロジェクトで使えないツールが提案される回帰を構造的に修正**。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 / スキル / サブエージェント) に絞り込み済み。
+
+詳細は [CHANGELOG](CHANGELOG.md) を参照。
+
+</details>
+
+## ライセンス
+
+MIT — see [LICENSE](LICENSE).

package/README.md

@@ -1,14 +1,39 @@
+<p align="center">
+  <img src=".github/og.svg" alt="Spotter — Audit agent for Claude Code" width="100%">
+</p>
+
 # Spotter
 
-> **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)。
+[![npm version](https://img.shields.io/npm/v/claude-spotter.svg?style=flat-square)](https://www.npmjs.com/package/claude-spotter)
+[![CI](https://github.com/kitepon-rgb/Spotter/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/Spotter/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/claude-spotter.svg?style=flat-square)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+
+**English · [日本語](README.ja.md)**
+
+> **Separate the spotter from the doer.** Spotter runs alongside Claude Code and quietly flags the moments when Bell (your primary Claude) **forgets to use a tool it has access to**.
+
+Claude has a structural blind spot: **it can't reach for a tool it doesn't realize it needs**. It will guess the current time instead of calling `current_time`, answer with stale knowledge instead of `web_search`, describe a config file from its name instead of `read_file`. The model can't always tell when it doesn't know — so the tool stays unused.
 
-**気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
+Spotter pins a second agent (Claude Haiku 4.5) next to Bell. The second agent has the full tool catalog memorized and audits both the user's prompt and Bell's reply in parallel. When it spots a missed tool, it injects a transparent recommendation into Bell's context and, if needed, asks Bell to amend its answer. **Bell is never asked to self-audit** — that would defeat the entire premise. Detection happens through hooks, independent of Bell's intent.
 
-> Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。現在時刻を推測で答える、web_search を呼ばずに古い情報で応答する、read_file を使わずにファイルの中身を推測する — 「分からないと自覚できない」から、ツールを取りに行けない。
+## See it in 30 seconds
+
+Examples of what Spotter catches:
+
+| Situation | What Bell would do | What Spotter flags |
+|---|---|---|
+| "What's the weather today?" | Guess from training data | Missed call to `web_search` |
+| "What's in this config file?" | Describe based on the filename | Missed call to `read_file` |
+| "What time is it?" | Answer from training-time knowledge | Missed call to `current_time` |
+| Asserting a fact | Stating it without verification | Opportunity to call a verification tool |
 
-Spotter は、ツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎にプロセスとして常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると、透明化された指摘として Bell に届け、補正応答を促します。Haiku 呼び出しは session-scoped (`--resume`) で同一セッションに再接続して cold-start を削減し、初回のみ preamble を送って以降は per-turn delta だけ送ることで session 肥大化を防ぎます。role collapse (persona drift で JSON 契約破棄) は構造的に予防せず、検知した瞬間に session を切り直して fresh state から再開する事後回復機構で長時間運用に耐えます。
+Spotter audits in two stages:
 
-## インストール
+- **`stage=user_input`** — given the user's prompt, list any tools whose `when_to_use` clearly applies. A *prompt-fulfillment* check
+- **`stage=turn_end`** — given Bell's final reply, look for places where a catalog tool (verification / recording / lookup) could plug in. A *missed-opportunity* audit. Zero findings is fine; tools already used in this turn are not re-flagged
+
+## Install
 
 ```bash
 npm install -g claude-spotter
@@ -16,74 +41,87 @@ cd your-project
 spotter install
 ```
 
-v0.3.0 以降は**プロジェクト単位の明示的 install** を採用しています (v0.2 までの `postinstall` 自動登録はデーモン増殖の主因だったため撤回)。各プロジェクトの `.claude/settings.json` に hook を登録し、そのプロジェクトでの Claude Code セッションのみで有効になります。
+Since `v0.3.0`, Spotter requires **explicit per-project install** (the earlier `postinstall` auto-registration was the leading cause of orphan daemons). `spotter install` writes hooks into the project's `.claude/settings.json`; the audit is then active only in Claude Code sessions for that project.
 
 ```bash
-spotter uninstall        # このプロジェクトの hook 登録を解除
+spotter uninstall        # remove hooks from this project
 ```
 
-## 動作要件
+## Requirements
 
-- Node.js **22.5 以上**
-- Claude Code **2.0 以上**
-- Claude **Max プラン** (`claude -p` で Haiku を起動するため)
+- **Node.js 22.5+**
+- **Claude Code 2.0+**
+- **Claude Max plan** (Spotter spawns Haiku via `claude -p`)
 
-## コンセプト
+## Architecture
 
 ```
-User 発話
+User prompt
   ↓
-UserPromptSubmit hook → Spotter がカタログと発話を見て一次判定
+UserPromptSubmit hook → Spotter does a first pass against the catalog
   ↓
-Bell Thinking (Spotter の推奨を additionalContext で受け取る)
+Bell thinking (receives Spotter's recommendations as additionalContext)
   ↓
-Bell 最終応答
+Bell's final answer
   ↓
-Stop hook → Spotter が応答と使用済みツールを見て最終チェック
+Stop hook → Spotter re-audits the answer + tools actually used
   ↓
-見落としあれば差し戻し (max 1 回、Claude Code の stop_hook_active で自動担保)
+If something was missed: send-back (max 1 round, guaranteed by Claude Code's stop_hook_active)
 ```
 
-監査対象のツール (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 / スキル / サブエージェントが他プロジェクトに混入することはありません。
+The audited tool catalog (name + description) lives in `<project>/.spotter/tool-db.json`. **Since v1.2.0 the daemon audits against the local DB only**; the global DB at `~/.spotter/tool-db.json` is a description-reuse cache shared across projects, not an audit source. Each project's local DB always matches the **current** discovery snapshot for that project (entries are pruned on refresh), so MCP servers, skills, or sub-agents installed in *other* projects can never bleed into this project's audit.
 
-**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` に該当サーバーが存在する環境でのみ注入)。**手書きでツールリストを管理する必要はありません**。
+**Since v1.1.0, `spotter install` runs the initial seed automatically, and the SessionStart hook triggers a background `spotter db refresh` on every Claude Code session start** — so you don't need to invoke catalog commands by hand. The discovery sources are: (1) **MCP servers** — enumerated from `claude mcp list` (membership) and merged with all three official Claude Code scopes for env / headers: User (`~/.claude.json` direct `mcpServers`) / Project (`<projectRoot>/.mcp.json`) / Local (`~/.claude.json` `projects[<root>].mcpServers`), with precedence Local > Project > User (v1.2.1+); a legacy `~/.claude/.mcp.json` source is also read at the lowest priority for backward compatibility. Each server's `tools/list` is fetched via JSON-RPC (HTTP/SSE transport supported); (2) **skills** — `{name, description}` extracted from SKILL.md frontmatter at user / project / plugin scope; (3) **sub-agents** — same pattern from agent `.md` frontmatter; (4) **claude.ai baseline** — Gmail / Calendar / Drive (25 entries via OAuth proxy) injected from a hand-maintained baseline only when `claude mcp list` confirms the server is present (v1.1.4+). **You never have to maintain the tool list by hand.**
 
-## Throughline との関係
+## Spotter and Throughline
 
-[Throughline](https://github.com/kitepon-rgb/Throughline) と Spotter は同じ作者が作った、**哲学を共有する別プロダクト**です。
+[Throughline](https://github.com/kitepon-rgb/Throughline) is a sibling project from the same author. Different mechanism, **shared philosophy**.
 
 |  | Throughline | Spotter |
 |---|---|---|
-| 思想 | 引き算 (要らないものを退避) | 足し算 (足りない動作に気づかせる) |
-| 対象 | コンテキスト肥大化 | ツール取りこぼし |
-| 仕組み | hook で記憶退避 | hook でサブエージェント並走 |
+| Direction | Subtraction — evict what isn't needed | Addition — surface what's missing |
+| Target | Context bloat | Missed tool calls |
+| Mechanism | Hook-driven memory eviction | Hook-driven sub-agent in parallel |
 
-両者に共通するのは **「主体 (Bell) に頼らない仕組み」**。併用できます。
+Both share the principle of **"don't rely on the primary agent (Bell) to do it itself."** They compose well — you can run them together.
 
-## よく使うコマンド
+## Common commands
 
 ```bash
-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 (カタログ設計変更時のクリーン用)
-spotter status           # 稼働中の daemon 一覧
-spotter doctor           # 環境診断 (Node / claude CLI / tool-db 整合性)
-spotter uninstall        # hook 登録を解除 (~/.spotter は残す)
+spotter db list          # show the current local tool-db (what the daemon actually audits against)
+spotter db refresh       # rediscover MCP / skills / sub-agents and update the DB
+                         #   (run automatically on install and on SessionStart since v1.1.0,
+                         #    so this is rarely needed by hand)
+spotter db rebuild       # wipe both local + global DBs and refresh from scratch
+                         #   (use after catalog-shape changes)
+spotter status           # list running daemons
+spotter doctor           # environment check (Node / claude CLI / tool-db integrity)
+spotter uninstall        # remove hooks from this project (leaves ~/.spotter intact)
 ```
 
-## 設計ドキュメント
+## Design docs
+
+- **Current design** (catalog, discovery, classification axes): [docs/catalog-design.md](docs/catalog-design.md) — source of truth from v1.0.0
+- **Open issues + unverified concerns**: [docs/open-issues.md](docs/open-issues.md) — read this before starting new work
+- **Implementation invariants (§0)**: [CLAUDE.md](CLAUDE.md) — no fallbacks, no silent failures, no provisional code
+- **Historical record (v0.1 design discussion)**: [docs/spotter-plan.md](docs/spotter-plan.md) — frozen design-discussion snapshot
+
+## Known limitations
+
+- The `Stop` hook fires **after** Bell's first answer has already been streamed to the user. When Spotter sends Bell back, the user sees both the original answer and the corrected one. Detection accuracy in `UserPromptSubmit` (the *pre-response* stage) is therefore Spotter's primary axis of quality
+- **Since v0.5.0, JSON schema violations from Haiku are treated as expected-anomalies** (silent pass + session renew, logged as `role_collapse_reset`) — this is the role-collapse recovery path. **Haiku timeouts still throw**, which surfaces as `UserPromptSubmit` blocking the user's prompt from reaching Bell. Timeouts have been raised twice (30s in v0.5.0, 45s in v0.13.1); making timeouts fail-open is deferred until §0 is revisited
+
+<details>
+<summary><strong>📋 v1.2.0 release notes (2026-04-26)</strong></summary>
+
+**Structural fix for a regression that suggested tools the current project can't actually use.** The catalog the daemon audits against is now **local-only**. The global DB has been demoted to a cross-project description-reuse cache. A prune step was added to the end of `resolveAll`: any local entry not present in the current project's discovery snapshot is removed. This closes the path through which MCP servers / skills / sub-agents discovered in other projects used to linger in this project's audit set.
 
-- **現行設計 (カタログ / 収集経路 / 分類軸)**: [docs/catalog-design.md](docs/catalog-design.md) — v1.0.0 以降の真実源
-- **現時点で塞がっていない穴 + 実測未検証の懸念**: [docs/open-issues.md](docs/open-issues.md) — 新規作業に入る前に必読
-- **実装規範と不変条件 (§0)**: [CLAUDE.md](CLAUDE.md) — フォールバック禁止 / silent fallback 禁止 / 暫定コード禁止
-- **歴史記録 (v0.1 時点の設計議事録)**: [docs/spotter-plan.md](docs/spotter-plan.md) — 作成時点で固定された議論過程のスナップショット、現行設計は上記 3 点を参照
+For projects that already have Spotter installed, the next SessionStart after the npm global upgrade triggers an auto-refresh; the ghosts disappear from the session-after-next (immediate cleanup: run `spotter db refresh` by hand). The pillars introduced in v1.1.0 (auto-build of the tool DB at install, automatic drift tracking on SessionStart) are unchanged. The audit scope set in v1.0.0 (user-added MCP / skills / sub-agents) is unchanged.
 
-## 既知の制約
+Full notes: [CHANGELOG](CHANGELOG.md).
 
-- Stop hook は Bell の最初の応答が**出力された後**に発火するため、Spotter が Stop で差し戻した場合、ユーザーは「最初の応答 + 補正応答」の 2 連続を見ます (Claude Code の hook 仕様による制約)。UserPromptSubmit 段階での先回り検出を精度の軸にしています
-- **JSON スキーマ違反は v0.5.0 以降「想定済み異常」として silent pass + session renew で回復**します (role collapse 検知パス、daemon ログに `role_collapse_reset` を残す)。一方 **Haiku timeout は引き続き throw** され、UserPromptSubmit がブロックされてユーザー入力が Bell に届かない症状として顕在化します (timeout は v0.5.0 で 30s、v0.13.1 で 45s に拡張)。timeout の fail-open 化 (pass 扱い) は §0 改訂とセットで今後検討
+</details>
 
-## ライセンス
+## License
 
 MIT — see [LICENSE](LICENSE).

package/package.json

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

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

@@ -170,13 +170,36 @@ function splitArgs(s) {
   return s.split(/\s+/).filter((t) => t.length > 0);
 }
 
-// On Windows, `.cmd` / `.bat` shims cannot be spawned directly without cmd.exe.
-// Unix-like paths or `.exe` binaries go through spawn as-is.
-function buildStdioSpawn(command, args) {
-  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(command)) {
-    return { cmd: 'cmd.exe', cmdArgs: ['/c', command, ...args] };
+// On Windows, npm-global CLI tools (e.g. `claude-mermaid`) ship as `<name>.cmd`
+// batch wrappers. Node's `child_process.spawn` without `shell: true` calls Windows
+// `CreateProcess`, which only directly executes `.exe` files — it does NOT search
+// PATHEXT for `.cmd`/`.bat` shims when given a bare command name. So
+// `spawn('claude-mermaid', ...)` fails with ENOENT even though `claude-mermaid.cmd`
+// is on PATH.
+//
+// Until v1.2.1 this function only wrapped commands whose name literally ended in
+// `.cmd`/`.bat`, which missed the common case where the registered command is a
+// bare name (the CLI as installed). v1.2.2 routes any non-`.exe` command through
+// `cmd.exe /c` on Windows, which makes PATHEXT lookup apply and runs both `.cmd`
+// shims and bare names transparently.
+//
+// We keep absolute `.exe` paths un-wrapped because (a) they spawn correctly as-is
+// and (b) wrapping them through `cmd.exe /c "<path with spaces>" args` runs into
+// cmd.exe's quoting rules for paths containing spaces, which add risk for zero
+// benefit.
+//
+// We use `cmd.exe /c` explicitly rather than `spawn({ shell: true })` because the
+// latter triggers DEP0190 on Node 24+ and re-introduces argument-quoting risks
+// (matches the rationale in haiku-caller's buildSpawnArgs and the caveat
+// `windows-node-spawn-claude-fails-with-enoent-because-claude-is-a-cmd-wrapper`).
+export function buildStdioSpawn(command, args) {
+  if (process.platform !== 'win32') {
+    return { cmd: command, cmdArgs: args };
+  }
+  if (/\.exe$/i.test(command)) {
+    return { cmd: command, cmdArgs: args };
   }
-  return { cmd: command, cmdArgs: args };
+  return { cmd: 'cmd.exe', cmdArgs: ['/c', command, ...args] };
 }
 
 async function spawnAndQuery({ command, args, env = {} }, serverName) {

package/src/tool-db/mcp-config.mjs

@@ -1,25 +1,45 @@
-// Read MCP server definitions directly from `.mcp.json` rather than parsing
-// `claude mcp list` text output.
+// Read MCP server definitions from Claude Code's official scope storage.
 //
-// Why: `.mcp.json` is the authoritative source for stdio env vars (e.g. bearer tokens
-// passed to the MCP subprocess) and HTTP headers (e.g. Authorization). The CLI output
-// of `claude mcp list` / `claude mcp get` hides those secrets. Without them, an HTTP
-// MCP server returns 401 and a stdio MCP server spawns without its API key.
+// Why: The CLI output of `claude mcp list` / `claude mcp get` hides secrets such as
+// stdio env vars (bearer tokens passed to the MCP subprocess) and HTTP headers
+// (Authorization). Without them, an HTTP MCP server returns 401 and a stdio MCP
+// server spawns without its API key. Reading the underlying config files directly is
+// the only way to recover full transport details.
 //
-// Scope: merges user-level `~/.claude/.mcp.json` with optional project-level
-// `<projectRoot>/.mcp.json`. Project scope overrides user scope on name collision
-// (matches Claude Code's own precedence — more-specific scope wins).
-// `settings.local.json` (local scope) is not yet consulted.
+// Scope (per Claude Code's official spec — https://code.claude.com/docs/en/mcp):
+//
+//   - User    — `~/.claude.json` direct `mcpServers`. Loaded in all projects.
+//   - Project — `<projectRoot>/.mcp.json`. Loaded in current project only.
+//   - Local   — `~/.claude.json` `projects["<projectRoot>"].mcpServers`. Loaded in
+//               current project only.
+//
+// Precedence on name collision (more specific wins): Local > Project > User.
+//
+// Additionally, `~/.claude/.mcp.json` is read as a "legacy user-level" source — it is
+// NOT part of the official scope model but some Spotter installations still rely on
+// it, so we keep reading it at the lowest priority for backward compatibility.
+//
+// Until v1.2.0 we only read project + legacy. That left two of the three official
+// sources unread, so a server registered with `claude mcp add -s user` (env stored in
+// `~/.claude.json` direct `mcpServers`) was discovered by `claude mcp list` but
+// spawned without its env, returning empty `tools/list` and getting pruned from the
+// catalog. This module now covers all four sources.
 //
 // This file does NOT read ~/.claude/.credentials.json (Anthropic OAuth token). That
-// remains off-limits per the v0.8.0 design decision. `.mcp.json` is user-authored
-// configuration where the user has already chosen to persist their own MCP credentials.
+// remains off-limits per the v0.8.0 design decision. The `.mcp.json` files and
+// `~/.claude.json`'s `mcpServers` are user-authored / Claude-Code-managed
+// configuration where the user has already chosen to persist their own MCP
+// credentials.
 
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export function userMcpConfigPath() {
+export function userClaudeJsonPath() {
+  return join(homedir(), '.claude.json');
+}
+
+export function legacyUserMcpConfigPath() {
   return join(homedir(), '.claude', '.mcp.json');
 }
 
@@ -27,25 +47,122 @@ export function projectMcpConfigPath(projectRoot) {
   return join(projectRoot, '.mcp.json');
 }
 
-async function readOne(path) {
+// Back-compat alias. Older callers / external integrators may still import this.
+export function userMcpConfigPath() {
+  return legacyUserMcpConfigPath();
+}
+
+// Read `~/.claude.json`. Missing file → null. Malformed JSON → null. Other I/O errors
+// re-throw. Lenient parsing because this file is owned by Claude Code (not Spotter
+// nor the user directly): a transient corruption mid-write must not crash Spotter.
+async function readClaudeJsonFile(path) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    if (err instanceof SyntaxError) return null;
+    throw err;
+  }
+}
+
+// Read an `.mcp.json`-shaped file (user-authored). Missing → empty map. Malformed
+// JSON or other I/O errors re-throw — these files are written by hand or by the
+// `claude mcp add` CLI; surfacing a parse error helps the user notice the corruption.
+async function readMcpServersFile(path) {
+  let text;
   try {
-    const text = await readFile(path, 'utf8');
-    const data = JSON.parse(text);
-    return data.mcpServers ?? {};
+    text = await readFile(path, 'utf8');
   } catch (err) {
     if (err.code === 'ENOENT') return {};
     throw err;
   }
+  const data = JSON.parse(text);
+  if (!data || typeof data !== 'object') return {};
+  return (data.mcpServers && typeof data.mcpServers === 'object') ? data.mcpServers : {};
+}
+
+// Normalize a project path for matching against `~/.claude.json` `projects[]` keys.
+// Claude stores absolute paths verbatim, but representation can drift across:
+//   - separator: `\` on Windows vs `/`
+//   - drive-letter case: `C:\` vs `c:\` on Windows
+//   - trailing slash: `/foo/bar` vs `/foo/bar/`
+// We canonicalize to forward slashes, strip trailing slashes, and lower-case on
+// Windows (case-insensitive filesystem). POSIX stays case-sensitive.
+export function normalizeProjectPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return '';
+  let s = p.replace(/\\/g, '/').replace(/\/+$/, '');
+  if (process.platform === 'win32') s = s.toLowerCase();
+  return s;
+}
+
+// Extract user-scope `mcpServers` from a parsed `~/.claude.json` object.
+export function extractUserScopeServers(claudeJson) {
+  if (!claudeJson || typeof claudeJson !== 'object') return {};
+  const servers = claudeJson.mcpServers;
+  return (servers && typeof servers === 'object') ? servers : {};
+}
+
+// Extract local-scope `mcpServers` for a given projectRoot from a parsed
+// `~/.claude.json` object. Tries the exact key first, then a normalized match
+// (separator / case / trailing-slash insensitive on Windows). If no key matches,
+// returns empty — we deliberately do NOT fuzzy-match (e.g. partial-prefix), since
+// that could pull in another project's secrets.
+export function findLocalScopeServers(claudeJson, projectRoot) {
+  if (!claudeJson || typeof claudeJson !== 'object') return {};
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) return {};
+  const projects = claudeJson.projects;
+  if (!projects || typeof projects !== 'object') return {};
+
+  const direct = projects[projectRoot];
+  if (direct && typeof direct === 'object'
+      && direct.mcpServers && typeof direct.mcpServers === 'object') {
+    return direct.mcpServers;
+  }
+
+  const target = normalizeProjectPath(projectRoot);
+  if (target.length === 0) return {};
+  for (const key of Object.keys(projects)) {
+    if (normalizeProjectPath(key) !== target) continue;
+    const entry = projects[key];
+    if (entry && typeof entry === 'object'
+        && entry.mcpServers && typeof entry.mcpServers === 'object') {
+      return entry.mcpServers;
+    }
+  }
+  return {};
 }
 
-// Returns the merged `mcpServers` object: user scope as base, project scope overrides
-// on name collision. Missing files are treated as empty (not an error). If projectRoot
-// is not supplied, only user scope is read.
-export async function readMcpServers({ projectRoot } = {}) {
-  const user = await readOne(userMcpConfigPath());
-  if (!projectRoot) return user;
-  const project = await readOne(projectMcpConfigPath(projectRoot));
-  return { ...user, ...project };
+// Returns the merged `mcpServers` map across all known scopes for the current
+// project. Sources, lowest → highest priority on name collision:
+//   1. legacy `~/.claude/.mcp.json`                                    (back-compat)
+//   2. user scope    `~/.claude.json` `mcpServers`                     (all projects)
+//   3. project scope `<projectRoot>/.mcp.json`                         (this project)
+//   4. local scope   `~/.claude.json` `projects[<root>].mcpServers`    (this project)
+//
+// Missing files / missing keys are treated as empty (no error). If `projectRoot` is
+// not supplied, scopes 3 and 4 are skipped.
+//
+// IMPORTANT: this function does NOT decide which servers are "loaded in this
+// project" — that is `claude mcp list`'s job. Callers in investigate-mcp.mjs
+// intersect this map with the CLI list (CLI authoritative for membership; this map
+// authoritative for transport details + secrets).
+export async function readMcpServers({
+  projectRoot,
+  claudeJsonPath = userClaudeJsonPath(),
+  legacyUserPath = legacyUserMcpConfigPath(),
+} = {}) {
+  const legacy = await readMcpServersFile(legacyUserPath);
+  const claudeJson = await readClaudeJsonFile(claudeJsonPath);
+  const user = extractUserScopeServers(claudeJson);
+  const project = projectRoot ? await readMcpServersFile(projectMcpConfigPath(projectRoot)) : {};
+  const local = projectRoot ? findLocalScopeServers(claudeJson, projectRoot) : {};
+  return { ...legacy, ...user, ...project, ...local };
 }
 
 // Normalise an `.mcp.json` entry into a server descriptor the investigator can use.