claude-token-saver 2.18.0 → 3.0.1

package/README.en.md

@@ -82,6 +82,8 @@ Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is
 | `claude-token-saver handoff` | Back work up to `HANDOFF-*.md` before a cap blocks you |
 | `claude-token-saver mode [keywords...]` | Output config (`icon`/`text`, `en`/`ko`, `1h`–`30d` window, …) |
 | `claude-token-saver harness ...` | 🅷 Harness management (below) |
+| `claude-token-saver frugon` | Export sessions → [frugon](https://github.com/Rodiun/frugon)-compatible JSONL (model-routing savings analysis, below) |
+| `claude-token-saver route-scan` | Detect recurring easy work on expensive models → propose haiku-delegation ratchet rules (below) |
 | `claude-token-saver install` | Manually register Skill + statusline |
 
 Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
@@ -114,11 +116,14 @@ claude-token-saver harness init                # this project
 claude-token-saver harness init --global       # ~/.claude/CLAUDE.md — every project
 claude-token-saver harness check               # current score (global fallback honored)
 claude-token-saver harness promote <N> --project|--global   # warning #N → ratchet rule (scope required)
+claude-token-saver harness promote "<rule text>" --project|--global  # register your own hand-written rules the same way
+claude-token-saver harness pull                # register the package's curated ratchet rules into your global ratchet (opt-in, dedupes)
 claude-token-saver harness list / rm <N>       # view / delete rules (auto .bak)
 claude-token-saver harness off | on            # toggle the 🅷 chip
 ```
 
 - `promote` **requires** `--project`/`--global` in non-TTY contexts (scripts, LLM calls) — a scope choice is never silently made for the caller.
+- `pull` registers the **author-curated ratchet rules** bundled with the package (`presets/ratchet-rules.md` — only general-purpose rules promoted from real recurring mistakes) into your global ratchet (`~/.claude/ratchet.md`). `install`/`init` never auto-inject anything; `pull` is always opt-in and idempotent. Drop any rule you dislike with `harness rm`.
 - 🅷⚠ runtime warnings (`ratchet?` `no-evidence` `PEV-skip`) expire after 30 minutes, subdirectory sessions match their project correctly, and PEV-skip counts only mutating tools (Edit/Write/Bash) so read-only research sessions don't trip it (v2.16.0+).
 
 <details>
@@ -133,6 +138,38 @@ The whole point of the ratchet is **one-direction accumulation**. Deleting rules
 An auto `.bak` is kept, but **the session context that earned the rule its place is not recoverable.**
 </details>
 
+## 🔀 frugon integration — "which calls could a cheaper model handle?"
+
+claude-token-saver catches cache/context waste; [frugon](https://github.com/Rodiun/frugon) (a local LLM cost analyzer) covers **model routing** — finding calls that never needed your most expensive model. The `frugon` subcommand bridges the two:
+
+```bash
+claude-token-saver frugon               # last 30 days → ./frugon-export.jsonl
+claude-token-saver frugon --run         # export + run frugon analyze immediately
+claude-token-saver frugon --days 7 --project myproj --out logs.jsonl
+```
+
+- Converts `~/.claude/projects/` transcripts into the OpenAI-compatible JSONL frugon reads. **Analysis is fully local** — no logs or keys leave your machine (same principle frugon holds).
+- **Cache-weighted tokens (default):** frugon doesn't know about prompt caching, so raw physical tokens would overstate your spend ~10x. By default the export folds in Anthropic's cache multipliers (read 0.1x · 5m write 1.25x · 1h write 2x) so frugon's dollar figures match your real bill. Use `--raw-tokens` for physical counts.
+- Preserves the signals frugon's easy/hard router reads (prompt/completion tokens, conversation depth) plus the last user prompt and reply text for `--measure` quality sampling. Strip text with `--no-content`.
+- Install frugon with `pipx install frugon` (if models show as unpriced, run `frugon update`).
+
+## 🔀 route-scan — "this recurring task could run on haiku"
+
+The practical follow-through of the frugon integration. It applies frugon-style difficulty analysis at the **episode (user request) level** to your session history, finds easy work your expensive model (opus/fable) keeps doing, and proposes promoting it into a haiku-subagent delegation rule. Fully local, zero token cost.
+
+```bash
+claude-token-saver route-scan                    # scan (24h cache) + print candidates
+claude-token-saver harness promote R1 --project  # promote candidate R1 to a ratchet rule
+claude-token-saver route-scan dismiss 1          # not interested — won't resurface
+```
+
+How it works (session-boundary calibration, NOT a real-time router):
+1. `install` registers a SessionStart hook that injects the cached scan results as session context on startup and `/clear` (the scan itself refreshes in the background, once a day).
+2. When a recurring (≥3×) easy pattern exists, the statusline shows a `🅷⚠ route? R1` chip and Claude asks you whether to register it, and at which scope (`--project`/`--global`).
+3. Promoted rules accumulate in ratchet.md, so **from the next session on, the main model delegates that work type to a haiku subagent automatically**.
+
+Recommended companion setup: create `model: haiku` subagents under `~/.claude/agents/` (e.g. haiku-explore / haiku-runner / haiku-translate) so the rules are immediately actionable.
+
 ## Spike issue codes
 
 | Code | Meaning |
@@ -213,6 +250,20 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.0.1 (2026-07-13)
+- **`harness pull` redefined** — v3.0.0's "copy global ratchet → project" was pointless (the global ratchet already applies to every project as the upper layer of the hierarchy) and is removed. `pull` now registers the **author-curated ratchet rules** bundled with the package (`presets/ratchet-rules.md`) into your global ratchet — six general-purpose rules promoted from real recurring mistakes; opt-in and idempotent.
+
+### v3.0.0 (2026-07-13)
+- **Major bump** — with v2.19's frugon integration and v2.20's route-scan, the product's character shifted from "after-the-fact token monitor" to "a routing layer that pushes recurring easy work down to cheaper models", so this ships as a major. No breaking changes (every existing command and setting remains compatible).
+- **route-scan promote fix** — `harness promote R<N> --project` now writes the rule into the `.claude/ratchet.md` of the project the candidate was **detected in** (previously it landed in whatever directory the CLI ran from). The scan stores each candidate's real session path (`projectPath`); promoting a foreign-project candidate from a pre-3.0 cache without that field is refused with a pointer to `route-scan --refresh`.
+- **New `harness pull`** — redefined in v3.0.1 (see above).
+
+### v2.20.0 (2026-07-13)
+- **route-scan**: detect recurring easy work on expensive models → `🅷⚠ route? R<N>` chip + SessionStart hook context injection + `harness promote R<N> --project|--global` to promote haiku-delegation ratchet rules.
+
+### v2.19.0 (2026-07-12)
+- **frugon integration**: `claude-token-saver frugon` — export session transcripts as [frugon](https://github.com/Rodiun/frugon)-compatible JSONL for model-routing savings analysis (`--run` to analyze immediately; cache-weighted tokens by default).
+
 ### v2.18.0 (2026-07-02)
 - **1M-context warning re-scoped** — current models (Fable 5, Opus 4.6–4.8, Sonnet 5) all default to a 1M window with no long-context premium since Opus 4.7, so the "1M mode ON = expensive" framing is retired. The warning is now a **usage signal**: `⚠ 1M ON` → `⚠ Ctx 200k+` (a single request actually exceeded 200k), and remediation is reordered to lead with `/compact`/`/clear` + `/effort` instead of "disable 1M". The incorrect "long-context pricing kicks in past 200k" copy is fixed.
 - **📦 segment shows live usage** — reads `context_window.used_percentage` from Claude Code's stdin and renders `📦 Ctx 68% of 1M`, colored by fill (green <70 / yellow 70–89 / red 90+). Falls back to transcript-inferred size when stdin is absent (1M now yellow, not red).

package/README.md

@@ -82,6 +82,8 @@ Claude 안에서 `/claude-token-saver` Skill을 실행하거나 칩 문구를
 | `claude-token-saver handoff` | 작업 상태를 `HANDOFF-*.md`로 백업 (캡 임박 시) |
 | `claude-token-saver mode [keywords...]` | 출력 설정 (`icon`/`text`, `ko`/`en`, `1h`~`30d` 윈도 등) |
 | `claude-token-saver harness ...` | 🅷 Harness 관리 (아래 참고) |
+| `claude-token-saver frugon` | 세션 기록 → [frugon](https://github.com/Rodiun/frugon) 호환 JSONL 내보내기 (모델 라우팅 절감 분석, 아래 참고) |
+| `claude-token-saver route-scan` | 상위 모델이 반복 처리한 easy 작업 감지 → haiku 위임 랫쳇 룰 제안 (아래 참고) |
 | `claude-token-saver install` | Skill·statusline 수동 등록 |
 
 출력 언어는 `mode ko` / `mode en`으로 전환합니다 (기본 영어, statusline 칩은 항상 기호). 전체 옵션은 [영문 README](./README.en.md#options) 참고.
@@ -95,11 +97,14 @@ claude-token-saver harness init                # 이 프로젝트에 셋업
 claude-token-saver harness init --global       # ~/.claude/CLAUDE.md — 모든 프로젝트 적용
 claude-token-saver harness check               # 현재 점수 (글로벌 fallback 인정)
 claude-token-saver harness promote <N> --project|--global   # 경고 #N → ratchet 룰 (스코프 필수)
+claude-token-saver harness promote "<룰 텍스트>" --project|--global  # 내가 직접 정의한 룰도 같은 명령으로 등록
+claude-token-saver harness pull                # 패키지 동봉 큐레이션 룰 → 내 글로벌 랫쳇에 등록 (opt-in, 중복 스킵)
 claude-token-saver harness list / rm <N>       # 룰 조회 / 삭제 (자동 .bak)
 claude-token-saver harness off | on            # 🅷 표시 토글
 ```
 
 - `promote`는 non-TTY(스크립트·LLM 호출)에서 `--project`/`--global` 플래그가 **필수** — 스코프가 묻지 않고 결정되는 사고를 막기 위한 설계입니다.
+- `pull`은 패키지에 동봉된 **제작자 큐레이션 랫쳇 룰**(`presets/ratchet-rules.md` — 실제 반복 사고에서 승격된 범용 룰만)을 내 글로벌 랫쳇(`~/.claude/ratchet.md`)에 등록합니다. 설치(`install`)나 `init`은 아무것도 자동 주입하지 않으며, `pull`은 항상 opt-in이고 재실행해도 중복이 없습니다(멱등). 마음에 안 드는 룰은 `harness rm`으로 제거하면 됩니다.
 - 🅷⚠ 런타임 경고(`ratchet?` `no-evidence` `PEV-skip`)는 30분 후 자동 만료되고, 하위 디렉터리 세션도 프로젝트에 올바르게 매칭됩니다. PEV-skip은 변경성 도구(Edit/Write/Bash)만 카운트해 읽기 위주 세션에서는 발동하지 않습니다 (v2.16.0+).
 
 <details>
@@ -114,6 +119,38 @@ ratchet의 가치는 **한 방향 누적**에 있습니다. 룰을 가볍게 지
 삭제 시 `.bak`이 남지만 **그 룰이 박힌 세션 컨텍스트(왜)는 복원되지 않습니다.**
 </details>
 
+## 🔀 frugon 연계 — "어떤 호출을 싼 모델로 내릴 수 있나"
+
+claude-token-saver가 캐시·컨텍스트 낭비를 잡는다면, [frugon](https://github.com/Rodiun/frugon)(로컬 LLM 비용 분석기)은 **모델 라우팅** 절감 — 굳이 비싼 모델이 필요 없는 호출 찾기 — 을 다룹니다. `frugon` 서브커맨드가 둘을 연결합니다:
+
+```bash
+claude-token-saver frugon               # 최근 30일 세션 → ./frugon-export.jsonl
+claude-token-saver frugon --run         # 내보내기 + frugon analyze 바로 실행
+claude-token-saver frugon --days 7 --project myproj --out logs.jsonl
+```
+
+- `~/.claude/projects/`의 transcript를 frugon이 읽는 OpenAI 호환 JSONL로 변환합니다. **분석은 전부 로컬** — 로그도 키도 밖으로 나가지 않습니다 (frugon의 원칙과 동일).
+- **캐시 가중 토큰(기본):** frugon은 프롬프트 캐싱을 모르기 때문에 물리 토큰을 그대로 주면 비용이 ~10배 과대평가됩니다. 기본값은 캐시 read 0.1x · 5m write 1.25x · 1h write 2x를 접어 넣은 유효 토큰이라 frugon의 달러 견적이 실제 청구액과 일치합니다. 물리 토큰이 필요하면 `--raw-tokens`.
+- frugon의 easy/hard 분류가 쓰는 신호(프롬프트·응답 토큰, 대화 깊이)와 `--measure` 품질 검증에 쓰는 마지막 유저 프롬프트·응답 텍스트를 보존합니다. 텍스트를 빼고 싶으면 `--no-content`.
+- frugon 설치: `pipx install frugon` (모델이 unpriced로 나오면 `frugon update`).
+
+## 🔀 route-scan — "이 반복 작업, haiku로 내려도 됩니다"
+
+frugon 연계의 실전 버전입니다. frugon식 난이도 분석을 **에피소드(사용자 요청) 단위**로 세션 기록에 적용해, 상위 모델(opus/fable)이 반복 처리해 온 easy 작업을 찾아 haiku 서브에이전트 위임 룰로 승격하도록 제안합니다. 전 과정 로컬, 토큰 비용 0.
+
+```bash
+claude-token-saver route-scan                    # 스캔 (24h 캐시) + 후보 출력
+claude-token-saver harness promote R1 --project  # 후보 R1을 랫쳇 룰로 등록
+claude-token-saver route-scan dismiss 1          # 관심 없으면 무시 (재스캔에도 안 뜸)
+```
+
+동작 구조 (실시간 라우팅이 아니라 **세션 경계 캘리브레이션**):
+1. `install` 시 SessionStart 훅이 등록되어, 새 세션 시작·`/clear` 때 캐시된 스캔 결과를 세션 컨텍스트로 주입합니다 (스캔 자체는 백그라운드에서 일 1회).
+2. 반복(≥3회) easy 패턴이 있으면 statusline에 `🅷⚠ route? R1` 칩이 뜨고, Claude가 등록 여부와 scope(`--project`/`--global`)를 물어봅니다.
+3. 등록된 룰은 ratchet.md에 쌓여 **다음 세션부터 메인 모델이 해당 유형을 haiku 서브에이전트로 자동 위임**합니다.
+
+권장 사전 준비: `~/.claude/agents/`에 `model: haiku` 서브에이전트(예: haiku-explore / haiku-runner / haiku-translate)를 만들어 두면 룰이 바로 실행 가능해집니다.
+
 ## 토큰 급증 원인 코드
 
 | 코드 | 의미 |
@@ -170,6 +207,20 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.0.1 (2026-07-13)
+- **`harness pull` 재정의** — v3.0.0의 "글로벌 랫쳇 → 프로젝트 복사"는 글로벌 랫쳇이 이미 프로젝트의 상위 계층으로 항상 적용되므로 무의미해 제거. `pull`은 이제 패키지에 동봉된 **제작자 큐레이션 랫쳇 룰**(`presets/ratchet-rules.md`)을 사용자의 글로벌 랫쳇에 등록합니다 — 실제 반복 사고에서 승격된 범용 룰 6종, opt-in·멱등.
+
+### v3.0.0 (2026-07-13)
+- **메이저 승격** — v2.19 frugon 연계 + v2.20 route-scan으로 "사후 토큰 모니터링 도구"에서 "반복 easy 작업을 싼 모델로 내려보내는 라우팅 계층"으로 제품 성격이 바뀌어 메이저 버전을 올립니다. Breaking change는 없습니다 (기존 명령·설정 전부 호환).
+- **route-scan promote 교정** — `harness promote R<N> --project`가 이제 후보가 **감지된 프로젝트**의 `.claude/ratchet.md`에 룰을 기록합니다 (이전에는 CLI를 실행한 디렉터리에 기록되는 버그). 스캔이 후보에 실제 세션 경로(`projectPath`)를 저장하며, 이 필드가 없는 구버전 캐시에서 다른 프로젝트 후보를 승격하려 하면 `route-scan --refresh`를 안내하고 중단합니다.
+- **`harness pull` 신설** — v3.0.1에서 재정의됨 (위 참고).
+
+### v2.20.0 (2026-07-13)
+- **route-scan**: 상위 모델이 반복 처리한 easy 작업 감지 → `🅷⚠ route? R<N>` 칩 + SessionStart 훅 컨텍스트 주입 + `harness promote R<N> --project|--global`로 haiku 위임 랫쳇 룰 승격.
+
+### v2.19.0 (2026-07-12)
+- **frugon 연계**: `claude-token-saver frugon` — 세션 transcript를 [frugon](https://github.com/Rodiun/frugon) 호환 JSONL로 내보내 모델 라우팅 절감 분석 (`--run`으로 즉시 분석, 캐시 가중 토큰 기본).
+
 ### v2.18.0 (2026-07-02)
 - **1M 컨텍스트 경고 의미 재정의** — 현재 모델(Fable 5, Opus 4.6~4.8, Sonnet 5)은 전부 1M 윈도가 기본이고 Opus 4.7부터 장기 컨텍스트 프리미엄도 없어, "1M 모드 ON = 비쌈" 프레임을 폐기했습니다. 경고는 이제 **실사용 신호**입니다: `⚠ 1M ON` → `⚠ Ctx 200k+`(단일 요청이 실제로 200k 초과), 처방도 "1M 끄기" 우선에서 "`/compact`/`/clear` + `/effort` 점검" 우선으로 재정렬. 잘못된 "200k 초과 시 장기 요금 적용" 문구 정정.
 - **📦 세그먼트가 실시간 사용률 표시** — Claude Code stdin의 `context_window.used_percentage`를 사용해 `📦 Ctx 68% of 1M` 형태로 렌더 (사용률 기준 녹 <70 / 황 70–89 / 적 90+). stdin이 없으면 기존 크기 추론으로 폴백하되 1M은 빨강 대신 노랑.

package/bin/cli.js

@@ -9,6 +9,9 @@
  *   npx claude-token-saver --format json      # JSON output
  *   npx claude-token-saver --format csv       # CSV output
  *   npx claude-token-saver --project myproj   # filter by project
+ *   npx claude-token-saver route-scan         # detect recurring easy work → haiku-delegation candidates
+ *   npx claude-token-saver frugon             # export transcripts → frugon JSONL (model-routing analysis)
+ *   npx claude-token-saver frugon --run       # export + run `frugon analyze`
  *   npx claude-token-saver --install-hook     # install PostToolUse hook
  *   npx claude-token-saver --uninstall-hook   # remove hook
  *   npx claude-token-saver --hook-run         # internal: called by hook
@@ -398,6 +401,7 @@ async function main() {
     };
     const r = installAll({ force });
     print('skill', r.skill);
+    print('SessionStart hook (route-scan)', r.sessionStartHook);
     {
       const s = r.statusline;
       const verb = s.action === 'exists' ? 'already configured (refreshInterval=5)'
@@ -462,11 +466,173 @@ async function main() {
     return;
   }
 
+  // Subcommand: route-scan — detect recurring easy work on expensive models
+  // and propose model-delegation ratchet rules. Zero token cost, fully local.
+  //   claude-token-saver route-scan                 # scan (24h cache) + print candidates
+  //   claude-token-saver route-scan --refresh       # force rescan
+  //   claude-token-saver route-scan --days 30       # wider lookback
+  //   claude-token-saver route-scan --hook          # SessionStart hook mode (context injection)
+  //   claude-token-saver route-scan dismiss <N>     # mute candidate R<N>
+  // Promote a candidate to a ratchet rule (scope is always explicit):
+  //   claude-token-saver harness promote R<N> --project|--global
+  if (args[0] === 'route-scan') {
+    const rs = await import('../src/route-scan.js');
+    const { userLanguage } = await import('../src/config.js');
+    const lang = userLanguage();
+
+    if (args[1] === 'dismiss') {
+      const n = parseInt(args[2], 10);
+      if (!Number.isFinite(n)) {
+        console.error('Usage: claude-token-saver route-scan dismiss <N>   # N from `route? R<N>`');
+        process.exit(1);
+      }
+      const cand = rs.resolveCandidate(n);
+      if (!cand) {
+        console.error(`No route candidate R${n}. Run: claude-token-saver route-scan`);
+        process.exit(1);
+      }
+      console.log(lang === 'ko'
+        ? `R${n} 무시 처리: ${cand.label} (${cand.project}) — 재스캔에도 다시 뜨지 않습니다.`
+        : `Dismissed R${n}: ${cand.label} (${cand.project}) — won't resurface on rescans.`);
+      return;
+    }
+
+    // --hook: SessionStart hook mode. Never scans inline (session start must
+    // stay fast) — reads the cache, kicks a detached refresh when stale, and
+    // prints delegation-candidate context for the new session.
+    if (hasFlag('--hook')) {
+      let cache = rs.readRouteScan();
+      if (!rs.isCacheFresh(cache)) {
+        try {
+          const { spawn } = await import('node:child_process');
+          spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
+            { detached: true, stdio: 'ignore' }).unref();
+        } catch { /* refresh is best-effort; stale cache still usable below */ }
+      }
+      const open = rs.openCandidates(cache);
+      if (open.length === 0) return; // silent — nothing to inject
+      const lines = [];
+      lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 상위 모델(opus/fable)이 처리한 반복 easy 작업이 감지되었습니다:`);
+      for (const c of open) {
+        lines.push(`  R${c.id} (×${c.count}, ${c.project}): ${c.label} → ${c.agent} 위임 권장 (scope 제안: ${c.suggestedScope})`);
+        lines.push(`      예시: "${c.example}"`);
+      }
+      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;
+    }
+
+    const days = parseFloat(getArg('--days') || '14');
+    let cache = rs.readRouteScan();
+    if (hasFlag('--refresh') || !rs.isCacheFresh(cache) || (cache && cache.days !== days)) {
+      cache = await rs.runRouteScan({ days });
+    }
+    if (hasFlag('--quiet')) return;
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(cache, null, 2));
+      return;
+    }
+    const easyPct = cache.totalEpisodes ? Math.round(cache.easyEpisodes / cache.totalEpisodes * 100) : 0;
+    console.log(lang === 'ko'
+      ? `route-scan — 최근 ${cache.days}일: 에피소드 ${cache.totalEpisodes}건 중 easy ${cache.easyEpisodes}건 (${easyPct}%)  [스캔: ${cache.scannedAt}]`
+      : `route-scan — last ${cache.days}d: ${cache.easyEpisodes}/${cache.totalEpisodes} episodes easy (${easyPct}%)  [scanned: ${cache.scannedAt}]`);
+    const open = rs.openCandidates(cache);
+    if (open.length === 0) {
+      console.log(lang === 'ko'
+        ? '위임 후보 없음 (반복 3회 미만이거나 이미 처리됨).'
+        : 'No delegation candidates (below recurrence threshold or already resolved).');
+      return;
+    }
+    console.log(lang === 'ko' ? '\n위임 후보:' : '\nDelegation candidates:');
+    for (const c of open) {
+      console.log(`  R${c.id}  ×${c.count}  ${c.label} → ${c.agent}  [${c.project}] (scope 제안: ${c.suggestedScope})`);
+      console.log(`       예시: "${c.example}"`);
+      console.log(`       룰: ${c.rule}`);
+    }
+    console.log('');
+    console.log(lang === 'ko' ? '등록 / 무시:' : 'Promote / dismiss:');
+    console.log('  claude-token-saver harness promote R<N> --project|--global');
+    console.log('  claude-token-saver route-scan dismiss <N>');
+    return;
+  }
+
+  // Subcommand: frugon — export Claude Code transcripts to the JSONL format
+  // frugon (local LLM cost analyzer, github.com/Rodiun/frugon) analyzes, so
+  // users can see which calls could route to a cheaper model.
+  //   claude-token-saver frugon                      # export last 30 days → ./frugon-export.jsonl
+  //   claude-token-saver frugon --days 7             # narrower window
+  //   claude-token-saver frugon --project myproj     # filter by project dir substring
+  //   claude-token-saver frugon --out PATH           # custom output path
+  //   claude-token-saver frugon --raw-tokens         # physical token counts (no cache weighting)
+  //   claude-token-saver frugon --no-content         # strip prompt/reply text (counts only)
+  //   claude-token-saver frugon --run                # run `frugon analyze` on the export
+  if (args[0] === 'frugon') {
+    const { exportFrugonLogs } = await import('../src/frugon-export.js');
+    const { userLanguage } = await import('../src/config.js');
+    const lang = userLanguage();
+    const days = parseFloat(getArg('--days') || '30');
+    const outPath = getArg('--out') || 'frugon-export.jsonl';
+    const cacheWeighted = !hasFlag('--raw-tokens');
+    const includeContent = !hasFlag('--no-content');
+    const res = await exportFrugonLogs({
+      days,
+      projectFilter: getArg('--project') || undefined,
+      outPath,
+      cacheWeighted,
+      includeContent,
+    });
+    if (res.records === 0) {
+      console.log(lang === 'ko'
+        ? `최근 ${days}일 내 세션 기록이 없습니다 (~/.claude/projects).`
+        : `No session records in the last ${days} days (~/.claude/projects).`);
+      return;
+    }
+    console.log(lang === 'ko'
+      ? `frugon 로그 내보내기 완료: ${res.outPath}`
+      : `frugon log export complete: ${res.outPath}`);
+    console.log(`  ${res.records} calls / ${res.sessions} sessions / last ${days}d`);
+    const byModel = Object.entries(res.models).sort((a, b) => b[1] - a[1]);
+    for (const [model, count] of byModel) console.log(`    ${model}: ${count}`);
+    console.log(cacheWeighted
+      ? (lang === 'ko'
+        ? '  prompt_tokens는 캐시 가중치 적용값 (read 0.1x, 5m write 1.25x, 1h write 2x) — frugon 비용이 실제 청구액과 일치. 해제: --raw-tokens'
+        : '  prompt_tokens are cache-weighted (read 0.1x, 5m write 1.25x, 1h write 2x) so frugon costs match your real bill. Disable: --raw-tokens')
+      : (lang === 'ko'
+        ? '  prompt_tokens는 물리 토큰 수 (캐시 가중치 없음 — frugon 비용이 실제보다 크게 나옴)'
+        : '  prompt_tokens are raw physical counts (no cache weighting — frugon will overstate cost)'));
+    if (hasFlag('--run')) {
+      const { spawnSync } = await import('node:child_process');
+      console.log('');
+      const run = spawnSync('frugon', ['analyze', res.outPath], { stdio: 'inherit' });
+      if (run.error && run.error.code === 'ENOENT') {
+        console.error(lang === 'ko'
+          ? 'frugon이 PATH에 없습니다. 설치: pipx install frugon  (또는 pip install frugon)'
+          : 'frugon not found on PATH. Install: pipx install frugon  (or pip install frugon)');
+        process.exit(1);
+      }
+      if (typeof run.status === 'number' && run.status !== 0) process.exit(run.status);
+      return;
+    }
+    console.log('');
+    console.log(lang === 'ko' ? '다음 단계:' : 'Next step:');
+    console.log(`  frugon analyze ${res.outPath}`);
+    console.log(lang === 'ko'
+      ? '  (frugon 미설치 시: pipx install frugon — 분석은 전부 로컬에서 실행됩니다)'
+      : '  (if frugon is not installed: pipx install frugon — analysis runs fully local)');
+    console.log(lang === 'ko'
+      ? '  (unpriced 모델이 나오면: frugon update 로 가격표를 갱신하세요)'
+      : '  (if models show as unpriced: run `frugon update` to refresh the pricing table)');
+    return;
+  }
+
   // Subcommand: harness — manage the project's CLAUDE.md harness rules.
   //   claude-token-saver harness init       # write CLAUDE.md (5 sections) + ratchet.md
   //   claude-token-saver harness uninit     # remove harness block from CLAUDE.md (backup kept)
   //   claude-token-saver harness check      # show 🅷 N/5 + which sections are missing
   //   claude-token-saver harness promote "<rule>"  # append a rule to ratchet.md
+  //   claude-token-saver harness pull [--global|--project]  # register the package's curated preset rules (default global)
   //   claude-token-saver harness off | on   # toggle the statusline 🅷 segment
   if (args[0] === 'harness') {
     const sub = args[1];
@@ -485,7 +651,7 @@ async function main() {
       }
       return dflt;
     };
-    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessListRules, harnessRmRule, findProjectRoot } =
+    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessPull, harnessListRules, harnessRmRule, findProjectRoot } =
       await import('../src/harness.js');
     const { HARNESS_SECTIONS } = await import('../src/harness-templates.js');
     const { loadConfig, saveConfig } = await import('../src/config.js');
@@ -579,6 +745,28 @@ async function main() {
         }
         rule = `반복 감지 ×${cand.count}: ${cand.pattern} — TODO: 원인·예방책 한 줄로`;
       }
+      // R-prefixed arg → route-scan delegation candidate (statusline `route? R<N>`).
+      // The rule text is pre-generated by the scan; promoting also resolves the
+      // candidate so the chip stops and rescans don't resurface it.
+      let routeCandidateId = null;
+      let routeCandidate = null;
+      if (/^[Rr]\d+$/.test(raw)) {
+        const n = parseInt(raw.slice(1), 10);
+        const rs = await import('../src/route-scan.js');
+        const cand = (rs.openCandidates(rs.readRouteScan()) || []).find((c) => c.id === n);
+        if (!cand) {
+          console.error(`No open route candidate R${n}. Run: claude-token-saver route-scan`);
+          process.exit(1);
+        }
+        rule = cand.rule;
+        routeCandidateId = n;
+        routeCandidate = cand;
+        if (!scope) {
+          console.error(`Route candidate R${n} requires an explicit scope (suggested: --${cand.suggestedScope}).`);
+          console.error('Ask the user, then pass --project or --global.');
+          process.exit(1);
+        }
+      }
       // Scope resolution: explicit flag wins. Otherwise prompt interactively
       // when running on a TTY; in non-TTY (CI/scripts) require an explicit
       // flag so the choice is never silently made for the caller.
@@ -604,9 +792,31 @@ async function main() {
           process.exit(1);
         }
       }
-      const r = harnessPromote(rule, { scope });
+      // Route candidates were detected in a specific project's sessions — a
+      // --project rule must land in THAT project's ratchet.md, not the cwd's.
+      // The candidate carries the real session cwd (projectPath); older cached
+      // scans predate that field, so fall back to verifying the cwd matches.
+      let promoteRoot;
+      if (routeCandidate && scope === 'project') {
+        const rs = await import('../src/route-scan.js');
+        if (routeCandidate.projectPath) {
+          promoteRoot = findProjectRoot(routeCandidate.projectPath);
+        } else if (rs.mungeProjectPath(findProjectRoot()) !== routeCandidate.project) {
+          console.error(`Route candidate R${routeCandidateId} was detected in another project (${routeCandidate.project}),`);
+          console.error('but this cached scan predates project-path tracking.');
+          console.error('Re-scan to capture it, then promote again:');
+          console.error('  claude-token-saver route-scan --refresh');
+          process.exit(1);
+        }
+      }
+      const r = harnessPromote(rule, promoteRoot ? { scope, root: promoteRoot } : { scope });
       console.log(`Appended to ${r.path} [${r.scope}]:`);
       console.log(`  - ${rule}`);
+      if (routeCandidateId !== null) {
+        const rs = await import('../src/route-scan.js');
+        rs.resolveCandidate(routeCandidateId);
+        console.log(`(route candidate R${routeCandidateId} resolved — 다음 세션부터 자동 위임 룰로 적용됩니다)`);
+      }
       if (/^\d+$/.test(raw)) {
         console.log('\n👉 ratchet.md를 열어 TODO 부분을 실제 룰로 다듬어주세요.');
       }
@@ -659,6 +869,25 @@ async function main() {
       return;
     }
 
+    if (sub === 'pull') {
+      // Register the package's curated preset rules (presets/ratchet-rules.md)
+      // into the user's ratchet — global by default (they're tool/environment
+      // rules, and a project ratchet inherits global anyway). Strictly opt-in:
+      // install/init never auto-injects rules.
+      const scope = parseHarnessScope(args.slice(2), 'global');
+      const r = harnessPull({ scope });
+      console.log(`Curated preset rules → ${r.path} [${r.scope}]`);
+      if (r.added.length) {
+        console.log(`✅ ${r.added.length}/${r.presets} rule(s) registered:`);
+        for (const t of r.added) console.log(`  - ${t}`);
+      } else {
+        console.log(`No new rules — all ${r.presets} presets already registered.`);
+      }
+      if (r.skippedRules && r.added.length) console.log(`   (${r.skippedRules} already present — skipped)`);
+      console.log('\n필요 없는 룰은 언제든: claude-token-saver harness list / rm <N>');
+      return;
+    }
+
     if (sub === 'list' || sub === 'ls') {
       const wantGlobal = hasFlag('--global');
       const wantProject = hasFlag('--project') || !wantGlobal;
@@ -722,7 +951,7 @@ async function main() {
     }
 
     console.error(`Unknown harness subcommand: ${sub}`);
-    console.error('Usage: claude-token-saver harness [check|init|uninit [--purge-ratchet]|promote "<rule>"|list|rm <N>|off|on]');
+    console.error('Usage: claude-token-saver harness [check|init|uninit [--purge-ratchet]|promote "<rule>"|pull [--global|--project]|list|rm <N>|off|on]');
     process.exit(1);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.18.0",
+  "version": "3.0.1",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   "files": [
     "bin/",
     "src/",
+    "presets/",
     "examples/",
     "README.md",
     "README.en.md"

package/presets/ratchet-rules.md

@@ -0,0 +1,16 @@
+# claude-token-saver 추천 Ratchet 룰 (curated presets)
+
+이 파일은 패키지에 동봉되는 제작자 큐레이션 랫쳇 룰입니다.
+`claude-token-saver harness pull`을 실행하면 아래 룰이 사용자의
+글로벌 랫쳇(`~/.claude/ratchet.md`)에 등록됩니다 (opt-in, 중복 자동 스킵).
+
+실제 반복 실수에서 승격된 룰만 담습니다 — 이론이 아니라 사고 이력.
+
+## Rules
+
+- 웹 fetch/search에서 robots·UA 차단('unable to fetch' 등)이 발생하면 → curl에 브라우저 UA(Mozilla/5.0 ... Chrome/...) 헤더를 붙여 재시도. reddit 등은 .json 엔드포인트 + UA 조합으로 접근 가능
+- ratchet 룰 promote 호출 직전 사용자에게 scope(project/global)를 먼저 묻는다 — Bash 환경은 non-TTY라 CLI readline 프롬프트가 안 뜨므로, 호출자(LLM)가 대신 묻고 --project/--global 플래그를 명시해 실행
+- 자동화 도구가 grep·정규식으로 찾는 마커 텍스트(헤더·앵커·키워드 라인)는 리팩터링·압축·수정 금지 — 정확 매칭 검출은 한 글자만 바뀌어도 깨짐
+- 자동화 설계에서 vision/screenshot 루프가 보이면 → 호출 가능한 함수·API·MCP tool부터 찾는다. 통제 가능한 내부 도구는 무조건 API, 통제 불가 외부 SaaS만 vision 차선책. 인터페이스를 바꾼 뒤에 모델을 내린다 — 거꾸로 가면 토큰 폭발
+- 입력 데이터(ground-truth) 변경 시 그에 의존하는 모든 파생 자산을 끝까지 재생성한다 — 중간 단계를 생략하면 stale 산출물이 새 입력 위에 얹혀 결과가 깨짐
+- 탐색·조회·상태 확인·명령 실행 같은 단순 요청은 haiku 서브에이전트(haiku-explore·haiku-runner 등)로 위임해 상위 모델 토큰을 아낀다

package/src/frugon-export.js

@@ -0,0 +1,211 @@
+/**
+ * frugon export — convert Claude Code session transcripts into the
+ * OpenAI-compatible JSONL log format frugon analyzes.
+ * (frugon: local LLM cost analyzer — github.com/Rodiun/frugon)
+ *
+ * One output line per API call:
+ *   {
+ *     "model": "claude-opus-4-8",
+ *     "timestamp": "2026-07-12T02:11:05.123Z",
+ *     "usage": { "prompt_tokens": 1234, "completion_tokens": 56 },
+ *     "request": { "messages": [ ...stubs..., { "role": "user", "content": "<last user prompt>" } ] },
+ *     "response": { "choices": [ { "message": { "role": "assistant", "content": "<reply>" } } ] }
+ *   }
+ *
+ * Design notes (kept in sync with frugon 0.2.x internals):
+ *  - frugon prefers the usage block for token counts, so message content is
+ *    never re-tokenized — stubs with empty content are safe.
+ *  - frugon's easy/hard difficulty score reads prompt_tokens, completion_tokens
+ *    and conversation depth (len(messages) - 1, saturating at 6 turns). We emit
+ *    up to MAX_STUB_MESSAGES role-alternating stubs so depth survives the
+ *    export without duplicating the whole conversation into every record.
+ *  - frugon has no notion of prompt caching: every prompt token is priced at
+ *    the base input rate. Claude Code sessions are cache-read heavy (~90%+),
+ *    so raw totals would overstate spend ~10x. By default we fold Anthropic's
+ *    cache multipliers (5m write 1.25x, 1h write 2x, read 0.1x) into an
+ *    "effective" prompt_tokens so frugon's dollar figures match reality.
+ *    Pass cacheWeighted: false for raw physical token counts.
+ */
+
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { discoverSessionFiles } from './parser.js';
+
+// Depth cap: frugon's turn signal saturates at 6 turns (len(messages)-1 >= 6),
+// so 7 messages carry the maximum-depth signal at minimum size.
+const MAX_STUB_MESSAGES = 7;
+
+// Anthropic cache multipliers relative to the base input rate — uniform
+// across model tiers (see src/cost.js PRICING).
+const CACHE_WEIGHTS = { write5m: 1.25, write1h: 2, read: 0.1 };
+
+/** Strip context-window suffixes like "[1m]" so frugon's pricing table matches. */
+export function normalizeModelId(model) {
+  return String(model || 'unknown').replace(/\[[^\]]*\]$/, '');
+}
+
+/**
+ * Effective prompt tokens: what the call *costs* expressed in base-rate
+ * input tokens, so frugon (which prices all prompt tokens at the input rate)
+ * reproduces the real cache-discounted spend.
+ */
+export function effectivePromptTokens(r) {
+  const tracked = (r.ephemeral5mTokens || 0) + (r.ephemeral1hTokens || 0);
+  const untracked = Math.max(0, (r.cacheCreationTokens || 0) - tracked);
+  return Math.round(
+    (r.inputTokens || 0) +
+    ((r.ephemeral5mTokens || 0) + untracked) * CACHE_WEIGHTS.write5m +
+    (r.ephemeral1hTokens || 0) * CACHE_WEIGHTS.write1h +
+    (r.cacheReadTokens || 0) * CACHE_WEIGHTS.read,
+  );
+}
+
+/** Raw physical prompt tokens (input + cache writes + cache reads). */
+export function rawPromptTokens(r) {
+  return (r.inputTokens || 0) + (r.cacheCreationTokens || 0) + (r.cacheReadTokens || 0);
+}
+
+/** Extract plain text from a Claude transcript message content field. */
+function contentText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text)
+    .join('\n');
+}
+
+/**
+ * Parse one session transcript into frugon records.
+ * Deduplicates by requestId (last-write-wins, matching parser.js) while
+ * tracking the conversation depth and last user prompt at each call.
+ */
+export async function collectSessionRecords(filePath, { cacheWeighted = true, includeContent = true } = {}) {
+  const records = new Map();
+  let depth = 0;
+  let lastUserText = '';
+  let lastCwd = '';
+
+  const rl = createInterface({
+    input: createReadStream(filePath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const msg = entry.message;
+    if (typeof entry.cwd === 'string' && entry.cwd) lastCwd = entry.cwd;
+    if (entry.type === 'user' && msg) {
+      depth += 1;
+      const text = contentText(msg.content);
+      if (text) lastUserText = text;
+      continue;
+    }
+    if (entry.type !== 'assistant' || !msg) continue;
+    depth += 1;
+
+    if (!msg.usage || !msg.id) continue;
+    // "<synthetic>" is Claude Code's placeholder for locally-generated
+    // entries (e.g. error stubs) — no real API call, nothing to price.
+    if (msg.model === '<synthetic>') continue;
+    const usage = msg.usage;
+    const reqId = entry.requestId || msg.id;
+    const r = {
+      inputTokens: usage.input_tokens || 0,
+      cacheCreationTokens: usage.cache_creation_input_tokens || 0,
+      cacheReadTokens: usage.cache_read_input_tokens || 0,
+      ephemeral5mTokens: usage.cache_creation?.ephemeral_5m_input_tokens || 0,
+      ephemeral1hTokens: usage.cache_creation?.ephemeral_1h_input_tokens || 0,
+      outputTokens: usage.output_tokens || 0,
+    };
+
+    records.set(reqId, {
+      model: normalizeModelId(msg.model),
+      timestamp: entry.timestamp || null,
+      prompt_tokens: cacheWeighted ? effectivePromptTokens(r) : rawPromptTokens(r),
+      completion_tokens: r.outputTokens,
+      depth,
+      userText: includeContent ? lastUserText : '',
+      assistantText: includeContent ? contentText(msg.content) : '',
+      cwd: lastCwd,
+    });
+  }
+
+  return [...records.values()];
+}
+
+/** Build the frugon JSONL object for one collected record. */
+export function toFrugonRecord(rec) {
+  const msgCount = Math.max(1, Math.min(rec.depth, MAX_STUB_MESSAGES));
+  const messages = [];
+  for (let i = 0; i < msgCount - 1; i++) {
+    messages.push({ role: i % 2 === 0 ? 'user' : 'assistant', content: '' });
+  }
+  messages.push({ role: 'user', content: rec.userText || '' });
+
+  const out = {
+    model: rec.model,
+    request: { messages },
+    response: {
+      choices: [{ message: { role: 'assistant', content: rec.assistantText || '' } }],
+    },
+    usage: {
+      prompt_tokens: rec.prompt_tokens,
+      completion_tokens: rec.completion_tokens,
+    },
+  };
+  if (rec.timestamp) out.timestamp = rec.timestamp;
+  return out;
+}
+
+/**
+ * Export Claude Code transcripts to a frugon-compatible JSONL file.
+ *
+ * @param {object} options
+ *   days           lookback window (default 30)
+ *   projectFilter  substring match on the project dir name
+ *   outPath        output JSONL path
+ *   cacheWeighted  fold cache pricing into prompt_tokens (default true)
+ *   includeContent include user prompt / assistant reply text (default true)
+ * @returns {Promise<{records:number, sessions:number, models:Object, outPath:string}>}
+ */
+export async function exportFrugonLogs({
+  days = 30,
+  projectFilter,
+  outPath,
+  cacheWeighted = true,
+  includeContent = true,
+} = {}) {
+  const files = await discoverSessionFiles({ days, projectFilter });
+  const models = {};
+  let recordCount = 0;
+  let sessionCount = 0;
+
+  const stream = createWriteStream(outPath, { encoding: 'utf8' });
+  for (const f of files) {
+    let recs;
+    try {
+      recs = await collectSessionRecords(f.path, { cacheWeighted, includeContent });
+    } catch {
+      continue;
+    }
+    if (recs.length === 0) continue;
+    sessionCount += 1;
+    for (const rec of recs) {
+      stream.write(JSON.stringify(toFrugonRecord(rec)) + '\n');
+      models[rec.model] = (models[rec.model] || 0) + 1;
+      recordCount += 1;
+    }
+  }
+  await new Promise((resolve, reject) => {
+    stream.end((err) => (err ? reject(err) : resolve()));
+  });
+
+  return { records: recordCount, sessions: sessionCount, models, outPath };
+}

package/src/harness.js

@@ -19,6 +19,7 @@ import {
   harnessRatchetMdInitial,
   appendRatchetRule,
 } from './harness-templates.js';
+import { routeWarningForStatusline } from './route-scan.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -276,6 +277,61 @@ export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'pr
   return { path: rmPath, root, scope };
 }
 
+/**
+ * harness pull — register the CURATED ratchet rules bundled with this package
+ * (presets/ratchet-rules.md) into the user's ratchet, global by default.
+ *
+ * Rationale: a project ratchet already inherits the global one (global is the
+ * upper layer of the hierarchy), so there is nothing to copy between the
+ * user's own scopes. What CAN'T reach the user any other way is the package
+ * author's field-tested rules — pull ships those, strictly opt-in:
+ * install/init never auto-injects anything.
+ *
+ * Deduped by rule text (ignoring the YYYY-MM-DD stamp) — idempotent.
+ * Returns { path, scope, added, skippedRules, presets }.
+ */
+export function harnessPull({ root = findProjectRoot(), scope = 'global' } = {}) {
+  const presets = presetRules();
+  const rmPath = resolveRatchetPath(scope, root);
+  const result = { path: rmPath, scope, added: [], skippedRules: 0, presets: presets.length };
+  const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}:\s*/, '').trim();
+
+  let content = existsSync(rmPath)
+    ? readFileSync(rmPath, 'utf8')
+    : harnessRatchetMdInitial();
+  const have = new Set(
+    harnessListRules({ root, scope }).rules.map((r) => stripDate(r.text)),
+  );
+  for (const rule of presets) {
+    if (have.has(rule)) {
+      result.skippedRules += 1;
+      continue;
+    }
+    content = appendRatchetRule(content, rule);
+    have.add(rule);
+    result.added.push(rule);
+  }
+  if (result.added.length) {
+    mkdirSync(dirname(rmPath), { recursive: true });
+    writeFileSync(rmPath, content);
+  }
+  return result;
+}
+
+/** Parse the bundled preset rules (markdown bullets under presets/). */
+export function presetRules() {
+  try {
+    const path = join(dirname(new URL(import.meta.url).pathname), '..', '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);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * harness list — return numbered ratchet rules from .claude/ratchet.md.
  * Numbering is 1-based and matches `harness rm <N>`.
@@ -362,6 +418,14 @@ export function harnessStatusForStatusline(cfg, { root } = {}) {
       else if (state.pevSkip) warning = 'PEV-skip';
     }
   }
+  // 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.
+  if (!warning) {
+    try {
+      warning = routeWarningForStatusline(projectRoot);
+    } catch { /* scan cache unreadable — stay silent */ }
+  }
   return { ...status, warning };
 }
 

package/src/installer.js

@@ -202,10 +202,47 @@ export function installStatusline({ force = false } = {}) {
   return { path: file, action: 'updated', reason: 'replaced previous statusLine' };
 }
 
+// Registers the SessionStart hook that surfaces route-scan delegation
+// candidates as session context (startup + /clear). Idempotent: skips when a
+// claude-token-saver route-scan hook is already present; never touches other
+// hooks the user configured.
+const ROUTE_SCAN_HOOK_COMMAND = 'claude-token-saver route-scan --hook';
+
+export function installSessionStartHook() {
+  const dir = claudeUserDir();
+  const file = join(dir, 'settings.json');
+  mkdirSync(dir, { recursive: true });
+
+  let settings = {};
+  if (existsSync(file)) {
+    try {
+      settings = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (e) {
+      return { path: file, action: 'skipped', reason: `unreadable JSON (${e.message})` };
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+  const list = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
+  const already = list.some((m) =>
+    Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('route-scan --hook')),
+  );
+  if (already) return { path: file, action: 'exists' };
+
+  list.push({
+    matcher: 'startup|clear',
+    hooks: [{ type: 'command', command: ROUTE_SCAN_HOOK_COMMAND, timeout: 10 }],
+  });
+  settings.hooks.SessionStart = list;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: 'created' };
+}
+
 export function installAll({ force = false } = {}) {
   return {
     skill: installSkill({ force }),
     statusline: installStatusline({ force }),
+    sessionStartHook: installSessionStartHook(),
     legacy: removeLegacyCommand(),
   };
 }

package/src/route-scan.js

@@ -0,0 +1,286 @@
+/**
+ * route-scan — detect recurring "easy" work running on expensive models and
+ * propose model-delegation ratchet rules.
+ *
+ * Runs the frugon-style difficulty idea at the EPISODE level (one user
+ * request = the consecutive API calls it triggered), because per-call scoring
+ * saturates on Claude Code's large session contexts. An episode is easy when
+ * the whole request finished in few calls with little generation — exactly
+ * the work a haiku subagent could take.
+ *
+ * Fully local, zero token cost. Results are cached (24h) so the SessionStart
+ * hook can read them without re-parsing a month of transcripts.
+ *
+ * Pipeline position (per design discussion): frugon/this scan is NOT a
+ * real-time router — it is a session-boundary calibrator that feeds the
+ * existing ratchet promote flow (`harness promote R<N> --project|--global`).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { discoverSessionFiles } from './parser.js';
+import { collectSessionRecords } from './frugon-export.js';
+
+// Episode is "easy" when the whole user request finished within these bounds.
+// Calibrated on real data (2026-07): 27% of episodes, 3-6% of tokens.
+export const EASY_MAX_CALLS = 6;
+export const EASY_MAX_OUT_TOKENS = 1500;
+// A pattern must recur this often before we nag about it.
+export const MIN_RECURRENCE = 3;
+// Cache is fresh for a day — the SessionStart hook never rescans inline.
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+// Category → recommended haiku subagent. First match wins; order matters
+// (translate before read: "번역해줘" also matches the read keywords).
+const CATEGORIES = [
+  {
+    id: 'translate',
+    label: '배치 번역·정형 텍스트 변환',
+    agent: 'haiku-translate',
+    re: /번역|translate|변환해|표로 정리|포맷팅/i,
+  },
+  {
+    id: 'explore',
+    label: '탐색·조회 (파일/값 찾기)',
+    agent: 'haiku-explore',
+    re: /grep|검색|찾아|search|find|어디|위치|목록|살펴/i,
+  },
+  {
+    id: 'read',
+    label: '읽기·요약·설명',
+    agent: 'haiku-explore',
+    re: /읽어|요약|설명|정리해|summar|explain|보여줘|알려줘|뭐야|what/i,
+  },
+  {
+    id: 'run',
+    label: '명령 실행 (빌드·테스트·git)',
+    agent: 'haiku-runner',
+    re: /git |commit|push|실행|돌려|run |build|빌드|테스트|npm |pip|설치/i,
+  },
+  {
+    id: 'check',
+    label: '상태 확인·검증',
+    agent: 'haiku-explore',
+    re: /확인|맞아\?|되나|됐나|괜찮|체크|check|verify|status|점검/i,
+  },
+];
+
+// Episodes that are not user-delegable requests: bare continuations, injected
+// notifications, image pastes. These are easy but there is nothing to route.
+const SKIP_RE = /^(계속|이어서|continue|다음|proceed|진행|응|네|넵|ok|okay|yes|ㄱ+|고고)\b/i;
+const SKIP_PREFIX = ['<task-notification', '<system', '[Image:', '<local-command'];
+
+function stateDir() {
+  if (process.platform === 'win32') {
+    return join(process.env.APPDATA || homedir(), 'claude-token-saver');
+  }
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Application Support', 'claude-token-saver');
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(xdg, 'claude-token-saver');
+}
+
+export function routeScanCachePath() {
+  return join(stateDir(), 'route-scan.json');
+}
+
+/** Munge an absolute path the way Claude Code names project dirs. */
+export function mungeProjectPath(p) {
+  return String(p).replace(/[^a-zA-Z0-9-]/g, '-');
+}
+
+function categorize(text) {
+  for (const c of CATEGORIES) if (c.re.test(text)) return c;
+  return null;
+}
+
+function isSkippable(text) {
+  if (!text) return true;
+  if (SKIP_RE.test(text.trim())) return true;
+  return SKIP_PREFIX.some((p) => text.startsWith(p));
+}
+
+/** Group a session's records into episodes (consecutive same trigger prompt). */
+function toEpisodes(records) {
+  const episodes = [];
+  let cur = null;
+  for (const r of records) {
+    const text = (r.userText || '').trim();
+    if (!cur || cur.text !== text) {
+      cur = { text, calls: 0, out: 0, models: new Set(), cwd: '' };
+      episodes.push(cur);
+    }
+    cur.calls += 1;
+    cur.out += r.completion_tokens;
+    cur.models.add(r.model);
+    if (!cur.cwd && r.cwd) cur.cwd = r.cwd;
+  }
+  return episodes;
+}
+
+function isExpensiveModel(model) {
+  return !/haiku/i.test(model);
+}
+
+/**
+ * Scan transcripts and build delegation candidates.
+ * Returns the cache object (also written to disk).
+ */
+export async function runRouteScan({ days = 14 } = {}) {
+  const files = await discoverSessionFiles({ days });
+  const groups = new Map(); // "category|project" → aggregate
+  let totalEpisodes = 0;
+  let easyEpisodes = 0;
+
+  for (const f of files) {
+    let records;
+    try {
+      // Raw counts are irrelevant here (we classify by output size), and
+      // content is required for categorization.
+      records = await collectSessionRecords(f.path, { cacheWeighted: false, includeContent: true });
+    } catch {
+      continue;
+    }
+    for (const ep of toEpisodes(records)) {
+      if (!ep.text) continue;
+      totalEpisodes += 1;
+      const easy = ep.calls <= EASY_MAX_CALLS && ep.out <= EASY_MAX_OUT_TOKENS;
+      if (!easy) continue;
+      easyEpisodes += 1;
+      if (isSkippable(ep.text)) continue;
+      if (![...ep.models].some(isExpensiveModel)) continue; // already cheap
+      const cat = categorize(ep.text);
+      if (!cat) continue;
+      const key = `${cat.id}|${f.projectDir}`;
+      const g = groups.get(key) || {
+        category: cat.id,
+        label: cat.label,
+        agent: cat.agent,
+        project: f.projectDir,
+        projectPath: '',
+        count: 0,
+        models: new Set(),
+        example: '',
+      };
+      g.count += 1;
+      for (const m of ep.models) g.models.add(m);
+      if (!g.projectPath && ep.cwd) g.projectPath = ep.cwd;
+      if (!g.example || (ep.text.length < g.example.length && ep.text.length > 10)) {
+        g.example = ep.text.slice(0, 80).replace(/\s+/g, ' ');
+      }
+      groups.set(key, g);
+    }
+  }
+
+  // Keep prior dismissed/promoted signatures across rescans.
+  const prev = readRouteScan();
+  const resolved = new Set(prev?.resolved || []);
+
+  const candidates = [...groups.values()]
+    .filter((g) => g.count >= MIN_RECURRENCE)
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 5)
+    .map((g, i) => ({
+      id: i + 1,
+      signature: `${g.category}|${g.project}`,
+      category: g.category,
+      label: g.label,
+      agent: g.agent,
+      project: g.project,
+      // Real session cwd for the project (munged `project` is lossy) — lets
+      // `harness promote R<N> --project` write the rule into the project the
+      // pattern was detected in, not whatever directory the CLI runs from.
+      projectPath: g.projectPath || null,
+      count: g.count,
+      models: [...g.models],
+      example: g.example,
+      // Concentrated in one project dir → project rule; the scan groups by
+      // project already, so scope suggestion is per-candidate 'project' unless
+      // the same category recurs across 2+ projects (then 'global').
+      suggestedScope: 'project',
+      rule: `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${g.agent}(haiku) 서브에이전트로 위임한다`,
+    }));
+
+  // Same category appearing in 2+ projects → suggest global for each.
+  const catProjects = new Map();
+  for (const c of candidates) {
+    catProjects.set(c.category, (catProjects.get(c.category) || 0) + 1);
+  }
+  for (const c of candidates) {
+    if ((catProjects.get(c.category) || 0) >= 2) c.suggestedScope = 'global';
+  }
+
+  const cache = {
+    scannedAt: new Date().toISOString(),
+    days,
+    totalEpisodes,
+    easyEpisodes,
+    candidates,
+    resolved: [...resolved],
+  };
+  try {
+    const dir = stateDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(routeScanCachePath(), JSON.stringify(cache, null, 2) + '\n');
+  } catch {
+    // best-effort — scan results are still returned
+  }
+  return cache;
+}
+
+/** Read the cached scan (null when absent/corrupt). */
+export function readRouteScan() {
+  try {
+    return JSON.parse(readFileSync(routeScanCachePath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function isCacheFresh(cache) {
+  if (!cache?.scannedAt) return false;
+  const ts = Date.parse(cache.scannedAt);
+  return Number.isFinite(ts) && Date.now() - ts < CACHE_TTL_MS;
+}
+
+/** Candidates not yet promoted/dismissed. */
+export function openCandidates(cache) {
+  if (!cache?.candidates) return [];
+  const resolved = new Set(cache.resolved || []);
+  return cache.candidates.filter((c) => !resolved.has(c.signature));
+}
+
+/**
+ * Mark a candidate resolved (promoted or dismissed) so the chip stops and
+ * rescans don't resurface it. Returns the candidate or null.
+ */
+export function resolveCandidate(id) {
+  const cache = readRouteScan();
+  if (!cache) return null;
+  const cand = (cache.candidates || []).find((c) => c.id === id);
+  if (!cand) return null;
+  cache.resolved = [...new Set([...(cache.resolved || []), cand.signature])];
+  try {
+    writeFileSync(routeScanCachePath(), JSON.stringify(cache, null, 2) + '\n');
+  } catch {
+    return null;
+  }
+  return cand;
+}
+
+/**
+ * Statusline helper — cheapest possible check (one small JSON read).
+ * Returns `route? #N` for the top open candidate relevant to this project
+ * (its own project dir, or a global-scoped suggestion), else null.
+ */
+export function routeWarningForStatusline(projectRoot) {
+  const cache = readRouteScan();
+  if (!cache) return null;
+  const open = openCandidates(cache);
+  if (open.length === 0) return null;
+  const munged = mungeProjectPath(projectRoot || '');
+  const hit = open.find((c) => c.project === munged || c.suggestedScope === 'global');
+  return hit ? `route? R${hit.id}` : null;
+}