claude-token-saver 3.2.1 → 3.3.0

package/README.en.md

@@ -7,7 +7,9 @@
 
 # claude-token-saver
 
-**Diagnose and save Claude Code tokens from a single statusline.** Zero dependencies, one-line install.
+**Diagnose Claude Code token usage from a single statusline — and route the easy work your expensive model keeps repeating down to cheaper models.** Zero dependencies, one-line install.
+
+Since v3.x this is more than after-the-fact monitoring: it's a **model-fitting routing layer**. Session logs are classified into tiers (T0/T1/T2), recurring patterns get promoted to "haiku/sonnet is enough for this" delegation rules, and your main model auto-delegates them from the next session ([route-scan](#-route-scan--this-recurring-task-could-run-on-a-cheaper-tier)).
 
 ```bash
 npm i -g claude-token-saver   # postinstall auto-registers the statusline + Skill
@@ -19,6 +21,7 @@ npm i -g claude-token-saver   # postinstall auto-registers the statusline + Skil
 
 | | |
 |---|---|
+| 🔀 **Model-fitting delegation** | Classifies the easy work your expensive model (opus/fable) keeps repeating into tiers (T0/T1/T2) → promotes haiku/sonnet delegation rules, auto-applied from the next session |
 | 💸 **−18.6% measured cost** | Cost per user message $2.35 → $1.91 after adopting harness+ratchet (author's logs, [details](#real-world-impact--beforeafter-report)) |
 | 🚨 **No surprise rate limits** | Instant warning when the 5H/7D window hits 90% + `handoff` to back up your work |
 | 🧠 **Cache waste detection** | Hit rate, TTL countdown, 1M-context detection — token spikes diagnosed with issue codes |
@@ -148,6 +151,21 @@ Analyzes your session history at the **episode (user request) level**, classifie
 
 Signals: call count, output tokens, **mutating tool calls (Edit/Write/Bash)**, **tool errors**, and request text. Output thresholds are auto-calibrated from your own 14-day distribution (fixed constants drift with workload).
 
+<details>
+<summary>Why this design — research evidence (deep-research, 21 cross-verified sources + 553 locally measured episodes)</summary>
+
+A survey of existing LLM-routing research and systems shaped each axis of the design:
+
+- **Conservative demotion — "only send down what's clearly easy" — is the unexplored direction.** In RouterArena (2025), every academic and commercial router fell far short of the oracle (90.9%; best entrant 66.9), and the failure mode was consistently **over-routing to expensive models**. Per the routing-collapse work, the oracle needs the top model for under 20% of queries — while 73% of the author's episodes were still on the top tier. The headroom is large.
+- **Difficulty is defined by outcome, not text guessing.** RouterArena labels difficulty as "how many of 42 models actually got it right". Our logs already contain outcomes: tool errors, mutating tool calls, episode length. Local measurement confirms it — error incidence splits the tiers sharply (T2 candidates 2% / T1 8% / T0 36%).
+- **Thresholds calibrate to the user's own distribution.** RouteLLM's stated limitation is that fixed thresholds drift as the query distribution shifts — so output-token thresholds are recomputed from your last 14 days' p25/p75 (clamped).
+- **An escalation path makes demotion mistakes cheap.** The FrugalGPT cascade lesson ("start cheap, escalate on failure"). In Claude Code this falls out naturally: when a subagent gets stuck, the main model takes over — and promoted rules spell out that guard.
+- **Subagent `model:` is Anthropic's official cost-control mechanism.** The docs recommend routing to cheaper models like Haiku for cost control — yet Claude Code itself does no automatic model routing; even trivial turns resend the full context on the session model. That gap is exactly what route-scan fills.
+- **Learned classifiers (BERT/embeddings) deliberately excluded.** Even the best is 24 points off the oracle, we have no preference-pair training data, and it would break the zero-dependency principle. Regex categories + outcome signals are the current position.
+
+Sources (RouteLLM, FrugalGPT, RouterArena, routing-survey arxiv links), the full local-measurement table, and the complete tier criteria: [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md).
+</details>
+
 ```bash
 claude-token-saver route-scan                    # scan (24h cache) + tiered candidates
 claude-token-saver harness promote R1 --project  # promote candidate R1 to a model-fitting rule
@@ -251,6 +269,16 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.3.0 (2026-07-13)
+- **Delegation visibility & briefing** — the whole model-fitting loop is now surfaced to the user:
+  - The SessionStart hook injects, per candidate, **the exact rule text that would be written to ratchet-model.md** — you see precisely what you're approving.
+  - Rules flipped to review (delegated-category error rate over 20%) are announced on **both** the statusline (`🅷⚠ rule-health R<N>` chip — implementing the item from the design doc; precedence: session-quality warnings > rule-health > route? candidates) and the session-start briefing.
+  - The ratchet-model.md header now instructs the model to prefix each delegation with `🔀 [claude-token-saver] model-fitting: "<category>" → <agent>` — making it visible which tool is saving your tokens.
+- README updated to the 3.x identity (model-fitting delegation in the top pitch, collapsible research-evidence section under route-scan); fixed a stale comment in model-rules.js.
+
+### v3.2.2 (2026-07-13)
+- **No re-proposing registered rules** — (tier|category|project) combinations that already have a model-fitting rule are excluded from scan candidates (a global rule covers every project). Fixes rules registered outside the promote flow (e.g. migrations) resurfacing as candidates.
+
 ### v3.2.1 (2026-07-13)
 - **Instant pattern analysis on first setup** — `install` (including npm postinstall) analyzes your existing session logs inline when no cache exists, so tier-delegation candidates appear from the very first Claude Code session (previously the second).
 

package/README.md

@@ -7,7 +7,9 @@
 
 # claude-token-saver
 
-**Claude Code 토큰 사용량을 statusline 한 줄로 진단하고 절약하는 CLI.** 의존성 0, 설치 한 줄이면 끝.
+**Claude Code 토큰 사용량을 statusline 한 줄로 진단하고, 상위 모델이 반복 처리하는 easy 작업은 더 싼 모델로 내려보내는 CLI.** 의존성 0, 설치 한 줄이면 끝.
+
+v3.x부터는 사후 모니터링을 넘어 **모델 피팅 라우팅 계층**입니다: 세션 로그를 티어(T0/T1/T2)로 분류해 "이 반복 작업은 haiku/sonnet이면 충분하다"를 룰로 승격하고, 다음 세션부터 메인 모델이 자동 위임합니다 ([route-scan](#-route-scan--이-반복-작업-더-싼-티어로-내려도-됩니다)).
 
 ```bash
 npm i -g claude-token-saver   # postinstall이 statusline + Skill 자동 등록
@@ -19,6 +21,7 @@ npm i -g claude-token-saver   # postinstall이 statusline + Skill 자동 등록
 
 | | |
 |---|---|
+| 🔀 **모델 피팅 위임** | 상위 모델(opus/fable)이 반복 처리해 온 easy 작업을 티어(T0/T1/T2)로 분류 → haiku/sonnet 위임 룰로 승격, 다음 세션부터 자동 적용 |
 | 💸 **비용 실측 −18.6%** | harness+ratchet 도입 전후, 사용자 메시지당 비용 $2.35 → $1.91 (저자 로그, [상세](#실제-효과--도입-전후-리포트)) |
 | 🚨 **한도 초과 예방** | 5H/7D rate-limit 윈도 90% 도달 시 즉시 경고 + `handoff`로 작업 백업 |
 | 🧠 **캐시 낭비 감지** | 히트율·TTL 카운트다운·1M 컨텍스트 자동 감지 — 토큰 급증 원인을 코드로 진단 |
@@ -129,6 +132,21 @@ ratchet의 가치는 **한 방향 누적**에 있습니다. 룰을 가볍게 지
 
 판정 신호는 호출 수·출력 토큰·**변경성 도구 수(Edit/Write/Bash)**·**도구 에러 수**·요청 텍스트이고, 출력 임계값은 사용자 자신의 최근 14일 분포에서 자동 보정됩니다 (고정 상수는 워크로드가 바뀌면 어긋나기 때문).
 
+<details>
+<summary>왜 이 설계인가 — 리서치 근거 (deep-research 소스 21개 교차검증 + 로컬 실측 553 에피소드)</summary>
+
+기존 LLM 라우팅 연구·시스템을 조사한 결과가 설계의 각 축을 결정했습니다:
+
+- **"쉬운 것만 확실히 내리는" 보수적 강등이 미개척 지대** — RouterArena(2025) 평가에서 학술·상용 라우터 전부 오라클(90.9%)에 크게 못 미쳤고(1위 66.9), 실패 방향은 일관되게 **비싼 모델로의 과잉 라우팅**이었습니다. 오라클 기준 최상위 모델이 정말 필요한 쿼리는 20% 미만인데(routing collapse 연구), 저자 로그에선 73%가 최상위 티어에 남아 있었습니다 — 헤드룸이 큽니다.
+- **난이도는 텍스트 추정이 아니라 결과(outcome)로 정의** — RouterArena는 난이도를 "42개 모델 중 몇 개가 실제로 맞혔나"로 라벨링했습니다. 우리 로그에도 결과가 이미 있습니다: 도구 에러·변경성 도구 수·에피소드 길이. 로컬 실측에서도 에러 경험률이 티어를 강하게 갈랐습니다 (T2 후보 2% / T1 8% / T0 36%).
+- **임계값은 사용자 분포에서 보정** — RouteLLM의 공식 한계가 "고정 임계값은 쿼리 분포가 바뀌면 어긋난다"입니다. 그래서 출력 토큰 임계값을 최근 14일 p25/p75에서 재계산합니다(클램프 포함).
+- **실패 시 승급 경로가 강등 오판 비용을 낮춤** — FrugalGPT 캐스케이드("싼 모델부터, 안 되면 위로")의 교훈. Claude Code에선 서브에이전트가 막히면 메인 모델이 이어받는 형태로 자연 구현되고, 승격 룰 텍스트에도 이 가드가 명시됩니다.
+- **서브에이전트 `model:`은 Anthropic 공식 비용 통제 메커니즘** — 공식 문서가 "Haiku 등 싼 모델로 라우팅해 비용 통제"를 권장하지만, Claude Code 본체는 자동 모델 라우팅을 하지 않습니다. 사소한 턴도 세션 모델이 전체 컨텍스트를 재전송하며 처리하는 이 공백이 route-scan이 메우는 자리입니다.
+- **학습형 분류기(BERT/임베딩)는 의도적으로 배제** — 최고 성능도 오라클과 24점 차이인 데다 학습 데이터가 없고 zero-dep 원칙에 어긋납니다. 정규식 카테고리 + outcome 신호 조합이 현재 위치.
+
+출처(RouteLLM·FrugalGPT·RouterArena·라우팅 서베이 arxiv 링크)와 로컬 실측 상세 테이블, 티어 기준 전문은 [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md) 참고.
+</details>
+
 ```bash
 claude-token-saver route-scan                    # 스캔 (24h 캐시) + 티어별 후보 출력
 claude-token-saver harness promote R1 --project  # 후보 R1을 모델 피팅 룰로 등록
@@ -208,6 +226,16 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.3.0 (2026-07-13)
+- **위임 가시화·브리핑 강화** — 모델 피팅의 전 과정이 사용자에게 보이도록:
+  - SessionStart 훅이 후보마다 **등록 시 ratchet-model.md에 기록될 룰 원문**을 함께 주입 — 무엇이 등록될지 정확히 보고 승인.
+  - 에러율 기준(20%) 초과로 review 상태가 된 룰은 **statusline `🅷⚠ rule-health R<N>` 칩** + 세션 시작 브리핑 양쪽으로 통지 (설계 문서에 있던 미구현 항목 구현. 우선순위: 세션 품질 경고 > rule-health > route? 후보).
+  - ratchet-model.md 헤더에 위임 실행 시 `🔀 [claude-token-saver] 모델 피팅: "<유형>" → <agent> 위임` 한 줄을 먼저 표시하라는 지시 추가 — 어떤 도구가 토큰을 아끼는지 가시화.
+- README에 3.x 정체성 반영 (상단 요약에 모델 피팅 위임 추가, route-scan 섹션에 리서치 근거 접이식), model-rules.js 주석-구현 불일치 수정.
+
+### v3.2.2 (2026-07-13)
+- **등록 룰 재제안 차단** — 이미 모델 피팅 룰이 있는 (티어|카테고리|프로젝트) 조합은 스캔 후보에서 자동 제외 (글로벌 룰은 전 프로젝트 커버). promote를 거치지 않고 등록된 룰(마이그레이션 등)이 후보로 되살아나던 문제 수정.
+
 ### v3.2.1 (2026-07-13)
 - **최초 설치 시 즉시 패턴 분석** — `install`(npm postinstall 포함)이 캐시가 없으면 기존 세션 로그를 그 자리에서 분석해, 첫 Claude Code 세션부터 티어 위임 후보가 표시됩니다 (기존에는 두 번째 세션부터).
 

package/bin/cli.js

@@ -558,17 +558,37 @@ async function main() {
         } catch { /* refresh is best-effort; stale cache still usable below */ }
       }
       const open = rs.openCandidates(cache);
-      if (open.length === 0) return; // silent — nothing to inject
+      // Registered rules whose delegated-category error rate crossed the
+      // health threshold since promotion — the user approved these, so a
+      // status change must be briefed, not just written into the md file.
+      let reviewRules = [];
+      try {
+        const mr = await import('../src/model-rules.js');
+        reviewRules = mr.loadModelRules().rules
+          .map((r, i) => ({ ...r, n: i + 1 }))
+          .filter((r) => r.status === 'review');
+      } catch { /* registry unreadable — candidate briefing still goes out */ }
+      if (open.length === 0 && reviewRules.length === 0) return; // silent — nothing to inject
       const lines = [];
-      lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 상위 모델(opus/fable)이 처리한 위임 가능 반복 작업이 감지되었습니다:`);
-      for (const c of open) {
-        const tierNote = c.tier === 'T1' ? 'sonnet 위임(중간 난도)' : `${c.agent} 위임(경량)`;
-        lines.push(`  R${c.id} [${c.tier || 'T2'}] (×${c.count}, ${c.project}): ${c.label} → ${tierNote} 권장 (scope 제안: ${c.suggestedScope})`);
-        lines.push(`      예시: "${c.example}"`);
+      if (open.length > 0) {
+        lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 상위 모델(opus/fable)이 처리한 위임 가능 반복 작업이 감지되었습니다:`);
+        for (const c of open) {
+          const tierNote = c.tier === 'T1' ? 'sonnet 위임(중간 난도)' : `${c.agent} 위임(경량)`;
+          lines.push(`  R${c.id} [${c.tier || 'T2'}] (×${c.count}, ${c.project}): ${c.label} → ${tierNote} 권장 (scope 제안: ${c.suggestedScope})`);
+          lines.push(`      예시: "${c.example}"`);
+          lines.push(`      등록 시 ratchet-model.md에 기록될 룰: "${c.rule}"`);
+        }
+        lines.push('등록하면 다음 세션부터 자동 위임됩니다. 사용자에게 등록 여부를 물을 때 위 룰 원문을 그대로 보여주고, scope까지 확인한 뒤 실행하세요:');
+        lines.push('  claude-token-saver harness promote R<N> --project|--global   # scope는 반드시 사용자에게 확인');
+        lines.push('  claude-token-saver route-scan dismiss <N>                    # 사용자가 원치 않으면');
+      }
+      if (reviewRules.length > 0) {
+        lines.push(`[claude-token-saver rule-health] 등록된 모델 피팅 룰 중 위임 대상 유형의 에러율이 기준(20%)을 넘은 룰이 있습니다 — 사용자에게 브리핑하고 조건 좁히기/제거를 상의하세요:`);
+        for (const r of reviewRules) {
+          lines.push(`  #${r.n} [${r.tier}|${r.scope}] 에러율 ${Math.round((r.errRate || 0) * 100)}%: ${r.rule}`);
+        }
+        lines.push('  제거: claude-token-saver route-scan rules rm <N>');
       }
-      lines.push('이 패턴을 랫쳇 룰로 등록하면 다음 세션부터 자동 위임됩니다. 적절한 시점에 사용자에게 등록 여부와 scope를 물어본 뒤 실행하세요:');
-      lines.push('  claude-token-saver harness promote R<N> --project|--global   # scope는 반드시 사용자에게 확인');
-      lines.push('  claude-token-saver route-scan dismiss <N>                    # 사용자가 원치 않으면');
       console.log(lines.join('\n'));
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {

package/src/harness.js

@@ -20,6 +20,7 @@ import {
   appendRatchetRule,
 } from './harness-templates.js';
 import { routeWarningForStatusline } from './route-scan.js';
+import { ruleHealthWarningForStatusline } from './model-rules.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -419,6 +420,14 @@ export function harnessStatusForStatusline(cfg, { root } = {}) {
       else if (state.pevSkip) warning = 'PEV-skip';
     }
   }
+  // Below session-quality warnings: a promoted delegation rule whose
+  // category started failing (`rule-health R<N>`) — the user approved that
+  // rule, so its degradation outranks a mere new-candidate nudge.
+  if (!warning) {
+    try {
+      warning = ruleHealthWarningForStatusline(projectRoot);
+    } catch { /* registry unreadable — stay silent */ }
+  }
   // Lowest precedence: route-scan delegation candidate (`route? R<N>`).
   // Session-quality warnings above always win — routing is an optimization
   // nudge, not a correctness signal. Cheap: one small cached-JSON read.

package/src/model-rules.js

@@ -97,6 +97,10 @@ export function renderModelRatchet(rules) {
     '로그 기반 티어 위임 룰. 이 파일은 route-scan이 매 스캔마다 통째로 재생성하므로',
     '직접 수정하지 마세요 — 목록/제거: `claude-token-saver route-scan rules [rm <N>]`.',
     '',
+    '아래 룰에 따라 위임을 실행할 때는 사용자에게 다음 한 줄을 먼저 표시할 것',
+    '(어떤 도구가 토큰을 아끼고 있는지 가시화):',
+    '`🔀 [claude-token-saver] 모델 피팅: "<유형>" → <agent> 위임`',
+    '',
     '## Rules',
     '',
   ];
@@ -110,6 +114,23 @@ export function renderModelRatchet(rules) {
   return lines.join('\n') + '\n';
 }
 
+/**
+ * Statusline helper (docs/TIER_CRITERIA.md §rule-health) — cheapest possible
+ * check, one small JSON read. Returns `rule-health R<N>` for the first
+ * review-flagged rule relevant to this project (its own root, or global
+ * scope), else null. N is the 1-based registry index, matching the numbering
+ * of `route-scan rules [rm <N>]` so the fix command is one lookup away.
+ */
+export function ruleHealthWarningForStatusline(projectRoot) {
+  const { rules } = loadModelRules();
+  for (let i = 0; i < rules.length; i++) {
+    const r = rules[i];
+    if (r.status !== 'review') continue;
+    if (r.scope === 'global' || r.targetRoot === projectRoot) return `rule-health R${i + 1}`;
+  }
+  return null;
+}
+
 export function modelRatchetPathFor(scope, targetRoot) {
   return scope === 'global'
     ? join(homedir(), '.claude', 'ratchet-model.md')
@@ -150,8 +171,11 @@ export function syncAllFiles({ previousPaths = [] } = {}) {
  * for each registered rule, recompute recurrence count and the error rate
  * of episodes in its (tier-eligible) category — the rule-health signal.
  *
- * `episodeStats`: Map "category|project" → { count, errCount, epCount }
- * where errCount/epCount measure post-promotion delegated-category episodes.
+ * `episodeStats`: Map "category|project" (plus a "category|*" wildcard key
+ * that global-scope rules fall back to) → { count, errCount, epCount }.
+ * errCount/epCount measure the scan window's shape-eligible episodes — ones
+ * an expensive model handled directly that still look T1/T2 by shape (tier
+ * judged with the error signal zeroed; see route-scan's rule-health pass).
  */
 export function refreshModelRules(episodeStats, { now } = {}) {
   const data = loadModelRules();

package/src/route-scan.js

@@ -285,12 +285,25 @@ export async function runRouteScan({ days = 14 } = {}) {
   const prev = readRouteScan();
   const resolved = new Set(prev?.resolved || []);
 
+  // Never re-propose a pattern that already has a registered model-fitting
+  // rule (a global rule covers the category in every project). Without this,
+  // rules that entered the registry outside the promote flow — migrations,
+  // future imports — would resurface as candidates forever.
+  let registered = [];
+  try {
+    const { loadModelRules } = await import('./model-rules.js');
+    registered = loadModelRules().rules;
+  } catch { /* registry unreadable — candidates may repeat until promote */ }
+  const hasRule = (g) => registered.some((r) =>
+    r.tier === g.tier && r.category === g.category &&
+    (r.scope === 'global' || r.project === g.project));
+
   const ruleText = (g) => g.tier === 'T2'
     ? `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${g.agent}(haiku) 서브에이전트로 위임한다`
     : `"${g.label}" 유형의 중간 난도 요청(예: "${g.example}")은 model: sonnet 서브에이전트로 위임한다 (설계 판단·반복 에러 발생 시 메인 모델이 이어받음)`;
 
   const candidates = [...groups.values()]
-    .filter((g) => g.count >= MIN_RECURRENCE)
+    .filter((g) => g.count >= MIN_RECURRENCE && !hasRule(g))
     .sort((a, b) => b.count - a.count)
     .slice(0, 8)
     .map((g, i) => ({