sprag-cli 3.53.0 → 3.54.0

package/src/codex-budget.js

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { parse } from 'smol-toml';
+import { codexUserDir } from './agent.js';
+import { pickBudgetSource } from './litellm-budget.js';
+
+const run = promisify(execFile);
+
+export function codexBudgetProvider({ home = codexUserDir(), env = process.env, providerName } = {}) {
+  try {
+    const cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8'));
+    const profile = cfg.profiles?.[cfg.profile] || {};
+    const name = providerName || profile.model_provider || cfg.model_provider;
+    const provider = cfg.model_providers?.[name];
+    if (!provider || !/litellm/i.test(`${name} ${provider.name || ''}`)) return null;
+    const url = new URL(provider.base_url);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) return null;
+    url.pathname = url.pathname.replace(/\/v1\/?$/, '').replace(/\/$/, '');
+    url.search = ''; url.hash = '';
+    return { name, base: url.toString().replace(/\/$/, ''),
+      key: provider.env_key ? env[provider.env_key] : null,
+      command: provider.auth?.command,
+      args: provider.auth?.args || [] };
+  } catch { return null; }
+}
+
+export async function codexProviderKey(provider, { execute = run } = {}) {
+  let key = provider.key;
+  if (!key && typeof provider.command === 'string') {
+    try {
+      const result = await execute(provider.command, provider.args, { encoding: 'utf8', timeout: 10000, maxBuffer: 64 * 1024 });
+      key = result.stdout.trim().split(/\r?\n/).filter(Boolean).pop();
+    } catch { throw new Error('Codex provider authentication helper failed'); }
+  }
+  if (!key) throw new Error('Codex provider credentials unavailable');
+  return key;
+}
+
+export async function fetchCodexBudget(provider, { fetchImpl = fetch, execute = run, now = Date.now() } = {}) {
+  const key = await codexProviderKey(provider, { execute });
+  // Tokens stay in memory and headers, never in argv, state files or errors.
+  const headers = { authorization: `Bearer ${key}`, accept: 'application/json' };
+  const get = async (path) => {
+    try {
+      const res = await fetchImpl(`${provider.base}${path}`, { headers, signal: AbortSignal.timeout(5000), redirect: 'error' });
+      return res.ok ? await res.json() : null;
+    } catch { return null; }
+  };
+  const [keyResponse, userResponse] = await Promise.all([get('/key/info'), get('/user/info')]);
+  if (!keyResponse && !userResponse) throw new Error('LiteLLM budget endpoints unavailable');
+  const budget = pickBudgetSource(keyResponse?.info, userResponse);
+  return budget ? { ...budget, checkedAt: now } : null;
+}
+
+// Refresh between frames without delaying terminal paint. Cache no credentials.
+export function createCodexBudgetReader({ provider = codexBudgetProvider, fetchBudget = fetchCodexBudget, now = Date.now } = {}) {
+  let base, snapshot = null, pending = false, checked = -Infinity;
+  return function read() {
+    const cfg = provider();
+    if (!cfg) { base = null; snapshot = null; return null; }
+    if (cfg.base !== base) { base = cfg.base; snapshot = null; checked = -Infinity; }
+    if (!pending && now() - checked >= 300000) {
+      checked = now(); pending = true;
+      const requestedBase = base;
+      Promise.resolve().then(() => fetchBudget(cfg)).then((value) => {
+        if (base === requestedBase) snapshot = value;
+      }).catch(() => {}).finally(() => { pending = false; });
+    }
+    return snapshot;
+  };
+}

package/src/codex-cache-policy.js

@@ -0,0 +1,203 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { parse } from 'smol-toml';
+import { codexUserDir } from './agent.js';
+import { userDataDir } from './paths.js';
+import { codexBudgetProvider, codexProviderKey } from './codex-budget.js';
+import { codexCachePolicy } from './codex-cache.js';
+
+export const CACHE_POLICY_MAX_AGE_MS = 300000;
+const OPENAI_POLICY = 'https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime';
+const BEDROCK_POLICY = 'https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-openai';
+
+function deploymentPolicy(row) {
+  const params = row?.litellm_params || {}, info = row?.model_info || {};
+  const route = typeof params.model === 'string' ? params.model : '';
+  const base = typeof info.base_model === 'string' ? info.base_model : route;
+  const backend = /^bedrock(?:\/|_mantle\/)/.test(route) ? 'Bedrock'
+    : /^(?:openai\/)?gpt-/.test(route) ? 'OpenAI' : null;
+  if (!backend || info.supports_prompt_caching === false) return null;
+  // An OpenAI-compatible server is not necessarily OpenAI, even with a GPT alias.
+  if (backend === 'OpenAI' && params.api_base) {
+    try { if (new URL(params.api_base).hostname !== 'api.openai.com') return null; }
+    catch { return null; }
+  }
+  const model = backend === 'Bedrock'
+    ? base.replace(/^bedrock(?:\/converse)?\//, '').replace(/^bedrock_mantle\//, '').replace(/^(?:(?:global|us|eu|apac)\.)?openai\./, '')
+    : route.replace(/^openai\//, '');
+  const seconds = codexCachePolicy(model);
+  if (!seconds) return null;
+  const options = params.prompt_cache_options;
+  if (options != null && (typeof options !== 'object' || Array.isArray(options))) return null;
+  if (options?.ttl != null && options.ttl !== '30m') return null;
+  if (options?.mode != null && !['implicit', 'explicit'].includes(options.mode)) return null;
+  if (params.prompt_cache_retention != null) return null;
+  return { backend, model, seconds, mode: options?.mode || 'implicit',
+    reference: backend === 'Bedrock' ? BEDROCK_POLICY : OPENAI_POLICY };
+}
+
+export function gatewayCachePolicies(payload) {
+  if (!Array.isArray(payload?.data)) throw new Error('LiteLLM model/info returned no model list');
+  const groups = new Map();
+  for (const row of payload.data) {
+    if (typeof row?.model_name !== 'string' || row.model_name.length > 256) continue;
+    const group = groups.get(row.model_name) || [];
+    group.push(deploymentPolicy(row));
+    groups.set(row.model_name, group);
+  }
+  // All deployments behind an alias must agree; load balancing must not change TTL.
+  return Object.fromEntries([...groups].map(([name, policies]) => [name,
+    policies[0] && policies.every((p) => JSON.stringify(p) === JSON.stringify(policies[0])) ? policies[0] : null]));
+}
+
+export const PRICE_MAX_AGE_MS = 7 * 86400000;
+const rate = (value) => Number.isFinite(value) && value >= 0 && value < 1 ? value : null;
+
+function deploymentPrice(row) {
+  const info = row?.model_info || {};
+  const mode = typeof info.mode === 'string' ? info.mode : null;
+  if (mode && !['chat', 'responses', 'completion'].includes(mode)) return null;
+  const input = rate(info.input_cost_per_token), output = rate(info.output_cost_per_token);
+  if (input === null || output === null) return null;
+  return { input, output, cacheRead: rate(info.cache_read_input_token_cost), cacheWrite: rate(info.cache_creation_input_token_cost) };
+}
+
+/** Per-token prices by alias. Load-balanced deployments must agree, like cache policy. */
+export function gatewayPrices(payload) {
+  if (!Array.isArray(payload?.data)) throw new Error('LiteLLM model/info returned no model list');
+  const groups = new Map();
+  for (const row of payload.data) {
+    if (typeof row?.model_name !== 'string' || row.model_name.length > 256) continue;
+    groups.set(row.model_name, [...(groups.get(row.model_name) || []), deploymentPrice(row)]);
+  }
+  return Object.fromEntries([...groups].map(([name, prices]) => [name,
+    prices[0] && prices.every((p) => JSON.stringify(p) === JSON.stringify(prices[0])) ? prices[0] : null]));
+}
+
+/**
+ * USD for a token mix at one model's prices, or null when a needed rate is
+ * missing. Cached input without a cache-read rate is unknown, not free.
+ */
+export function codexRunCost({ input = 0, cached = 0, cacheWrite = 0, output = 0 }, price) {
+  if (!price || price.input === null || price.output === null) return null;
+  if (cached > 0 && price.cacheRead === null) return null;
+  // cache_write_input_tokens is billed at the creation rate when one is published, else as input.
+  const uncached = Math.max(0, input - cached - cacheWrite);
+  return uncached * price.input + cached * (price.cacheRead ?? 0) + cacheWrite * (price.cacheWrite ?? price.input) + output * price.output;
+}
+
+function cacheFile(provider, { home = codexUserDir(), dir = userDataDir() } = {}) {
+  const key = createHash('sha256').update(JSON.stringify([resolve(home), provider.name, provider.base])).digest('hex').slice(0, 24);
+  return join(dir, 'codex-cache-policy', `${key}.json`);
+}
+
+function gatewayProvider(session, opts) {
+  if (!session?.provider || session.provider === 'openai') return null;
+  return codexBudgetProvider({ ...opts, providerName: session.provider });
+}
+
+function directPolicy(session, { home = codexUserDir(), now = Date.now() } = {}) {
+  if (session?.provider !== 'openai' || !codexCachePolicy(session.model)) return null;
+  try {
+    let cfg = {};
+    try { cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8')); }
+    catch (e) { if (e.code !== 'ENOENT') return null; }
+    if (cfg.openai_base_url && new URL(cfg.openai_base_url).hostname !== 'api.openai.com') return null;
+  } catch { return null; }
+  return { backend: 'OpenAI', model: session.model, seconds: codexCachePolicy(session.model),
+    requestedModel: session.model, provider: session.provider, checkedAt: now, reference: OPENAI_POLICY };
+}
+
+function selectPolicy(snapshot, session, now) {
+  if (!Number.isFinite(snapshot?.checkedAt) || snapshot.checkedAt > now || now - snapshot.checkedAt >= CACHE_POLICY_MAX_AGE_MS) return null;
+  const policy = Object.hasOwn(snapshot.models || {}, session.model) ? snapshot.models[session.model] : null;
+  if (!policy || !['OpenAI', 'Bedrock'].includes(policy.backend) || policy.seconds !== codexCachePolicy(policy.model) || !policy.seconds) return null;
+  return { ...policy, requestedModel: session.model, provider: session.provider, checkedAt: snapshot.checkedAt };
+}
+
+/** Offline read for statuslines and diagnostics; no auth helper or network calls. */
+export function readCodexCachePolicy(session, opts = {}) {
+  const direct = directPolicy(session, opts);
+  if (direct) return direct;
+  const provider = gatewayProvider(session, opts);
+  if (!provider) return null;
+  try { return selectPolicy(JSON.parse(readFileSync(cacheFile(provider, opts), 'utf8')), session, opts.now ?? Date.now()); }
+  catch { return null; }
+}
+
+/**
+ * Offline price table for the configured gateway, from the snapshot the cache
+ * policy refresh writes. Prices change rarely, so a week-old table still counts;
+ * anything older reads as unknown rather than silently current.
+ */
+export function readCodexPrices({ provider, now = Date.now(), ...opts } = {}) {
+  provider ??= codexBudgetProvider(opts);
+  if (!provider) return null;
+  try {
+    const snapshot = JSON.parse(readFileSync(cacheFile(provider, opts), 'utf8'));
+    if (!Number.isFinite(snapshot?.checkedAt) || snapshot.checkedAt > now || now - snapshot.checkedAt > PRICE_MAX_AGE_MS) return null;
+    if (!snapshot.prices || typeof snapshot.prices !== 'object') return null;
+    return { checkedAt: snapshot.checkedAt, provider: provider.name, base: provider.base, prices: snapshot.prices };
+  } catch { return null; }
+}
+
+/** Fetch prices for the configured gateway without needing a session. */
+export async function refreshCodexPrices({ provider = codexBudgetProvider(), fetchImpl = fetch, execute, ...opts } = {}) {
+  if (!provider) throw new Error('No configured LiteLLM endpoint for Codex');
+  await writeGatewaySnapshot(provider, { fetchImpl, execute, ...opts });
+  return readCodexPrices({ provider, ...opts });
+}
+
+async function writeGatewaySnapshot(provider, { fetchImpl = fetch, execute, ...opts } = {}) {
+  const key = await codexProviderKey(provider, { execute });
+  let payload;
+  try {
+    const res = await fetchImpl(`${provider.base}/model/info`, {
+      headers: { authorization: `Bearer ${key}`, accept: 'application/json' },
+      signal: AbortSignal.timeout(5000), redirect: 'error',
+    });
+    if (!res.ok) throw new Error();
+    payload = await res.json();
+  } catch { throw new Error('LiteLLM model/info unavailable; cache policy was not verified'); }
+  const now = opts.now ?? Date.now();
+  let prices = null;
+  try { prices = gatewayPrices(payload); } catch { /* Prices are optional; the policy stands alone. */ }
+  const snapshot = { checkedAt: now, models: gatewayCachePolicies(payload), prices };
+  const file = cacheFile(provider, opts);
+  // Persist only policy and price fields, never raw model/info (which can contain secrets).
+  mkdirSync(join(opts.dir || userDataDir(), 'codex-cache-policy'), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(snapshot) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+  return snapshot;
+}
+
+export async function refreshCodexCachePolicy(session, { fetchImpl = fetch, execute, ...opts } = {}) {
+  const direct = directPolicy(session, opts);
+  if (direct) return direct;
+  const provider = gatewayProvider(session, opts);
+  if (!provider) throw new Error('No configured LiteLLM endpoint for this session provider');
+  const snapshot = await writeGatewaySnapshot(provider, { fetchImpl, execute, ...opts });
+  return selectPolicy(snapshot, session, snapshot.checkedAt);
+}
+
+/** Refresh between frames. Each provider/model has its own in-flight lookup. */
+export function createCodexCachePolicyReader({ refresh = refreshCodexCachePolicy, now = Date.now, ...opts } = {}) {
+  const attempts = new Map();
+  return function read(session) {
+    const at = now();
+    const policy = readCodexCachePolicy(session, { ...opts, now: at });
+    if (policy || !session) return policy;
+    const provider = gatewayProvider(session, opts);
+    if (!provider) return null;
+    const key = JSON.stringify([provider.name, provider.base, session.model]);
+    const last = attempts.get(key);
+    if (!last || (!last.pending && at - last.at >= CACHE_POLICY_MAX_AGE_MS)) {
+      const attempt = { at, pending: true };
+      attempts.set(key, attempt);
+      Promise.resolve().then(() => refresh(session, { ...opts, now: at })).catch(() => {}).finally(() => { attempt.pending = false; });
+    }
+    return null;
+  };
+}

package/src/codex-cache.js

@@ -0,0 +1,46 @@
+// Minimum retention windows, not exact expiration timestamps. Gateway aliases
+// require a resolved deployment before applying a provider's documented policy.
+// https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime
+export function codexCachePolicy(model) {
+  return /^gpt-(?:5\.6(?:-(?:sol|terra|luna))?|6-(?:astra|sol|luna))(?:-\d{4}-\d{2}-\d{2})?$/i.test(model || '') ? 1800 : null;
+}
+
+export function parseCodexCacheTtl(value) {
+  if (value === 'auto' || value === 'off') return value;
+  const match = /^(\d+)(m|h)$/.exec(value || '');
+  const seconds = match ? Number(match[1]) * (match[2] === 'h' ? 3600 : 60) : NaN;
+  if (!Number.isSafeInteger(seconds) || seconds < 60 || seconds > 86400) {
+    throw new Error('Cache TTL expects auto, off, or 1m through 24h (for example 30m). This changes the display estimate, not provider retention.');
+  }
+  return seconds;
+}
+
+export function codexCacheTimer(session, { now = Date.now(), ttl = 'auto', policy } = {}) {
+  if (ttl === 'off') return null;
+  const activity = session?.cacheActivity;
+  const at = activity?.at ? new Date(activity.at).getTime() : NaN;
+  const sameModel = activity?.model === session?.model;
+  if (!Number.isFinite(at) || at > now || !sameModel || activity?.provider !== session?.provider) {
+    return { text: 'Cache timer n/a', tone: 90, source: 'unavailable' };
+  }
+  const elapsed = Math.floor((now - at) / 1000);
+  const configured = Number.isSafeInteger(ttl) && ttl >= 60 && ttl <= 86400;
+  const resolved = policy && policy.requestedModel === session.model && policy.provider === session.provider &&
+    ['OpenAI', 'Bedrock'].includes(policy.backend) && policy.seconds === codexCachePolicy(policy.model) &&
+    Number.isFinite(policy.checkedAt) && now >= policy.checkedAt && now - policy.checkedAt < 300000;
+  const direct = policy === undefined && session.provider === 'openai' && codexCachePolicy(session.model);
+  const seconds = configured ? ttl : resolved ? policy.seconds : direct;
+  if (!seconds) return { text: `Cache age ${clock(elapsed)} / TTL unknown`, tone: 90, source: 'age', elapsed };
+  const remaining = Math.max(0, seconds - elapsed);
+  const source = configured ? 'configured estimate' : `${resolved ? policy.backend : 'OpenAI'} 30m`;
+  const text = remaining > 0 ? `Cache ${clock(remaining)} (${source})` : `Cache window elapsed (${source}; expiry unknown)`;
+  return { text, tone: remaining <= 0 ? 90 : remaining <= 60 ? 31 : remaining <= 300 ? 33 : 32,
+    source: configured ? 'configured' : 'provider-policy', seconds, elapsed, remaining };
+}
+
+function clock(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = seconds % 60;
+  return h ? `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}` : `${m}:${String(s).padStart(2, '0')}`;
+}

package/src/codex-delegation.js

@@ -0,0 +1,154 @@
+import { readFileSync, readdirSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parse } from 'smol-toml';
+import { userDataDir } from './paths.js';
+import { codexUserDir, codexProviderName } from './agent.js';
+import { categorize, ESCALATE_RE, EDIT_RE } from './route-scan.js';
+import { looksPasted } from './route-inject.js';
+import { newRouteId, recordCodexDelegation } from './codex-ledger.js';
+
+export const CODEX_ROUTE_CATEGORIES = ['paste', 'translate', 'explore', 'read', 'check', 'run'];
+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);
+
+export function validateCodexTarget(model, effort) {
+  if (!safeId(model)) throw new Error('Provide a literal Codex model ID.');
+  if (!validEffort(effort)) {
+    throw new Error('Invalid reasoning effort; choose a value supported by the target model.');
+  }
+  return { model, ...(effort === undefined ? {} : { effort }) };
+}
+
+const rulesFile = (dir) => join(dir, 'codex-model-rules.json');
+export function loadCodexModelRules({ dir = userDataDir() } = {}) {
+  try {
+    const data = JSON.parse(readFileSync(rulesFile(dir), 'utf8'));
+    if (data?.version !== 1 || !Array.isArray(data.rules) || data.rules.some((r) => !r ||
+      !CODEX_ROUTE_CATEGORIES.includes(r.category) || !safeId(r.from) || !safeId(r.model) || r.from === r.model ||
+      !validEffort(r.effort) || r.status !== 'active' || !['global', 'project'].includes(r.scope) ||
+      (r.provider != null && !safeId(r.provider)) ||
+      (r.scope === 'project' ? typeof r.targetRoot !== 'string' || resolve(r.targetRoot) !== r.targetRoot : r.targetRoot !== null))) throw new Error();
+    return data.rules;
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw new Error('Cannot parse Codex model rules; file left unchanged.');
+  }
+}
+
+function saveRules(rules, dir) {
+  mkdirSync(dir, { recursive: true });
+  const file = rulesFile(dir), tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, rules }, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+export function addCodexModelRule({ category, model, effort, from, scope, root, provider }, { dir = userDataDir() } = {}) {
+  validateCodexTarget(model, effort);
+  if (!CODEX_ROUTE_CATEGORIES.includes(category)) throw new Error(`Category must be ${CODEX_ROUTE_CATEGORIES.join(', ')}`);
+  if (!safeId(from) || from === model) throw new Error('--from must name a different parent model.');
+  if (!['global', 'project'].includes(scope)) throw new Error('Choose --global or --project for the rule.');
+  if (provider != null && !safeId(provider)) throw new Error('Invalid Codex provider ID.');
+  const rules = loadCodexModelRules({ dir });
+  const targetRoot = scope === 'project' ? resolve(root) : null;
+  const rule = { category, model, effort, from, scope, targetRoot, ...(provider ? { provider } : {}), status: 'active', createdAt: new Date().toISOString() };
+  const old = rules.findIndex((r) => r.category === category && r.from === from && r.scope === scope && r.targetRoot === targetRoot && r.provider === provider);
+  if (old < 0) rules.push(rule); else rules[old] = rule;
+  saveRules(rules, dir);
+  return rule;
+}
+
+export function removeCodexModelRule(index, { dir = userDataDir() } = {}) {
+  const rules = loadCodexModelRules({ dir });
+  if (!Number.isSafeInteger(index) || index < 1 || index > rules.length) throw new Error('Unknown Codex rule index.');
+  rules.splice(index - 1, 1);
+  saveRules(rules, dir);
+}
+
+/**
+ * The category a prompt can be routed under at runtime, or null. The route
+ * scan counts episodes with this same gate, so a rule it proposes is one the
+ * prompt hook can actually match.
+ */
+export function codexPromptCategory(text) {
+  const prompt = typeof text === 'string' ? text.trim() : '';
+  if (prompt.length < 8 || ESCALATE_RE.test(prompt) || EDIT_RE.test(prompt) || /\b(?:implement|modify|fix|delete|push|commit)\b/i.test(prompt)) return null;
+  const category = categorize(prompt, null);
+  if (!category || (category.id === 'paste' && !looksPasted(prompt))) return null;
+  return category;
+}
+
+export function matchCodexModelRule(text, { model, root, provider = codexProviderName(), rules = loadCodexModelRules() } = {}) {
+  const category = codexPromptCategory(text);
+  if (!category) return null;
+  const usable = rules.filter((r) => r?.status === 'active' && r.category === category.id && r.from === model &&
+    (!r.provider || r.provider === provider) &&
+    safeId(r.model) && validEffort(r.effort) && r.model !== model && (r.scope === 'global' || (r.scope === 'project' && r.targetRoot === resolve(root || '.'))));
+  return usable.find((r) => r.scope === 'project') || usable[0] || null;
+}
+
+export function codexRouteHint(payload, opts = {}) {
+  const rule = matchCodexModelRule(payload?.prompt, { provider: payload?.model_provider || codexProviderName(), ...opts, model: payload?.model, root: opts.root || payload?.cwd });
+  if (!rule) return null;
+  return `[Sprag model routing] This request matches the approved ${rule.category} rule: delegate the bounded task to model ${rule.model}`
+    + (rule.effort ? ` with reasoning_effort ${rule.effort}` : '')
+    + '. Use the available native Codex subagent tool and a built-in role. Wait for its result, verify it, and report unfinished work. '
+    + 'Do not spawn another CLI process. If subagent tools or the target model are unavailable, keep the task on the main agent and state that delegation was unavailable.';
+}
+
+function customRole(role, root, home) {
+  // Custom role files override an explicit spawn model. Leave those calls alone.
+  const layers = new Set([home]);
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    layers.add(join(dir, '.codex'));
+    if (dirname(dir) === dir) break;
+  }
+  for (const layer of layers) {
+    try {
+      const cfg = parse(readFileSync(join(layer, 'config.toml'), 'utf8'));
+      if (Object.hasOwn(cfg.agents || {}, role)) return true;
+    } catch (e) { if (e.code !== 'ENOENT') return true; }
+    const dir = join(layer, 'agents');
+    let names;
+    try { names = readdirSync(dir); } catch (e) { if (e.code === 'ENOENT') continue; return true; }
+    for (const name of names.filter((n) => n.endsWith('.toml'))) {
+      try { if (parse(readFileSync(join(dir, name), 'utf8')).name === role) return true; }
+      catch { return true; }
+    }
+  }
+  return false;
+}
+
+export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules, dir = userDataDir(), record = recordCodexDelegation } = {}) {
+  if (cfg.codex?.delegate !== true) return null;
+  const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');
+  if (!['spawn_agent', 'Agent'].includes(tool)) return null;
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object' || Array.isArray(input) || typeof input.message !== 'string' || !input.message.trim() || input.message.includes(MARKER)) return null;
+  const role = input.agent_type || 'default';
+  if (!['default', 'worker', 'explorer'].includes(role) || customRole(role, payload.cwd || root, home)) return null;
+  const explicit = Object.hasOwn(input, 'model');
+  const provider = payload.model_provider || codexProviderName({ home });
+  const rule = explicit ? null : matchCodexModelRule(input.message, { model: payload.model, provider, root, rules });
+  const target = rule || (!explicit && cfg.codex?.delegateTarget);
+  const updatedInput = { ...input };
+  let routeLine = '';
+  if (target) {
+    validateCodexTarget(target.model, target.effort);
+    updatedInput.model = target.model;
+    if (target.effort !== undefined && !Object.hasOwn(input, 'reasoning_effort')) updatedInput.reasoning_effort = target.effort;
+    // Only a route Sprag applied, with a known parent, can be credited later.
+    if (safeId(payload.model) && payload.model !== target.model) {
+      const id = newRouteId();
+      try {
+        record({ id, parentSessionId: typeof payload.session_id === 'string' ? payload.session_id : null,
+          source: rule ? 'rule' : 'default', category: rule?.category ?? null, scope: rule?.scope ?? null,
+          from: payload.model, to: target.model, provider, effort: updatedInput.reasoning_effort ?? null }, { dir });
+        routeLine = `\n<!-- sprag:codex:route id=${id} -->`;
+      } catch { /* Accounting is optional; the route itself still applies. */ }
+    }
+  }
+  updatedInput.message += `\n\n${MARKER}${routeLine}\nStay within the assigned task and requested output shape. Back findings with file references or actual command results. State what you could not verify. Honor caller-provided limits; do not invent a budget or assume the parent's model tier. Stop and report partial work when a limit or unavailable dependency prevents completion. Do not recursively delegate this bounded task.`;
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', updatedInput } };
+}

package/src/codex-doc2md-ledger.js

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, realpathSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+import { codexUserDir } from './agent.js';
+import { userDataDir } from './paths.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;
+
+// One file per source avoids lost updates when parallel hooks prepare documents.
+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(),
+      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`;
+    writeFileSync(tmp, JSON.stringify(event) + '\n', { mode: 0o600 });
+    renameSync(tmp, file);
+  } catch { /* Accounting must not prevent document conversion. */ }
+}
+
+export function codexDocumentTotals(opts) {
+  const total = { docs: 0, byExt: [], scope: 'codex-total' };
+  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 {
+        const event = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+        if (event?.version !== 1 || !['pdf', 'pptx', 'xlsx', 'xls', 'docx', 'fig'].includes(event.ext)) continue;
+        total.docs++;
+        byExt.set(event.ext, (byExt.get(event.ext) || 0) + 1);
+      } catch { /* Ignore only the damaged record. */ }
+    }
+  } catch { /* No Codex document history yet. */ }
+  total.byExt = [...byExt].map(([ext, docs]) => ({ ext, docs })).sort((a, b) => b.docs - a.docs || a.ext.localeCompare(b.ext));
+  return total;
+}

package/src/codex-doc2md.js

@@ -0,0 +1,99 @@
+import { createRequire } from 'node:module';
+import { realpathSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { recordCodexDocument } from './codex-doc2md-ledger.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']);
+
+function canonicalPath(file) {
+  const missing = [];
+  for (let current = file; ; current = dirname(current)) {
+    try { return resolve(realpathSync(current), ...missing.reverse()); }
+    catch (e) { if (!['ENOENT', 'ENOTDIR'].includes(e.code) || dirname(current) === current) return file; }
+    missing.push(basename(current));
+  }
+}
+
+export function codexDocumentNote() {
+  return '[Sprag Doc2md]\nBefore reading PDF, Office, or Figma documents, run sprag doc2md <path> --agent codex and read the resulting Markdown. '
+    + 'Conversions are one-way: never edit the cached Markdown. To modify a document, copy the original and edit the copy with a format-aware library, then reconvert it to verify the text. '
+    + 'Text extraction does not verify charts, images, or layout. Report conversion failures and do not claim visual verification from text alone.';
+}
+
+export function convertCodexDocument(source, { convert = doc2md.convert, ...opts } = {}) {
+  let result;
+  try { result = convert(source, { agent: 'codex' }); }
+  catch { return { ok: false, reason: 'convert-failed' }; }
+  if (!result?.ok) return result || { ok: false, reason: 'convert-failed' };
+  let tmp;
+  try {
+    // Existing shared caches can carry Claude attachment baselines and prices.
+    // Keep their body, but give Codex a separate view with neutral provenance.
+    const original = readFileSync(result.cacheFile, 'utf8');
+    const end = original.startsWith('<!--\nsprag doc2md') ? original.indexOf('\n-->\n') : -1;
+    const body = end >= 0 ? original.slice(end + 5) : original;
+    const cacheFile = result.cacheFile.replace(/\.md$/, '.codex.md');
+    const text = `<!--\nsprag doc2md: generated Markdown; do not edit.\nSource: ${JSON.stringify(resolve(source))}\nText extraction does not verify images or layout.\n-->\n${body}`;
+    let previous;
+    try { previous = readFileSync(cacheFile, 'utf8'); } catch { /* First Codex use. */ }
+    if (previous !== text) {
+      tmp = `${cacheFile}.${randomUUID()}.tmp`;
+      writeFileSync(tmp, text, { mode: 0o600 });
+      renameSync(tmp, cacheFile);
+      tmp = null;
+    }
+    const { savedUsd, baselineTokens, ...meta } = result.meta || {};
+    const prepared = { ...result, cacheFile, meta };
+    recordCodexDocument(source, prepared, opts);
+    return prepared;
+  } catch {
+    return { ok: false, reason: 'cache-unavailable' };
+  } finally {
+    if (tmp) { try { rmSync(tmp, { force: true }); } catch { /* Best-effort temporary file cleanup. */ } }
+  }
+}
+
+/** Adapt supported Codex calls to the shared converter and write guard. */
+export function codexDocumentTool(payload, { convert = convertCodexDocument, guard = doc2md.decideForWrite } = {}) {
+  const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');
+  const input = payload?.tool_input;
+  const command = typeof input === 'string' ? input : input?.command ?? input?.cmd ?? input?.content ?? input?.patch;
+  const cwd = resolve(payload?.cwd || process.cwd(), typeof input?.workdir === 'string' ? input.workdir : '.');
+  let writes = [];
+  if (tool === 'apply_patch' && typeof command === 'string' && command.startsWith('*** Begin Patch')) {
+    writes = [...command.matchAll(/^\*\*\* (?:Add File|Update File|Move to): (.+)\r?$/gm)].map((m) => m[1].trimEnd());
+  } else if (['Edit', 'Write'].includes(tool) && typeof input?.file_path === 'string') writes = [input.file_path];
+  else if (shellTools.has(tool)) writes = lint.writtenPathsOfBash(command);
+  for (const path of writes) {
+    const file = resolve(cwd, path);
+    const canonical = canonicalPath(file);
+    for (const target of new Set([file, canonical])) {
+      const decision = guard({ tool_name: 'Write', tool_input: { file_path: target } }, { agent: 'codex' });
+      if (decision?.deny) return { hookSpecificOutput: { hookEventName: 'PreToolUse',
+        permissionDecision: 'deny', permissionDecisionReason: decision.reason } };
+    }
+  }
+
+  let file;
+  if (['Read', 'read_file', 'mcp__filesystem__read_file', 'mcp__filesystem__read_text_file'].includes(tool)) {
+    file = input?.file_path ?? input?.path;
+  } else if (shellTools.has(tool) && typeof command === 'string') {
+    // Only literal, single-file reads. Compound commands and expansions stay untouched.
+    const match = /^(?:cat\s+(?:--\s+)?|(?:head|tail)\s+(?:-n\s+\d+\s+)?)(?:"([^"$`\n]+)"|'([^'\n]+)'|([^\s'"`$;&|<>*?(){}\\]+))\s*$/.exec(command.trim());
+    if (match) file = match[1] || match[2] || match[3];
+  }
+  if (typeof file !== 'string' || !doc2md.isTargetPath(file)) return null;
+  const result = convert(resolve(cwd, file));
+  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()}` }) } };
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny',
+    permissionDecisionReason: `[doc2md] Read the converted Markdown at ${JSON.stringify(result.cacheFile)} instead of extracting ${JSON.stringify(file)} again. `
+      + `Source ${result.meta?.size ?? 'unknown'} bytes; Markdown ${result.meta?.markdownBytes ?? 'unknown'} bytes.`
+      + (result.meta?.clipped ? ' The conversion is clipped; it is not the complete document.'
+        : result.meta?.truncated ? ' Text extraction is incomplete; it is not the complete document.' : '') } };
+}