sprag-cli 3.62.0 → 3.64.0

package/src/commands/codex.js

@@ -1,6 +1,6 @@
 import { createArgs } from '../cli-args.js';
 import { configureCodexHooks } from '../codex-installer.js';
-import { initCodexHarness, uninitCodexHarness, codexHarnessStatus } from '../codex-harness.js';
+import { initCodexHarness, uninitCodexHarness, codexHarnessStatus, syncCodexKoreanBlock } from '../codex-harness.js';
 import { findProjectRoot, harnessPromote, harnessListRules, harnessRmRule, harnessPrune } from '../harness.js';
 import { loadConfig, saveConfig } from '../config.js';
 import { resolve } from 'node:path';
@@ -25,7 +25,9 @@ Usage: sprag <command> --agent codex [options]
   handoff [--cwd path]           Write Git state and Codex usage to HANDOFF-*.md
   saved [reset|undo]             Show, reset or restore the saved-money counters
   delegate on|off|status         Native model routing and SubagentStart guidance
+  delegate doctor               Local CLI features, model catalog and matched child activity
   delegate model <model>         Default target for spawns without an explicit model
+  delegate implementation       After design: resolve T1 with --from, --provider, --session
   delegate rules                Codex rules and shared delegation policies
   delegate shared on|off|status  Reuse approved policies; keep original scopes
   delegate shared map T1|T2     Map a tier: --from <parent> --model <target>
@@ -42,6 +44,7 @@ Usage: sprag <command> --agent codex [options]
   harness init|uninit|check|promote|list|rm|prune
                                 Rules in Codex AGENTS.md and ratchet files
   korean / cohesion / doc2md     Writing guidance and document conversion
+  doc2md savings                Codex document estimates; --format json for reasons and totals
   mode                          Shared label/color preferences
   install [--no-panel]           Register hooks and global harness; trust via /hooks
   uninstall                     Remove global integration; keep rules and shared state
@@ -141,6 +144,10 @@ export async function run({ args, version }) {
       console.log(`Hooks: ${report.hooks.error || `${report.hooks.events.filter((hook) => hook.registered).length}/${report.hooks.events.length} registered; trust unknown`}`);
       for (const hook of report.hooks.events) console.log(`  ${hook.event}: ${hook.registered ? 'registered' : 'missing/outdated; run sprag install --agent codex'}`);
       if (report.config.hooksDisabled) console.log('WARNING: user config disables hooks. Review features.hooks in Codex config.');
+      if (report.config.agentsDisabled) console.log('WARNING: user config disables agent tools. Review agents.enabled and features.multi_agent in Codex config.');
+      console.log(`Delegation: ${report.delegation.settled} completed, ${report.delegation.bound} bound, ${report.delegation.pending} pending, ${report.delegation.unclaimed} unclaimed offers (session)`);
+      console.log(`Agent tools: ${report.delegation.tools}`);
+      if (report.delegation.offers && !report.delegation.settled && !report.delegation.bound) console.log('Routing hints have no matched child. Check native subagent tool availability in the active session; preference and hook registration do not prove execution.');
       for (const [scope, harness] of Object.entries(report.harness)) console.log(`Harness ${scope}: ${harness.error ? terminalText(harness.error) : `${harness.configured}/${harness.total}`}`);
       console.log(`Session: ${report.session ? `${terminalText(report.session.id)} (${terminalText(report.session.model)})` : 'no matching rollout log'}`);
       console.log(`Panel: ${report.panel.live ? 'recent rendered frame observed' : 'no recent rendered frame'}`);
@@ -263,7 +270,7 @@ export async function run({ args, version }) {
   const statusline = hasFlag('--statusline') || format === 'statusline';
   if (statusline && (!cmd || cmd.startsWith('-'))) {
     const { createPanelReader, formatCodexPanel } = await import('../codex-panel.js');
-    const data = await createPanelReader({ root: selectedRoot, sessionId: getArg('--session'), days: numArg('--days', { dflt: 7, min: 0 }), hasFlag })();
+    const data = await createPanelReader({ root: selectedRoot, sessionId: getArg('--session'), days: numArg('--days', { dflt: 7, min: 0 }), hasFlag, version })();
     const columns = numArg('--columns', { dflt: process.stdout.columns || 100, min: 1, max: 10000 });
     const text = formatCodexPanel(data, { compact: true, columns: hasFlag('--single-line') ? 100000 : columns,
       rows: 10000, version, color: !hasFlag('--no-color') && !process.env.NO_COLOR && !!process.stdout.isTTY && data.color });
@@ -354,7 +361,7 @@ export async function run({ args, version }) {
     return runCodexPanel({
       read: createPanelReader({ root: getArg('--project') ? resolve(getArg('--project')) : root,
         sessionId: getArg('--session'), sessionFile: getArg('--session-file'), days: numArg('--days', { dflt: 7, min: 0 }), readBudget: readBudget.read,
-        readCachePolicy: hasFlag('--once') ? async (session) => {
+        version, refreshUpdate: !hasFlag('--once'), readCachePolicy: hasFlag('--once') ? async (session) => {
           const { readCodexCachePolicy } = await import('../codex-cache-policy.js');
           try { return readCodexCachePolicy(session) || await refreshCodexCachePolicy(session); }
           catch (e) { debug('codex:cache-policy', e); return null; }
@@ -364,7 +371,7 @@ export async function run({ args, version }) {
       fitRows: createInlinePanelResizer(),
       onFrame: (data) => {
         renderedSessionId = data.sessionId || data.session?.sessionId;
-        recordPanelState(panelRoot, 'frame', { status: 'rendered', pid: process.pid, sessionId: renderedSessionId });
+        recordPanelState(panelRoot, 'frame', { status: 'rendered', pid: process.pid, version, sessionId: renderedSessionId });
       },
       onClose: () => recordPanelState(panelRoot, 'frame', { status: 'closed', pid: process.pid, sessionId: renderedSessionId }),
     });
@@ -392,7 +399,7 @@ export async function run({ args, version }) {
         }
         return;
       }
-      const out = await codexHookOutput(getArg('--event'), payload);
+      const out = await codexHookOutput(getArg('--event'), payload, { version });
       if (out) console.log(JSON.stringify(out));
     } catch (e) { debug('codex:hook', e); /* Hook failures must not break the agent loop. */ }
     return;
@@ -408,6 +415,10 @@ export async function run({ args, version }) {
     if (process.env.CTS_NO_HARNESS !== '1') {
       const h = initCodexHarness({ root, scope: 'global' });
       console.log(`Codex harness: ${h.file}`);
+      try {
+        const k = syncCodexKoreanBlock({ cfg });
+        console.log(`Codex korean-style: ${k.file} (${k.action})`);
+      } catch (e) { debug('codex:korean-sync', e); }
     }
     try {
       const { preparePresetRatchet } = await import('../preset-ratchet.js');
@@ -426,9 +437,9 @@ export async function run({ args, version }) {
       const auto = parent ? autoCodexSharedTargets({ model: parent, provider }) : { targets: [], reason: 'Codex config names no default model' };
       console.log(auto.targets.length
         ? `Delegation tiers for ${parent} on ${provider} (auto): ${auto.targets.map((t) => `${t.tier} -> ${t.model}`).join(', ')}. Change: sprag delegate shared status --agent codex`
-        : `Delegation tiers: not resolved yet (${auto.reason}). They resolve once a cheaper priced model has run in Codex, or map one: sprag delegate shared map T2 --from <parent> --model <target> --agent codex`);
+        : `Delegation tiers: not resolved yet (${auto.reason}). They resolve once Codex lists or has run a cheaper priced model, or map one: sprag delegate shared map T2 --from <parent> --model <target> --agent codex`);
     } catch (e) { debug('codex:auto-tiers', e); }
-    console.log('First-use delegation: sprag seed --agent codex to approve policies, then sprag delegate on --agent codex. No Claude installation is required.');
+    console.log('First-use delegation: sprag seed --agent codex to approve policies; delegation is on by default (turn off: sprag delegate off --agent codex). No Claude installation is required.');
     console.log('Korean guidance is opt-in: sprag korean on --agent codex');
     return;
   }
@@ -436,8 +447,11 @@ export async function run({ args, version }) {
     if (hasFlag('--purge')) throw new Error('Codex uninstall keeps shared Sprag state; --purge is not supported.');
     const hook = configureCodexHooks({ remove: true });
     const h = uninitCodexHarness({ root, scope: 'global' });
+    const { installPanelShell } = await import('../codex-panel-shell.js');
+    const shellFile = installPanelShell({ remove: true });
     console.log(`Codex hooks: ${hook.file} (${hook.action})`);
     console.log(`Codex harness: ${h.file} (${h.removed ? 'removed' : 'absent'})`);
+    console.log(`Codex shell wrapper removed: ${shellFile}. Open a new shell to use the standalone codex command.`);
     console.log('Ratchet rules, project harnesses, backups, and shared Sprag state kept.');
     return;
   }
@@ -513,6 +527,7 @@ export async function run({ args, version }) {
     const { setKoreanStyleEnabled } = await import('../korean-style.js');
     if (args[1] === 'on') configureCodexHooks();
     setKoreanStyleEnabled(args[1] === 'on');
+    try { syncCodexKoreanBlock({ cfg: loadConfig() }); } catch (e) { debug('codex:korean-sync', e); }
     console.log(`Korean guidance: ${args[1]} (shared Sprag preference). Review/trust the Sprag hooks in Codex /hooks.`);
     return;
   }
@@ -542,9 +557,27 @@ export async function run({ args, version }) {
     console.log('Prompt conversion, supported reads, and document/cache write guards require trusted hooks. Review in Codex /hooks.');
     return;
   }
+  if (cmd === 'doc2md' && args[1] === 'savings') {
+    const { codexDocumentTotals } = await import('../codex-doc2md-ledger.js');
+    const totals = codexDocumentTotals();
+    if (format === 'json') console.log(JSON.stringify({ agent: 'codex', ...totals }, null, 2));
+    else {
+      console.log(`Doc2md saved ${totals.savings.priced ? `${signedUsd(totals.savings.total, 4)} estimated` : 'n/a'} | ${totals.docs} docs, ${totals.savings.unpriced} unpriced`);
+      console.log('Estimate: Office XML versus prepared Markdown at UTF-8 bytes/4, priced at the recorded Codex model input rate. Not billed savings.');
+      for (const [reason, count] of Object.entries(totals.savings.reasons)) console.log(`${reason}: ${count}`);
+    }
+    return;
+  }
   if (cmd === 'doc2md' && args[1] && !args[1].startsWith('-') && args[1] !== 'install-converter') {
     const { convertCodexDocument } = await import('../codex-doc2md.js');
-    const result = convertCodexDocument(resolve(args[1]));
+    const sessionId = getArg('--session') || process.env.CODEX_THREAD_ID;
+    let identity = {};
+    if (sessionId) {
+      const { createPanelReader } = await import('../codex-panel.js');
+      const { session } = await createPanelReader({ root, sessionId })();
+      if (session) identity = { model: session.model, provider: session.provider };
+    }
+    const result = convertCodexDocument(resolve(args[1]), identity);
     if (!result.ok) {
       console.error(`Doc2md failed: ${result.reason}`);
       if (result.reason === 'no-markitdown') console.error('Run sprag doc2md install-converter --agent codex, then retry.');
@@ -555,21 +588,25 @@ export async function run({ args, version }) {
     console.log(`Source ${result.meta.size} bytes; Markdown ${result.meta.markdownBytes} bytes.`);
     if (result.meta.clipped || result.meta.truncated) console.log('Text extraction is incomplete; inspect the source for omitted content.');
     if (result.meta.note) console.log(result.meta.note);
+    const saving = result.meta.codexSaving;
+    console.log(`Doc2md saved ${Number.isFinite(saving?.usd) ? `${signedUsd(saving.usd, 4)} estimated (Office XML vs Markdown, bytes/4)` : `n/a (${saving?.reason || 'unknown'})`}`);
     return;
   }
   if (cmd === 'upgrade') {
-    const command = 'npm i -g sprag-cli --ignore-scripts';
+    const { upgradeInstructions } = await import('../update-notice.js');
+    const [command, setup] = upgradeInstructions('codex');
     if (!hasFlag('--print')) throw new Error(`For a Codex-only upgrade, run ${command}, then sprag install --agent codex.`);
     console.log(command);
-    console.log('sprag install --agent codex');
+    console.log(setup);
     return;
   }
   const shared = new Set(['korean', 'cohesion', 'doc2md', 'mode', 'feedback', 'update-check']);
   if (shared.has(cmd)) {
     if (args.some((a) => a.startsWith('--hook'))) throw new Error('Use codex-hook for Codex hook payloads.');
     if (cmd === 'cohesion' && args[1] === 'on') configureCodexHooks();
+    if (cmd === 'korean' && args[1] === 'reply' && args[2] === 'on') configureCodexHooks();
     const { userDataDir } = await import('../paths.js');
-    const result = await (await import(`./${cmd}.js`)).run({ args, getArg, hasFlag, numArg, version, dataDir: userDataDir() });
+    const result = await (await import(`./${cmd}.js`)).run({ args, getArg, hasFlag, numArg, version, agent: 'codex', dataDir: userDataDir() });
     if (cmd === 'cohesion' && args[1] === 'on') console.log('Review/trust the Sprag hooks in Codex /hooks.');
     return result;
   }

package/src/commands/doc2md.js

@@ -104,6 +104,7 @@ export async function run({ args, hasFlag }) {
     console.log(res.action === 'skipped'
       ? `✗ ${res.reason}`
       : `✓ Read hook ${res.action} (${res.path})`);
+    if (res.modReason) console.log(`  mod: not registered — ${res.modReason}`);
     // A registered hook with no converter behind it does nothing at all, and
     // says nothing about it either, which reads as a broken feature. Offer the
     // one command that closes the gap right where the gap is visible.
@@ -160,6 +161,17 @@ export async function run({ args, hasFlag }) {
   console.log(`  converter: ${python ? `markitdown via ${python}` : `not installed — ${doc2md.INSTALL_HINT}`}`);
   console.log(`  cache:     ${dir} (${cached} file(s))`);
   console.log(`  hook:      ${hookRegistered() ? 'registered on Read' : 'not registered'}`);
+  // The mod has the same two halves as the hook: `doc2md on` can leave it out
+  // (a shell value of the variable, a /plugin copy) while the hook goes in.
+  // A path the user added to their own shell variable counts as registered.
+  {
+    const { modDirsState, modDir, DOC2MD_MOD } = await import('../installer.js');
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const inShell = (process.env.CLAUDE_CODE_PLUGIN_DIRS || '').split(sep).includes(modDir(DOC2MD_MOD));
+    console.log(`  mod:       ${modDirsState()[DOC2MD_MOD] || inShell
+      ? 'registered (Claude Code 2.1.287+ reads the Markdown in the same Read)'
+      : 'not registered — `doc2md on` registers it or says why not'}`);
+  }
   console.log('');
   if (!python) console.log(`Install the converter: ${doc2md.INSTALL_HINT}`);
   console.log('Enable with: sprag doc2md on');

package/src/commands/install.js

@@ -85,6 +85,8 @@ export async function run({ hasFlag }) {
     print('skill', r.skill);
     print('SessionStart hook (route-scan)', r.sessionStartHook);
     print('PostToolUse hook (delegation rescan)', r.delegationHook);
+    print('mod (delegation meter, Claude Code 2.1.287+)', r.delegationMeterMod);
+    if (r.delegationMeterMod.reason) console.log(`    ${r.delegationMeterMod.reason}`);
     print('UserPromptSubmit hook (brief)', r.briefHook);
     {
       let s = r.statusline;
@@ -333,6 +335,7 @@ export async function run({ hasFlag }) {
         console.log(res.action === 'skipped'
           ? `  doc2md: ${res.reason}`
           : `  doc2md: Read/Write hook ${res.action} (${res.path})`);
+        if (res.modReason) console.log(`  doc2md: mod not registered — ${res.modReason}`);
         console.log(lang === 'ko'
           ? `           대상 형식: ${doc2md.TARGET_EXTENSIONS.join(' ')} — 모델이 읽기 전에 Markdown으로 변환합니다.`
           : `           formats: ${doc2md.TARGET_EXTENSIONS.join(' ')} — converted to Markdown before the model reads them.`);
@@ -449,6 +452,11 @@ export async function run({ hasFlag }) {
           if (process.env.CTS_NO_HARNESS !== '1') {
             const h = initCodexHarness({ scope: 'global' });
             console.log(`  codex: harness ${h.file}`);
+            try {
+              const { syncCodexKoreanBlock } = await import('../codex-harness.js');
+              const k = syncCodexKoreanBlock({ cfg: config });
+              console.log(`  codex: korean-style ${k.action} (${k.file})`);
+            } catch (e) { debug('install:codex-korean', e); }
           }
           try { (await import('../preset-ratchet.js')).preparePresetRatchet({ agent: 'codex' }); } catch (e) { debug('install:codex-preset', e); }
           if (!manual) {

package/src/commands/korean.js

@@ -53,6 +53,7 @@ export async function run({ args, hasFlag }) {
   const sub = args[1] || 'status';
   const ks = await import('../korean-style.js');
   const { userLanguage, loadConfig, saveConfig } = await import('../config.js');
+  const { debug } = await import('../debug.js');
   const lang = userLanguage();
 
   // PostToolUse hook. Claude Code feeds the tool-call payload on stdin; we
@@ -222,6 +223,8 @@ export async function run({ args, hasFlag }) {
   if (sub === 'on' || sub === 'off') {
     const enabled = sub === 'on';
     ks.setKoreanStyleEnabled(enabled);
+    // Codex reads the guide from its global AGENTS.md; keep that block in step.
+    try { (await import('../codex-harness.js')).syncCodexKoreanBlock({ cfg: loadConfig() }); } catch (e) { debug('korean:codex-sync', e); }
     const {
       installKoreanLintHook, removeKoreanLintHook,
       installReplyLanguageHook, removeReplyLanguageHook,

package/src/commands/route-scan.js

@@ -360,48 +360,14 @@ export async function run({ args, hasFlag, numArg }) {
       // — the refresh runs detached off the statusline path, never here.
       let updateBlock = null;
       try {
-        const { updateStatus, maybeSpawnUpdateCheck, SESSION_START_CHECK_INTERVAL_MS } = await import('../update-check.js');
+        const { updateOffer } = await import('../update-notice.js');
         const pkgVersion = readPackageVersion();
         // Session start is the one moment where a stale cache matters most, so
         // kick the detached refresh here too, on a shorter interval than the
         // statusline's 24h: releases can land several times a day, and a
         // session opened that afternoon should hear about them. It lands in
         // time for the statusline and for the next session, not for this line.
-        if (pkgVersion) maybeSpawnUpdateCheck(pkgVersion, { intervalMs: SESSION_START_CHECK_INTERVAL_MS });
-        const u = pkgVersion ? updateStatus(pkgVersion) : null;
-        // `dismissed` is the whole point of asking once: a user who said no to
-        // this version must not be asked again every `/clear`.
-        if (u && u.available && !u.dismissed) {
-          // What the release adds, when we managed to read it. "A newer version
-          // exists" is not a reason to upgrade; the reason is in this list, and
-          // without it the user is being asked to decide on no information.
-          const notes = Array.isArray(u.highlights) ? u.highlights : [];
-          const koNotes = notes.length
-            ? ['  이 버전에서 새로 생긴 것:', ...notes.map((n) => `    · ${n}`)]
-            : [];
-          const enNotes = notes.length
-            ? ['  What this release adds:', ...notes.map((n) => `    · ${n}`)]
-            : [];
-          updateBlock = lang === 'ko'
-            ? [
-                `[sprag update] 새 버전이 나와 있습니다: v${u.current} → ${u.latest}.`,
-                ...koNotes,
-                notes.length
-                  ? '  위 내용을 사용자에게 보여 주고 업그레이드할지 물어보십시오. 승낙하면 아래 명령을 실행하고, 묻지 않고 설치하지는 마십시오.'
-                  : '  사용자에게 지금 업그레이드할지 물어보고, 승낙하면 아래 명령을 실행하십시오. 묻지 않고 설치하지는 마십시오.',
-                '  sprag upgrade                  # 업그레이드 실행',
-                '  sprag update-check --dismiss   # 사용자가 원치 않으면 (다음 버전이 나올 때까지 다시 묻지 않습니다)',
-              ].join('\n')
-            : [
-                `[sprag update] A newer version is available: v${u.current} → ${u.latest}.`,
-                ...enNotes,
-                notes.length
-                  ? '  Show that list to the user and ask whether to upgrade. Run the command below only if they agree; do not install without asking.'
-                  : 'Ask the user whether to upgrade now, and run the command below only if they agree. Do not install without asking.',
-                '  sprag upgrade                  # perform the upgrade',
-                '  sprag update-check --dismiss   # if they decline (stays quiet until a newer release)',
-              ].join('\n');
-        }
+        if (pkgVersion) updateBlock = updateOffer(pkgVersion, { lang });
       } catch (e) { debug('route-scan:update-check', e); /* the offer is optional */ }
 
       if (open.length === 0 && reviewRules.length === 0) {

package/src/commands/saved.js

@@ -22,7 +22,7 @@ const SCOPE_SETS = {
   codex: ['codex-routing', 'codex-docs'],
 };
 
-/** Totals since each scope's mark: { usd } for money counters, { docs } for the Codex document counter. */
+/** Totals since each scope's mark; Codex keeps unavailable estimates explicit. */
 async function currentTotals(scope, dir) {
   if (scope === 'routing') {
     const { delegationSavedTotals } = await import('../savings-ledger.js');
@@ -34,10 +34,12 @@ async function currentTotals(scope, dir) {
   }
   if (scope === 'codex-routing') {
     const { codexRoutingSavedTotals } = await import('../codex-ledger.js');
-    return { usd: codexRoutingSavedTotals({ dir }).total };
+    const totals = codexRoutingSavedTotals({ dir });
+    return { usd: totals.priced ? totals.total : null, unpriced: totals.runs - totals.priced };
   }
   const { codexDocumentTotals } = await import('../codex-doc2md-ledger.js');
-  return { docs: codexDocumentTotals({ dir }).docs };
+  const totals = codexDocumentTotals({ dir });
+  return { docs: totals.docs, usd: totals.savings.priced ? totals.savings.total : null, unpriced: totals.savings.unpriced };
 }
 
 /**
@@ -75,7 +77,11 @@ export async function run({ args, hasFlag, agent = 'claude', dir: dirArg, rescan
   const suffix = agent === 'codex' ? ' --agent codex' : '';
 
   const money = (v) => (v < 0 ? `-$${(-v).toFixed(2)}` : `$${v.toFixed(2)}`);
-  const fmtTotal = (t) => (t.docs !== undefined ? (ko ? `${t.docs}건` : `${t.docs} doc(s)`) : money(t.usd));
+  const fmtTotal = (t) => {
+    const value = Number.isFinite(t.usd) ? money(t.usd) : 'n/a';
+    return t.docs !== undefined ? `${ko ? `${t.docs}건` : `${t.docs} doc(s)`}, ${value} (${ko ? 'XML 대비 추정' : 'XML estimate'}; ${t.unpriced} unpriced)`
+      : `${value}${t.unpriced ? ` +${t.unpriced} unpriced` : ''}`;
+  };
   const fmtTime = (ms) => new Date(ms).toLocaleString(ko ? 'ko-KR' : 'en-US');
   const label = (scope) => ({
     routing: ko ? '라우팅 절감' : 'Routing saved',

package/src/commands/update-check.js

@@ -11,7 +11,7 @@
  * command detached so the render itself stays offline and instant.
  */
 
-export async function run({ hasFlag, version }) {
+export async function run({ hasFlag, version, agent = 'claude' }) {
   const {
     updateStatus,
     refreshUpdateState,
@@ -56,7 +56,10 @@ export async function run({ hasFlag, version }) {
     console.log(lang === 'ko'
       ? `새 버전이 있습니다: v${version} → ${s.latest}`
       : `Update available: v${version} → ${s.latest}`);
-    console.log(lang === 'ko'
+    if (agent === 'codex') {
+      const { upgradeInstructions } = await import('../update-notice.js');
+      for (const command of upgradeInstructions(agent)) console.log(command);
+    } else console.log(lang === 'ko'
       ? `업그레이드: ${upgradeCommand()}   (또는 sprag upgrade)`
       : `Upgrade with: ${upgradeCommand()}   (or: sprag upgrade)`);
     if (s.dismissed) {
@@ -71,7 +74,7 @@ export async function run({ hasFlag, version }) {
     : `Up to date (v${version}).`);
   if (!s.latest) {
     console.log(lang === 'ko'
-      ? `아직 확인된 기록이 없습니다. 지금 확인하려면: sprag update-check --refresh (기록 파일: ${updateStatePath()})`
-      : `No check has completed yet. Run: sprag update-check --refresh (state: ${updateStatePath()})`);
+      ? `아직 확인된 기록이 없습니다. 지금 확인하려면: sprag update-check --refresh${agent === 'codex' ? ' --agent codex' : ''} (기록 파일: ${updateStatePath()})`
+      : `No check has completed yet. Run: sprag update-check --refresh${agent === 'codex' ? ' --agent codex' : ''} (state: ${updateStatePath()})`);
   }
 }

package/src/implementation-delegation.js

@@ -0,0 +1,34 @@
+/** Shared policy, rendered with each client's native model selector. */
+export function implementationDelegationRule(agent = 'claude', lang = 'en') {
+  const target = agent === 'codex'
+    ? 'the resolved T1 model for the current parent model and provider (explicit mapping first, automatic resolution otherwise)'
+    : 'a model: sonnet subagent';
+  if (lang === 'ko') return [
+    '- **구현 분업**: 여러 파일을 고칠 때 설계와 스펙 확정은 메인 모델이 맡습니다.',
+    `  구현은 ${agent === 'codex' ? '현재 부모 모델과 프로바이더의 T1 모델' : 'model: sonnet 서브에이전트'}에 위임합니다.`,
+    '  Claude는 sonnet을 쓰고, Codex는 명시적 T1 매핑을 우선하며 없으면 자동 해석한 T1을 씁니다.',
+    '  두 모델의 성능이 같다고 가정하지 않으며 haiku나 T2에 구현을 맡기지 않습니다.',
+    '  위임 프롬프트에는 설계, 수정할 파일, 제약, 완료 기준, 테스트 명령, 예산과',
+    '  권장 모델 및 선택 이유를 적어 다른 문맥 없이 실행할 수 있게 합니다.',
+    '  이미 읽은 파일의 약 50줄 이하 변경이나 의존 단계가 하나인 짧은 구현은',
+    '  분업 비용을 고려해 메인 모델이 직접 처리합니다. Codex에서 T1을 해석하지 못하면',
+    '  메인이 이어받습니다. 위임이 꺼져 있거나 하위 모델 또는 위임 도구를 사용할 수',
+    '  없어도 메인이 처리하고 그 이유를 알립니다.',
+    '  메인 모델은 위임 완료를 기다리고 같은 구현을 중복 실행하지 않습니다.',
+    '  반환된 diff와 테스트 결과를 직접 검증한 뒤 완료로 보고합니다.',
+  ].join('\n');
+  return [
+    '- **Implementation split**: the main model fixes the design and specification,',
+    `  then delegates multi-file implementation to ${target}.`,
+    '  Claude uses sonnet; Codex uses its resolved T1, not a presumed Sonnet equivalent.',
+    '  Never use haiku or T2 for implementation. Give a self-contained specification',
+    '  with owned files, constraints, completion criteria, test commands, a budget,',
+    '  and the recommended model with a one-line reason. Changes of roughly',
+    '  50 lines or less in files already in context, or one short dependency chain,',
+    '  stay on the main model. Codex also stays on the main model if T1 is unresolved.',
+    '  If delegation is off, or the model or subagent tools are unavailable,',
+    '  stay on the main model and say why.',
+    '  Wait for the child instead of duplicating its implementation. The main model',
+    '  verifies the diff and actual test results before reporting completion.',
+  ].join('\n');
+}

package/src/installer.js

@@ -16,7 +16,8 @@
 import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync, rmSync, copyFileSync, renameSync, realpathSync, statSync } 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 { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { claudeUserDir, userDataDir } from './paths.js';
 
 /**
@@ -692,6 +693,122 @@ export function removeReplyLanguageHook() {
   return { path: file, action: 'removed' };
 }
 
+// Mods: plugin folders shipped in this package's mod/ directory, which Claude
+// Code (2.1.287 and later) runs inside its own process. They are loaded through
+// CLAUDE_CODE_PLUGIN_DIRS in the env block of ~/.claude/settings.json, the one
+// way to load a plugin folder that needs neither a marketplace nor the `claude`
+// CLI at install time, so `npm i -g` stays the whole setup. An older Claude
+// Code ignores the variable, and the settings hooks keep doing the work alone.
+//
+// The variable holds absolute paths, so an entry goes stale when the package
+// moves (a Node version switch under nvm puts it in another global root). An
+// entry counts as ours by its last two segments, `mod/<a name below>`, and
+// adding a mod first drops every older path to it, so a reinstall repairs the
+// list instead of growing it. Other folders in the variable are left alone.
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PLUGIN_DIRS_ENV = 'CLAUDE_CODE_PLUGIN_DIRS';
+export const DOC2MD_MOD = 'sprag-doc2md';
+export const DELEGATION_METER_MOD = 'sprag-delegation-meter';
+export const MOD_NAMES = [DOC2MD_MOD, DELEGATION_METER_MOD];
+
+export function modDir(name) {
+  return join(PACKAGE_ROOT, 'mod', name);
+}
+
+const pluginDirsSeparator = () => (process.platform === 'win32' ? ';' : ':');
+
+function isOurModEntry(entry, names) {
+  const parts = String(entry).split(/[\\/]/).filter(Boolean);
+  return parts.length >= 2 && parts[parts.length - 2] === 'mod' && names.includes(parts[parts.length - 1]);
+}
+
+function pluginDirEntries(settings) {
+  const value = isPlainObject(settings.env) ? settings.env[PLUGIN_DIRS_ENV] : undefined;
+  return typeof value === 'string' ? value.split(pluginDirsSeparator()).filter(Boolean) : [];
+}
+
+/**
+ * Point CLAUDE_CODE_PLUGIN_DIRS at this package's copy of one mod, in place on
+ * a settings object read by the caller. Returns true when the object changed,
+ * false when it already held exactly that, or a reason string when the mod is
+ * better left out: `env` is not something this can safely extend, or the user
+ * already loads mods in a way a write here would break or duplicate.
+ *
+ * `inherited` is the variable as this process received it. When settings.json
+ * has no value of its own, that is the user's shell value. Claude Code's docs
+ * say a settings `env` entry replaces the inherited value in most sessions, so
+ * a value written here would stop the user's own mods from loading; were this
+ * variable one of the exceptions, ours would be ignored instead. Either way
+ * the write is wrong, so the case is refused with the path to add by hand.
+ */
+function addModDir(settings, name, inherited = process.env[PLUGIN_DIRS_ENV]) {
+  if (settings.env !== undefined && !isPlainObject(settings.env)) return 'env is not an object — fix settings.json manually';
+  const current = settings.env?.[PLUGIN_DIRS_ENV];
+  if (current !== undefined && typeof current !== 'string') return `env.${PLUGIN_DIRS_ENV} is not a string — fix settings.json manually`;
+  // A copy installed through /plugin would run beside this one, every hook twice.
+  const installed = isPlainObject(settings.enabledPlugins)
+    ? Object.keys(settings.enabledPlugins).find((id) => id.split('@')[0] === name && settings.enabledPlugins[id])
+    : undefined;
+  if (installed) return `${name} is already installed as the plugin ${installed} — that copy stays the one that runs`;
+  const target = modDir(name);
+  const sep = pluginDirsSeparator();
+  if (current === undefined && typeof inherited === 'string') {
+    const theirs = inherited.split(sep).filter((e) => e && !isOurModEntry(e, MOD_NAMES));
+    if (theirs.length) {
+      return `${PLUGIN_DIRS_ENV} is set in your shell (${theirs.join(sep)}), and a value in settings.json would replace it — add ${target} to that variable yourself`;
+    }
+  }
+  const before = pluginDirEntries(settings);
+  const stale = before.filter((e) => e !== target && isOurModEntry(e, [name]));
+  if (before.includes(target) && stale.length === 0) return false;
+  const entries = [...before.filter((e) => !isOurModEntry(e, [name])), target];
+  settings.env = { ...(settings.env || {}), [PLUGIN_DIRS_ENV]: entries.join(sep) };
+  return true;
+}
+
+/**
+ * Drop every entry of the named mods, wherever it points. The variable goes
+ * when nothing is left in it, and `env` when this emptied it. Returns whether
+ * the object changed.
+ */
+function dropModDirs(settings, names) {
+  const before = pluginDirEntries(settings);
+  const kept = before.filter((e) => !isOurModEntry(e, names));
+  if (kept.length === before.length) return false;
+  if (kept.length) settings.env[PLUGIN_DIRS_ENV] = kept.join(pluginDirsSeparator());
+  else delete settings.env[PLUGIN_DIRS_ENV];
+  if (Object.keys(settings.env).length === 0) delete settings.env;
+  return true;
+}
+
+/** Which mods settings.json currently loads from this package's own copy. */
+export function modDirsState() {
+  const read = readSettings(join(claudeUserDir(), 'settings.json'));
+  const entries = read.state === 'ok' ? pluginDirEntries(read.settings) : [];
+  return Object.fromEntries(MOD_NAMES.map((name) => [name, entries.includes(modDir(name))]));
+}
+
+// The delegation meter only observes (see mod/sprag-delegation-meter), so it
+// ships on with the rest of installAll(), beside the PostToolUse hook that
+// feeds the transcript-based ledger it is measured against. uninstallAll()
+// takes it out with every other mod.
+export function installDelegationMeterMod() {
+  const dir = claudeUserDir();
+  const file = join(dir, 'settings.json');
+  mkdirSync(dir, { recursive: true });
+  const read = readSettings(file);
+  if (read.state === 'unusable') return { path: file, action: 'skipped', reason: read.reason };
+  const settings = read.settings;
+  const changed = addModDir(settings, DELEGATION_METER_MOD);
+  if (typeof changed === 'string') return { path: file, action: 'skipped', reason: changed };
+  if (!changed) return { path: file, action: 'exists' };
+  const writeProblem = writeSettings(file, settings);
+  if (writeProblem) return { path: file, action: 'skipped', reason: writeProblem };
+  // The action names what happened to the file, as installDelegationGuardHook's
+  // does: one entry added to a settings.json already there is an update.
+  return { path: file, action: read.state === 'absent' ? 'created' : 'updated' };
+}
+
 // Registers the PreToolUse hook that converts attached documents to Markdown
 // before the model reads them. PreToolUse rather than PostToolUse because the
 // point is to intervene before a pptx lands in the context window; afterwards
@@ -775,14 +892,22 @@ export function installDoc2mdHook() {
     }
   }
 
-  if (!hasReadHook || addedPrompt || addedWriteGuard) {
+  // The mod answers a document Read with the converted Markdown in the same
+  // call, where the hook above can only refuse it (mod/sprag-doc2md). It rides
+  // this hook's on and off so the two never disagree about doc2md being on. An
+  // `env` this cannot extend costs only the mod: the hooks still go in.
+  const modChange = addModDir(settings, DOC2MD_MOD);
+  const addedMod = modChange === true;
+  const modNote = typeof modChange === 'string' ? { modReason: modChange } : {};
+
+  if (!hasReadHook || addedPrompt || addedWriteGuard || addedMod) {
     {
       const writeProblem = writeSettings(file, settings);
       if (writeProblem) return { path: file, action: 'skipped', reason: writeProblem };
     }
-    return { path: file, action: hasReadHook ? 'updated' : 'created' };
+    return { path: file, action: hasReadHook ? 'updated' : 'created', ...modNote };
   }
-  return { path: file, action: 'exists' };
+  return { path: file, action: 'exists', ...modNote };
 }
 
 export function removeDoc2mdHook() {
@@ -805,6 +930,7 @@ export function removeDoc2mdHook() {
     if (kept.length === 0) delete settings.hooks[event];
     else settings.hooks[event] = kept;
   }
+  if (dropModDirs(settings, [DOC2MD_MOD])) touched = true;
   if (!touched) return { path: file, action: 'absent' };
   {
     const writeProblem = writeSettings(file, settings);
@@ -1022,6 +1148,10 @@ export function uninstallAll({ purge = false } = {}) {
     }
     if (isPlainObject(settings.hooks) && Object.keys(settings.hooks).length === 0) delete settings.hooks;
 
+    // Mods are found by their folder name, so a path left by an older install
+    // location goes with the current one.
+    if (dropModDirs(settings, MOD_NAMES)) result.removed.push(`env.${PLUGIN_DIRS_ENV} (mods)`);
+
     // Nothing of ours in the file means nothing to rewrite (and no backup to churn).
     if (result.removed.length > 0) {
       const writeProblem = writeSettings(file, settings);
@@ -1116,6 +1246,7 @@ export function installAll({ force = false } = {}) {
     statusline: installStatusline({ force }),
     sessionStartHook: installSessionStartHook(),
     delegationHook: installDelegationHook(),
+    delegationMeterMod: installDelegationMeterMod(),
     briefHook: installBriefHook(),
     cacheMonitorMigration: migrateLegacyCacheMonitorHook(),
     legacy: removeLegacyCommand(),

package/src/model-rules.js

@@ -36,6 +36,7 @@ import { userLanguage } from './config.js';
 import { agentPhrase, agentPhraseEn } from './agents.js';
 import { writeStateFile } from './state-file.js';
 import { signedUsd } from './money.js';
+import { implementationDelegationRule } from './implementation-delegation.js';
 
 // Post-promotion delegated-category error rate above this flags the rule
 // for review (rule-health). Calibrated against local T0 avg error incidence.
@@ -267,15 +268,7 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
     '- **위임 배치**: 서브에이전트 비용의 지배 항은 생성이 아니라 컨텍스트',
     '  적재다. 같은 파일들을 읽어야 하는 작업 여러 개는 에이전트 하나에 묶어',
     '  보내고, 읽는 영역이 다른 작업만 나눈다.',
-    '- **구현 분업**: 여러 파일에 걸친 구현은 설계·스펙 확정은 메인 모델이 하고,',
-    '  출력 토큰이 많은 실제 코드 작성은 스펙을 자기완결적으로(참조 없이 실행',
-    '  가능하게) 적어 model: sonnet 서브에이전트에 위임한다. haiku에는 맡기지',
-    '  않는다. 위임 프롬프트에는 작업별 권장 모델과 그 이유를 한 줄로 적는다.',
-    '  스펙을 쓴 쪽이 난도를 제일 잘 알기 때문이다. 단, 이미 컨텍스트에 있는',
-    '  파일의 약 50줄 이하 변경이나 의존 단계가 하나뿐인 짧은 구현은 분해',
-    '  오버헤드가 더 크므로 메인 모델이 직접 한다. 위임한 구현이 돌아오면 메인',
-    '  모델이 diff와 테스트 결과를 검증하고 나서 완료로 보고한다. 이 검증',
-    '  비용까지가 위임 비용이다.',
+    implementationDelegationRule('claude', lang),
     '- **에스컬레이션**: 같은 에러 2회 반복, 답이 복수 후보로 갈림, 서브에이전트가',
     '  질문을 멈추고 헛도는 징후가 보이면 즉시 인계한다. 대응 순서는',
     '  ① 재지시 후 재시도 → ② 한 티어 상향 → ③ 메인 모델이 직접 수습.',
@@ -326,17 +319,7 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
     '- **Batching**: a subagent\'s dominant cost is context ingestion, not',
     '  generation. Bundle tasks that read the same files into one agent; split',
     '  only when the areas they read differ.',
-    '- **Implementation split**: for multi-file implementation, the main model',
-    '  fixes the design and writes a self-contained spec (executable without',
-    '  back-references), then delegates the output-heavy code writing to a',
-    '  model: sonnet subagent — never haiku. The delegation prompt names the',
-    '  recommended model per task with a one-line why: whoever wrote the spec',
-    '  knows the difficulty best. A change of roughly 50 lines or less in files',
-    '  already in context, or a short implementation with a single dependency',
-    '  chain, stays on the main model: decomposition overhead outweighs the',
-    '  saving. When a delegated implementation comes back, the',
-    '  main model verifies the diff and test results before reporting done —',
-    '  that verification is part of the delegation cost.',
+    implementationDelegationRule('claude', lang),
     '- **Escalation**: hand off immediately on the same error twice, an answer',
     '  splitting into multiple candidates, or a subagent spinning without asking',
     '  questions. Order: ① re-instruct and retry → ② move up one tier → ③ the',