claude-token-saver 2.17.0 → 3.0.0

package/README.en.md

@@ -55,7 +55,7 @@ The statusline appears at the bottom of Claude Code right away. If auto-registra
 | `🧠` | Cache hit rate (green at 85%+) |
 | `⏳` | Cache TTL countdown — send a message before expiry to keep the cache warm |
 | `✦ current` / `📅 weekly` | 5-hour / 7-day rate-limit window usage + reset time |
-| `📦` | Context window (1M shows red — a major cost driver) |
+| `📦` | Context usage (e.g. `Ctx 68% of 1M`) — colored by fill. Current models default to 1M with no premium, but token volume itself drives per-turn cost and 5H/7D burn |
 | `💰` | Cumulative savings from prompt caching |
 
 When something is wrong, a **warning chip leads the line**:
@@ -64,7 +64,7 @@ When something is wrong, a **warning chip leads the line**:
 🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 4.8 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📅 weekly ▓░░░░░ 12% 🔄 Sun 14:26 · 📦 Ctx 200k · last 1d
 ```
 
-Chips — `🚨 5H/7D NN%` (cap imminent) · `⚠ 1M ON` · `⚠ Cache miss` · `⚠ Input spike` · `⚠ Output heavy` · `⚠ Call surge` · `⚠ Rebuild churn` · `⚠ 5m TTL`. When both windows cross 90% at once, the sooner-resetting one is promoted to 🚨 and the other stays visible as a red segment (v2.16.0+).
+Chips — `🚨 5H/7D NN%` (cap imminent) · `⚠ Ctx 200k+` (a single request actually exceeded 200k) · `⚠ Cache miss` · `⚠ Input spike` · `⚠ Output heavy` · `⚠ Call surge` · `⚠ Rebuild churn` · `⚠ 5m TTL`. When both windows cross 90% at once, the sooner-resetting one is promoted to 🚨 and the other stays visible as a red segment (v2.16.0+).
 
 ### When a chip appears
 
@@ -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,15 @@ 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                # pull your global ratchet rules into this project (dedupes)
+claude-token-saver harness pull --harness      # also pull the global harness block (5 sections)
 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.
+- `install` / `init` never auto-inject rules into a project. When you want the rules you've accumulated globally in a new project, pull them explicitly with `harness pull` (idempotent — re-running adds nothing twice).
 - 🅷⚠ 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,11 +139,43 @@ 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 |
 |---|---|
-| `LARGE_INPUT_PER_REQUEST` | single request > 250k tokens → 1M context likely |
+| `LARGE_INPUT_PER_REQUEST` | single request > 200k input tokens — per-turn re-billing and cap burn spike |
 | `LOW_HIT_RATE` | cache hit rate < 50% |
 | `BUCKET_5M_DOMINANT` | > 70% of cache writes hit the 5m bucket |
 | `HIGH_OUTPUT_RATIO` | output/input > 0.15 (output is 5× input price) |
@@ -213,6 +251,22 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### 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`** — explicitly pull your global ratchet rules into a project (`--harness` also pulls the global harness block). Dedupes by rule text, so re-running is idempotent. `install`/`init` still never auto-inject anything — pulling is always opt-in.
+
+### 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).
+- Back-compat: the legacy `⚠ 1M ON` chip and old detail strings in existing history files still resolve.
+
 ### v2.17.0 (2026-07-02)
 - **Fable 5 pricing tier** — `claude-fable-5`/`claude-mythos-5` previously fell through to the Sonnet tier ($3/$15), under-estimating costs ~3×. Now priced at the real rates ($10 input / $50 output / $12.50 5m-write / $20 1h-write / $1 read).
 - README overhaul — top-level impact summary, segment table, harness scope-flag docs, pricing table brought current.

package/README.md

@@ -55,7 +55,7 @@ npm i -g claude-token-saver
 | `🧠` | 캐시 히트율 (85%+ 녹색) |
 | `⏳` | 캐시 TTL 카운트다운 — 만료 전에 메시지를 보내면 캐시 유지 |
 | `✦ current` / `📅 weekly` | 5시간 / 7일 rate-limit 윈도 사용률 + 리셋 시각 |
-| `📦` | 컨텍스트 윈도 (1M이면 빨간 경고 — 비용 급증 요인) |
+| `📦` | 컨텍스트 사용률 (예: `Ctx 68% of 1M`) — 사용률 기준 녹/황/적. 현재 모델은 1M이 기본·프리미엄 없음이지만, 토큰량 자체가 턴당 비용과 5H/7D 한도를 태웁니다 |
 | `💰` | 캐시가 절약해준 누적 금액 |
 
 문제가 감지되면 **경고 칩이 맨 앞에** 붙습니다:
@@ -64,7 +64,7 @@ npm i -g claude-token-saver
 🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 4.8 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📅 weekly ▓░░░░░ 12% 🔄 Sun 14:26 · 📦 Ctx 200k · last 1d
 ```
 
-칩 종류 — `🚨 5H/7D NN%`(캡 임박) · `⚠ 1M ON` · `⚠ Cache miss` · `⚠ Input spike` · `⚠ Output heavy` · `⚠ Call surge` · `⚠ Rebuild churn` · `⚠ 5m TTL`. 두 윈도가 동시에 90%+면 리셋이 임박한 쪽이 🚨로 승격되고 나머지는 빨간 세그먼트로 유지됩니다 (v2.16.0+).
+칩 종류 — `🚨 5H/7D NN%`(캡 임박) · `⚠ Ctx 200k+`(단일 요청이 실제로 200k 초과) · `⚠ Cache miss` · `⚠ Input spike` · `⚠ Output heavy` · `⚠ Call surge` · `⚠ Rebuild churn` · `⚠ 5m TTL`. 두 윈도가 동시에 90%+면 리셋이 임박한 쪽이 🚨로 승격되고 나머지는 빨간 세그먼트로 유지됩니다 (v2.16.0+).
 
 ### 경고 칩이 떴을 때
 
@@ -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,15 @@ 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                # 글로벌 랫쳇 룰을 이 프로젝트로 가져오기 (중복 자동 스킵)
+claude-token-saver harness pull --harness      # 글로벌 하네스 블록(5개 섹션)까지 함께 가져오기
 claude-token-saver harness list / rm <N>       # 룰 조회 / 삭제 (자동 .bak)
 claude-token-saver harness off | on            # 🅷 표시 토글
 ```
 
 - `promote`는 non-TTY(스크립트·LLM 호출)에서 `--project`/`--global` 플래그가 **필수** — 스코프가 묻지 않고 결정되는 사고를 막기 위한 설계입니다.
+- 설치(`install`)나 `init`은 프로젝트에 룰을 자동 주입하지 않습니다. 글로벌에 쌓아둔 룰을 새 프로젝트에서 쓰고 싶을 때만 `harness pull`로 명시적으로 가져오세요 (재실행해도 중복 없음).
 - 🅷⚠ 런타임 경고(`ratchet?` `no-evidence` `PEV-skip`)는 30분 후 자동 만료되고, 하위 디렉터리 세션도 프로젝트에 올바르게 매칭됩니다. PEV-skip은 변경성 도구(Edit/Write/Bash)만 카운트해 읽기 위주 세션에서는 발동하지 않습니다 (v2.16.0+).
 
 <details>
@@ -114,11 +120,43 @@ 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)를 만들어 두면 룰이 바로 실행 가능해집니다.
+
 ## 토큰 급증 원인 코드
 
 | 코드 | 의미 |
 |---|---|
-| `LARGE_INPUT_PER_REQUEST` | 단일 요청 250k+ → 1M 컨텍스트 의심 |
+| `LARGE_INPUT_PER_REQUEST` | 단일 요청 입력이 200k 초과 — 턴당 재과금·한도 소모 급증 |
 | `LOW_HIT_RATE` | 캐시 히트율 50% 미만 |
 | `BUCKET_5M_DOMINANT` | 캐시 쓰기의 70%+가 5분 버킷 (Pro 플랜/Max 다운그레이드) |
 | `HIGH_OUTPUT_RATIO` | 출력/입력 비율 0.15 초과 (출력 단가는 입력의 5배) |
@@ -170,6 +208,22 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### 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` 신설** — 글로벌 랫쳇 룰을 프로젝트로 명시적으로 가져옵니다 (`--harness`로 글로벌 하네스 블록까지). 룰 텍스트 기준 중복 자동 스킵이라 재실행해도 안전(멱등). 설치·init은 계속 아무것도 자동 주입하지 않습니다 — 가져오기는 항상 opt-in.
+
+### 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은 빨강 대신 노랑.
+- 구버전 히스토리 호환: `⚠ 1M ON` 칩·구 디테일 문구도 계속 해석됩니다.
+
 ### v2.17.0 (2026-07-02)
 - **Fable 5 가격 티어 추가** — `claude-fable-5`/`claude-mythos-5`가 Sonnet 단가($3/$15)로 폴백돼 비용이 ~3배 과소 추정되던 문제 수정. 실제 단가(입력 $10 / 출력 $50 / 캐시쓰기 5m $12.50·1h $20 / 캐시읽기 $1) 적용.
 - README 전면 개편 — 최상위 임팩트 요약, 세그먼트 표, harness scope 플래그 문서화, 가격 테이블 최신화.

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
@@ -93,6 +96,24 @@ function bedrockDisplayFromId(id) {
   return `${family} ${m[2]}.${m[3]}`;
 }
 
+/**
+ * Live context usage from Claude Code's stdin payload (`context_window`).
+ * More accurate than inferring from transcripts: it's the CURRENT session's
+ * real fill level, updated every refresh. Shape (subset):
+ *   "context_window": { "context_window_size": 200000, "used_percentage": 68 }
+ */
+function extractContextUsage(stdinJson) {
+  const cw = stdinJson && stdinJson.context_window;
+  if (!cw || typeof cw !== 'object') return null;
+  const usedPct = Number(cw.used_percentage);
+  const size = Number(cw.context_window_size);
+  if (!Number.isFinite(usedPct)) return null;
+  return {
+    usedPct,
+    size: Number.isFinite(size) && size > 0 ? size : null,
+  };
+}
+
 function extractModel(stdinJson) {
   if (!stdinJson || !stdinJson.model) return null;
   const m = stdinJson.model;
@@ -380,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)'
@@ -444,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 [--harness]   # copy global ratchet rules (+block) into this project
   //   claude-token-saver harness off | on   # toggle the statusline 🅷 segment
   if (args[0] === 'harness') {
     const sub = args[1];
@@ -467,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');
@@ -561,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.
@@ -586,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 부분을 실제 룰로 다듬어주세요.');
       }
@@ -641,6 +869,26 @@ async function main() {
       return;
     }
 
+    if (sub === 'pull') {
+      // Pull the user's GLOBAL ratchet rules (and optionally the global
+      // harness block) into this project. Explicitly opt-in — install/init
+      // never auto-injects rules into a project.
+      const includeBlock = args.includes('--harness');
+      const r = harnessPull({ includeBlock });
+      console.log(`Pull global → project (${r.root})`);
+      if (r.added.length) {
+        console.log(`✅ ${r.added.length} rule(s) pulled into .claude/ratchet.md:`);
+        for (const t of r.added) console.log(`  - ${t}`);
+      } else {
+        console.log('No new rules to pull.');
+      }
+      if (r.skippedRules) console.log(`   (${r.skippedRules} already present — skipped)`);
+      for (const f of r.wrote.filter((w) => w.includes('CLAUDE.md'))) console.log(`✅ ${f}`);
+      for (const f of r.skipped) console.log(`   skip: ${f}`);
+      if (!includeBlock) console.log('\n글로벌 하네스 블록(CLAUDE.md 5개 섹션)까지 가져오려면: claude-token-saver harness pull --harness');
+      return;
+    }
+
     if (sub === 'list' || sub === 'ls') {
       const wantGlobal = hasFlag('--global');
       const wantProject = hasFlag('--project') || !wantGlobal;
@@ -704,7 +952,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 [--harness]|list|rm <N>|off|on]');
     process.exit(1);
   }
 
@@ -894,6 +1142,7 @@ async function main() {
   const stdinJson = readStdinJson();
   let caps = extractCaps(stdinJson);
   let model = extractModel(stdinJson);
+  const ctxLive = extractContextUsage(stdinJson);
   if (isStatusline && (caps || model)) {
     try {
       const { persistSnapshot } = await import('../src/caps-cache.js');
@@ -923,7 +1172,7 @@ async function main() {
   if (format === 'statusline') {
     if (contextWindow.size === '1M') {
       spikeChip = chipForIssues([], contextWindow);
-      chipDetail = `Context auto-promoted to 1M (max single-request ${Math.round(contextWindow.maxContext / 1000)}k tokens)`;
+      chipDetail = `Single-request context exceeded 200k (max ${Math.round(contextWindow.maxContext / 1000)}k tokens)`;
     } else {
       const recentSession = sessions
         .slice()
@@ -994,6 +1243,7 @@ async function main() {
     lastActivity,
     spikeReport,
     contextWindow,
+    ctxLive,
     spikeChip,
     caps,
     model,

package/package.json

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