claude-token-saver 3.25.1 → 3.26.0

package/README.md

@@ -162,6 +162,9 @@ Claude Code 안에서 `/claude-token-saver` Skill을 실행하거나, 칩에 적
 | `claude-token-saver korean on\|off\|status` | 한국어 문체 지침을 세션 시작 시 주입하고, 쓰기 시점 검사를 함께 설치합니다 (아래 참고) |
 | `claude-token-saver korean lint block\|warn\|off` | 쓰기 시점 검사가 위반을 어떻게 처리할지 정합니다 |
 | `claude-token-saver korean lint scope all\|prose` | 검사 범위를 모든 텍스트 파일과 문서 전용 사이에서 고릅니다 |
+| `claude-token-saver doc2md on\|off` | 첨부 문서를 모델이 읽기 전에 Markdown 으로 변환합니다 (아래 참고) |
+| `claude-token-saver doc2md <파일>` | 파일 하나를 직접 변환합니다. 진단 용도이며 실패 이유를 그대로 출력합니다 |
+| `claude-token-saver mode ttl=5m\|1h\|auto` | 캐시 TTL 버킷을 직접 지정합니다. 기본값 `auto`는 실측값을 먼저 보고, 실측값이 없으면 게이트웨이 여부로 판정합니다 |
 | `claude-token-saver --version` | 설치된 버전을 출력합니다 |
 | `claude-token-saver update-check` | 새 버전이 있는지 확인합니다 (`--refresh`로 즉시 조회, `--dismiss`로 그 버전 안내 끄기) |
 | `claude-token-saver upgrade` | 설치 경로에 맞는 명령으로 최신 버전을 설치합니다 (`--print`로 실행 없이 명령만 확인) |
@@ -364,6 +367,45 @@ npm의 `postinstall`이나 CI처럼 사람이 붙어 있지 않은 설치에서
 > 지침 원문은 [fluent-korean](https://github.com/snflkd/fluent-korean)에서 가져왔습니다. Copyright (c) 2026 snflkd, MIT License.
 > 원문은 수정하지 않았고 output style 프런트매터만 제거했습니다. 라이선스 전문은 패키지의 `presets/korean-style/LICENSE-fluent-korean`에 함께 배포합니다.
 
+## 📄 doc2md: 첨부 문서를 읽기 전에 Markdown 으로 바꿉니다
+
+pptx·xlsx·pdf·docx 를 그대로 `Read` 하면 모델이 읽지 못하는 바이트가 컨텍스트에 그대로 올라갑니다. 이 기능은 그 `Read` 를 가로채 파일을 한 번 변환해 두고, 원본 대신 변환본을 읽게 합니다.
+
+```bash
+pip install "markitdown[pptx,pdf,xlsx,docx]"   # 변환기는 파이썬 패키지입니다
+claude-token-saver doc2md on                   # Read 훅 등록
+claude-token-saver doc2md 보고서.pptx           # 직접 변환해 결과 확인
+```
+
+변환은 [markitdown](https://github.com/microsoft/markitdown)이 담당하며, 슬라이드 번호와 제목 계층, 표, 발표자 노트, 시트 구분이 모두 남습니다. 한글도 깨지지 않습니다.
+
+몇 가지는 의도적으로 하지 않습니다.
+
+- **이미지는 변환하지 않습니다.** markitdown 이 빈 결과를 돌려주고, OCR 은 실측에서 리소스 이름을 틀리게 읽었습니다(`c5.xlarge` 를 `c.xlarge` 로). 이름 자체가 내용인 문서에서는 텍스트가 없느니만 못합니다. 모델이 이미지는 직접 읽습니다.
+- **markitdown 이 없으면 조용히 실패하지 않습니다.** 설치 명령을 한 번 안내한 뒤 원본 `Read` 를 그대로 통과시킵니다. 매번 알리면 그것대로 방해가 되고, 아무 말도 하지 않으면 고장을 숨기게 됩니다.
+- **변환본은 프로젝트 안에 남기지 않습니다.** 도구의 상태 디렉터리 아래 권한 `0700` 으로 저장하므로 `.gitignore` 에 무엇을 추가할 필요가 없습니다. 파일명이 급여·계약·개인정보 같은 패턴에 걸리면 아예 변환하지 않습니다.
+- **압축 폭탄은 막습니다.** pptx·xlsx·docx 는 zip 컨테이너입니다. 선언된 크기를 먼저 걸러 내고, 선언은 조작될 수 있으므로 실제 해제 바이트도 상한과 대조합니다.
+- **엑셀은 행 수로 자릅니다.** 변환 시간은 파일 크기가 아니라 행 수를 따릅니다(실측: PDF 6.3MB 0.9초, 엑셀 5.8MB 47.75초). 5만 행을 넘으면 앞부분만 변환하고, **잘랐다는 사실과 전체 행 수를 안내에 함께 적습니다.**
+
+`claude-token-saver doc2md --clean` 으로 변환 캐시를 비우고, `doc2md off` 로 훅을 제거합니다. 훅 해제는 자기 항목만 골라 지우므로 `PreToolUse` 에 등록해 둔 다른 훅은 그대로 남습니다.
+
+## 🌐 Bedrock·Vertex 경유 환경
+
+게이트웨이를 거치면 응답이 캐시 쓰기 합계만 내려보내고 5분·1시간 버킷별 분해 값은 채우지 않습니다. 그래서 이 도구가 "캐시 쓰기가 아직 없다"와 "이 제공자는 알려 주지 않는다"를 구별하지 못했고, 판정 불가일 때 1시간을 기본값으로 잡았습니다. Bedrock 은 5분 버킷만 제공하므로 남은 시간이 최대 12배로 부풀어 보였습니다.
+
+v3.26.0부터 트랜스크립트의 모델 ID로 게이트웨이를 감지해 다음을 바로잡습니다.
+
+- 판정 불가일 때의 카운트다운 기본값이 5분이 되고, 버킷 라벨이 `5m?` 로 표시됩니다. 실측값은 `5m`, 추정은 `5m?`, 근거 없음은 `?` 로 세 단계를 구분합니다.
+- 5분 버킷에서는 카운트다운 색이 비율이 아니라 절대 시간을 따릅니다. 5분의 30%는 90초여서, 초록이 주는 여유가 실제와 어긋났습니다.
+- `⚠ 5m TTL` 경고가 이 환경에도 도달합니다. 다만 조언 문구는 다릅니다. 구독 플랜을 바꿔도 해소되지 않는 환경이므로 플랜 전환을 권하지 않습니다.
+- `Extra cost if 5m-only` 는 1시간 쓰기가 있는 경우에만 묻습니다. 이미 5분 전용인 환경에서는 질문 자체가 성립하지 않아 `+$0` 이 잘못 읽혔습니다.
+- 위임 건이 모델 ID 해석 실패로 버려졌으면 statusline 에 `🔀 N unresolved` 로 알립니다. 이전에는 "위임한 적 없음"과 화면상 구별되지 않았습니다.
+- 환경변수를 `foundation-model` ARN 으로 지정한 경우에도 모델을 해석합니다. 이름을 담고 있지 않은 `application-inference-profile` ID 는 그대로 거부합니다. 값을 추측해 넣으면 원장에 틀린 금액이 들어가기 때문입니다.
+
+감지가 틀리면 `claude-token-saver mode ttl=5m`(또는 `ttl=1h`)로 직접 지정할 수 있습니다. 지정값이 실측값보다 우선합니다.
+
+세션 기본 모델이 sonnet 이면 sonnet 위임 규칙(T1)은 구조적으로 절감이 0입니다. 같은 급으로 내려보내 봐야 차액이 없기 때문이며 이는 정상 동작입니다. 다만 `route-scan rules` 가 이 경우를 "아직 위임 없음"과 같은 문구로 표시해 고장처럼 보였으므로, 이제 현재 기본 모델 기준으로 적용되지 않는다는 사실을 따로 적습니다.
+
 ## 토큰 급증 원인 코드
 
 | 코드 | 의미 |
@@ -420,6 +462,12 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.26.0 (2026-09-04)
+- **첨부 문서를 읽기 전에 Markdown 으로 변환합니다.** pptx·xlsx·pdf·docx 를 그대로 `Read` 하면 모델이 읽지 못하는 바이트가 컨텍스트에 올라갑니다. `doc2md on` 으로 `Read` 훅을 등록하면 파일을 한 번 변환해 캐시에 두고 변환본을 읽게 합니다. 변환기가 없으면 안내를 한 번만 하고 원본 `Read` 를 통과시키며, 압축 폭탄은 막고, 5만 행이 넘는 엑셀은 앞부분만 변환한 뒤 잘랐다는 사실을 함께 알립니다. 자세한 내용은 [doc2md](#-doc2md-첨부-문서를-읽기-전에-markdown-으로-바꿉니다) 절을 참고하십시오.
+- **Bedrock·Vertex 경유 환경의 TTL 표시를 바로잡았습니다.** 게이트웨이는 버킷별 분해 값을 내려보내지 않는데, 판정 불가일 때 1시간을 기본값으로 잡고 있었습니다. 5분 버킷만 제공하는 환경에서 남은 시간이 최대 12배로 부풀어 보였습니다. 이제 모델 ID로 게이트웨이를 감지해 5분을 기본값으로 쓰고, 라벨을 `5m?` 로 적어 추정임을 밝힙니다. `mode ttl=5m` 으로 직접 지정할 수도 있습니다.
+- **위임 집계가 조용히 버려지지 않습니다.** 모델 ID를 해석하지 못해 제외된 위임이 있으면 statusline 에 `🔀 N unresolved` 로 알립니다. 이전에는 "위임한 적 없음"과 화면상 구별되지 않아, 집계가 통째로 사라져도 알 방법이 없었습니다. `foundation-model` ARN 으로 지정된 환경변수도 이제 해석합니다.
+- **한국어 지침의 적용 범위 충돌을 해소했습니다.** 주입문은 코드 주석을 검사 대상에 넣는데 벤더링한 원문은 두 번에 걸쳐 제외한다고 적고 있어서, 모델이 어느 쪽을 따를지 판단할 근거가 없었습니다. 원문은 그대로 두고 어느 쪽이 우선인지 명시하는 한 줄을 추가했습니다. 출처 표기에 들어 있던 엠대시도 지침 스스로 금지하는 표기였으므로 콜론으로 바꿨습니다.
+
 ### v3.25.0 (2026-09-04)
 - **statusline에 실행 중인 버전을 표시합니다.** 지금까지는 표 형식 리포트의 각주에만 버전이 있었기 때문에, 어떤 버전이 도는지 확인하려면 전체 리포트를 실행해야 했습니다. `--version` 플래그도 함께 추가했습니다.
 - **새 버전이 나오면 세션 시작에 물어봅니다.** statusline은 대화 상자를 띄울 수 없으므로, 알림과 질문을 나누었습니다. statusline은 `⬆ v3.24.0 → 3.25.0`으로 알리기만 하고, 실제 질문은 SessionStart 훅이 모델에게 "사용자에게 업그레이드 여부를 확인하라"고 주입해서 이루어집니다. 승낙하면 `claude-token-saver upgrade`가 설치 경로에 맞는 명령을 실행하고, 거절하면 `update-check --dismiss`가 그 버전을 더 묻지 않도록 기록합니다.

package/bin/cli.js

@@ -161,6 +161,13 @@ async function main() {
     return (await import('../src/commands/korean.js')).run({ args, hasFlag });
   }
 
+  // Subcommand: doc2md — convert pptx/xlsx/pdf/docx to Markdown before the
+  // model reads them, so an unreadable binary never enters the context window.
+  //   claude-token-saver doc2md on | off | <file> | --clean
+  if (args[0] === 'doc2md') {
+    return (await import('../src/commands/doc2md.js')).run({ args, hasFlag });
+  }
+
   // 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)
@@ -511,6 +518,27 @@ async function main() {
   } catch (e) {
     debug('savings-ledger:totals', e);
   }
+  // Delegated runs route-scan had to throw away because their model id could
+  // not be priced. Also a lookup of the cached scan, never a scan. Without it
+  // the statusline shows the same blank for "no delegation happened" and for
+  // "delegation happened and was silently discarded".
+  let unresolvedRuns = 0;
+  try {
+    const { readRouteScan } = await import('../src/route-scan.js');
+    unresolvedRuns = Number(readRouteScan()?.unresolvedRuns) || 0;
+  } catch (e) {
+    debug('route-scan:unresolved', e);
+  }
+  // 'auto' unless the user pinned a bucket. Read here rather than in the
+  // statusline branch below because the table and JSON formatters want the
+  // same answer.
+  let ttlBucket = 'auto';
+  try {
+    const { statuslineDefaults } = await import('../src/config.js');
+    ttlBucket = statuslineDefaults().ttlBucket;
+  } catch (e) {
+    debug('config:ttlBucket', e);
+  }
 
   const data = {
     summary: sum,
@@ -530,6 +558,8 @@ async function main() {
     model,
     delegationSaved,
     delegationTotals,
+    unresolvedRuns,
+    ttlBucket,
   };
 
   let output;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.25.1",
+  "version": "3.26.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/presets/doc2md/convert.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Convert one office/PDF document to Markdown and print a JSON result.
+
+Invoked as a child process by src/doc2md.cjs. Everything it needs to say
+travels in the JSON on stdout, so the Node side never has to interpret a
+traceback:
+
+    {"ok": true,  "markdown": "...", "note": null, "truncated": false, "rows": 0}
+    {"ok": false, "reason": "no-text", "detail": "..."}
+
+Exit status is 0 whenever the JSON was written, including for a refusal. A
+non-zero exit means the interpreter itself failed and the caller falls back to
+letting the original file be read as it always was.
+
+Two things here are defenses rather than features:
+
+* Zip bombs. pptx/xlsx/docx are zip containers, and a hostile attachment can
+  declare a small size and expand to fill the disk. The central directory is
+  checked first because it is cheap, and then every member is decompressed in
+  chunks against a hard ceiling, because the central directory is written by
+  whoever built the file and can simply lie.
+* Row count. Conversion time tracks spreadsheet rows, not bytes: a 6MB PDF
+  converts in about a second while a 6MB 200,000-row workbook takes about a
+  minute. Past the row cap the sheet is converted head-first by hand and the
+  truncation is stated in the result, because a silently shortened table is
+  worse than no table.
+"""
+
+import json
+import os
+import sys
+import zipfile
+
+MAX_UNCOMPRESSED = 500 * 1024 * 1024
+MAX_RATIO = 200
+ROW_CAP = int(os.environ.get("CTS_DOC2MD_ROW_CAP", "50000"))
+ZIP_EXTS = {".pptx", ".xlsx", ".docx"}
+
+
+def fail(reason, detail=""):
+    json.dump({"ok": False, "reason": reason, "detail": str(detail)[:500]}, sys.stdout)
+    sys.exit(0)
+
+
+def check_zip(path):
+    """Classify an archive before opening it as a document.
+
+    Returns None when it is safe to convert, or a (reason, detail) pair. The
+    reason distinguishes a hostile file from a merely broken one: those want
+    opposite handling, and calling a truncated download a zip bomb would send
+    the user hunting for an attacker who is not there.
+    """
+    try:
+        with zipfile.ZipFile(path) as zf:
+            infos = zf.infolist()
+            declared = sum(i.file_size for i in infos)
+            packed = sum(i.compress_size for i in infos) or 1
+            if declared > MAX_UNCOMPRESSED or declared / packed > MAX_RATIO:
+                return ("unsafe-archive",
+                        "declared size %d bytes at %.0fx compression" % (declared, declared / packed))
+            # The numbers above came from the archive itself, so verify them by
+            # actually decompressing, stopping the moment the running total
+            # passes the ceiling rather than once the disk is full. Understated
+            # sizes are caught here twice over: by this budget, and by the
+            # CRC-32 check zipfile performs while streaming, which fails as
+            # soon as a member's real contents disagree with its header.
+            budget = MAX_UNCOMPRESSED
+            for info in infos:
+                with zf.open(info) as member:
+                    while True:
+                        chunk = member.read(1 << 20)
+                        if not chunk:
+                            break
+                        budget -= len(chunk)
+                        if budget <= 0:
+                            return ("unsafe-archive", "expands past %d bytes" % MAX_UNCOMPRESSED)
+    except zipfile.BadZipFile as e:
+        return ("bad-archive", str(e))
+    return None
+
+
+def sheet_rows(path):
+    """Total rows across every sheet, or None when openpyxl cannot say."""
+    try:
+        import openpyxl
+    except ImportError:
+        return None
+    try:
+        wb = openpyxl.load_workbook(path, read_only=True)
+        try:
+            return sum(ws.max_row or 0 for ws in wb.worksheets)
+        finally:
+            wb.close()
+    except Exception:
+        return None
+
+
+def md_cell(v):
+    if v is None:
+        return ""
+    return str(v).replace("|", "\\|").replace("\n", " ")
+
+
+def head_of_workbook(path, cap):
+    """Markdown for the first `cap` rows, sheet by sheet.
+
+    Used only past the row cap. markitdown would produce nicer output, but it
+    reads the whole workbook first, which is the cost being avoided.
+    """
+    import openpyxl
+
+    wb = openpyxl.load_workbook(path, read_only=True)
+    out = []
+    left = cap
+    try:
+        for ws in wb.worksheets:
+            if left <= 0:
+                break
+            out.append("## %s" % ws.title)
+            header_written = False
+            for row in ws.iter_rows(values_only=True):
+                if left <= 0:
+                    break
+                cells = [md_cell(c) for c in row]
+                out.append("| " + " | ".join(cells) + " |")
+                if not header_written:
+                    out.append("| " + " | ".join(["---"] * len(cells)) + " |")
+                    header_written = True
+                left -= 1
+            out.append("")
+    finally:
+        wb.close()
+    return "\n".join(out)
+
+
+def main():
+    if len(sys.argv) < 2:
+        fail("usage", "convert.py <file>")
+    path = sys.argv[1]
+    if not os.path.isfile(path):
+        fail("missing", path)
+
+    ext = os.path.splitext(path)[1].lower()
+    if ext in ZIP_EXTS:
+        problem = check_zip(path)
+        if problem:
+            fail(problem[0], problem[1])
+
+    note = None
+    truncated = False
+    rows = 0
+
+    if ext in (".xlsx", ".xls"):
+        counted = sheet_rows(path)
+        rows = counted or 0
+        if counted and counted > ROW_CAP:
+            try:
+                text = head_of_workbook(path, ROW_CAP)
+            except Exception as e:
+                fail("convert-failed", e)
+            note = ("전체 %d행 가운데 앞 %d행만 변환했습니다. "
+                    "전수 분석이 필요하면 원본을 직접 다루십시오." % (counted, ROW_CAP))
+            json.dump({"ok": True, "markdown": text, "note": note,
+                       "truncated": True, "rows": counted}, sys.stdout)
+            return
+
+    try:
+        from markitdown import MarkItDown
+    except ImportError as e:
+        fail("no-markitdown", e)
+
+    try:
+        result = MarkItDown().convert(path)
+        text = (result.text_content or "").strip()
+    except Exception as e:
+        fail("convert-failed", e)
+
+    if not text:
+        # An empty file would read to the model as a document with nothing in
+        # it, which is a different and worse claim than "could not extract".
+        fail("no-text", "converter returned nothing")
+
+    json.dump({"ok": True, "markdown": text, "note": note,
+               "truncated": truncated, "rows": rows}, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/src/advice.js

@@ -180,6 +180,34 @@ export const ISSUE_MESSAGES = {
       },
     ],
   },
+  // Same symptom as BUCKET_5M_DOMINANT, different remedy. On Bedrock/Vertex
+  // the 5m bucket is the only bucket, so telling the user to upgrade a
+  // subscription plan sends them to buy something that changes nothing.
+  BUCKET_5M_DOMINANT_GATEWAY: {
+    title: 'This gateway offers only the 5-minute TTL bucket',
+    titleKo: '이 게이트웨이는 5분 TTL 버킷만 제공합니다',
+    explain:
+      'Bedrock/Vertex do not expose the 1h extended bucket, and they do not report the ' +
+      'per-bucket split either, so this is inferred from the model ids in the transcript. ' +
+      'No subscription plan changes it.',
+    explainKo:
+      'Bedrock과 Vertex는 1시간 확장 버킷을 제공하지 않으며, 버킷별 분해 값도 내려보내지 않습니다. ' +
+      '그래서 이 판정은 트랜스크립트에 남은 모델 ID로 추정한 것입니다. 구독 플랜을 바꾸어도 해소되지 않습니다.',
+    actions: () => [
+      {
+        label: 'What actually helps here',
+        labelKo: '이 환경에서 실제로 듣는 대응',
+        commands: [
+          'Send the next request within 5 minutes — that window is all you get',
+          '`/compact` before stepping away, so the rebuild after expiry costs less',
+        ],
+        commandsKo: [
+          '다음 요청을 5분 안에 보내십시오. 이 환경에서 주어지는 창은 그것이 전부입니다.',
+          '작업을 중단하기 전에 `/compact`를 실행해 만료 후의 재빌드 비용을 낮추십시오.',
+        ],
+      },
+    ],
+  },
   HIGH_OUTPUT_RATIO: {
     title: 'Output share is abnormally high',
     titleKo: '출력 비중이 비정상적으로 높음',
@@ -454,6 +482,10 @@ export const ISSUE_TIPS = {
     en: 'Send any prompt within 5min to keep cache warm; Max plan unlocks 1h TTL',
     ko: '5분 이내 한 번 더 보내 캐시 유지; Max 플랜은 1시간 TTL 제공',
   },
+  BUCKET_5M_DOMINANT_GATEWAY: {
+    en: 'Gateway (Bedrock/Vertex) is 5m-only — no plan changes that; send within 5min or `/compact` before idling',
+    ko: '게이트웨이(Bedrock·Vertex)는 5분 고정이라 플랜으로 해소되지 않음; 5분 안에 보내거나 작업 중단 전 `/compact`',
+  },
   HIGH_OUTPUT_RATIO: {
     en: 'Check `/effort` (`xhigh` inflates output); prefer Edit over full rewrites; model matching: Sonnet 80% / Opus 15% / Haiku 5%',
     ko: '`/effort` 확인 (`xhigh`는 출력 폭증); Edit 도구 우선 (전체 재작성 피하기); 모델 매칭: Sonnet 80% / Opus 15% / Haiku 5%',
@@ -488,7 +520,7 @@ export const CHIP_TO_CODES = {
   '⚠ 1M ON': ['LARGE_INPUT_PER_REQUEST'],
   '⚠ Cache miss': ['LOW_HIT_RATE'],
   '⚠ Input spike': ['LARGE_INPUT_PER_REQUEST'],
-  '⚠ 5m TTL': ['BUCKET_5M_DOMINANT'],
+  '⚠ 5m TTL': ['BUCKET_5M_DOMINANT', 'BUCKET_5M_DOMINANT_GATEWAY'],
   '⚠ Rebuild churn': ['FREQUENT_CACHE_REBUILD'],
   '⚠ Output heavy': ['HIGH_OUTPUT_RATIO'],
   '⚠ Call surge': ['HIGH_REQUEST_COUNT'],
@@ -520,7 +552,7 @@ export function chipForIssues(issues, contextWindow) {
   if (contextWindow?.size === '1M') return '⚠ Ctx 200k+';
   const codes = issues.map((i) => i.code);
   if (codes.includes('LARGE_INPUT_PER_REQUEST')) return '⚠ Input spike';
-  if (codes.includes('BUCKET_5M_DOMINANT')) return '⚠ 5m TTL';
+  if (codes.includes('BUCKET_5M_DOMINANT') || codes.includes('BUCKET_5M_DOMINANT_GATEWAY')) return '⚠ 5m TTL';
   if (codes.includes('LOW_HIT_RATE')) return '⚠ Cache miss';
   if (codes.includes('FREQUENT_CACHE_REBUILD')) return '⚠ Rebuild churn';
   if (codes.includes('HIGH_OUTPUT_RATIO')) return '⚠ Output heavy';

package/src/commands/doc2md.js

@@ -0,0 +1,100 @@
+/**
+ * Subcommand: doc2md — convert attached documents to Markdown before the
+ * model reads them.
+ *
+ *   claude-token-saver doc2md              # status
+ *   claude-token-saver doc2md on|off       # register / remove the Read hook
+ *   claude-token-saver doc2md <file>       # convert one file by hand
+ *   claude-token-saver doc2md --clean      # drop every cached conversion
+ *   claude-token-saver doc2md --hook       # PreToolUse entry point
+ */
+
+import { createRequire } from 'node:module';
+import { readdirSync, rmSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+export async function run({ args, hasFlag }) {
+  const doc2md = require('../doc2md.cjs');
+  const sub = args[1];
+
+  // Hook path first and cheap: this runs on every Read of a matching file, so
+  // nothing above it may cost a syscall.
+  if (hasFlag?.('--hook') || sub === '--hook') {
+    const { readStdinJson } = await import('../stdin-payload.js');
+    const payload = readStdinJson();
+    if (!payload) return;
+    let out = null;
+    try {
+      out = doc2md.formatHookOutput(doc2md.decideForRead(payload));
+    } catch {
+      // A converter that throws must not take the Read down with it. Printing
+      // nothing leaves Claude Code to run the tool call exactly as before.
+      return;
+    }
+    if (out) console.log(out);
+    return;
+  }
+
+  if (sub === 'on') {
+    const { installDoc2mdHook } = await import('../installer.js');
+    const res = installDoc2mdHook();
+    console.log(res.action === 'skipped'
+      ? `✗ ${res.reason}`
+      : `✓ Read hook ${res.action} (${res.path})`);
+    const python = doc2md.findInterpreter();
+    console.log(python
+      ? `  converter: markitdown via ${python}`
+      : `  converter: not installed yet — ${doc2md.INSTALL_HINT}`);
+    return;
+  }
+
+  if (sub === 'off') {
+    const { removeDoc2mdHook } = await import('../installer.js');
+    const res = removeDoc2mdHook();
+    console.log(res.action === 'skipped' ? `✗ ${res.reason}` : `✓ Read hook ${res.action}`);
+    return;
+  }
+
+  if (hasFlag?.('--clean') || sub === '--clean') {
+    const dir = doc2md.cacheDir();
+    let removed = 0;
+    if (existsSync(dir)) {
+      for (const name of readdirSync(dir)) {
+        rmSync(join(dir, name), { force: true });
+        removed += 1;
+      }
+    }
+    console.log(`✓ removed ${removed} cached file(s) from ${dir}`);
+    return;
+  }
+
+  // A path: convert it now and print where the result landed. This is the
+  // diagnostic path — it reports the refusal reason instead of swallowing it,
+  // which is how you find out that markitdown is missing rather than guessing.
+  if (sub && !sub.startsWith('-')) {
+    const result = doc2md.convert(sub);
+    if (result.ok) {
+      console.log(`✓ ${result.cached ? 'cached' : 'converted'}: ${result.cacheFile}`);
+      if (result.meta?.note) console.log(`  ${result.meta.note}`);
+      if (result.meta?.clipped) console.log('  결과가 상한을 넘어 뒷부분을 잘랐습니다.');
+      console.log(`  ${statSync(result.cacheFile).size} bytes`);
+      return;
+    }
+    console.error(`✗ ${result.reason}${result.detail ? `: ${result.detail}` : ''}`);
+    if (result.reason === 'no-markitdown') console.error(`  ${doc2md.INSTALL_HINT}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const python = doc2md.findInterpreter();
+  const dir = doc2md.cacheDir();
+  const cached = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')).length : 0;
+  console.log('doc2md — attached documents are converted to Markdown before the model reads them.');
+  console.log(`  formats:   ${doc2md.TARGET_EXTENSIONS.join(' ')}`);
+  console.log(`  converter: ${python ? `markitdown via ${python}` : `not installed — ${doc2md.INSTALL_HINT}`}`);
+  console.log(`  cache:     ${dir} (${cached} file(s))`);
+  console.log('');
+  console.log('Enable with: claude-token-saver doc2md on');
+}

package/src/commands/mode.js

@@ -20,6 +20,7 @@ export async function run({ args }) {
       console.log(`  timer:   ${eff.timer}`);
       console.log(`  color:   ${eff.color}`);
       console.log(`  window:  ${eff.windowLabel} (${eff.windowHours}h)`);
+      console.log(`  ttl:     ${eff.ttlBucket}${eff.ttlBucket === 'auto' ? ' (measured split, else gateway detection)' : ' (pinned)'}`);
       console.log('');
       console.log('Output language (advice / history / last):');
       console.log(`  language: ${userLanguage()}`);

package/src/commands/route-scan.js

@@ -100,6 +100,14 @@ export async function run({ args, hasFlag, numArg }) {
         return;
       }
       console.log(lang === 'ko' ? '📐 모델 피팅 룰 (로그 기반 자동 갱신):' : '📐 Model-fitting rules (auto-refreshed from logs):');
+      // A T1 rule delegates to sonnet, so in a session whose own model is
+      // already sonnet it can never save anything. That is correct behaviour,
+      // but listed as "measured delegations — (none yet)" it reads as a
+      // promise of savings that will never arrive.
+      const { aliasForRole } = await import('../model-alias.js');
+      const { modelRank } = await import('../cost.js');
+      const sessionModel = aliasForRole('main');
+      const sessionRank = sessionModel ? modelRank(sessionModel) : null;
       rules.forEach((r, i) => {
         const health = r.status === 'review'
           ? (lang === 'ko' ? '  ⚠ 에러율 초과 — 재검토 필요' : '  ⚠ error rate over threshold — needs review')
@@ -115,7 +123,13 @@ export async function run({ args, hasFlag, numArg }) {
           ? (lang === 'ko'
             ? `실제 위임 ${r.delegatedRuns}건 · 에러율 ${Math.round((r.delegatedErrRate || 0) * 100)}% · 절감 ~$${(r.savedUsd || 0).toFixed(2)}`
             : `measured ×${r.delegatedRuns} · err ${Math.round((r.delegatedErrRate || 0) * 100)}% · saved ~$${(r.savedUsd || 0).toFixed(2)}`)
-          : (lang === 'ko' ? '실제 위임 기록 — (아직 없음)' : 'measured delegations — (none yet)');
+          : (sessionRank !== null && !rs.worthDelegating(r.tier, sessionRank)
+            ? (lang === 'ko'
+              ? `이 규칙은 현재 기본 모델(${sessionModel}) 기준으로는 적용되지 않습니다. 세션 모델이 이미 위임 목표와 같은 급이어서 절감이 발생하지 않습니다.`
+              : `not in effect for the current default model (${sessionModel}) — the session already runs at the delegation target's tier`)
+            : (lang === 'ko'
+              ? '실제 위임 기록이 아직 없습니다.'
+              : 'measured delegations — (none yet)'));
         console.log(`      ${measured}`);
         // Same composer the md file uses, so what is listed here is exactly
         // what the model reads.

package/src/config.js

@@ -82,6 +82,7 @@ export const VALID_KEYWORDS = Object.keys(KEYWORDS)
     '<N>h (e.g. 1h, 6h, 24h)',
     '<N>d (e.g. 1d, 7d, 30d)',
     'lang=en | lang=ko',
+    'ttl=5m | ttl=1h | ttl=auto',
     'reset',
     'default',
   ]);
@@ -120,6 +121,15 @@ export function applyMode(words) {
       applied.push(`lang=${cfg.language}`);
       continue;
     }
+    // Checked before parseWindow, which would otherwise read the `5m`/`1h`
+    // part as an analysis window.
+    const ttlMatch = lower.match(/^ttl=(5m|1h|auto)$/);
+    if (ttlMatch) {
+      if (ttlMatch[1] === 'auto') delete cfg.statusline.ttlBucket;
+      else cfg.statusline.ttlBucket = ttlMatch[1];
+      applied.push(`ttl=${ttlMatch[1]}`);
+      continue;
+    }
     const hours = parseWindow(lower);
     if (hours !== null && hours > 0) {
       cfg.statusline.windowHours = hours;
@@ -168,6 +178,11 @@ export function statuslineDefaults() {
     color:       s.color   !== false,
     windowHours,
     windowLabel: formatWindow(windowHours),
+    // 'auto' | '5m' | '1h'. Auto lets the measured split decide and falls back
+    // to gateway detection. An explicit value exists because detection can be
+    // wrong in either direction, and a user who can read their own clock
+    // should not have to wait for a release to correct it.
+    ttlBucket: s.ttlBucket === '5m' || s.ttlBucket === '1h' ? s.ttlBucket : 'auto',
   };
 }
 

package/src/cost.js

@@ -234,6 +234,12 @@ export function estimateCost(totals, model) {
     savingsRate: noCacheCost > 0 ? (noCacheCost - actual) / noCacheCost : 0,
     scenario5mCost: round(scenario5mCost),
     extraCostIf5m: round(scenario5mCost - actual),
+    // The row asks a counterfactual: what would dropping to 5m-only cost you?
+    // With no 1h writes there is nothing to lose, and the arithmetically
+    // honest `+$0` it printed read as "5m-only is free" — the opposite of the
+    // truth for a gateway user already confined to 5m. The display layer has
+    // to change the question rather than the number.
+    extraCostIf5mApplicable: write1h > 0,
   };
 }
 

package/src/doc2md.cjs

@@ -0,0 +1,378 @@
+/**
+ * doc2md — hand the model a Markdown rendering of an attached document
+ * instead of the binary.
+ *
+ * A pptx or xlsx read straight into the context window is close to the worst
+ * thing a token-saving tool can allow: the bytes are unreadable to the model,
+ * so it either gets nothing useful or spends a fortune finding that out. This
+ * intercepts the Read, converts the file once, caches the result, and points
+ * the model at the .md.
+ *
+ * CommonJS on purpose. It runs from ~/.claude/ through the copied hook script,
+ * where there is no package.json to declare `"type": "module"`, which is the
+ * same reason korean-lint.cjs is written this way.
+ *
+ * Conversion is markitdown, a Python package. It cannot be an npm dependency,
+ * so a missing install is an ordinary state rather than an error: say so once,
+ * then get out of the way and let the Read proceed untouched. Failing loudly
+ * on every Read would be worse than the problem being solved, and failing
+ * silently is how graphify's `except ImportError: return ""` hid a broken
+ * converter for months.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+// Formats where the original is of no use to the model. Images are absent
+// deliberately: markitdown returns nothing for them, and OCR misread resource
+// names in testing (`c5.xlarge` as `c.xlarge`), which is worse than no text at
+// all in a document where those names are the content. The model reads images
+// natively anyway.
+const TARGET_EXTENSIONS = ['.pptx', '.xlsx', '.xls', '.pdf', '.docx'];
+
+// Big enough for real decks and reports, small enough that a hostile file
+// cannot make the converter the expensive part of the turn.
+const MAX_SOURCE_BYTES = 50 * 1024 * 1024;
+// A conversion larger than this costs more to read than it saves.
+const MAX_MARKDOWN_BYTES = 2 * 1024 * 1024;
+// Cold `import markitdown` measured at ~12s; conversions after that are under
+// two seconds except for very large workbooks, which the row cap handles.
+const CONVERT_TIMEOUT_MS = 120_000;
+
+// Names that suggest the file should not be left lying around as plain text.
+// Deliberately blunt: the cost of skipping a payroll deck is one extra manual
+// step, and the cost of caching it is not recoverable.
+const SENSITIVE_PATTERNS = [
+  /secret/i, /password/i, /credential/i, /salary/i, /payroll/i, /confidential/i,
+  /개인정보/, /급여/, /계약/, /대외비/,
+];
+
+// Mirrors src/paths.js userDataDir(). Duplicated rather than imported because
+// this file is CommonJS and paths.js is ESM; the precedence order has to match
+// it exactly, or conversions would land somewhere the rest of the tool does
+// not look.
+function userDataDir() {
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, 'claude-token-saver');
+  }
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'claude-token-saver');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'claude-token-saver');
+  }
+  return path.join(os.homedir(), '.config', 'claude-token-saver');
+}
+
+/**
+ * Where conversions live.
+ *
+ * Not next to the original, and not in the project's own `.claude/`: either
+ * one drops a plain-text copy of a possibly confidential attachment into a
+ * directory people commit. Keeping it in the tool's own state directory means
+ * there is nothing for the user to remember to gitignore.
+ */
+function cacheDir() {
+  return path.join(userDataDir(), 'doc2md-cache');
+}
+
+function ensureCacheDir() {
+  const dir = cacheDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // mkdir honours the mode only on creation, so an older directory made with
+  // the default mask is tightened here.
+  try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
+  return dir;
+}
+
+function isTargetPath(filePath) {
+  if (typeof filePath !== 'string' || !filePath) return false;
+  return TARGET_EXTENSIONS.includes(path.extname(filePath).toLowerCase());
+}
+
+function isSensitivePath(filePath) {
+  const base = path.basename(filePath || '');
+  return SENSITIVE_PATTERNS.some((re) => re.test(base));
+}
+
+/**
+ * Cache path for a source file. The hash covers the absolute path, so two
+ * `report.pptx` files in different projects do not overwrite each other.
+ */
+function cachePathFor(filePath) {
+  const abs = path.resolve(filePath);
+  const hash = crypto.createHash('sha256').update(abs).digest('hex').slice(0, 12);
+  const base = path.basename(abs).replace(/[^\w.\-]/g, '_');
+  return path.join(cacheDir(), `${base}.${hash}.md`);
+}
+
+function metaPathFor(cacheFile) {
+  return cacheFile.replace(/\.md$/, '.meta.json');
+}
+
+/** A cached conversion still matching the source's mtime and size, or null. */
+function readCache(filePath) {
+  const cacheFile = cachePathFor(filePath);
+  try {
+    const src = fs.statSync(filePath);
+    const meta = JSON.parse(fs.readFileSync(metaPathFor(cacheFile), 'utf8'));
+    if (meta.size !== src.size || meta.mtimeMs !== src.mtimeMs) return null;
+    fs.statSync(cacheFile);
+    return { cacheFile, meta };
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(filePath, markdown, extra) {
+  ensureCacheDir();
+  const cacheFile = cachePathFor(filePath);
+  const src = fs.statSync(filePath);
+  fs.writeFileSync(cacheFile, markdown, { encoding: 'utf8', mode: 0o600 });
+  const meta = Object.assign({
+    source: path.resolve(filePath),
+    size: src.size,
+    mtimeMs: src.mtimeMs,
+    convertedAt: new Date().toISOString(),
+  }, extra || {});
+  fs.writeFileSync(metaPathFor(cacheFile), JSON.stringify(meta, null, 2), { encoding: 'utf8', mode: 0o600 });
+  return { cacheFile, meta };
+}
+
+/**
+ * A Python that can import markitdown, or null.
+ *
+ * Order matters: an explicit override first, then a `uv tool` install, then
+ * whatever is on PATH. Probing costs a process spawn each, so the answer is
+ * memoized for the life of this process, and the caller memoizes across
+ * processes through the notice file.
+ */
+let interpreterCache;
+function findInterpreter() {
+  if (interpreterCache !== undefined) return interpreterCache;
+  const candidates = [];
+  if (process.env.CTS_DOC2MD_PYTHON) candidates.push(process.env.CTS_DOC2MD_PYTHON);
+  candidates.push(
+    path.join(os.homedir(), '.local', 'share', 'uv', 'tools', 'markitdown', 'bin', 'python'),
+    path.join(os.homedir(), '.local', 'bin', 'markitdown-python'),
+    'python3',
+    'python',
+  );
+  for (const bin of candidates) {
+    try {
+      const probe = spawnSync(bin, ['-c', 'import markitdown'], { timeout: 20_000, stdio: 'ignore' });
+      if (probe.status === 0) {
+        interpreterCache = bin;
+        return bin;
+      }
+    } catch { /* candidate unusable, try the next */ }
+  }
+  interpreterCache = null;
+  return null;
+}
+
+const CONVERTER = path.join(__dirname, '..', 'presets', 'doc2md', 'convert.py');
+
+/**
+ * Convert one file. Returns `{ ok: true, cacheFile, meta }`, or
+ * `{ ok: false, reason, detail }` where reason is one of:
+ *   no-markitdown | too-large | sensitive | unsafe-archive | no-text |
+ *   convert-failed | timeout
+ *
+ * Every failure is a reason to leave the original Read alone, never to break
+ * it. That is the whole contract with the hook.
+ */
+function convert(filePath, { converter = CONVERTER, python: pythonOverride = null } = {}) {
+  if (!isTargetPath(filePath)) return { ok: false, reason: 'not-target' };
+  if (isSensitivePath(filePath)) return { ok: false, reason: 'sensitive' };
+
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch (e) {
+    return { ok: false, reason: 'missing', detail: String(e.message || e) };
+  }
+  if (stat.size > MAX_SOURCE_BYTES) {
+    return { ok: false, reason: 'too-large', detail: `${stat.size} bytes` };
+  }
+
+  const cached = readCache(filePath);
+  if (cached) return { ok: true, cached: true, cacheFile: cached.cacheFile, meta: cached.meta };
+
+  // The override exists so tests can drive a stub converter with any Python at
+  // all: the normal search insists the interpreter can import markitdown,
+  // which would make the whole path untestable without the real package.
+  const python = pythonOverride || findInterpreter();
+  if (!python) return { ok: false, reason: 'no-markitdown' };
+
+  const run = spawnSync(python, [converter, filePath], {
+    encoding: 'utf8',
+    timeout: CONVERT_TIMEOUT_MS,
+    maxBuffer: MAX_MARKDOWN_BYTES * 4,
+  });
+  if (run.error && run.error.code === 'ETIMEDOUT') return { ok: false, reason: 'timeout' };
+  if (run.status !== 0) {
+    return { ok: false, reason: 'convert-failed', detail: (run.stderr || '').slice(0, 300) };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(run.stdout);
+  } catch {
+    return { ok: false, reason: 'convert-failed', detail: 'converter produced no JSON' };
+  }
+  if (!payload.ok) return { ok: false, reason: payload.reason, detail: payload.detail };
+
+  let markdown = payload.markdown || '';
+  let clipped = false;
+  if (Buffer.byteLength(markdown, 'utf8') > MAX_MARKDOWN_BYTES) {
+    // Reading a 20MB markdown file is the same waste in a different format.
+    markdown = markdown.slice(0, MAX_MARKDOWN_BYTES);
+    clipped = true;
+  }
+
+  const written = writeCache(filePath, markdown, {
+    note: payload.note || null,
+    truncated: !!payload.truncated || clipped,
+    rows: payload.rows || 0,
+    clipped,
+  });
+  return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
+}
+
+/** Where the "markitdown is not installed" notice records that it was shown. */
+function noticePath() {
+  return path.join(userDataDir(), 'doc2md-notice.json');
+}
+
+function noticeAlreadyShown() {
+  try {
+    return JSON.parse(fs.readFileSync(noticePath(), 'utf8')).shown === true;
+  } catch {
+    return false;
+  }
+}
+
+function markNoticeShown() {
+  try {
+    fs.mkdirSync(userDataDir(), { recursive: true });
+    fs.writeFileSync(noticePath(), JSON.stringify({ shown: true, at: new Date().toISOString() }));
+  } catch { /* an unwritable state dir just means the notice repeats */ }
+}
+
+const INSTALL_HINT = 'pip install "markitdown[pptx,pdf,xlsx,docx]"';
+
+/**
+ * Decide what to tell Claude Code about one PreToolUse(Read) payload.
+ *
+ * Returns null when the hook should stay out of the way, or a PreToolUse hook
+ * output object. Blocking is the right call for a successful conversion:
+ * allowing the Read and merely mentioning the .md would put the binary in the
+ * context window anyway, which is the cost this exists to avoid.
+ */
+function decideForRead(context, opts = {}) {
+  if (!context || context.tool_name !== 'Read') return null;
+  const toolInput = context.tool_input;
+  const filePath = toolInput && typeof toolInput.file_path === 'string' ? toolInput.file_path : '';
+  if (!isTargetPath(filePath)) return null;
+
+  const result = convert(filePath, opts);
+  const name = path.basename(filePath);
+
+  if (result.ok) {
+    const bits = [`[doc2md] ${name} 는 Markdown 으로 변환했습니다.`];
+    bits.push(`  변환본: ${result.cacheFile}`);
+    if (result.meta && result.meta.note) bits.push(`  ${result.meta.note}`);
+    if (result.meta && result.meta.clipped) {
+      bits.push('  변환 결과가 너무 커서 뒷부분을 잘랐습니다. 전체가 필요하면 원본을 직접 다루십시오.');
+    }
+    bits.push('  원본 대신 이 파일을 Read 하십시오. 원본을 직접 확인해야 한다면 그 이유를 밝히십시오.');
+    return { deny: true, reason: bits.join('\n') };
+  }
+
+  // From here down the Read is allowed through untouched. The only question is
+  // whether the model is told why nothing was converted.
+  if (result.reason === 'no-markitdown') {
+    if (noticeAlreadyShown()) return null;
+    markNoticeShown();
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 를 변환하려 했으나 markitdown 이 설치되어 있지 않습니다.\n`
+        + `  설치: ${INSTALL_HINT}\n`
+        + '  설치 전까지는 원본을 그대로 읽습니다. 이 안내는 한 번만 표시됩니다.',
+    };
+  }
+  if (result.reason === 'no-text') {
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 에서 본문 텍스트를 추출하지 못했습니다(스캔 PDF 로 보입니다). 원본을 직접 확인하십시오.`,
+    };
+  }
+  // The one case that blocks without converting. A file that expands to fill
+  // the disk is not something to hand on to the next reader with a shrug.
+  if (result.reason === 'unsafe-archive') {
+    return {
+      deny: true,
+      reason: `[doc2md] ${name} 는 압축 폭탄으로 보여 변환하지 않았습니다 (${result.detail}). 신뢰할 수 있는 파일인지 먼저 확인하십시오.`,
+    };
+  }
+  if (result.reason === 'bad-archive') {
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 는 압축 파일로 열리지 않습니다 (${result.detail}). 내려받다 끊겼을 수 있습니다.`,
+    };
+  }
+  if (result.reason === 'too-large') {
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 는 크기 상한(50MB)을 넘어 변환하지 않았습니다 (${result.detail}).`,
+    };
+  }
+  if (result.reason === 'sensitive') {
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 는 파일명이 민감 문서 패턴에 걸려 변환하지 않았습니다. 평문 사본을 남기지 않기 위한 조치입니다.`,
+    };
+  }
+  if (result.reason === 'timeout' || result.reason === 'convert-failed') {
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 변환에 실패했습니다(${result.reason}). 원본을 그대로 읽습니다.`,
+    };
+  }
+  return null;
+}
+
+/** The decision rendered as the JSON Claude Code expects on stdout. */
+function formatHookOutput(decision) {
+  if (!decision) return null;
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision.deny ? 'deny' : 'allow',
+      permissionDecisionReason: decision.reason,
+    },
+  });
+}
+
+module.exports = {
+  TARGET_EXTENSIONS,
+  MAX_SOURCE_BYTES,
+  INSTALL_HINT,
+  cacheDir,
+  cachePathFor,
+  metaPathFor,
+  isTargetPath,
+  isSensitivePath,
+  findInterpreter,
+  readCache,
+  writeCache,
+  convert,
+  decideForRead,
+  formatHookOutput,
+};

package/src/formatters/statusline.js

@@ -280,10 +280,27 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // infer the bucket. Default to 1h-sized countdown rather than 5m so Max
   // users on idle don't see a misleading "Cache expires 5:00". The bucket
   // label is shown as "?" so the uncertainty is visible.
+  //
+  // That default is exactly backwards behind a gateway. Bedrock and Vertex
+  // never report the per-bucket split, so ttl.total stays 0 there forever, and
+  // they offer only the 5m bucket: the countdown opened at 59:59 for a window
+  // that was really 5:00, overstating it twelvefold. So the fallback now
+  // follows the evidence — gateway seen, assume 5m; otherwise keep 1h. An
+  // explicit `ttlBucket` setting outranks both, so a gateway that starts
+  // reporting the split correctly does not need a release to be believed.
   const hasTtlData = ttl.total > 0;
-  const is1h = hasTtlData ? ttl.pct1h >= 0.5 : true;
-  const bucketLabel = hasTtlData ? (is1h ? '1h' : '5m') : '?';
-  const bucketColor = hasTtlData ? (is1h ? GREEN : YELLOW) : GRAY;
+  const override = data.ttlBucket === '5m' || data.ttlBucket === '1h' ? data.ttlBucket : null;
+  const is1h = override ? override === '1h' : (hasTtlData ? ttl.pct1h >= 0.5 : !ttl.gatewayObserved);
+  // Three grades of certainty, three labels: measured (`1h`/`5m`), inferred
+  // from a gateway model id (`5m?`), and unknown (`?`). Folding the middle
+  // case into `?` would hide a judgement the user could otherwise check.
+  const bucketKnown = hasTtlData || !!override;
+  const bucketLabel = bucketKnown
+    ? (is1h ? '1h' : '5m')
+    : (ttl.gatewayObserved ? '5m?' : '?');
+  const bucketColor = bucketKnown
+    ? (is1h ? GREEN : YELLOW)
+    : (ttl.gatewayObserved ? YELLOW : GRAY);
   const ttlSeconds = is1h ? 3600 : 300;
 
   const savings = cost?.savings ?? 0;
@@ -320,9 +337,18 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   const delegateLabel = isIcon
     ? (verbose ? '🔀 Routing saved' : '🔀')
     : 'Routing saved';
+  // Zero savings has two very different causes and, until now, one appearance:
+  // nothing at all. "Never delegated" and "delegated plenty, but every run was
+  // dropped because the gateway model id could not be resolved" looked
+  // identical, so users in the second case had no reason to suspect anything
+  // was wrong. The count gets a chip; the explanation stays in `route-scan
+  // rules`, where there is room for it.
+  const unresolvedRuns = Number(data.unresolvedRuns) || 0;
   const delegateSeg = delegationSaved > 0
     ? `${c(GREEN)}${delegateLabel}${c(RESET)} ${formatMoney(delegationSaved)}`
-    : null;
+    : (unresolvedRuns > 0
+      ? `${c(YELLOW)}🔀 ${unresolvedRuns} unresolved${c(RESET)}`
+      : null);
 
   // Routing-savings headline line (multi-line layout). The lifetime sum from
   // the delegation ledger — the number the whole tool exists to grow, so it
@@ -397,11 +423,15 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     const remaining = Math.min(ttlSeconds, ttlSeconds - elapsed);
     const text = formatTimer(remaining);
     const pct = remaining / ttlSeconds;
+    // Percentages are the wrong unit in a 5-minute bucket: 30% of it is 90
+    // seconds, and green there reads as comfort the user does not have. Below
+    // an hour the thresholds are absolute, so the color tracks whether there
+    // is time to finish a thought rather than a share of a short window.
     const timerColor =
       remaining <= 0 ? RED :
-      pct > 0.30 ? GREEN :
-      pct > 0.10 ? YELLOW :
-      RED;
+      is1h
+        ? (pct > 0.30 ? GREEN : pct > 0.10 ? YELLOW : RED)
+        : (remaining > 60 ? GREEN : remaining > 30 ? YELLOW : RED);
 
     if (isIcon && verbose) {
       // Drop bucket here too — `⏳ Expires 1h 57:20` reads as "1h 57m 20s left"

package/src/formatters/table.js

@@ -241,7 +241,14 @@ export function formatReport({ summary: sum, trend, ttl, anomalies, cost, option
   lines.push('  ' + tableRow(['Without cache', `$${cost.noCacheCost}`], costW, costA));
   lines.push('  ' + tableSep(costW));
   lines.push('  ' + tableRow(['Savings', `$${cost.savings} (${pct(cost.savingsRate)})`], costW, costA));
-  lines.push('  ' + tableRow(['Extra cost if 5m-only', `+$${cost.extraCostIf5m}`], costW, costA));
+  // Only worth asking of someone who has 1h writes to lose. Everyone else got
+  // a `+$0` that read as an endorsement of the 5m bucket they were already
+  // stuck in.
+  if (cost.extraCostIf5mApplicable === false) {
+    lines.push('  ' + tableRow(['Already 5m-only', ttl.gatewayObserved ? 'gateway' : 'yes'], costW, costA));
+  } else {
+    lines.push('  ' + tableRow(['Extra cost if 5m-only', `+$${cost.extraCostIf5m}`], costW, costA));
+  }
   lines.push('  ' + tableBot(costW));
   lines.push('');
 

package/src/installer.js

@@ -346,6 +346,75 @@ export function removeKoreanLintHook() {
   return { path: file, action: 'removed' };
 }
 
+// Registers the PreToolUse hook that converts attached documents to Markdown
+// before the model reads them. PreToolUse rather than PostToolUse because the
+// point is to intervene before a pptx lands in the context window; afterwards
+// the tokens are already spent.
+//
+// No `timeout` is set, on purpose. Claude Code defaults command hooks to ten
+// minutes, so naming a number here could only lower that ceiling, and a cold
+// `import markitdown` measured at twelve seconds by itself, with a very large
+// workbook adding a minute on top. The row cap inside the converter is what
+// actually bounds the work; the timeout is only a backstop.
+// Installed by `doc2md on`, removed by `doc2md off`. Idempotent.
+const DOC2MD_HOOK_COMMAND = 'claude-token-saver doc2md --hook';
+
+export function installDoc2mdHook() {
+  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 || {};
+  if (settings.hooks.PreToolUse !== undefined && !Array.isArray(settings.hooks.PreToolUse)) {
+    return { path: file, action: 'skipped', reason: 'hooks.PreToolUse is not an array — fix settings.json manually' };
+  }
+  const list = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
+  const already = list.some((m) =>
+    Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('doc2md --hook')),
+  );
+  if (already) return { path: file, action: 'exists' };
+
+  list.push({
+    matcher: 'Read',
+    hooks: [{ type: 'command', command: DOC2MD_HOOK_COMMAND }],
+  });
+  settings.hooks.PreToolUse = list;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: 'created' };
+}
+
+export function removeDoc2mdHook() {
+  const file = join(claudeUserDir(), 'settings.json');
+  if (!existsSync(file)) return { path: file, action: 'absent' };
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { path: file, action: 'skipped', reason: `unreadable JSON (${e.message})` };
+  }
+  const list = settings?.hooks?.PreToolUse;
+  if (!Array.isArray(list)) return { path: file, action: 'absent' };
+  // Only this tool's own entry goes; anything else registered under
+  // PreToolUse stays exactly where the user put it.
+  const kept = list.filter((m) =>
+    !(Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('doc2md --hook'))),
+  );
+  if (kept.length === list.length) return { path: file, action: 'absent' };
+  if (kept.length === 0) delete settings.hooks.PreToolUse;
+  else settings.hooks.PreToolUse = kept;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: 'removed' };
+}
+
 export function installAll({ force = false } = {}) {
   return {
     skill: installSkill({ force }),

package/src/korean-style.js

@@ -35,7 +35,10 @@ const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 
 export const KOREAN_STYLE_PATH = join(packageRoot, 'presets', 'korean-style', 'fluent-korean.md');
 export const KOREAN_STYLE_LICENSE_PATH = join(packageRoot, 'presets', 'korean-style', 'LICENSE-fluent-korean');
-export const KOREAN_STYLE_SOURCE = 'fluent-korean by snflkd (MIT) — https://github.com/snflkd/fluent-korean';
+// The separator here is a colon, not an em dash. The guidance this line cites
+// bans em dashes in Korean prose, and shipping one inside its own attribution
+// is the kind of contradiction that teaches the model the rule is negotiable.
+export const KOREAN_STYLE_SOURCE = 'fluent-korean by snflkd (MIT): https://github.com/snflkd/fluent-korean';
 
 /** Whether session-start injection is enabled. Off unless the user asked. */
 export function koreanStyleEnabled(cfg = loadConfig()) {
@@ -134,6 +137,13 @@ export function koreanScopeLines(cfg = loadConfig()) {
   return [
     '적용 대상: 대화 답변, 그리고 세션이 쓰거나 고치는 모든 파일의 한국어를 포함합니다. 문서와 보고서는 물론이고 코드 주석, 화면에 나가는 문자열, 자막과 템플릿, 스크립트가 읽어 산출물을 만드는 데이터 파일까지 모두 해당합니다.',
     '적용 예외: 원문을 그대로 옮기는 인용과, 프로젝트의 기존 표기 관례를 따라야 하는 커밋 메시지와 로그 문자열입니다.',
+    // The vendored text says the opposite of the line above, and it says so
+    // twice. Left unaddressed the model has no way to decide which sentence
+    // governs a code comment, and in September 2026 that ambiguity shipped em
+    // dashes into comments and log strings while the guidance was active. The
+    // vendored wording stays untouched, so the conflict is resolved by naming
+    // which side wins rather than by editing the source.
+    '아래에 이어지는 fluent-korean 본문은 "인용, 코드, 코드 주석에는 이 지침들을 적용하지 않습니다"라고 적고 있으며 동작 범위 2번 조항에서 한 번 더 강조합니다. 그러나 이 세션에서는 바로 위의 적용 대상과 적용 예외가 그 문장보다 우선합니다. 즉 코드 주석에도 지침을 적용하십시오.',
     '쓰기 시점에 기계 검사가 함께 돌아갑니다. 위반을 알리면 그 파일을 고친 뒤에 다음 작업으로 넘어가십시오.',
   ];
 }

package/src/model-alias.js

@@ -69,8 +69,14 @@ const ROLES = ['main', 'opus', 'sonnet', 'haiku', 'fable'];
 
 /**
  * Alias for a role, taken from the environment Claude Code itself uses to
- * pick subagent models. Returns null when the variable is absent or is itself
- * an ARN (resolving an ARN to another ARN would loop).
+ * pick subagent models. Returns null when the variable is absent, or when it
+ * is an opaque ARN that names no model (resolving one of those to another ARN
+ * would loop).
+ *
+ * A `foundation-model` ARN is not opaque: it spells the model out in its
+ * resource part, so it is unwrapped rather than rejected. Users who point
+ * these variables straight at an ARN — a normal way to configure a private
+ * gateway — used to get no delegation stats at all, and no hint as to why.
  */
 export function aliasForRole(role, env = process.env) {
   const candidates = {
@@ -81,7 +87,13 @@ export function aliasForRole(role, env = process.env) {
     fable: [env.ANTHROPIC_DEFAULT_FABLE_MODEL],
   }[role] || [];
   for (const v of candidates) {
-    if (typeof v === 'string' && v && !isGatewayModelId(v)) return v;
+    if (typeof v !== 'string' || !v) continue;
+    if (!isGatewayModelId(v)) return v;
+    // `arn:…:foundation-model/anthropic.claude-haiku-4-5-…` → the model id.
+    // An `application-inference-profile` id is a random string and stays
+    // rejected: guessing at it is how wrong prices get into the ledger.
+    const inner = profileIdFrom(v);
+    if (inner && /claude/i.test(inner)) return inner;
   }
   return null;
 }

package/src/parser.js

@@ -4,10 +4,23 @@ import { createInterface } from 'node:readline';
 import { join, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { loadCache, getCached, putCached, saveCache } from './session-cache.js';
-import { resolveModelAlias } from './model-alias.js';
+import { resolveModelAlias, isGatewayModelId } from './model-alias.js';
 
 const CLAUDE_DIR = join(homedir(), '.claude', 'projects');
 
+/**
+ * Keys LiteLLM adds when it rewrites a Bedrock response into Anthropic shape.
+ * A stock Anthropic `usage` object carries none of them, so their presence is
+ * evidence of a gateway even when the model id looks ordinary. It is weak
+ * evidence — another gateway may not add them — so it is only consulted after
+ * the model id has already failed to answer the question.
+ */
+const GATEWAY_USAGE_KEYS = ['inference_geo', 'iterations', 'speed'];
+
+function usageLooksGatewayShaped(usage) {
+  return GATEWAY_USAGE_KEYS.some((k) => Object.prototype.hasOwnProperty.call(usage, k));
+}
+
 /**
  * Parse a single session JSONL file.
  * Deduplicates by requestId (last-write-wins for streaming chunks).
@@ -17,6 +30,7 @@ export async function parseSessionFile(filePath) {
   let sessionId = null;
   let firstTimestamp = null;
   let lastTimestamp = null;
+  let gatewayObserved = false;
 
   const rl = createInterface({
     input: createReadStream(filePath, { encoding: 'utf8' }),
@@ -48,6 +62,14 @@ export async function parseSessionFile(filePath) {
     const cc = usage.cache_creation || {};
     const reqId = entry.requestId || msg.id;
 
+    // Recorded from the RAW id, before resolveModelAlias() turns the ARN into
+    // a plain model name. Downstream this is the only thing that distinguishes
+    // "no cache writes yet" from "a gateway that never reports the TTL split",
+    // and those two states want opposite countdown defaults.
+    if (!gatewayObserved && (isGatewayModelId(msg.model) || usageLooksGatewayShaped(usage))) {
+      gatewayObserved = true;
+    }
+
     requests.set(reqId, {
       requestId: reqId,
       model: resolveModelAlias(msg.model),
@@ -87,6 +109,7 @@ export async function parseSessionFile(filePath) {
     totals,
     maxContextPerRequest,
     model: reqs[0]?.model || 'unknown',
+    gatewayObserved,
   };
 }
 

package/src/session-cache.js

@@ -26,7 +26,10 @@ import { debug } from './debug.js';
 const CACHE_PATH = join(userDataDir(), 'session-cache.json');
 // Bump when the cached summary's shape changes — old entries are dropped
 // wholesale rather than migrated.
-const CACHE_VERSION = 1;
+// 2: sessions carry `gatewayObserved`. Entries written by version 1 lack it,
+// and a missing flag reads as "not a gateway" — the wrong default for exactly
+// the users the flag exists for.
+const CACHE_VERSION = 2;
 // Entries for transcripts this old are pruned on write. Keeps the file
 // bounded without an existence check per entry (which would cost the syscalls
 // the cache exists to avoid).

package/src/stats.js

@@ -59,10 +59,12 @@ export function dailyTrend(sessions) {
 export function ttlBreakdown(sessions) {
   let total5m = 0;
   let total1h = 0;
+  let gatewayObserved = false;
 
   for (const s of sessions) {
     total5m += s.totals.ephemeral5m;
     total1h += s.totals.ephemeral1h;
+    if (s.gatewayObserved) gatewayObserved = true;
   }
 
   const total = total5m + total1h;
@@ -72,6 +74,12 @@ export function ttlBreakdown(sessions) {
     total,
     pct5m: total > 0 ? total5m / total : 0,
     pct1h: total > 0 ? total1h / total : 0,
+    // Bedrock and Vertex fill only the `cache_creation_input_tokens` sum and
+    // leave the per-bucket split at zero, so `total === 0` there means "cannot
+    // tell" rather than "no cache writes happened". Carrying the observation
+    // alongside the numbers lets the display layer tell those two apart
+    // without going back to the environment.
+    gatewayObserved,
   };
 }
 
@@ -135,6 +143,7 @@ export function sessionMetrics(session) {
     outputRatio,
     writeToReadRatio,
     maxContextPerRequest: session.maxContextPerRequest || 0,
+    gatewayObserved: !!session.gatewayObserved,
     totals: t,
   };
 }
@@ -217,11 +226,23 @@ export function diagnoseSession(metrics, baseline) {
     });
   }
 
-  if (metrics.pct5m > 0.7 && (metrics.totals.ephemeral5m + metrics.totals.ephemeral1h) > 0) {
+  // The split is only knowable when the provider reports it. Requiring that
+  // sum outright meant gateway users — who are on a 5m-only backend and so
+  // need this warning most — never saw it at all.
+  const ttlSplitKnown = (metrics.totals.ephemeral5m + metrics.totals.ephemeral1h) > 0;
+  if (ttlSplitKnown && metrics.pct5m > 0.7) {
     issues.push({
       code: 'BUCKET_5M_DOMINANT',
       pct5m: metrics.pct5m,
     });
+  } else if (!ttlSplitKnown && metrics.gatewayObserved && metrics.totals.cacheCreation > 0) {
+    // Bedrock and Vertex offer no 1h bucket, so every write is a 5m write.
+    // The advice differs from the subscription case: no plan change fixes it.
+    issues.push({
+      code: 'BUCKET_5M_DOMINANT_GATEWAY',
+      pct5m: 1.0,
+      inferred: true,
+    });
   }
 
   if (metrics.outputRatio > 0.15) {