sprag-cli 3.53.0 → 3.55.0

package/src/commands/install.js

@@ -5,8 +5,12 @@
  * a legacy command file is removed automatically. Cross-platform.
  *   sprag install              # install/update the skill
  *   sprag install --force      # overwrite existing skill file
- *   sprag install --yes        # take the defaults instead of asking
- *   sprag install --no-input   # same as --yes; also implied by CTS_NO_INPUT=1
+ *   sprag install --manual     # ask before each optional step instead
+ *
+ * The default is automatic: nothing is asked, the bundled presets are
+ * registered globally, and Codex is set up too when ~/.codex exists. `--manual`
+ * restores the step-by-step questions (they still need a terminal attached).
+ * `--yes` and `--no-input` are accepted as the explicit spelling of the default.
  */
 
 import { debug } from '../debug.js';
@@ -19,12 +23,13 @@ export async function run({ hasFlag }) {
     const { userLanguage, languageDecided, setUserLanguage } = await import('../config.js');
     const { canPrompt, confirm } = await import('../prompt.js');
     const force = hasFlag('--force');
-    // Two features below write to ~/.claude and cost tokens in every session,
-    // so the install shows what they contain and asks before turning them on.
-    // Asking is only possible with a human attached: postinstall, CI and pipes
-    // fall through to the previous automatic defaults so an unattended upgrade
-    // behaves exactly as it did before.
-    const interactive = canPrompt() && !hasFlag('--yes') && !hasFlag('--no-input');
+    // Automatic unless asked otherwise. A question per step turned the install
+    // into a dozen answers before any work, and every answer has a sensible
+    // default: the harness and presets are what make the first session save
+    // tokens. `--manual` brings the questions back, and only with a terminal
+    // attached, so postinstall, CI and pipes never wait on input.
+    const manual = hasFlag('--manual') && !hasFlag('--yes') && !hasFlag('--no-input');
+    const interactive = manual && canPrompt();
 
     // Output language, decided first because every line below it — and every
     // briefing the hooks inject from here on — is written in it. Until now it
@@ -342,10 +347,37 @@ export async function run({ hasFlag }) {
     // postinstall cannot hold a conversation, and a prompt here would be
     // answered by whoever happens to be at the terminal for a set of rules
     // they have not read. All the install does is say what is waiting.
+    // Presets now live in ratchet-preset.md. Moving the ones older versions
+    // appended to ratchet.md comes first, so they are not offered again below.
     try {
-      const { pendingSeeds } = await import('../seed-rules.js');
+      const { preparePresetRatchet } = await import('../preset-ratchet.js');
+      const p = preparePresetRatchet();
+      if (p.moved) {
+        console.log('');
+        console.log(lang === 'ko'
+          ? `  preset: ratchet.md 에 있던 추천 룰 ${p.moved}건을 ${p.file} 로 옮겼습니다 (원본은 ratchet.md.bak-preset-migration).`
+          : `  preset: moved ${p.moved} bundled rule(s) from ratchet.md to ${p.file} (original kept as ratchet.md.bak-preset-migration).`);
+      }
+    } catch (e) {
+      debug('install:preset-ratchet', e); // the next session start retries
+    }
+
+    try {
+      const { pendingSeeds, acceptSeed } = await import('../seed-rules.js');
       const pending = pendingSeeds();
-      if (pending.length > 0) {
+      if (pending.length > 0 && !manual) {
+        // Automatic install registers every preset globally. Global because a
+        // preset is a tool-wide rule, not a project's; `sprag seed` lists them
+        // and `sprag harness rm` removes any one afterwards.
+        let n = 0;
+        for (const p of pending) {
+          try { if (await acceptSeed(p.id, { scope: 'global' })) n += 1; } catch (e) { debug('install:seed-accept', e); }
+        }
+        console.log('');
+        console.log(lang === 'ko'
+          ? `  seed: 추천 룰 ${n}건을 전체 프로젝트에 등록했습니다 (모델 피팅 + 래칫 프리셋). 목록: sprag seed`
+          : `  seed: registered ${n} recommended rule(s) for all projects (model-fitting + ratchet presets). List: sprag seed`);
+      } else if (pending.length > 0) {
         console.log('');
         console.log(lang === 'ko'
           ? `  seed: 추천 룰 ${pending.length}건이 대기 중입니다 (모델 피팅 + 래칫 프리셋).`
@@ -358,6 +390,70 @@ export async function run({ hasFlag }) {
       debug('install:seed-offer', e); // optional feature; never fail install
     }
 
+    // Codex, when it is installed on this machine. Without this a Codex user
+    // had to know to run `sprag install --agent codex` after the package
+    // install. Registration is all we can do: Codex still asks the user to
+    // trust the hooks in /hooks before they run, and that step stays theirs.
+    try {
+      const { codexUserDir } = await import('../agent.js');
+      const { existsSync } = await import('node:fs');
+      if (process.env.CTS_NO_CODEX !== '1' && existsSync(codexUserDir())) {
+        let proceed = true;
+        if (interactive) {
+          console.log('');
+          proceed = await confirm(lang === 'ko'
+            ? '  codex: Codex 가 설치되어 있습니다. Codex 훅과 하네스도 함께 설정할까요?'
+            : '  codex: Codex is installed here. Set up its hooks and harness too?', { defaultValue: true });
+        }
+        if (proceed) {
+          const { configureCodexHooks } = await import('../codex-installer.js');
+          const { initCodexHarness } = await import('../codex-harness.js');
+          const { loadConfig } = await import('../config.js');
+          const { setupCodexPanel, describePanelSetup } = await import('../codex-panel-setup.js');
+          const config = loadConfig() || {};
+          // A manual install asks before touching the system package manager.
+          let env = process.env;
+          if (interactive && process.platform === 'darwin') {
+            const { tmuxAvailable } = await import('../codex-panel-setup.js');
+            if (!tmuxAvailable() && !await confirm(lang === 'ko'
+              ? '  codex: tmux 가 없습니다. Homebrew 로 설치해 같은 창에 패널을 붙일까요?'
+              : '  codex: tmux is missing. Install it with Homebrew so the panel shares the Codex window?', { defaultValue: true })) {
+              env = { ...process.env, CTS_NO_TMUX: '1' };
+            }
+          }
+          let panel;
+          try { panel = setupCodexPanel({ config, env }); }
+          catch (e) {
+            debug('install:codex-panel', e);
+            const auto = process.platform === 'darwin' && config.codex?.panelAuto !== false;
+            panel = { panelAuto: auto, mode: auto ? 'window' : 'off' };
+          }
+          const hook = configureCodexHooks({ panelAuto: panel.panelAuto });
+          console.log('');
+          console.log(`  codex: hooks ${hook.action} (${hook.file})`);
+          for (const line of describePanelSetup(panel, lang)) console.log(`  codex: ${line}`);
+          if (process.env.CTS_NO_HARNESS !== '1') {
+            const h = initCodexHarness({ scope: 'global' });
+            console.log(`  codex: harness ${h.file}`);
+          }
+          try { (await import('../preset-ratchet.js')).preparePresetRatchet({ agent: 'codex' }); } catch (e) { debug('install:codex-preset', e); }
+          if (!manual) {
+            const { pendingSeeds, acceptSeed } = await import('../seed-rules.js');
+            let n = 0;
+            for (const p of pendingSeeds({ agent: 'codex' })) {
+              try { if (await acceptSeed(p.id, { scope: 'global', agent: 'codex' })) n += 1; } catch (e) { debug('install:codex-seed', e); }
+            }
+            if (n) console.log(lang === 'ko' ? `  codex: 추천 룰 ${n}건 등록` : `  codex: registered ${n} recommended rule(s)`);
+          }
+          console.log(lang === 'ko'
+            ? '  codex: Codex 에서 /hooks 를 열어 Sprag 훅을 신뢰해야 실행됩니다 (Codex 보안 정책이라 자동화할 수 없습니다).'
+            : "  codex: open /hooks in Codex and trust the Sprag hooks; Codex requires that step and it cannot be automated.");
+        }
+      }
+    } catch (e) {
+      debug('install:codex', e); // optional; `sprag install --agent codex` still works
+    }
+
     console.log('');
     console.log('Open Claude Code in any directory and just mention:');
     console.log('  "cache hit rate" / "1M context" / "5H cap" — the skill auto-activates.');

package/src/commands/route-scan.js

@@ -277,6 +277,10 @@ export async function run({ args, hasFlag, numArg }) {
       // when the rendering differs, so the common case is a read and a string
       // compare.
       try { mrHook.syncAllFiles(); } catch (e) { debug('route-scan:sync-ratchet', e); }
+      // Same reason for the preset ratchet: an upgrade that rewords or drops a
+      // bundled rule reaches ratchet-preset.md here, without a reinstall. It
+      // also moves presets older versions appended to ratchet.md.
+      try { (await import('../preset-ratchet.js')).preparePresetRatchet(); } catch (e) { debug('route-scan:sync-preset', e); }
       // Registered rules whose delegated-category error rate crossed the
       // health threshold since promotion — the user approved these, so a
       // status change must be briefed, not just written into the md file.

package/src/commands/seed.js

@@ -5,7 +5,8 @@
  *   sprag seed accept <id> --global     # register one rule
  *   sprag seed accept <id> --project    # ... into this project only
  *   sprag seed accept all --global      # when the user says "all of them"
- *   sprag seed skip <id> | skip all     # never offer it again
+ *   sprag seed skip <id> | skip all     # never offer it again; for an
+ *                                       # accepted preset, drop it from ratchet-preset.md
  *   sprag seed reset                    # make every preset pending again
  *
  * Scope is explicit on purpose, exactly as `harness promote` requires it: the
@@ -13,19 +14,20 @@
  * flag rather than let a default decide where a rule lands.
  */
 
-export async function run({ args, hasFlag }) {
+export async function run({ args, hasFlag, agent = 'claude', root: rootArg }) {
   const sub = args[1];
   const seed = await import('../seed-rules.js');
   const { userLanguage } = await import('../config.js');
   const { findProjectRoot } = await import('../harness.js');
   const lang = userLanguage();
   const ko = lang === 'ko';
-  const root = findProjectRoot();
+  const root = rootArg || findProjectRoot(process.cwd(), { agent });
+  const suffix = agent === 'codex' ? ' --agent codex' : '';
 
   const scopeFlag = () => (hasFlag('--global') ? 'global' : hasFlag('--project') ? 'project' : null);
 
   if (sub === 'reset') {
-    const n = seed.resetSeeds();
+    const n = await seed.resetSeeds({ agent });
     console.log(ko
       ? `기록된 응답 ${n}건을 지웠습니다 — 프리셋 전체가 다시 제안 대상이 됩니다.`
       : `Cleared ${n} recorded answer(s) — every preset is pending again.`);
@@ -40,14 +42,16 @@ export async function run({ args, hasFlag }) {
         : 'Pass an id (list them with `sprag seed`), or `all`.');
       process.exit(1);
     }
-    const pending = seed.pendingSeeds({ lang, root });
+    const pending = seed.pendingSeeds({ lang, root, agent });
     const targets = ids.includes('all') ? pending.map((s) => s.id) : ids;
 
     if (sub === 'skip') {
       for (const id of targets) {
-        const r = seed.skipSeed(id, { lang, root });
+        const r = await seed.skipSeed(id, { lang, root, agent });
         console.log(r
-          ? (ko ? `건너뜀: ${id}` : `skipped: ${id}`)
+          ? (r.removed
+            ? (ko ? `프리셋 파일에서 뺐습니다: ${id}` : `removed from the preset file: ${id}`)
+            : (ko ? `건너뜀: ${id}` : `skipped: ${id}`))
           : (ko ? `대기 중인 프리셋이 아닙니다: ${id}` : `not a pending preset: ${id}`));
       }
       return;
@@ -61,7 +65,7 @@ export async function run({ args, hasFlag }) {
       process.exit(1);
     }
     for (const id of targets) {
-      const r = await seed.acceptSeed(id, { scope, root, lang });
+      const r = await seed.acceptSeed(id, { scope, root, lang, agent });
       if (!r) {
         console.log(ko ? `대기 중인 프리셋이 아닙니다: ${id}` : `not a pending preset: ${id}`);
         continue;
@@ -77,8 +81,8 @@ export async function run({ args, hasFlag }) {
 
   // Default: status. Lists what is pending and what was already answered, so a
   // user who said no can see that they did and reverse it with `reset`.
-  const pending = seed.pendingSeeds({ lang, root });
-  const { decided } = seed.loadSeedState();
+  const pending = seed.pendingSeeds({ lang, root, agent });
+  const { decided } = seed.loadSeedState({ agent });
   const answered = Object.entries(decided);
   console.log(ko
     ? `seed — 동봉 프리셋 중 대기 ${pending.length}건, 응답 완료 ${answered.length}건`
@@ -99,7 +103,7 @@ export async function run({ args, hasFlag }) {
   if (pending.length > 0) {
     console.log('');
     console.log(ko
-      ? '등록: sprag seed accept <id> --global|--project   ·   거절: seed skip <id>'
-      : 'register: sprag seed accept <id> --global|--project   ·   decline: seed skip <id>');
+      ? `등록: sprag seed accept <id> --global|--project${suffix}   ·   거절: seed skip <id>${suffix}`
+      : `register: sprag seed accept <id> --global|--project${suffix}   ·   decline: seed skip <id>${suffix}`);
   }
 }

package/src/commands/uninstall.js

@@ -35,6 +35,29 @@ export async function run({ hasFlag, args = [] }) {
   for (const item of r.kept) {
     console.log(lang === 'ko' ? `  유지: ${item}` : `  kept: ${item}`);
   }
+  // The install now registers Codex too when it finds it, so removal has to
+  // undo that as well; otherwise Codex keeps calling a command that may no
+  // longer exist. Only our own entries go, exactly as `uninstall --agent codex`.
+  try {
+    const { codexHookStatus, configureCodexHooks } = await import('../codex-installer.js');
+    const { codexHarnessStatus, uninitCodexHarness } = await import('../codex-harness.js');
+    const hooked = codexHookStatus().some((h) => h.registered);
+    let harness = false;
+    try { harness = codexHarnessStatus({ scope: 'global' }).configured > 0; } catch { /* no AGENTS.md */ }
+    if (hooked || harness) {
+      const hook = configureCodexHooks({ remove: true });
+      const h = uninitCodexHarness({ scope: 'global' });
+      console.log(lang === 'ko'
+        ? `  Codex: 훅 ${hook.action} (${hook.file}), 하네스 ${h.removed ? '제거' : '없음'}`
+        : `  Codex: hooks ${hook.action} (${hook.file}), harness ${h.removed ? 'removed' : 'absent'}`);
+      if (process.platform === 'darwin') {
+        try {
+          const { installPanelShell } = await import('../codex-panel-shell.js');
+          installPanelShell({ remove: true });
+        } catch (e) { /* a malformed or foreign block stays for the user to repair */ }
+      }
+    }
+  } catch { /* Codex state is optional; the Claude removal above already succeeded */ }
   if (!purge) {
     console.log(lang === 'ko'
       ? `  기록된 절감액과 설정까지 지우려면 \`${CLI_NAME} uninstall --purge\` 를 실행하십시오.`

package/src/commands/upgrade.js

@@ -31,6 +31,17 @@ export async function run({ hasFlag, version }) {
   const lang = userLanguage();
   const cmd = upgradeCommand();
 
+  // pnpm and bun skip lifecycle scripts by default, and npm skips them under
+  // ignore-scripts, so the new copy's setup (Codex hooks, tmux panel) runs here.
+  // The install is idempotent, so npm running it twice changes nothing.
+  async function runSetup() {
+    console.log('$ sprag install');
+    const installCode = await runCommand('sprag install');
+    if (installCode !== 0) console.error(lang === 'ko'
+      ? '설치 후 설정(sprag install)이 실패했습니다. 새 셸에서 sprag install 을 직접 실행하십시오.'
+      : 'Post-upgrade setup (sprag install) failed. Run sprag install in a fresh shell.');
+  }
+
   if (hasFlag('--print')) {
     console.log(cmd);
     return;
@@ -55,6 +66,7 @@ export async function run({ hasFlag, version }) {
         : `Migration command failed with exit code ${migrateCode}. Check the output above.`);
       process.exit(migrateCode);
     }
+    await runSetup();
     console.log(lang === 'ko'
       ? '이전이 끝났습니다. 새 셸에서 sprag --version 으로 확인하십시오.'
       : 'Migration done. Confirm with sprag --version in a fresh shell.');
@@ -86,6 +98,7 @@ export async function run({ hasFlag, version }) {
   // still reports the old version. Refresh the cache against the new latest so
   // the statusline chip clears on the next render instead of lingering.
   await refreshUpdateState(s.latest);
+  await runSetup();
   console.log(lang === 'ko'
     ? `설치가 끝났습니다. 새 셸에서 sprag --version 으로 ${s.latest} 인지 확인하십시오.`
     : `Done. In a fresh shell, run sprag --version to confirm ${s.latest}.`);

package/src/doc2md.cjs

@@ -182,7 +182,7 @@ function banner(sourcePath, saving) {
   return lines.join('\n');
 }
 
-function writeCache(filePath, markdown, extra) {
+function writeCache(filePath, markdown, extra, { agent } = {}) {
   ensureCacheDir();
   const cacheFile = cachePathFor(filePath);
   const src = fs.statSync(filePath);
@@ -197,7 +197,7 @@ function writeCache(filePath, markdown, extra) {
     { markdown },
   );
   fs.writeFileSync(cacheFile, banner(filePath, saving) + markdown, { encoding: 'utf8', mode: 0o600 });
-  ledger.recordConversion(userDataDir(), {
+  if (agent !== 'codex') ledger.recordConversion(userDataDir(), {
     key: path.resolve(filePath),
     ts: Date.now(),
     usd: saving.usd,
@@ -447,7 +447,7 @@ function spawnFigConvert(fig2md, filePath) {
   }
 }
 
-function convert(filePath, { converter = CONVERTER, python: pythonOverride = null } = {}) {
+function convert(filePath, { converter = CONVERTER, python: pythonOverride = null, agent } = {}) {
   if (!isTargetPath(filePath)) return { ok: false, reason: 'not-target' };
   if (isSensitivePath(filePath)) return { ok: false, reason: 'sensitive' };
 
@@ -478,7 +478,7 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
     if (!result.ok) return result;
     const written = writeCache(filePath, result.markdown, {
       note: result.note, truncated: false, rows: 0, pages: 0, markupBytes: 0,
-    });
+    }, { agent });
     return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
   }
 
@@ -537,7 +537,7 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
     pages: payload.pages || 0,
     markupBytes: payload.markup_bytes || 0,
     clipped,
-  });
+  }, { agent });
   return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
 }
 
@@ -763,19 +763,38 @@ function decideForRead(context, opts = {}) {
  * Quoted, `@`-prefixed and bare paths all count. Windows drive letters are
  * matched too, since the rest of the module is path-agnostic.
  */
-function documentPathsIn(text) {
+function documentPathsIn(text, cwd = process.cwd()) {
   if (typeof text !== 'string' || !text) return [];
   const exts = TARGET_EXTENSIONS.map((e) => e.slice(1)).join('|');
   // Backslashes count as path characters, not just separators to tolerate:
   // `C:\\Users\\me\\deck.pptx` and `\\\\server\\share\\deck.pptx` are how
   // Windows users write a path, and without them the scanner silently sees no
   // documents at all on that platform.
-  const re = new RegExp(`[@'"\`]?((?:[A-Za-z]:)?[~./\\\\][^\\s'"\`]*\\.(?:${exts}))`, 'gi');
+  //
+  // The extension may be followed by anything except more of a filename, so
+  // `deck.pptx를` and `(./a.pdf)` still count while `a.pdfx` does not. Korean
+  // attaches a particle straight to the path, and a whitelist of punctuation
+  // after the extension silently dropped every such prompt.
+  const tail = '(?![A-Za-z0-9_])';
+  const forms = [
+    // A path that starts like one (`~`, `.`, `/`, `\`, a drive letter), found
+    // anywhere in the text. This is the original scanner, kept whole so that a
+    // new form can only add paths, never lose one it used to find.
+    new RegExp(`((?:[A-Za-z]:)?[~./\\\\][^\\s'"\x60]*\\.(?:${exts}))${tail}`, 'gi'),
+    // A quoted path, which may contain spaces and needs no leading `./`.
+    new RegExp(`["'\x60]([^"'\x60]+\\.(?:${exts}))["'\x60]`, 'gi'),
+    // A bare name such as `book.pdf` or `docs/a.pdf`, starting a word. An
+    // opening bracket or an `@` is a word boundary, not part of the name.
+    new RegExp(`(?:^|[\\s@(\\[{<])([^\\s'"\x60()\\[\\]{}<>@][^\\s'"\x60]*\\.(?:${exts}))${tail}`, 'gi'),
+  ];
   const found = [];
-  for (const m of text.matchAll(re)) {
-    const raw = m[1];
-    const abs = raw.startsWith('~') ? path.join(os.homedir(), raw.slice(1)) : path.resolve(raw);
-    if (!found.includes(abs)) found.push(abs);
+  for (const re of forms) {
+    for (const m of text.matchAll(re)) {
+      const raw = m[1];
+      if (raw.includes('://')) continue;
+      const abs = raw.startsWith('~') ? path.join(os.homedir(), raw.slice(1)) : path.resolve(cwd, raw);
+      if (!found.includes(abs)) found.push(abs);
+    }
   }
   return found;
 }
@@ -812,25 +831,30 @@ function conversionSummary(sourcePath, meta = {}) {
 function contextForPrompt(payload, opts = {}) {
   const lang = opts.lang === 'ko' ? 'ko' : 'en';
   if (!payload || typeof payload.prompt !== 'string') return null;
-  const paths = documentPathsIn(payload.prompt).filter((p) => {
+  const paths = documentPathsIn(payload.prompt, payload.cwd || process.cwd()).filter((p) => {
     try { return fs.statSync(p).isFile(); } catch { return false; }
   });
   if (paths.length === 0) return null;
 
   const lines = [];
   const targets = paths.slice(0, MAX_PROMPT_CONVERSIONS);
+  const { convert: convertFn = convert, ...convertOptions } = opts;
   for (const p of targets) {
     const name = path.basename(p);
-    const result = convert(p, opts);
+    const result = convertFn(p, convertOptions);
     if (result.ok) {
       lines.push(`  ${name} → ${result.cacheFile}`);
-      lines.push(`      ${conversionSummary(p, result.meta)}`);
+      lines.push(`      ${conversionSummary(p, opts.agent === 'codex' ? { ...result.meta, savedUsd: 0 } : result.meta)}`);
       if (result.meta && result.meta.note) lines.push(`      ${result.meta.note}`);
-      if (result.meta && result.meta.clipped) {
+      if (opts.agent === 'codex' && (result.meta?.clipped || result.meta?.truncated)) {
+        lines.push('      Text extraction is incomplete; inspect the source for omitted content.');
+      } else if (result.meta && result.meta.clipped) {
         lines.push('      변환 결과가 너무 커서 뒷부분을 잘랐습니다. 전체가 필요하면 원본을 직접 다루십시오.');
       }
     } else if (result.reason === 'no-markitdown') {
-      lines.push(lang === 'ko'
+      lines.push(opts.agent === 'codex'
+        ? `  ${name}: converter unavailable. Run sprag doc2md install-converter --agent codex, then retry.`
+        : lang === 'ko'
         ? `  ${name}: 변환기를 설치하는 중입니다(첫 실행에만 걸립니다). 설치가 끝나면 다음 요청부터 자동 변환됩니다.`
         : `  ${name}: the converter is installing now (first run only). It will convert automatically from the next request.`);
     } else if (result.reason === 'drm-protected') {
@@ -865,6 +889,12 @@ function contextForPrompt(payload, opts = {}) {
       : `  (converted the first ${targets.length} of ${paths.length} documents; run \`sprag doc2md <path>\` for the rest.)`);
   }
 
+  if (opts.agent === 'codex') return [
+    '[doc2md] Document conversion results:', ...lines,
+    'Read each successfully converted Markdown file instead of extracting the original document again.',
+    'Report conversion failures accurately. For successful conversions, mention the source and Markdown sizes.',
+    'For other documents, run sprag doc2md <path> --agent codex. Text extraction does not verify images or layout.',
+  ].join('\n');
   return lang === 'ko'
     ? [
       '[doc2md] 이 프롬프트에 문서 경로가 있어 Markdown 으로 변환해 두었습니다.',
@@ -919,12 +949,13 @@ function sessionNote(lang = 'en') {
  * .fig overwritten with text is destroyed, not edited. Nothing this tool
  * ships can write those formats back.
  */
-function decideForWrite(context) {
+function decideForWrite(context, opts = {}) {
   if (!context || (context.tool_name !== 'Edit' && context.tool_name !== 'Write')) return null;
   const toolInput = context.tool_input;
   const filePath = toolInput && typeof toolInput.file_path === 'string' ? toolInput.file_path : '';
   if (!filePath) return null;
   const abs = path.resolve(filePath);
+  const codex = opts.agent === 'codex';
 
   if (abs.startsWith(cacheDir() + path.sep)) {
     let source = null;
@@ -933,23 +964,36 @@ function decideForWrite(context) {
     } catch { /* the deny stands on its own */ }
     return {
       deny: true,
-      reason: '[doc2md] 이 파일은 변환 캐시입니다. 여기를 고쳐도 원본 문서에는 아무것도 반영되지 않고, '
-        + '캐시만 오염된 채 다음 읽기부터 계속 서빙됩니다.\n'
-        + (source ? `  원본: ${source}\n` : '')
-        + '  문서 수정이 목적이라면: 원본을 복사한 뒤(cp) 복사본을 스크립트로 수정하십시오. '
-        + `pptx·docx·xlsx 는 ${managedPython()} 에 python-pptx·python-docx·openpyxl 이 설치되어 있고, `
-        + '.fig 는 doc2md-fig 의 openfig-core 로 편집·재인코드할 수 있습니다. '
-        + '수정 후 복사본을 `sprag doc2md <복사본>` 으로 재변환해 의도한 변경이 들어갔는지 확인하십시오. 원본은 절대 직접 수정하지 마십시오.',
+      reason: codex
+        ? '[doc2md] This file is a conversion cache. Editing it changes nothing in the source document; '
+          + 'it only corrupts the cache, which keeps being served on every later read.\n'
+          + (source ? `  Source: ${source}\n` : '')
+          + '  To modify the document instead: copy the original, then edit the copy with a script. '
+          + `pptx/docx/xlsx have python-pptx/python-docx/openpyxl installed under ${managedPython()}, `
+          + "and .fig edits go through doc2md-fig's openfig-core. "
+          + 'After editing, reconvert the copy with `sprag doc2md <copy> --agent codex` to verify the change landed. Never edit the original directly.'
+        : '[doc2md] 이 파일은 변환 캐시입니다. 여기를 고쳐도 원본 문서에는 아무것도 반영되지 않고, '
+          + '캐시만 오염된 채 다음 읽기부터 계속 서빙됩니다.\n'
+          + (source ? `  원본: ${source}\n` : '')
+          + '  문서 수정이 목적이라면: 원본을 복사한 뒤(cp) 복사본을 스크립트로 수정하십시오. '
+          + `pptx·docx·xlsx 는 ${managedPython()} 에 python-pptx·python-docx·openpyxl 이 설치되어 있고, `
+          + '.fig 는 doc2md-fig 의 openfig-core 로 편집·재인코드할 수 있습니다. '
+          + '수정 후 복사본을 `sprag doc2md <복사본>` 으로 재변환해 의도한 변경이 들어갔는지 확인하십시오. 원본은 절대 직접 수정하지 마십시오.',
     };
   }
 
   if (isTargetPath(abs)) {
     return {
       deny: true,
-      reason: `[doc2md] ${path.basename(abs)} 는 이진 문서입니다. Edit/Write 는 텍스트를 쓰므로 이 파일을 파괴합니다. `
-        + '수정하려면 원본을 복사한 뒤(cp) 복사본을 스크립트로 고치십시오. '
-        + `pptx·docx·xlsx 는 ${managedPython()} 의 python-pptx·python-docx·openpyxl, .fig 는 openfig-core 를 쓰고, `
-        + '수정 후 `sprag doc2md <복사본>` 재변환으로 결과를 검증하십시오.',
+      reason: codex
+        ? `[doc2md] ${path.basename(abs)} is a binary document. Edit/Write emit text, so this call would destroy it. `
+          + 'To modify it, copy the original, then edit the copy with a script. '
+          + `pptx/docx/xlsx use python-pptx/python-docx/openpyxl under ${managedPython()}, and .fig uses openfig-core. `
+          + 'After editing, reconvert with `sprag doc2md <copy> --agent codex` to verify the change landed.'
+        : `[doc2md] ${path.basename(abs)} 는 이진 문서입니다. Edit/Write 는 텍스트를 쓰므로 이 파일을 파괴합니다. `
+          + '수정하려면 원본을 복사한 뒤(cp) 복사본을 스크립트로 고치십시오. '
+          + `pptx·docx·xlsx 는 ${managedPython()} 의 python-pptx·python-docx·openpyxl, .fig 는 openfig-core 를 쓰고, `
+          + '수정 후 `sprag doc2md <복사본>` 재변환으로 결과를 검증하십시오.',
     };
   }
   return null;

package/src/handoff.js

@@ -66,11 +66,11 @@ function pickPath(cwd, now) {
   return join(cwd, `${stem}-${Date.now()}.md`);
 }
 
-function renderTemplate({ now, cwd, git, caps }) {
+function renderTemplate({ now, cwd, git, caps, agent, session }) {
   const lines = [];
   lines.push(`# Handoff — ${ymd(now)} ${pad(now.getHours())}:${pad(now.getMinutes())}`);
   lines.push('');
-  lines.push(`Generated by \`sprag handoff\`.`);
+  lines.push(`Generated by \`sprag handoff${agent === 'codex' ? ' --agent codex' : ''}\`.`);
   lines.push('');
   lines.push('## Context');
   lines.push('');
@@ -92,7 +92,27 @@ function renderTemplate({ now, cwd, git, caps }) {
 
   lines.push('## Cap snapshot');
   lines.push('');
-  if (caps && Array.isArray(caps.windows) && caps.windows.length > 0) {
+  if (agent === 'codex') {
+    lines.push('- Source: recorded Codex rollout, not a live quota or billing response.');
+    if (session) {
+      lines.push(`- Session: ${JSON.stringify(session.sessionId)}`);
+      lines.push(`- Model: ${JSON.stringify(session.model)}; effort: ${JSON.stringify(session.effort)}`);
+      lines.push(`- Last activity: ${session.lastActivity ? new Date(session.lastActivity).toISOString() : 'unknown'}`);
+      lines.push(`- Recorded input context: ${session.lastContextTokens ?? 'unknown'} / ${session.contextWindow ?? 'unknown'} tokens`);
+      lines.push(`- Tokens: input ${session.totals.input + session.totals.cacheRead}, cached ${session.totals.cacheRead}, output ${session.totals.output}`);
+      lines.push(`- Limits snapshot: ${session.rateLimitsAt ? new Date(session.rateLimitsAt).toISOString() : 'not reported'}`);
+      for (const key of ['primary', 'secondary']) {
+        const win = session.rateLimits?.[key];
+        if (!Number.isFinite(win?.used_percent)) continue;
+        const reset = Number.isFinite(win.resets_at) ? win.resets_at * 1000 : null;
+        const resetDate = reset === null ? null : new Date(reset);
+        const resetText = resetDate && Number.isFinite(resetDate.getTime())
+          ? reset <= now.getTime() ? 'awaiting new usage' : `reset at ${resetDate.toISOString()}` : 'reset unknown';
+        lines.push(`- ${key}: ${win.used_percent}% used (${resetText})`);
+      }
+    } else lines.push('- No matching Codex session log.');
+    lines.push('- Cost and cache TTL: unavailable.');
+  } else if (caps && Array.isArray(caps.windows) && caps.windows.length > 0) {
     for (const win of caps.windows) {
       const label = labelForKey(win.key).long;
       if (!Number.isFinite(win.usedPct)) {
@@ -132,7 +152,7 @@ function renderTemplate({ now, cwd, git, caps }) {
   lines.push('- _(non-obvious gotchas, half-finished refactors, failing tests)_');
   lines.push('');
 
-  lines.push('## Resume prompt for the next Claude Code session');
+  lines.push(`## Resume prompt for the next ${agent === 'codex' ? 'Codex' : 'Claude Code'} session`);
   lines.push('');
   lines.push('```');
   lines.push('Read the most recent HANDOFF-*.md in this directory and continue the work.');
@@ -151,11 +171,11 @@ function renderTemplate({ now, cwd, git, caps }) {
  * @param {Date} [opts.now=new Date()]
  * @returns {{ path: string, git: { branch: string, head: string, status: string } | null }}
  */
-export function writeHandoff({ cwd = process.cwd(), caps = null, now = new Date() } = {}) {
+export function writeHandoff({ cwd = process.cwd(), caps = null, now = new Date(), agent = 'claude', session = null } = {}) {
   const absCwd = resolve(cwd);
   const git = gitSnapshot(absCwd);
   const path = pickPath(absCwd, now);
-  const body = renderTemplate({ now, cwd: absCwd, git, caps });
-  writeFileSync(path, body);
+  const body = renderTemplate({ now, cwd: absCwd, git, caps, agent, session });
+  writeFileSync(path, body, { flag: 'wx' });
   return { path, git };
 }

package/src/harness-templates.js

@@ -40,6 +40,38 @@ export function modelRatchetImportLine(scope = 'project') {
   return scope === 'global' ? '@~/.claude/ratchet-model.md' : '@.claude/ratchet-model.md';
 }
 
+/**
+ * The preset ratchet: the bundled rules the user accepted globally. It is a
+ * tool-owned file like ratchet-model.md, regenerated whole from the recorded
+ * answers, so an upgrade can reword, add or drop presets without touching the
+ * rules the user wrote into ratchet.md. Presets are global-only, so only the
+ * global block imports it.
+ */
+export function presetRatchetImportLine() {
+  return '@~/.claude/ratchet-preset.md';
+}
+export const PRESET_RATCHET_IMPORT_RE = /^@~\/\.claude\/ratchet-preset\.md\s*$/m;
+
+/**
+ * Render ratchet-preset.md. `rules` is [{ id, text }] in display order. The
+ * file is loaded into every session, so the header stays short.
+ */
+export function renderPresetRatchet(rules, { lang = 'en', agent = 'claude' } = {}) {
+  const ko = lang === 'ko' && agent !== 'codex';
+  const suffix = agent === 'codex' ? ' --agent codex' : '';
+  const head = ko
+    ? `# Preset Ratchet Rules (sprag 관리)
+
+sprag 에 동봉된 추천 룰 가운데 전역으로 등록한 것입니다. sprag 가 이 파일을 통째로 다시 쓰므로
+직접 고치지 마십시오. 하나를 빼려면 \`sprag seed skip <id>${suffix}\`, 직접 쓰는 룰은 ratchet.md 에 둡니다.`
+    : `# Preset Ratchet Rules (managed by sprag)
+
+Bundled rules you registered globally. Sprag rewrites this file whole, so do not
+edit it. Drop one with \`sprag seed skip <id>${suffix}\`; your own rules belong in ratchet.md.`;
+  const body = rules.map((r) => `- [${r.id}] ${r.text}`).join('\n');
+  return `${head}\n\n## Rules\n\n${body}${body ? '\n' : ''}`;
+}
+
 // Matches either scope's import line, so completeness checks don't need to know
 // which scope wrote the block. `(?!-)` keeps the ratchet-model import from
 // counting as the ratchet.md one.
@@ -118,7 +150,7 @@ ${HARNESS_SECTIONS[4].heading}
 📥 ratchet 룰 로드 (이 줄들을 지우면 룰이 적용되지 않습니다):
 
 ${ratchetImportLine(scope)}
-${modelRatchetImportLine(scope)}
+${modelRatchetImportLine(scope)}${scope === 'global' ? `\n${presetRatchetImportLine()}` : ''}
 ${HARNESS_BLOCK_END}
 `;
 }