claude-spotter 1.4.4 → 1.4.6

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 1.4.6
+
+**Codex 初回セッションが空 catalog に依存し得る穴を修正**。v1.4.5 までは
+`spotter install` が Codex hooks を登録しても Codex host-local DB は seed せず、
+初回 Codex セッションの `SessionStart` が detached `spotter db refresh --host-agent codex`
+を起動するだけだった。そのため最初の `UserPromptSubmit` が refresh 完了前に走ると
+`.spotter/tool-db.codex.json` が空 / 未作成のまま Codex auditor が動き得た。
+
+### 変更点
+
+- **編集 [src/cli/install.mjs](src/cli/install.mjs)**:
+  Codex CLI が見つかり Codex hooks を登録した project install では、Claude DB seed に続いて
+  `refresh({hostAgent:"codex"})` も同期実行し、`.spotter/tool-db.codex.json` と
+  `~/.spotter/tool-db.codex.json` を作るようにした。以降の Codex `SessionStart` bg refresh は
+  drift 追従用として残す。Codex CLI が見つからなかった場合の next steps も、Codex hooks が
+  active ではないことと `codex --version` が通る環境で再実行すべきことを明示する。
+- **編集 [test/install.test.mjs](test/install.test.mjs)**:
+  Codex hooks 登録時に Claude / Codex の両 host DB refresh が順に走ること、Codex CLI
+  unavailable 時は Codex seed へ進まないことを固定。
+- **編集 README / README.ja / docs**:
+  Codex DB は install 時に初回 seed され、SessionStart refresh は以後の drift 追従であることを明記。
+
+### ユーザー側で必要な手順
+
+1. `npm install -g claude-spotter@1.4.6`
+2. Codex を使う各プロジェクトで `spotter install` を再実行
+
+## 1.4.5
+
+**Codex global tool-db を Claude global tool-db から分離**。v1.4.4 までは local DB は
+`.spotter/tool-db.json` と `.spotter/tool-db.codex.json` に分かれていたが、refresh 時の
+description 再利用 cache は Claude / Codex とも `~/.spotter/tool-db.json` を共有していた。
+Claude 側で苦労して塞いだ「別環境の DB が監査視野に混ざる」設計事故を Codex 側で再発させないため、
+host-global DB も分離した。
+
+### 変更点
+
+- **編集 [src/tool-db/loader.mjs](src/tool-db/loader.mjs)**:
+  `globalDbPath(hostAgent)` を host-aware にし、Claude は既存互換の
+  `~/.spotter/tool-db.json`、Codex は `~/.spotter/tool-db.codex.json` を使うようにした。
+- **編集 [src/tool-db/refresh.mjs](src/tool-db/refresh.mjs)**:
+  `refresh({hostAgent})` の local → global → investigate lookup が同じ host の
+  global cache だけを見るようにした。
+- **編集 [src/cli/db-cmd.mjs](src/cli/db-cmd.mjs) / [src/cli/doctor.mjs](src/cli/doctor.mjs)**:
+  `spotter db refresh/rebuild --host-agent codex` と `spotter doctor` の表示・消去対象を
+  host-global DB に追従。
+- **編集 [test/tool-db.test.mjs](test/tool-db.test.mjs)**:
+  Claude global cache の同名 entry が Codex refresh に write-through されず、
+  Codex 側では Codex global cache / investigate を使う回帰テストを追加。
+- **編集 README / README.ja / CLAUDE.md / docs**:
+  local だけでなく global description cache も Claude / Codex で分離する設計に更新。
+
+### ユーザー側で必要な手順
+
+1. `npm install -g claude-spotter@1.4.5`
+2. 既存の shared global cache を掃除するため、各プロジェクトで
+   `spotter db rebuild` と `spotter db rebuild --host-agent codex` を 1 回ずつ実行
+3. 各プロジェクトで `spotter install`
+
 ## 1.4.4
 
 **Codex CLI auditor の default model を明示固定**。Spotter の hook 判定は高頻度・低遅延・低コストの

package/README.ja.md

@@ -105,9 +105,9 @@ flowchart LR
     DB --> H[Haiku 監査<br/>session-scoped, preamble-once]
 ```
 
-監査対象のツール (name + description) は host-local に分離されます。Claude は `<project>/.spotter/tool-db.json`、Codex は `<project>/.spotter/tool-db.codex.json` を使います。**daemon が監査に使うのは Claude local DB のみ**で、Codex native hooks は Codex local DB を読みます。グローバル DB `~/.spotter/tool-db.json` は他プロジェクトでの description 再利用キャッシュとしてのみ機能し、監査入力には混ぜません。各 host-local DB は **その host の現時点の discovery 結果と一致** (refresh 時に prune される) するため、別プロジェクトや別 host のツールリストで上書きされることはありません。
+監査対象のツール (name + description) は host-local に分離されます。Claude は `<project>/.spotter/tool-db.json`、Codex は `<project>/.spotter/tool-db.codex.json` を使います。**daemon が監査に使うのは Claude local DB のみ**で、Codex native hooks は Codex local DB を読みます。グローバル description cache も host ごとに分離され、Claude は `~/.spotter/tool-db.json`、Codex は `~/.spotter/tool-db.codex.json` を使います。これらは同じ host の他プロジェクト間でだけ再利用され、監査入力には混ぜません。各 host-local DB は **その host の現時点の discovery 結果と一致** (refresh 時に prune される) するため、別プロジェクトや別 host のツールリストで上書きされることはありません。
 
-**`spotter install` が Claude catalog の初回 seed を自動実行し、Claude Code セッション起動ごとに SessionStart hook が bg で `spotter db refresh` を走らせる**ため、Claude 通常運用で手動コマンドを叩く必要はありません。Codex CLI が使える環境では、同じ `spotter install` が Codex native hooks も登録します。Codex `SessionStart` hook は `spotter db refresh --host-agent codex` を bg 起動して `.spotter/tool-db.codex.json` を更新します。Claude catalog には書き込みません。Claude discovery は `claude mcp list` と Claude skills / sub-agents、Codex discovery は `codex mcp list/get` と Codex skills を読むため、両 host の利用可能ツール差分を別 DB として保持できます。各 MCP サーバーの `tools/list` は JSON-RPC で取得 (HTTP / SSE / stdio transport 対応)、スキルとサブエージェントは frontmatter から直接抽出、claude.ai baseline (OAuth proxy 経由の Gmail / Calendar / Drive 25 件) は Claude 側でのみ `claude mcp list` に該当サーバーが存在する環境で注入されます。**手書きでツールリストを管理する必要はありません**。
+**`spotter install` が Claude catalog の初回 seed を自動実行し、Claude Code セッション起動ごとに SessionStart hook が bg で `spotter db refresh` を走らせる**ため、Claude 通常運用で手動コマンドを叩く必要はありません。Codex CLI が使える環境では、同じ `spotter install` が Codex native hooks も登録し、`.spotter/tool-db.codex.json` も同期 seed します。これにより初回 Codex セッションから catalog を読めます。以降の Codex `SessionStart` hook は `spotter db refresh --host-agent codex` を bg 起動して `.spotter/tool-db.codex.json` を更新します。Claude catalog には書き込みません。Claude discovery は `claude mcp list` と Claude skills / sub-agents、Codex discovery は `codex mcp list/get` と Codex skills を読むため、両 host の利用可能ツール差分を別 DB として保持できます。各 MCP サーバーの `tools/list` は JSON-RPC で取得 (HTTP / SSE / stdio transport 対応)、スキルとサブエージェントは frontmatter から直接抽出、claude.ai baseline (OAuth proxy 経由の Gmail / Calendar / Drive 25 件) は Claude 側でのみ `claude mcp list` に該当サーバーが存在する環境で注入されます。**手書きでツールリストを管理する必要はありません**。
 
 ## Throughline との関係
 
@@ -132,7 +132,7 @@ spotter db refresh --host-agent codex
                          # Codex MCP / スキルから description を収集して .spotter/tool-db.codex.json を更新
                          # (Claude は install + Claude SessionStart、Codex は spotter install 後の
                          #  Codex SessionStart で自動実行されるので通常は不要)
-spotter db rebuild       # Claude local + global DB を両方消してから refresh (カタログ設計変更時のクリーン用)
+spotter db rebuild       # Claude local + Claude global DB を両方消してから refresh (カタログ設計変更時のクリーン用)
 spotter status           # 稼働中の daemon 一覧
 spotter doctor           # 環境診断 (Node / claude CLI / Codex readiness / tool-db 整合性)
 spotter diagnostics logs # daemon log から pass=false / backend latency / anomaly signal を集計

package/README.md

@@ -105,9 +105,9 @@ flowchart LR
     DB --> H[Haiku audit<br/>session-scoped, preamble-once]
 ```
 
-The audited catalog is host-local: Claude uses `<project>/.spotter/tool-db.json`, while Codex uses `<project>/.spotter/tool-db.codex.json`. **The daemon audits against the Claude local DB only**, and Codex native hooks read the Codex local DB. The global DB at `~/.spotter/tool-db.json` is a description-reuse cache shared across projects, not an audit source. Each host-local DB matches that host's **current** discovery snapshot for the project (stale entries are pruned on refresh), so tools from another project or another host cannot overwrite this session's audit catalog.
+The audited catalog is host-local: Claude uses `<project>/.spotter/tool-db.json`, while Codex uses `<project>/.spotter/tool-db.codex.json`. **The daemon audits against the Claude local DB only**, and Codex native hooks read the Codex local DB. Global description caches are host-specific too: Claude uses `~/.spotter/tool-db.json`, while Codex uses `~/.spotter/tool-db.codex.json`. They are shared only across projects for the same host and are never audit sources. Each host-local DB matches that host's **current** discovery snapshot for the project (stale entries are pruned on refresh), so tools from another project or another host cannot overwrite this session's audit catalog.
 
-**`spotter install` seeds the Claude catalog automatically, and the SessionStart hook runs a background `spotter db refresh` on every Claude Code session start** — so you don't need to invoke Claude catalog commands by hand. When Codex CLI is available, the same `spotter install` registers Codex native hooks; their `SessionStart` hook starts `spotter db refresh --host-agent codex` in the background, updating `.spotter/tool-db.codex.json` without touching the Claude catalog. Claude discovery reads `claude mcp list` plus Claude skills / sub-agents; Codex discovery reads `codex mcp list/get` plus Codex skills. Each MCP server's `tools/list` is fetched via JSON-RPC (HTTP / SSE / stdio transports supported); skill and sub-agent metadata comes straight from frontmatter; the claude.ai baseline (25 hand-curated entries for Gmail / Calendar / Drive over OAuth proxy) is injected only for Claude when `claude mcp list` confirms the server is present. **You never have to maintain the tool list by hand.**
+**`spotter install` seeds the Claude catalog automatically, and the SessionStart hook runs a background `spotter db refresh` on every Claude Code session start** — so you don't need to invoke Claude catalog commands by hand. When Codex CLI is available, the same `spotter install` registers Codex native hooks and seeds `.spotter/tool-db.codex.json` synchronously, so the first Codex session has a catalog too. Later Codex `SessionStart` hooks start `spotter db refresh --host-agent codex` in the background, updating `.spotter/tool-db.codex.json` without touching the Claude catalog. Claude discovery reads `claude mcp list` plus Claude skills / sub-agents; Codex discovery reads `codex mcp list/get` plus Codex skills. Each MCP server's `tools/list` is fetched via JSON-RPC (HTTP / SSE / stdio transports supported); skill and sub-agent metadata comes straight from frontmatter; the claude.ai baseline (25 hand-curated entries for Gmail / Calendar / Drive over OAuth proxy) is injected only for Claude when `claude mcp list` confirms the server is present. **You never have to maintain the tool list by hand.**
 
 ## Spotter and Throughline
 
@@ -132,7 +132,7 @@ spotter db refresh --host-agent codex
                          # rediscover Codex MCP / skills and update .spotter/tool-db.codex.json
                          #   (Claude refresh is automatic on install + Claude SessionStart;
                          #    Codex refresh is automatic on Codex SessionStart after spotter install)
-spotter db rebuild       # wipe Claude local + global DBs and refresh from scratch
+spotter db rebuild       # wipe Claude local + Claude global DBs and refresh from scratch
                          #   (use after catalog-shape changes)
 spotter status           # list running daemons
 spotter doctor           # environment check (Node / claude CLI / Codex readiness / tool-db integrity)
@@ -189,7 +189,7 @@ those values for smoke tests or controlled experiments.
 <summary><strong>📋 Recent highlights</strong></summary>
 
 - **Plugin-scoped MCP servers** — names like `plugin:everything-claude-code:context7` (with internal colons) are now parsed correctly and their tools enter the catalog. Earlier versions silently collapsed all plugin MCP servers into a single literal `"plugin"`, dropping their tools from Bell's audit
-- **Per-project audit isolation** — the daemon audits against the local DB only; the global DB has been demoted to a description-reuse cache. Tools discovered in *other* projects can never bleed into this project's audit set
+- **Per-project / per-host audit isolation** — the daemon audits against the local DB only; global DBs are host-specific description caches. Tools discovered in *other* projects or another host can never bleed into this project's audit set
 - **Zero-touch catalog** — `spotter install` seeds the Claude DB automatically; Claude and Codex SessionStart hooks keep their host-local DBs fresh in the background. You never have to maintain the tool list by hand
 - **Codex native hooks** — Codex host uses Codex CLI as the primary auditor backend, keeps a separate `.spotter/tool-db.codex.json`, and surfaces backend failures explicitly instead of falling back to Haiku
 - **Audit scope** — only user-added surface (MCP servers / skills / sub-agents). Claude Code's built-in tools are intentionally out of scope; Bell already uses those reliably

package/package.json

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

package/src/cli/db-cmd.mjs

@@ -2,7 +2,7 @@
 //
 //   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 + global DBs then refresh (forces re-investigation)
+//   spotter db rebuild          — wipe host-local + host-global DBs then refresh
 //
 // Run inside a project that has been `spotter install`-ed.
 
@@ -52,20 +52,19 @@ export async function runDbRefresh({ argv = [] } = {}) {
   process.stdout.write(
     `${resolved.size} tool(s) resolved (local=${counts.local}, global=${counts.global}, investigated=${counts.investigated})\n`
       + `local DB:  ${localDbPath(projectRoot, opts.hostAgent)}\n`
-      + `global DB: ${globalDbPath()}\n`
+      + `global DB: ${globalDbPath(opts.hostAgent)}\n`
   );
 }
 
 export async function runDbRebuild({ argv = [] } = {}) {
   const projectRoot = requireProjectRoot();
   const opts = parseDbArgs(argv);
-  // 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.
+  // Wipe BOTH host-local and host-global DB. Rationale: catalog scope changes and
+  // description drift must not leak between Claude and Codex; each host cache is a
+  // separate clean-slate unit.
   await saveDb(localDbPath(projectRoot, opts.hostAgent), emptyDb());
-  await saveDb(globalDbPath(), emptyDb());
-  process.stderr.write(`spotter db rebuild: cleared ${opts.hostAgent} local + global DB, refreshing...\n`);
+  await saveDb(globalDbPath(opts.hostAgent), emptyDb());
+  process.stderr.write(`spotter db rebuild: cleared ${opts.hostAgent} local + ${opts.hostAgent} global DB, refreshing...\n`);
   await runDbRefresh({ argv });
 }
 

package/src/cli/doctor.mjs

@@ -78,15 +78,18 @@ export async function runDoctor() {
     if (!sidecar.ok) warnings += 1;
   }
 
-  // tool-db (global cache). Since v1.2.0 this is not part of daemon audit input;
-  // the daemon audits the project-local DB only. Empty global cache is fine.
-  try {
-    const global = await loadDb(globalDbPath());
-    const count = Object.keys(global.tools).length;
-    mark(true, `global cache DB: ${count} tools at ${globalDbPath()}`);
-  } catch (err) {
-    mark(false, 'global cache DB', `${err.message} (cache only; daemon audits local DB)`);
-    warnings += 1;
+  // tool-db (host-specific global caches). Since v1.2.0 these are not part of
+  // audit input; each host audits its project-local DB only. Empty caches are fine.
+  for (const hostAgent of ['claude', 'codex']) {
+    try {
+      const path = globalDbPath(hostAgent);
+      const global = await loadDb(path);
+      const count = Object.keys(global.tools).length;
+      mark(true, `${hostAgent} global cache DB: ${count} tools at ${path}`);
+    } catch (err) {
+      mark(false, `${hostAgent} global cache DB`, `${err.message} (cache only; audit uses local DB)`);
+      warnings += 1;
+    }
   }
 
   // tool-db (local) if cwd is inside a Spotter project. Claude and Codex use

package/src/cli/install.mjs

@@ -120,9 +120,11 @@ export async function runInstall({
     console.log(`wrote ${settingsPath}`);
   }
 
+  let codexHooksRegistered = false;
   if (target === 'project' && !skipCodexHooks) {
     if (codexCliPresentFn()) {
       const result = await installCodexHooksFn();
+      codexHooksRegistered = true;
       console.log('  Codex hooks registered');
       console.log(`  Codex hooks: ${result.hooksPath}`);
     } else {
@@ -140,23 +142,33 @@ export async function runInstall({
     console.log('\ndiscovering MCP servers, skills, and sub-agents...');
     const log = (msg) => process.stderr.write(`  ${msg}\n`);
     try {
-      const resolved = await refreshFn({ projectRoot: cwd, hostAgent: 'claude', logFn: log });
-      console.log(`  ${resolved.size} tool(s) resolved`);
-      console.log(`  local DB:  ${localDbPath(cwd, 'claude')}`);
-      console.log(`  global DB: ${globalDbPath()}`);
+      const claudeResolved = await refreshFn({ projectRoot: cwd, hostAgent: 'claude', logFn: log });
+      console.log(`  ${claudeResolved.size} Claude tool(s) resolved`);
+      console.log(`  Claude local DB:  ${localDbPath(cwd, 'claude')}`);
+      console.log(`  Claude global DB: ${globalDbPath('claude')}`);
+      if (codexHooksRegistered) {
+        const codexResolved = await refreshFn({ projectRoot: cwd, hostAgent: 'codex', logFn: log });
+        console.log(`  ${codexResolved.size} Codex tool(s) resolved`);
+        console.log(`  Codex local DB:  ${localDbPath(cwd, 'codex')}`);
+        console.log(`  Codex global DB: ${globalDbPath('codex')}`);
+      }
     } catch (err) {
       // §0: throw (fallback 禁止). But surface the recovery path so the user isn't
       // left with "hooks registered, tool-db missing" and no clue what to run.
       process.stderr.write(`\nspotter install: tool-db seeding failed.\n`);
       process.stderr.write(`  hooks are registered but tool-db is not ready.\n`);
-      process.stderr.write(`  recover with: spotter db refresh\n`);
+      process.stderr.write(`  recover with: spotter db refresh and, for Codex, spotter db refresh --host-agent codex\n`);
       throw err;
     }
   }
 
   console.log('\nnext steps:');
   console.log('  reload Claude Code (or open a new session) to activate Spotter');
-  console.log('  open a new Codex session to activate Codex hooks when Codex CLI is installed');
+  if (codexHooksRegistered) {
+    console.log('  open a new Codex session to activate Codex hooks');
+  } else if (target === 'project' && !skipCodexHooks) {
+    console.log('  Codex hooks are not active: rerun `spotter install` where `codex --version` succeeds');
+  }
 }
 
 async function exists(path) {

package/src/tool-db/loader.mjs

@@ -3,7 +3,8 @@
 // Two layers:
 //   - local:  <project>/.spotter/tool-db.json          (Claude host)
 //             <project>/.spotter/tool-db.codex.json    (Codex host)
-//   - global: ~/.spotter/tool-db.json
+//   - global: ~/.spotter/tool-db.json                  (Claude host)
+//             ~/.spotter/tool-db.codex.json            (Codex host)
 //
 // Both have the same shape:
 //   { "version": 1, "tools": { "<name>": "<description>", ... } }
@@ -22,8 +23,10 @@ export class ToolDbSchemaError extends Error {
   }
 }
 
-export function globalDbPath() {
-  return join(homedir(), '.spotter', 'tool-db.json');
+export function globalDbPath(hostAgent = 'claude') {
+  const host = normalizeToolDbHostAgent(hostAgent);
+  const file = host === 'claude' ? 'tool-db.json' : `tool-db.${host}.json`;
+  return join(homedir(), '.spotter', file);
 }
 
 export function localDbPath(projectRoot, hostAgent = 'claude') {

package/src/tool-db/refresh.mjs

@@ -101,14 +101,14 @@ export async function refresh({
   return resolveAll({
     toolNames,
     localPath: localDbPath(projectRoot, toolDbHostAgent),
-    globalPath: globalDbPath(),
+    globalPath: globalDbPath(toolDbHostAgent),
     investigate,
     logFn,
   });
 }
 
 // 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
+// specific project can actually use. The host-specific global DB is a cache 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.