claude-spotter 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.6.0
+
+**Preamble-once: 初回のみ role+schema+catalog を送り、以降は per-turn delta のみ**。v0.5.x で実測した「resumed 呼び出しが first より遅い」問題の原因に手を入れた構造変更。
+
+### 事の発端
+
+v0.5.2 で可視化した duration_ms を数ターン観測したところ、`mode=first=7.4s → mode=resumed=12.5s → mode=resumed=20.2s` と、**resumed が first より遅い**結果になった。プラン §5.5 は「`--resume` で cold-start を消せる」を前提にしていたので、この傾向は設計意図と逆。
+
+調べたところ、v0.5.x の daemon は Haiku 呼び出しのたびに `SHARED_HEADER + catalog + user_input + instruction` を full で組み立てて送っていた。つまり `--resume` で session を継いでいるのに、毎回同じ前置きを再送して session を肥大化させていた。`--resume` の prefill caching 節約より、肥大した prompt の送信・prefill コストのほうが大きい、という構造。
+
+同作者の [OpenClaw](https://github.com/kitepon-rgb/OpenClaw) は Discord から同一セッションへ長期間会話を流し続ける運用で、こちらは**初回のみ role を確立し以降は差分だけ送る**形で動いている。Spotter にも同じ形を持ち込めば、resumed のコストが first より重くなる理由は消えるはず。
+
+### 変更点
+
+- **[src/daemon/haiku-caller.mjs](src/daemon/haiku-caller.mjs)**: `buildPreamble({ catalog })` を新設。`SHARED_HEADER` に `stage=user_input` / `stage=turn_end` 両方の判定指示と few-shot を集約し、カタログと一緒に初回 1 回だけ送る。`buildFirstStagePrompt` / `buildFinalStagePrompt` はカタログと role を剥がして per-turn payload (stage マーカー + 入力タグ) のみに縮小。`createHaikuCaller({ preamble, ... })` が optional preamble を受け取り、`isFirstCall === true` のときだけ prompt に prepend する。`reset()` は `isFirstCall = true` を復元するので role collapse 回復時は新 session に preamble が再送される。
+- **[src/daemon/daemon.mjs](src/daemon/daemon.mjs)**: startup で `buildPreamble({ catalog })` を 1 回作って `createHaikuCaller` に渡す。`handleUserInput` / `handleTurnEnd` の呼び出し側はカタログを渡さないシンプルな形に戻る (カタログは daemon 内部でのみ保持、preamble に封じ込む)。
+- **[test/haiku-caller.test.mjs](test/haiku-caller.test.mjs)**: `buildPreamble` が role+schema+catalog+few-shot を全て含むこと、per-turn 側のプロンプトが catalog/role を含まないこと、non-string な preamble が TypeError になることを検証。
+- **[test/daemon.test.mjs](test/daemon.test.mjs)**: 既存の「every Haiku invocation receives the full catalog prompt」テストを **逆の主張 (per-turn prompt は catalog を含まない)** に置き換え。
+
+### 期待される効果
+
+- **per-turn prompt サイズが大幅減**: v0.5.x の full prompt (カタログ JSON + SHARED_HEADER + few-shot で 2KB 前後) が、v0.6.0 では stage マーカー + ユーザー入力 (数百バイト) に縮む。Stop hook 側は final_response と used_tools の分だけ増えるが、カタログ再送よりは軽い。
+- **resumed の cold-start 削減が数値で出るはず**: 次セッションで `mode=resumed, duration_ms=<N>` が `mode=first` より短ければ、プラン §5.5 の前提が正しく機能したことが実測で確認できる。
+- **role collapse 耐性**: 既存の reset 機構はそのまま動き、session renew 時に preamble が自動で再送される構造なので、v0.5.x の回復挙動を保存。
+
+### 既知のリスク
+
+- 「preamble を session replay 任せにする」ので、Anthropic 側で session replay が不完全だと Haiku が role を見失う (= role collapse 発生頻度が上がる可能性)。v0.5.0 で入れた `E_HAIKU_SCHEMA → reset()` 回復機構と `role_collapse_reset` ログで観測可能。多発するなら preamble を毎回送る形に戻す判断を v0.6.1 以降で検討。
+
 ## 0.5.2
 
 **Haiku 呼び出しのレイテンシ可視化 (観測性の改善のみ、機能変更なし)**。

package/package.json

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

package/src/daemon/daemon.mjs

@@ -1,13 +1,17 @@
 // Session-scoped daemon — receives hook events, dispatches to handlers,
 // calls Haiku on user_input / turn_end, keeps used_tools in process memory.
 //
+// v0.6.0: preamble (role + schema + catalog) is sent only on the first Haiku call of the
+// session; subsequent calls send only the per-turn delta, relying on --resume to replay
+// the preamble from session history. This is the OpenClaw pattern and addresses v0.5.x's
+// "resumed calls slower than first" observation (prompt bloat had been outweighing the
+// --resume prefill savings).
+//
 // v0.5.0: Haiku calls are session-scoped at the claude -p layer (--session-id + --resume).
-// The daemon holds one Haiku caller for the session's lifetime; the first call establishes
-// the claude -p session and every subsequent call reattaches, avoiding cold-start spawn.
-// Role collapse (Haiku drifting into Bell's persona, previously the reason v0.4.0 reverted
-// to stateless) is handled by a recovery mechanism rather than structural prevention:
-// E_HAIKU_SCHEMA → haikuCaller.reset() + silent-pass the offending turn. This is the §0
-// "想定済み異常 = 記録 + 正常リターン" classification.
+// Role collapse (Haiku drifting into Bell's persona) is handled by recovery rather than
+// structural prevention: E_HAIKU_SCHEMA → haikuCaller.reset() + silent-pass the offending
+// turn (a §0 "想定済み異常 = 記録 + 正常リターン" classification). reset() restores
+// isFirstCall=true so the next attempt re-sends the preamble on a fresh session.
 //
 // §5.7: event dispatch follows the envelope contract.
 // §14:  unexpected errors are thrown; hooks convert them to exit codes.
@@ -26,6 +30,7 @@ import { createServer, ensureRuntimeDir, socketPath } from './transport.mjs';
 import {
   buildFirstStagePrompt,
   buildFinalStagePrompt,
+  buildPreamble,
   parseHaikuResponse,
   createHaikuCaller,
   HaikuError,
@@ -73,7 +78,11 @@ export async function startDaemon({
   const catalog = await loadCatalog(catalogPath);
   logFn(`catalog loaded: ${catalog.tools.length} tools from ${catalogPath}`);
 
-  const callHaiku = haikuCaller ?? createHaikuCaller({ timeoutMs: DEFAULT_HAIKU_TIMEOUT_MS });
+  // v0.6.0: preamble (role + schema + catalog) is built once and threaded into the Haiku
+  // caller. The caller prepends it on the first call only; --resume keeps it in session
+  // history for all subsequent calls.
+  const preamble = buildPreamble({ catalog });
+  const callHaiku = haikuCaller ?? createHaikuCaller({ preamble, timeoutMs: DEFAULT_HAIKU_TIMEOUT_MS });
 
   // Per-turn state, reset on turn_end.
   const state = {
@@ -169,7 +178,7 @@ export async function startDaemon({
     state.lastUserInput = userInput;
     state.usedTools = []; // reset tools for this turn
 
-    const { parsed, meta } = await runHaikuJudgment('user_input', buildFirstStagePrompt({ catalog, userInput }));
+    const { parsed, meta } = await runHaikuJudgment('user_input', buildFirstStagePrompt({ userInput }));
     logFn(
       `user_input: pass=${parsed.pass}, missing=${parsed.missing_tools.map((m) => m.name).join(',')}, mode=${meta.mode}, duration_ms=${meta.durationMs}${
         parsed.reason ? `, reason=${parsed.reason}` : ''
@@ -213,7 +222,6 @@ export async function startDaemon({
     const { parsed, meta } = await runHaikuJudgment(
       'turn_end',
       buildFinalStagePrompt({
-        catalog,
         userInput: savedUserInput,
         usedTools: savedUsedTools,
         finalResponse,

package/src/daemon/haiku-caller.mjs

@@ -1,17 +1,17 @@
 // claude -p --model claude-haiku-4-5-* wrapper.
 // §5.5: structured JSON I/O, no retries, schema violations throw.
 //
-// v0.5.0: session-scoped Haiku is back. Each daemon holds a single Haiku session-id for
-// the life of the Bell session; the first call uses --session-id only, subsequent calls
-// use --session-id + --resume to reattach to the same claude -p conversation, avoiding
-// per-turn cold-start spawn (observed 20–50s in v0.4.x stateless mode).
+// v0.6.0: preamble-once. The full role + schema + few-shot + catalog (the "preamble") is
+// sent only on the first call of a Haiku session; every subsequent call sends only the
+// per-turn delta. Anthropic's --resume replays the preamble from session history, so
+// Haiku keeps its role and catalog context without us re-transmitting ~2KB of boilerplate
+// per turn. This is the OpenClaw pattern (same author, proven in production with Discord
+// → Claude long-lived sessions). Role collapse remains handled by reset() → fresh session
+// → preamble resent on next call.
 //
-// Role-collapse (Haiku drifting into Bell's persona over long sessions — the failure mode
-// v0.4.0 reverted to stateless to avoid) is now handled by a recovery mechanism instead of
-// structural prevention: if the daemon detects a schema violation (E_HAIKU_SCHEMA) from
-// parseHaikuResponse, it calls reset() on the caller to renew the session-id, then silent-
-// passes the offending turn. See daemon.mjs for the catch site. This makes role collapse a
-// "想定済み異常" (CLAUDE.md §0) — recorded, recovered from, never bubbled up as exit 2.
+// v0.5.x prior behaviour (re-sending full context every turn) made subsequent "resumed"
+// calls *slower* than the first (prompt bloat outweighed --resume prefill savings). v0.6.0
+// puts the catalog only in the first turn's user message; the session retains it for free.
 
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
@@ -36,13 +36,8 @@ export async function ensureWorkdir() {
   return WORKDIR;
 }
 
-// v0.4.3 minimization (retained in v0.5.0):
-//   Aggressive trim — no adversarial prompt-injection list, no 【最重要】 tags, no triple
-//   restatement. The judgment-anchoring instruction at the tail stays prominent.
-//
-// Shared header (role + schema + few-shot) is identical between first/final stages, which
-// keeps the Anthropic prompt-cache prefix stable across calls of the same stage.
-
+// Shared header covers BOTH stages — the preamble documents stage=user_input and
+// stage=turn_end so per-turn prompts only need to announce which stage they are.
 const SHARED_HEADER = [
   'あなたは Spotter。Bell (主役の Claude) が呼び忘れるツールを検出する監査役です。',
   'ユーザーへの会話文は生成せず、必ず下記 JSON のみを返します。',
@@ -52,50 +47,55 @@ const SHARED_HEADER = [
   '- pass:true なら missing_tools は空、pass:false なら 1 件以上',
   '- JSON のみ。前置き・コードフェンス禁止',
   '',
+  '## 判定対象',
+  '各ターン、以下いずれかの stage で判定リクエストを受けます:',
+  '- stage=user_input: <user_input> のみ届く。when_to_use に明確に該当するツールを列挙',
+  '- stage=turn_end: <user_input> + <used_tools> + <final_response> が届く。既使用を除き Bell が呼び忘れたツールを列挙',
+  'どちらも推測禁止。該当なしなら pass:true。',
+  '',
   '## 例',
-  '- "今何時?" → {"pass":false,"missing_tools":[{"name":"current_time","reason":"時刻の直接質問"}]}',
-  '- "ありがとう" → {"pass":true,"missing_tools":[]}',
+  '- stage=user_input "今何時?" → {"pass":false,"missing_tools":[{"name":"current_time","reason":"時刻の直接質問"}]}',
+  '- stage=user_input "ありがとう" → {"pass":true,"missing_tools":[]}',
 ].join('\n');
 
-// Build the first-stage prompt — sent on UserPromptSubmit before tools are invoked.
-export function buildFirstStagePrompt({ catalog, userInput }) {
+// Preamble — sent exactly once per Haiku session (first call). Contains the role,
+// output contract, few-shot examples, and the tool catalog. The Anthropic session
+// retains this in history so subsequent --resume calls can judge with only a small
+// per-turn payload.
+export function buildPreamble({ catalog }) {
   return [
     SHARED_HEADER,
     '',
     '## カタログ',
     JSON.stringify(projectCatalog(catalog), null, 2),
-    '',
-    '## ユーザー入力',
+  ].join('\n');
+}
+
+// Per-turn prompt — UserPromptSubmit stage. Sent as-is on every call (first and resumed);
+// createHaikuCaller prepends the preamble on first call only.
+export function buildFirstStagePrompt({ userInput }) {
+  return [
+    'stage=user_input',
     '<user_input>',
     userInput,
     '</user_input>',
-    '',
-    'when_to_use に明確に該当するツールだけを列挙。推測禁止。該当なしなら pass:true。',
   ].join('\n');
 }
 
-// Build the final-stage prompt — Stop hook, after Bell's response.
-export function buildFinalStagePrompt({ catalog, userInput, usedTools, finalResponse }) {
+// Per-turn prompt — Stop hook stage.
+export function buildFinalStagePrompt({ userInput, usedTools, finalResponse }) {
+  const usedList = usedTools.length > 0 ? usedTools.map((t) => `- ${t}`).join('\n') : '(なし)';
   return [
-    SHARED_HEADER,
-    '',
-    '## カタログ',
-    JSON.stringify(projectCatalog(catalog), null, 2),
-    '',
-    '## ユーザー入力',
+    'stage=turn_end',
     '<user_input>',
     userInput,
     '</user_input>',
-    '',
-    '## Bell が既に使用したツール',
-    usedTools.length > 0 ? usedTools.map((t) => `- ${t}`).join('\n') : '(なし)',
-    '',
-    '## Bell の応答',
+    '<used_tools>',
+    usedList,
+    '</used_tools>',
     '<final_response>',
     finalResponse,
     '</final_response>',
-    '',
-    '既使用ツールを除き、when_to_use に明確に該当するのに Bell が呼び忘れたツールを列挙。推測禁止。該当なしなら pass:true。',
   ].join('\n');
 }
 
@@ -167,11 +167,6 @@ function truncate(s, n = 300) {
 // On Windows, the `claude` entry is typically a .cmd shim which Node's spawn cannot locate
 // without going through the shell. We use cmd.exe /c explicitly rather than spawn({ shell:
 // true }) because the latter triggers DEP0190 on Node 24+.
-//
-// v0.5.1: claude CLI rejects `--session-id` together with `--resume` unless `--fork-session`
-// is present (fork would create a new id, defeating the point). So first call uses
-// `--session-id <uuid>` to pin the id; every subsequent call uses `--resume <uuid>` alone to
-// re-attach. buildSpawnArgs is exported so tests can assert flag wiring without spawning.
 export function buildSpawnArgs({ claudeBin, model, sessionId, resume }) {
   const args = resume
     ? ['-p', '--resume', sessionId, '--model', model]
@@ -186,20 +181,25 @@ export function buildSpawnArgs({ claudeBin, model, sessionId, resume }) {
 // §5.5: no retry on failure. §14.1: silent fallback forbidden (role-collapse recovery in
 // daemon.mjs is an explicit §0 exception, not silent fallback).
 //
-// v0.5.0: session-scoped. The caller keeps one session-id for the session's lifetime, and
-// exposes a reset() method that rotates the session-id (used by daemon on E_HAIKU_SCHEMA
-// to recover from role collapse). The returned value is a function (so existing tests that
-// check `typeof caller === 'function'` still pass) with `reset` and `sessionId` attached.
-export function createHaikuCaller({ timeoutMs, claudeBin = 'claude', model = HAIKU_MODEL, env = process.env }) {
+// v0.6.0: accepts an optional `preamble` string that is prepended to the user message on
+// the first call only. Subsequent calls (after a successful first call) send only the
+// per-turn prompt — the preamble lives in Anthropic's session history via --resume. A
+// reset() call (used on role collapse) restores isFirstCall=true so the preamble is
+// re-sent on the next attempt with a fresh session-id.
+export function createHaikuCaller({ preamble, timeoutMs, claudeBin = 'claude', model = HAIKU_MODEL, env = process.env }) {
   if (typeof timeoutMs !== 'number' || timeoutMs <= 0) {
     throw new TypeError('timeoutMs must be a positive number');
   }
+  if (preamble !== undefined && typeof preamble !== 'string') {
+    throw new TypeError('preamble must be a string if provided');
+  }
 
   let currentSessionId = randomUUID();
   let isFirstCall = true;
 
   const callHaiku = async function (prompt) {
     await ensureWorkdir();
+    const wirePrompt = (isFirstCall && preamble) ? `${preamble}\n\n${prompt}` : prompt;
     return new Promise((resolve, reject) => {
       const { cmd, cmdArgs } = buildSpawnArgs({
         claudeBin,
@@ -243,13 +243,13 @@ export function createHaikuCaller({ timeoutMs, claudeBin = 'claude', model = HAI
           return;
         }
         // Flip isFirstCall only after a successful spawn — a failed first call should
-        // still be treated as "session not yet established" so the next attempt uses
-        // --session-id only (not --resume against a non-existent session).
+        // still be treated as "preamble not yet delivered" so the next attempt re-sends
+        // the full prelude against a fresh --session-id (not --resume a non-existent one).
         isFirstCall = false;
         resolve(stdout);
       });
 
-      child.stdin.end(prompt, 'utf8');
+      child.stdin.end(wirePrompt, 'utf8');
     });
   };