claude-spotter 1.4.28 → 1.4.29

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.4.29 — 2026-08-04
+
+- **提案率とtool採用率の端末内評価を追加。** Claude / Codexの成功UserPromptSubmitを母数に、
+  safe projector後に実際に提示したtool itemと、同じturnでのcanonical tool利用を
+  `~/.spotter/evaluation.db`へ記録する。採用率の母数はoutcome確定itemだけとし、利用記録不全は
+  `outcome_missing`へ分離する。組込みtoolは評価対象外で、既存turn-end auditorのraw usedToolsは変更しない。
+- **提案時の別文脈を保存。** proposal確定時刻を記録し、既存Throughline `observer-read`を一度だけ呼ぶ。
+  Spotterがauditorへ渡したcontextとは別fieldに保存し、失敗時はcontextだけunavailableとしてretryしない。
+  返却されたhost / thread hashを提案元sessionと照合し、同じprojectの並行sessionを取り違えた場合も
+  snapshotを保存しない。
+- **欠測とtool identityを率から分離。** Claudeの利用記録失敗、Codex transcript不全、Stopが30分以上
+  欠落したopen proposalは`outcome_missing`として投影し、非採用へ混ぜない。Codex Skillは提案済みの
+  正規`SKILL.md`を実際にreadしたcallだけを採用として認識する。現行Codexのouter `exec`内で実行される
+  nested MCP callと、同じturn内の複数`exec`も個別の利用入力として保持する。
+- **初回同時openを直列化。** 2 projectが未作成の評価DBを同時に開いてもWAL設定前に
+  `database is locked`とならないよう、bounded busy timeoutをschema初期化より先に有効化する。
+  retry、lockfile、background回収は追加しない。
+- **評価CLIを追加。** `spotter evaluation report`で全project / project / tool / host別の
+  `S/P/I/C/A/M`、`P/S`、`A/C`を表示し、`cases` / `case`で非採用caseのrequest、2種類の文脈、
+  提案ID、利用ID、outcomeを確認できる。reportは保存済みSQLiteだけを読み、JSONはWindows
+  PowerShell 5.1でも壊れないASCII-safe形式で出力する。
+- **検証・公開。** 固定fixture、Claude / Codex hook、Throughline束縛、2 process同時writeを含む
+  568 tests（macOS / Linuxは566 pass / 2 skip、Windowsは556 pass / 12 platform skip）、
+  macOS / Linux / Windows × Node 22.13 / 22.xのCI run `30913375991`、75-file packを通過した。
+  別projectの実Codex turnではThroughline文脈付きproposalから
+  `S=1 P=1 I=1 C=1 A=1 M=0`を記録し、Claude実turnのpass観測と両hostのproposal fixtureも確認した。
+  Windowsではouter `exec`内の絶対pathを壊さずSkill採用へ変換する回帰も固定した。
+
 ## 1.4.28 — 2026-07-21
 
 - **Windows Codex SessionStartの誤timeoutを修正。** detached refreshを起動するSpotter所有hookの

package/README.ja.md

@@ -13,6 +13,16 @@
 
 > **気づく役と実行する役を分離する。** Claude Code の横で並走し、主役の Claude が**ツールを呼び忘れたとき**だけ静かに指摘する監査役。
 
+[kitepon.dev](https://kitepon.dev/)を運営する[クオ（@QLyun35332）](https://x.com/QLyun35332)が
+開発・メンテナンスしています。
+
+## 所有境界
+
+本repositoryは監査挙動、project marker、installer、release、diagnosticsを所有します。
+製品横断のcatalogとhost統合は、kitepon.devの製品開発を支える内部基盤
+[dotagents](https://github.com/kitepon-rgb/dotagents)が担当します。
+MarkItDownは別区分の第三者CLIです。
+
 Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。記録すべき決定を memory / caveat MCP に残さない、docs lookup MCP を呼ばずに古い知識で応答する、ブラウザ自動化 MCP で確認せず UI 状態を推測する — **「分からないと自覚できない」から、ツールを取りに行けない**。
 
 Spotter はツールカタログを完全に把握した別の監査エージェントで、ユーザー入力と主役 AI の応答を並走監査します。自動選択では Claude host は Codex CLI があればそれを、なければ session-scoped Haiku を選び、Codex host は Codex CLI を既定にします。明示 backend override は host より優先しますが、runtime failure で別 backend へ黙って切り替えません。応答前は検証済みtool IDだけを固定・非命令形の助言へ変換でき、応答後のfindingは構造eventに留めて後続turnへ注入しません。監査用AIの自由文が親セッションへ入ることはありません。**主役 AI が自覚して自己監査する**設計は本プロダクトの存在意義を破壊するため、hook 経由でその意思と独立に検出します。
@@ -207,6 +217,12 @@ spotter db rebuild       # Claude local + Claude global DB を両方消してか
 spotter status           # 稼働中の daemon 一覧
 spotter doctor           # 環境診断 (Node / claude CLI / Codex readiness / tool-db 整合性)
 spotter diagnostics logs # daemon log から pass=false / backend latency / anomaly signal を集計
+spotter evaluation report
+                         # 端末内DBからproject横断の提案率・tool採用率を集計
+spotter evaluation cases --outcome not-adopted
+                         # 提案されたが同じturnで使われなかったtool itemを一覧
+spotter evaluation case <observation-id>
+                         # request、2種類の文脈、提案、利用、outcomeを確認
 spotter codex risk-check --findings findings.json --host-agent claude
                          # Spotter finding を codex-sidecar に渡して read-only risk analysis
 spotter codex review|explore|opinion --findings findings.json --host-agent claude

package/README.md

@@ -13,6 +13,16 @@
 
 > **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**.
 
+Built and maintained by [Quo](https://x.com/QLyun35332) at [kitepon.dev](https://kitepon.dev/en).
+
+## Ownership boundary
+
+This repository owns auditor behavior, project markers, installers, release,
+and diagnostics. The cross-product catalog and host integration are handled by
+[dotagents](https://github.com/kitepon-rgb/dotagents), the internal development
+toolchain behind kitepon.dev's products.
+MarkItDown is managed separately as a third-party CLI.
+
 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 runs a separate auditor with the full tool catalog and checks both the user's prompt and the primary agent's reply. Automatic selection uses Codex CLI on a Claude host when available, otherwise the session-scoped Haiku path; on a Codex host it defaults to Codex CLI. An explicit backend override takes precedence, but a runtime failure never silently switches backend. Before the primary reply, validated tool IDs may become fixed, non-directive advice; after the reply, findings remain structured events and are not injected into a later turn. Auditor prose never enters the parent session. **The primary agent is never asked to self-audit** — that would defeat the premise. Detection happens through hooks, independent of the primary agent's intent.
@@ -216,6 +226,12 @@ spotter doctor           # environment check (Node / claude CLI / Codex readines
 spotter diagnostics logs # summarize daemon logs for pass=false / backend latency / anomaly signals
 spotter diagnostics runtime-errors
                          # print the local allow-listed runtime-error aggregate snapshot (no network)
+spotter evaluation report
+                         # show cross-project proposal/adoption counts and rates from the local DB
+spotter evaluation cases --outcome not-adopted
+                         # list proposed tools that were not used in the same turn
+spotter evaluation case <observation-id>
+                         # inspect request, Spotter context, Throughline snapshot, proposal, usage, and outcome
 spotter codex risk-check --findings findings.json --host-agent claude
                          # run read-only codex-sidecar risk analysis for Spotter findings
 spotter codex review|explore|opinion --findings findings.json --host-agent claude

package/bin/spotter.mjs

@@ -11,6 +11,7 @@ import { runCodexCommand } from '../src/cli/codex-cmd.mjs';
 import { runCodexHookCommand } from '../src/cli/codex-hook-cmd.mjs';
 import { runAuditorCommand } from '../src/cli/auditor-cmd.mjs';
 import { runDiagnosticsCommand } from '../src/cli/diagnostics-cmd.mjs';
+import { runEvaluationCommand } from '../src/cli/evaluation-cmd.mjs';
 import { runFactoryDiagnostics } from '../src/cli/factory-diagnostics.mjs';
 import { runDaemonStart } from '../src/cli/daemon-cmd.mjs';
 import { runSessionStart } from '../src/hooks/session-start.mjs';
@@ -45,6 +46,10 @@ Usage:
   spotter diagnostics logs [--json]     summarize daemon logs for precision diagnostics
   spotter diagnostics runtime-errors [snapshot|ack|resolve|reopen|compact]
                                         consume the local allow-listed aggregate store
+  spotter evaluation report [filters] [--json]
+  spotter evaluation cases --outcome OUTCOME [filters] [--json]
+  spotter evaluation case OBSERVATION_ID [--json]
+                                        read saved proposal-adoption observations
   spotter codex risk-check --findings FILE
                                         run read-only codex-sidecar risk analysis
   spotter codex review|explore|opinion --findings FILE
@@ -124,6 +129,9 @@ async function main() {
       }
       await runDiagnosticsCommand({ argv: rest });
       return;
+    case 'evaluation':
+      await runEvaluationCommand({ argv: rest });
+      return;
     case 'daemon': {
       const sub = rest[0];
       if (sub === 'start') { await runDaemonStart({ argv: rest.slice(1) }); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "1.4.28",
+  "version": "1.4.29",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {
@@ -11,6 +11,8 @@
   },
   "scripts": {
     "test": "node --test",
+    "verify:release-commit": "node scripts/verify-release-commit.mjs",
+    "prepublishOnly": "npm run verify:release-commit && npm test",
     "postinstall": "node scripts/postinstall.mjs",
     "preuninstall": "node scripts/preuninstall.mjs"
   },
@@ -23,7 +25,10 @@
     "audit",
     "spotter"
   ],
-  "author": "kitepon",
+  "author": {
+    "name": "Quo / クオ at kitepon.dev",
+    "url": "https://kitepon.dev/"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/verify-release-commit.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+// publishする成果が、既定ブランチへ着地済みのcommitから作られていることを保証する。
+// 着地していないbranchからpublishすると、そのbranchが取り残された時点で公開物が
+// 後続releaseから消え、統合契約だけが存在しない面を指し続ける（0.3.0の孤児releaseが実例）。
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptPath = fileURLToPath(import.meta.url);
+const defaultProjectDirectory = path.dirname(path.dirname(scriptPath));
+
+export function verifyReleaseCommit({
+  projectDirectory = defaultProjectDirectory,
+  spawn = spawnSync,
+} = {}) {
+  const git = (...args) => {
+    const result = spawn("git", args, { cwd: projectDirectory, encoding: "utf8" });
+    return { ok: result.status === 0, stdout: (result.stdout ?? "").trim() };
+  };
+
+  const head = git("rev-parse", "HEAD");
+  assert.ok(head.ok, "git HEAD を解決できません");
+  const originHead = git("symbolic-ref", "--quiet", "refs/remotes/origin/HEAD");
+  const defaultRef = originHead.ok && originHead.stdout
+    ? originHead.stdout.replace("refs/remotes/", "")
+    : "origin/main";
+  const defaultResolved = git("rev-parse", "--verify", `${defaultRef}^{commit}`);
+  assert.ok(defaultResolved.ok, `既定ブランチ ${defaultRef} を解決できません。git fetch origin を先に実行してください。`);
+  const isAncestor = git("merge-base", "--is-ancestor", head.stdout, defaultRef);
+  assert.ok(
+    isAncestor.ok,
+    `publish対象 ${head.stdout.slice(0, 12)} が ${defaultRef} の祖先ではありません。`
+      + " 先に既定ブランチへ着地させてpushしてから publish してください。"
+  );
+  const dirty = git("status", "--porcelain", "--untracked-files=normal");
+  assert.ok(dirty.ok, "working treeの状態を確認できません");
+  assert.equal(
+    dirty.stdout,
+    "",
+    `working treeに未commitの変更があります。publish対象commitとpayloadが一致しません:\n${dirty.stdout}`
+  );
+  return `release commit ${head.stdout.slice(0, 12)} is landed on ${defaultRef}.`;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === scriptPath) {
+  console.log(verifyReleaseCommit());
+}

package/scripts/verify-release-commit.test.mjs

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { verifyReleaseCommit } from "./verify-release-commit.mjs";
+
+function git(cwd, ...args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+
+async function createReleaseFixture(t) {
+  const root = await mkdtemp(path.join(tmpdir(), "spotter-release-gate-"));
+  const remote = path.join(root, "origin.git");
+  const work = path.join(root, "work");
+  t.after(async () => rm(root, { recursive: true, force: true }));
+  await mkdir(work);
+  git(root, "init", "--bare", remote);
+  git(work, "init", "--initial-branch=main");
+  git(work, "config", "user.name", "Spotter release gate test");
+  git(work, "config", "user.email", "spotter-release-gate@example.invalid");
+  await writeFile(path.join(work, ".gitignore"), "ignored.tmp\n", "utf8");
+  await writeFile(path.join(work, "tracked.txt"), "tracked\n", "utf8");
+  git(work, "add", ".gitignore", "tracked.txt");
+  git(work, "commit", "-m", "fixture");
+  git(work, "remote", "add", "origin", remote);
+  git(work, "push", "--set-upstream", "origin", "main");
+  return work;
+}
+
+test("release gate passes for a commit landed on main", async (t) => {
+  const work = await createReleaseFixture(t);
+  assert.match(verifyReleaseCommit({ projectDirectory: work }), /landed on origin\/main/);
+});
+
+test("release gate rejects an untracked publish payload", async (t) => {
+  const work = await createReleaseFixture(t);
+  await writeFile(path.join(work, "untracked.txt"), "must block publish\n", "utf8");
+  assert.throws(() => verifyReleaseCommit({ projectDirectory: work }), /working treeに未commitの変更があります/);
+});
+
+test("release gate permits ignored generated output", async (t) => {
+  const work = await createReleaseFixture(t);
+  await writeFile(path.join(work, "ignored.tmp"), "generated\n", "utf8");
+  assert.match(verifyReleaseCommit({ projectDirectory: work }), /landed on origin\/main/);
+});

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

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -34,6 +35,15 @@ import {
   readProjectAuditorContextConfig,
 } from '../core/auditor-context.mjs';
 import { observeRuntimeErrorIsolatedSafe } from '../core/runtime-error-store.mjs';
+import { createEvaluationStore } from '../core/evaluation-store.mjs';
+import { loadEvaluationObserverContext } from '../core/evaluation-context.mjs';
+import {
+  canonicalizeCodexNestedMcpToolIds,
+  canonicalizeCodexSkillReadToolIds,
+  canonicalizeProposedToolIds,
+  canonicalizeUsedToolIds,
+} from '../core/evaluation-tool-id.mjs';
+import { version as SPOTTER_VERSION } from '../version.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
@@ -125,22 +135,77 @@ export async function runCodexUserPromptSubmitHook({
   writeOutput = (text) => process.stdout.write(text),
   writeError = (text) => process.stderr.write(text),
   runtimeErrorObserver = async () => ({ collected: false, reason: 'observer_not_configured' }),
+  createEvaluationStoreFn = createEvaluationStore,
+  loadEvaluationObserverContextFn = loadEvaluationObserverContext,
+  randomUUIDFn = randomUUID,
+  now = () => Date.now(),
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
+  const observationId = randomUUIDFn();
+  const recordedAtMs = now();
   const projectRoot = findSpotterMarker(input.cwd);
   if (!projectRoot) return;
   const startedAt = Date.now();
   let contextDurationMs = null;
+  let auditorContextConfig;
 
   const prompt = requireString(input, 'prompt');
+  const sessionId = codexSessionId(input);
+  const recordEvaluation = async ({ auditStatus, proposedToolIds = [], backend = null, model = null, auditorSeenContext = null, config = undefined }) => {
+    if (!sessionId) {
+      reportEvaluationFailure(writeError);
+      return;
+    }
+    const proposals = canonicalizeProposedToolIds(proposedToolIds);
+    let observerContext = { status: 'not_requested', snapshot: null };
+    let proposedAtMs = recordedAtMs;
+    try {
+      if (auditStatus === 'success' && proposals.resolvedToolIds.length > 0) {
+        proposedAtMs = now();
+        observerContext = await loadEvaluationObserverContextFn({
+          projectRoot,
+          host: 'codex',
+          sessionId,
+          config,
+          recordedAtMs: proposedAtMs,
+        });
+      }
+      const store = createEvaluationStoreFn();
+      try {
+        store.recordTurn({
+          observationId,
+          recordedAtMs: proposals.resolvedToolIds.length > 0 ? proposedAtMs : recordedAtMs,
+          proposedAtMs,
+          projectPath: projectRoot,
+          host: 'codex',
+          sessionId,
+          auditStatus,
+          requestText: prompt,
+          auditorSeenContext,
+          observerContextStatus: observerContext.status,
+          observerSnapshot: observerContext.snapshot,
+          proposedToolIds: proposals.resolvedToolIds,
+          backend,
+          model,
+          spotterVersion: SPOTTER_VERSION,
+        });
+      } finally {
+        store.close();
+      }
+    } catch {
+      reportEvaluationFailure(writeError);
+    }
+  };
   const legacyPending = await discardLegacyPendingFn({ projectRoot, sessionId: codexSessionId(input) });
   let context;
   const contextStartedAt = Date.now();
   try {
     const config = await readAuditorContextConfigFn(projectRoot);
+    auditorContextConfig = config;
     contextDurationMs = Date.now() - contextStartedAt;
     if (config.mode === 'disabled') {
+      await recordEvaluation({ auditStatus: 'skipped' });
       await recordCodexHookEventSafe(recordHookEventFn, {
         projectRoot,
         event: {
@@ -164,6 +229,7 @@ export async function runCodexUserPromptSubmitHook({
     });
     contextDurationMs = Date.now() - contextStartedAt;
   } catch (err) {
+    await recordEvaluation({ auditStatus: 'error' });
     await observeRuntimeFailure(runtimeErrorObserver, 'auditor_unavailable');
     contextDurationMs = Date.now() - contextStartedAt;
     const failure = projectBackendFailure(err?.code);
@@ -184,6 +250,7 @@ export async function runCodexUserPromptSubmitHook({
     return;
   }
   if (context.status === 'unavailable' || context.status === 'schema_mismatch') {
+    await recordEvaluation({ auditStatus: 'error' });
     await observeRuntimeFailure(runtimeErrorObserver, 'auditor_unavailable');
     const failure = projectBackendFailure(context.status === 'unavailable'
       ? 'E_AUDITOR_CONTEXT_UNAVAILABLE'
@@ -205,6 +272,7 @@ export async function runCodexUserPromptSubmitHook({
     return;
   }
   if (context.status !== 'fresh') {
+    await recordEvaluation({ auditStatus: 'skipped' });
     await recordCodexHookEventSafe(recordHookEventFn, {
       projectRoot,
       event: {
@@ -237,6 +305,7 @@ export async function runCodexUserPromptSubmitHook({
       contextStatus: 'fresh',
     });
   } catch (err) {
+    await recordEvaluation({ auditStatus: 'error', backend: err?.backend ?? null, model: err?.diagnostics?.modelSelection?.effectiveModel ?? null });
     if (enteredAuditorBoundary) await observeRuntimeFailure(runtimeErrorObserver, 'auditor_unavailable');
     const failure = projectBackendFailure(err?.code);
     safeWriteError(writeError, failure.stderr);
@@ -274,10 +343,23 @@ export async function runCodexUserPromptSubmitHook({
     },
   }, writeError);
   if (judgment.pass === true) {
+    await recordEvaluation({
+      auditStatus: 'success',
+      backend: judgment.meta?.backend ?? backend.name ?? 'unknown',
+      model: judgment.meta?.modelSelection?.effectiveModel ?? null,
+    });
     return;
   }
 
   const toolIds = projectToolIds(judgment.findings.map((finding) => finding.toolName));
+  await recordEvaluation({
+    auditStatus: 'success',
+    proposedToolIds: toolIds,
+    backend: judgment.meta?.backend ?? backend.name ?? 'unknown',
+    model: judgment.meta?.modelSelection?.effectiveModel ?? null,
+    auditorSeenContext: JSON.stringify(context.turns),
+    config: auditorContextConfig,
+  });
   const advice = projectParentAdvice(toolIds);
   if (advice) writeCodexUserPromptContexts({ contexts: [advice], writeOutput });
 }
@@ -291,20 +373,35 @@ export async function runCodexStopHook({
   writeOutput = (text) => process.stdout.write(text),
   writeError = (text) => process.stderr.write(text),
   runtimeErrorObserver = async () => ({ collected: false, reason: 'observer_not_configured' }),
+  createEvaluationStoreFn = createEvaluationStore,
+  codexHome = process.env.CODEX_HOME || join(homedir(), '.codex'),
+  now = () => Date.now(),
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
-  if (input.stop_hook_active === true) return;
   const projectRoot = findSpotterMarker(input.cwd);
   if (!projectRoot) return;
   const startedAt = Date.now();
   const reportError = (text) => safeWriteError(writeError, text);
+  if (input.stop_hook_active === true) {
+    await closeCodexEvaluationTurn({
+      createEvaluationStoreFn,
+      sessionId: codexSessionId(input),
+      usageStatus: 'incomplete',
+      completedAtMs: now(),
+      writeError: reportError,
+    });
+    return;
+  }
   const transcriptPath = requireString(input, 'transcript_path');
   const finalResponse = codexLastAssistantMessage(input) ?? '(no final response available)';
   let toolUsage;
   try {
     toolUsage = await readCodexToolUsageFn(transcriptPath);
   } catch (err) {
+    await closeCodexEvaluationTurn({
+      createEvaluationStoreFn, sessionId: codexSessionId(input), usageStatus: 'incomplete', completedAtMs: now(), writeError: reportError,
+    });
     const failure = projectBackendFailure(err?.code);
     reportError(failure.stderr);
     writeCodexSystemMessage({ systemMessage: failure.systemMessage, writeOutput });
@@ -322,6 +419,15 @@ export async function runCodexStopHook({
     return;
   }
   const usedTools = Array.isArray(toolUsage?.usedTools) ? toolUsage.usedTools : [];
+  await closeCodexEvaluationTurn({
+    createEvaluationStoreFn,
+    sessionId: codexSessionId(input),
+    toolUsage,
+    projectRoot,
+    codexHome,
+    completedAtMs: now(),
+    writeError: reportError,
+  });
   const toolUsageEvent = compactCodexToolUsageForEvent(toolUsage);
   if (toolUsageEvent.toolUsageAnomalyCount === 0
     && shouldSkipShortCodexStop({ finalResponse, usedTools, env: process.env })) {
@@ -777,6 +883,79 @@ function safeWriteError(writeError, text) {
   }
 }
 
+function reportEvaluationFailure(writeError) {
+  safeWriteError(writeError, 'Spotter の評価記録に失敗しました。\n');
+}
+
+function isCompleteCodexUsage(toolUsage, canonicalUsage) {
+  if (!toolUsage || !Array.isArray(toolUsage.usedTools) || !Array.isArray(toolUsage.toolCalls)) return false;
+  if (toolUsage.scope !== 'current-turn') return false;
+  if (Array.isArray(toolUsage.anomalies) && toolUsage.anomalies.length > 0) return false;
+  return canonicalUsage.missingCount === 0;
+}
+
+function isCodexEvaluationUsage(toolName) {
+  return typeof toolName === 'string' && (
+    /^mcp__[A-Za-z0-9_-]+__/u.test(toolName)
+    || toolName === 'Skill'
+    || toolName === 'skill'
+    || /^(?:skills?|Skill)(?:__|\.)/u.test(toolName)
+  );
+}
+
+async function closeCodexEvaluationTurn({
+  createEvaluationStoreFn,
+  sessionId,
+  usedToolIds = [],
+  usageStatus,
+  toolUsage = null,
+  projectRoot = null,
+  codexHome = process.env.CODEX_HOME || join(homedir(), '.codex'),
+  completedAtMs,
+  writeError,
+}) {
+  if (!sessionId) {
+    reportEvaluationFailure(writeError);
+    return;
+  }
+  try {
+    const store = createEvaluationStoreFn();
+    try {
+      const row = store.database.prepare(`
+        SELECT observation_id FROM evaluation_turns
+        WHERE session_id = ? AND completed_at_ms IS NULL
+        ORDER BY recorded_at_ms DESC LIMIT 1
+      `).get(sessionId);
+      if (!row) return;
+      if (toolUsage) {
+        const proposals = store.database.prepare(`
+          SELECT tool_id FROM evaluation_items WHERE observation_id = ? ORDER BY tool_id
+        `).all(row.observation_id).map((item) => item.tool_id);
+        const allUsages = toolUsage.toolCalls ?? toolUsage.usedTools.map((toolName) => ({ toolName }));
+        const evaluationUsages = allUsages.filter((usage) => isCodexEvaluationUsage(usage?.toolName));
+        const canonicalUsage = canonicalizeUsedToolIds(evaluationUsages, { host: 'codex' });
+        const skillReads = await canonicalizeCodexSkillReadToolIds(allUsages, {
+          proposedToolIds: proposals,
+          projectRoot,
+          codexHome,
+        });
+        const nestedMcpCalls = canonicalizeCodexNestedMcpToolIds(allUsages);
+        usedToolIds = [...new Set([
+          ...canonicalUsage.resolvedToolIds,
+          ...nestedMcpCalls,
+          ...skillReads,
+        ])];
+        usageStatus = isCompleteCodexUsage(toolUsage, canonicalUsage) ? 'complete' : 'incomplete';
+      }
+      store.closeTurn({ observationId: row.observation_id, usedToolIds, usageStatus, completedAtMs });
+    } finally {
+      store.close();
+    }
+  } catch {
+    reportEvaluationFailure(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.

package/src/cli/diagnostics-cmd.mjs

@@ -59,7 +59,7 @@ export async function runDiagnosticsLogsCommand({
   writeOutput(formatDaemonLogSummary(merged));
 }
 
-function stringifyAsciiJson(value) {
+export function stringifyAsciiJson(value) {
   return JSON.stringify(value, null, 2).replace(/[\u007f-\uffff]/g, (character) =>
     `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`
   );