sprag-cli 3.53.0 → 3.55.0

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.' : '') } };
+}

package/src/codex-doctor.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'smol-toml';
+import { codexUserDir } from './agent.js';
+import { codexHookStatus } from './codex-installer.js';
+import { createPanelReader } from './codex-panel.js';
+import { panelHealth } from './codex-panel-state.js';
+
+export const CODEX_CAPABILITIES = [
+  { feature: 'statusline', support: 'supported', command: 'sprag --statusline --agent codex', note: 'Local terminal output; native footer accepts only Codex item identifiers.' },
+  { feature: 'panel', support: 'supported', command: 'sprag panel --agent codex', note: 'Local logs; tmux inline layout; optional macOS window.' },
+  { feature: 'reports', support: 'supported', command: 'sprag --agent codex --format json', note: 'Token usage, cached input, reasoning, session and project filters.' },
+  { feature: 'harness', support: 'supported', command: 'sprag harness check --agent codex', note: 'AGENTS.md, overrides, explicit-scope ratchet rule management.' },
+  { feature: 'brief', support: 'supported', command: 'sprag brief --agent codex', note: 'Fresh context and limit warnings; change-triggered prompt hook.' },
+  { feature: 'history', support: 'supported', command: 'sprag history --agent codex', note: 'Codex-only session warning records; last shows the latest warning.' },
+  { 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: '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: 'delegate', support: 'supported', command: 'sprag delegate on --agent codex', note: 'Opt-in native spawn model routing, scoped category rules, and SubagentStart guidance. Explicit models/custom roles preserved; no enforced budget.' },
+  { 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: '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: 'Agent-compatible ratchet presets; separate decisions and explicit scope. No Claude tier presets.' },
+  { feature: 'transcript ratchet', support: 'supported', command: 'sprag --statusline --agent codex', note: 'Recent repeated tool failures become ratchet? candidates; no automatic rule registration.' },
+  { feature: 'compact-window', support: 'native', note: 'Codex uses model_auto_compact_token_limit; no Claude autoCompactWindow heuristic.' },
+  { feature: 'cost / exact cache expiry', support: 'unavailable', note: 'Not measured in rollout logs; never estimated with Anthropic prices.' },
+];
+
+export async function codexDoctor({ root = process.cwd(), sessionId, days = 7 } = {}) {
+  const home = codexUserDir();
+  const file = join(home, 'config.toml');
+  const config = { file, present: existsSync(file) };
+  try {
+    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.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.';
+  } catch { config.error = 'Cannot parse user config.toml; file left unchanged.'; }
+  let hooks;
+  try { hooks = { file: join(home, 'hooks.json'), events: codexHookStatus(), trust: 'unknown; review in Codex /hooks' }; }
+  catch { hooks = { error: 'Cannot parse Codex hooks.json; file left unchanged.', events: [] }; }
+  const data = await createPanelReader({ root, sessionId, days })();
+  const session = data.session ? { id: data.session.sessionId, model: data.session.model,
+    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 };
+}

package/src/codex-harness.js

@@ -0,0 +1,200 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { codexUserDir } from './agent.js';
+import { codexToolEvents, codexLegacyToolEvent, readCodexTailLines } from './codex-parser.js';
+
+export const CODEX_BEGIN = '<!-- sprag:codex:harness:begin -->';
+export const CODEX_END = '<!-- sprag:codex:harness:end -->';
+const sections = [
+  ['Ratchet', 'When a mistake recurs, propose a concise condition/action rule. Ask the user for global or project scope before registering it with `sprag harness promote --agent codex --global|--project "rule"`.'],
+  ['Evidence', 'Support completion claims with actual test results, command output, a file diff, or a screenshot. State any verification you could not run.'],
+  ['Plan, Execute, Verify', 'For multi-step work, plan the steps, execute them, and verify the result before reporting completion.'],
+  ['Structured Task', 'Establish the goal, constraints, verification method, and completion criteria before substantial work.'],
+  ['Default Safe Path', 'Ask before destructive or external actions unless already authorized. Proceed with reads, local edits, and tests within the granted permissions.'],
+];
+
+export function codexHarnessPaths(root, scope = 'project') {
+  const dir = scope === 'global' ? codexUserDir() : root;
+  // Codex reads the override instead of AGENTS.md when it is non-empty.
+  const override = join(dir, 'AGENTS.override.md');
+  const file = existsSync(override) && readFileSync(override, 'utf8').trim() ? override : join(dir, 'AGENTS.md');
+  return { file, ratchet: scope === 'global' ? join(dir, 'ratchet.md') : join(dir, '.codex', 'ratchet.md') };
+}
+
+export function codexHarnessBlock() {
+  return `${CODEX_BEGIN}\n## Sprag Harness\n\n${sections.map(([name, text], i) => `### ${i + 1}. ${name}\n${text}`).join('\n\n')}\n\nRead the global and project Codex ratchet files before working when present. Run \`sprag harness list --agent codex --global\` and \`sprag harness list --agent codex --project\` to retrieve them. These are instructions, not Claude-style @ imports.\nUse \`sprag doc2md <file> --agent codex\` before reading PDF, Office, or Figma documents. Delegate only through available Codex tools and configured roles; do not assume Claude model names or Task/Agent arguments.\n${CODEX_END}\n`;
+}
+
+function range(content) {
+  const begin = content.indexOf(CODEX_BEGIN);
+  const end = content.indexOf(CODEX_END);
+  if ((begin < 0) !== (end < 0) || (begin >= 0 && end < begin) || content.indexOf(CODEX_BEGIN, begin + CODEX_BEGIN.length) >= 0) {
+    throw new Error('Malformed Sprag Codex harness markers; repair them before updating this file.');
+  }
+  return begin < 0 ? null : [begin, end + CODEX_END.length];
+}
+
+export function initCodexHarness({ root, scope = 'project' }) {
+  const paths = codexHarnessPaths(root, scope);
+  const existing = existsSync(paths.file) ? readFileSync(paths.file, 'utf8') : '';
+  const span = range(existing);
+  const block = codexHarnessBlock();
+  const next = span ? existing.slice(0, span[0]) + block.trimEnd() + existing.slice(span[1])
+    : existing + (existing ? '\n\n' : '') + block;
+  mkdirSync(dirname(paths.file), { recursive: true });
+  if (next !== existing) {
+    if (existing) writeFileSync(`${paths.file}.bak-${Date.now()}`, existing);
+    writeFileSync(paths.file, next);
+  }
+  if (!existsSync(paths.ratchet)) {
+    mkdirSync(dirname(paths.ratchet), { recursive: true });
+    writeFileSync(paths.ratchet, '# Codex Ratchet Rules\n\n## Rules\n\n');
+  }
+  return paths;
+}
+
+export function uninitCodexHarness({ root, scope = 'project' }) {
+  const { file } = codexHarnessPaths(root, scope);
+  if (!existsSync(file)) return { file, removed: false };
+  const existing = readFileSync(file, 'utf8');
+  const span = range(existing);
+  if (!span) return { file, removed: false };
+  writeFileSync(`${file}.bak-${Date.now()}`, existing);
+  writeFileSync(file, existing.slice(0, span[0]) + existing.slice(span[1]));
+  return { file, removed: true };
+}
+
+export function codexHarnessStatus({ root, scope = 'project' }) {
+  const { file } = codexHarnessPaths(root, scope);
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const span = range(text);
+  const block = span ? text.slice(...span) : '';
+  const missing = sections.filter(([name], i) => !block.includes(`### ${i + 1}. ${name}`)).map(([name]) => name);
+  return { file, configured: sections.length - missing.length, total: sections.length, missing };
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const LOOKUP = new Set(['read', 'search', 'list_files']);
+
+/** The script a `zsh -lc` argv runs, or the argv itself. */
+function commandLine(argv) {
+  const i = argv.findIndex((a) => a === '-lc' || a === '-c');
+  return (i >= 0 ? argv[i + 1] : argv.join(' ')) || '';
+}
+
+/** Shell words of a script's first command, honoring simple quotes. */
+function firstWords(script, n) {
+  const words = [];
+  for (const m of String(script).matchAll(/'([^']*)'|"([^"]*)"|([^\s'"|;&]+)|([|;&])/g)) {
+    if (m[4]) break;
+    words.push(m[1] ?? m[2] ?? m[3]);
+    if (words.length === n) break;
+  }
+  return words;
+}
+
+// Tools whose exit 1 is an answer, not an error: grep-style "no match" and
+// diff/cmp-style "the inputs differ". Only exit 1 is exempt; 2+ still counts.
+const ANSWER_EXIT_1 = /^(?:diff|cmp|grep|egrep|fgrep|rg|ag|test|\[|comm)$|^git (?:diff|grep)$/;
+
+/**
+ * A failure's identity across retries: the command's first two words plus the
+ * start of its output, with run-specific noise (paths, ids, positions) removed
+ * so the same failure in another temp dir still matches. Other numbers stay,
+ * since exit codes and counts carry meaning.
+ */
+export function codexErrorSignature(ev, { cwd, home = homedir() } = {}) {
+  let text = String(ev.output || '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+  if (cwd) text = text.replace(new RegExp(escapeRe(cwd), 'g'), '.');
+  if (home) text = text.replace(new RegExp(escapeRe(home), 'g'), '~');
+  text = text.replace(/(?:\/private)?\/(?:tmp|var\/folders)\/[^\s:'"]+/g, '<tmp>')
+    .replace(/\b[0-9a-f]{8,}(?:-[0-9a-f]{4,}){0,4}\b/gi, '<id>')
+    .replace(/:\d+:\d+/g, ':N:N')
+    .replace(/\s+/g, ' ').trim().slice(0, 80);
+  const head = ev.kind === 'patch' ? 'apply_patch'
+    : firstWords(commandLine(ev.argv || []), 2).map((w) => w.split('/').pop()).join(' ');
+  return `${head}: ${text}`;
+}
+
+/** Whether a failure is worth remembering, rather than a probe or Sprag's own feedback. */
+function countable(ev) {
+  if (!ev.failed) return false;
+  // Sprag's write lint rewrites the tool output; that is feedback, not a mistake to learn from.
+  if (/^\[(?:korean-style|claude-token-saver|sprag)/.test(String(ev.output || '').trim())) return false;
+  if (ev.kind === 'patch') return true;
+  // `rg` finding nothing and `ls` on an absent path are how exploration works.
+  const types = (ev.parsed || []).map((c) => c?.type);
+  if (types.length && types.every((t) => LOOKUP.has(t))) return false;
+  if (ev.exit === 1) {
+    const words = firstWords(commandLine(ev.argv || []), 2).map((w) => w.split('/').pop());
+    if (ANSWER_EXIT_1.test(words[0]) || ANSWER_EXIT_1.test(words.join(' '))) return false;
+  }
+  return true;
+}
+
+/**
+ * Repeated failures in a rollout's recent turns, newest-first by count. Reads
+ * only the file tail, which is where the current session's recent work is.
+ */
+export function codexRatchetCandidates(filePath, { now = Date.now(), turns: window = 30, ttlMs = 30 * 60000, tailBytes = 2 * 1024 * 1024, home } = {}) {
+  const lines = readCodexTailLines(filePath, tailBytes);
+  if (!lines) return [];
+  const order = [];
+  const seen = new Set();
+  const failures = [];
+  const calls = new Map();
+  const outputs = [];
+  let cwd = null;
+  let current = null;
+  for (const line of lines) {
+    // Cheap prefilter: these candidate lines are a small share of a rollout.
+    if (!/"(?:item_completed|exec_command_end|patch_apply_end|task_started|turn_context|session_meta|function_call|function_call_output|custom_tool_call|custom_tool_call_output)"/.test(line)) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const p = e?.payload;
+    if (e?.type === 'session_meta' && typeof p?.cwd === 'string') cwd ??= p.cwd;
+    if (e?.type === 'turn_context' && typeof p?.cwd === 'string') cwd = p.cwd;
+    if (e?.type === 'event_msg' && p?.type === 'task_started') current = p.turn_id || current;
+    for (const ev of codexToolEvents(e)) {
+      if (ev.kind === 'call') { if (ev.callId) calls.set(ev.callId, ev); continue; }
+      if (ev.kind === 'output') {
+        if (ev.exit !== null && ev.callId) outputs.push({ ...ev, turn: current, cwd });
+        continue;
+      }
+      if (ev.kind !== 'command' && ev.kind !== 'patch') continue;
+      if (ev.callId) { if (seen.has(ev.callId)) continue; seen.add(ev.callId); }
+      const turn = ev.turnId || current;
+      if (turn && !order.includes(turn)) order.push(turn);
+      if (countable(ev)) failures.push({ ...ev, turn, cwd: ev.cwd || cwd });
+    }
+  }
+  for (const out of outputs) {
+    if (seen.has(out.callId)) continue;
+    const ev = codexLegacyToolEvent(calls.get(out.callId), out);
+    if (!ev) continue;
+    seen.add(out.callId);
+    if (ev.turn && !order.includes(ev.turn)) order.push(ev.turn);
+    if (countable(ev)) failures.push(ev);
+  }
+  const recent = new Set(order.slice(-window));
+  const groups = new Map();
+  for (const ev of failures) {
+    if (!recent.has(ev.turn) || !Number.isFinite(ev.at) || now - ev.at > ttlMs) continue;
+    const pattern = codexErrorSignature(ev, { cwd: ev.cwd, home });
+    const g = groups.get(pattern) || { pattern, count: 0, lastAt: 0 };
+    g.count++;
+    g.lastAt = Math.max(g.lastAt, ev.at);
+    groups.set(pattern, g);
+  }
+  return [...groups.values()].filter((g) => g.count >= 2)
+    .sort((a, b) => b.count - a.count || b.lastAt - a.lastAt).slice(0, 5)
+    .map((g, i) => ({ id: i + 1, ...g }));
+}
+
+/** The ratchet text a candidate promotes to; the user replaces the TODO. */
+export function codexCandidateRule(cand, lang) {
+  return lang === 'ko'
+    ? `반복 감지 ×${cand.count}: ${cand.pattern} · TODO: 원인과 예방책을 한 줄로 적습니다`
+    : `Repeated failure x${cand.count}: ${cand.pattern} · TODO: write the cause and prevention in one line`;
+}

package/src/codex-hooks.js

@@ -0,0 +1,138 @@
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig, userLanguage } from './config.js';
+import { koreanStyleInjection, koreanStyleEnabled } from './korean-style.js';
+import { cohesionInjection } from './cohesion.js';
+import { codexHarnessPaths } from './codex-harness.js';
+import { findProjectRoot } from './harness.js';
+import { runCodexBrief } from './codex-brief.js';
+import { codexDocumentTool, codexDocumentNote, convertCodexDocument } from './codex-doc2md.js';
+import { codexDelegationTool, codexRouteHint } from './codex-delegation.js';
+import { seedOfferBlock } from './seed-rules.js';
+import { readCodexRouteScan, openCodexCandidates, shouldRescanCodex } from './codex-route-scan.js';
+
+const require = createRequire(import.meta.url);
+const lint = require('./korean-lint.cjs');
+const doc2md = require('./doc2md.cjs');
+
+function context(event, text) {
+  return text ? { hookSpecificOutput: { hookEventName: event, additionalContext: text } } : null;
+}
+
+/**
+ * Project route candidates from the last scan. Never scans inline: session
+ * start must stay fast, so a stale scan is refreshed in a detached process
+ * and its results show up next session.
+ */
+async function routeNotice(root, { spawnRescan = defaultRescan } = {}) {
+  const cache = readCodexRouteScan();
+  if (await shouldRescanCodex(cache)) spawnRescan();
+  const open = openCodexCandidates(cache, { root });
+  if (!open.length) return null;
+  return [`[Sprag route-scan] ${open.length} recurring delegable pattern(s) in this project. Mention them once; do not register without the user's scope decision.`,
+    ...open.slice(0, 3).map((c) => `  R${c.id} ${c.category} x${c.count}: ${c.from} -> ${c.suggestedModel || '(choose a model)'}`),
+    '  Review: sprag route-scan --agent codex | approve: sprag delegate rules add R<N> --global|--project --agent codex'].join('\n');
+}
+
+function defaultRescan() {
+  if (process.env.CTS_NO_ROUTE_SCAN === '1') return;
+  spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet', '--agent', 'codex'],
+    { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+}
+
+export function lintCodexTool(payload, { scope = 'all' } = {}) {
+  if (!payload || typeof payload !== 'object') return null;
+  const input = payload.tool_input;
+  const command = typeof input === 'string' ? input : input?.command ?? input?.cmd ?? input?.content ?? input?.patch;
+  const tool = payload.tool_name?.replace(/^(?:functions|tools)\./, '');
+  let paths = [];
+  if (['Bash', 'exec_command', 'shell_command', 'shell'].includes(tool)) paths = lint.writtenPathsOfBash(command);
+  else if (['apply_patch', 'Edit', 'Write'].includes(tool) && typeof command === 'string' && command.startsWith('*** Begin Patch')) {
+    // Patch headers are the path-bearing records of Codex's patch grammar.
+    // Check the final file, including move destinations, not diff markers.
+    paths = [...command.matchAll(/^\*\*\* (?:Add File|Update File|Move to): (.+)\r?$/gm)].map((m) => m[1].trimEnd());
+  } else return lint.lintToolUse(payload, { scope });
+  const messages = [];
+  for (const path of new Set(paths)) {
+    const file = resolve(payload.cwd || process.cwd(), typeof input?.workdir === 'string' ? input.workdir : '.', path);
+    if (!lint.isLintTarget(file, scope)) continue;
+    try {
+      const s = statSync(file);
+      if (!s.isFile() || s.size > 512 * 1024) continue;
+      let text = readFileSync(file, 'utf8');
+      if (lint.isHtmlFile(file)) text = lint.stripHtml(text);
+      const findings = lint.lintKoreanText(text, { code: !lint.isProseFile(file) });
+      if (findings.length) messages.push(lint.formatFindings(file, findings));
+    } catch { /* Deleted, moved, or unreadable files need no feedback. */ }
+  }
+  return messages.length ? messages.join('\n\n') : null;
+}
+
+export async function codexHookOutput(event, payload, { cfg = loadConfig() } = {}) {
+  if (!payload || typeof payload !== 'object') return null;
+  if (event === 'session-start' || event === 'subagent-start') {
+    if (event === 'subagent-start' && cfg?.codex?.delegate !== true) return null;
+    const root = findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' });
+    const parts = [];
+    // Keep the preset file current with this version's wording before it is read.
+    if (event === 'session-start') {
+      try { (await import('./preset-ratchet.js')).preparePresetRatchet({ agent: 'codex' }); } catch { /* Presets are optional. */ }
+    }
+    const { presetRatchetPath } = await import('./preset-ratchet.js');
+    for (const [scope, ratchet] of [['global', codexHarnessPaths(root, 'global').ratchet],
+      ['preset', presetRatchetPath({ agent: 'codex' })], ['project', codexHarnessPaths(root, 'project').ratchet]]) {
+      try {
+        if (statSync(ratchet).size > 32 * 1024) {
+          parts.push(`Read the ${scope} Sprag ratchet rules at ${JSON.stringify(ratchet)} before working; they exceed the automatic injection limit.`);
+        } else {
+          const text = readFileSync(ratchet, 'utf8').trim();
+          // An empty preset file is only its header; injecting it would spend
+          // tokens every session on no rules.
+          if (text && (scope !== 'preset' || /^- /m.test(text))) parts.push(`[Sprag Codex ratchet: ${scope}]\n${text}`);
+        }
+      } catch { /* No rules registered in this scope. */ }
+    }
+    parts.push(koreanStyleInjection({ cfg }), await cohesionInjection({ cfg }));
+    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) parts.push(codexDocumentNote());
+    if (event === 'session-start' && payload.source !== 'compact') {
+      try { parts.push(seedOfferBlock({ root, agent: 'codex' })); } catch { /* Offers are optional. */ }
+      try { parts.push(await routeNotice(root)); } catch { /* A missing scan only delays candidates. */ }
+    }
+    if (event === 'subagent-start') parts.push(
+      '[Sprag Codex delegation]\nStay within the assigned task and any caller-provided budget. Return findings with file references and actual verification results; state unfinished work. Use only available Codex tools and configured roles. Do not infer a model tier or invent a tool-call budget.');
+    return context(event === 'subagent-start' ? 'SubagentStart' : 'SessionStart', parts.filter(Boolean).join('\n\n'));
+  }
+  if (event === 'prompt') {
+    const parts = [];
+    if (cfg?.codex?.delegate === true) {
+      try { parts.push(codexRouteHint(payload, { root: findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' }) })); }
+      catch { /* Invalid routing state must not suppress briefing or conversion. */ }
+    }
+    if (cfg?.codex?.brief !== false) {
+      try { parts.push(runCodexBrief({ sessionId: payload.session_id, transcriptPath: payload.transcript_path, cwd: payload.cwd })); }
+      catch { /* Local telemetry must not prevent document conversion. */ }
+    }
+    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) {
+      parts.push(doc2md.contextForPrompt(payload, { lang: userLanguage(), agent: 'codex', convert: convertCodexDocument }));
+    }
+    return context('UserPromptSubmit', parts.filter(Boolean).join('\n\n'));
+  }
+  if (event === 'pre-tool') {
+    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) {
+      const result = codexDocumentTool(payload);
+      if (result) return result;
+    }
+    return codexDelegationTool(payload, { cfg, root: findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' }) });
+  }
+  if (event === 'post-tool') {
+    if (!koreanStyleEnabled(cfg) || cfg?.koreanStyle?.lint === 'off') return null;
+    const result = lintCodexTool(payload, { scope: cfg?.koreanStyle?.lintScope === 'prose' ? 'prose' : 'all' });
+    const text = typeof result === 'string' ? result : result ? lint.formatFindings(result.filePath, result.findings) : null;
+    if (!text) return null;
+    if (cfg?.koreanStyle?.lint === 'warn') return context('PostToolUse', text);
+    return { decision: 'block', reason: text };
+  }
+  throw new Error(`Unknown Codex hook event: ${event}`);
+}

package/src/codex-installer.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { codexUserDir } from './agent.js';
+
+export const CODEX_HANDLERS = {
+  SessionStart: { matcher: 'startup|resume|clear|compact', command: 'sprag codex-hook --agent codex --event session-start', timeout: 15 },
+  UserPromptSubmit: { command: 'sprag codex-hook --agent codex --event prompt', timeout: 600 },
+  PreToolUse: { matcher: '^(Bash|Read|read_file|Edit|Write|Agent|spawn_agent|mcp__filesystem__read_(?:text_)?file|(?:functions\\.|tools\\.)?(?:exec_command|shell_command|shell|apply_patch|spawn_agent))$', command: 'sprag codex-hook --agent codex --event pre-tool', timeout: 600 },
+  PostToolUse: { matcher: '^(Bash|apply_patch|Edit|Write|(?:functions\\.|tools\\.)?(?:exec_command|shell_command|shell|apply_patch))$', command: 'sprag codex-hook --agent codex --event post-tool', timeout: 15 },
+  SubagentStart: { command: 'sprag codex-hook --agent codex --event subagent-start', timeout: 15 },
+};
+const ownCommands = new Set(Object.values(CODEX_HANDLERS).map((h) => h.command));
+const PANEL_COMMAND = 'sprag codex-hook --agent codex --event panel-start';
+ownCommands.add(PANEL_COMMAND);
+
+export function codexPanelAutoEnabled() {
+  const data = readHooks(join(codexUserDir(), 'hooks.json'));
+  return (data.hooks?.SessionStart || []).some((g) => g.hooks.some((h) => h?.command === PANEL_COMMAND));
+}
+
+export function readCodexHooks(file = join(codexUserDir(), 'hooks.json')) {
+  if (!existsSync(file)) return {};
+  const data = JSON.parse(readFileSync(file, 'utf8'));
+  if (!data || typeof data !== 'object' || Array.isArray(data) ||
+      (data.hooks !== undefined && (!data.hooks || typeof data.hooks !== 'object' || Array.isArray(data.hooks)))) {
+    throw new Error(`Invalid Codex hooks configuration: ${file}`);
+  }
+  for (const groups of Object.values(data.hooks || {})) {
+    if (!Array.isArray(groups) || groups.some((g) => !g || !Array.isArray(g.hooks))) {
+      throw new Error(`Invalid Codex hook groups: ${file}`);
+    }
+  }
+  return data;
+}
+
+const readHooks = readCodexHooks;
+
+export function codexHookStatus() {
+  const data = readCodexHooks();
+  return Object.entries(CODEX_HANDLERS).map(([event, expected]) => {
+    const groups = data.hooks?.[event] || [];
+    // Async hooks cannot enforce write guards or lint feedback. Conversion hooks
+    // also need time for interpreter probes and multiple bounded conversions.
+    const registered = groups.some((group) => group.matcher === expected.matcher && group.hooks.some((hook) =>
+      hook?.type === 'command' && hook.command === expected.command && hook.enabled !== false && hook.async !== true &&
+      Number.isFinite(hook.timeout ?? 600) && (hook.timeout ?? 600) >= expected.timeout));
+    return { event, registered };
+  });
+}
+
+export function configureCodexHooks({ remove = false, panelAuto } = {}) {
+  const file = join(codexUserDir(), 'hooks.json');
+  const data = readHooks(file);
+  const before = JSON.stringify(data);
+  const auto = panelAuto ?? (data.hooks?.SessionStart || []).some((g) => g.hooks.some((h) => h?.command === PANEL_COMMAND));
+  data.hooks ||= {};
+  for (const [event, groups] of Object.entries(data.hooks)) {
+    data.hooks[event] = groups.map((g) => ({ ...g, hooks: g.hooks.filter((h) => !ownCommands.has(h?.command)) }))
+      .filter((g) => g.hooks.length);
+    if (!data.hooks[event].length) delete data.hooks[event];
+  }
+  if (!remove) {
+    for (const [event, { matcher, command, timeout }] of Object.entries(CODEX_HANDLERS)) {
+      const group = { hooks: [{ type: 'command', command, timeout }] };
+      if (matcher) group.matcher = matcher;
+      (data.hooks[event] ||= []).push(group);
+    }
+    if (auto) data.hooks.SessionStart.push({ matcher: 'startup|resume', hooks: [{ type: 'command', command: PANEL_COMMAND, timeout: 10 }] });
+  }
+  if (remove && !Object.keys(data.hooks).length) delete data.hooks;
+  if (JSON.stringify(data) !== before) {
+    mkdirSync(dirname(file), { recursive: true });
+    if (existsSync(file)) writeFileSync(`${file}.bak-${Date.now()}`, readFileSync(file));
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+    renameSync(tmp, file);
+  }
+  return { file, action: remove ? 'removed' : 'configured' };
+}