claude-token-saver 3.30.1 → 3.34.0

package/src/commands/install.js

@@ -16,9 +16,8 @@ class SkipStep extends Error {}
 
 export async function run({ hasFlag }) {
     const { installAll } = await import('../installer.js');
-    const { userLanguage } = await import('../config.js');
+    const { userLanguage, languageDecided, setUserLanguage } = await import('../config.js');
     const { canPrompt, confirm } = await import('../prompt.js');
-    const lang = userLanguage();
     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.
@@ -26,6 +25,45 @@ export async function run({ hasFlag }) {
     // 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');
+
+    // 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
+    // fell back to English with no question asked, so a Korean user read English
+    // reports until they happened to find `mode ko`.
+    //
+    // The locale is the default, not the answer: a terminal user gets to
+    // overrule it either way. An unattended install records the detected locale
+    // rather than leaving the setting blank, because "blank" silently means
+    // English — the one outcome a Korean-locale machine should not get by
+    // default. Already decided means never asked again.
+    try {
+      if (!languageDecided() && !process.env.CTS_LANG) {
+        const { koreanLocaleDetected } = await import('../korean-style.js');
+        const detected = koreanLocaleDetected() ? 'ko' : 'en';
+        console.log('');
+        console.log('  language: reports, warnings and session briefings are written in this language.');
+        console.log(`            detected locale: ${detected === 'ko' ? 'Korean' : 'not Korean (English)'}`);
+        let chosen = detected;
+        if (interactive) {
+          const ko = await confirm('            Use Korean? (no = English)', { defaultValue: detected === 'ko' });
+          chosen = ko ? 'ko' : 'en';
+        }
+        setUserLanguage(chosen);
+        console.log(`  language: set to ${chosen === 'ko' ? '한국어' : 'English'} — change it any time with \`claude-token-saver mode lang=${chosen === 'ko' ? 'en' : 'ko'}\``);
+      } else if (process.env.CTS_LANG) {
+        // Escape hatch for scripted installs, which cannot answer a prompt but
+        // do know which language the machine's user reads.
+        const forced = setUserLanguage(process.env.CTS_LANG);
+        console.log('');
+        console.log(forced
+          ? `  language: set to ${forced} (CTS_LANG)`
+          : `  language: ignored CTS_LANG=${process.env.CTS_LANG} — use 'ko' or 'en'`);
+      }
+    } catch (e) {
+      debug('install:language', e); // the English fallback still works
+    }
+    const lang = userLanguage();
+
     const print = (kind, r) => {
       const verb = r.action === 'exists' ? 'already exists' : r.action;
       console.log(`  ${kind}: ${r.path} (${verb})`);
@@ -214,6 +252,73 @@ export async function run({ hasFlag }) {
       debug('install:korean-style', e); // optional feature; never fail install
     }
 
+    // doc2md. The hook itself is two entries in settings.json and costs
+    // nothing until a document shows up, so it goes on with the rest of the
+    // install instead of waiting for the user to discover `doc2md on` — the
+    // people who would save the most tokens are the ones who never find it.
+    // The converter is the expensive half (a venv plus a pip install), so it
+    // is only built when a human is attached; an unattended postinstall just
+    // prints the command.
+    try {
+      const { createRequire } = await import('node:module');
+      const require = createRequire(import.meta.url);
+      const doc2md = require('../doc2md.cjs');
+      if (process.env.CTS_NO_DOC2MD === '1') {
+        console.log('');
+        console.log(lang === 'ko'
+          ? '  doc2md: CTS_NO_DOC2MD=1 이므로 건너뜁니다 (나중에 `doc2md on`).'
+          : '  doc2md: skipped (CTS_NO_DOC2MD=1) — run `doc2md on` later.');
+      } else {
+        const { installDoc2mdHook } = await import('../installer.js');
+        const res = installDoc2mdHook();
+        console.log('');
+        console.log(res.action === 'skipped'
+          ? `  doc2md: ${res.reason}`
+          : `  doc2md: Read/Write hook ${res.action} (${res.path})`);
+        console.log(lang === 'ko'
+          ? `           대상 형식: ${doc2md.TARGET_EXTENSIONS.join(' ')} — 모델이 읽기 전에 Markdown으로 변환합니다.`
+          : `           formats: ${doc2md.TARGET_EXTENSIONS.join(' ')} — converted to Markdown before the model reads them.`);
+        let python = doc2md.findInterpreter();
+        if (!python && interactive) {
+          const build = await confirm(lang === 'ko'
+            ? '           변환기(markitdown)를 지금 설치할까요? 몇 분 걸립니다.'
+            : '           Install the converter (markitdown) now? Takes a few minutes.', { defaultValue: true });
+          if (build) {
+            const cres = doc2md.installConverter({ onProgress: (m) => console.log(`           ${m}`) });
+            if (cres.ok) python = cres.python;
+            else console.log(`           ${cres.reason}: ${cres.detail || ''}`);
+          }
+        }
+        console.log(python
+          ? (lang === 'ko' ? `           변환기: ${python}` : `           converter: ${python}`)
+          : (lang === 'ko'
+            ? `           변환기가 없습니다 — \`${doc2md.INSTALL_HINT}\` 를 실행해야 훅이 동작합니다.`
+            : `           converter missing — run \`${doc2md.INSTALL_HINT}\` or the hook does nothing.`));
+      }
+    } catch (e) {
+      debug('install:doc2md', e); // optional feature; never fail install
+    }
+
+    // Starter rules. The asking itself belongs to the first session — a
+    // 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.
+    try {
+      const { pendingSeeds } = await import('../seed-rules.js');
+      const pending = pendingSeeds();
+      if (pending.length > 0) {
+        console.log('');
+        console.log(lang === 'ko'
+          ? `  seed: 추천 룰 ${pending.length}건이 대기 중입니다 (모델 피팅 + 랫쳇 프리셋).`
+          : `  seed: ${pending.length} recommended rule(s) are waiting (model-fitting + ratchet presets).`);
+        console.log(lang === 'ko'
+          ? '        다음 Claude Code 세션에서 한 건씩 등록할지 물어봅니다. 지금 보려면: claude-token-saver seed'
+          : '        the next Claude Code session asks about them one at a time. See them now: claude-token-saver seed');
+      }
+    } catch (e) {
+      debug('install:seed-offer', e); // optional feature; never fail install
+    }
+
     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

@@ -137,9 +137,17 @@ export async function run({ args, hasFlag, numArg }) {
         const health = r.status === 'review'
           ? (lang === 'ko' ? '  ⚠ 에러율 초과 — 재검토 필요' : '  ⚠ error rate over threshold — needs review')
           : '';
+        // A seeded rule has no recurrence of its own until a scan measures one,
+        // so "반복 0회 / seen ×0" would misreport a curated preset as work that
+        // never happens.
+        const evidence = r.origin === 'preset' && !r.count
+          ? (lang === 'ko' ? '동봉 프리셋 (로그 누적 전)' : 'bundled preset (no local history yet)')
+          : (lang === 'ko'
+            ? `반복 ${r.count || 0}회 · 에러율 ${Math.round((r.errRate || 0) * 100)}%`
+            : `seen ×${r.count || 0} · err ${Math.round((r.errRate || 0) * 100)}%`);
         const stat = lang === 'ko'
-          ? `${r.tier} (${rs.tierLabel(r.tier)}) · ${rs.scopeLabel(r.scope)} · 반복 ${r.count || 0}회 · 에러율 ${Math.round((r.errRate || 0) * 100)}%`
-          : `${r.tier} (${rs.tierLabel(r.tier, 'en')}) · ${rs.scopeLabel(r.scope, 'en')} · seen ×${r.count || 0} · err ${Math.round((r.errRate || 0) * 100)}%`;
+          ? `${r.tier} (${rs.tierLabel(r.tier)}) · ${rs.scopeLabel(r.scope)} · ${evidence}`
+          : `${r.tier} (${rs.tierLabel(r.tier, 'en')}) · ${rs.scopeLabel(r.scope, 'en')} · ${evidence}`;
         console.log(`  #${i + 1} ${stat}${health}`);
         // Measured outcome of the rule actually firing, plus what it saved.
         // A rule with no measured delegations shows "—", never "$0.00": the
@@ -254,6 +262,19 @@ export async function run({ args, hasFlag, numArg }) {
         if (doc2mdHookRegistered()) doc2mdBlock = require('../doc2md.cjs').sessionNote(lang);
       } catch (e) { debug('route-scan:doc2md-note', e); /* the note is optional */ }
 
+      // Starter rules that the user has not answered yet (bundled presets, both
+      // model-fitting and ratchet). A fresh install has an empty model ratchet
+      // and an empty ratchet.md, so without this the tool delegates nothing
+      // until the user's own history is long enough to propose a candidate.
+      // The asking happens here because a CLI prompt cannot reach a user whose
+      // only interface is the chat: the model gets the list and asks one rule
+      // at a time. Silent — and free — once everything has an answer.
+      let seedBlock = null;
+      try {
+        const { seedOfferBlock } = await import('../seed-rules.js');
+        seedBlock = seedOfferBlock({ lang });
+      } catch (e) { debug('route-scan:seed-offer', e); /* the offer is optional */ }
+
       // Upgrade offer. A statusline cannot open a dialog, so session start is
       // where the *asking* happens: the model gets one line telling it a newer
       // version exists and to ask before installing anything. Cached read only
@@ -288,11 +309,13 @@ export async function run({ args, hasFlag, numArg }) {
 
       if (open.length === 0 && reviewRules.length === 0) {
         if (updateBlock) console.log(updateBlock);
+        if (seedBlock) console.log(seedBlock);
         if (doc2mdBlock) console.log(doc2mdBlock);
         if (koreanBlock) console.log(koreanBlock);
         return; // nothing else to inject
       }
       if (updateBlock) console.log(updateBlock);
+      if (seedBlock) console.log(seedBlock);
       if (doc2mdBlock) console.log(doc2mdBlock);
       // This text is injected straight into the model's context, so it must
       // follow the user's configured language — a Korean-only briefing in an

package/src/commands/seed.js

@@ -0,0 +1,105 @@
+/**
+ * Subcommand: seed — register the bundled starter rules, one answer at a time.
+ *
+ *   claude-token-saver seed                          # what is still pending
+ *   claude-token-saver seed accept <id> --global     # register one rule
+ *   claude-token-saver seed accept <id> --project    # ... into this project only
+ *   claude-token-saver seed accept all --global      # when the user says "all of them"
+ *   claude-token-saver seed skip <id> | skip all     # never offer it again
+ *   claude-token-saver seed reset                    # make every preset pending again
+ *
+ * Scope is explicit on purpose, exactly as `harness promote` requires it: the
+ * hook environment is non-TTY, so the model has to ask the user and pass the
+ * flag rather than let a default decide where a rule lands.
+ */
+
+export async function run({ args, hasFlag }) {
+  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 scopeFlag = () => (hasFlag('--global') ? 'global' : hasFlag('--project') ? 'project' : null);
+
+  if (sub === 'reset') {
+    const n = seed.resetSeeds();
+    console.log(ko
+      ? `기록된 응답 ${n}건을 지웠습니다 — 프리셋 전체가 다시 제안 대상이 됩니다.`
+      : `Cleared ${n} recorded answer(s) — every preset is pending again.`);
+    return;
+  }
+
+  if (sub === 'accept' || sub === 'skip') {
+    const ids = args.slice(2).filter((a) => !a.startsWith('-'));
+    if (ids.length === 0) {
+      console.error(ko
+        ? 'id를 지정하십시오 (목록: claude-token-saver seed). 전체는 `all`.'
+        : 'Pass an id (list them with `claude-token-saver seed`), or `all`.');
+      process.exit(1);
+    }
+    const pending = seed.pendingSeeds({ lang, root });
+    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 });
+        console.log(r
+          ? (ko ? `건너뜀: ${id}` : `skipped: ${id}`)
+          : (ko ? `대기 중인 프리셋이 아닙니다: ${id}` : `not a pending preset: ${id}`));
+      }
+      return;
+    }
+
+    const scope = scopeFlag();
+    if (!scope) {
+      console.error(ko
+        ? '적용 범위를 명시하십시오 (사용자에게 먼저 확인): --global 또는 --project'
+        : 'Scope required (confirm it with the user first): --global or --project');
+      process.exit(1);
+    }
+    for (const id of targets) {
+      const r = await seed.acceptSeed(id, { scope, root, lang });
+      if (!r) {
+        console.log(ko ? `대기 중인 프리셋이 아닙니다: ${id}` : `not a pending preset: ${id}`);
+        continue;
+      }
+      console.log(ko
+        ? `✅ 등록: ${id} [${scope === 'global' ? '전체 프로젝트' : '이 프로젝트'}]`
+        : `✅ registered: ${id} [${scope}]`);
+      console.log(`   ${r.rule}`);
+      for (const p of r.paths || (r.path ? [r.path] : [])) console.log(`   → ${p}`);
+    }
+    return;
+  }
+
+  // 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 answered = Object.entries(decided);
+  console.log(ko
+    ? `seed — 동봉 프리셋 중 대기 ${pending.length}건, 응답 완료 ${answered.length}건`
+    : `seed — ${pending.length} preset(s) pending, ${answered.length} already answered`);
+  for (const s of pending) {
+    const head = s.kind === 'model'
+      ? `[${s.id}] ${s.tier} · "${s.label}" → ${s.agent}`
+      : `[${s.id}] ${ko ? '랫쳇 룰' : 'ratchet rule'}`;
+    console.log(`  ${head}`);
+    console.log(`      ${s.ruleText}`);
+  }
+  if (answered.length > 0) {
+    console.log(ko ? '  응답 기록:' : '  answered:');
+    for (const [id, d] of answered) {
+      console.log(`    ${id}: ${d.action}${d.scope ? ` (${d.scope})` : ''} — ${d.at}`);
+    }
+  }
+  if (pending.length > 0) {
+    console.log('');
+    console.log(ko
+      ? '등록: claude-token-saver seed accept <id> --global|--project   ·   거절: seed skip <id>'
+      : 'register: claude-token-saver seed accept <id> --global|--project   ·   decline: seed skip <id>');
+  }
+}

package/src/config.js

@@ -197,6 +197,31 @@ export function userLanguage() {
   return v === 'ko' ? 'ko' : 'en';
 }
 
+/**
+ * Whether the language is a recorded choice rather than the 'en' fallback.
+ *
+ * The install needs the distinction: a user who picked English must not be
+ * asked again on the next upgrade, and "nothing recorded" has to stay
+ * distinguishable from "chose en", which `userLanguage()` alone cannot say.
+ */
+export function languageDecided() {
+  const cfg = loadConfig();
+  const v = cfg.language || (cfg.statusline && cfg.statusline.language);
+  return v === 'ko' || v === 'en';
+}
+
+/** Record the output language ('ko' | 'en'). Anything else is ignored. */
+export function setUserLanguage(v) {
+  const lang = v === 'ko' ? 'ko' : v === 'en' ? 'en' : null;
+  if (!lang) return null;
+  const cfg = loadConfig();
+  cfg.language = lang;
+  // The legacy slot would win on a later read for configs written by 2.9.x.
+  if (cfg.statusline) delete cfg.statusline.language;
+  saveConfig(cfg);
+  return lang;
+}
+
 /**
  * Render hours as the most natural unit:
  *   24h → "1d", 168h → "7d", 6h → "6h", 36h → "36h" (not whole days).

package/src/cost.js

@@ -125,7 +125,12 @@ const TIER_RANK = {
  * from the ranking instead of guessed at.
  */
 export function isUnknownModel(model) {
-  return !model || String(model).toLowerCase() === 'unknown';
+  if (!model) return true;
+  const m = String(model).toLowerCase();
+  // "<synthetic>" is Claude Code's placeholder for locally-generated error
+  // stubs — no real API call happened, so pricing it as Sonnet would be a
+  // silent guess (session-records.js skips it for the same reason).
+  return m === 'unknown' || m === '<synthetic>';
 }
 
 /**

package/src/demo.js

@@ -99,15 +99,16 @@ const SCENARIOS = [
   },
   {
     name: 'ctx-1m',
-    label: '⚠ Context past 200k',
+    label: '⚠ Context past 500k',
     data: {
       hitRate: 0.78,
       pct1h: 0.92,
       savings: 1340,
       elapsedSec: 30,
       contextSize: '1M',
-      ctxUsedPct: 28, // 28% of 1M ≈ 280k actually in context
-      spikeChip: '⚠ Ctx 200k+',
+      ctxOverWarn: true,
+      ctxUsedPct: 62, // 62% of 1M ≈ 620k actually in context
+      spikeChip: '⚠ Ctx 500k+',
       caps: HEALTHY_CAPS,
     },
   },
@@ -271,9 +272,9 @@ export function buildTableDemoData(options = {}) {
       version: options.version ?? '',
     },
     spikeReport: { spikes, baseline: { p95: 940_000 } },
-    contextWindow: { size: '1M', maxContext: 280_000 },
+    contextWindow: { size: '1M', maxContext: 620_000, overWarn: true },
     lastActivity: Date.now() - 60 * 1000,
-    spikeChip: '⚠ Ctx 200k+',
+    spikeChip: '⚠ Ctx 500k+',
   };
 }
 
@@ -303,7 +304,7 @@ export function buildScenarioData(scenarioName, options) {
     if (!scenario) return null;
   }
 
-  const { hitRate, pct1h, pct5m, savings, elapsedSec, contextSize, ctxUsedPct, spikeChip, caps } = scenario.data;
+  const { hitRate, pct1h, pct5m, savings, elapsedSec, contextSize, ctxOverWarn, ctxUsedPct, spikeChip, caps } = scenario.data;
   return {
     summary: { hitRate },
     ttl: { pct1h, pct5m: pct5m ?? (1 - pct1h) },
@@ -315,7 +316,7 @@ export function buildScenarioData(scenarioName, options) {
       version: options.version ?? '',
     },
     lastActivity: Date.now() - elapsedSec * 1000,
-    contextWindow: { size: contextSize },
+    contextWindow: { size: contextSize, overWarn: Boolean(ctxOverWarn) },
     // Live fill level (`📦 68%`) — scenarios that set ctxUsedPct exercise the
     // stdin-driven segment; the rest fall back to the size-based chip.
     ctxLive: ctxUsedPct != null

package/src/formatters/statusline.js

@@ -51,7 +51,11 @@ const GRAY = fg(100, 116, 139, '\x1b[90m');
 const BOLD = '\x1b[1m';
 
 function formatMoney(usd) {
-  if (usd >= 1000) return `$${(usd / 1000).toFixed(1)}K`;
+  // Boundaries sit at 999.5/999500 so a value that would round up into the
+  // next band's width ($999.9 → "$1000") jumps to that band's unit instead —
+  // otherwise "$1000" renders visually larger than "$1.0K".
+  if (usd >= 999500) return `$${(usd / 1e6).toFixed(1)}M`;
+  if (usd >= 999.5) return `$${(usd / 1000).toFixed(1)}K`;
   if (usd >= 100) return `$${usd.toFixed(0)}`;
   if (usd >= 10) return `$${usd.toFixed(1)}`;
   return `$${usd.toFixed(2)}`;
@@ -541,7 +545,9 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     }
   } else if (contextWindow && contextWindow.size && contextWindow.size !== 'unknown') {
     const label = contextWindow.size === '1M' ? '1M' : '200k';
-    const ctxColor = contextWindow.size === '1M' ? YELLOW : GREEN;
+    // Yellow is reserved for the 500k warn line. A 1M window by itself is the
+    // default on every current model, so colouring it yellow cried wolf.
+    const ctxColor = contextWindow.overWarn ? YELLOW : GREEN;
     if (isIcon && verbose) {
       ctxSeg = `${c(ctxColor)}📦 Ctx ${label}${c(RESET)}`;
     } else if (isIcon) {

package/src/formatters/table.js

@@ -84,9 +84,9 @@ function renderSpikeSection(spikes, contextWindow) {
   const lines = [];
   lines.push(rbl('  ⚠ Token spike detected'));
   lines.push(r(`  ${'─'.repeat(50)}`));
-  if (contextWindow && contextWindow.size === '1M') {
+  if (contextWindow && contextWindow.overWarn) {
     lines.push(
-      r(`  Context usage exceeded 200k  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`),
+      r(`  Context usage exceeded 500k  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`),
     );
     lines.push('');
   }
@@ -196,9 +196,11 @@ export function formatReport({ summary: sum, trend, ttl, anomalies, cost, option
   // Context window chip for the normal case too
   if (contextWindow && contextWindow.size !== 'unknown') {
     const note =
-      contextWindow.size === '1M'
-        ? '⚠ Context exceeded 200k in recent requests — big contexts re-bill every turn and drain the 5H/7D caps. Use /compact or /clear.'
-        : '✓ 200k context (standard)';
+      contextWindow.overWarn
+        ? '⚠ Context exceeded 500k in recent requests — big contexts re-bill every turn and drain the 5H/7D caps. Use /compact or /clear.'
+        : contextWindow.size === '1M'
+          ? '✓ 1M window in use, under the 500k warn line'
+          : '✓ 200k context (standard)';
     lines.push(`  Context window: ${contextWindow.size}  ${note}`);
     lines.push(`  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`);
     lines.push('');

package/src/harness-analyzer.cjs

@@ -39,15 +39,20 @@ const PEV_TOOLUSE_THRESHOLD = 5;
 // researching, which is exactly the behavior we don't want to punish.
 const MUTATING_TOOL_RE = /^(edit|write|multiedit|notebookedit|bash)$/i;
 
+// Mirrors src/paths.js userDataDir() exactly (same order as doc2md.cjs).
+// Duplicated because this file is CommonJS and paths.js is ESM; the
+// precedence must match or state lands where the rest of the tool won't look.
 function stateDir() {
-  if (process.platform === 'win32') {
-    return path.join(process.env.APPDATA || os.homedir(), 'claude-token-saver');
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, 'claude-token-saver');
+  }
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'claude-token-saver');
   }
   if (process.platform === 'darwin') {
     return path.join(os.homedir(), 'Library', 'Application Support', 'claude-token-saver');
   }
-  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(xdg, 'claude-token-saver');
+  return path.join(os.homedir(), '.config', 'claude-token-saver');
 }
 
 function readJsonl(file) {

package/src/harness.js

@@ -25,6 +25,7 @@ import {
 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';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -366,23 +367,35 @@ export function harnessPull({ root = findProjectRoot(), scope = 'global' } = {})
   return result;
 }
 
-/** Parse the bundled preset rules (markdown bullets under presets/). */
-export function presetRules() {
+/**
+ * The bundled preset rules, both languages per rule.
+ *
+ * These strings are injected into the model's context (by `seed`) and written
+ * into the user's ratchet (by `pull`), so a Korean-only set would pull an
+ * English session's responses into Korean — hence the pair. The `ko` text is
+ * canonical: it is what identifies a rule, so revising an English wording never
+ * turns a rule the user already answered into a new one.
+ */
+export function presetRuleEntries() {
   try {
     // fileURLToPath, not `.pathname`: the latter yields `/D:/repo/src` on
     // Windows, where the read fails and the catch below turns a missing
     // file into an empty rule set without ever saying so.
-    const path = join(dirname(fileURLToPath(import.meta.url)), '..', 'presets', 'ratchet-rules.md');
-    return readFileSync(path, 'utf8')
-      .split('\n')
-      .filter((l) => /^\s*-\s+/.test(l))
-      .map((l) => l.replace(/^\s*-\s+/, '').trim())
-      .filter(Boolean);
+    const path = join(dirname(fileURLToPath(import.meta.url)), '..', 'presets', 'ratchet-rules.json');
+    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() }));
   } catch {
     return [];
   }
 }
 
+/** Preset rule text in the user's configured language. */
+export function presetRules(lang = userLanguage()) {
+  return presetRuleEntries().map((r) => (lang === 'ko' ? r.ko : r.en));
+}
+
 /**
  * harness list — return numbered ratchet rules from .claude/ratchet.md.
  * Numbering is 1-based and matches `harness rm <N>`.

package/src/history.js

@@ -69,7 +69,8 @@ function saveState(state) {
 function chipKo(chip) {
   if (!chip) return chip;
   const map = {
-    '⚠ Ctx 200k+': '⚠ 컨텍스트 200k 초과',
+    '⚠ Ctx 500k+': '⚠ 컨텍스트 500k 초과',
+    '⚠ Ctx 200k+': '⚠ 컨텍스트 200k 초과', // legacy (pre-v3.32)
     '⚠ 1M ON': '⚠ 1M 컨텍스트 활성', // legacy (pre-v2.18)
     '⚠ Cache miss': '⚠ 캐시 미스',
     '⚠ Rebuild churn': '⚠ 캐시 재빌드 빈발',
@@ -93,8 +94,10 @@ function chipKo(chip) {
  */
 function detailKo(detail) {
   if (!detail) return detail;
-  const m0 = detail.match(/^Single-request context exceeded 200k \(max (\d+)k tokens\)$/);
-  if (m0) return `단일 요청 컨텍스트 200k 초과 (최대 ${m0[1]}k 토큰)`;
+  // The threshold moved from 200k to 500k in v3.32, so both spellings have to
+  // resolve: history files written by older versions still carry the old one.
+  const m0 = detail.match(/^Single-request context exceeded (200|500)k \(max (\d+)k tokens\)$/);
+  if (m0) return `단일 요청 컨텍스트 ${m0[1]}k 초과 (최대 ${m0[2]}k 토큰)`;
   // legacy detail shape (pre-v2.18)
   const m1 = detail.match(/^Context auto-promoted to 1M \(max single-request (\d+)k tokens\)$/);
   if (m1) return `1M 컨텍스트 자동 활성 (단일 요청 최대 ${m1[1]}k 토큰)`;

package/src/hook-manager.js

@@ -1,21 +1,31 @@
 /**
- * Install/uninstall the SessionEnd hook in ~/.claude/settings.json
+ * Install/uninstall the cache-monitor PostToolUse hook in ~/.claude/settings.json
+ *
+ * Registered as a CLI subcommand (`claude-token-saver --hook-run`) like every
+ * other hook in this package — NOT as a copied file. The old copy-to-home
+ * approach pinned a stale hook.cjs in ~/.claude/ forever, never shipped
+ * harness-analyzer.cjs alongside it, and survived `uninstall` because its
+ * command line did not contain the CLI name. Registering the CLI itself
+ * removes the copy, the staleness, and the orphan in one move.
  */
 
-import { readFile, writeFile, copyFile } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { fileURLToPath } from 'node:url';
 
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
-const HOOK_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), 'hook.cjs');
-const HOOK_DEST = join(homedir(), '.claude', 'cache-monitor-hook.cjs');
+// Legacy copied-file location — removed on install/uninstall so machines that
+// installed an older version don't keep a dead hook script around.
+const LEGACY_HOOK_DEST = join(homedir(), '.claude', 'cache-monitor-hook.cjs');
 const HOOK_MARKER = 'cache-monitor-hook';
 
-export async function installHook({ threshold = 0.7 } = {}) {
-  // Copy hook script to ~/.claude/ for stable path
-  await copyFile(HOOK_SCRIPT, HOOK_DEST);
+function isCacheMonitorHook(nh) {
+  const cmd = nh?.command;
+  if (typeof cmd !== 'string') return false;
+  return cmd.includes(HOOK_MARKER) || cmd.includes('--hook-run');
+}
 
+export async function installHook({ threshold = 0.7 } = {}) {
   let settings;
   try {
     const raw = await readFile(SETTINGS_PATH, 'utf8');
@@ -27,24 +37,18 @@ export async function installHook({ threshold = 0.7 } = {}) {
   if (!settings.hooks) settings.hooks = {};
   if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
 
-  // Remove existing cache-monitor hook if present
+  // Remove existing cache-monitor hook if present — matches both the current
+  // subcommand form and the legacy copied-file form.
   settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
-    (h) => {
-      // Check nested hooks structure
-      const nested = h.hooks || [];
-      return !nested.some((nh) => nh.command?.includes(HOOK_MARKER));
-    },
+    (h) => !(h.hooks || []).some(isCacheMonitorHook),
   );
 
-  // Add new hook (correct 3-level nested structure)
-  // Normalize path separators for Windows compatibility in shell commands
-  const hookPath = HOOK_DEST.replace(/\\/g, '/');
   settings.hooks.PostToolUse.push({
     matcher: 'Bash|Edit|Write',
     hooks: [
       {
         type: 'command',
-        command: `node "${hookPath}" --threshold ${threshold}`,
+        command: `claude-token-saver --hook-run --threshold ${threshold}`,
         timeout: 10,
       },
     ],
@@ -52,7 +56,10 @@ export async function installHook({ threshold = 0.7 } = {}) {
 
   await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
 
-  console.log(`✓ Hook installed at ${HOOK_DEST}`);
+  // Clean up the legacy copy left by older versions.
+  await rm(LEGACY_HOOK_DEST, { force: true }).catch(() => {});
+
+  console.log('✓ Hook installed (PostToolUse → claude-token-saver --hook-run)');
   console.log(`  Settings updated: ${SETTINGS_PATH}`);
   console.log(`  Threshold: ${(threshold * 100).toFixed(0)}%`);
   console.log(`  Stats file: ~/.claude/cache-stats.jsonl`);
@@ -71,10 +78,7 @@ export async function uninstallHook() {
   if (settings.hooks?.PostToolUse) {
     const before = settings.hooks.PostToolUse.length;
     settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
-      (h) => {
-        const nested = h.hooks || [];
-        return !nested.some((nh) => nh.command?.includes(HOOK_MARKER));
-      },
+      (h) => !(h.hooks || []).some(isCacheMonitorHook),
     );
     const removed = before - settings.hooks.PostToolUse.length;
 
@@ -86,4 +90,7 @@ export async function uninstallHook() {
   } else {
     console.log('No cache-monitor hook found in settings.');
   }
+
+  // The legacy copied hook file is dead weight either way.
+  await rm(LEGACY_HOOK_DEST, { force: true }).catch(() => {});
 }