claude-spotter 1.4.19 → 1.4.21

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.4.21 — 2026-07-13
+
+### Changed
+
+- **Throughline監査文脈をdefault-onへ変更。** `spotter install`がPATH上のThroughlineをabsolute pathへ解決できる場合、project markerへ既定設定する。marker v2の`origin:default|explicit`で旧既定disabledだけを移行し、明示OFFは再install後も維持する。POSIXはrealpath、Windows npm shimはabsolute `node.exe + throughline.mjs`を保存する。
+- **不在時は明示disabled。** Throughlineが見つからない場合は固定理由付きdisabledとし、current-only監査や別backendへfallbackしない。installerとdoctorが状態・OFF手順を表示する。
+- **実運用効果測定。** default-onで7日以上・fresh 30件以上を集め、過検出・見逃し・stale率・latencyから維持、修正、default-off rollbackを判断する。L2本文は評価ログへ保存しない。
+
+## 1.4.20 — 2026-07-13
+
+### Added
+
+- **Throughline監査文脈のopt-in配布。** 新規projectは既定`disabled`のまま、ownerがabsoluteなThroughline commandとrepeatableな先頭引数で有効化できる。freshな完了L2 user/assistant pairだけを`N=2`、body 600文字、total 4,000文字に制限し、Codex CLIへstdinで渡す。Haikuはこのcontext経路では呼ばず、fresh以外でもAIを呼ばない。connector障害は固定警告に限定する。親出力は安全なcatalog tool ID由来の固定・非命令形助言だけで、L2、reason、provider rawを反射しない。7日・30 fresh resultのproduction default昇格gateは未完了のため、配布後もproject opt-inを維持する。
+
+### 検証・公開
+
+Spotter 476 tests（474 pass / 2 skip）、Throughline 580 tests（全pass）、両CIのmacOS/Linux/Windows ×
+Node matrix各6/6、packの秘密・開発者固有path scan、隔離tarball installを通過。公開commitは`7cbc3a1`、
+npm `claude-spotter@1.4.20`、tag / GitHub Release `v1.4.20`、registry由来global installを同期した。
+`spotter doctor`は0 warnings、監査文脈connectorはavailable。Codex hook trustだけは仕様上機械検証不能のため、
+`/hooks`での人手確認を残す。
+
 ## 1.4.19
 
 親セッションの暴走を誘発できたHook出力の信頼境界を修正する。監査用AIは内部で構造化判定を返すだけとし、
@@ -29,8 +51,10 @@ AI/backend/provider sentinel、unsafe ID、legacy pending非読取unlink、Stop
 読込例外の固定degradationを確認した。敵対的再監査は初回BLOCKER 2件（Codex読込例外の境界外、
 UI可視性の過剰主張）を検出・修正し、再監査BLOCKER 0。`npm pack --dry-run`は62 files、global
 `spotter 1.4.19`へlocal installし、projector smoke・Hook diagnostics・global UserPromptSubmit smokeを
-確認した。公開前release gateとしてfull test、pack、秘密混入、CI、registry tarballを再検証し、
-`v1.4.19` tag・npm `latest`・GitHub Release・global installを同一versionへ揃える。
+確認した。公開前release gateでfull test、pack、秘密混入を再検証し、公開SHA`5393919`のCIは
+macOS/Linux/Windows × Node 22.5/22.xの6/6 green。`v1.4.19` tag、npm `latest`、
+[GitHub Release](https://github.com/kitepon-rgb/Spotter/releases/tag/v1.4.19)、registry由来global installを
+1.4.19へ揃え、global projector smokeとHook diagnosticsもgreen。
 
 ## 1.4.18
 

package/README.ja.md

@@ -146,6 +146,52 @@ flowchart LR
 
 両者に共通するのは **「主体に頼らない仕組み」**。併用できます。
 
+### Throughline auditor context（既定ON）
+
+`spotter install`はPATH上のThroughlineを絶対パスへ解決できる場合、auditor contextを既定で有効化します。
+旧版の既定`disabled` markerも通常の再installで有効化されます。過去に明示的に無効化したprojectは
+`origin: explicit`として保持され、勝手に再有効化されません。無効化するには次を実行します。
+
+```bash
+spotter install -y --auditor-context disabled
+```
+
+自動解決できない環境で手動設定する場合は、絶対パスのThroughline実行ファイルと、必要なら
+繰り返し指定できる`--throughline-arg`を設定します。
+
+```bash
+spotter install -y --auditor-context throughline \
+  --throughline-command /absolute/path/to/throughline
+```
+
+Windows では shell injection を避けるため `.cmd` / `.bat` wrapper を意図的に拒否します。絶対パスの
+`node.exe` を command にし、絶対パスの `throughline.mjs` を繰り返し引数として渡してください。
+
+```powershell
+spotter install -y --auditor-context throughline `
+  --throughline-command 'C:\Program Files\nodejs\node.exe' `
+  --throughline-arg 'C:\absolute\path\to\throughline\bin\throughline.mjs'
+```
+
+この connector の AI 呼出しは Codex CLI のみです。コンテキストを argv には載せず、AI へは stdin 経由で
+渡します。Haiku はこの context path に未対応であり、呼び出しません。Throughline 結果が `fresh` の時だけ
+AI 呼出し候補になり、それ以外の status では AI を呼びません。enabled connector の障害は hidden fallback
+ではなく固定 warning として出します。
+
+Throughline から渡すのは fresh な完了済み L2 user/assistant pair だけです。直近 2 pair (N=2)、各 body は
+600 文字、合計は 4,000 文字に制限します。Spotter は Throughline の L2、`reason`、`raw` を親へ反射せず、
+親には安全な catalog tool ID から作る固定・非命令形の助言だけを渡します。`spotter doctor` は command / args
+を表示せず、auditor-context mode と固定の availability detail だけを表示します。
+
+v2 model-matrix では context choice を明示できます。
+
+```bash
+spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.json \
+  --recent-turns 2 --body-cap 600
+```
+
+評価結論はN=2 / 600です。既定ONの実運用で7日・30 fresh resultを集め、維持・修正・rollbackを判断します。
+
 ## よく使うコマンド
 
 ```bash
@@ -172,7 +218,7 @@ spotter codex-hook install
                          # Codex native hooks の修復 / 明示登録 (通常は spotter install が実行)
 spotter codex-hook diagnostics
                          # Codex hook の登録/readiness を診断。trust は /hooks で review
-spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v1.json
+spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.json --recent-turns 2 --body-cap 600
                          # pinned auditor model profile を再現可能に比較する experimental eval
 spotter uninstall        # hook 登録を解除 (~/.spotter は残す)
 ```

package/README.md

@@ -146,6 +146,58 @@ The audited catalog is host-local: Claude uses `<project>/.spotter/tool-db.json`
 
 Both share the principle of **"don't rely on the primary agent to do it itself."** They compose well — you can run them together.
 
+### Throughline auditor context (default-on)
+
+When `spotter install` can resolve Throughline on PATH to an absolute executable,
+auditor context is enabled by default. A normal reinstall migrates legacy markers
+whose disabled state came from the old default. An explicit project opt-out is
+stored with `origin: explicit` and is never silently re-enabled. Disable it with:
+
+```bash
+spotter install -y --auditor-context disabled
+```
+
+When automatic discovery is unavailable, configure a direct absolute Throughline
+executable and any leading arguments with repeatable `--throughline-arg`:
+
+```bash
+spotter install -y --auditor-context throughline \
+  --throughline-command /absolute/path/to/throughline
+```
+
+On Windows, `.cmd` and `.bat` wrappers are deliberately rejected to avoid shell
+injection. Point at an absolute `node.exe` and pass the absolute
+`throughline.mjs` path as a repeated argument instead:
+
+```powershell
+spotter install -y --auditor-context throughline `
+  --throughline-command 'C:\Program Files\nodejs\node.exe' `
+  --throughline-arg 'C:\absolute\path\to\throughline\bin\throughline.mjs'
+```
+
+The connector is Codex CLI-only. It sends no context in argv: the bounded
+projection is supplied to that AI over stdin. Haiku does not support this
+context path and is never called for it. Only a `fresh` Throughline result is
+eligible for an AI call; every other status skips AI. An enabled connector
+failure becomes a fixed warning, not a hidden fallback.
+
+Throughline contributes only fresh, completed L2 user/assistant pairs: two
+recent pairs (N=2), each body capped at 600 characters and 4,000 characters in
+total. Spotter never reflects Throughline L2, `reason`, or `raw` to the parent.
+The parent receives only fixed non-imperative advice built from safe catalog tool
+IDs. `spotter doctor` displays the auditor-context mode and a fixed availability
+detail without printing its command or arguments.
+
+The v2 model-matrix can make the context choice explicit:
+
+```bash
+spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.json \
+  --recent-turns 2 --body-cap 600
+```
+
+The evaluated setting is N=2 / 600. Default-on operation now collects the 7-day,
+30-fresh-result sample used to decide whether to keep, adjust, or roll back the default.
+
 ## Common commands
 
 ```bash
@@ -173,7 +225,7 @@ spotter codex-hook install
                          # repair / explicitly register Codex native hooks (normally handled by spotter install)
 spotter codex-hook diagnostics
                          # check Codex hook registration/readiness; trust is reviewed with /hooks
-spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v1.json
+spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.json --recent-turns 2 --body-cap 600
                          # experimental reproducible comparison of pinned auditor model profiles
 spotter uninstall        # remove hooks from this project (leaves ~/.spotter intact)
 ```

package/bin/spotter.mjs

@@ -21,8 +21,12 @@ import { runSessionEnd } from '../src/hooks/session-end.mjs';
 const USAGE = `spotter — Claude Code tool-call auditor
 
 Usage:
-  spotter install [-y]                  register hooks in <cwd>/.claude/settings.json
+  spotter install [-y] [--auditor-context disabled|throughline]
+                                        [--throughline-command ABS] [--throughline-arg VALUE]
+                                        register hooks in <cwd>/.claude/settings.json
                                         and create <cwd>/.spotter/marker.json
+                                        (Throughline on PATH enables context by default;
+                                         pass disabled for a persistent project opt-out)
                                         (run inside each project you want audited)
   spotter install --user [-y]           legacy: register globally in ~/.claude/settings.json
                                         (NOT RECOMMENDED — fires for every Claude Code session
@@ -75,9 +79,8 @@ async function main() {
   const [cmd, ...rest] = argv;
   switch (cmd) {
     case 'install': {
-      const target = rest.includes('--user') ? 'user' : 'project';
-      const autoYes = rest.includes('-y') || rest.includes('--yes');
-      await runInstall({ target, autoYes });
+      const options = parseInstallArgs(rest);
+      await runInstall(options);
       return;
     }
     case 'uninstall': {
@@ -140,6 +143,60 @@ async function main() {
   }
 }
 
+function parseInstallArgs(argv) {
+  let target = 'project';
+  let autoYes = false;
+  let mode = null;
+  let command = null;
+  const args = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--user') {
+      if (target === 'user') throw invalidInstallArgs();
+      target = 'user';
+    } else if (arg === '-y' || arg === '--yes') {
+      if (autoYes) throw invalidInstallArgs();
+      autoYes = true;
+    } else if (arg === '--auditor-context') {
+      if (mode !== null) throw invalidInstallArgs();
+      mode = argv[++index];
+      if (mode !== 'disabled' && mode !== 'throughline') throw invalidInstallArgs();
+    } else if (arg === '--throughline-command') {
+      if (command !== null) throw invalidInstallArgs();
+      command = argv[++index];
+      if (typeof command !== 'string' || command.length === 0) throw invalidInstallArgs();
+    } else if (arg === '--throughline-arg') {
+      const value = argv[++index];
+      if (typeof value !== 'string' || value.length === 0) throw invalidInstallArgs();
+      args.push(value);
+    } else {
+      throw invalidInstallArgs();
+    }
+  }
+  if (mode === null && (command !== null || args.length > 0)) throw invalidInstallArgs();
+  if (mode === 'disabled' && (command !== null || args.length > 0)) throw invalidInstallArgs();
+  if (mode === 'throughline' && (command === null || !isAbsoluteCommand(command) || isShellWrapper(command))) throw invalidInstallArgs();
+  const auditorContext = mode === null ? undefined : mode === 'disabled'
+    ? { mode: 'disabled', origin: 'explicit' }
+    : { mode: 'throughline', command, args, origin: 'explicit' };
+  return { target, autoYes, auditorContext };
+}
+
+function isAbsoluteCommand(value) {
+  return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value);
+}
+
+function isShellWrapper(value) {
+  return /\.(?:cmd|bat)$/i.test(value);
+}
+
+function invalidInstallArgs() {
+  const err = new Error('invalid install arguments');
+  err.stack = '';
+  err.exitCode = 2;
+  return err;
+}
+
 main().catch((err) => {
   process.stderr.write(`spotter: ${err.stack || err.message || err}\n`);
   process.exit(err.exitCode ?? 2);

package/package.json

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

package/src/cli/auditor-cmd.mjs

@@ -37,7 +37,7 @@ export async function runAuditorCommand({ argv = process.argv.slice(2) } = {}) {
   }
   if (sub === 'model-matrix') {
     if (argv.slice(1).includes('--help') || argv.slice(1).includes('-h')) {
-      process.stdout.write(`Usage: spotter auditor model-matrix --fixtures FILE [--profile baseline|luna|terra|terra-medium]...\n       [--repeat N] [--project DIR] [--output FILE]\n`);
+      process.stdout.write(`Usage: spotter auditor model-matrix --fixtures FILE [--profile baseline|luna|terra|terra-medium]...\n       [--repeat N] [--recent-turns 0|1|2|3] [--body-cap CHARS] [--project DIR] [--output FILE]\n`);
       return;
     }
     await runAuditorModelMatrixCommand({ argv: argv.slice(1) });

package/src/cli/auditor-model-matrix-cmd.mjs

@@ -4,7 +4,7 @@ import { promisify } from 'node:util';
 import { readFile, writeFile } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { version } from '../version.mjs';
-import { createCodexCliAuditorBackend } from '../core/codex-cli-backend.mjs';
+import { CODEX_AUDITOR_PROMPT_VERSION, createCodexCliAuditorBackend } from '../core/codex-cli-backend.mjs';
 import { CODEX_AUDITOR_MODEL_POLICY, resolveCodexAuditorModelSelection } from '../core/codex-auditor-model-policy.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -21,6 +21,7 @@ export async function runAuditorModelMatrixCommand({
   const raw = await readFileFn(opts.fixturesPath);
   const fixtureBytes = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
   const fixture = parseAndValidateFixture(fixtureBytes.toString('utf8'));
+  const contextOptions = resolveContextOptions(opts, fixture.schema);
   if (fixture.cases.length * opts.repeat * opts.profiles.length > MAX_MODEL_MATRIX_RUNS) {
     throw new Error(`model-matrix run count exceeds maximum ${MAX_MODEL_MATRIX_RUNS}`);
   }
@@ -40,7 +41,7 @@ export async function runAuditorModelMatrixCommand({
     const modelSelection = selections[profile];
     try {
       const backend = backends[profile];
-      const judgment = await backend.judge({ ...toAuditorInput(item), meta: { caseId: item.id, repeat, profile } });
+      const judgment = await backend.judge({ ...toAuditorInput(item, contextOptions), meta: { caseId: item.id, repeat, profile } });
       if (!sameSelection(modelSelection, judgment?.meta?.modelSelection)) {
         throw new Error('judgment model selection does not match backend model selection');
       }
@@ -87,6 +88,7 @@ export async function runAuditorModelMatrixCommand({
     schema: 'spotter.auditor_model_matrix.v1', generatedAt: generatedAt(), packageVersion: version,
     fixture: { schema: fixture.schema, path: safeFixturePath(opts.fixturesPath, opts.projectRoot), sha256: createHash('sha256').update(fixtureBytes).digest('hex'), cases: fixture.cases.length, catalogCount: fixture.catalog.length },
     codexCli: cliVersion, policy: { schema: CODEX_AUDITOR_MODEL_POLICY.schema, version: CODEX_AUDITOR_MODEL_POLICY.policyVersion },
+    auditorPromptVersion: CODEX_AUDITOR_PROMPT_VERSION,
     profiles: Object.fromEntries(Object.entries(selections).map(([profile, selection]) => [profile, {
       model: selection.effectiveModel,
       reasoningEffort: selection.effectiveReasoningEffort,
@@ -96,7 +98,7 @@ export async function runAuditorModelMatrixCommand({
       selection,
     }])), runs, summary: summarize(runs, opts.profiles), usageStatus: usage.status, tokenUsage: usage.summary,
     costStatus: 'not-available-chatgpt-plan', cost: null,
-    evaluation: { repeat: opts.repeat, profiles: opts.profiles, maxRuns: MAX_MODEL_MATRIX_RUNS },
+    evaluation: { repeat: opts.repeat, profiles: opts.profiles, maxRuns: MAX_MODEL_MATRIX_RUNS, recentTurns: contextOptions.recentTurns, bodyCap: contextOptions.bodyCap },
     executionOrdering: 'case-repeat-profile', promotionEligible: false, blockingReasons: blockingReasons(runs, usage.status),
   };
   const json = JSON.stringify(artifact, null, 2) + '\n';
@@ -106,7 +108,7 @@ export async function runAuditorModelMatrixCommand({
 }
 
 function parseArgs(argv) {
-  const opts = { fixturesPath: null, profiles: [], repeat: 1, projectRoot: process.cwd(), outputPath: null };
+  const opts = { fixturesPath: null, profiles: [], repeat: 1, projectRoot: process.cwd(), outputPath: null, recentTurns: null, bodyCap: null };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i]; const value = () => { const v = argv[++i]; if (!v || v.startsWith('--')) throw new Error(`${arg} requires a value`); return v; };
     if (arg === '--fixtures') opts.fixturesPath = resolve(value());
@@ -114,10 +116,14 @@ function parseArgs(argv) {
     else if (arg === '--repeat') opts.repeat = Number(value());
     else if (arg === '--project') opts.projectRoot = resolve(value());
     else if (arg === '--output') opts.outputPath = resolve(value());
+    else if (arg === '--recent-turns') opts.recentTurns = Number(value());
+    else if (arg === '--body-cap') opts.bodyCap = Number(value());
     else throw new Error(`unknown auditor model-matrix option: ${arg}`);
   }
   if (!opts.fixturesPath) throw new Error('--fixtures FILE is required');
   if (!Number.isInteger(opts.repeat) || opts.repeat < 1) throw new Error('--repeat must be a positive integer');
+  if (opts.recentTurns !== null && (!Number.isInteger(opts.recentTurns) || opts.recentTurns < 0 || opts.recentTurns > 3)) throw new Error('--recent-turns must be 0, 1, 2, or 3');
+  if (opts.bodyCap !== null && (!Number.isInteger(opts.bodyCap) || opts.bodyCap <= 0)) throw new Error('--body-cap must be a positive integer');
   opts.profiles = opts.profiles.length ? opts.profiles : [...DEFAULT_PROFILES];
   if (new Set(opts.profiles).size !== opts.profiles.length || opts.profiles.some((profile) => !ALLOWED_PROFILES.includes(profile))) throw new Error('--profile must be baseline, luna, terra, or terra-medium without duplicates');
   return opts;
@@ -126,7 +132,7 @@ function parseArgs(argv) {
 function parseAndValidateFixture(raw) {
   let fixture; try { fixture = JSON.parse(raw); } catch { throw new Error('fixture must be valid JSON'); }
   objectOnly(fixture, ['schema', 'catalog', 'cases'], 'fixture');
-  if (fixture.schema !== 'spotter.auditor_model_fixtures.v1') throw new Error('unsupported fixture schema');
+  if (!['spotter.auditor_model_fixtures.v1', 'spotter.auditor_model_fixtures.v2'].includes(fixture.schema)) throw new Error('unsupported fixture schema');
   if (!Array.isArray(fixture.catalog) || !Array.isArray(fixture.cases) || fixture.cases.length === 0) throw new Error('fixture catalog and non-empty cases are required');
   const catalogNames = new Set();
   for (const tool of fixture.catalog) { objectOnly(tool, ['name', 'description'], 'catalog tool'); clean(tool.name, 'catalog name'); clean(tool.description, 'catalog description'); if (catalogNames.has(tool.name)) throw new Error('duplicate catalog name'); catalogNames.add(tool.name); }
@@ -135,7 +141,7 @@ function parseAndValidateFixture(raw) {
     objectOnly(item, ['id', 'stage', 'input', 'expected'], 'case'); clean(item.id, 'case id');
     if (ids.has(item.id)) throw new Error('duplicate case id'); ids.add(item.id);
     if (!['user_input', 'turn_end'].includes(item.stage)) throw new Error('case stage is invalid');
-    validateInput(item.stage, item.input); objectOnly(item.expected, ['pass', 'missingTools'], 'case expected');
+    validateInput(fixture.schema, item.stage, item.input); objectOnly(item.expected, ['pass', 'missingTools'], 'case expected');
     if (typeof item.expected.pass !== 'boolean' || !Array.isArray(item.expected.missingTools)
       || new Set(item.expected.missingTools).size !== item.expected.missingTools.length
       || item.expected.missingTools.some((name) => typeof name !== 'string' || !catalogNames.has(name))
@@ -145,8 +151,9 @@ function parseAndValidateFixture(raw) {
 }
 function objectOnly(value, keys, label) { if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some((key) => !keys.includes(key))) throw new Error(`${label} has invalid fields`); }
 function clean(value, label) { if (typeof value !== 'string' || value.length === 0 || value.trim() !== value) throw new Error(`${label} must be a clean non-empty string`); }
-function validateInput(stage, input) { if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('case input is invalid'); if (stage === 'user_input') { objectOnly(input, ['userInput'], 'user_input input'); clean(input.userInput, 'userInput'); } else { objectOnly(input, ['finalResponse', 'usedTools'], 'turn_end input'); clean(input.finalResponse, 'finalResponse'); if (!Array.isArray(input.usedTools) || input.usedTools.some((tool) => typeof tool !== 'string' || tool.length === 0 || tool.trim() !== tool) || new Set(input.usedTools).size !== input.usedTools.length) throw new Error('usedTools is invalid'); } }
-function toAuditorInput(item) { return item.stage === 'user_input' ? { stage: item.stage, userInput: item.input.userInput } : { stage: item.stage, finalResponse: item.input.finalResponse, usedTools: item.input.usedTools }; }
+function validateInput(schema, stage, input) { if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('case input is invalid'); if (stage === 'user_input') { objectOnly(input, schema === 'spotter.auditor_model_fixtures.v2' ? ['userInput', 'recentContext'] : ['userInput'], 'user_input input'); clean(input.userInput, 'userInput'); if (schema === 'spotter.auditor_model_fixtures.v2') { if (!Array.isArray(input.recentContext) || input.recentContext.length < 1 || input.recentContext.length > 3) throw new Error('recentContext must contain one to three turns'); for (const turn of input.recentContext) { objectOnly(turn, ['user', 'assistant'], 'recentContext turn'); clean(turn.user, 'recentContext user'); clean(turn.assistant, 'recentContext assistant'); } } } else { objectOnly(input, ['finalResponse', 'usedTools'], 'turn_end input'); clean(input.finalResponse, 'finalResponse'); if (!Array.isArray(input.usedTools) || input.usedTools.some((tool) => typeof tool !== 'string' || tool.length === 0 || tool.trim() !== tool) || new Set(input.usedTools).size !== input.usedTools.length) throw new Error('usedTools is invalid'); } }
+function resolveContextOptions(opts, schema) { if (schema === 'spotter.auditor_model_fixtures.v1') { if (opts.recentTurns !== null || opts.bodyCap !== null) throw new Error('--recent-turns and --body-cap require a v2 fixture'); return { recentTurns: null, bodyCap: null }; } return { recentTurns: opts.recentTurns ?? 2, bodyCap: opts.bodyCap ?? 1200 }; }
+function toAuditorInput(item, contextOptions) { if (item.stage !== 'user_input') return { stage: item.stage, finalResponse: item.input.finalResponse, usedTools: item.input.usedTools }; const input = { stage: item.stage, userInput: item.input.userInput }; if (contextOptions.recentTurns > 0 && item.input.recentContext) input.recentContext = item.input.recentContext.slice(-contextOptions.recentTurns).map((turn) => ({ user: turn.user.slice(-contextOptions.bodyCap), assistant: turn.assistant.slice(-contextOptions.bodyCap) })); return input; }
 function isCleanString(value) { return typeof value === 'string' && value.length > 0 && value.trim() === value; }
 function cleanStrings(values = []) { return [...new Set(values.filter(isCleanString))]; }
 function successRun({ order, item, repeat, profile, modelSelection, durationMs, schemaSuccess, actualPass, actualTools, invalidFindingCount, droppedTools, droppedToolCount, anomalyTypes, anomalyCount, tokenUsage }) { const expectedTools = item.expected.missingTools; const fp = [...actualTools.filter((tool) => !expectedTools.includes(tool)), ...droppedTools.filter((tool) => !expectedTools.includes(tool))]; const fn = expectedTools.filter((tool) => !actualTools.includes(tool)); return { order, caseId: item.id, repeat, profile, status: 'success', durationMs, schemaSuccess, exactMatch: schemaSuccess && actualPass === item.expected.pass && actualTools.length === expectedTools.length && fp.length === 0 && fn.length === 0 && droppedToolCount === 0 && anomalyCount === 0, expected: item.expected, actual: { pass: actualPass, missingTools: actualTools, invalidFindingCount, droppedCatalogExternalNames: droppedTools, droppedCatalogExternalNameCount: droppedToolCount, anomalies: anomalyTypes, anomalyCount }, falsePositiveTools: fp, falseNegativeTools: fn, modelSelection, tokenUsage }; }

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

@@ -28,13 +28,16 @@ import {
   hookEventsPath,
   summarizeHookEvents,
 } from '../core/hook-event-log.mjs';
+import {
+  loadAuditorContext,
+  readProjectAuditorContextConfig,
+} from '../core/auditor-context.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
 const SPOTTER_BIN = join(PACKAGE_ROOT, 'bin', 'spotter.mjs');
 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_HOOK_FEATURE_NAMES = ['hooks', 'codex_hooks'];
 
@@ -114,6 +117,8 @@ export async function runCodexUserPromptSubmitHook({
   createAuditorBackendFn = createAuditorBackend,
   recordHookEventFn = appendCodexHookEvent,
   discardLegacyPendingFn = discardLegacyPending,
+  readAuditorContextConfigFn = readProjectAuditorContextConfig,
+  loadAuditorContextFn = loadAuditorContext,
   writeOutput = (text) => process.stdout.write(text),
   writeError = (text) => process.stderr.write(text),
 } = {}) {
@@ -122,16 +127,88 @@ export async function runCodexUserPromptSubmitHook({
   const projectRoot = findSpotterMarker(input.cwd);
   if (!projectRoot) return;
   const startedAt = Date.now();
+  let contextDurationMs = null;
 
   const prompt = requireString(input, 'prompt');
   const legacyPending = await discardLegacyPendingFn({ projectRoot, sessionId: codexSessionId(input) });
-  if ([...prompt.trim()].length <= SHORT_PROMPT_MAX_CHARS) {
+  let context;
+  const contextStartedAt = Date.now();
+  try {
+    const config = await readAuditorContextConfigFn(projectRoot);
+    contextDurationMs = Date.now() - contextStartedAt;
+    if (config.mode === 'disabled') {
+      await recordCodexHookEventSafe(recordHookEventFn, {
+        projectRoot,
+        event: {
+          hook: 'UserPromptSubmit',
+          status: 'skipped',
+          reason: 'context_disabled',
+          contextStatus: 'disabled',
+          contextDurationMs,
+          legacyPendingDiagnostic: legacyPending.diagnostic,
+          durationMs: Date.now() - startedAt,
+        },
+      }, writeError);
+      return;
+    }
+    context = await loadAuditorContextFn({
+      config,
+      host: 'codex',
+      sessionId: requireCodexSessionId(input),
+      projectRoot,
+      transcriptPath: requireString(input, 'transcript_path'),
+    });
+    contextDurationMs = Date.now() - contextStartedAt;
+  } catch (err) {
+    contextDurationMs = Date.now() - contextStartedAt;
+    const failure = projectBackendFailure(err?.code);
+    safeWriteError(writeError, failure.stderr);
+    await recordCodexHookEventSafe(recordHookEventFn, {
+      projectRoot,
+      event: {
+        hook: 'UserPromptSubmit',
+        status: 'error',
+        code: failure.code,
+        reason: 'auditor_context',
+        contextDurationMs,
+        legacyPendingDiagnostic: legacyPending.diagnostic,
+        durationMs: Date.now() - startedAt,
+      },
+    }, writeError);
+    writeCodexSystemMessage({ systemMessage: failure.systemMessage, writeOutput });
+    return;
+  }
+  if (context.status === 'unavailable' || context.status === 'schema_mismatch') {
+    const failure = projectBackendFailure(context.status === 'unavailable'
+      ? 'E_AUDITOR_CONTEXT_UNAVAILABLE'
+      : 'E_AUDITOR_CONTEXT_SCHEMA');
+    safeWriteError(writeError, failure.stderr);
+    await recordCodexHookEventSafe(recordHookEventFn, {
+      projectRoot,
+      event: {
+        hook: 'UserPromptSubmit',
+        status: 'error',
+        code: failure.code,
+        reason: 'auditor_context_status',
+        contextDurationMs,
+        legacyPendingDiagnostic: legacyPending.diagnostic,
+        durationMs: Date.now() - startedAt,
+      },
+    }, writeError);
+    writeCodexSystemMessage({ systemMessage: failure.systemMessage, writeOutput });
+    return;
+  }
+  if (context.status !== 'fresh') {
     await recordCodexHookEventSafe(recordHookEventFn, {
       projectRoot,
       event: {
         hook: 'UserPromptSubmit',
         status: 'skipped',
-        reason: 'short_prompt',
+        reason: 'context_not_fresh',
+        contextStatus: context.status,
+        contextTurns: 0,
+        contextChars: 0,
+        contextDurationMs,
         legacyPendingDiagnostic: legacyPending.diagnostic,
         durationMs: Date.now() - startedAt,
       },
@@ -145,7 +222,12 @@ export async function runCodexUserPromptSubmitHook({
   try {
     catalog = await readLocalFn({ projectRoot, hostAgent: 'codex' });
     backend = createCodexHookAuditorBackend({ catalog, projectRoot, createAuditorBackendFn });
-    judgment = await backend.judge({ stage: 'user_input', userInput: prompt });
+    judgment = await backend.judge({
+      stage: 'user_input',
+      userInput: prompt,
+      recentContext: context.turns,
+      contextStatus: 'fresh',
+    });
   } catch (err) {
     const failure = projectBackendFailure(err?.code);
     safeWriteError(writeError, failure.stderr);
@@ -172,6 +254,10 @@ export async function runCodexUserPromptSubmitHook({
       backend: judgment.meta?.backend ?? backend.name ?? 'unknown',
       pass: judgment.pass,
       missingTools: projectToolIds(judgment.findings.map((finding) => finding.toolName)),
+      contextStatus: 'fresh',
+      contextTurns: context.stats.returnedTurns,
+      contextChars: context.stats.chars,
+      contextDurationMs,
       ...compactCodexModelSelectionForEvent(judgment.meta?.modelSelection),
       legacyPendingDiagnostic: legacyPending.diagnostic,
       backendDurationMs: judgment.meta?.durationMs ?? null,
@@ -621,6 +707,14 @@ function codexSessionId(payload) {
   return typeof value === 'string' && value.length > 0 ? value : null;
 }
 
+function requireCodexSessionId(payload) {
+  const value = codexSessionId(payload);
+  if (value) return value;
+  const err = new Error('session_id is required');
+  err.code = 'E_AUDITOR_CONTEXT_INPUT';
+  throw err;
+}
+
 // v1.4.19: legacy pending migration is handled only by `discardLegacyPending` on
 // UserPromptSubmit. Stop findings are never persisted for a future parent prompt.
 

package/src/cli/doctor.mjs

@@ -2,7 +2,7 @@
 
 import { access, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { loadDb, globalDbPath, localDbPath } from '../tool-db/loader.mjs';
@@ -75,6 +75,10 @@ export async function runDoctor() {
     const sidecar = await codexSidecarAuditorReadiness(projectRoot);
     mark(sidecar.ok, `codex-sidecar auditor: ${sidecar.status}`, sidecar.detail);
     if (!sidecar.ok) warnings += 1;
+
+    const auditorContext = await inspectAuditorContextConfiguration({ projectRoot });
+    mark(auditorContext.ok, `auditor context: ${auditorContext.mode}`, auditorContext.detail);
+    if (!auditorContext.ok) warnings += 1;
   }
 
   // tool-db (host-specific global caches). Since v1.2.0 these are not part of
@@ -132,6 +136,50 @@ export async function inspectCodexHookConfiguration({ projectRoot = null, diagno
   };
 }
 
+export async function inspectAuditorContextConfiguration({
+  projectRoot,
+  readFileFn = readFile,
+  accessFn = access,
+} = {}) {
+  const disabled = { ok: true, mode: 'disabled', detail: 'disabled' };
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) return disabled;
+
+  let marker;
+  try {
+    marker = JSON.parse(await readFileFn(join(projectRoot, '.spotter', 'marker.json'), 'utf8'));
+  } catch {
+    return { ok: false, mode: 'unknown', detail: 'marker unreadable' };
+  }
+
+  const config = marker?.auditorContext;
+  if (config === undefined) return disabled;
+  if (config?.mode === 'disabled') {
+    if (config.origin === 'explicit') return { ok: true, mode: 'disabled', detail: 'explicit project opt-out' };
+    if (config.reason === 'throughline_unavailable') {
+      return { ok: true, mode: 'disabled', detail: 'default disabled: Throughline unavailable' };
+    }
+    return disabled;
+  }
+  if (config?.mode !== 'throughline') {
+    return { ok: false, mode: 'unknown', detail: 'invalid configuration' };
+  }
+  if (
+    typeof config.command !== 'string' ||
+    !isAbsolute(config.command) ||
+    /\.(?:cmd|bat)$/i.test(config.command) ||
+    !Array.isArray(config.args) ||
+    config.args.some((arg) => typeof arg !== 'string' || arg.length === 0)
+  ) {
+    return { ok: false, mode: 'throughline', detail: 'invalid configuration' };
+  }
+  try {
+    await accessFn(config.command);
+  } catch {
+    return { ok: false, mode: 'throughline', detail: 'command unavailable' };
+  }
+  return { ok: true, mode: 'throughline', detail: 'command available' };
+}
+
 function formatCodexAuditorModelSelection({ backend, selection }) {
   if (backend && backend !== 'codex-cli') return 'auditor-model=not-applicable';
   if (!selection || typeof selection !== 'object') return 'auditor-model=unknown';