claude-spotter 1.4.2 → 1.4.4

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.4.4
+
+**Codex CLI auditor の default model を明示固定**。Spotter の hook 判定は高頻度・低遅延・低コストの
+構造化 JSON 監査であり、Codex CLI の暗黙 default model に依存すると、`--ignore-user-config` 環境で
+実際に呼ぶ model が不透明になるため修正。
+
+### 変更点
+
+- **編集 [src/core/codex-cli-backend.mjs](src/core/codex-cli-backend.mjs)**:
+  `SPOTTER_CODEX_CLI_MODEL` 未設定時も `--model gpt-5.4-mini` を渡すようにした。
+  `SPOTTER_CODEX_CLI_REASONING_EFFORT` 未設定時の `model_reasoning_effort="low"` は維持。
+- **編集 [test/codex-cli-backend.test.mjs](test/codex-cli-backend.test.mjs)**:
+  default args が `gpt-5.4-mini` を含むことと、明示的に `model: ""` を渡した場合だけ
+  `--model` を省略できることを固定。
+- **編集 README / README.ja / CLAUDE.md / docs**: Codex CLI auditor child の既定を
+  `gpt-5.4-mini` + `model_reasoning_effort="low"` と明記。
+
+### ユーザー側で必要な手順
+
+1. `npm install -g claude-spotter@1.4.4`
+2. 各プロジェクトで `spotter install`
+
+## 1.4.3
+
+**README の Codex refresh 手順表現を v1.4.2 の実装と一致させる docs patch release**。v1.4.2 で Codex hooks 登録は `spotter install` に集約済みだが、README / README.ja の common commands コメントに `codex-hook install` 後という古い表現が残っていたため修正。
+
+### 変更点
+
+- **編集 [README.md](README.md) / [README.ja.md](README.ja.md)**: Codex SessionStart refresh は `spotter install` 後に自動実行される、と明記。`spotter codex-hook install` は修復 / 明示登録用 command として残す
+
+### ユーザー側で必要な手順
+
+1. `npm install -g claude-spotter@1.4.3`
+2. 各プロジェクトで `spotter install`
+
 ## 1.4.2
 
 **既存 project の hook command path を npm global 版へ更新する patch release**。v1.4.1 の `spotter install` は Codex hooks を自動登録するようになったが、既存 `.claude/settings.json` に `spotter.mjs` hook がある場合、登録済み判定で timeout だけ更新し、command path を現在の package root へ差し替えていなかった。local checkout 由来の hook が残ると、global npm update 後も古い checkout を呼び続け得るため修正。
@@ -398,7 +433,7 @@ v0.8.0 で claude.ai OAuth 系 MCP (Gmail / Calendar / Drive) を手書き basel
 - **編集 [docs/catalog-design.md](docs/catalog-design.md)**:
   - 新節「収集タイミング (v1.1.0 以降)」追加 — install 同期 seed / SessionStart bg refresh / db refresh / db rebuild の 4 経路を整理
   - 歴史節に v1.1.x の「収集タイミング自動化」を追記
-- **編集 [docs/spotter-plan.md](docs/spotter-plan.md)**:
+- **編集 [docs/archive/spotter-plan.md](docs/archive/spotter-plan.md)**:
   - 冒頭に「v0.1 時点の設計議事録」である旨のブリッジ追加、現行設計の真実源 (catalog-design.md / open-issues.md / CLAUDE.md) へのリンクを明示
 
 ## 1.1.2
@@ -1161,7 +1196,7 @@ layers cover the same proliferation cases.
 
 ## 0.1.1 — ⚠️ DEPRECATED 2026-04-19
 
-**Do not install this version.** Real-world testing against a live Claude Code session revealed that the "one daemon per session" model is based on a wrong assumption — `SessionStart` hooks fire per subagent (Task tool invocation), not only at top-level session startup. Within 41 seconds of install, 213 orphan daemons accumulated and Haiku API calls uniformly timed out. `npm uninstall -g` also did not execute `preuninstall`, leaving hook entries in `~/.claude/settings.json`. See [docs/spotter-plan.md §18](https://github.com/kitepon-rgb/Spotter/blob/main/docs/spotter-plan.md#18) for details and the v0.2 redesign plan.
+**Do not install this version.** Real-world testing against a live Claude Code session revealed that the "one daemon per session" model is based on a wrong assumption — `SessionStart` hooks fire per subagent (Task tool invocation), not only at top-level session startup. Within 41 seconds of install, 213 orphan daemons accumulated and Haiku API calls uniformly timed out. `npm uninstall -g` also did not execute `preuninstall`, leaving hook entries in `~/.claude/settings.json`. See [docs/archive/spotter-plan.md §18](https://github.com/kitepon-rgb/Spotter/blob/main/docs/archive/spotter-plan.md#18) for details and the v0.2 redesign plan.
 
 ## 0.1.1 (pre-deprecation notes)
 
@@ -1188,4 +1223,4 @@ Initial release.
 
 ### Design
 
-All non-negotiable design decisions — including transparency vs invisibility, JSON I/O, socket abstraction, message envelope, SessionStart readiness — are documented in [docs/spotter-plan.md](docs/spotter-plan.md).
+All non-negotiable design decisions — including transparency vs invisibility, JSON I/O, socket abstraction, message envelope, SessionStart readiness — are documented in [docs/archive/spotter-plan.md](docs/archive/spotter-plan.md).

package/README.ja.md

@@ -63,6 +63,10 @@ spotter uninstall        # このプロジェクトの hook 登録を解除
 
 ### 1 ターンの監査フロー
 
+Claude Code と Codex では `Stop` の受け口が違います。下の図は Claude host の流れです。
+Codex native `Stop` は遅延配送で、不足ツールの指摘を queue し、次の same-session
+`UserPromptSubmit` で提示します。
+
 ```mermaid
 flowchart TD
     U([User 発話]) --> UPH[UserPromptSubmit hook<br/>Spotter が発話とカタログから一次判定]
@@ -126,7 +130,7 @@ spotter db list --host-agent codex
 spotter db refresh       # Claude MCP / スキル / サブエージェントから description を収集して Claude DB 更新
 spotter db refresh --host-agent codex
                          # Codex MCP / スキルから description を収集して .spotter/tool-db.codex.json を更新
-                         # (Claude は install + Claude SessionStart、Codex は codex-hook install 後の
+                         # (Claude は install + Claude SessionStart、Codex は spotter install 後の
                          #  Codex SessionStart で自動実行されるので通常は不要)
 spotter db rebuild       # Claude local + global DB を両方消してから refresh (カタログ設計変更時のクリーン用)
 spotter status           # 稼働中の daemon 一覧
@@ -159,21 +163,23 @@ SPOTTER_CODEX_RISK_CHECK=1 spotter daemon start --session-id ... --project-root
 Primary auditor backend policy: Claude hooks は現行の Haiku compatibility path を既定のまま維持します。
 Codex native hooks は Codex CLI を既定 backend とし、Haiku へ fallback しません。
 Codex 側の SessionStart hook は `.spotter/tool-db.codex.json` を bg refresh し、Claude DB には触れません。
+Codex CLI auditor の子プロセスは、hook 判定を安く速く保つため既定で `gpt-5.4-mini` と
+`model_reasoning_effort="low"` を明示指定します。実測や制御された実験では
+`SPOTTER_CODEX_CLI_MODEL` / `SPOTTER_CODEX_CLI_REASONING_EFFORT` で上書きできます。
 明示 smoke には `SPOTTER_AUDITOR_BACKEND=codex-sidecar` も使えます。
 
 ## 設計ドキュメント
 
 - **現行設計 (カタログ / 収集経路 / 分類軸)**: [docs/catalog-design.md](docs/catalog-design.md) — v1.0.0 以降の真実源
 - **現時点で塞がっていない穴 + 実測未検証の懸念**: [docs/open-issues.md](docs/open-issues.md) — 新規作業に入る前に必読
-- **Claude contract capture**: [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md) — Codex 作業で維持すべき hook / daemon / Haiku の現行契約
-- **Claude / Codex 両対応ブリーフ**: [docs/SPOTTER_CODEX_DUAL_SUPPORT.md](docs/SPOTTER_CODEX_DUAL_SUPPORT.md) と完了済み [TODO](docs/SPOTTER_CODEX_DUAL_SUPPORT_TODO.md) — second-pass `codex-sidecar` workflow
-- **Primary auditor backend migration**: [docs/SPOTTER_PRIMARY_BACKEND_TODO.md](docs/SPOTTER_PRIMARY_BACKEND_TODO.md) — Codex CLI / `codex-sidecar` auditor backend の rollout 状況
+- **Runtime contract**: [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md) — Claude hook / daemon / Haiku 契約と Codex native hook policy
 - **実装規範と不変条件 (§0)**: [CLAUDE.md](CLAUDE.md) — フォールバック禁止 / silent fallback 禁止 / 暫定コード禁止
-- **歴史記録 (v0.1 時点の設計議事録)**: [docs/spotter-plan.md](docs/spotter-plan.md) — 作成時点で固定された議論過程のスナップショット、現行設計は上記 3 点を参照
+- **Archive**: [docs/archive/](docs/archive/) — 完了済み Codex rollout 計画、primary backend smoke log、v0.1 設計議事録
 
 ## 既知の制約
 
 - 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 になりやすい実測結果を避けるためです
 - **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

@@ -63,6 +63,10 @@ spotter uninstall        # remove hooks from this project
 
 ### Audit flow per turn
 
+Claude Code and Codex have different `Stop` surfaces. The diagram below is the Claude
+host flow. Codex native `Stop` uses deferred delivery: findings are queued and shown on
+the next same-session `UserPromptSubmit`.
+
 ```mermaid
 flowchart TD
     U([User prompt]) --> UPH[UserPromptSubmit hook<br/>Spotter audits prompt against catalog]
@@ -127,7 +131,7 @@ spotter db refresh       # rediscover Claude MCP / skills / sub-agents and updat
 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 codex-hook install)
+                         #    Codex refresh is automatic on Codex SessionStart after spotter install)
 spotter db rebuild       # wipe Claude local + global DBs and refresh from scratch
                          #   (use after catalog-shape changes)
 spotter status           # list running daemons
@@ -161,21 +165,24 @@ Primary auditor backend policy: Claude hooks keep the current Haiku-compatible p
 default. Codex native hooks use Codex CLI by default and do not fall back to Haiku;
 their SessionStart hook refreshes `.spotter/tool-db.codex.json` in the background
 without touching the Claude DB.
+Codex CLI auditor child processes explicitly use `gpt-5.4-mini` with
+`model_reasoning_effort="low"` by default so hook checks stay cheap and fast;
+`SPOTTER_CODEX_CLI_MODEL` and `SPOTTER_CODEX_CLI_REASONING_EFFORT` can override
+those values for smoke tests or controlled experiments.
 `SPOTTER_AUDITOR_BACKEND=codex-sidecar` is available for explicit sidecar auditor smoke.
 
 ## Design docs
 
 - **Current design** (catalog, discovery, classification axes): [docs/catalog-design.md](docs/catalog-design.md) — source of truth from v1.0.0
 - **Open issues + unverified concerns**: [docs/open-issues.md](docs/open-issues.md) — read this before starting new work
-- **Claude contract capture**: [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md) — current hook / daemon / Haiku behavior that Codex work must preserve
-- **Claude / Codex dual-support brief**: [docs/SPOTTER_CODEX_DUAL_SUPPORT.md](docs/SPOTTER_CODEX_DUAL_SUPPORT.md) and completed [TODO](docs/SPOTTER_CODEX_DUAL_SUPPORT_TODO.md) — second-pass `codex-sidecar` workflows
-- **Primary auditor backend migration**: [docs/SPOTTER_PRIMARY_BACKEND_TODO.md](docs/SPOTTER_PRIMARY_BACKEND_TODO.md) — Codex CLI / `codex-sidecar` auditor backend rollout status
+- **Runtime contract**: [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md) — Claude hook / daemon / Haiku contract plus Codex native hook policy
 - **Implementation invariants (§0)**: [CLAUDE.md](CLAUDE.md) — no fallbacks, no silent failures, no provisional code
-- **Historical record (v0.1 design discussion)**: [docs/spotter-plan.md](docs/spotter-plan.md) — frozen design-discussion snapshot
+- **Archived plans and history**: [docs/archive/](docs/archive/) — completed Codex rollout plans, primary backend smoke logs, and the frozen v0.1 design discussion
 
 ## 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"`
 - **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.2",
+  "version": "1.4.4",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {

package/src/core/codex-cli-backend.mjs

@@ -7,6 +7,7 @@ import { AuditorBackendError } from './auditor-error.mjs';
 import { filterCatalogMisses, parseAuditorResponse } from './auditor-response.mjs';
 
 const DEFAULT_CODEX_CLI_TIMEOUT_MS = 45_000;
+const DEFAULT_CODEX_CLI_MODEL = 'gpt-5.4-mini';
 const DEFAULT_CODEX_CLI_REASONING_EFFORT = 'low';
 const STDERR_LIMIT = 32 * 1024;
 const STDOUT_LIMIT = 64 * 1024;
@@ -73,7 +74,7 @@ export function createCodexCliAuditorBackend({
           env,
           spawnFn,
           timeoutMs,
-          model: env?.SPOTTER_CODEX_CLI_MODEL,
+          model: env?.SPOTTER_CODEX_CLI_MODEL || DEFAULT_CODEX_CLI_MODEL,
           reasoningEffort: env?.SPOTTER_CODEX_CLI_REASONING_EFFORT || DEFAULT_CODEX_CLI_REASONING_EFFORT,
         });
         let rawFinal;
@@ -146,7 +147,7 @@ export function buildCodexCliAuditorPrompt({ catalog, input }) {
   return lines.join('\n');
 }
 
-export function buildCodexExecArgs({ schemaPath, lastMessagePath, projectRoot, prompt, model = '', reasoningEffort = DEFAULT_CODEX_CLI_REASONING_EFFORT }) {
+export function buildCodexExecArgs({ schemaPath, lastMessagePath, projectRoot, prompt, model = DEFAULT_CODEX_CLI_MODEL, reasoningEffort = DEFAULT_CODEX_CLI_REASONING_EFFORT }) {
   for (const [name, value] of Object.entries({ schemaPath, lastMessagePath, projectRoot, prompt })) {
     if (typeof value !== 'string' || value.length === 0) {
       throw new TypeError(`buildCodexExecArgs: ${name} must be a non-empty string`);