claude-spotter 1.4.6 → 1.4.8

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # 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 までは

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 として配信])
 ```
 
 ### カタログの収集経路
@@ -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
@@ -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.6",
+  "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/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(

package/src/core/hook-event-log.mjs

@@ -0,0 +1,146 @@
+// Phase D (hook parity, 2026-05-08): host-neutral hook-event JSONL log.
+//
+// Codex side previously wrote `.spotter/codex-hook-events.jsonl` with schema
+// `spotter.codex_hook_event.v1`. v1.4.8 unifies that into `.spotter/hook-events.jsonl`
+// with schema `spotter.hook_event.v1` + a `host` field, and Claude hooks now write to
+// the same file. Records every hook firing with skip / success / error / queued status
+// so `spotter diagnostics logs` can surface hook-side observations the daemon log alone
+// never sees (short-prompt skip, drained pending count, hook-level transport errors).
+//
+// File path: `<projectRoot>/.spotter/hook-events.jsonl` (append-only, no rotation yet).
+// Record schema (v1):
+//   {
+//     schema: "spotter.hook_event.v1",
+//     timestamp: "<ISO 8601 UTC>",
+//     host: "claude" | "codex",
+//     hook: "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "Stop" | "SessionEnd",
+//     status: <hook-specific string>,
+//     backend?: "haiku" | "codex-cli" | "codex-sidecar" | null,
+//     pass?: boolean | null,
+//     missingTools?: string[],
+//     code?: string | null,
+//     reason?: string | null,
+//     durationMs?: number,
+//     backendDurationMs?: number | null,
+//     usedToolCount?: number,
+//     pendingContextCount?: number,
+//     toolName?: string | null
+//   }
+
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+const HOOK_EVENTS_FILE = 'hook-events.jsonl';
+export const HOOK_EVENT_SCHEMA = 'spotter.hook_event.v1';
+export const HOOK_EVENTS_SUMMARY_SCHEMA = 'spotter.hook_events_summary.v1';
+
+export function hookEventsPath(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new TypeError('hookEventsPath: projectRoot must be a non-empty string');
+  }
+  return join(projectRoot, '.spotter', HOOK_EVENTS_FILE);
+}
+
+export async function appendHookEvent({ projectRoot, host, event } = {}) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new TypeError('appendHookEvent: projectRoot must be a non-empty string');
+  }
+  if (host !== 'claude' && host !== 'codex') {
+    throw new TypeError(`appendHookEvent: host must be "claude" or "codex" (got ${String(host)})`);
+  }
+  if (!event || typeof event !== 'object') {
+    throw new TypeError('appendHookEvent: event must be an object');
+  }
+  const value = {
+    schema: HOOK_EVENT_SCHEMA,
+    timestamp: new Date().toISOString(),
+    host,
+    ...event,
+  };
+  const path = hookEventsPath(projectRoot);
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, JSON.stringify(value) + '\n', 'utf8');
+}
+
+// Best-effort wrapper used by hook handlers — hook event log failures should never
+// fail the hook itself (the auditor judgment + pending queue are the user-facing
+// surfaces; missing diagnostics is acceptable degradation).
+export async function appendHookEventSafe({ projectRoot, host, event, writeError } = {}) {
+  try {
+    await appendHookEvent({ projectRoot, host, event });
+  } catch (err) {
+    if (typeof writeError === 'function') {
+      writeError(`spotter hook-event log failed: ${err.message}\n`);
+    }
+  }
+}
+
+export async function summarizeHookEvents({ projectRoot, readFileFn = readFile } = {}) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new TypeError('summarizeHookEvents: projectRoot must be a non-empty string');
+  }
+  const summary = {
+    schema: HOOK_EVENTS_SUMMARY_SCHEMA,
+    projectRoot,
+    logPath: hookEventsPath(projectRoot),
+    exists: false,
+    events: 0,
+    parseErrors: 0,
+    byHost: {},
+    byHook: {},
+    byStatus: {},
+    byBackend: {},
+    averageDurationMs: 0,
+    maxDurationMs: 0,
+    recent: [],
+  };
+  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;
+      }
+      summary.events += 1;
+      bump(summary.byHost, event.host ?? 'unknown');
+      bump(summary.byHook, event.hook ?? 'unknown');
+      bump(summary.byStatus, event.status ?? 'unknown');
+      if (event.backend) bump(summary.byBackend, event.backend);
+      if (Number.isFinite(event.durationMs)) {
+        totalDurationMs += event.durationMs;
+        summary.maxDurationMs = Math.max(summary.maxDurationMs, event.durationMs);
+      }
+      summary.recent.push(compactHookEvent(event));
+      if (summary.recent.length > 5) summary.recent.shift();
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  summary.averageDurationMs = summary.events > 0 ? Math.round(totalDurationMs / summary.events) : 0;
+  return summary;
+}
+
+function compactHookEvent(event) {
+  return {
+    timestamp: event.timestamp ?? null,
+    host: event.host ?? null,
+    hook: event.hook ?? 'unknown',
+    status: event.status ?? 'unknown',
+    backend: event.backend ?? null,
+    pass: typeof event.pass === 'boolean' ? event.pass : null,
+    missingTools: Array.isArray(event.missingTools) ? event.missingTools : [],
+    code: event.code ?? null,
+    reason: event.reason ?? null,
+    durationMs: Number.isFinite(event.durationMs) ? event.durationMs : null,
+  };
+}
+
+function bump(counter, key) {
+  counter[key] = (counter[key] ?? 0) + 1;
+}