claude-token-saver 3.3.0 → 3.3.1

package/README.en.md

@@ -269,6 +269,9 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.3.1 (2026-07-13)
+- **Plain language instead of codes** — bare `R1`/`T2` codes were unreadable for first-time users. Every user-facing listing (SessionStart hook briefing, `route-scan` candidates, `route-scan rules`) now spells tiers out as `T2 (simple — haiku-class is enough)` and scopes as `this project only` / `all projects (global)`. The hook briefing also instructs the model to relay the spelled-out explanation, not the codes. (Statusline chips keep the terse `route? R1` for width; the session briefing carries the meaning.)
+
 ### 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.

package/README.md

@@ -226,6 +226,9 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.3.1 (2026-07-13)
+- **코드 대신 풀어쓴 설명** — `R1`, `T2` 같은 코드가 설명 없이 노출돼 처음 쓰는 사람이 알 수 없던 문제 수정. 모든 사용자 대면 출력(SessionStart 훅 브리핑, `route-scan` 후보 목록, `route-scan rules` 목록)에서 티어를 `T2 (단순 작업 — haiku급이면 충분)` 식으로 풀어쓰고, scope도 `이 프로젝트만`/`모든 프로젝트(글로벌)`로 표기. 훅 브리핑에는 "사용자에게 전달할 때 코드가 아니라 풀어쓴 설명으로 브리핑하라"는 지시 포함. (statusline 칩은 폭 제약상 `route? R1` 유지 — 의미는 세션 브리핑이 설명)
+
 ### v3.3.0 (2026-07-13)
 - **위임 가시화·브리핑 강화** — 모델 피팅의 전 과정이 사용자에게 보이도록:
   - SessionStart 훅이 후보마다 **등록 시 ratchet-model.md에 기록될 룰 원문**을 함께 주입 — 무엇이 등록될지 정확히 보고 승인.

package/bin/cli.js

@@ -520,8 +520,13 @@ async function main() {
       }
       console.log(lang === 'ko' ? '📐 모델 피팅 룰 (로그 기반 자동 갱신):' : '📐 Model-fitting rules (auto-refreshed from logs):');
       rules.forEach((r, i) => {
-        const health = r.status === 'review' ? '  ⚠ rule-health' : '';
-        console.log(`  #${i + 1} [${r.tier}|${r.scope}] ×${r.count || 0} err ${Math.round((r.errRate || 0) * 100)}%${health}`);
+        const health = r.status === 'review'
+          ? (lang === 'ko' ? '  ⚠ 에러율 초과 — 재검토 필요' : '  ⚠ error rate over threshold — needs review')
+          : '';
+        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)}%`;
+        console.log(`  #${i + 1} ${stat}${health}`);
         console.log(`      ${r.rule}`);
       });
       console.log('\n제거: claude-token-saver route-scan rules rm <N>');
@@ -571,21 +576,24 @@ async function main() {
       if (open.length === 0 && reviewRules.length === 0) return; // silent — nothing to inject
       const lines = [];
       if (open.length > 0) {
-        lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 상위 모델(opus/fable)이 처리한 위임 가능 반복 작업이 감지되었습니다:`);
+        lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 비싼 모델(opus/fable)이 반복 처리해 온, 더 싼 모델로 넘겨도 되는 작업이 감지되었습니다.`);
+        lines.push('(R<N>은 후보 번호, T2/T1은 난이도 등급입니다 — 사용자에게 전달할 때는 코드가 아니라 아래 풀어쓴 설명으로 브리핑하세요)');
         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}"`);
+          const tier = c.tier || 'T2';
+          lines.push(`  후보 R${c.id} — "${c.label}" 유형, ${c.count}회 반복 (프로젝트: ${c.project})`);
+          lines.push(`      판정: ${tier} (${rs.tierLabel(tier)}) → ${c.agent} 서브에이전트 위임 권장 · 적용 범위 제안: ${rs.scopeLabel(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('등록하면 다음 세션부터 자동 위임됩니다. 사용자에게 등록 여부를 물을 때 위 룰 원문을 그대로 보여주고, 적용 범위까지 확인한 뒤 실행하세요:');
+        lines.push('  claude-token-saver harness promote R<N> --project|--global   # 적용 범위는 반드시 사용자에게 확인');
         lines.push('  claude-token-saver route-scan dismiss <N>                    # 사용자가 원치 않으면');
       }
       if (reviewRules.length > 0) {
-        lines.push(`[claude-token-saver rule-health] 등록된 모델 피팅 룰 중 위임 대상 유형의 에러율이 기준(20%)을 넘은 룰이 있습니다 — 사용자에게 브리핑하고 조건 좁히기/제거를 상의하세요:`);
+        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(`  룰 #${r.n} (${r.tier} ${rs.tierLabel(r.tier)} · ${rs.scopeLabel(r.scope)}) — 최근 에러율 ${Math.round((r.errRate || 0) * 100)}%`);
+          lines.push(`      "${r.rule}"`);
         }
         lines.push('  제거: claude-token-saver route-scan rules rm <N>');
       }
@@ -614,11 +622,18 @@ async function main() {
         : 'No delegation candidates (below recurrence threshold or already resolved).');
       return;
     }
-    console.log(lang === 'ko' ? '\n위임 후보:' : '\nDelegation candidates:');
+    console.log(lang === 'ko' ? '\n위임 후보 (R<N>=후보 번호, T2/T1=난이도 등급):' : '\nDelegation candidates (R<N> = candidate id, T2/T1 = difficulty tier):');
     for (const c of open) {
-      console.log(`  R${c.id}  [${c.tier || 'T2'}] ×${c.count}  ${c.label} → ${c.agent}  [${c.project}] (scope 제안: ${c.suggestedScope})`);
-      console.log(`       예시: "${c.example}"`);
-      console.log(`       룰: ${c.rule}`);
+      const tier = c.tier || 'T2';
+      if (lang === 'ko') {
+        console.log(`  R${c.id}  "${c.label}" ×${c.count}회 [${c.project}]`);
+        console.log(`       판정: ${tier} (${rs.tierLabel(tier)}) → ${c.agent} 위임 권장 · 적용 범위 제안: ${rs.scopeLabel(c.suggestedScope)}`);
+      } else {
+        console.log(`  R${c.id}  "${c.label}" ×${c.count} [${c.project}]`);
+        console.log(`       verdict: ${tier} (${rs.tierLabel(tier, 'en')}) → delegate to ${c.agent} · suggested scope: ${rs.scopeLabel(c.suggestedScope, 'en')}`);
+      }
+      console.log(`       ${lang === 'ko' ? '예시' : 'example'}: "${c.example}"`);
+      console.log(`       ${lang === 'ko' ? '룰' : 'rule'}: ${c.rule}`);
     }
     console.log('');
     console.log(lang === 'ko' ? '등록 / 무시:' : 'Promote / dismiss:');

package/package.json

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

package/src/route-scan.js

@@ -406,6 +406,30 @@ export async function shouldRescan(cache, { days = 14 } = {}) {
   return age >= RESCAN_MAX_AGE_MS;
 }
 
+/**
+ * Human-readable labels for the T0/T1/T2 codes and scope values — used by
+ * every user-facing listing so a bare code never appears without its meaning
+ * (first-time users can't be expected to know the tier vocabulary).
+ */
+export function tierLabel(tier, lang = 'ko') {
+  const ko = {
+    T2: '단순 작업 — haiku급이면 충분',
+    T1: '중간 난도 — sonnet급이면 충분',
+    T0: '고난도 — 지금 모델 유지',
+  };
+  const en = {
+    T2: 'simple — haiku-class is enough',
+    T1: 'moderate — sonnet-class is enough',
+    T0: 'hard — stays on the session model',
+  };
+  return (lang === 'ko' ? ko : en)[tier] || tier;
+}
+
+export function scopeLabel(scope, lang = 'ko') {
+  if (lang === 'ko') return scope === 'global' ? '모든 프로젝트(글로벌)' : '이 프로젝트만';
+  return scope === 'global' ? 'all projects (global)' : 'this project only';
+}
+
 /** Candidates not yet promoted/dismissed. */
 export function openCandidates(cache) {
   if (!cache?.candidates) return [];