claude-spotter 1.4.5 → 1.4.8

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # Changelog
 
+## 1.4.8
+
+**Hook 挙動 parity (Codex → Claude) 移植**。Codex 側で確定していた 3 つの hook 挙動 — Stop
+short-skip / Stop deferred delivery / hook event JSONL ログ — を Claude 側にも適用し、
+両 host で同じ思想で動くよう揃えた。`decision:"block"` は Claude hook から完全撤去された。
+
+### 変更点
+
+- **編集 [src/daemon/daemon.mjs](src/daemon/daemon.mjs)** (Phase A):
+  `handleTurnEnd` 冒頭に short-final + 0 used_tools の skip 分岐を追加。最終応答が ≤120 chars
+  (code-point 単位) かつ used_tools 0 件のとき auditor を呼ばずに
+  `{pass:true, reason:"short_final_no_tools"}` を即返す。`SPOTTER_STOP_SHORT_FINAL_MAX_CHARS`
+  で閾値変更、`<= 0` で機能無効化。Codex 側 `shouldSkipShortCodexStop` と同じ判定軸。
+  pure helper `shouldSkipShortStop` / `resolveStopShortFinalMaxChars` を export。
+- **編集 [src/hooks/stop.mjs](src/hooks/stop.mjs)** (Phase B):
+  `decision:"block"` を撤去。daemon が `pass:false` を返したら、
+  `<projectRoot>/.spotter/pending/<sessionId>.json` に指摘テキスト (formatTransparentBlockReason
+  の同じ wording) を append し、stdout は空のまま exit 0。次の UserPromptSubmit が drain して
+  `additionalContext` で配信する。`stop_hook_active:true` の早期 pass は維持。
+- **編集 [src/hooks/user-prompt.mjs](src/hooks/user-prompt.mjs)** (Phase B):
+  入口で `<projectRoot>/.spotter/pending/<sessionId>.json` を drain → `additionalContext` に統合。
+  daemon の `pass:false` 結果と pending drain は同じ `additionalContext` に合体。短プロンプト
+  早期 return 経路でも drain は走るので pending が一時返答に詰まらない。
+- **新規 [src/hooks/pending-context.mjs](src/hooks/pending-context.mjs)** (Phase B):
+  共有 pending queue helper (`pendingPath` / `appendPendingContext` / `drainPendingContexts` /
+  `readPendingContexts`)。Claude / Codex 両 host から同じ実装を通る。pending file は
+  `<projectRoot>/.spotter/pending/<sanitized-id>.json`、JSON 配列形式、識別 dedupe。
+- **編集 [src/cli/codex-hook-cmd.mjs](src/cli/codex-hook-cmd.mjs)** (Phase B + Phase D):
+  Codex 側 private `codexPendingPath` / `appendCodexPendingContext` / `drainCodexPendingContexts`
+  / `readCodexPendingContexts` を共有 helper に置換、`CODEX_PENDING_DIR` 定数撤去。
+  `appendCodexHookEvent` は `appendHookEvent({host:'codex'})` の薄い wrapper に変更し、
+  `summarizeCodexHookEvents` は host:codex でフィルタする wrapper にして既存 export 名互換を維持。
+  pending 保存先を `.spotter/codex-pending/` から host-neutral `.spotter/pending/` に移行。
+- **新規 [src/core/hook-event-log.mjs](src/core/hook-event-log.mjs)** (Phase D):
+  host-neutral hook event JSONL helper (`appendHookEvent` / `appendHookEventSafe` /
+  `summarizeHookEvents` / `hookEventsPath` / schema 定数)。schema は
+  `spotter.hook_event.v1`、`host: "claude" | "codex"` フィールドを必須化。
+- **編集 Claude 側 hook 5 種** (Phase D):
+  `src/hooks/{session-start,user-prompt,pre-tool-use,stop,session-end}.mjs` に
+  `recordClaudeHookEvent` 経由で hook event JSONL に append。各 hook の status / reason /
+  durationMs / pendingContextCount / missingTools が `<projectRoot>/.spotter/hook-events.jsonl`
+  に時系列で記録される。Codex 側 records と同一ファイル / 同一 schema。
+- **編集 [src/hooks/lib.mjs](src/hooks/lib.mjs)** (Phase D):
+  Claude hook 用の `recordClaudeHookEvent` ヘルパ追加 (best-effort、失敗は stderr へ warn のみで
+  hook 自体は壊さない)。
+- **編集 [src/cli/diagnostics-cmd.mjs](src/cli/diagnostics-cmd.mjs)** (Phase D):
+  `--project DIR` option 追加 (default: cwd)。daemon log の集計に加えて
+  `<projectRoot>/.spotter/hook-events.jsonl` も読み、`hookEvents` セクションに
+  `byHost` / `byHook` / `byStatus` / `byBackend` / 平均 / 最大 duration を出力。
+- **編集 test/** (Phase A/B/D 合わせて 37 件追加 / 3 件 short-skip 干渉回避):
+  test/daemon.test.mjs (Phase A 13 件), test/hooks.test.mjs (Phase B 13 件),
+  test/hook-event-log.test.mjs (Phase D 11 件)。フルスイート 320 tests / 319 pass / 1 skip。
+
+### 安全制約 (変更なし)
+
+`SPOTTER_PARENT_PID` / `SPOTTER_BACKEND` / `SPOTTER_CHILD_BACKEND` / `agent_id` /
+`source === "startup"` / `.spotter/marker.json` / PID preexist check / 10 秒 Haiku call window
+はすべて v1.4.7 と同じ仕様を維持。daemon の auditor 経路 (`createAuditorBackend` /
+`createCodexCliAuditorBackend`) も無変更。Backend 取り扱い (Phase 5 / v1.4.7 で完了済み) も
+無変更。Backend error / transport error は引き続き hook が exit 1 + stderr で表面化し、pending
+queue へは混ぜない (silent fallback 禁止)。
+
+### ユーザー側で必要な手順
+
+1. `npm install -g claude-spotter@1.4.8`
+2. 各プロジェクトで `spotter install` 再実行 (新 hook event JSONL の path 整合のため)
+3. 既存 `<projectRoot>/.spotter/codex-pending/` ディレクトリは v1.4.8 では参照されなくなる
+   (新パスは `.spotter/pending/`)。残存 file は手動削除可、自動 cleanup はしない
+4. 既存 `<projectRoot>/.spotter/codex-hook-events.jsonl` も v1.4.8 では新規書き込みされず、
+   新ファイルは `.spotter/hook-events.jsonl`。古い JSONL は手動 archive / 削除が望ましい
+
+### 検証
+
+- `node --test` 320 tests / 319 pass / 1 skip 緑
+- 実セッション smoke は Spotter 自身のリポジトリでは self-referential 制約のため実施せず。
+  別プロジェクトでの実セッション smoke と数日分 diagnostics は rollout 観測フェーズに回す
+
+## 1.4.7
+
+**Claude host の opt-in `next` policy を Codex CLI primary auditor に切り替え (Phase 5)**。
+v1.4.6 までは `SPOTTER_AUDITOR_BACKEND_POLICY=next` を Claude host で立てても
+`policy_next_claude_held_for_phase5` のまま Haiku に張り付いていた。Phase 4 matrix smoke
+(2026-05-06, GeForce 5000 fixture) で `claude.codex-cli=10041ms` /
+`claude.codex-sidecar=12863ms` と Codex CLI が latency 優位、かつ Haiku diagnostics 平均が
+`user_input ~14.3s / turn_end ~16.6s` だったため、Claude host も `next` で Codex CLI を
+選ぶようにした。Codex host 既定 (`v1.4.3` で固定) と同じ判定軸。
+
+### 変更点
+
+- **編集 [src/core/auditor-backend.mjs](src/core/auditor-backend.mjs)**:
+  `selectByPolicy` の Claude+`next` 経路を Codex CLI に変更
+  (`reason=policy_next_claude_codex_cli`, `compatibility=none`)。`current` policy と
+  `SPOTTER_AUDITOR_BACKEND=haiku` 明示時のみ Haiku を維持する。Codex CLI が unavailable /
+  timeout / schema invalid / non-zero exit の場合、`createCodexCliAuditorBackend` が
+  既存通り `AuditorBackendError` を投げ、daemon は Haiku に hidden fallback せず
+  structured error として hook に伝搬する。
+- **編集 [test/auditor-backend.test.mjs](test/auditor-backend.test.mjs)**:
+  Phase 1 用の "held for phase5" 固定を Phase 5 後の挙動 (Claude+`next` →
+  `policy_next_claude_codex_cli`) に置き換え、`current` policy が両 host で Haiku を維持する
+  test、Claude+`next` で `SPOTTER_AUDITOR_BACKEND=haiku` 明示が依然として Haiku を選ぶ
+  互換 test、`createAuditorBackend` factory が `auto` + Claude + `next` で Codex CLI backend を
+  返す factory-level test を追加。
+- **編集 [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md)** /
+  [docs/archive/SPOTTER_PRIMARY_BACKEND_TODO.md](docs/archive/SPOTTER_PRIMARY_BACKEND_TODO.md) /
+  [docs/open-issues.md](docs/open-issues.md):
+  Claude host の `current` / `next` policy 表と Phase 5 ゲート、Haiku compatibility が
+  `current` policy または `SPOTTER_AUDITOR_BACKEND=haiku` 明示時のみであること、hidden
+  fallback 不可を明記。
+
+### 安全制約 (変更なし)
+
+`SPOTTER_PARENT_PID`, `SPOTTER_BACKEND`, `SPOTTER_CHILD_BACKEND`, `agent_id`,
+`source === "startup"`, `.spotter/marker.json`, PID preexist check, 10 秒 Haiku call window
+は全て v1.4.6 と同じ仕様を維持。Codex CLI auditor child は引き続き
+`--ephemeral --ignore-user-config --ignore-rules --sandbox read-only` + recursion marker env で
+spawn される。
+
+### ユーザー側で必要な手順
+
+1. `npm install -g claude-spotter@1.4.7`
+2. Claude host の `next` policy を試したいプロジェクトで
+   `SPOTTER_AUDITOR_BACKEND_POLICY=next` をセット (例: shell rc / `.envrc`)
+3. Codex CLI が PATH にあること、`codex --version` が通ることを確認
+4. `current` policy (= 既存 Haiku 動作) は明示変更しない限り維持される
+
+### 検証
+
+- `node --test` 緑化
+- 実セッション smoke は Spotter 自身のリポジトリでは self-referential 制約があるため
+  実施しない。代替として Phase 4 matrix smoke (2026-05-06) と Phase 5 unit test を gate に
+  使う。別プロジェクトでの実セッション smoke と数日分 diagnostics は Phase 7 rollout 観測で
+  追って計測する。
+
+## 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 は

package/README.ja.md

@@ -75,8 +75,8 @@ flowchart TD
     BA --> SH[Stop hook<br/>応答と使用済みツールから最終チェック]
     SH --> DEC{見落とし<br/>あり?}
     DEC -->|なし| DONE([完了])
-    DEC -->|あり| SB[差し戻し<br/>max 1 回<br/>stop_hook_active で自動担保]
-    SB --> BA2([Bell の補正応答]) --> DONE
+    DEC -->|あり| SB[.spotter/pending/ に積む<br/>v1.4.8 deferred delivery]
+    SB --> NEXT([次の UserPromptSubmit で<br/>additionalContext として配信])
 ```
 
 ### カタログの収集経路
@@ -107,7 +107,7 @@ flowchart LR
 
 監査対象のツール (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 との関係
 
@@ -178,8 +178,8 @@ Codex CLI auditor の子プロセスは、hook 判定を安く速く保つため
 
 ## 既知の制約
 
-- Stop hook は Bell の最初の応答が**出力された後**に発火するため、Spotter が Stop で差し戻した場合、ユーザーは「最初の応答 + 補正応答」の 2 連続を見ます (Claude Code の hook 仕様による制約)。UserPromptSubmit 段階での先回り検出を精度の軸にしています
-- Codex native `Stop` は **即時ブロックではなく遅延配送**です。Codex `Stop` で不足ツールを見つけた場合、Spotter は `.spotter/codex-pending/` に指摘を保存し、次の same-session `UserPromptSubmit` で `additionalContext` として提示します。これは Codex の現行 `decision:"block"` が `Stop Blocked` / exit code 1 になりやすい実測結果を避けるためです
+- v1.4.8 以降、Claude / Codex 両 host で `Stop` hook は **遅延配送 (deferred delivery)** に統一されました。`Stop` で見落としツールを検出した場合、Spotter は `<projectRoot>/.spotter/pending/<sessionId>.json` に指摘を積み、次の same-session `UserPromptSubmit` で `additionalContext` として配信します。当ターンの最初の応答は transcript にそのまま残るため、`decision:"block"` で補正サイクルを回す方式の「最終応答が補正中心になって元の文脈が迷子」問題が解消します (Codex 側は `Stop Blocked` / exit code 1 回避も兼ねる)
+- pending ファイルは Claude / Codex が同じパス (`.spotter/pending/`) を共有します。host-neutral 設計です
 - **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>

package/README.md

@@ -75,8 +75,8 @@ flowchart TD
     BA --> SH[Stop hook<br/>Spotter re-audits answer + tools used]
     SH --> DEC{Missed<br/>tool?}
     DEC -->|No| DONE([Done])
-    DEC -->|Yes| SB[Send-back to Bell<br/>max 1 round<br/>guarded by stop_hook_active]
-    SB --> BA2([Bell's amended answer]) --> DONE
+    DEC -->|Yes| SB[Queue finding to .spotter/pending/<br/>v1.4.8 deferred delivery]
+    SB --> NEXT([Surfaces as additionalContext<br/>on next UserPromptSubmit])
 ```
 
 ### Catalog discovery
@@ -107,7 +107,7 @@ flowchart LR
 
 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
 
@@ -182,7 +182,7 @@ those values for smoke tests or controlled experiments.
 ## 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
-- Codex native `Stop` is **deferred**, not an immediate block. If Spotter finds a missed tool at Codex `Stop`, it writes the finding to `.spotter/codex-pending/` and surfaces it on the next same-session `UserPromptSubmit` as `additionalContext`. This avoids Codex's current `Stop Blocked` / exit-code-1 behavior for `decision:"block"`
+- `Stop` hook is **deferred** for both Claude and Codex hosts as of v1.4.8. When Spotter finds a missed tool at `Stop`, it appends the finding to `<projectRoot>/.spotter/pending/<sessionId>.json` and surfaces it on the next same-session `UserPromptSubmit` as `additionalContext`. The original assistant message stays as the turn's final transcript entry — no `decision:"block"` re-generation cycle. The same pending file is shared by Claude and Codex (host-neutral path)
 - **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>

package/package.json

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

package/src/cli/codex-hook-cmd.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { appendFile, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -18,6 +18,15 @@ import {
   readStdinJson,
   requireString,
 } from '../hooks/lib.mjs';
+import {
+  appendPendingContext,
+  drainPendingContexts,
+} from '../hooks/pending-context.mjs';
+import {
+  appendHookEvent,
+  hookEventsPath,
+  summarizeHookEvents,
+} from '../core/hook-event-log.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
@@ -26,8 +35,6 @@ const CODEX_HOOK_TIMEOUT_SEC = 60;
 const DEFAULT_CODEX_HOOK_AUDITOR_TIMEOUT_MS = 20_000;
 const SHORT_PROMPT_MAX_CHARS = 10;
 const DEFAULT_CODEX_STOP_SHORT_FINAL_MAX_CHARS = 120;
-const CODEX_PENDING_DIR = 'codex-pending';
-const CODEX_HOOK_EVENTS_FILE = 'codex-hook-events.jsonl';
 
 const CODEX_HOOK_USAGE = `spotter codex-hook — Codex native hook adapter
 
@@ -114,7 +121,7 @@ export async function runCodexUserPromptSubmitHook({
   const startedAt = Date.now();
 
   const prompt = requireString(input, 'prompt');
-  const contexts = await drainCodexPendingContexts({ projectRoot, sessionId: codexSessionId(input) });
+  const contexts = await drainPendingContexts({ projectRoot, sessionId: codexSessionId(input) });
   if ([...prompt.trim()].length <= SHORT_PROMPT_MAX_CHARS) {
     await recordCodexHookEventSafe(recordHookEventFn, {
       projectRoot,
@@ -213,7 +220,7 @@ export async function runCodexStopHook({
   } catch (err) {
     const errorText = formatCodexHookBackendError(err);
     writeError(`${errorText}\n`);
-    await appendCodexPendingContext({
+    await appendPendingContext({
       projectRoot,
       sessionId: codexSessionId(input),
       text: errorText,
@@ -248,7 +255,7 @@ export async function runCodexStopHook({
     return;
   }
 
-  await appendCodexPendingContext({
+  await appendPendingContext({
     projectRoot,
     sessionId: codexSessionId(input),
     text: formatTransparentBlockReason(legacyResultFromJudgment(judgment).missing_tools),
@@ -450,60 +457,17 @@ function codexSessionId(payload) {
   return typeof value === 'string' && value.length > 0 ? value : null;
 }
 
-function codexPendingPath({ projectRoot, sessionId }) {
-  if (!sessionId) return null;
-  const clean = sessionId.replace(/[^A-Za-z0-9_-]/g, '');
-  if (!clean) return null;
-  return join(projectRoot, '.spotter', CODEX_PENDING_DIR, `${clean}.json`);
-}
-
-async function appendCodexPendingContext({ projectRoot, sessionId, text }) {
-  const path = codexPendingPath({ projectRoot, sessionId });
-  const value = String(text ?? '').trim();
-  if (!path || !value) return false;
-  const contexts = await readCodexPendingContexts(path);
-  if (!contexts.includes(value)) contexts.push(value);
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(contexts, null, 2) + '\n', 'utf8');
-  return true;
-}
-
-async function drainCodexPendingContexts({ projectRoot, sessionId }) {
-  const path = codexPendingPath({ projectRoot, sessionId });
-  if (!path) return [];
-  const contexts = await readCodexPendingContexts(path);
-  if (contexts.length > 0) {
-    try {
-      await unlink(path);
-    } catch (err) {
-      if (err.code !== 'ENOENT') throw err;
-    }
-  }
-  return contexts;
-}
-
-async function readCodexPendingContexts(path) {
-  try {
-    const raw = await readFile(path, 'utf8');
-    const parsed = JSON.parse(raw);
-    return Array.isArray(parsed)
-      ? parsed.map((item) => typeof item === 'string' ? item.trim() : '').filter(Boolean)
-      : [];
-  } catch (err) {
-    if (err.code === 'ENOENT') return [];
-    throw err;
-  }
-}
+// Phase B (hook parity, 2026-05-08): pending-context helpers were moved to
+// `src/hooks/pending-context.mjs` and the on-disk path migrated from
+// `.spotter/codex-pending/` to host-neutral `.spotter/pending/`. The Claude Stop hook
+// now writes to the same queue.
 
+// Phase D (hook parity, 2026-05-08): Codex hook events now go through the host-neutral
+// `appendHookEvent` so Claude / Codex events live in the same `.spotter/hook-events.jsonl`.
+// Kept as an internal wrapper so existing call sites (and the `recordHookEventFn` DI knob
+// in tests) can stay on the same shape.
 async function appendCodexHookEvent({ projectRoot, event }) {
-  const value = {
-    schema: 'spotter.codex_hook_event.v1',
-    timestamp: new Date().toISOString(),
-    ...event,
-  };
-  const path = codexHookEventsPath(projectRoot);
-  await mkdir(dirname(path), { recursive: true });
-  await appendFile(path, JSON.stringify(value) + '\n', 'utf8');
+  await appendHookEvent({ projectRoot, host: 'codex', event });
 }
 
 async function recordCodexHookEventSafe(recordHookEventFn, input, writeError) {
@@ -514,17 +478,24 @@ async function recordCodexHookEventSafe(recordHookEventFn, input, writeError) {
   }
 }
 
+// Phase D (hook parity, 2026-05-08): Codex `--project` diagnostics now read the host-neutral
+// `<projectRoot>/.spotter/hook-events.jsonl` and filter to `host:"codex"` so the existing
+// `codex-hook diagnostics` shape (counts of just Codex events) stays intact.
 export async function summarizeCodexHookEvents({ projectRoot, readFileFn = readFile } = {}) {
   if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
     throw new TypeError('summarizeCodexHookEvents: projectRoot must be a non-empty string');
   }
+  const full = await summarizeHookEvents({ projectRoot, readFileFn });
+  // Re-aggregate with a Codex-only filter so the legacy diagnostics caller doesn't see Claude
+  // entries pulled in from the unified file. We re-read the JSONL ourselves to keep counts
+  // exact (summarizeHookEvents already iterated, but it folded Claude entries in).
   const summary = {
-    schema: 'spotter.codex_hook_events_summary.v1',
+    schema: 'spotter.hook_events_summary.v1',
     projectRoot,
-    logPath: codexHookEventsPath(projectRoot),
-    exists: false,
+    logPath: hookEventsPath(projectRoot),
+    exists: full.exists,
     events: 0,
-    parseErrors: 0,
+    parseErrors: full.parseErrors,
     byHook: {},
     byStatus: {},
     byBackend: {},
@@ -532,19 +503,19 @@ export async function summarizeCodexHookEvents({ projectRoot, readFileFn = readF
     maxDurationMs: 0,
     recent: [],
   };
+  if (!summary.exists) return summary;
   let totalDurationMs = 0;
   try {
     const raw = await readFileFn(summary.logPath, 'utf8');
-    summary.exists = true;
     for (const line of raw.split(/\r?\n/)) {
       if (!line.trim()) continue;
       let event;
       try {
         event = JSON.parse(line);
       } catch {
-        summary.parseErrors += 1;
         continue;
       }
+      if (event.host !== 'codex') continue;
       summary.events += 1;
       incrementCounter(summary.byHook, event.hook ?? 'unknown');
       incrementCounter(summary.byStatus, event.status ?? 'unknown');
@@ -577,10 +548,6 @@ function compactCodexHookEvent(event) {
   };
 }
 
-function codexHookEventsPath(projectRoot) {
-  return join(projectRoot, '.spotter', CODEX_HOOK_EVENTS_FILE);
-}
-
 function incrementCounter(counter, key) {
   counter[key] = (counter[key] ?? 0) + 1;
 }

package/src/cli/diagnostics-cmd.mjs

@@ -1,10 +1,14 @@
 import { resolve } from 'node:path';
 import { defaultDaemonLogDir, summarizeDaemonLogs } from '../core/daemon-log-diagnostics.mjs';
+import { summarizeHookEvents } from '../core/hook-event-log.mjs';
 
 const DIAGNOSTICS_USAGE = `spotter diagnostics — read-only operational diagnostics
 
 Usage:
-  spotter diagnostics logs [--log-dir DIR] [--json]
+  spotter diagnostics logs [--log-dir DIR] [--project DIR] [--json]
+
+  --log-dir   daemon log directory (default: ~/.spotter/runtime)
+  --project   project root for hook-events.jsonl (default: cwd)
 `;
 
 export async function runDiagnosticsCommand({ argv = process.argv.slice(2) } = {}) {
@@ -20,15 +24,21 @@ export async function runDiagnosticsCommand({ argv = process.argv.slice(2) } = {
 export async function runDiagnosticsLogsCommand({
   argv = [],
   summarizeDaemonLogsFn = summarizeDaemonLogs,
+  summarizeHookEventsFn = summarizeHookEvents,
   writeOutput = (text) => process.stdout.write(text),
 } = {}) {
   const opts = parseLogsArgs(argv);
   const summary = await summarizeDaemonLogsFn({ logDir: opts.logDir });
+  // Phase D (hook parity, 2026-05-08): hook-event JSONL read alongside daemon log so
+  // the hook-side observations (skip reasons, drained pending counts, transport errors
+  // that never reach the daemon) surface in the same diagnostics output.
+  const hookEvents = await summarizeHookEventsFn({ projectRoot: opts.projectRoot });
+  const merged = { ...summary, hookEvents };
   if (opts.json) {
-    writeOutput(JSON.stringify(summary, null, 2) + '\n');
+    writeOutput(JSON.stringify(merged, null, 2) + '\n');
     return;
   }
-  writeOutput(formatDaemonLogSummary(summary));
+  writeOutput(formatDaemonLogSummary(merged));
 }
 
 export function formatDaemonLogSummary(summary) {
@@ -80,12 +90,40 @@ export function formatDaemonLogSummary(summary) {
     `  codex_risk_check: dispatched=${summary.codexRiskCheck.dispatched}, disabled_skips=${summary.codexRiskCheck.disabledSkips}, no_project_skips=${summary.codexRiskCheck.noProjectRootSkips}, failures=${summary.codexRiskCheck.dispatchFailures}`
   );
 
+  // Phase D (hook parity): host-neutral hook-events.jsonl summary if present.
+  const hookEvents = summary.hookEvents;
+  if (hookEvents) {
+    if (!hookEvents.exists) {
+      lines.push(`  hook-events.jsonl: not present (path=${hookEvents.logPath})`);
+    } else {
+      lines.push(
+        `  hook-events.jsonl: events=${hookEvents.events}, parse_errors=${hookEvents.parseErrors}, avg=${hookEvents.averageDurationMs}ms, max=${hookEvents.maxDurationMs}ms`
+      );
+      const byHost = formatCounter(hookEvents.byHost);
+      if (byHost) lines.push(`    by host: ${byHost}`);
+      const byHook = formatCounter(hookEvents.byHook);
+      if (byHook) lines.push(`    by hook: ${byHook}`);
+      const byStatus = formatCounter(hookEvents.byStatus);
+      if (byStatus) lines.push(`    by status: ${byStatus}`);
+      const byBackend = formatCounter(hookEvents.byBackend);
+      if (byBackend) lines.push(`    by backend: ${byBackend}`);
+    }
+  }
+
   return lines.join('\n') + '\n';
 }
 
+function formatCounter(counter) {
+  if (!counter || typeof counter !== 'object') return '';
+  const entries = Object.entries(counter).sort(([a], [b]) => a.localeCompare(b));
+  if (entries.length === 0) return '';
+  return entries.map(([k, v]) => `${k}=${v}`).join(', ');
+}
+
 function parseLogsArgs(argv) {
   const opts = {
     logDir: defaultDaemonLogDir(),
+    projectRoot: process.cwd(),
     json: false,
   };
   for (let index = 0; index < argv.length; index += 1) {
@@ -94,6 +132,10 @@ function parseLogsArgs(argv) {
       opts.logDir = resolve(requireValue(argv, (index += 1), '--log-dir'));
       continue;
     }
+    if (arg === '--project') {
+      opts.projectRoot = resolve(requireValue(argv, (index += 1), '--project'));
+      continue;
+    }
     if (arg === '--json') {
       opts.json = true;
       continue;

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('claude')}`);
+      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/core/auditor-backend.mjs

@@ -175,11 +175,21 @@ function selectByPolicy({ hostAgent, policy, projectConfig }) {
     };
   }
   if (hostAgent === 'claude') {
+    // Phase 5: Claude host opt-in `next` policy promotes the primary auditor backend
+    // from Haiku to Codex CLI. Phase 4 matrix smoke (2026-05-06, GeForce 5000 fixture)
+    // measured `claude.codex-cli=10041ms` vs `claude.codex-sidecar=12863ms` and Haiku
+    // diagnostics averaged `user_input ~14.3s / turn_end ~16.6s`, so Codex CLI wins on
+    // latency without giving up schema-fixed JSON judgment. Hidden fallback is
+    // forbidden — when codex-cli is unavailable / times out / exits non-zero,
+    // `createCodexCliAuditorBackend` throws `AuditorBackendError` and the daemon
+    // surfaces the structured error instead of dropping back to Haiku.
+    // Haiku stays reachable only via `current` policy or
+    // `SPOTTER_AUDITOR_BACKEND=haiku`.
     return {
-      backend: 'haiku',
-      mode: 'compatibility_haiku',
-      compatibility: 'current_haiku',
-      reason: 'policy_next_claude_held_for_phase5',
+      backend: 'codex-cli',
+      mode: 'codex-cli',
+      compatibility: 'none',
+      reason: 'policy_next_claude_codex_cli',
     };
   }
   throw new AuditorBackendError(