claude-spotter 1.4.13 → 1.4.15

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.4.15
+
+**codex ログイン失効でサイレントに死に、host の Claude が無反応になる実害バグを根治**。codex auditor の
+ログインが失効 (`token_revoked` / `refresh_token_reused` / `401 Unauthorized`) すると、`spotter install`
+済みプロジェクトで毎ターン入力が消えて「Claude が一切反応しない」状態になっていた。実セッションの daemon
+ログ (`handler error on user_input/turn_end: E_CODEX_CLI_EXIT`) + コード監査 + 公式 hook 仕様の裏取りで
+根本原因を 2 点に特定: (A) codex 異常終了時、stderr/stdout に入っているログイン失効の痕跡を捨てて全部
+`E_CODEX_CLI_EXIT` に潰しており、auth 失敗を区別できていなかった。(B) `UserPromptSubmit` hook が daemon
+エラーを一律 `die(exit 2)` で処理しており、Claude Code は入力時 hook の exit 2 を **ブロッキング扱い =
+プロンプト消去** とするため、失効が永続する限り毎ターン入力が消えていた。
+
+### 変更点
+
+- **編集 [src/core/codex-cli-backend.mjs](src/core/codex-cli-backend.mjs)**: codex の非ゼロ終了時に
+  stdout+stderr をスキャンし、ログイン失効の痕跡があれば新コード `E_CODEX_CLI_AUTH` (対処法
+  「`codex login`」を含むメッセージ) を投げる。痕跡が無ければ従来通り `E_CODEX_CLI_EXIT`。新規 export
+  `isCodexAuthFailure`。分類は非ゼロ終了経路のみ (auth 失敗は <1s で即終了するため timeout 経路は対象外)。
+- **編集 [src/hooks/lib.mjs](src/hooks/lib.mjs)**: `formatSpotterWarning({code,message})` を新設
+  (`[Spotter からの警告]` ブロック、`E_CODEX_CLI_AUTH` は `codex login` を案内、他は理由コード入りの汎用
+  文面)。exit-code 契約コメントを「audit 失敗は loud degradation = exit 0 + additionalContext、exit 2 は
+  malformed envelope 専用」に更新。
+- **編集 [src/hooks/user-prompt.mjs](src/hooks/user-prompt.mjs)**: daemon/transport/resurrect 失敗で
+  `die(exit 2)` する代わりに `degrade()` — 警告を `additionalContext` (drain 済み pending と merge) で出して
+  **exit 0 でプロンプトを通す**。失効に限らずあらゆる監査失敗で host が固まらない。throw 値の `.message`
+  アクセスを optional chaining 化し、非 Error throw が top-level catch (exit 2) に抜ける穴も塞いだ。
+- **編集 [src/hooks/stop.mjs](src/hooks/stop.mjs)**: backend/transport エラーと marker 消失 (TOCTOU) で
+  `die(exit 2 = 継続強制)` をやめ、`status:"degraded"` 記録 + exit 0。pending は積まない (verdict 未生成)。
+  loud な警告は次の `UserPromptSubmit` が配信。
+- **編集 [src/hooks/pre-tool-use.mjs](src/hooks/pre-tool-use.mjs)**: daemon/transport エラーで
+  `die(exit 2 = ツール拒否)` をやめ、`status:"degraded"` 記録 + exit 0 (ツール許可)。記録は best-effort
+  telemetry でありツールを止める理由にならない。
+- **更新 [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md)**: `UserPromptSubmit` /
+  `PreToolUse` / `Stop` の失敗時 exit-code 契約を新挙動に追従。
+- **追記 [docs/open-issues.md](docs/open-issues.md)**: auth-freeze バグの解決を記録。`Stop` 失敗が
+  セッション最終ターンだと deferred-delivery の性質上サイレントになる残課題を P2 に追記。
+- **テスト 11 件追加** ([test/hooks.test.mjs](test/hooks.test.mjs) /
+  [test/codex-cli-backend.test.mjs](test/codex-cli-backend.test.mjs)): auth 分類 / `formatSpotterWarning` /
+  UserPromptSubmit の loud degrade (auth/汎用/pending merge/resurrect 失敗/非 Error throw) / Stop degrade /
+  PreToolUse degrade。`node --test` 344 pass / 1 skip 緑。
+
+### 検証
+
+実プロジェクトの監査経路 (`createCodexCliAuditorBackend.judge` を実コードで起動) で、再ログイン後に
+`pass` verdict が返ること、および fake spawn でログイン失効 stderr → `E_CODEX_CLI_AUTH` 分類 → hook が
+`[Spotter からの警告]` を additionalContext に出して exit 0 することを確認。多エージェントの敵対的レビュー
+(host-freeze 完全性 / §0 silent-fallback / 分類器精度+docs) で HIGH 2 / MEDIUM 3 を検出し全て反映。
+
+## 1.4.14
+
+**README 等の公開資産から内部コードネーム "Bell" を撤去**。Spotter の内部設計議論で使われている
+"Bell" (主役の Claude を指す呼称) は private な codename であり、README や OG banner で
+公開すべきものではないという運用判断を反映。コード・内部ドキュメント (CLAUDE.md / docs/) には
+影響なし。npm tarball 同梱の README を新版で配るため patch bump。
+
+### 変更点
+
+- **編集 [README.md](README.md) / [README.ja.md](README.ja.md)**:
+  "Bell" を文脈に応じて `Claude` / `your primary Claude` / `the primary Claude` に置換、
+  `(Bell)` 括弧書きは削除。日本語版の `主体 (Bell) に` は `主体に` に整形。
+- **編集 [.github/og.svg](.github/og.svg) と再生成された [.github/og.png](.github/og.png)**:
+  OG banner の bullet text 2 件を Claude 表記に。`svgexport` で 1280×640 PNG を再レンダリング。
+- **編集 [.github/concept.svg](.github/concept.svg)**:
+  内部 HTML コメント `Bell side` を `Primary Claude side` に。
+
+### 検証
+
+- `grep -rn "Bell" README.md README.ja.md .github/` で公開資産に Bell 残存なしを確認。
+- `node --test` 334 tests / 333 pass / 1 skip 緑 (README / asset 変更のみで test には影響しない)。
+
 ## 1.4.13
 
 **Spotter 監査文面の末尾「監査役を明示してください」念押し行を削除**。
@@ -1044,7 +1113,7 @@ Haiku 突然死 (shutdown ログなしで daemon 再起動する事象、v0.12.0
 
 ### 事の発端
 
-v0.8.0 の `spotter db refresh` 実測で x-api (HTTP MCP) が 401 Unauthorized で落ちていた。`claude mcp list` では `x-api: https://kitepon.dynv6.net/mcp (HTTP)` と表示され URL は拾えるが、Spotter の refresh プロセスから叩くと認証情報がないため拒否。ユーザーの指摘で `.mcp.json` を直接 cat したところ、実態は **stdio** で `env: {X_BEARER_TOKEN: "..."}` を持つ設定だった。CLI 表示と actual config が食い違っていた (CLI の cache の古さと思われる)。
+v0.8.0 の `spotter db refresh` 実測で x-api (HTTP MCP) が 401 Unauthorized で落ちていた。`claude mcp list` では `x-api: https://kitepon.dev/mcp (HTTP)` と表示され URL は拾えるが、Spotter の refresh プロセスから叩くと認証情報がないため拒否。ユーザーの指摘で `.mcp.json` を直接 cat したところ、実態は **stdio** で `env: {X_BEARER_TOKEN: "..."}` を持つ設定だった。CLI 表示と actual config が食い違っていた (CLI の cache の古さと思われる)。
 
 判明した設計上の転換点:
 

package/README.ja.md

@@ -11,17 +11,25 @@
 
 **[English](README.md) · 日本語**
 
-> **気づく役と実行する役を分離する。** Claude Code の横で並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**だけ静かに指摘する監査役。
+> **気づく役と実行する役を分離する。** Claude Code の横で並走し、主役の Claude が**ツールを呼び忘れたとき**だけ静かに指摘する監査役。
 
 Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。記録すべき決定を memory / caveat MCP に残さない、docs lookup MCP を呼ばずに古い知識で応答する、ブラウザ自動化 MCP で確認せず UI 状態を推測する — **「分からないと自覚できない」から、ツールを取りに行けない**。
 
-Spotter はツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎に常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると透明化された指摘として Bell に届け、補正応答を促します。**Bell が自覚して呼ぶ**設計は本プロダクトの存在意義を破壊するため、Bell から呼ぶのではなく hook 経由で Bell の意思と独立に検出する構造を取っています。
+Spotter はツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎に常駐させ、Claude の発話予定と応答を並走監査します。見落としを検出すると透明化された指摘として Claude に届け、補正応答を促します。**Claude が自覚して呼ぶ**設計は本プロダクトの存在意義を破壊するため、Claude から呼ぶのではなく hook 経由で Claude の意思と独立に検出する構造を取っています。
+
+<p align="center">
+  <img src=".github/concept.svg" alt="Claude が答え、Spotter が見ている" width="80%">
+</p>
+
+<p align="center">
+  <sub><b>Claude</b> が答える（実行する役） &nbsp;·&nbsp; <b>Spotter</b> が見ている（気づく役・沈黙監査）</sub>
+</p>
 
 ## 30 秒で見るポイント
 
 Spotter が拾うのは、たとえばこういう瞬間です。
 
-| 状況 | Bell の応答 | Spotter の指摘 |
+| 状況 | Claude の応答 | Spotter の指摘 |
 |---|---|---|
 | 「この OAuth の落とし穴を覚えて」 | 了解だけして進める | memory / caveat MCP の使用機会 |
 | 「このパッケージの最新版 API は？」 | 学習時点の知識で答える | docs lookup MCP の照会機会 |
@@ -33,7 +41,7 @@ Spotter が拾うのは、たとえばこういう瞬間です。
 判定軸は 2 段階:
 
 - **入力時 (`stage=user_input`)**: ユーザー要請に対し、ローカルカタログの description から用途が明確に該当するツールを列挙する **要請充足チェック**
-- **応答後 (`stage=turn_end`)**: Bell の最終応答に対し、事実の断定 / 記録すべき新情報 / 既知情報の参照それぞれに、カタログ上のツール (検証 / 登録 / 照会) を差し込める余地がないかを問う **ツール適用機会の監査**
+- **応答後 (`stage=turn_end`)**: Claude の最終応答に対し、事実の断定 / 記録すべき新情報 / 既知情報の参照それぞれに、カタログ上のツール (検証 / 登録 / 照会) を差し込める余地がないかを問う **ツール適用機会の監査**
 
 ## インストール
 
@@ -86,8 +94,8 @@ Codex native `Stop` は遅延配送で、不足ツールの指摘を queue し
 ```mermaid
 flowchart TD
     U([User 発話]) --> UPH[UserPromptSubmit hook<br/>Spotter が発話とカタログから一次判定]
-    UPH --> BT[Bell Thinking<br/>Spotter の推奨を<br/>additionalContext で受信]
-    BT --> BA([Bell の最初の応答])
+    UPH --> BT[Claude Thinking<br/>Spotter の推奨を<br/>additionalContext で受信]
+    BT --> BA([Claude の最初の応答])
     BA --> SH[Stop hook<br/>応答と使用済みツールから最終チェック]
     SH --> DEC{見落とし<br/>あり?}
     DEC -->|なし| DONE([完了])
@@ -135,7 +143,7 @@ flowchart LR
 | 対象 | コンテキスト肥大化 | ツール取りこぼし |
 | 仕組み | hook で記憶退避 | hook でサブエージェント並走 |
 
-両者に共通するのは **「主体 (Bell) に頼らない仕組み」**。併用できます。
+両者に共通するのは **「主体に頼らない仕組み」**。併用できます。
 
 ## よく使うコマンド
 
@@ -196,16 +204,16 @@ Codex CLI auditor の子プロセスは、hook 判定を安く速く保つため
 
 - 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 改訂とセットで今後検討
+- **JSON スキーマ違反は v0.5.0 以降「想定済み異常」として silent pass + session renew で回復**します (role collapse 検知パス、daemon ログに `role_collapse_reset` を残す)。一方 **Haiku timeout は引き続き throw** され、UserPromptSubmit がブロックされてユーザー入力が Claude に届かない症状として顕在化します (timeout は v0.5.0 で 30s、v0.13.1 で 45s に拡張)。timeout の fail-open 化 (pass 扱い) は §0 改訂とセットで今後検討
 
 <details>
 <summary><strong>📋 最近のハイライト</strong></summary>
 
-- **プラグイン形式の MCP サーバー対応** — `plugin:everything-claude-code:context7` のように名前に内部コロンを含むサーバーを正しくパースし、配下のツールをカタログに取り込めるようになった (旧版はこの形式のサーバーをすべて単一の `"plugin"` に潰して、Bell の監査から silent に脱落させていた)
+- **プラグイン形式の MCP サーバー対応** — `plugin:everything-claude-code:context7` のように名前に内部コロンを含むサーバーを正しくパースし、配下のツールをカタログに取り込めるようになった (旧版はこの形式のサーバーをすべて単一の `"plugin"` に潰して、Claude の監査から silent に脱落させていた)
 - **プロジェクト単位の監査隔離** — daemon が監査に使うのはローカル DB のみ。グローバル DB は description 再利用キャッシュに役割限定。**他プロジェクト**でインストールしたツールが現プロジェクトの監査に混入することはない
 - **手放しでカタログ維持** — `spotter install` が Claude DB を自動 seed、Claude / Codex それぞれの SessionStart が host-local DB を bg refresh する。手書き管理は一切不要
 - **Codex native hooks** — Codex host は primary auditor backend として Codex CLI を使い、`.spotter/tool-db.codex.json` を Claude DB と分離し、backend failure は Haiku fallback ではなく明示 error として扱う
-- **監査対象** — ユーザー追加分 (MCP / スキル / サブエージェント) のみ。Claude Code 本体側のツールは意図的に対象外 (Bell は元から自発率が高いため)
+- **監査対象** — ユーザー追加分 (MCP / スキル / サブエージェント) のみ。Claude Code 本体側のツールは意図的に対象外 (Claude は元から自発率が高いため)
 - **実装規範** — フォールバック禁止 / silent fallback 禁止 / 暫定コード禁止 ([CLAUDE.md §0](CLAUDE.md))
 
 リリース履歴の全文は [CHANGELOG](CHANGELOG.md) を参照。

package/README.md

@@ -11,17 +11,25 @@
 
 **English · [日本語](README.ja.md)**
 
-> **Separate the spotter from the doer.** Spotter runs alongside Claude Code and quietly flags the moments when Bell (your primary Claude) **forgets to use a tool it has access to**.
+> **Separate the spotter from the doer.** Spotter runs alongside Claude Code and quietly flags the moments when your primary Claude **forgets to use a tool it has access to**.
 
 Claude has a structural blind spot: **it can't reach for a tool it doesn't realize it needs**. It may skip a project memory MCP when a decision should be recorded, answer from stale memory instead of a docs-lookup MCP, or reason about UI state without a browser-automation MCP. The model can't always tell when it doesn't know — so the tool stays unused.
 
-Spotter pins a second agent (Claude Haiku 4.5) next to Bell. The second agent has the full tool catalog memorized and audits both the user's prompt and Bell's reply in parallel. When it spots a missed tool, it injects a transparent recommendation into Bell's context and, if needed, asks Bell to amend its answer. **Bell is never asked to self-audit** — that would defeat the entire premise. Detection happens through hooks, independent of Bell's intent.
+Spotter pins a second agent (Claude Haiku 4.5) next to Claude. The second agent has the full tool catalog memorized and audits both the user's prompt and Claude's reply in parallel. When it spots a missed tool, it injects a transparent recommendation into Claude's context and, if needed, asks Claude to amend its answer. **Claude is never asked to self-audit** — that would defeat the entire premise. Detection happens through hooks, independent of Claude's intent.
+
+<p align="center">
+  <img src=".github/concept.svg" alt="Claude answers · Spotter watches" width="80%">
+</p>
+
+<p align="center">
+  <sub><b>Claude</b> answers (the doer) &nbsp;·&nbsp; <b>Spotter</b> watches (the auditor, silent)</sub>
+</p>
 
 ## See it in 30 seconds
 
 Examples of what Spotter catches:
 
-| Situation | What Bell would do | What Spotter flags |
+| Situation | What Claude would do | What Spotter flags |
 |---|---|---|
 | "Please remember this OAuth gotcha" | Acknowledge and move on | Missed call to a memory / caveat MCP |
 | "How does this package API work in the latest version?" | Answer from training-time knowledge | Missed call to a docs-lookup MCP |
@@ -33,7 +41,7 @@ Examples of what Spotter catches:
 Spotter audits in two stages:
 
 - **`stage=user_input`** — given the user's prompt, list any local catalog tools whose description clearly applies. A *prompt-fulfillment* check
-- **`stage=turn_end`** — given Bell's final reply, look for places where a catalog tool (verification / recording / lookup) could plug in. A *missed-opportunity* audit. Zero findings is fine; tools already used in this turn are not re-flagged
+- **`stage=turn_end`** — given Claude's final reply, look for places where a catalog tool (verification / recording / lookup) could plug in. A *missed-opportunity* audit. Zero findings is fine; tools already used in this turn are not re-flagged
 
 ## Install
 
@@ -86,8 +94,8 @@ the next same-session `UserPromptSubmit`.
 ```mermaid
 flowchart TD
     U([User prompt]) --> UPH[UserPromptSubmit hook<br/>Spotter audits prompt against catalog]
-    UPH --> BT[Bell thinking<br/>receives Spotter's recommendations<br/>as additionalContext]
-    BT --> BA([Bell's first answer])
+    UPH --> BT[Claude thinking<br/>receives Spotter's recommendations<br/>as additionalContext]
+    BT --> BA([Claude's first answer])
     BA --> SH[Stop hook<br/>Spotter re-audits answer + tools used]
     SH --> DEC{Missed<br/>tool?}
     DEC -->|No| DONE([Done])
@@ -135,7 +143,7 @@ The audited catalog is host-local: Claude uses `<project>/.spotter/tool-db.json`
 | Target | Context bloat | Missed tool calls |
 | Mechanism | Hook-driven memory eviction | Hook-driven sub-agent in parallel |
 
-Both share the principle of **"don't rely on the primary agent (Bell) to do it itself."** They compose well — you can run them together.
+Both share the principle of **"don't rely on the primary agent to do it itself."** They compose well — you can run them together.
 
 ## Common commands
 
@@ -197,18 +205,18 @@ 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
+- The `Stop` hook fires **after** Claude's first answer has already been streamed to the user. When Spotter sends Claude 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
 - `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
+- **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 Claude. 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>
 <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
+- **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 Claude's audit
 - **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
+- **Audit scope** — only user-added surface (MCP servers / skills / sub-agents). Claude Code's built-in tools are intentionally out of scope; Claude already uses those reliably
 - **Implementation invariants** — no fallbacks, no silent failures, no provisional code (see [§0 in CLAUDE.md](CLAUDE.md))
 
 Full release history: [CHANGELOG](CHANGELOG.md).

package/package.json

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

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

@@ -12,6 +12,37 @@ const DEFAULT_CODEX_CLI_REASONING_EFFORT = 'low';
 const STDERR_LIMIT = 32 * 1024;
 const STDOUT_LIMIT = 64 * 1024;
 
+// codex prints auth/login failures to BOTH stdout (the JSON error stream, e.g.
+// {"type":"error","message":"...sign in again..."}) and stderr (codex_login::auth::manager,
+// e.g. "401 Unauthorized ... token_revoked"). We scan the combined text for these markers so a
+// revoked/expired login is classified as the distinct, actionable E_CODEX_CLI_AUTH instead of
+// being collapsed into the generic E_CODEX_CLI_EXIT. Conservative case-insensitive substring
+// match keyed on the wording codex actually emits; if codex changes its wording the generic
+// path still degrades loudly (the hook no longer freezes the host on either code). Classification
+// runs only on the nonzero-exit path below — auth failures are observed to exit immediately
+// (<1s), so the timeout path is not expected to see them; if codex ever starts hanging on auth,
+// the timeout would surface as the generic E_CODEX_CLI_TIMEOUT rather than E_CODEX_CLI_AUTH.
+const CODEX_AUTH_FAILURE_MARKERS = [
+  'token_revoked',
+  'refresh_token_reused',
+  'refresh token was already used',
+  'refresh token has already been used',
+  'invalidated oauth token',
+  '401 unauthorized',
+  'sign in again',
+  'sign back in',
+  'log out and sign in',
+  'not logged in',
+  'please log in',
+  'please login',
+];
+
+export function isCodexAuthFailure(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  const haystack = text.toLowerCase();
+  return CODEX_AUTH_FAILURE_MARKERS.some((marker) => haystack.includes(marker));
+}
+
 export const CODEX_AUDITOR_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -295,9 +326,17 @@ async function runCodexExec({
     child.on('close', (code) => {
       settle(() => {
         if (code !== 0) {
+          const diag = { ...diagnostics(), exitCode: code };
+          if (isCodexAuthFailure(`${diag.stdout}\n${diag.stderr}`)) {
+            reject(new AuditorBackendError('E_CODEX_CLI_AUTH', 'codex-cli auth failed — codex login required (run `codex login`)', {
+              backend: 'codex-cli',
+              diagnostics: diag,
+            }));
+            return;
+          }
           reject(new AuditorBackendError('E_CODEX_CLI_EXIT', `codex-cli exited with code ${code}`, {
             backend: 'codex-cli',
-            diagnostics: { ...diagnostics(), exitCode: code },
+            diagnostics: diag,
           }));
           return;
         }

package/src/hooks/lib.mjs

@@ -1,11 +1,18 @@
 // Shared hook plumbing — stdin read, error → exit-code mapping per §14.3 / §14.4.
 //
 // Exit code contract (§14.3 / §14.4):
-//   0 = success (normal flow)
-//   1 = expected abnormal (daemon unreachable; user should restart daemon)
-//   2 = unexpected (propagate to Claude Code transcript)
+//   0 = success (normal flow), OR a LOUD degradation: the audit could not run but the failure
+//       is surfaced in-band via a `[Spotter からの警告]` additionalContext block, so the host
+//       stays responsive and the user's prompt is never erased. UserPromptSubmit uses this for
+//       any daemon / auditor-backend failure (e.g. codex login expired) — see user-prompt.mjs.
+//   1 = expected abnormal, non-blocking (Claude Code proceeds; first stderr line shown to user).
+//   2 = unexpected protocol/contract violation (malformed Claude Code envelope, missing required
+//       field). Reserved for cases where there is no real user prompt worth preserving — a
+//       UserPromptSubmit exit 2 BLOCKS and erases the prompt, so audit failures must NOT use it.
 //
-// Silent fallback (exit 0 with missing behaviour) is forbidden. See §14.1.
+// A loud degradation (visible warning naming the cause + remedy) is NOT a silent fallback: the
+// user is explicitly told the audit did not run. The forbidden pattern (§14.1) is the SILENT
+// exit-0 that leaves the user believing they are protected when they are not.
 //
 // v0.2 gate helpers (plan §18 / C:\Users\kite_\.claude\plans\10-cuddly-codd.md):
 // - isChildCall(): env-var gate for Spotter's own child backend invocations
@@ -114,15 +121,6 @@ export function optionalString(input, key) {
   return value;
 }
 
-// Map a TransportError / HaikuError into an exit code.
-export function exitCodeFor(err) {
-  if (err && typeof err.code === 'string') {
-    if (err.code === 'E_UNREACHABLE') return 1;
-    return 2;
-  }
-  return 2;
-}
-
 export function die(message, exitCode = 2) {
   process.stderr.write(`spotter-hook: ${message}\n`);
   process.exit(exitCode);
@@ -162,3 +160,25 @@ export function formatTransparentBlockReason(missingTools) {
     ...lines,
   ].join('\n');
 }
+
+// Loud degradation notice (§0 / §14.1): the auditor could not run this turn. Surfaced via the
+// same additionalContext channel as findings so the host stays responsive AND the user is told
+// they are temporarily unprotected (and, for an expired codex login, exactly how to recover).
+// This is the opposite of a silent fallback.
+export function formatSpotterWarning({ code, message } = {}) {
+  const header = '[Spotter からの警告]';
+  if (code === 'E_CODEX_CLI_AUTH') {
+    return [
+      header,
+      'Spotter の監査エンジン (codex) のログインが失効しているため、今回の入力は監査できませんでした。',
+      'この応答を続ける前に、ユーザーに「端末で `codex login` を実行して再ログインすれば Spotter の監査が復旧する」ことを伝えてください。',
+    ].join('\n');
+  }
+  const lines = [
+    header,
+    `Spotter は今回の入力を監査できませんでした (理由コード: ${code ?? 'unknown'})。この応答は監査されていません。`,
+    'この応答を続ける前に、ユーザーに Spotter の監査が一時的に無効になっていることを伝えてください。',
+  ];
+  if (typeof message === 'string' && message.length > 0) lines.push(`詳細: ${message}`);
+  return lines.join('\n');
+}

package/src/hooks/pre-tool-use.mjs

@@ -7,7 +7,6 @@
 import {
   readStdinJson,
   requireString,
-  exitCodeFor,
   die,
   isChildCall,
   isSubagentCall,
@@ -23,7 +22,6 @@ export async function runPreToolUse({
   readInput = readStdinJson,
   sendRequestFn = sendRequest,
   recordHookEventFn = recordClaudeHookEvent,
-  dieFn = die,
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -43,17 +41,21 @@ export async function runPreToolUse({
       timeoutMs: TIMEOUT_MS,
     });
     if (response.ok !== true) {
+      // Recording is best-effort telemetry, not an audit verdict. On a daemon-side error, allow
+      // the tool (exit 0) — a PreToolUse exit 2 would DENY the tool, which must never happen
+      // just because Spotter could not record it. The audit at user_input/turn_end still warns
+      // loudly if the backend is down.
       await recordHookEventFn({
         projectRoot,
         event: {
           hook: 'PreToolUse',
-          status: 'error',
+          status: 'degraded',
           toolName,
           code: response.error?.code ?? 'E_INTERNAL',
+          reason: 'daemon_error',
           durationMs: Date.now() - startedAt,
         },
       });
-      dieFn(`daemon error on tool_used: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
       return;
     }
     await recordHookEventFn({
@@ -66,17 +68,18 @@ export async function runPreToolUse({
       },
     });
   } catch (err) {
+    // Transport failure during best-effort recording: allow the tool (no exit 2 deny).
     await recordHookEventFn({
       projectRoot,
       event: {
         hook: 'PreToolUse',
-        status: 'error',
+        status: 'degraded',
         toolName,
         code: err?.code ?? 'E_INTERNAL',
+        reason: 'transport',
         durationMs: Date.now() - startedAt,
       },
     });
-    dieFn(`pre-tool-use transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
   }
 }
 

package/src/hooks/stop.mjs

@@ -10,8 +10,11 @@
 // queue and folds the entries into `additionalContext`, so Bell receives the audit finding
 // alongside the next user input. The original A reply stays as the turn's final message.
 //
-// `decision:"block"` is no longer emitted from this hook. Backend / transport errors still
-// exit with code 1 + stderr (silent fallback is forbidden — see lib.mjs).
+// `decision:"block"` is no longer emitted from this hook. Backend / transport errors do NOT
+// force a continuation (a Stop exit 2 would block stopping = harmful noise on a Spotter-side
+// failure); they are recorded as `degraded` and exit 0. The next UserPromptSubmit surfaces the
+// loud `[Spotter からの警告]`. No verdict is produced on failure, so nothing is queued — this is
+// still not a silent "all clear" (the surfacing just moves to the next turn — see lib.mjs).
 // `stop_hook_active:true` is still observed: the daemon early-passes on it, so we just
 // receive `pass:true` and return without writing pending context.
 //
@@ -20,7 +23,6 @@
 import {
   readStdinJson,
   requireString,
-  exitCodeFor,
   die,
   findSpotterMarker,
   formatTransparentBlockReason,
@@ -41,7 +43,6 @@ export async function runStop({
   appendPendingContextFn = appendPendingContext,
   getLastAssistantTextFn = getLastAssistantText,
   recordHookEventFn = recordClaudeHookEvent,
-  dieFn = die,
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -71,30 +72,36 @@ export async function runStop({
       timeoutMs: TIMEOUT_MS,
     });
   } catch (err) {
+    // Spotter-side failure (daemon unreachable, etc.): record + exit 0. Do NOT force the model to
+    // continue (a Stop exit 2 blocks stopping). The next UserPromptSubmit surfaces the loud
+    // warning; no pending is written, so this is not a silent "all clear" — there was no verdict.
     await recordHookEventFn({
       projectRoot,
       event: {
         hook: 'Stop',
-        status: 'error',
+        status: 'degraded',
         code: err?.code ?? 'E_INTERNAL',
+        reason: 'transport',
         durationMs: Date.now() - startedAt,
       },
     });
-    dieFn(`stop transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
     return;
   }
 
   if (response.ok !== true) {
+    // Auditor backend failed (e.g. codex login expired): record + exit 0. Forcing a continuation
+    // (exit 2) on a Spotter-side failure is harmful; the loud warning is delivered by the next
+    // UserPromptSubmit. No verdict was produced, so nothing is queued.
     await recordHookEventFn({
       projectRoot,
       event: {
         hook: 'Stop',
-        status: 'error',
+        status: 'degraded',
         code: response.error?.code ?? 'E_INTERNAL',
+        reason: 'daemon_error',
         durationMs: Date.now() - startedAt,
       },
     });
-    dieFn(`daemon error on turn_end: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
     return;
   }
 
@@ -117,9 +124,10 @@ export async function runStop({
   // decision:"block". Using the same transparent block-reason wording keeps the user-facing
   // text identical to the prior block flow.
   if (!projectRoot) {
-    // Marker walk-up returns null only when isOutsideSpotterProject would have early-returned
-    // above. Reaching here implies the marker disappeared mid-turn; treat as unexpected.
-    dieFn(`stop: cannot queue pending context — no .spotter/marker.json above cwd=${input.cwd}`, 2);
+    // TOCTOU: the marker disappeared between the isOutsideSpotterProject guard and now. We cannot
+    // persist the finding (no project dir to write into), but a Stop exit 2 would force the model
+    // to continue — the harmful pattern this hook avoids. Drop the unpersistable finding and exit
+    // 0; the next UserPromptSubmit re-audits from a fresh marker walk.
     return;
   }
   const text = formatTransparentBlockReason(result.missing_tools);

package/src/hooks/user-prompt.mjs

@@ -16,9 +16,9 @@
 import {
   readStdinJson,
   requireString,
-  exitCodeFor,
   die,
   formatTransparentContext,
+  formatSpotterWarning,
   isChildCall,
   isSubagentCall,
   isOutsideSpotterProject,
@@ -39,7 +39,6 @@ export async function runUserPrompt({
   drainPendingContextsFn = drainPendingContexts,
   recordHookEventFn = recordClaudeHookEvent,
   writeOutput = (text) => process.stdout.write(text),
-  dieFn = die,
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -58,6 +57,26 @@ export async function runUserPrompt({
     ? await drainPendingContextsFn({ projectRoot, sessionId })
     : [];
 
+  // Loud degradation (§0 / §14.1): the audit could not run, but the user's prompt is valid.
+  // Surface a visible [Spotter からの警告] (merged with any drained pending context) and exit 0
+  // so the prompt reaches the host — never erase it with a blocking exit 2.
+  const degrade = async ({ code, message, reason }) => {
+    const contexts = pendingContexts.slice();
+    contexts.push(formatSpotterWarning({ code, message }));
+    emitAdditionalContext(writeOutput, contexts);
+    await recordHookEventFn({
+      projectRoot,
+      event: {
+        hook: 'UserPromptSubmit',
+        status: 'degraded',
+        code: code ?? 'E_INTERNAL',
+        reason,
+        pendingContextCount: pendingContexts.length,
+        durationMs: Date.now() - startedAt,
+      },
+    });
+  };
+
   if ([...prompt.trim()].length <= SHORT_PROMPT_MAX_CHARS) {
     if (pendingContexts.length > 0) {
       emitAdditionalContext(writeOutput, pendingContexts);
@@ -88,67 +107,31 @@ export async function runUserPrompt({
     response = await sendUserInput();
   } catch (err) {
     if (err instanceof TransportError && err.code === 'E_UNREACHABLE') {
-      // v0.12.0: daemon is gone (heartbeat shutdown, crash, missing). Resurrect and retry.
-      if (!projectRoot) {
-        dieFn(`user-prompt: cannot resurrect daemon — no .spotter/marker.json above cwd=${input.cwd}`, 2);
-        return;
-      }
+      // v0.12.0: daemon is gone (heartbeat shutdown, crash, missing). Resurrect and retry once.
+      // projectRoot is guaranteed non-null here (isOutsideSpotterProject early-returned otherwise).
       try {
         await spawnDaemonAndWaitReadyFn({ sessionId, projectRoot });
-      } catch (spawnErr) {
-        await recordHookEventFn({
-          projectRoot,
-          event: {
-            hook: 'UserPromptSubmit',
-            status: 'error',
-            code: spawnErr?.code ?? 'E_RESURRECT_FAILED',
-            durationMs: Date.now() - startedAt,
-          },
-        });
-        dieFn(`user-prompt: daemon resurrect failed: ${spawnErr.message}`, spawnErr.exitCode ?? 2);
-        return;
-      }
-      try {
         response = await sendUserInput();
-      } catch (retryErr) {
-        await recordHookEventFn({
-          projectRoot,
-          event: {
-            hook: 'UserPromptSubmit',
-            status: 'error',
-            code: retryErr?.code ?? 'E_INTERNAL',
-            durationMs: Date.now() - startedAt,
-          },
+      } catch (recoverErr) {
+        await degrade({
+          code: recoverErr?.code ?? 'E_RESURRECT_FAILED',
+          message: recoverErr?.message ?? '',
+          reason: 'resurrect_failed',
         });
-        dieFn(`user-prompt transport failure after resurrect: ${retryErr.code ?? '?'}: ${retryErr.message}`, exitCodeFor(retryErr));
         return;
       }
     } else {
-      await recordHookEventFn({
-        projectRoot,
-        event: {
-          hook: 'UserPromptSubmit',
-          status: 'error',
-          code: err?.code ?? 'E_INTERNAL',
-          durationMs: Date.now() - startedAt,
-        },
-      });
-      dieFn(`user-prompt transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
+      await degrade({ code: err?.code ?? 'E_INTERNAL', message: err?.message ?? '', reason: 'transport' });
       return;
     }
   }
 
   if (response.ok !== true) {
-    await recordHookEventFn({
-      projectRoot,
-      event: {
-        hook: 'UserPromptSubmit',
-        status: 'error',
-        code: response.error?.code ?? 'E_INTERNAL',
-        durationMs: Date.now() - startedAt,
-      },
+    await degrade({
+      code: response.error?.code ?? 'E_INTERNAL',
+      message: response.error?.message ?? '',
+      reason: 'daemon_error',
     });
-    dieFn(`daemon error on user_input: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
     return;
   }