claude-token-saver 3.23.3 → 3.25.0

package/README.en.md

@@ -130,6 +130,8 @@ With an empty ledger (no measured delegation yet) row 1 is not drawn and the lay
 | `✦ current` / `📅 weekly` | 5-hour / 7-day rate-limit window usage + reset time |
 | `📦` | 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 — a **different** number from row 1's `🔀` (model routing) |
+| `v3.24.0` | The version you are running. Gray, at the tail, when it is the latest one |
+| `⬆ v3.24.0 → 3.25.0` | A newer release exists. Actionable, so it moves to the front of the line ([Update notifications](#-update-notifications)) |
 
 When something is wrong, a **warning chip leads the line**:
 
@@ -158,7 +160,12 @@ Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is
 | `claude-token-saver route-scan` | Detect recurring easy work on expensive models → propose haiku-delegation ratchet rules (below) |
 | `claude-token-saver route-scan savings` | The routing-savings ledger — per-model-change rollup + per-run log (the evidence behind the figure) |
 | `claude-token-saver compact-window` | Warn when a 1M-context session has no auto-compact cap → pin 400k with `set` (below) |
-| `claude-token-saver korean on\|off\|status` | Inject Korean writing guidance at session start (below) |
+| `claude-token-saver korean on\|off\|status` | Inject Korean writing guidance at session start and install the write-time check (below) |
+| `claude-token-saver korean lint block\|warn\|off` | How the write-time check handles findings |
+| `claude-token-saver korean lint scope all\|prose` | Check every text file, or documents only |
+| `claude-token-saver --version` | Print the installed version |
+| `claude-token-saver update-check` | Is a newer version out? (`--refresh` to ask now, `--dismiss` to mute this version's offer) |
+| `claude-token-saver upgrade` | Install the latest release with the package manager that installed this copy (`--print` shows the command only) |
 | `claude-token-saver install` | Manually register Skill + statusline |
 
 Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
@@ -182,6 +189,16 @@ Switch output language with `mode ko` / `mode en` (English default; statusline c
 | `--install-hook` / `--uninstall-hook` | Manage the PostToolUse hook | – |
 </details>
 
+## ⬆ Update notifications
+
+A statusline cannot open a dialog, and it re-renders every ~300ms, so it can never touch the network while drawing. The notification is therefore split in two:
+
+- **The statusline tells you.** Up to date: a quiet gray `v3.24.0` at the tail. Newer release out: `⬆ v3.24.0 → 3.25.0` in yellow, moved to the front. Never red — nothing is broken.
+- **Session start asks you.** On a new session or `/clear`, the SessionStart hook injects one line telling the model a newer version exists and to ask before installing anything. Only after you agree does it run `claude-token-saver upgrade`.
+- **Declining sticks.** `claude-token-saver update-check --dismiss` mutes the offer for that version; the next release asks again. The statusline chip stays — you declined the question, not the fact.
+
+The registry lookup runs at most once every 24h in a detached background process and only ever writes a cache file (`update-check.json`) — the same shape npm's `update-notifier` uses. A failed check still stamps its timestamp, so an offline machine backs off instead of retrying on every render. Turn checks off entirely with `CTS_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER`.
+
 ## 🅷 Harness mode
 
 Bootstrap five engineering principles (Ratchet · Evidence · PEV · Structured Task · Default Safe Path) into `CLAUDE.md` with one command; the statusline scores it as `🅷 5/5`. When the same error keeps recurring, a `🅷⚠ ratchet?` nudge appears so you can promote it to a rule.
@@ -313,6 +330,29 @@ Three things change. Clauses chained with em dashes become separate sentences, s
 
 The technical content is identical in both. The guidance touches sentence construction only, not judgement or accuracy: the answer does not change, it just stops needing a second read. In a channel people scroll through, that difference cuts follow-up questions — and the tokens those follow-ups would have cost.
 
+### The write-time check (v3.24.0)
+
+Injecting the guidance once at session start turned out to be half the job. The model reads it, then writes dozens of files over the next hours with nothing re-reading the output. Sessions with the guidance active still shipped violations into documents, and it surfaced only when a human read the finished artifact. An August 2026 fix reworded the scope sentence to address this; it recurred, because rewording an instruction does not add a checkpoint.
+
+From v3.24.0 `korean on` also installs a PostToolUse hook. It opens the file the model just wrote, runs the clauses a machine can decide, and hands any findings back. The file is already saved, so nothing is lost — the model fixes it on the spot.
+
+```bash
+claude-token-saver korean lint block   # default: findings are handed back as blocking feedback
+claude-token-saver korean lint warn    # print findings, do not block
+claude-token-saver korean lint off     # disable the check
+
+claude-token-saver korean lint scope all     # default: every text file the session writes
+claude-token-saver korean lint scope prose   # documents only
+
+claude-token-saver korean lint docs/*.md     # check files already on disk
+```
+
+Checked: 15 figurative phrases, translationese markers, separators (`—`·`ㅡ`·`|`), three or more `의` particles in one phrase, and a period after a nominal ending. Clauses that need judgement stay with the guidance text.
+
+The default `all` scope covers code comments, UI strings, subtitles, templates, and build output, not just documents. The vendored guidance exempts comments, but comments are read by people and generated artifacts (PDF, HTML) are assembled from those strings, so exempting them reopens the exact gap that was reported. Only installed dependencies, VCS internals, lockfiles, and binary or image files are skipped; `dist/` and `build/` are checked. `korean lint scope prose` restores the narrow reading.
+
+The scope sentence in the injected guidance is generated from the same setting, so the model is never told one rule while being corrected against another.
+
 ### The encoding rule that ships with it (v3.23.2)
 
 Alongside the writing guidance, one more line is injected: **non-ASCII strings in tool-call parameters must be written as literal UTF-8, never as `\uXXXX` unicode escapes.**
@@ -414,6 +454,11 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.25.0 (2026-09-04)
+- **The statusline now shows which version is running** — until now the version lived only in the table report's footer, so "which version am I on" meant running a full report. A `--version` flag was added alongside it.
+- **A new release asks at session start** — a statusline cannot open a dialog, so telling and asking are split. The statusline only reports (`⬆ v3.24.0 → 3.25.0`); the SessionStart hook injects a line telling the model to ask the user whether to upgrade. On yes it runs `claude-token-saver upgrade`, which uses the package manager that installed this copy; on no, `update-check --dismiss` mutes that version until a newer one ships.
+- **The check never blocks a render** — the registry lookup runs at most once every 24h in a detached background process, and the render path only reads the cache file. A failed check still stamps its timestamp, so an offline machine backs off instead of retrying every render. Disable with `CTS_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER`.
+
 ### v3.21.0 (2026-08-22)
 - **The install shows what it is about to enable, then asks** — the harness 5 principles and the Korean writing guidance used to be switched on by the installer, leaving the user with the result rather than the choice. The install now prints the five principle headings, and for the Korean guidance what it changes plus its per-session cost and source, before asking. Locale detection is demoted from an answer to the question's default, so an English-locale machine used for Korean work can enable it on the spot.
 - **Unattended installs behave exactly as before** — npm `postinstall`, CI, piped stdin and `CTS_NO_INPUT=1` skip the question and apply the old defaults, because a blocked prompt hangs an install. `--yes` and `--no-input` force that path explicitly. A non-interactive install on a non-Korean machine now leaves the setting undecided instead of recording an answer nobody gave, so a later run at a terminal still asks.

package/README.md

@@ -129,6 +129,8 @@ npm i -g claude-token-saver
 | `✦ current` / `📅 weekly` | 5시간 / 7일 rate-limit 윈도 사용률 + 리셋 시각 |
 | `📦` | 컨텍스트 사용률입니다(예: `Ctx 68% of 1M`). 사용률에 따라 녹색·노란색·빨간색으로 표시합니다. 최신 모델은 1M 컨텍스트가 기본이고 별도 요금이 붙지 않지만, 토큰량 자체가 턴당 비용과 5시간·7일 한도를 빠르게 소모시킵니다 |
 | `💰` | 프롬프트 캐시가 절약해 준 누적 금액입니다. 첫째 줄의 `🔀`(모델 라우팅 절감액)와는 **서로 다른 수치입니다** |
+| `v3.24.0` | 지금 실행 중인 claude-token-saver의 버전입니다. 최신이면 회색으로 줄 끝에 조용히 놓입니다 |
+| `⬆ v3.24.0 → 3.25.0` | 새 버전이 배포되어 있다는 표시입니다. 조치가 필요한 칩이므로 줄 앞쪽으로 올라옵니다 ([업데이트 안내](#-업데이트-안내)) |
 
 문제가 감지되면 **경고 칩을 줄 맨 앞에** 붙입니다.
 
@@ -157,11 +159,26 @@ Claude Code 안에서 `/claude-token-saver` Skill을 실행하거나, 칩에 적
 | `claude-token-saver route-scan` | 상위 모델이 반복 처리한 쉬운 작업을 감지해 haiku 위임 랫쳇 룰을 제안합니다 (아래 참고) |
 | `claude-token-saver route-scan savings` | 라우팅 절감 원장입니다. 모델 이동별 합계와 실행별 내역을 함께 보여 주며, 표시되는 금액의 근거가 됩니다 |
 | `claude-token-saver compact-window` | 1M 컨텍스트를 쓰면서 자동 압축 창이 설정되지 않았으면 경고하고, `set`으로 40만에 고정합니다 (아래 참고) |
-| `claude-token-saver korean on\|off\|status` | 한국어 문체 지침을 세션 시작 시 주입합니다 (아래 참고) |
+| `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 --version` | 설치된 버전을 출력합니다 |
+| `claude-token-saver update-check` | 새 버전이 있는지 확인합니다 (`--refresh`로 즉시 조회, `--dismiss`로 그 버전 안내 끄기) |
+| `claude-token-saver upgrade` | 설치 경로에 맞는 명령으로 최신 버전을 설치합니다 (`--print`로 실행 없이 명령만 확인) |
 | `claude-token-saver install` | Skill·statusline 수동 등록 |
 
 출력 언어는 `mode ko`와 `mode en`으로 전환합니다. 기본값은 영어이며, statusline의 칩은 언제나 기호로 표시합니다. 전체 옵션은 [영문 README](./README.en.md#options)를 참고하십시오.
 
+## ⬆ 업데이트 안내
+
+statusline은 대화 상자를 띄울 수 없고, 300밀리초마다 다시 그려지기 때문에 그리는 시점에 네트워크를 쓸 수도 없습니다. 그래서 안내를 두 지점으로 나누었습니다.
+
+- **statusline은 알리기만 합니다.** 최신 버전이면 줄 끝에 `v3.24.0`을 회색으로 조용히 표시하고, 새 버전이 있으면 `⬆ v3.24.0 → 3.25.0`을 줄 앞쪽에 노란색으로 올립니다. 빨간색은 쓰지 않습니다. 무엇도 고장 난 상태가 아니기 때문입니다.
+- **묻는 일은 세션 시작에서 합니다.** 새 세션이나 `/clear` 시점에 SessionStart 훅이 "새 버전이 있으니 사용자에게 업그레이드할지 물어보라"는 한 줄을 모델에게 주입합니다. 모델은 사용자에게 확인한 뒤에만 `claude-token-saver upgrade`를 실행합니다. 묻지 않고 설치하지 않습니다.
+- **거절은 기억합니다.** 사용자가 원치 않으면 `claude-token-saver update-check --dismiss`로 그 버전을 묻지 않도록 설정합니다. 더 새로운 버전이 배포되면 다시 묻습니다. statusline 칩은 그대로 남습니다. 거절한 것은 질문이지, 새 버전이 있다는 사실이 아니기 때문입니다.
+
+버전 조회는 24시간에 한 번, 분리된 백그라운드 프로세스가 수행하고 결과만 파일에 남깁니다(`update-check.json`). 이 방식은 npm의 `update-notifier`가 쓰는 것과 같습니다. 네트워크가 끊겨 있어도 실패 시각을 기록해 두므로 매 렌더마다 재시도하지 않습니다. 확인 자체를 끄려면 환경 변수 `CTS_NO_UPDATE_CHECK=1` 또는 `NO_UPDATE_NOTIFIER`를 설정하십시오.
+
 ## 🅷 Harness 모드
 
 다섯 원칙(Ratchet · Evidence · PEV · Structured Task · Default Safe Path)을 한 줄 명령으로 `CLAUDE.md`에 셋업하고 statusline이 `🅷 5/5`로 점수화합니다. 같은 에러가 반복되면 `🅷⚠ ratchet?` 알림이 떠서 룰로 승격할 수 있습니다.
@@ -303,6 +320,29 @@ Claude Code의 output style로도 같은 일을 할 수 있지만, output style
 
 기술적 내용은 양쪽이 동일합니다. 지침은 판단이나 정확도가 아니라 문장의 완성도에만 관여하므로, 답이 달라지는 것이 아니라 같은 답을 다시 읽지 않아도 되는 형태로 만들어 줍니다. 슬랙처럼 사람이 스크롤하며 읽는 채널에서는 이 차이가 되묻는 횟수를 줄이고, 되묻지 않는 만큼 토큰도 아낍니다.
 
+### 쓰기 시점 검사 (v3.24.0)
+
+지침을 세션 시작에 한 번 넣는 것만으로는 부족했습니다. 모델은 지침을 한 번 읽고 그 뒤로 파일 수십 개를 쓰는데, 그동안 결과물을 다시 읽어 보는 단계가 없었습니다. 그래서 지침이 켜진 세션이 규약에 어긋나는 문장을 문서에 그대로 실어 보냈고, 사람이 완성본을 읽을 때에야 드러났습니다. 2026년 8월에 적용 범위 문장을 고쳐서 같은 문제를 잡으려 했지만, 문장을 고쳐도 검사 단계가 없다는 조건은 그대로였기 때문에 재발했습니다.
+
+v3.24.0부터 `korean on`이 PostToolUse 훅을 함께 설치합니다. 모델이 방금 쓴 파일을 열어서 기계로 판정할 수 있는 조항을 검사하고, 위반이 있으면 모델에게 되돌려 보냅니다. 파일은 이미 저장된 뒤이므로 잃는 것은 없고, 모델이 그 자리에서 고칩니다.
+
+```bash
+claude-token-saver korean lint block   # 기본값. 위반을 되돌려 보내 고치게 합니다
+claude-token-saver korean lint warn    # 알리기만 하고 진행을 막지 않습니다
+claude-token-saver korean lint off     # 검사하지 않습니다
+
+claude-token-saver korean lint scope all     # 기본값. 세션이 쓴 모든 텍스트 파일
+claude-token-saver korean lint scope prose   # 마크다운·텍스트 문서만
+
+claude-token-saver korean lint docs/*.md     # 이미 저장된 파일을 직접 검사
+```
+
+검사 항목은 사람이 판정할 필요가 없는 것들입니다. 비유 어휘 15종(`~는 자리`, `~의 흐름`, `닿는다`, `걷어내다`, `발목을 잡다` 등), 번역체 표지(`~에 대한`, `~를 위한`, `~되어지`), 구분자(`—`·`ㅡ`·`|`), 한 구에 세 번 이상 이어지는 조사 `의`, 명사형 종결 뒤의 마침표입니다. 판단이 필요한 조항(성분 생략, 한자어 선택)은 그대로 지침이 담당합니다.
+
+기본 범위 `all`은 문서뿐 아니라 **코드 주석과 화면에 나가는 문자열, 자막·템플릿, 생성 결과물까지** 검사합니다. 벤더링한 지침 원문은 코드 주석을 예외로 두지만, 주석도 사람이 읽고 PDF·HTML 같은 산출물은 그 문자열들로 조립되기 때문에 예외로 두면 정확히 문제가 됐던 경로가 다시 열립니다. 검사에서 빠지는 것은 설치된 의존성(`node_modules`), VCS 내부, 락 파일, 그리고 이진·이미지 파일뿐입니다. `dist`나 `build` 같은 산출물 디렉터리는 검사합니다. 원문 규약대로 문서만 보고 싶으면 `korean lint scope prose`로 되돌립니다.
+
+주입문의 적용 범위 안내도 이 설정에서 생성합니다. 모델에게 알리는 범위와 검사하는 범위가 갈라지면 8월과 같은 상태로 돌아가기 때문입니다.
+
 ### 함께 주입되는 인코딩 규칙 (v3.23.2)
 
 문체 지침과 별도로, **도구 호출 인자에 담는 비ASCII 문자열은 리터럴 UTF-8로 쓰고 `\uXXXX` 유니코드 이스케이프로는 쓰지 말라**는 한 줄이 같이 주입됩니다.
@@ -380,6 +420,11 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.25.0 (2026-09-04)
+- **statusline에 실행 중인 버전을 표시합니다.** 지금까지는 표 형식 리포트의 각주에만 버전이 있었기 때문에, 어떤 버전이 도는지 확인하려면 전체 리포트를 실행해야 했습니다. `--version` 플래그도 함께 추가했습니다.
+- **새 버전이 나오면 세션 시작에 물어봅니다.** statusline은 대화 상자를 띄울 수 없으므로, 알림과 질문을 나누었습니다. statusline은 `⬆ v3.24.0 → 3.25.0`으로 알리기만 하고, 실제 질문은 SessionStart 훅이 모델에게 "사용자에게 업그레이드 여부를 확인하라"고 주입해서 이루어집니다. 승낙하면 `claude-token-saver upgrade`가 설치 경로에 맞는 명령을 실행하고, 거절하면 `update-check --dismiss`가 그 버전을 더 묻지 않도록 기록합니다.
+- **버전 확인이 렌더를 붙잡지 않습니다.** 조회는 24시간에 한 번 분리된 백그라운드 프로세스가 수행하고, 렌더 경로는 캐시 파일만 읽습니다. 확인에 실패해도 시각을 기록하므로 오프라인에서 매 렌더마다 재시도하지 않습니다. `CTS_NO_UPDATE_CHECK=1` 또는 `NO_UPDATE_NOTIFIER`로 끌 수 있습니다.
+
 ### v3.21.0 (2026-08-22)
 - **설치가 무엇을 켜는지 보여 준 뒤 물어봅니다** — 지금까지는 🅷 Harness 5원칙과 한국어 문체 지침을 설치가 스스로 켰고, 사용자는 결과만 볼 수 있었습니다. 이제 harness는 다섯 원칙의 제목을, 한국어 지침은 바꾸는 내용과 세션당 비용과 출처를 먼저 출력한 다음 켤지 묻습니다. 로캘 감지는 답이 아니라 질문의 기본값으로 내려왔으므로, 영어 로캘에서 한국어로 작업하는 경우에도 그 자리에서 켤 수 있습니다.
 - **사람이 붙어 있지 않은 설치는 예전대로 동작합니다** — npm의 `postinstall`, CI, 파이프 입력, `CTS_NO_INPUT=1`에서는 질문을 건너뛰고 기존 기본값을 그대로 적용합니다. 프롬프트가 멈춰 서면 설치가 걸리기 때문입니다. `--yes`와 `--no-input`으로 직접 강제할 수도 있습니다. 비대화형이면서 로캘이 한국어가 아닌 경우에는 설정을 저장하지 않고 미결정으로 남겨 두므로, 나중에 터미널에서 설치하면 그때 물어봅니다.

package/bin/cli.js

@@ -52,6 +52,7 @@ import { estimateCost } from '../src/cost.js';
 import { chipForIssues } from '../src/advice.js';
 import { debug } from '../src/debug.js';
 import { createArgs } from '../src/cli-args.js';
+import { updateStatus, maybeSpawnUpdateCheck } from '../src/update-check.js';
 
 const args = process.argv.slice(2);
 
@@ -66,6 +67,22 @@ const PKG_VERSION = (() => {
 
 const { getArg, hasFlag, numArg } = createArgs(args);
 
+/**
+ * Version/update state for the statusline chip. Reads a cache file and, when
+ * that cache has aged past the check interval, kicks a detached child to
+ * refresh it for a later render. Never awaits the network, never throws into
+ * the render: a registry outage must not cost the statusline its other chips.
+ */
+function readUpdateChip() {
+  try {
+    maybeSpawnUpdateCheck(PKG_VERSION);
+    return updateStatus(PKG_VERSION);
+  } catch (e) {
+    debug('update-check:chip', e);
+    return null;
+  }
+}
+
 async function main() {
   // Subcommand: last — print the most recent warning + how to handle it.
   // Designed for the auto-trigger skill so the user immediately sees
@@ -166,6 +183,37 @@ async function main() {
     return (await import('../src/commands/compact-window.js')).run({ args, hasFlag });
   }
 
+  // `--version` / `-v` — the flag every CLI is expected to answer. Until now
+  // the version was only visible in the table view's footer, which meant
+  // "which version am I on" required running a full report.
+  if (hasFlag('--version') || hasFlag('-v')) {
+    console.log(PKG_VERSION);
+    return;
+  }
+
+  // Subcommand: update-check — the registry lookup behind the ⬆ statusline
+  // chip and the session-start upgrade offer.
+  //   claude-token-saver update-check              # print cached status
+  //   claude-token-saver update-check --refresh    # hit the registry now (detached child uses this)
+  //   claude-token-saver update-check --dismiss    # stop offering THIS version at session start
+  if (args[0] === 'update-check') {
+    return (await import('../src/commands/update-check.js')).run({
+      hasFlag,
+      version: PKG_VERSION,
+    });
+  }
+
+  // Subcommand: upgrade — run the install command that matches how this copy
+  // got here, then confirm the new version.
+  //   claude-token-saver upgrade          # install the latest release
+  //   claude-token-saver upgrade --print  # just show the command, run nothing
+  if (args[0] === 'upgrade') {
+    return (await import('../src/commands/upgrade.js')).run({
+      hasFlag,
+      version: PKG_VERSION,
+    });
+  }
+
   // Hook management
   if (hasFlag('--install-hook')) {
     const { installHook } = await import('../src/hook-manager.js');
@@ -319,7 +367,7 @@ async function main() {
         } catch (e) { debug('caps-cache:persist', e); }
       }
       console.log(formatNoSession(
-        { caps, model, windowLabel },
+        { caps, model, windowLabel, version: PKG_VERSION, update: readUpdateChip() },
         { color: colorOk, mode: isIcon ? 'icon' : 'text' },
       ));
       return;
@@ -471,6 +519,8 @@ async function main() {
     anomalies,
     cost,
     options: { days, windowHours, windowLabel, version: PKG_VERSION },
+    // Cached-only; the background refresh it may trigger lands on a later render.
+    update: format === 'statusline' ? readUpdateChip() : null,
     lastActivity,
     spikeReport,
     contextWindow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.23.3",
+  "version": "3.25.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/src/commands/korean.js

@@ -11,14 +11,144 @@
  * machine. This ships the guidance with the package and delivers it through
  * the SessionStart hook that is already installed, so it applies everywhere
  * the CLI is installed and leaves the output-style slot free.
+ *
+ * Injection alone turned out to be half the job. The guidance is read once at
+ * session start and never again, so a long session writes documents that drift
+ * back to the patterns it forbids, and the drift is caught only when a human
+ * reads the finished file. `korean on` therefore also installs a PostToolUse
+ * hook that runs the machine-checkable clauses over the prose the model just
+ * wrote:
+ *   claude-token-saver korean lint block|warn|off   # how findings are handled
+ *   claude-token-saver korean lint <file...>        # check files on disk
  */
 
-export async function run({ args }) {
+// Enforcement is only useful if it is on by default — a check the user has to
+// discover is the same hole in a different shape.
+function koreanLintMode(cfg) {
+  const mode = cfg?.koreanStyle?.lint;
+  return mode === 'off' || mode === 'warn' ? mode : 'block';
+}
+
+// `all` checks every text file the session writes, including Korean sitting in
+// comments and UI strings. That is wider than the vendored guidance's own
+// exemption list, and deliberately so: a comment is read by a person, and
+// generated artifacts (PDF, HTML, captions) are assembled from those strings,
+// so exempting them reopens the gap for exactly the outputs users complained
+// about. `prose` restores the narrow reading.
+function koreanLintScope(cfg) {
+  return cfg?.koreanStyle?.lintScope === 'prose' ? 'prose' : 'all';
+}
+
+export async function run({ args, hasFlag }) {
   const sub = args[1] || 'status';
   const ks = await import('../korean-style.js');
-  const { userLanguage } = await import('../config.js');
+  const { userLanguage, loadConfig, saveConfig } = await import('../config.js');
   const lang = userLanguage();
 
+  // PostToolUse hook. Claude Code feeds the tool-call payload on stdin; we
+  // check the prose the model just wrote and hand any findings straight back
+  // to it. Silent and cheap when the file is clean, which is the common case.
+  if (hasFlag?.('--hook') || sub === '--hook') {
+    const { readStdinJson } = await import('../stdin-payload.js');
+    const payload = readStdinJson();
+    if (!payload || !ks.koreanStyleEnabled()) return;
+    const mode = koreanLintMode(loadConfig());
+    if (mode === 'off') return;
+    const { createRequire } = await import('node:module');
+    const req = createRequire(import.meta.url);
+    const lint = req('../korean-lint.cjs');
+    const result = lint.lintToolUse(payload, { scope: koreanLintScope(loadConfig()) });
+    if (!result) return;
+    const message = lint.formatFindings(result.filePath, result.findings);
+    if (mode === 'block') {
+      // Exit 2 is Claude Code's blocking-feedback channel: the file is already
+      // written, so nothing is lost, but the model must address this before it
+      // moves on. That is the whole point — a warning it can scroll past is
+      // what failed in the first place.
+      process.stderr.write(message + '\n');
+      process.exit(2);
+    }
+    console.log(message);
+    return;
+  }
+
+  // Manual run over files already on disk: `korean lint docs/*.md`.
+  if (sub === 'lint' && args.length > 2 && !['on', 'off', 'warn', 'block', 'scope'].includes(args[2])) {
+    const { readFileSync } = await import('node:fs');
+    const { createRequire } = await import('node:module');
+    const lint = createRequire(import.meta.url)('../korean-lint.cjs');
+    let total = 0;
+    for (const file of args.slice(2)) {
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch (e) {
+        console.error(`${file}: ${e.message}`);
+        continue;
+      }
+      const findings = lint.lintKoreanText(text, { code: !lint.isProseFile(file) });
+      total += findings.length;
+      if (findings.length) console.log(lint.formatFindings(file, findings));
+    }
+    if (total === 0) {
+      console.log(lang === 'ko' ? '문체 규약 위반이 없습니다.' : 'No findings.');
+    }
+    process.exit(total > 0 ? 1 : 0);
+  }
+
+  // Scope switch: `korean lint scope all|prose`.
+  if (sub === 'lint' && args[2] === 'scope') {
+    const cfg = loadConfig();
+    const next = args[3];
+    if (!next) {
+      console.log(lang === 'ko'
+        ? `검사 범위: ${koreanLintScope(cfg)}`
+        : `Check scope: ${koreanLintScope(cfg)}`);
+      return;
+    }
+    if (!['all', 'prose'].includes(next)) {
+      console.error('Usage: claude-token-saver korean lint scope [all|prose]');
+      process.exit(1);
+    }
+    cfg.koreanStyle = cfg.koreanStyle || {};
+    cfg.koreanStyle.lintScope = next;
+    saveConfig(cfg);
+    console.log(lang === 'ko'
+      ? (next === 'all'
+        ? '검사 범위: all — 문서와 코드 주석, UI 문자열까지 세션이 쓴 모든 텍스트 파일을 검사합니다.'
+        : '검사 범위: prose — 마크다운과 텍스트 문서만 검사합니다.')
+      : (next === 'all'
+        ? 'Check scope: all — every text file the session writes, comments and UI strings included.'
+        : 'Check scope: prose — documents only.'));
+    return;
+  }
+
+  // Enforcement mode: `korean lint block|warn|off`.
+  if (sub === 'lint') {
+    const mode = args[2];
+    const cfg = loadConfig();
+    if (!mode) {
+      console.log(lang === 'ko'
+        ? `쓰기 시점 검사: ${koreanLintMode(cfg)} (범위 ${koreanLintScope(cfg)})`
+        : `Write-time check: ${koreanLintMode(cfg)} (scope ${koreanLintScope(cfg)})`);
+      return;
+    }
+    if (!['block', 'warn', 'off'].includes(mode)) {
+      console.error('Usage: claude-token-saver korean lint [block|warn|off] | korean lint <file...>');
+      process.exit(1);
+    }
+    cfg.koreanStyle = cfg.koreanStyle || {};
+    cfg.koreanStyle.lint = mode;
+    saveConfig(cfg);
+    const note = {
+      block: lang === 'ko' ? '위반을 발견하면 모델에게 되돌려 보내 고치게 합니다.' : 'Findings are handed back to the model as blocking feedback.',
+      warn: lang === 'ko' ? '위반을 알리기만 하고 진행을 막지 않습니다.' : 'Findings are printed as a note and do not block.',
+      off: lang === 'ko' ? '쓰기 시점 검사를 하지 않습니다.' : 'The write-time check is disabled.',
+    }[mode];
+    console.log(`${lang === 'ko' ? '쓰기 시점 검사' : 'Write-time check'}: ${mode} — ${note}`);
+    return;
+  }
+
   if (sub === 'show') {
     const text = ks.koreanStyleText();
     if (!text) {
@@ -32,6 +162,8 @@ export async function run({ args }) {
   if (sub === 'on' || sub === 'off') {
     const enabled = sub === 'on';
     ks.setKoreanStyleEnabled(enabled);
+    const { installKoreanLintHook, removeKoreanLintHook } = await import('../installer.js');
+    const hook = enabled ? installKoreanLintHook() : removeKoreanLintHook();
     if (enabled) {
       console.log(lang === 'ko'
         ? '한국어 문체 지침을 켰습니다. 다음 세션부터 모든 프로젝트에 적용됩니다.'
@@ -42,6 +174,15 @@ export async function run({ args }) {
       console.log(lang === 'ko'
         ? `  출처: ${ks.KOREAN_STYLE_SOURCE}`
         : `  Source: ${ks.KOREAN_STYLE_SOURCE}`);
+      if (hook.action === 'skipped') {
+        console.log(lang === 'ko'
+          ? `  ⚠ 쓰기 시점 검사 훅을 못 걸었습니다: ${hook.reason}`
+          : `  ⚠ Could not register the write-time hook: ${hook.reason}`);
+      } else {
+        console.log(lang === 'ko'
+          ? `  쓰기 시점 검사: ${koreanLintMode(loadConfig())}, 범위 ${koreanLintScope(loadConfig())} (Write·Edit 로 쓴 한국어를 검사합니다)`
+          : `  Write-time check: ${koreanLintMode(loadConfig())}, scope ${koreanLintScope(loadConfig())} (runs on Korean written via Write/Edit)`);
+      }
     } else {
       console.log(lang === 'ko'
         ? '한국어 문체 지침을 껐습니다. 다음 세션부터 주입하지 않습니다.'
@@ -59,6 +200,7 @@ export async function run({ args }) {
   if (lang === 'ko') {
     console.log(`한국어 문체 지침: ${on ? '켜짐' : '꺼짐'}`);
     console.log(`  비용: 세션당 약 ${tokens} 토큰 (세션 시작 1회 주입)`);
+    console.log(`  쓰기 시점 검사: ${koreanLintMode(loadConfig())}, 범위 ${koreanLintScope(loadConfig())} (바꾸려면 claude-token-saver korean lint block|warn|off, korean lint scope all|prose)`);
     console.log(`  출처: ${ks.KOREAN_STYLE_SOURCE}`);
     console.log(`  라이선스 전문: ${ks.KOREAN_STYLE_LICENSE_PATH}`);
     console.log(on
@@ -67,6 +209,7 @@ export async function run({ args }) {
   } else {
     console.log(`Korean writing guidance: ${on ? 'on' : 'off'}`);
     console.log(`  Cost: ~${tokens} tokens per session (injected once at session start)`);
+    console.log(`  Write-time check: ${koreanLintMode(loadConfig())}, scope ${koreanLintScope(loadConfig())} (change with: claude-token-saver korean lint block|warn|off, korean lint scope all|prose)`);
     console.log(`  Source: ${ks.KOREAN_STYLE_SOURCE}`);
     console.log(`  License text: ${ks.KOREAN_STYLE_LICENSE_PATH}`);
     console.log(on

package/src/commands/route-scan.js

@@ -2,9 +2,23 @@
 
  */
 
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { readStdinJson } from '../stdin-payload.js';
 import { debug } from '../debug.js';
 
+/** This package's own version — the baseline the upgrade offer compares against. */
+function readPackageVersion() {
+  try {
+    const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkg, 'utf8')).version || null;
+  } catch (e) {
+    debug('route-scan:pkg-version', e);
+    return null;
+  }
+}
+
 export async function run({ args, hasFlag, numArg }) {
     const rs = await import('../route-scan.js');
     const { userLanguage } = await import('../config.js');
@@ -190,10 +204,44 @@ export async function run({ args, hasFlag, numArg }) {
         koreanBlock = koreanStyleInjection();
       } catch (e) { debug('route-scan:korean-style', e); /* style is optional */ }
 
+      // Upgrade offer. A statusline cannot open a dialog, so session start is
+      // where the *asking* happens: the model gets one line telling it a newer
+      // version exists and to ask before installing anything. Cached read only
+      // — the refresh runs detached off the statusline path, never here.
+      let updateBlock = null;
+      try {
+        const { updateStatus, maybeSpawnUpdateCheck } = await import('../update-check.js');
+        const pkgVersion = readPackageVersion();
+        // Session start is the one moment where a stale cache matters most, so
+        // kick the detached refresh here too. It lands in time for the
+        // statusline and for the next session, not for this line.
+        if (pkgVersion) maybeSpawnUpdateCheck(pkgVersion);
+        const u = pkgVersion ? updateStatus(pkgVersion) : null;
+        // `dismissed` is the whole point of asking once: a user who said no to
+        // this version must not be asked again every `/clear`.
+        if (u && u.available && !u.dismissed) {
+          updateBlock = lang === 'ko'
+            ? [
+                `[claude-token-saver update] 새 버전이 나와 있습니다: v${u.current} → ${u.latest}.`,
+                '사용자에게 지금 업그레이드할지 물어보고, 승낙하면 아래 명령을 실행하십시오. 묻지 않고 설치하지는 마십시오.',
+                '  claude-token-saver upgrade            # 업그레이드 실행',
+                '  claude-token-saver update-check --dismiss   # 사용자가 원치 않으면 (다음 버전이 나올 때까지 다시 묻지 않습니다)',
+              ].join('\n')
+            : [
+                `[claude-token-saver update] A newer version is available: v${u.current} → ${u.latest}.`,
+                'Ask the user whether to upgrade now, and run the command below only if they agree. Do not install without asking.',
+                '  claude-token-saver upgrade                  # perform the upgrade',
+                '  claude-token-saver update-check --dismiss   # if they decline (stays quiet until a newer release)',
+              ].join('\n');
+        }
+      } catch (e) { debug('route-scan:update-check', e); /* the offer is optional */ }
+
       if (open.length === 0 && reviewRules.length === 0) {
+        if (updateBlock) console.log(updateBlock);
         if (koreanBlock) console.log(koreanBlock);
         return; // nothing else to inject
       }
+      if (updateBlock) console.log(updateBlock);
       // This text is injected straight into the model's context, so it must
       // follow the user's configured language — a Korean-only briefing in an
       // English session steers the whole first response into Korean.

package/src/commands/update-check.js

@@ -0,0 +1,77 @@
+/**
+ * Subcommand: update-check — everything around "is a newer version out".
+ *
+ *   claude-token-saver update-check              # print the cached answer
+ *   claude-token-saver update-check --refresh    # ask the registry now
+ *   claude-token-saver update-check --refresh --quiet
+ *                                                # what the detached background child runs
+ *   claude-token-saver update-check --dismiss    # stop offering this version at session start
+ *
+ * The statusline never calls the --refresh path directly; it spawns this
+ * command detached so the render itself stays offline and instant.
+ */
+
+export async function run({ hasFlag, version }) {
+  const {
+    updateStatus,
+    refreshUpdateState,
+    dismissUpdate,
+    upgradeCommand,
+    updateCheckDisabled,
+    updateStatePath,
+  } = await import('../update-check.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const quiet = hasFlag('--quiet');
+
+  if (hasFlag('--refresh')) {
+    const res = await refreshUpdateState(version);
+    if (quiet) return;
+    if (!res.ok) {
+      console.error(lang === 'ko'
+        ? `최신 버전을 확인하지 못했습니다: ${res.error}`
+        : `Could not reach the registry: ${res.error}`);
+      process.exit(1);
+    }
+  }
+
+  if (hasFlag('--dismiss')) {
+    const s = updateStatus(version);
+    if (s.latest) dismissUpdate(s.latest);
+    console.log(lang === 'ko'
+      ? `${s.latest || '최신'} 버전 안내를 끕니다. 그 다음 버전이 나오면 다시 안내합니다.`
+      : `Muted the ${s.latest || 'latest'} notice. The next release after it will ask again.`);
+    return;
+  }
+
+  if (updateCheckDisabled()) {
+    console.log(lang === 'ko'
+      ? `현재 버전 v${version} — 업데이트 확인이 환경 변수로 꺼져 있습니다 (CTS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER).`
+      : `v${version} — update checks are disabled by env var (CTS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER).`);
+    return;
+  }
+
+  const s = updateStatus(version);
+  if (s.available) {
+    console.log(lang === 'ko'
+      ? `새 버전이 있습니다: v${version} → ${s.latest}`
+      : `Update available: v${version} → ${s.latest}`);
+    console.log(lang === 'ko'
+      ? `업그레이드: ${upgradeCommand()}   (또는 claude-token-saver upgrade)`
+      : `Upgrade with: ${upgradeCommand()}   (or: claude-token-saver upgrade)`);
+    if (s.dismissed) {
+      console.log(lang === 'ko'
+        ? '이 버전은 사용자가 한 번 넘긴 상태라, 세션 시작 시에는 다시 묻지 않습니다.'
+        : 'This version was dismissed, so the session-start offer stays quiet for it.');
+    }
+    return;
+  }
+  console.log(lang === 'ko'
+    ? `최신 버전을 쓰고 있습니다 (v${version}).`
+    : `Up to date (v${version}).`);
+  if (!s.latest) {
+    console.log(lang === 'ko'
+      ? `아직 확인된 기록이 없습니다. 지금 확인하려면: claude-token-saver update-check --refresh (기록 파일: ${updateStatePath()})`
+      : `No check has completed yet. Run: claude-token-saver update-check --refresh (state: ${updateStatePath()})`);
+  }
+}