claude-spotter 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 1.1.5
+
+**Windows で refresh 毎に cmd.exe console window が flash + 入力フォーカスを奪う UX 回帰を修正**。`listMcpServers` / `getStdioConfig` が `execClaude` 経由で spawn する `cmd.exe /c claude mcp list/get` に `windowsHide: true` が付いておらず、SessionStart 毎の bg refresh と install 時 seed で毎回黒いウィンドウが一瞬表示されキーボード入力が奪われていた。
+
+### 変更点
+
+- **編集 [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs)**: `execClaude` ヘルパ内で `opts` を spread した上で `windowsHide: true` を強制。呼び出し側 (`listMcpServers`, `getStdioConfig`) の `execOpts` に毎回書かせるのではなく、helper 層で固定することで将来の call site も自動で守られる。
+
+### 背景
+
+Windows の `spawn` / `execFile` は `windowsHide` オプションが `false` のとき、child process の console window を visible で起動する。Spotter の spawn サイトは 6 箇所 (daemon spawn / refresh detached / haiku-caller / MCP stdio spawn / doctor / execClaude) あり、うち 5 箇所は個別に `windowsHide: true` を付けていたが、`execClaude` だけ opts 任せになっていて pass されていなかった。
+
+SessionStart 毎の `spotter db refresh` で `listMcpServers` が 1 回、stdio MCP サーバーの数だけ `getStdioConfig` が呼ばれるため、MCP サーバー N 個の環境では SessionStart 毎に **1 + N 回** の flash が発生。加えて `spotter install` 時の seed でも同じ経路を通る。体感「結構な頻度で入力を奪われる」という UX 回帰の直接原因。
+
+### 設計判断
+
+- **helper 層で windowsHide 強制**: call site 毎に書かせる方針は 2 箇所の execOpts を更新するだけで済むが、新 call site 追加時に忘れるリスクが残る。`execClaude` は外部コマンド (`claude` CLI) 専用で Windows では常に cmd.exe 経由のため、「このヘルパ経由なら silent」という不変条件を layer 内で閉じた方が防御堅牢。
+- **他 5 spawn サイトの監査**: `spawn-daemon.mjs` (daemon + refresh detached), `haiku-caller.mjs` (claude -p), `investigate-mcp.mjs:spawnAndQuery` (MCP stdio), `doctor.mjs` (claude --version) はすべて `windowsHide: true` 済みを確認。この修正で残る穴はゼロ。
+- **テスト追加なし**: Windows console window visibility は cross-platform ユニットテストで検証しづらい (Windows 環境でも Node の test runner 経由で spawn した child の visibility を assert する API がない)。監査対象は 6 spawn サイト全件の源コード上の `windowsHide: true` の存在のみ、これは grep で機械検証できる。
+
+## 1.1.4
+
+**MCP 投資ロジックの 2 件の穴を修正**。どちらも「名乗っているスコープ」と「実際に参照されるスコープ」が一致していない silent mismatch。前者は projectRoot 引数が効かない経路、後者は baseline が現実を無視して常に 25 件投入される経路。
+
+### 変更点
+
+- **編集 [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs)**: `listMcpServers` / `getStdioConfig` が projectRoot を受け取っておきながら `execClaude(claude mcp list / mcp get)` に `cwd` を渡していなかったため、`.mcp.json` 読み込みと claude CLI の walk-up が別プロジェクトを見る可能性があった。`cwd: projectRoot` を付与し、`listMcpToolsOne` を通じて projectRoot を伝搬するシグネチャに変更。通常は `process.cwd() === projectRoot` で表面化しないが、API の意味論を実装に揃える
+- **編集 [src/tool-db/claude-ai-baseline.mjs](src/tool-db/claude-ai-baseline.mjs)**: flat な `listClaudeAiNames` / `getClaudeAiDescription` を削除、server 単位の `getClaudeAiBaselineByServer()` に再編。Gmail / Calendar / Drive を個別集合として保持し、呼び出し側で現実に存在するサーバーのみ注入できるようにした
+- **編集 [src/tool-db/refresh.mjs](src/tool-db/refresh.mjs)**: `buildInvestigationSnapshot` で `listMcpServers` の結果に基づき baseline を filter。`claude mcp list` に `claude.ai Gmail` / `claude.ai Google Calendar` / `claude.ai Google Drive` が存在しない環境 (隔離 `CLAUDE_CONFIG_DIR`, claude.ai OAuth 未連携, 部分連携) では該当 baseline は投入されない。純粋関数 `filterClaudeAiBaseline` を named export として切り出しテスト可能にした
+- **編集 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: `filterClaudeAiBaseline` の回帰テスト 3 件追加 — 全 3 サーバー存在 / Gmail のみ存在 / 全不在
+
+### 背景
+
+#### projectRoot の silent mismatch
+
+v0.10.0 で `.mcp.json` の project scope 対応を入れた際、`readMcpServers({projectRoot})` は projectRoot を尊重するようにしたが、同じ関数内で spawn している `claude mcp list` / `claude mcp get` には `cwd` を渡し忘れていた。claude CLI は cwd から親方向に walk-up して `.mcp.json` を探すため、Spotter が引数で指定した projectRoot と claude CLI が勝手に見つけた project scope が乖離する可能性が残っていた。
+
+#### claude.ai baseline の無条件注入
+
+v0.8.0 で claude.ai OAuth 系 MCP (Gmail / Calendar / Drive) を手書き baseline として導入した際、「live HTTP investigate が成功した場合 override される」という想定で無条件注入ロジックを置いていた。しかし claude.ai 系は `.mcp.json` に載らず OAuth proxy 経由のため、`listMcpToolsAll` の investigate 対象にそもそも入らない = override 経路は発動不能。結果、claude.ai 未連携 / 部分連携環境 (隔離 `CLAUDE_CONFIG_DIR` での bellbot 等) で最大 25 件の幻ツールが catalog に残り、Bell が呼べないツールを Spotter が推奨する誤検出源になっていた。
+
+### 設計判断
+
+- **`listMcpToolsAll` のシグネチャは触らない**: baseline filter 用に `listMcpServers` を buildInvestigationSnapshot で先に呼ぶと、内部で listMcpToolsAll がもう一度 CLI spawn する。pre-resolved servers 引数で避けられるが、API 表面を増やすコストに対し `claude mcp list` は 0.5-2s の 1 度だけなので受容
+- **診断ログ追加**: baseline 注入時に `claude.ai baseline injected: N tools from <server list>` を logFn に出力。どの環境で何件入ったか後から追えるようにした
+- **後方互換 export は削除**: `listClaudeAiNames` / `getClaudeAiDescription` は [src/index.mjs](src/index.mjs) に re-export されておらず、外部利用の形跡なし。残しても drift 源になるため削除
+
 ## 1.1.3
 
 **v1.1.x の実装進展にドキュメントを追従させる docs-only リリース**。コード変更なし。npm package tarball 同梱の README が古い手順を指していたため再 publish。

package/README.md

@@ -1,6 +1,6 @@
 # Spotter
 
-> **v1.1.2 released 2026-04-20**. **install が tool-db を自動構築 + SessionStart で drift 自動追従**。`spotter install` 実行時に MCP / スキル / サブエージェントを discover して tool-db.json を seed、以降 Claude Code セッション起動ごとに SessionStart hook が detached で `spotter db refresh` を bg 発火 (反映は次セッション以降)。手動の `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.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)。
 
 **気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
 
@@ -44,7 +44,7 @@ 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 で補完。**手書きでツールリストを管理する必要はありません**。
+監査対象のツール (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` に該当サーバーが存在する環境でのみ注入)。**手書きでツールリストを管理する必要はありません**。
 
 ## Throughline との関係
 

package/package.json

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

package/src/tool-db/claude-ai-baseline.mjs

@@ -75,12 +75,19 @@ const DRIVE = {
     'List who has access to a Drive file and their role (reader/commenter/writer/owner). Use when the user asks who can see or edit a file.',
 };
 
-const ALL = { ...GMAIL, ...CALENDAR, ...DRIVE };
-
-export function listClaudeAiNames() {
-  return Object.keys(ALL);
-}
+// Server-level structure. Keys are the literal server names as reported by
+// `claude mcp list` — the callers in refresh.mjs filter by this name so that the
+// baseline is only injected for servers actually visible in the current session.
+// Without this filter, 25 phantom tools leak into the catalog in any environment
+// where Claude.ai OAuth is not connected (isolated CLAUDE_CONFIG_DIR, Max plan
+// users without Desktop integration, or partial Gmail-only / Calendar-only setups).
+const BY_SERVER = {
+  'claude.ai Gmail': GMAIL,
+  'claude.ai Google Calendar': CALENDAR,
+  'claude.ai Google Drive': DRIVE,
+};
 
-export function getClaudeAiDescription(name) {
-  return ALL[name] ?? null;
+// Returns Map<serverName, {toolName: description}>.
+export function getClaudeAiBaselineByServer() {
+  return new Map(Object.entries(BY_SERVER));
 }

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

@@ -23,11 +23,15 @@ const HANDSHAKE_TIMEOUT_MS = 10_000;
 // On Windows, `claude` is a .cmd shim; Node's execFile cannot locate it directly without
 // going through cmd.exe. Matches the pattern in src/daemon/haiku-caller.mjs buildSpawnArgs.
 // We use cmd.exe /c rather than shell:true to avoid DEP0190 on Node 24+.
+// `windowsHide: true` is forced at this layer so every caller (listMcpServers,
+// getStdioConfig, etc.) is silent — without it a cmd.exe console window flashes on every
+// refresh, and those flashes steal keyboard focus on Windows.
 async function execClaude(claudeBin, args, opts) {
+  const execOpts = { ...opts, windowsHide: true };
   if (process.platform === 'win32') {
-    return execFileP('cmd.exe', ['/c', claudeBin, ...args], opts);
+    return execFileP('cmd.exe', ['/c', claudeBin, ...args], execOpts);
   }
-  return execFileP(claudeBin, args, opts);
+  return execFileP(claudeBin, args, execOpts);
 }
 
 export class McpInvestigationError extends Error {
@@ -45,7 +49,7 @@ export async function listMcpToolsAll({ logFn = () => {}, claudeBin = 'claude',
   const out = new Map();
   for (const server of servers) {
     try {
-      const tools = await listMcpToolsOne({ server, logFn });
+      const tools = await listMcpToolsOne({ server, logFn, claudeBin, projectRoot });
       out.set(server.name, tools);
     } catch (err) {
       logFn(`mcp investigate failed for "${server.name}": ${err.message}`);
@@ -64,9 +68,15 @@ export async function listMcpToolsAll({ logFn = () => {}, claudeBin = 'claude',
 // full descriptor (with env/headers). Otherwise we fall back to the parsed CLI line,
 // which at minimum gives us name + transport + url (or triggers `claude mcp get` for
 // stdio command tokenisation).
+//
+// We pass `cwd: projectRoot` to the CLI so its project-scope walk-up lands in the same
+// directory we read `.mcp.json` from. Without this, `claude` walks up from the parent
+// process's cwd and can resolve a different project than `readMcpServers` does.
 export async function listMcpServers({ claudeBin = 'claude', projectRoot } = {}) {
+  const execOpts = { encoding: 'utf8' };
+  if (projectRoot) execOpts.cwd = projectRoot;
   const [{ stdout }, mcpServers] = await Promise.all([
-    execClaude(claudeBin, ['mcp', 'list'], { encoding: 'utf8' }),
+    execClaude(claudeBin, ['mcp', 'list'], execOpts),
     readMcpServers({ projectRoot }),
   ]);
   const cliList = parseMcpListOutput(stdout);
@@ -115,12 +125,12 @@ export function parseMcpListOutput(text) {
 // Fetch tools/list from a single MCP server. The `server` descriptor either came
 // from `.mcp.json` (carries env / headers) or from CLI output (bare). For stdio
 // entries without full config we fall back to `claude mcp get`.
-export async function listMcpToolsOne({ server, logFn = () => {}, claudeBin = 'claude' }) {
+export async function listMcpToolsOne({ server, logFn = () => {}, claudeBin = 'claude', projectRoot }) {
   if (server.transport === 'stdio') {
     const hasFullConfig = server.command !== undefined;
     const config = hasFullConfig
       ? { command: server.command, args: server.args ?? [], env: server.env ?? {} }
-      : await getStdioConfig({ name: server.name, claudeBin });
+      : await getStdioConfig({ name: server.name, claudeBin, projectRoot });
     return spawnAndQuery(config, server.name);
   }
   if (server.transport === 'http' || server.transport === 'sse') {
@@ -135,8 +145,12 @@ export async function listMcpToolsOne({ server, logFn = () => {}, claudeBin = 'c
 }
 
 // Parse `claude mcp get <name>` to extract Command + Args for stdio servers.
-async function getStdioConfig({ name, claudeBin }) {
-  const { stdout } = await execClaude(claudeBin, ['mcp', 'get', name], { encoding: 'utf8' });
+// `cwd: projectRoot` pins the CLI's scope walk-up to the same directory used for
+// `.mcp.json` reading — see listMcpServers for the rationale.
+async function getStdioConfig({ name, claudeBin, projectRoot }) {
+  const execOpts = { encoding: 'utf8' };
+  if (projectRoot) execOpts.cwd = projectRoot;
+  const { stdout } = await execClaude(claudeBin, ['mcp', 'get', name], execOpts);
   let command = null;
   let argsRaw = null;
   for (const rawLine of stdout.split('\n')) {

package/src/tool-db/refresh.mjs

@@ -11,12 +11,26 @@
 // sub-agents.
 
 import { resolveAll } from './lookup.mjs';
-import { listMcpToolsAll, bellVisibleName } from './investigate-mcp.mjs';
-import { getClaudeAiDescription, listClaudeAiNames } from './claude-ai-baseline.mjs';
+import { listMcpToolsAll, listMcpServers, bellVisibleName } from './investigate-mcp.mjs';
+import { getClaudeAiBaselineByServer } from './claude-ai-baseline.mjs';
 import { listSkillsAll } from './investigate-skills.mjs';
 import { listAgentsAll } from './investigate-agents.mjs';
 import { localDbPath, globalDbPath } from './loader.mjs';
 
+// Pure filter: returns the subset of the claude.ai baseline whose server name is
+// present in `presentServerNames`. Accepts a Set for O(1) membership. Extracted as
+// a named export so it can be unit-tested without a live `claude` CLI.
+export function filterClaudeAiBaseline(presentServerNames) {
+  const out = new Map();
+  for (const [serverName, tools] of getClaudeAiBaselineByServer()) {
+    if (!presentServerNames.has(serverName)) continue;
+    for (const [toolName, description] of Object.entries(tools)) {
+      out.set(toolName, description);
+    }
+  }
+  return out;
+}
+
 // 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)
@@ -27,11 +41,19 @@ import { localDbPath, globalDbPath } from './loader.mjs';
 export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin = 'claude', projectRoot } = {}) {
   const snapshot = new Map();
 
-  // Anthropic-provided `claude.ai ...` MCP servers — hardcoded because the OAuth proxy
+  // 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.
-  for (const name of listClaudeAiNames()) {
-    snapshot.set(name, getClaudeAiDescription(name));
+  // Injected only for servers actually present in `claude mcp list` — otherwise phantom
+  // tools (Gmail/Calendar/Drive) leak into environments where those servers are not
+  // connected. See filterClaudeAiBaseline above.
+  const servers = await listMcpServers({ claudeBin, projectRoot });
+  const presentServerNames = new Set(servers.map((s) => s.name));
+  const baseline = filterClaudeAiBaseline(presentServerNames);
+  for (const [name, description] of baseline) {
+    snapshot.set(name, description);
+  }
+  if (baseline.size > 0) {
+    logFn(`claude.ai baseline injected: ${baseline.size} tools from ${[...presentServerNames].filter((n) => n.startsWith('claude.ai ')).join(', ')}`);
   }
 
   // MCP servers (stdio + user-registered HTTP/SSE). projectRoot forwards for