sprag-cli 3.62.0 → 3.64.0

package/mod/sprag-doc2md/hooks/register.ts

@@ -0,0 +1,97 @@
+import type { EngineInterface, Register } from 'claude-code'
+
+/**
+ * sprag-doc2md: the mod form of sprag's PreToolUse(Read) hook.
+ *
+ * The settings hook can only refuse the Read and tell Claude where the
+ * converted Markdown is, which costs one more tool call per document. A mod
+ * sits in front of the call, so it hands the same call on with the path
+ * swapped: Claude asked for deck.pptx and reads deck.md, and the permission
+ * check still runs on the path that is actually read.
+ *
+ * Whenever this mod does not redirect (not a document, conversion refused or
+ * failed, sprag not on PATH) the call goes on untouched, and sprag's settings
+ * hook beneath it explains the refusal exactly as it does today. After a
+ * redirect that hook sees a .md path and stays silent, so the two never
+ * answer the same Read twice.
+ */
+
+// Mirrors TARGET_EXTENSIONS in src/doc2md.cjs. A hooks module has no Node, so
+// it cannot load that file; test/mod-install.test.js holds the two in step.
+const TARGET = /\.(pptx|xlsx|xls|pdf|docx|fig)$/i
+
+// The CLI's name, as CLI_NAME in src/cli-name.js spells it. The mod cannot
+// import that file either; test/mod-install.test.js holds the two in step.
+const CLI = 'sprag'
+
+// The converter gives up at 120 s on its own; the margin covers CLI start-up.
+// Time spent in $.process.run does not count against the hook's 10 s budget,
+// so the Read waits as long as the conversion does, as it does under the
+// settings hook today. The status line says so while it lasts.
+const CONVERT_TIMEOUT_MS = 150_000
+
+// What `sprag doc2md <path>` prints on success. Parsing human output is a
+// prototype shortcut: a `--json` flag on that command should replace it.
+const CONVERTED = /^✓ (cached|converted): (.+)$/m
+
+type Converted = { cacheFile: string; isCached: boolean }
+
+const baseName = (path: string) => path.split(/[\\/]/).pop() ?? path
+
+/**
+ * Runs the conversion the settings hook would run, ledger entry included.
+ * Answers null on any failure so the caller passes the event on unchanged.
+ *
+ * A first conversion can take a minute, and nothing else on screen says the
+ * Read is waiting on it, so the status line under the prompt names the file
+ * until the CLI returns. A status line rather than a transcript line: whether
+ * the file is cached is unknown until the CLI answers, and a log line on every
+ * Read would double the lines for the cached ones too.
+ */
+async function convert($: EngineInterface, path: string): Promise<Converted | null> {
+  $.ui.status(`doc2md: ${baseName(path)} 변환 중…`)
+  try {
+    const run = await $.process.run([CLI, 'doc2md', path], { timeoutMs: CONVERT_TIMEOUT_MS })
+    if (run.exitCode !== 0) return null
+    const match = CONVERTED.exec(run.stdout)
+    if (!match) return null
+    return { cacheFile: match[2].trim(), isCached: match[1] === 'cached' }
+  } catch {
+    return null
+  } finally {
+    $.ui.status(undefined)
+  }
+}
+
+function logRedirect($: EngineInterface, from: string, doc: Converted) {
+  $.ui.log(`doc2md: ${baseName(from)} 대신 변환본을 읽습니다${doc.isCached ? ' (캐시)' : ''}`)
+}
+
+export const register: Register = on => {
+  // Both hooks fail open, which is the point of the .catch on each: this mod
+  // saves a round trip and guards nothing, so a hook that breaks hands the
+  // event on as it came and sprag's settings hook beneath answers as before.
+  // Where the hook had already called next, next(e) replays that call.
+  on('tool.call', { tool: 'Read' }, async ($, e, next) => {
+    if (!TARGET.test(e.file_path)) return next(e)
+    const doc = await convert($, e.file_path)
+    if (!doc) return next(e)
+    logRedirect($, e.file_path, doc)
+    // Line and page ranges addressed the binary and mean nothing in the
+    // Markdown (`pages` applies to PDFs only), so the whole file is read.
+    const { offset: _offset, limit: _limit, pages: _pages, ...call } = e
+    return next({ ...call, file_path: doc.cacheFile })
+  }).catch(($, e, next) => next(e))
+
+  // An @-mentioned document is attached whole, before any tool call, so the
+  // Read hook above never sees it. Redirect the attachment the same way.
+  on('prompt.mention', { path: TARGET }, async ($, e, next) => {
+    const doc = await convert($, e.path)
+    if (!doc) return next(e)
+    logRedirect($, e.path, doc)
+    // A mention carries no `pages` (PromptMentionInput has mention, path,
+    // offset, limit and agentId), so only the line range is dropped here.
+    const { offset: _offset, limit: _limit, ...mention } = e
+    return next({ ...mention, path: doc.cacheFile })
+  }).catch(($, e, next) => next(e))
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.62.0",
+  "version": "3.64.0",
   "description": "Lower your Claude Code bill without changing how you work: simple tasks go to cheaper models, documents go in as compact Markdown, and the statusline shows spend and savings live. Works with Codex too.",
   "type": "module",
   "bin": {
@@ -15,11 +15,14 @@
     "release:notes": "node scripts/release-notes.mjs",
     "site:docs": "node scripts/build-site-docs.mjs",
     "test": "node --test",
+    "test:mods": "claude plugin test mod/sprag-doc2md && claude plugin test mod/sprag-delegation-meter",
     "version": "node scripts/sync-site-version.mjs"
   },
   "files": [
     "bin/",
     "src/",
+    "mod/*/.claude-plugin/plugin.json",
+    "mod/*/hooks/**",
     "presets/",
     "examples/",
     "README.md",

package/src/codex-brief.js

@@ -7,7 +7,7 @@ import { writeViaTmp } from './state-file.js';
 import { readCodexSnapshot } from './codex-parser.js';
 import { loadCodexModelRules } from './codex-delegation.js';
 import { loadCodexLedger } from './codex-ledger.js';
-import { codexRulesInReview } from './codex-rule-health.js';
+import { codexRulesInReview, codexSharedRuleHealth } from './codex-rule-health.js';
 
 const RESET_TOLERANCE_S = 300;
 const hash = (value) => createHash('sha256').update(value).digest('hex');
@@ -88,6 +88,15 @@ export function runCodexBrief({ sessionId, transcriptPath, cwd, root: projectRoo
       }
     }
   } catch { /* An unreadable rule file or ledger only skips this line. */ }
+  try {
+    for (const { rule, health, from, model, provider } of codexSharedRuleHealth({ root: cwd || projectRoot || snapshot.projectDir, dir })) {
+      if (health.status !== 'review') continue;
+      issues.push({ key: 'rule-health', tier: 1,
+        signature: `shared-rule-health:${JSON.stringify([rule.sharedSignature, rule.scope, rule.targetRoot, provider, from, model])}`,
+        level: 'warning', message: `Codex shared policy ${rule.tier} ${rule.category} (${provider}: ${from} -> ${model}) failed ${health.errs} of ${health.runs} measured runs.`,
+        advice: 'Review: sprag delegate rules --agent codex. Pause shared routing: sprag delegate shared off --agent codex. Common policy removal affects both agents.' });
+    }
+  } catch { /* Shared health is independent of Codex-only rule parsing. */ }
   const next = issues.filter((issue) => !active.includes(issue.signature) &&
     !(issue.key === 'context' && issue.tier === 1 && active.includes('context:2')));
   // Missing or stale measurements do not resolve an earlier warning. A fresh

package/src/codex-delegation-diagnostics.js

@@ -0,0 +1,42 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'smol-toml';
+import { codexUserDir, codexModelName } from './agent.js';
+import { codexDelegationStatus } from './codex-ledger.js';
+
+/** Local introspection only. A CLI feature flag cannot prove a model received a tool. */
+export function codexDelegationDiagnostics({ home = codexUserDir(), model = codexModelName({ home }), sessionId, dir,
+  exec = execFileSync } = {}) {
+  const result = { model, version: null, flags: {}, configuredDisabled: false,
+    catalogAgentVersion: null, activity: codexDelegationStatus({ dir, sessionId }),
+    tools: 'unverified in the active session', warnings: [], errors: [] };
+  try {
+    const cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8'));
+    const profile = cfg.profiles?.[cfg.profile];
+    result.configuredDisabled = (profile?.agents?.enabled ?? cfg.agents?.enabled) === false ||
+      (profile?.features?.multi_agent ?? cfg.features?.multi_agent) === false;
+  } catch (e) { if (e.code !== 'ENOENT') result.errors.push('Cannot parse user config.'); }
+  const run = (args) => exec('codex', args, { encoding: 'utf8', timeout: 5000, maxBuffer: 20 * 1024 * 1024,
+    env: { ...process.env, CODEX_HOME: home }, stdio: ['ignore', 'pipe', 'pipe'] });
+  try { result.version = run(['--version']).trim().slice(0, 100); } catch { result.errors.push('Codex version unavailable.'); }
+  try {
+    for (const line of run(['features', 'list']).split('\n')) {
+      const m = /^(multi_agent(?:_v2(?:_dynamic_tools)?)?)\s+.+?\s+(true|false)\s*$/.exec(line);
+      if (m) result.flags[m[1]] = m[2] === 'true';
+    }
+  } catch { result.errors.push('Codex feature list unavailable.'); }
+  try {
+    const data = JSON.parse(run(['debug', 'models', '--bundled']));
+    const models = Array.isArray(data) ? data : data.models;
+    const found = models?.find((m) => m.slug === model);
+    if (['v1', 'v2'].includes(found?.multi_agent_version)) result.catalogAgentVersion = found.multi_agent_version;
+  } catch { result.errors.push('Bundled model catalog unavailable.'); }
+  if (result.configuredDisabled || result.flags.multi_agent === false) result.warnings.push('Agent tools are disabled in the inspected configuration.');
+  if (result.catalogAgentVersion === 'v2' && result.flags.multi_agent_v2 === false) {
+    result.warnings.push('The bundled model catalog names v2 while the v2 feature is off. This is a compatibility clue, not proof of the cause; no setting was changed.');
+  }
+  if (result.activity.offers && !result.activity.bound && !result.activity.settled) result.warnings.push('Sprag emitted offers but no child execution is connected.');
+  result.warnings.push('Confirm spawn_agent and wait_agent in the running session. If absent, continue on the main agent and report the limitation; do not launch another CLI as a substitute.');
+  return result;
+}

package/src/codex-delegation.js

@@ -19,6 +19,13 @@ const MARKER = '<!-- sprag:codex:delegation -->';
 const safeId = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,255}$/.test(value);
 const validEffort = (value) => value === undefined || ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'].includes(value);
 
+/**
+ * Delegation is on unless the user turned it off. A fresh install writes no
+ * setting, so requiring `delegate === true` meant nothing ever delegated; only
+ * `sprag delegate off --agent codex` stores `false`.
+ */
+export function codexDelegateEnabled(cfg) { return cfg?.codex?.delegate !== false; }
+
 export function validateCodexTarget(model, effort) {
   if (!safeId(model)) throw new Error('Provide a literal Codex model ID.');
   if (!validEffort(effort)) {
@@ -56,13 +63,30 @@ function observedCodexModels(dir, provider) {
   } catch { return []; }
 }
 
+/**
+ * Model slugs Codex's own catalog lists for this account
+ * (`<codex home>/models_cache.json`, entries with visibility "list"). A new
+ * user has no session history, so the catalog is the only evidence of what
+ * Codex can run. Unreadable or malformed files give [].
+ */
+function catalogCodexModels(home) {
+  try {
+    const data = JSON.parse(readFileSync(join(home, 'models_cache.json'), 'utf8'));
+    return (Array.isArray(data?.models) ? data.models : [])
+      .filter((m) => m && m.visibility === 'list' && typeof m.slug === 'string').map((m) => m.slug);
+  } catch { return []; }
+}
+
 /**
  * The models Codex resolves T2 and T1 to when the user mapped none, the way
- * Claude Code resolves `haiku` and `sonnet`. Only a model that is priced on the
- * parent's provider, costs less than the parent, and has already run in this
- * user's Codex sessions qualifies, so the hint never names a model the gateway
- * cannot serve. The cheapest is T2 and the next one up is T1; with a single
- * candidate T1 stays on the main agent. Returns { targets, reason }.
+ * Claude Code resolves `haiku` and `sonnet`. Candidates are the models that
+ * already ran in this user's Codex sessions plus, for the built-in OpenAI
+ * provider only, the models Codex's catalog lists for the account (a gateway
+ * serves its own set, which the catalog does not describe). A candidate
+ * qualifies only if it is priced on the parent's provider and costs less than
+ * the parent, so the hint never names a model the gateway cannot serve. The
+ * cheapest is T2 and the next one up is T1; with a single candidate T1 stays
+ * on the main agent. Returns { targets, reason }.
  */
 export function autoCodexSharedTargets({ dir = userDataDir(), home = codexUserDir(), model, provider, now = Date.now() } = {}) {
   if (!safeId(model) || !safeId(provider)) return { targets: [], reason: 'unknown parent model or provider' };
@@ -71,10 +95,15 @@ export function autoCodexSharedTargets({ dir = userDataDir(), home = codexUserDi
   const cost = (m) => codexRunCost(RANKING_USAGE, book.prices[m]);
   const parent = cost(model);
   if (parent === null) return { targets: [], reason: `${model} is not priced on ${provider}` };
-  const cheaper = [...new Set(observedCodexModels(dir, provider))]
+  const available = [...new Set([...observedCodexModels(dir, provider), ...(provider === 'openai' ? catalogCodexModels(home) : [])])];
+  const cheaper = available
     .filter((m) => m !== model && safeId(m)).map((m) => ({ model: m, usd: cost(m) }))
     .filter((x) => x.usd !== null && x.usd < parent).sort((a, b) => a.usd - b.usd || a.model.localeCompare(b.model));
-  if (!cheaper.length) return { targets: [], reason: `no cheaper priced model has run in your Codex sessions on ${provider}` };
+  if (!cheaper.length) {
+    return { targets: [], reason: available.length
+      ? `${model} is already the cheapest available model on ${provider}`
+      : `no cheaper priced model has run in your Codex sessions on ${provider}` };
+  }
   const targets = cheaper.slice(0, 2).map((x, i) => ({ tier: i === 0 ? 'T2' : 'T1', from: model, model: x.model, provider, auto: true }));
   return { targets, reason: null };
 }
@@ -86,7 +115,7 @@ export function autoCodexSharedTargets({ dir = userDataDir(), home = codexUserDi
  */
 export function codexTierTargets({ cfg = loadConfig(), dir = userDataDir(), home = codexUserDir(), model, provider = codexProviderName() } = {}) {
   const explicit = codexSharedTargets(cfg).filter((t) => t.from === model && t.provider === provider);
-  if (cfg.codex?.delegate !== true || cfg.codex?.sharedRules?.auto === false) return explicit;
+  if (!codexDelegateEnabled(cfg) || cfg.codex?.sharedRules?.auto === false) return explicit;
   const auto = autoCodexSharedTargets({ dir, home, model, provider }).targets
     .filter((t) => !explicit.some((e) => e.tier === t.tier));
   return [...explicit, ...auto];
@@ -215,6 +244,23 @@ const SHARED_TIER_GUIDANCE = 'Choose T2 only for a simple bounded lookup or comm
 const WAIT_TEXT = 'Wait for it to finish (call wait_agent with timeout_ms of at least 120000, and again if it times out) and do not do the delegated task yourself while it runs; then verify its result and report unfinished work. Do not spawn another CLI process. '
   + 'If sub-agent tools or the target model are unavailable, keep the task on the main agent and state that delegation was unavailable.';
 
+/** Called explicitly by the parent after design, never by prompt classification. */
+export function codexImplementationHint({ model, provider, sessionId, cfg = loadConfig(), dir = userDataDir(),
+  home = codexUserDir(), record = recordCodexDelegation } = {}) {
+  if (!safeId(model) || !safeId(provider) || !safeId(sessionId)) throw new Error('Implementation delegation requires --from, --provider and --session for the active parent.');
+  if (!codexDelegateEnabled(cfg) || cfg.codex?.sharedRules?.enabled === false) return 'Implementation delegation is off. Keep the implementation on the main agent.';
+  const target = codexTierTargets({ cfg, dir, home, model, provider }).find((t) => t.tier === 'T1');
+  if (!target) return 'T1 is unresolved for this parent/provider. Keep the implementation on the main agent; do not fall back to T2.';
+  const id = newRouteId();
+  record({ id, parentSessionId: sessionId, via: 'prompt', source: 'implementation', tier: 'T1',
+    from: model, to: target.model, provider, effort: target.effort ?? null }, { dir });
+  return `[Sprag implementation delegation] The user-approved implementation-split policy keeps design and specification on the main agent. `
+    + `Delegate only the implementation of that completed design to model ${target.model}${target.effort ? `, reasoning_effort ${target.effort}` : ''}, with fork_turns "none". `
+    + 'Never delegate design judgement or irreversible actions. Give one child a self-contained specification, owned files, constraints, test commands, completion criteria and the reason for this model choice. '
+    + 'Cap: 8000 output tokens. Stop and report partial work before exceeding it. Do not recursively delegate. '
+    + WAIT_TEXT + `\nEnd the child task message with this route line only:\n<!-- sprag:codex:route id=${id} -->`;
+}
+
 function sharedTargetText(rule) {
   return `${rule.tier}: model ${rule.model}${rule.effort ? `, reasoning_effort ${rule.effort}` : ''}. ${sharedRuleBounds(rule)}`.trim();
 }
@@ -307,7 +353,7 @@ function customRole(role, root, home) {
 // Kept for Codex versions that do send spawn_agent through PreToolUse; on
 // 0.159.2 the hook never fires for it, so codexRouteHint above is the live path.
 export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules: given, dir = userDataDir(), record = recordCodexDelegation } = {}) {
-  if (cfg.codex?.delegate !== true) return null;
+  if (!codexDelegateEnabled(cfg)) return null;
   const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');
   if (!['spawn_agent', 'Agent'].includes(tool)) return null;
   const input = payload.tool_input;

package/src/codex-doc2md-ledger.js

@@ -5,43 +5,88 @@ import { codexUserDir } from './agent.js';
 import { userDataDir } from './paths.js';
 import { writeViaTmp } from './state-file.js';
 import { readResetMarks, isBeforeReset } from './saved-reset.cjs';
+import { codexPriceBook, readCodexPrices } from './codex-cache-policy.js';
 
 const hash = (value) => createHash('sha256').update(value).digest('hex');
 const ledgerDir = ({ home = codexUserDir(), dir = userDataDir() } = {}) => join(dir, 'codex-doc2md', hash(resolve(home)));
 const finite = (n) => Number.isSafeInteger(n) && n >= 0;
 
+/** Office XML versus the prepared Markdown, not native attachment billing. */
+export function estimateCodexDocument(source, meta, { model, provider, home, dir, now = Date.now(), prices } = {}) {
+  const unknown = (reason) => ({ usd: null, reason });
+  if (meta.clipped || meta.truncated) return unknown('incomplete-text');
+  if (!['.pptx', '.docx', '.xlsx'].includes(extname(source).toLowerCase()) || !finite(meta.markupBytes) || meta.markupBytes === 0) {
+    return unknown('no-comparable-baseline');
+  }
+  if (!finite(meta.markdownBytes)) return unknown('missing-markdown-size');
+  if (typeof model !== 'string' || !model || typeof provider !== 'string' || !provider) return unknown('unknown-model-provider');
+  const book = codexPriceBook(provider, prices === undefined ? readCodexPrices({ home, dir, now }) : prices, { home });
+  const rate = book?.prices?.[model]?.input;
+  if (!Number.isFinite(rate) || rate < 0) return unknown('unpriced-model');
+  const baseline = Math.ceil(meta.markupBytes / 4), tokens = Math.ceil(meta.markdownBytes / 4);
+  return { usd: (baseline - tokens) * rate, baseline, tokens, savedTokens: baseline - tokens,
+    method: 'office-xml-vs-markdown-bytes/4', model, provider, inputRate: rate,
+    priceSource: book.source, priceCheckedAt: book.checkedAt };
+}
+
 // One file per source avoids lost updates when parallel hooks prepare documents.
-export function recordCodexDocument(source, result, opts) {
+export function recordCodexDocument(source, result, opts = {}) {
   if (!result?.ok) return;
   try {
     const dir = ledgerDir(opts);
     const file = join(dir, `${hash(realpathSync(source))}.json`);
     const meta = result.meta || {};
-    const event = { version: 1, ext: extname(source).slice(1).toLowerCase(),
+    const now = opts.now ?? Date.now();
+    const st = statSync(source);
+    const fingerprint = hash(JSON.stringify([st.size, st.mtimeMs, meta.markupBytes, meta.markdownBytes, !!(meta.clipped || meta.truncated)]));
+    let previous;
+    try { previous = JSON.parse(readFileSync(file, 'utf8')); } catch { /* First use. */ }
+    const same = previous?.version === 2 && previous.fingerprint === fingerprint;
+    const since = readResetMarks(opts.dir ?? userDataDir())['codex-docs'];
+    const estimate = estimateCodexDocument(source, meta, opts);
+    // Reusing a cache without session identity must not erase a priced snapshot.
+    const saving = same && !isBeforeReset(previous.at, since) && Number.isFinite(previous.saving?.usd) ? previous.saving : estimate;
+    const event = { version: 2, ext: extname(source).slice(1).toLowerCase(),
+      fingerprint, at: same && !isBeforeReset(previous.at, since) ? previous.at : now, saving,
       sourceBytes: finite(meta.size) ? meta.size : null,
       markdownBytes: finite(meta.markdownBytes) ? meta.markdownBytes : null,
       clipped: !!(meta.clipped || meta.truncated) };
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const tmp = `${file}.${randomUUID()}.tmp`;
     writeViaTmp(tmp, file, JSON.stringify(event) + '\n', { mode: 0o600 });
+    return saving;
   } catch { /* Accounting must not prevent document conversion. */ }
 }
 
-// Records carry no timestamp field, so the reset mark is compared with the
-// file's mtime. A source converted again rewrites its record and counts as new.
-export function codexDocumentTotals(opts) {
+// Legacy records use mtime; new records retain their first priced observation.
+export function codexDocumentTotals(opts = {}) {
   const since = readResetMarks(opts?.dir ?? userDataDir())['codex-docs'];
-  const total = { docs: 0, byExt: [], scope: 'codex-total', since };
+  const now = opts.now ?? Date.now();
+  const savings = { week: 0, month: 0, total: 0, priced: 0, unpriced: 0, savedTokens: 0, reasons: {} };
+  const total = { docs: 0, byExt: [], scope: 'codex-total', since, savings };
   const byExt = new Map();
   try {
     const dir = ledgerDir(opts);
     for (const file of readdirSync(dir).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))) {
       try {
-        if (since !== null && isBeforeReset(statSync(join(dir, file)).mtimeMs, since)) continue;
         const event = JSON.parse(readFileSync(join(dir, file), 'utf8'));
-        if (event?.version !== 1 || !['pdf', 'pptx', 'xlsx', 'xls', 'docx', 'fig'].includes(event.ext)) continue;
+        if (![1, 2].includes(event?.version) || !['pdf', 'pptx', 'xlsx', 'xls', 'docx', 'fig'].includes(event.ext)) continue;
+        const at = event.version === 2 ? event.at : statSync(join(dir, file)).mtimeMs;
+        if (isBeforeReset(at, since)) continue;
         total.docs++;
         byExt.set(event.ext, (byExt.get(event.ext) || 0) + 1);
+        const s = event.saving;
+        if (event.version === 2 && s?.method === 'office-xml-vs-markdown-bytes/4' && Number.isFinite(s.usd)) {
+          savings.priced++;
+          savings.total += s.usd;
+          savings.savedTokens += Number.isFinite(s.savedTokens) ? s.savedTokens : 0;
+          if (at <= now && now - at < 7 * 86400000) savings.week += s.usd;
+          if (at <= now && now - at < 30 * 86400000) savings.month += s.usd;
+        } else {
+          savings.unpriced++;
+          const reason = event.version === 1 ? 'legacy-record' : s?.reason || 'unknown';
+          savings.reasons[reason] = (savings.reasons[reason] || 0) + 1;
+        }
       } catch { /* Ignore only the damaged record. */ }
     }
   } catch { /* No Codex document history yet. */ }

package/src/codex-doc2md.js

@@ -1,14 +1,31 @@
 import { createRequire } from 'node:module';
-import { realpathSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { realpathSync, readFileSync, writeFileSync, renameSync, rmSync, openSync, readSync, closeSync } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { recordCodexDocument } from './codex-doc2md-ledger.js';
+import { readCodexSnapshot } from './codex-parser.js';
 
 const require = createRequire(import.meta.url);
 const doc2md = require('./doc2md.cjs');
 const lint = require('./korean-lint.cjs');
 const shellTools = new Set(['Bash', 'exec_command', 'shell_command', 'shell']);
 
+/** Hook identity, never the user's default model or another project's session. */
+export function codexDocumentContext(payload = {}) {
+  const snapshot = readCodexSnapshot(payload.transcript_path);
+  let provider, id, fd;
+  try {
+    fd = openSync(payload.transcript_path, 'r');
+    const buf = Buffer.alloc(65536);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    const first = JSON.parse(buf.subarray(0, n).toString('utf8').split('\n')[0]);
+    if (first.type === 'session_meta') { provider = first.payload?.model_provider; id = first.payload?.id || first.payload?.session_id; }
+  } catch { /* Payload identity may still be complete. */ }
+  finally { if (fd !== undefined) closeSync(fd); }
+  if (id && payload.session_id && id !== payload.session_id) return {};
+  return { model: payload.model || snapshot?.model, provider: payload.model_provider || provider || snapshot?.provider };
+}
+
 function canonicalPath(file) {
   const missing = [];
   for (let current = file; ; current = dirname(current)) {
@@ -47,8 +64,8 @@ export function convertCodexDocument(source, { convert = doc2md.convert, ...opts
       tmp = null;
     }
     const { savedUsd, baselineTokens, ...meta } = result.meta || {};
-    const prepared = { ...result, cacheFile, meta };
-    recordCodexDocument(source, prepared, opts);
+    const prepared = { ...result, cacheFile, meta: { ...meta, markdownBytes: Buffer.byteLength(text, 'utf8') } };
+    prepared.meta.codexSaving = recordCodexDocument(source, prepared, opts);
     return prepared;
   } catch {
     return { ok: false, reason: 'cache-unavailable' };
@@ -87,7 +104,7 @@ export function codexDocumentTool(payload, { convert = convertCodexDocument, gua
     if (match) file = match[1] || match[2] || match[3];
   }
   if (typeof file !== 'string' || !doc2md.isTargetPath(file)) return null;
-  const result = convert(resolve(cwd, file));
+  const result = convert(resolve(cwd, file), codexDocumentContext(payload));
   if (!result.ok) return { hookSpecificOutput: { hookEventName: 'PreToolUse',
     ...(result.reason === 'unsafe-archive' ? { permissionDecision: 'deny', permissionDecisionReason: '[doc2md] Unsafe archive; do not extract it.' }
       : { additionalContext: `[doc2md] Conversion failed (${result.reason}). Do not claim this document was converted. ${codexDocumentNote()}` }) } };

package/src/codex-doctor.js

@@ -15,13 +15,18 @@ export const CODEX_CAPABILITIES = [
   { feature: 'history', support: 'supported', command: 'sprag history --agent codex', note: 'Codex-only records of context (80%/95%) and 5h/weekly rate-limit (90%) warnings, plus handoffs. Cache and TTL chips are not recorded; last shows the latest event.' },
   { feature: 'handoff', support: 'supported', command: 'sprag handoff --agent codex', note: 'Git state and recorded Codex session usage; never reads Claude caps.' },
   { feature: 'korean', support: 'supported', command: 'sprag korean status --agent codex', note: 'Session guidance and recognized write-target lint; shared preference.' },
+  { feature: 'reply-language', support: 'supported', command: 'sprag korean reply on --agent codex', note: 'Trusted Stop hook checks the current Korean prompt and final reply; continuation, opt-out and explicit English requests are excluded.' },
   { feature: 'cohesion', support: 'supported', command: 'sprag cohesion status --agent codex', note: 'Shared English guidance preference.' },
   { feature: 'doc2md', support: 'supported', command: 'sprag doc2md status --agent codex', note: 'Shared converter, prompt paths, supported file reads, and recognized document/cache write guards; not arbitrary shell extraction.' },
+  { feature: 'doc2md-saved', support: 'partial', command: 'sprag doc2md savings --agent codex', note: 'Office XML versus Markdown bytes/4 at the recorded Codex input price. Estimate only; incomplete or unsupported baselines and missing prices stay unknown.' },
+  { feature: 'delegation-diagnostics', support: 'supported', command: 'sprag delegate doctor --agent codex', note: 'Local feature/catalog and matched-child evidence. Never claims that an enabled preference proves native tools are available.' },
   { feature: 'delegate', support: 'supported', command: 'sprag delegate on --agent codex', note: 'Native routing and shared delegation policies; tier models resolve from priced models already run in Codex, or from explicit mappings. Explicit models/custom roles preserved; bounds are guidance, not enforced limits.' },
   { feature: 'routing-saved', support: 'partial', command: 'sprag route-scan savings --agent codex', note: 'Sprag-routed child usage with matching LiteLLM prices; counterfactual estimate, not billed savings. Unpriced runs stay unknown.' },
   { feature: 'cache-timer', support: 'partial', command: 'sprag cache status --refresh --agent codex', note: 'Documented minimum retention after recorded cache usage; LiteLLM deployments resolved through model/info. Unknown routes show age; exact expiry is not reported.' },
   { feature: 'mode', support: 'partial', command: 'sprag mode --agent codex', note: 'Labels, color, and timer apply to panel/statusline; Claude TTL buckets do not.' },
   { feature: 'upgrade', support: 'manual', command: 'sprag upgrade --print --agent codex', note: 'Skip the Claude npm postinstall; reinstall Codex hooks after upgrade.' },
+  { feature: 'update-notice', support: 'supported', command: 'sprag update-check --agent codex', note: 'Live panel refreshes in the background; one-shot statusline reads cached state; interactive SessionStart offers upgrades with consent.' },
+  { feature: 'implementation-delegation', support: 'supported', command: 'sprag delegate implementation --agent codex --from MODEL --provider PROVIDER --session ID', note: 'Main agent designs and verifies; implementation uses resolved T1 only. Requires native subagent tools and records only matched child runs.' },
   { feature: 'route-scan', support: 'supported', command: 'sprag route-scan --agent codex', note: 'Recurring simple turns grouped by project, provider, and parent model; explicit approval before routing.' },
   { feature: 'seed', support: 'supported', command: 'sprag seed --agent codex', note: 'Shared delegation policies plus agent-compatible ratchet presets. Explicit scope; tier models resolve automatically or by mapping. No Claude installation needed.' },
   { feature: 'transcript ratchet', support: 'supported', command: 'sprag --statusline --agent codex', note: 'Recent repeated tool failures become ratchet? candidates; no automatic rule registration.' },
@@ -37,6 +42,8 @@ export async function codexDoctor({ root = process.cwd(), sessionId, days = 7 }
     const cfg = config.present ? parse(readFileSync(file, 'utf8')) : {};
     // Only expose an allowlist. Provider auth and arbitrary config may hold secrets.
     config.hooksDisabled = cfg.features?.hooks === false || (cfg.features?.hooks === undefined && cfg.features?.codex_hooks === false);
+    config.agentsDisabled = cfg.agents?.enabled === false || cfg.features?.multi_agent === false;
+    config.agentsMaxThreads = cfg.agents?.max_concurrent_threads_per_session ?? cfg.agents?.max_threads ?? null;
     config.statusLine = Array.isArray(cfg.tui?.status_line) ? cfg.tui.status_line.filter((item) => typeof item === 'string') : null;
     config.autoCompactTokenLimit = Number.isFinite(cfg.model_auto_compact_token_limit) ? cfg.model_auto_compact_token_limit : null;
     config.note = 'User config only; active profile, project, managed policy, and runtime overrides may differ.';
@@ -49,5 +56,6 @@ export async function codexDoctor({ root = process.cwd(), sessionId, days = 7 }
     lastActivity: data.session.lastActivity, usageUpdates: data.session.requestCount } : null;
   return { agent: 'codex', home, root, config, hooks, harness: data.harness, rules: data.rules,
     preferences: { korean: data.korean, lint: data.lint, cohesion: data.cohesion, doc2md: data.doc2md, brief: data.brief, delegate: data.delegate },
-    session, panel: panelHealth(root, { sessionId }), capabilities: CODEX_CAPABILITIES };
+    session, delegation: { ...data.delegation, tools: 'unknown; only the running agent can confirm spawn_agent and wait_agent availability' },
+    documents: data.documents, routingSaved: data.routingSaved, panel: panelHealth(root, { sessionId }), capabilities: CODEX_CAPABILITIES };
 }