claude-token-saver 3.44.0 → 3.55.0

package/src/codex-parser.js

@@ -0,0 +1,397 @@
+import { createReadStream, openSync, readSync, closeSync, fstatSync } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { join, resolve } from 'node:path';
+import { codexUserDir } from './agent.js';
+
+const count = (n) => Number.isSafeInteger(n) && n >= 0 ? n : 0;
+const emptyTotals = () => ({ input: 0, cacheRead: 0, cacheCreation: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 });
+
+function updateSnapshot(session, e) {
+  const p = e?.payload;
+  if (!p || typeof p !== 'object') return;
+  const activity = Date.parse(e.timestamp);
+  if (Number.isFinite(activity)) session.lastActivity = new Date(activity);
+  if (e.type === 'session_meta') {
+    session.sessionId = p.id || p.session_id || null;
+    session.projectDir = typeof p.cwd === 'string' ? p.cwd : '';
+    session.source = p.source ?? null;
+    session.isSubagent = typeof p.source === 'object' && p.source !== null && 'subagent' in p.source;
+    session.branch = typeof p.git?.branch === 'string' ? p.git.branch : null;
+    session.provider = typeof p.model_provider === 'string' ? p.model_provider : null;
+  }
+  if (e.type === 'turn_context') {
+    if (typeof p.model === 'string') session.model = p.model;
+    const effort = p.effort ?? p.reasoning_effort;
+    if (typeof effort === 'string') session.effort = effort;
+  }
+  if (e.type !== 'event_msg') return;
+  if (p.type === 'task_started') session.status = 'working';
+  if (p.type === 'task_complete') session.status = 'idle';
+  if (p.type === 'turn_aborted') session.status = 'interrupted';
+  if (p.type !== 'token_count') return;
+  if (p.rate_limits && typeof p.rate_limits === 'object') {
+    session.rateLimits = p.rate_limits;
+    session.rateLimitsAt = Number.isFinite(activity) ? new Date(activity) : null;
+  }
+  if (Number.isSafeInteger(p.info?.last_token_usage?.input_tokens) && p.info.last_token_usage.input_tokens >= 0) {
+    session.lastContextTokens = p.info.last_token_usage.input_tokens;
+    session.contextAt = Number.isFinite(activity) ? new Date(activity) : null;
+  }
+  if (count(p.info?.model_context_window)) session.contextWindow = p.info.model_context_window;
+}
+
+/** The last `tailBytes` of a rollout as whole lines; a cut first line is dropped. */
+export function readCodexTailLines(filePath, tailBytes = 256 * 1024) {
+  if (!filePath) return null;
+  let fd;
+  try {
+    fd = openSync(filePath, 'r');
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - tailBytes);
+    const buffer = Buffer.alloc(size - start);
+    const length = readSync(fd, buffer, 0, buffer.length, start);
+    const lines = buffer.subarray(0, length).toString('utf8').split('\n');
+    if (start) lines.shift();
+    return lines;
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** Prompt hooks only need the newest measurements, never a full usage scan. */
+export function readCodexSnapshot(filePath, { tailBytes = 256 * 1024 } = {}) {
+  const lines = readCodexTailLines(filePath, tailBytes);
+  if (!lines) return null;
+  const snapshot = {};
+  for (const line of lines) {
+    try { updateSnapshot(snapshot, JSON.parse(line)); } catch { /* Partial or malformed record. */ }
+  }
+  return snapshot;
+}
+
+const textOf = (content) => (Array.isArray(content) ? content : [])
+  .filter((c) => c && typeof c.text === 'string').map((c) => c.text).join('\n');
+// Legacy outputs carry the exit status only as text inside the tool result.
+const exitFromText = (text) => {
+  const m = /(?:^|\n)(?:Process exited with code|Exit code:)\s*(-?\d+)/.exec(String(text ?? ''));
+  return m ? Number(m[1]) : null;
+};
+const fileCwd = (value) => typeof value === 'string' ? value.replace(/^file:\/\//, '') : null;
+
+/**
+ * Tool events of one rollout record, in a shape both formats share.
+ * Current rollouts carry structured `item_completed` items; older ones carry
+ * `exec_command_end`/`patch_apply_end`, and the oldest only a text exit line.
+ */
+export function codexToolEvents(e) {
+  const p = e?.payload;
+  if (!p || typeof p !== 'object') return [];
+  const at = Date.parse(e.timestamp);
+  if (e.type === 'event_msg' && p.type === 'item_completed' && p.item && typeof p.item === 'object') {
+    const it = p.item;
+    const base = { turnId: p.turn_id || null, threadId: p.thread_id || null, callId: it.id || null, at };
+    if (it.type === 'UserMessage') return [{ kind: 'user', ...base, text: textOf(it.content) }];
+    if (it.type === 'CommandExecution') return [{ kind: 'command', ...base,
+      argv: Array.isArray(it.command) ? it.command.map(String) : [String(it.command ?? '')],
+      parsed: Array.isArray(it.parsed_cmd) ? it.parsed_cmd : [],
+      exit: Number.isInteger(it.exit_code) ? it.exit_code : null,
+      failed: it.status === 'failed' || (Number.isInteger(it.exit_code) && it.exit_code !== 0),
+      output: String(it.aggregated_output ?? it.formatted_output ?? it.stdout ?? ''),
+      cwd: fileCwd(it.cwd) }];
+    if (it.type === 'FileChange') return [{ kind: 'patch', ...base, failed: it.status === 'failed',
+      output: String(it.stderr || it.stdout || '') }];
+    if (it.type === 'McpToolCall') return [{ kind: 'mcp', ...base, failed: it.status === 'failed' }];
+    return [];
+  }
+  if (e.type === 'event_msg' && p.type === 'exec_command_end') {
+    return [{ kind: 'command', turnId: p.turn_id || null, threadId: null, callId: p.call_id || null, at,
+      argv: Array.isArray(p.command) ? p.command.map(String) : [String(p.command ?? '')],
+      parsed: Array.isArray(p.parsed_cmd) ? p.parsed_cmd : [],
+      exit: Number.isInteger(p.exit_code) ? p.exit_code : null,
+      failed: p.status === 'failed' || (Number.isInteger(p.exit_code) && p.exit_code !== 0),
+      output: String(p.aggregated_output ?? p.formatted_output ?? p.stdout ?? ''), cwd: fileCwd(p.cwd) }];
+  }
+  if (e.type === 'event_msg' && p.type === 'patch_apply_end') {
+    return [{ kind: 'patch', turnId: p.turn_id || null, threadId: null, callId: p.call_id || null, at,
+      failed: p.success === false || p.status === 'failed', output: String(p.stderr || p.stdout || '') }];
+  }
+  if (e.type === 'event_msg' && p.type === 'user_message' && typeof p.message === 'string') {
+    return [{ kind: 'user', turnId: p.turn_id || null, threadId: null, callId: null, at, text: p.message, legacy: true }];
+  }
+  if (e.type === 'response_item' && (p.type === 'function_call' || p.type === 'custom_tool_call')) {
+    return [{ kind: 'call', name: String(p.name ?? ''), callId: p.call_id || null, at,
+      input: typeof p.arguments === 'string' ? p.arguments : typeof p.input === 'string' ? p.input : '' }];
+  }
+  if (e.type === 'response_item' && (p.type === 'function_call_output' || p.type === 'custom_tool_call_output')) {
+    const text = typeof p.output === 'string' ? p.output : textOf(p.output);
+    return [{ kind: 'output', callId: p.call_id || null, at, exit: exitFromText(text), output: text }];
+  }
+  return [];
+}
+
+// Map each Codex tool call onto the Claude tool names route-scan's behavior
+// pool counts, one name per call: lookup-only commands are lookups, anything
+// else a shell command could have done is a run.
+function behaviorName(ev) {
+  if (ev.kind === 'patch') return 'Edit';
+  if (ev.kind === 'mcp') return 'Mcp';
+  if (ev.kind !== 'command') return null;
+  const types = ev.parsed.map((c) => c?.type);
+  if (!types.length || types.includes('unknown')) return 'Bash';
+  if (types.every((t) => t === 'search')) return 'Grep';
+  if (types.every((t) => t === 'list_files')) return 'LS';
+  return 'Read';
+}
+
+/** Fill in a tool result only when no structured completion describes it. */
+export function codexLegacyToolEvent(call, out) {
+  if (!/^(?:functions\.|tools\.)?(?:exec_command|shell_command|shell|exec|apply_patch)$/.test(call?.name || '')) return null;
+  if (/apply_patch$/.test(call.name)) return { ...out, kind: 'patch', failed: out.exit !== 0 };
+  let input;
+  try { input = JSON.parse(call.input); } catch { /* Older calls can carry plain commands. */ }
+  const command = input?.cmd ?? input?.command ?? call.input ?? '';
+  return { ...out, kind: 'command', argv: Array.isArray(command) ? command : [String(command)],
+    parsed: [], failed: out.exit !== 0, cwd: input?.workdir || null };
+}
+
+const emptyTurn = (turnId) => ({ turnId, startedAt: null, endedAt: null, aborted: false, model: null, effort: null, cwd: null,
+  text: '', userMessages: 0, calls: 0, out: 0, input: 0, cached: 0, cacheWrite: 0, tools: {}, mutating: 0, errors: 0,
+  delegated: 0, commands: [], patches: [], usageKnown: false });
+
+/**
+ * One rollout as turns, for scans that need per-turn behavior rather than
+ * session totals. Legacy "Process exited" text only fills in a call no
+ * structured event described, so a call is never counted twice.
+ */
+export async function parseCodexTurns(filePath, { cutoffMs = -Infinity } = {}) {
+  const session = { filePath, sessionId: null, projectDir: '', isSubagent: false, parentThreadId: null, provider: null, turns: [] };
+  const turns = new Map();
+  const turnOf = (id) => {
+    if (!id) return null;
+    if (!turns.has(id)) turns.set(id, emptyTurn(id));
+    return turns.get(id);
+  };
+  const seenCalls = new Set();
+  const calls = new Map();
+  const legacy = [];
+  const modernUsage = new Map();
+  let previousUsage = null;
+  let current = null;
+  let context = { model: null, effort: null, cwd: null };
+  const stream = createReadStream(filePath, { encoding: 'utf8' });
+  const lines = createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of lines) {
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const p = e?.payload;
+    if (!p || typeof p !== 'object') continue;
+    if (e.type === 'session_meta') {
+      session.sessionId = p.id || p.session_id || null;
+      session.projectDir = typeof p.cwd === 'string' ? p.cwd : '';
+      session.isSubagent = typeof p.source === 'object' && p.source !== null && 'subagent' in p.source;
+      session.parentThreadId = p.source?.subagent?.thread_spawn?.parent_thread_id || null;
+      session.provider = typeof p.model_provider === 'string' ? p.model_provider : null;
+      continue;
+    }
+    if (e.type === 'turn_context') {
+      context = { model: typeof p.model === 'string' ? p.model : context.model,
+        effort: typeof (p.effort ?? p.reasoning_effort) === 'string' ? (p.effort ?? p.reasoning_effort) : context.effort,
+        cwd: typeof p.cwd === 'string' ? p.cwd : context.cwd };
+      const t = turnOf(p.turn_id || current);
+      if (t) Object.assign(t, { model: context.model, effort: context.effort, cwd: context.cwd });
+      continue;
+    }
+    if (e.type === 'event_msg' && p.type === 'task_started') {
+      current = p.turn_id || null;
+      const t = turnOf(current);
+      if (t) {
+        t.startedAt ??= Number.isFinite(Number(p.started_at)) ? Number(p.started_at) * 1000 : Date.parse(e.timestamp);
+        t.model ??= context.model; t.effort ??= context.effort; t.cwd ??= context.cwd;
+      }
+      continue;
+    }
+    if (e.type === 'event_msg' && (p.type === 'task_complete' || p.type === 'turn_aborted')) {
+      const t = turnOf(p.turn_id || current);
+      if (t) {
+        t.endedAt = Number.isFinite(Number(p.completed_at)) ? Number(p.completed_at) * 1000 : Date.parse(e.timestamp);
+        if (p.type === 'turn_aborted') t.aborted = true;
+      }
+      continue;
+    }
+    if (e.type === 'token_usage_record') {
+      const t = turnOf(p.turn_id);
+      const u = p.turn_token_usage || p.usage;
+      if (t && Number.isSafeInteger(u?.input_tokens) && Number.isSafeInteger(u?.output_tokens)) {
+        const usage = { out: count(u.output_tokens), input: count(u.input_tokens),
+          cached: count(u.cached_input_tokens), cacheWrite: count(u.cache_write_input_tokens) };
+        const old = modernUsage.get(t.turnId);
+        if (!p.turn_token_usage && old) for (const key of Object.keys(usage)) usage[key] += old[key];
+        modernUsage.set(t.turnId, { ...usage, calls: (old?.calls || 0) + 1, usageKnown: true });
+      }
+      continue;
+    }
+    if (e.type === 'event_msg' && p.type === 'token_count') {
+      const u = p.info?.total_token_usage;
+      if (!Number.isSafeInteger(u?.input_tokens) || !Number.isSafeInteger(u?.output_tokens)) continue;
+      const usage = { input: count(u.input_tokens), out: count(u.output_tokens),
+        cached: count(u.cached_input_tokens), cacheWrite: count(u.cache_write_input_tokens) };
+      const reset = previousUsage && (usage.input < previousUsage.input || usage.out < previousUsage.out);
+      const base = reset ? null : previousUsage;
+      const delta = Object.fromEntries(Object.entries(usage).map(([key, value]) => [key, Math.max(0, value - (base?.[key] || 0))]));
+      previousUsage = usage;
+      const t = turnOf(p.turn_id || current);
+      if (t && (delta.input || delta.out)) {
+        for (const [key, value] of Object.entries(delta)) t[key] += value;
+        t.calls++;
+        t.usageKnown = true;
+      }
+      continue;
+    }
+    for (const ev of codexToolEvents(e)) {
+      if (ev.kind === 'call') {
+        if (ev.callId) calls.set(ev.callId, ev);
+        const t = turnOf(current);
+        if (t && /^(?:functions\.|tools\.)?spawn_agent$/.test(ev.name)) t.delegated++;
+        continue;
+      }
+      if (ev.kind === 'output') { if (ev.exit !== null && ev.callId) legacy.push({ ...ev, turnId: current }); continue; }
+      const t = turnOf(ev.turnId || current);
+      if (!t) continue;
+      if (ev.kind === 'user') {
+        t.userMessages++;
+        if (!t.text) t.text = ev.text.trim();
+        continue;
+      }
+      if (ev.callId) {
+        if (seenCalls.has(ev.callId)) continue;
+        seenCalls.add(ev.callId);
+      }
+      const name = behaviorName(ev);
+      if (name) t.tools[name] = (t.tools[name] || 0) + 1;
+      if (name === 'Bash' || name === 'Edit') t.mutating++;
+      if (ev.failed) t.errors++;
+      if (ev.kind === 'command') t.commands.push(ev);
+      if (ev.kind === 'patch') t.patches.push(ev);
+    }
+  }
+  for (const out of legacy) {
+    if (seenCalls.has(out.callId)) continue;
+    const t = turnOf(out.turnId);
+    const call = calls.get(out.callId);
+    // write_stdin/wait poll a command that is already running; only calls that
+    // start work count, or one long command becomes several.
+    const ev = codexLegacyToolEvent(call, out);
+    if (!t || !ev) continue;
+    seenCalls.add(out.callId);
+    const name = behaviorName(ev);
+    t.tools[name] = (t.tools[name] || 0) + 1;
+    t.mutating++;
+    if (ev.failed) t.errors++;
+    (ev.kind === 'patch' ? t.patches : t.commands).push(ev);
+  }
+  for (const [id, usage] of modernUsage) Object.assign(turns.get(id), usage);
+  session.turns = [...turns.values()].filter((t) => (t.startedAt ?? t.endedAt ?? 0) >= cutoffMs || !Number.isFinite(t.startedAt ?? t.endedAt));
+  return session;
+}
+
+/** Rollout JSONL is a best-effort local format, not a stable Codex API. */
+export async function parseCodexSessionFile(filePath, { cutoffMs = -Infinity } = {}) {
+  const session = {
+    agent: 'codex', sessionId: null, filePath, projectDir: '', model: 'unknown',
+    startTime: null, endTime: null, requestCount: 0, totals: emptyTotals(),
+    maxContextPerRequest: 0, reasoningOutputTokens: 0, contextWindow: null,
+    lastContextTokens: null, rateLimits: null, lastActivity: null, effort: null,
+    cacheActivity: null,
+  };
+  let previous = null;
+  const stream = createReadStream(filePath, { encoding: 'utf8' });
+  const lines = createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of lines) {
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const p = e?.payload;
+    if (!p) continue;
+    updateSnapshot(session, e);
+    if (e.type !== 'event_msg' || p.type !== 'token_count') continue;
+    if (!p.info) continue;
+    const info = p.info;
+    const total = info.total_token_usage;
+    // Repeated token_count events also carry rate-limit updates. Only a
+    // change in cumulative usage represents newly consumed tokens.
+    if (!total || !Number.isSafeInteger(total.input_tokens) || !Number.isSafeInteger(total.output_tokens)) continue;
+    const current = {
+      input: count(total.input_tokens), cached: count(total.cached_input_tokens),
+      written: count(total.cache_write_input_tokens),
+      output: count(total.output_tokens), reasoning: count(total.reasoning_output_tokens),
+    };
+    const reset = previous && (current.input < previous.input || current.output < previous.output);
+    const base = reset || !previous ? { input: 0, cached: 0, written: 0, output: 0, reasoning: 0 } : previous;
+    const delta = Object.fromEntries(Object.keys(current).map((k) => [k, Math.max(0, current[k] - base[k])]));
+    previous = current;
+    if (!delta.input && !delta.output) continue;
+    const ts = Date.parse(e.timestamp);
+    // Quota-only snapshots repeat cumulative usage. Only newly observed cache
+    // reads/writes refresh the clock, never local tools or repeated snapshots.
+    if (Number.isFinite(ts) && delta.input > 0 && (delta.cached > 0 || delta.written > 0) &&
+        (!session.cacheActivity || ts >= session.cacheActivity.at.getTime())) {
+      session.cacheActivity = { at: new Date(ts), model: session.model, provider: session.provider,
+        cached: Math.min(delta.input, delta.cached), written: Math.min(delta.input, delta.written) };
+    }
+    if (!Number.isFinite(ts) || ts < cutoffMs) continue;
+    const cached = Math.min(delta.input, delta.cached);
+    session.totals.input += delta.input - cached;
+    session.totals.cacheRead += cached;
+    session.totals.output += delta.output;
+    // Reasoning is a subset of output, just as cached input is a subset of input.
+    session.reasoningOutputTokens += Math.min(delta.output, delta.reasoning);
+    session.requestCount++;
+    session.startTime ??= new Date(ts);
+    session.endTime = new Date(ts);
+    session.maxContextPerRequest = Math.max(session.maxContextPerRequest, count(info.last_token_usage?.input_tokens));
+    if (count(info.model_context_window)) session.contextWindow = info.model_context_window;
+  }
+  return session;
+}
+
+export async function discoverCodexSessionFiles({ home = codexUserDir(), days = 30, excludeSessionPath } = {}) {
+  const cutoff = Date.now() - days * 86400000;
+  const files = [];
+  const excluded = excludeSessionPath ? resolve(excludeSessionPath) : null;
+  async function walk(dir) {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile() && entry.name.endsWith('.jsonl') && resolve(path) !== excluded) {
+        try {
+          const s = await stat(path);
+          if (s.mtimeMs >= cutoff) files.push({ path, mtime: s.mtimeMs, size: s.size });
+        } catch { /* A session may disappear during archival. */ }
+      }
+    }
+  }
+  await walk(join(home, 'sessions'));
+  await walk(join(home, 'archived_sessions'));
+  return files.sort((a, b) => a.mtime - b.mtime);
+}
+
+export async function parseAllCodexSessions(options = {}) {
+  const files = await discoverCodexSessionFiles(options);
+  const cutoffMs = Date.now() - (options.days ?? 30) * 86400000;
+  const results = [];
+  for (let i = 0; i < files.length; i += 10) {
+    const batch = await Promise.all(files.slice(i, i + 10).map(async ({ path }) => {
+      try { return await parseCodexSessionFile(path, { cutoffMs }); } catch { return null; }
+    }));
+    results.push(...batch.filter((s) => s?.requestCount && (!options.projectFilter || s.projectDir.includes(options.projectFilter))));
+  }
+  // An archive can briefly coexist with the original rollout.
+  const seen = new Set();
+  return results.reverse().filter((s) => {
+    const key = s.sessionId || s.filePath;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  }).reverse();
+}

package/src/codex-route-scan.js

@@ -0,0 +1,171 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { userDataDir } from './paths.js';
+import { loadConfig } from './config.js';
+import { findProjectRoot } from './harness.js';
+import { discoverCodexSessionFiles, parseCodexTurns } from './codex-parser.js';
+import { categorize, isSkippable, tierOf, calibrateThresholds, MIN_RECURRENCE,
+  RESCAN_MIN_INTERVAL_MS, RESCAN_BIG_DELTA_BYTES, RESCAN_MAX_AGE_MS } from './route-scan.js';
+import { codexPromptCategory, loadCodexModelRules } from './codex-delegation.js';
+import { codexRunCost, readCodexPrices } from './codex-cache-policy.js';
+import { refreshCodexLedger } from './codex-ledger.js';
+
+/*
+ * Codex route-scan: recurring easy turns become delegation-rule candidates.
+ * Kept apart from Claude's route-scan.json, model-rules.json and
+ * ratchet-model.md; approval goes through the Codex rule store with an
+ * explicit scope.
+ */
+
+const cacheFile = (dir) => join(dir, 'codex-route-scan.json');
+const MAX_CANDIDATES = 8;
+
+export function readCodexRouteScan({ dir = userDataDir() } = {}) {
+  try {
+    const data = JSON.parse(readFileSync(cacheFile(dir), 'utf8'));
+    return data?.version === 1 && Array.isArray(data.candidates) ? data : null;
+  } catch { return null; }
+}
+
+function writeCache(data, dir) {
+  mkdirSync(dir, { recursive: true });
+  const file = cacheFile(dir), tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/** Candidates not yet approved or dismissed; with `root`, only that project's. */
+export function openCodexCandidates(cache, { root } = {}) {
+  if (!cache?.candidates) return [];
+  const resolved = new Set(cache.resolved || []);
+  const project = root ? resolve(root) : null;
+  return cache.candidates.filter((c) => !resolved.has(c.signature) && (!project || c.projectRoot === project));
+}
+
+export function findCodexCandidate(ref, { dir = userDataDir() } = {}) {
+  const m = /^R?(\d+)$/i.exec(String(ref || ''));
+  if (!m) return null;
+  return openCodexCandidates(readCodexRouteScan({ dir })).find((c) => c.id === Number(m[1])) || null;
+}
+
+/** Stop offering a candidate: it was approved or the user said no. */
+export function resolveCodexCandidate(cand, { dir = userDataDir() } = {}) {
+  const cache = readCodexRouteScan({ dir });
+  if (!cache) return;
+  cache.resolved = [...new Set([...(cache.resolved || []), cand.signature])];
+  writeCache(cache, dir);
+}
+
+/** Same gate as Claude's: at most hourly, and only when enough new log data arrived. */
+export async function shouldRescanCodex(cache, { home, days = 14, now = Date.now() } = {}) {
+  const ts = Date.parse(cache?.scannedAt);
+  if (!Number.isFinite(ts)) return true;
+  const age = now - ts;
+  if (age < RESCAN_MIN_INTERVAL_MS) return false;
+  let total = 0, anyNew = false;
+  try {
+    for (const f of await discoverCodexSessionFiles({ home, days })) {
+      total += f.size;
+      if (f.mtime > ts) anyNew = true;
+    }
+  } catch { return age >= RESCAN_MAX_AGE_MS; }
+  if (!anyNew) return false;
+  if (total - (cache.dataBytes || 0) >= RESCAN_BIG_DELTA_BYTES) return true;
+  return age >= RESCAN_MAX_AGE_MS;
+}
+
+/**
+ * Cheaper targets the user can actually run. "Known to work" means seen in
+ * this user's Codex sessions, set as the default delegate target, or already
+ * a rule target, so a gateway that also serves unrelated models (embeddings,
+ * other vendors) never has one suggested blind.
+ */
+function pickTarget(group, { prices, known }) {
+  const cost = (model) => prices?.provider === group.provider ? codexRunCost(group.tokens, prices.prices[model]) : null;
+  const parent = cost(group.from);
+  if (parent === null) return { suggestedModel: null, alternatives: [], estSavedUsd: null };
+  const cheaper = Object.keys(prices.prices).filter((m) => m !== group.from && prices.prices[m])
+    .map((m) => ({ model: m, usd: cost(m) })).filter((x) => x.usd !== null && x.usd < parent)
+    .sort((a, b) => a.usd - b.usd);
+  const eligible = cheaper.filter((x) => known.has(`${group.provider}|${x.model}`));
+  // Simple work goes to the cheapest model; moderate work steps down one notch.
+  const pick = group.tiers.T2 >= group.tiers.T1 ? eligible[0] : eligible.at(-1);
+  return {
+    suggestedModel: pick?.model ?? null,
+    alternatives: pick ? [] : cheaper.slice(0, 3).map((x) => x.model),
+    estSavedUsd: pick ? parent - pick.usd : null,
+  };
+}
+
+export async function runCodexRouteScan({ days = 14, now = Date.now(), home, dir = userDataDir(),
+  prices = readCodexPrices({ now, home, dir }), cfg = loadConfig(), refreshLedger = true } = {}) {
+  const files = await discoverCodexSessionFiles({ home, days });
+  const cutoffMs = now - days * 86400000;
+  const episodes = [];
+  const observed = new Set();
+  const seen = new Set();
+  let dataBytes = 0;
+  for (const f of files.slice().reverse()) {
+    dataBytes += f.size;
+    let s;
+    try { s = await parseCodexTurns(f.path, { cutoffMs }); } catch { continue; }
+    const identity = s.sessionId || f.path;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    // A model a subagent ran on is proven to work, even though its turns are
+    // the delegated work itself rather than requests to route.
+    for (const t of s.turns) if (t.model) observed.add(`${s.provider}|${t.model}`);
+    if (s.isSubagent) continue;
+    for (const t of s.turns) {
+      if (t.aborted || !Number.isFinite(t.endedAt) || !t.text || !t.model || isSkippable(t.text)) continue;
+      episodes.push({ ...t, provider: s.provider, projectRoot: findProjectRoot(t.cwd || s.projectDir || '.', { agent: 'codex' }) });
+    }
+  }
+  const thresholds = calibrateThresholds(episodes.map((e) => e.out));
+  const groups = new Map();
+  for (const ep of episodes) {
+    // A second user message mid-turn is steering, which is not a bounded task.
+    if (ep.userMessages > 1) continue;
+    // Group by the category the prompt hook would route, so an approved rule
+    // can fire. The tool mix only vetoes editing turns, which categorize()
+    // leaves unclassified.
+    const runtime = codexPromptCategory(ep.text);
+    if (!runtime || !categorize(ep.text, ep.tools)) continue;
+    const tier = tierOf(ep, runtime, thresholds);
+    if (tier !== 'T1' && tier !== 'T2') continue;
+    const key = `${runtime.id}|${ep.provider}|${ep.model}|${ep.projectRoot}`;
+    const g = groups.get(key) || { signature: key, category: runtime.id, label: runtime.label, labelEn: runtime.labelEn,
+      from: ep.model, provider: ep.provider, projectRoot: ep.projectRoot, count: 0, tiers: { T1: 0, T2: 0 }, example: ep.text,
+      tokens: { input: 0, cached: 0, cacheWrite: 0, output: 0 }, lastSeen: 0 };
+    g.count++;
+    g.tiers[tier]++;
+    if (ep.text.length < g.example.length) g.example = ep.text;
+    g.tokens.input += ep.input; g.tokens.cached += ep.cached; g.tokens.cacheWrite += ep.cacheWrite; g.tokens.output += ep.out;
+    g.lastSeen = Math.max(g.lastSeen, ep.endedAt ?? ep.startedAt ?? 0);
+    groups.set(key, g);
+  }
+  let rules = [];
+  try { rules = loadCodexModelRules({ dir }); } catch { /* An unreadable rule file only means candidates may repeat. */ }
+  const covered = (g) => rules.some((r) => r.category === g.category && r.from === g.from &&
+    (!r.provider || r.provider === g.provider) &&
+    (r.scope === 'global' || r.targetRoot === g.projectRoot));
+  const known = new Set([...observed, ...rules.filter((r) => r.provider).map((r) => `${r.provider}|${r.model}`)]);
+  if (prices?.provider && cfg?.codex?.delegateTarget?.model) known.add(`${prices.provider}|${cfg.codex.delegateTarget.model}`);
+  const prev = readCodexRouteScan({ dir });
+  const resolved = new Set(prev?.resolved || []);
+  const candidates = [...groups.values()]
+    .filter((g) => g.count >= MIN_RECURRENCE && !covered(g) && !resolved.has(g.signature))
+    .sort((a, b) => b.count - a.count || b.lastSeen - a.lastSeen)
+    .slice(0, MAX_CANDIDATES)
+    .map((g, i) => ({ id: i + 1, signature: g.signature, category: g.category, label: g.label, labelEn: g.labelEn,
+      from: g.from, provider: g.provider, projectRoot: g.projectRoot, count: g.count, tiers: g.tiers, example: g.example.slice(0, 160),
+      lastSeen: g.lastSeen || null, suggestedScope: 'project', ...pickTarget(g, { prices, known }) }));
+  const data = { version: 1, scannedAt: new Date(now).toISOString(), days, dataBytes, totalEpisodes: episodes.length,
+    thresholds, observedModels: [...observed], priceCheckedAt: prices?.checkedAt ?? null, candidates, resolved: [...resolved] };
+  writeCache(data, dir);
+  if (refreshLedger) {
+    try { await refreshCodexLedger({ dir, home, now, prices }); } catch { /* The ledger catches up on the next scan. */ }
+  }
+  return data;
+}

package/src/commands/brief.js

@@ -22,10 +22,33 @@ export async function run({ hasFlag }) {
       process.exit(1);
     }
     const ctx = readStdinJson() || {};
+    const parts = [];
     try {
       const { runBrief } = await import('../brief.js');
       const out = await runBrief({ sessionId: ctx.session_id, transcriptPath: ctx.transcript_path });
-      if (out) console.log(out);
+      if (out) parts.push(out);
     } catch (e) { debug('brief:hook', e); /* briefing is best-effort — never block a prompt */ }
+    // State the matching delegation rule as a fact about this request. Registered
+    // rules were going unused because applying one meant scanning a list and
+    // resolving it against a general "don't spawn subagents" instruction; naming
+    // the match here removes both steps. Silent unless it is sure — see
+    // src/route-inject.js.
+    try {
+      const { routeHint, sessionModelRank } = await import('../route-inject.js');
+      // The payload names the session but not its model, so the rank comes from
+      // the transcript: without it a Sonnet session is told to delegate to
+      // Sonnet, which saves nothing.
+      const sessionRank = sessionModelRank({ transcriptPath: ctx.transcript_path });
+      // `root` is the session's own cwd, not this process's. agentPhrase names the
+      // subagent only where `<root>/.claude/agents/<name>.md` exists, and with no
+      // root that lookup falls back to process.cwd() — whatever directory the hook
+      // was spawned in, which stops being the project root as soon as the two
+      // differ. Claude Code sends `cwd` for that reason and the PreToolUse hook
+      // already reads it (src/delegation-guard.js). A payload without the field
+      // leaves root undefined, which is the behaviour this had before.
+      const hint = routeHint(ctx.prompt, { sessionRank, root: ctx.cwd });
+      if (hint) parts.push(hint);
+    } catch (e) { debug('brief:route-hint', e); }
+    if (parts.length) console.log(parts.join('\n'));
     return;
 }

package/src/commands/codex-delegate.js

@@ -0,0 +1,59 @@
+import { loadConfig, saveConfig } from '../config.js';
+import { configureCodexHooks } from '../codex-installer.js';
+import { validateCodexTarget, loadCodexModelRules, addCodexModelRule, removeCodexModelRule } from '../codex-delegation.js';
+import { findCodexCandidate, resolveCodexCandidate } from '../codex-route-scan.js';
+import { codexRoutingSavedTotals } from '../codex-ledger.js';
+import { codexProviderName } from '../agent.js';
+
+export function run({ args, getArg, hasFlag, root }) {
+  const sub = args[1] || 'status';
+  if (args.some((arg) => arg.startsWith('--hook'))) throw new Error('Use codex-hook for Codex hook payloads.');
+  for (const flag of ['--model', '--effort', '--from']) {
+    if (args.some((arg) => arg === flag || arg.startsWith(`${flag}=`)) && (!getArg(flag) || getArg(flag).startsWith('-'))) {
+      throw new Error(`${flag} requires a value.`);
+    }
+  }
+  const rules = loadCodexModelRules();
+  if (sub === 'rules') {
+    if (args[2] === 'add') {
+      if (hasFlag('--global') === hasFlag('--project')) throw new Error('Choose --global or --project for the rule.');
+      const scope = hasFlag('--project') ? 'project' : 'global';
+      // `add R<N>` approves a route-scan candidate; its project is where the pattern was seen.
+      const cand = /^R\d+$/i.test(args[3] || '') ? findCodexCandidate(args[3]) : null;
+      if (/^R\d+$/i.test(args[3] || '') && !cand) throw new Error(`No open Codex route candidate ${args[3]}. Run sprag route-scan --agent codex.`);
+      const model = getArg('--model') ?? cand?.suggestedModel;
+      if (cand && !model) throw new Error(`R${cand.id} has no priced target the user has run. Pass --model <id>${cand.alternatives?.length ? ` (priced cheaper: ${cand.alternatives.join(', ')})` : ''}.`);
+      const rule = addCodexModelRule({ category: cand?.category ?? args[3], model, effort: getArg('--effort'),
+        from: cand?.from ?? getArg('--from'), scope, root: cand?.projectRoot ?? root, provider: cand?.provider || codexProviderName() });
+      if (cand) resolveCodexCandidate(cand);
+      console.log(`Codex rule: ${rule.category} | ${rule.from} -> ${rule.model} | ${rule.scope}${rule.targetRoot ? ` ${rule.targetRoot}` : ''}`);
+    } else if (args[2] === 'rm') removeCodexModelRule(Number(args[3]));
+    else if (args[2]) throw new Error('Usage: delegate rules [add <category|R<N>> --from <model> --model <model> --global|--project | rm <N>]');
+    const rules = loadCodexModelRules();
+    if (!rules.length) console.log('No Codex model rules. Claude rules are not imported.');
+    rules.forEach((r, i) => console.log(`#${i + 1} ${r.category} | ${r.from} -> ${r.model} | ${r.scope}${r.targetRoot ? ` ${r.targetRoot}` : ''}`));
+    return;
+  }
+  if (!['on', 'off', 'status', 'model'].includes(sub)) throw new Error('Usage: delegate on|off|status|model <model>|rules --agent codex');
+  const cfg = loadConfig();
+  let target;
+  if (sub === 'model') target = args[2] === 'off' ? null : validateCodexTarget(args[2], getArg('--effort'));
+  else if (getArg('--model') !== undefined) target = validateCodexTarget(getArg('--model'), getArg('--effort'));
+  else if (hasFlag('--effort')) throw new Error('--effort requires a target model.');
+  if (target !== undefined && !['model', 'on'].includes(sub)) throw new Error('Set the target with delegate model or delegate on --model.');
+  if (sub === 'on') configureCodexHooks();
+  if (sub !== 'status') {
+    cfg.codex = { ...cfg.codex };
+    if (sub === 'on' || sub === 'off') cfg.codex.delegate = sub === 'on';
+    if (target !== undefined) cfg.codex.delegateTarget = target;
+    saveConfig(cfg);
+  }
+  console.log(`Codex delegate: ${cfg.codex?.delegate === true ? 'on' : 'off'} (model routing and guidance)`);
+  console.log(`Default target: ${cfg.codex?.delegateTarget?.model || 'inherit (no override)'}`);
+  console.log(`Codex rules: ${rules.length}`);
+  console.log('Explicit spawn models and custom roles are preserved. Targets must be available from your Codex provider.');
+  const saved = codexRoutingSavedTotals();
+  console.log(saved.priced
+    ? `Routing saved: $${saved.total.toFixed(4)} over ${saved.priced} priced run(s). Details: sprag route-scan savings --agent codex`
+    : `Routing saved: n/a (${saved.runs ? `${saved.runs} attributed run(s), none priced` : 'no attributed runs yet'}). Review/trust the Sprag hooks in Codex /hooks.`);
+}