sprag-cli 3.52.0 → 3.54.0

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.js

@@ -26,6 +26,7 @@ import { routeWarningForStatusline } from './route-scan.js';
 import { ruleHealthWarningForStatusline, modelRatchetPathFor, renderModelRatchet } from './model-rules.js';
 import { compactWindowWarningForStatusline } from './compact-window.js';
 import { userLanguage } from './config.js';
+import { codexUserDir } from './agent.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -42,11 +43,13 @@ function readHarnessState() {
  * or package.json). Falls back to `start` itself so harness commands always
  * have *some* directory to write into, even outside a repo.
  */
-export function findProjectRoot(start = process.cwd()) {
+export function findProjectRoot(start = process.cwd(), { agent = 'claude' } = {}) {
   let dir = resolve(start);
   for (;;) {
     if (
-      existsSync(join(dir, 'CLAUDE.md')) ||
+      (agent === 'codex'
+        ? existsSync(join(dir, 'AGENTS.md')) || existsSync(join(dir, 'AGENTS.override.md'))
+        : existsSync(join(dir, 'CLAUDE.md'))) ||
       existsSync(join(dir, '.git')) ||
       existsSync(join(dir, 'package.json'))
     ) {
@@ -70,10 +73,15 @@ function globalRatchetMdPath() {
   return join(homedir(), '.claude', 'ratchet.md');
 }
 
-function resolveRatchetPath(scope, root) {
+function resolveRatchetPath(scope, root, agent = 'claude') {
+  if (agent === 'codex') return scope === 'global' ? join(codexUserDir(), 'ratchet.md') : join(root, '.codex', 'ratchet.md');
   return scope === 'global' ? globalRatchetMdPath() : ratchetMdPath(root);
 }
 
+function initialRatchet(agent) {
+  return agent === 'codex' ? '# Codex Ratchet Rules\n\n## Rules\n\n' : harnessRatchetMdInitial();
+}
+
 // Global harness lives in ~/.claude/CLAUDE.md — Claude Code loads this for every
 // project, so a global init makes the 5 harness sections apply everywhere
 // (mirrors the project/global split that ratchet.md already has).
@@ -312,14 +320,14 @@ export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false,
  * harness promote — append a one-line rule to .claude/ratchet.md.
  * Creates the file from the initial template if missing.
  */
-export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'project' } = {}) {
-  const rmPath = resolveRatchetPath(scope, root);
+export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'project', agent = 'claude' } = {}) {
+  const rmPath = resolveRatchetPath(scope, root, agent);
   let existing = '';
   if (existsSync(rmPath)) {
     existing = readFileSync(rmPath, 'utf8');
   } else {
     mkdirSync(dirname(rmPath), { recursive: true });
-    existing = harnessRatchetMdInitial();
+    existing = initialRatchet(agent);
   }
   const next = appendRatchetRule(existing, ruleText);
   writeFileSync(rmPath, next);
@@ -339,17 +347,17 @@ export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'pr
  * Deduped by rule text (ignoring the YYYY-MM-DD stamp) — idempotent.
  * Returns { path, scope, added, skippedRules, presets }.
  */
-export function harnessPull({ root = findProjectRoot(), scope = 'global' } = {}) {
+export function harnessPull({ root = findProjectRoot(), scope = 'global', agent = 'claude' } = {}) {
   const presets = presetRules();
-  const rmPath = resolveRatchetPath(scope, root);
+  const rmPath = resolveRatchetPath(scope, root, agent);
   const result = { path: rmPath, scope, added: [], skippedRules: 0, presets: presets.length };
   const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}:\s*/, '').trim();
 
   let content = existsSync(rmPath)
     ? readFileSync(rmPath, 'utf8')
-    : harnessRatchetMdInitial();
+    : initialRatchet(agent);
   const have = new Set(
-    harnessListRules({ root, scope }).rules.map((r) => stripDate(r.text)),
+    harnessListRules({ root, scope, agent }).rules.map((r) => stripDate(r.text)),
   );
   for (const rule of presets) {
     if (have.has(rule)) {
@@ -385,7 +393,8 @@ export function presetRuleEntries() {
     const data = JSON.parse(readFileSync(path, 'utf8'));
     return (Array.isArray(data.rules) ? data.rules : [])
       .filter((r) => r && typeof r.ko === 'string' && r.ko.trim())
-      .map((r) => ({ ko: r.ko.trim(), en: (r.en || r.ko).trim() }));
+      .map((r) => ({ ko: r.ko.trim(), en: (r.en || r.ko).trim(),
+        ...(Array.isArray(r.agents) ? { agents: r.agents.filter((a) => typeof a === 'string') } : {}) }));
   } catch {
     return [];
   }
@@ -400,8 +409,8 @@ export function presetRules(lang = userLanguage()) {
  * harness list — return numbered ratchet rules from .claude/ratchet.md.
  * Numbering is 1-based and matches `harness rm <N>`.
  */
-export function harnessListRules({ root = findProjectRoot(), scope = 'project' } = {}) {
-  const rmPath = resolveRatchetPath(scope, root);
+export function harnessListRules({ root = findProjectRoot(), scope = 'project', agent = 'claude' } = {}) {
+  const rmPath = resolveRatchetPath(scope, root, agent);
   if (!existsSync(rmPath)) return { path: rmPath, rules: [] };
   const lines = readFileSync(rmPath, 'utf8').split('\n');
   const rules = [];
@@ -482,8 +491,8 @@ export function contextWeightStatus({ root = findProjectRoot() } = {}) {
  * it. Selection is by tag and/or age; nothing is deleted, so a pruned rule can
  * be pasted back. Returns the pruned rules for the CLI to echo.
  */
-export function harnessPrune({ root = findProjectRoot(), scope = 'project', tag = null, olderThanMonths = null, dryRun = false } = {}) {
-  const { path: rmPath, rules } = harnessListRules({ root, scope });
+export function harnessPrune({ root = findProjectRoot(), scope = 'project', agent = 'claude', tag = null, olderThanMonths = null, dryRun = false } = {}) {
+  const { path: rmPath, rules } = harnessListRules({ root, scope, agent });
   if (!existsSync(rmPath)) return { ok: false, error: `ratchet.md not found at ${rmPath}` };
   if (!tag && !olderThanMonths) return { ok: false, error: 'Nothing selected — pass --tag <t> and/or --older-than <months>' };
   const cutoff = olderThanMonths ? Date.now() - olderThanMonths * 30 * 24 * 60 * 60 * 1000 : null;
@@ -519,8 +528,8 @@ export function harnessPrune({ root = findProjectRoot(), scope = 'project', tag
  * value is one-way accumulation; deleting should feel deliberate. The CLI
  * surfaces a "narrow the condition instead" reminder around this call.
  */
-export function harnessRmRule(n, { root = findProjectRoot(), scope = 'project' } = {}) {
-  const { path: rmPath, rules } = harnessListRules({ root, scope });
+export function harnessRmRule(n, { root = findProjectRoot(), scope = 'project', agent = 'claude' } = {}) {
+  const { path: rmPath, rules } = harnessListRules({ root, scope, agent });
   if (!existsSync(rmPath)) {
     return { ok: false, error: `ratchet.md not found at ${rmPath}` };
   }

package/src/installer.js

@@ -14,6 +14,7 @@
  */
 
 import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync, rmSync } from 'node:fs';
+import { loadConfig, saveConfig } from './config.js';
 import { CLI_NAME, LEGACY_CLI_NAME } from './cli-name.js';
 import { join } from 'node:path';
 import { claudeUserDir, userDataDir } from './paths.js';
@@ -602,6 +603,154 @@ export function removeDoc2mdHook() {
   return { path: file, action: 'removed' };
 }
 
+// Registers the PreToolUse hook that rewrites Task/Agent delegation prompts
+// (see delegation-guard.js for what it appends and why). Matches on both tool
+// names because Claude Code's own docs and its runtime disagree on which one
+// fires — cheaper to catch both than to find out which build is running.
+//
+// timeout: 10 — this hook reads a transcript TAIL (4 MiB; see TAIL_BYTES in
+// session-paths.js, measured at 11.5ms on a real 4.65MB session) and two small
+// preset files, nowhere near doc2md's markitdown cold-import cost, so a short
+// timeout is safe and catches a hung read fast. The size lives in that one
+// constant; quoting a number here is only ever a stale copy of it.
+//
+// Installed by `delegate on`, removed by `delegate off`. Idempotent. Not part
+// of `installAll()` — this feature rewrites tool input on every delegation,
+// which is exactly the kind of silent-by-default behavior install.js's other
+// opt-in features (doc2md, korean, cohesion) avoid shipping without being asked.
+const DELEGATION_GUARD_HOOK_COMMAND = `${CLI} delegate --hook`;
+// One pattern, shared by install, remove and the status readout. Three
+// hand-written variants drifted apart once already in this file: a substring
+// test confused `--hook` with `--hook-delegated`. `(?![\\w-])` rejects both a
+// hyphen and a word character, so `--hookfoo` is not mistaken for this hook.
+// Not exported. Every consumer in this file goes through the wrapper below, and
+// handing the bare pattern out would let a caller outside repeat the judgement
+// this file just narrowed: the flag alone, with isOurCommand() skipped.
+const DELEGATION_GUARD_HOOK_PATTERN = /delegate --hook(?![\w-])/;
+
+/**
+ * Whether a settings.json hook command is THIS hook: both our executable in
+ * the command position and our flag.
+ *
+ * The flag alone is not enough. It says nothing about which program runs, so
+ * a hook the user registered themselves — `other-tool delegate --hook`, or a
+ * script of their own named `delegate` — matched, and `delegate off` deleted
+ * it. This repository has already shipped that bug once: CHANGELOG v3.46.1
+ * records `uninstall` removing `node ~/.claude/probe/sprag-probe.mjs` and
+ * `my-sprag-wrapper` because the check looked at the wrong part of the
+ * command. isOurCommand() is the fix that landed then, and it belongs here
+ * too. Install, remove and the status readout all go through this.
+ */
+export function isDelegationGuardHookCommand(command) {
+  return typeof command === 'string'
+    && isOurCommand(command)
+    && DELEGATION_GUARD_HOOK_PATTERN.test(command);
+}
+
+// Named for the feature, not the flag: `installDelegationHook()` above is
+// already taken by the route-scan PostToolUse hook, and it rewrites its own
+// matcher as the same 'Task|Agent' string. A one-word difference between the
+// two names (Delegate vs Delegation) once caused a call to the wrong hook to
+// go unnoticed, so this pair spells out which concern it belongs to
+// (delegation-guard.js's prompt rewrite) rather than staying terse.
+/**
+ * Whether this hook is registered, and when it is not, why — for the status
+ * readout, which otherwise reported "not registered" identically for a
+ * settings.json that has no hook and one this tool refused to touch. Only the
+ * second of those is something the user has to fix, and only this carries the
+ * reason out to them. Install and remove read and write the same file, so they
+ * keep their own traversal; what is shared is the predicate.
+ */
+export function delegationGuardHookState() {
+  const file = join(claudeUserDir(), 'settings.json');
+  if (!existsSync(file)) return { registered: false, path: file };
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { registered: false, path: file, reason: `unreadable JSON (${e.message})` };
+  }
+  const list = settings?.hooks?.PreToolUse;
+  if (list === undefined) return { registered: false, path: file };
+  if (!Array.isArray(list)) {
+    return { registered: false, path: file, reason: 'hooks.PreToolUse is not an array — fix settings.json manually' };
+  }
+  return {
+    registered: list.some((m) => Array.isArray(m?.hooks) && m.hooks.some((h) => isDelegationGuardHookCommand(h?.command))),
+    path: file,
+  };
+}
+
+export function installDelegationGuardHook() {
+  const dir = claudeUserDir();
+  const file = join(dir, 'settings.json');
+  mkdirSync(dir, { recursive: true });
+  // Remembered before the write: appending an entry to a settings file that
+  // was already there is an update, and reporting 'created' would tell the
+  // user their file is new when it is not.
+  const existed = existsSync(file);
+
+  let settings = {};
+  if (existed) {
+    try {
+      settings = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (e) {
+      return { path: file, action: 'skipped', reason: `unreadable JSON (${e.message})` };
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+  if (settings.hooks.PreToolUse !== undefined && !Array.isArray(settings.hooks.PreToolUse)) {
+    return { path: file, action: 'skipped', reason: 'hooks.PreToolUse is not an array — fix settings.json manually' };
+  }
+  const list = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
+  const already = list.some((m) =>
+    Array.isArray(m?.hooks) && m.hooks.some((h) => isDelegationGuardHookCommand(h?.command)),
+  );
+  if (already) return { path: file, action: 'exists' };
+
+  list.push({
+    matcher: 'Task|Agent',
+    hooks: [{ type: 'command', command: DELEGATION_GUARD_HOOK_COMMAND, timeout: 10 }],
+  });
+  settings.hooks.PreToolUse = list;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: existed ? 'updated' : 'created' };
+}
+
+export function removeDelegationGuardHook() {
+  const file = join(claudeUserDir(), 'settings.json');
+  if (!existsSync(file)) return { path: file, action: 'absent' };
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { path: file, action: 'skipped', reason: `unreadable JSON (${e.message})` };
+  }
+  const list = settings?.hooks?.PreToolUse;
+  if (!Array.isArray(list)) return { path: file, action: 'absent' };
+  // Per hook, not per matcher group — the same correction uninstallAll() above
+  // carries, for the same reason. Claude Code merges entries that share a
+  // matcher into one group, so filtering whole groups took the other tool's
+  // hook with ours whenever we were installed second. v3.46.1 and v3.51.0 both
+  // record that failure; a group survives here as long as something of
+  // somebody else's is left in it.
+  let touched = false;
+  const kept = [];
+  for (const m of list) {
+    if (!Array.isArray(m?.hooks)) { kept.push(m); continue; }
+    const hooks = m.hooks.filter((h) => !isDelegationGuardHookCommand(h?.command));
+    if (hooks.length === m.hooks.length) { kept.push(m); continue; }
+    touched = true;
+    if (hooks.length) kept.push({ ...m, hooks });
+  }
+  if (!touched) return { path: file, action: 'absent' };
+  if (kept.length === 0) delete settings.hooks.PreToolUse;
+  else settings.hooks.PreToolUse = kept;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: 'removed' };
+}
+
 /**
  * Undo what `install` did: every hook this tool registered, the statusline
  * entry when it is still ours, and the skill file.
@@ -689,7 +838,26 @@ export function uninstallAll({ purge = false } = {}) {
       result.removed.push('state directory');
     }
   } else {
+    // The state directory stays so a reinstall keeps ledgers and preferences,
+    // with one exception carved out just below.
     result.kept.push('state directory (savings ledgers, config, cache) — remove with --purge');
+    // delegate.enabled is not a preference, it is an assertion that a hook is
+    // registered — and the hooks were just removed above. `delegate on` goes
+    // out of its way to hold the invariant "flag on implies hook registered",
+    // installing first and leaving the flag alone when that fails; leaving the
+    // flag set here breaks the same invariant from the other side and makes
+    // status report `delegate: on, hook not registered` after a clean
+    // uninstall. Config it does not own is left untouched.
+    try {
+      const cfg = loadConfig();
+      if (cfg?.delegate?.enabled) {
+        cfg.delegate = { ...cfg.delegate, enabled: false };
+        saveConfig(cfg);
+        result.removed.push('delegate flag');
+      }
+    } catch {
+      // A config this cannot read is not worth failing an uninstall over.
+    }
   }
 
   return { ...result, action: 'removed' };