claude-token-saver 3.23.3 → 3.24.0

package/README.en.md

@@ -158,7 +158,9 @@ 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 install` | Manually register Skill + statusline |
 
 Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
@@ -313,6 +315,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.**

package/README.md

@@ -157,7 +157,9 @@ 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 install` | Skill·statusline 수동 등록 |
 
 출력 언어는 `mode ko`와 `mode en`으로 전환합니다. 기본값은 영어이며, statusline의 칩은 언제나 기호로 표시합니다. 전체 옵션은 [영문 README](./README.en.md#options)를 참고하십시오.
@@ -303,6 +305,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` 유니코드 이스케이프로는 쓰지 말라**는 한 줄이 같이 주입됩니다.

package/package.json

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

@@ -284,6 +284,68 @@ export function installBriefHook() {
   return { path: file, action: 'created' };
 }
 
+// Registers the PostToolUse hook that checks Korean prose the session just
+// wrote. Session-start guidance teaches the model but is never re-read, so
+// files written later drift back to the patterns the guidance forbids and the
+// drift surfaces only when a human reads the artifact. This hook closes that
+// gap: it runs on the file the model just wrote, while it can still fix it.
+// Installed by `korean on`, removed by `korean off`. Idempotent.
+const KOREAN_LINT_HOOK_COMMAND = 'claude-token-saver korean --hook';
+
+export function installKoreanLintHook() {
+  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.PostToolUse !== undefined && !Array.isArray(settings.hooks.PostToolUse)) {
+    return { path: file, action: 'skipped', reason: 'hooks.PostToolUse is not an array — fix settings.json manually' };
+  }
+  const list = Array.isArray(settings.hooks.PostToolUse) ? settings.hooks.PostToolUse : [];
+  const already = list.some((m) =>
+    Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('korean --hook')),
+  );
+  if (already) return { path: file, action: 'exists' };
+
+  list.push({
+    matcher: 'Write|Edit|MultiEdit',
+    hooks: [{ type: 'command', command: KOREAN_LINT_HOOK_COMMAND, timeout: 10 }],
+  });
+  settings.hooks.PostToolUse = list;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: 'created' };
+}
+
+export function removeKoreanLintHook() {
+  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?.PostToolUse;
+  if (!Array.isArray(list)) return { path: file, action: 'absent' };
+  const kept = list.filter((m) =>
+    !(Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('korean --hook'))),
+  );
+  if (kept.length === list.length) return { path: file, action: 'absent' };
+  if (kept.length === 0) delete settings.hooks.PostToolUse;
+  else settings.hooks.PostToolUse = 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-lint.cjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * korean-lint — machine-checkable half of the fluent-korean guidance.
+ *
+ * Why this exists next to korean-style.js:
+ *
+ * korean-style.js hands the model ~1.3k tokens of prose at session start. That
+ * is the right way to teach judgement, but prose has no enforcement point. The
+ * model reads it once, writes forty files over the next two hours, and nothing
+ * ever re-checks the output. Users reported exactly that hole: the guidance was
+ * loaded, the session still shipped `~는 자리` and `~의 흐름` into documents,
+ * and it surfaced only when a human read the finished artifact.
+ *
+ * So the clauses a machine can decide are checked at write time instead. The
+ * PostToolUse hook already runs on Write/Edit, so every file the session
+ * produces passes through here and findings are handed back to the model while
+ * it can still fix them.
+ *
+ * Scope: every text file the session writes, documents and source alike. The
+ * vendored guidance exempts code comments, but a comment is read by a person
+ * and generated artifacts are assembled from the strings sitting in source, so
+ * exempting them reopens the gap for exactly the outputs that were reported.
+ * `isLintTarget(path, 'prose')` restores the narrow reading. Only dependencies,
+ * VCS internals, lockfiles, and binary or image files are skipped; build output
+ * is checked like anything else, and fenced code blocks are dropped from
+ * documents. Findings are requests to confirm, not
+ * verdicts — a settled idiom or a verbatim quotation is allowed to stay.
+ *
+ * Zero dependencies, CommonJS, so ~/.claude/cache-monitor-hook.cjs can require
+ * it standalone.
+ */
+
+'use strict';
+
+// Documents. Under the `prose` scope these are the only files checked.
+const PROSE_EXTENSIONS = new Set(['.md', '.mdx', '.markdown', '.txt', '.rst', '.adoc']);
+
+// Only two kinds of path are skipped: installed dependencies and VCS
+// internals, neither of which anyone in this session wrote. Build output is
+// deliberately NOT on this list. Generated artifacts are the files a reader
+// actually receives, so exempting `dist/` or `build/` would exempt the very
+// documents the check exists for.
+const SKIP_PATH = /(^|[\\/])(node_modules|\.git|.*\.min\.[a-z]+|.*-lock\.json|.*\.lock)([\\/]|$)/i;
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.pdf', '.zip', '.gz', '.tar',
+  '.mp3', '.mp4', '.wav', '.mov', '.woff', '.woff2', '.ttf', '.otf', '.map', '.bin',
+]);
+
+/**
+ * Figurative vocabulary (guidance 3.4). This is the clause human review misses
+ * most often, because each individual phrase reads fine in isolation — it is
+ * only against the rule that it is standing where a plain noun or verb should.
+ * Add a line here when a new one shows up; that is the whole maintenance story.
+ */
+const METAPHOR_LEXICON = [
+  // `자리` is the single most common substitution for a plain noun. Physical
+  // seating is the rare literal use, so those modifiers are excluded and
+  // everything else is raised for confirmation.
+  { re: /(?<!빈 |좌석 |앞 |뒤 |옆 )(?:^|(?<=\s))자리(?:에서|에서는|에|로|가|는|다|입니다|였습니다)?(?=\s|$|[.,·)])/, fix: "'지점'·'상황'·'부분'처럼 뜻을 그대로 담은 명사로 바꿉니다" },
+  { re: /[가-힣]+의\s*흐름/, fix: "'방향'·'순서'·'경과'로 바꿉니다" },
+  { re: /닿(?:는다|습니다|아|는 지점)/, fix: "'겨냥하다'·'해당하다'처럼 동작을 그대로 서술합니다" },
+  { re: /박(?:아 두|혀 있|아 넣)/, fix: "'명시하다'·'기록하다'로 바꿉니다" },
+  { re: /걷어내/, fix: "'없애다'·'제거하다'로 바꿉니다" },
+  { re: /손대(?:는|지|어)/, fix: "'수정하다'·'변경하다'로 바꿉니다" },
+  { re: /발목을 잡/, fix: '무엇이 어떻게 막는지 그대로 서술합니다' },
+  { re: /민낯|속살/, fix: "'실제 상태'·'내부 구조'로 바꿉니다" },
+  { re: /열쇠(?:다|입니다|가 된다)/, fix: "'핵심 조건'·'결정 요인'으로 바꿉니다" },
+  { re: /물꼬|신호탄|분수령|기폭제/, fix: '무엇이 시작되고 무엇이 바뀌는지 그대로 적습니다' },
+  { re: /판(?:을|도가|이)\s*(?:흔들|바뀌|뒤집)/, fix: '무엇이 어떻게 달라지는지 그대로 적습니다' },
+  { re: /몸집|심장부|두뇌 역할/, fix: "'규모'·'중심 구성 요소'로 바꿉니다" },
+  { re: /벽에 부딪|길을 열|문을 열/, fix: '무엇이 막히고 무엇이 가능해지는지 그대로 적습니다' },
+  { re: /갈림길|갈리는 지점/, fix: "'결정이 나뉘는 조건'으로 바꿉니다" },
+  { re: /깨어나|잠들어 있/, fix: "'동작을 시작하다'·'실행되지 않고 있다'로 바꿉니다" },
+];
+
+// Guidance 3.2/3.3: literal renderings of English noun phrases.
+const TRANSLATIONESE = [
+  { re: /에 대한/, fix: '서술어로 풀어 씁니다' },
+  { re: /[을를] 위한/, fix: '서술어로 풀어 씁니다' },
+  { re: /되어지/, fix: '이중 피동을 없애고 능동이나 단일 피동으로 씁니다' },
+  { re: /하는 것을 통해/, fix: "'~해서'·'~함으로써'로 줄입니다" },
+  { re: /라고 할 수 있다/, fix: '단정하거나 근거를 붙여 서술합니다' },
+];
+
+// Guidance 3.7: a period belongs after a 종결어미, not after a nominal ending.
+const NOMINAL_ENDING = /(?:음|함|됨|임|점|론|양|성|화)\.$/;
+
+/**
+ * Which files the checker opens.
+ *
+ * `prose` follows the guidance's own exemption list: documents only, because
+ * code and comments are excluded there. `all` is the scope users asked for
+ * once they saw what the narrow reading costs — Korean written into a comment,
+ * a UI string, or a template ends up in front of a reader exactly like a
+ * document does, and a generated PDF is assembled from those strings. Under
+ * `all` the only things skipped are installed dependencies, lockfiles, and
+ * files that are not text.
+ *
+ * When the scope is `all` the injected guidance says so too (see
+ * korean-style.js), so the model is told the same rule the checker enforces.
+ */
+function isLintTarget(filePath, scope = 'all') {
+  if (!filePath) return false;
+  if (SKIP_PATH.test(filePath)) return false;
+  const dot = filePath.lastIndexOf('.');
+  const ext = dot === -1 ? '' : filePath.slice(dot).toLowerCase();
+  if (PROSE_EXTENSIONS.has(ext)) return true;
+  if (scope !== 'all') return false;
+  if (!ext) return false;
+  return !BINARY_EXTENSIONS.has(ext);
+}
+
+// Kept for callers that only ever meant documents.
+function isProseFile(filePath) {
+  return isLintTarget(filePath, 'prose');
+}
+
+/** Drop fenced code blocks and inline code so snippets never trip the rules. */
+function stripCode(text) {
+  const out = [];
+  let fenced = false;
+  for (const line of String(text).split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      out.push('');
+      continue;
+    }
+    out.push(fenced ? '' : line.replace(/`[^`]*`/g, ' '));
+  }
+  return out;
+}
+
+function hasKorean(s) {
+  return /[가-힣]/.test(s);
+}
+
+/**
+ * Lint one document. Returns `[{ line, rule, hit, fix }]`, empty when clean.
+ * `lines` are 1-indexed against the original text so the model can jump
+ * straight to the offending line.
+ */
+function lintKoreanText(text, { maxFindings = 20, code = false } = {}) {
+  const findings = [];
+  const lines = stripCode(text);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!hasKorean(line)) continue;
+    // Reference lists and link lines are citations, not authored prose.
+    if (/^\s*\[\d+\]:/.test(line)) continue;
+    // A document that teaches the rules has to spell the banned form out. Its
+    // headings and its ✗/○ example pairs are quotations of the rule, not
+    // breaches of it, so they are left alone.
+    if (/^\s*#/.test(line)) continue;
+    if (/[✗○✘❌⭕]/.test(line)) continue;
+
+    const at = i + 1;
+    const push = (rule, hit, fix) => {
+      if (findings.length < maxFindings) findings.push({ line: at, rule, hit, fix });
+    };
+
+    // In a source file `|` is an operator, so only the dashes are checked
+    // there; in a document a leading `|` is a table row rather than a sentence.
+    const sep = line.match(code ? /[—ㅡ]/ : /[—ㅡ|]/);
+    if (sep && !(sep[0] === '|' && /^\s*\|/.test(line))) {
+      push('구분자', sep[0], '접속사나 쉼표, 가운뎃점(·)으로 바꿉니다');
+    }
+
+    for (const { re, fix } of TRANSLATIONESE) {
+      const m = line.match(re);
+      if (m) push('번역체', m[0], fix);
+    }
+
+    for (const { re, fix } of METAPHOR_LEXICON) {
+      const m = line.match(re);
+      if (m) push('비유 어휘', m[0], fix);
+    }
+
+    for (const chunk of line.split(/[.,·\n]/)) {
+      const count = (chunk.match(/[가-힣]의(?=\s|[가-힣])/g) || []).length;
+      if (count >= 3) {
+        push("'의' 반복", chunk.trim().slice(0, 30), '생략된 문장 성분이 없는지 확인합니다');
+        break;
+      }
+    }
+
+    const trimmed = line.trim();
+    if (NOMINAL_ENDING.test(trimmed) && !/^[#>\-*\d]/.test(trimmed)) {
+      push('명사형 종결', trimmed.slice(-8), "마침표를 빼거나 '~습니다'로 끝맺습니다");
+    }
+  }
+
+  return findings;
+}
+
+/** Pull the text a Write/Edit/MultiEdit call just put on disk. */
+function writtenTextOf(toolName, toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  if (toolName === 'Write') return typeof toolInput.content === 'string' ? toolInput.content : null;
+  if (toolName === 'Edit') return typeof toolInput.new_string === 'string' ? toolInput.new_string : null;
+  if (toolName === 'MultiEdit' || toolName === 'NotebookEdit') {
+    const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
+    const joined = edits.map((e) => (e && typeof e.new_string === 'string' ? e.new_string : '')).join('\n');
+    return joined || null;
+  }
+  return null;
+}
+
+/**
+ * Full check for one PostToolUse payload. Returns null when there is nothing to
+ * say, which is the common case and must stay cheap.
+ */
+function lintToolUse(context, { scope = 'all' } = {}) {
+  if (!context) return null;
+  const toolName = context.tool_name;
+  const toolInput = context.tool_input;
+  const filePath = toolInput && typeof toolInput.file_path === 'string' ? toolInput.file_path : '';
+  if (!isLintTarget(filePath, scope)) return null;
+
+  const text = writtenTextOf(toolName, toolInput);
+  if (!text || !hasKorean(text)) return null;
+
+  const findings = lintKoreanText(text, { code: !isProseFile(filePath) });
+  if (findings.length === 0) return null;
+  return { filePath, findings };
+}
+
+/** Render findings as the message handed back to the model. */
+function formatFindings(filePath, findings) {
+  const head = `[korean-style] ${filePath} 에 문체 규약 위반 ${findings.length}건이 있습니다. 파일을 고친 뒤 계속하십시오.`;
+  const body = findings.map((f) => `  ${f.line}행 ${f.rule}: "${f.hit}" 이 걸렸습니다. ${f.fix}`);
+  const tail = '  (원문 인용이거나 이미 굳은 표현이면 그대로 두고, 그 이유를 한 줄로 밝히십시오.)';
+  return [head, ...body, tail].join('\n');
+}
+
+module.exports = {
+  METAPHOR_LEXICON,
+  isLintTarget,
+  isProseFile,
+  lintKoreanText,
+  writtenTextOf,
+  lintToolUse,
+  formatFindings,
+};

package/src/korean-style.js

@@ -117,6 +117,27 @@ export function koreanStyleText() {
  * "the user is asking about Korean writing rules" instead of "these rules
  * govern how I write from now on".
  */
+// The injected scope sentence and the write-time checker have to agree. When
+// they disagree the model is told one thing and corrected for another, which
+// is how the August 2026 report started: the scope line read as excluding
+// documents, so a session shipped 18 em dashes into a markdown deliverable
+// while the guidance was active. These lines are therefore derived from the
+// same `lintScope` setting the checker reads.
+export function koreanScopeLines(cfg = loadConfig()) {
+  const scope = cfg?.koreanStyle?.lintScope === 'prose' ? 'prose' : 'all';
+  if (scope === 'prose') {
+    return [
+      '적용 대상: 대화 답변, 그리고 새로 작성하거나 수정하는 마크다운·문서·보고서의 한국어 산문을 모두 포함합니다.',
+      '적용 예외: 원문을 그대로 옮기는 인용, 코드, 코드 주석, 그리고 프로젝트의 기존 표기 관례를 따라야 하는 커밋 메시지와 로그 문자열입니다.',
+    ];
+  }
+  return [
+    '적용 대상: 대화 답변, 그리고 세션이 쓰거나 고치는 모든 파일의 한국어를 포함합니다. 문서와 보고서는 물론이고 코드 주석, 화면에 나가는 문자열, 자막과 템플릿, 스크립트가 읽어 산출물을 만드는 데이터 파일까지 모두 해당합니다.',
+    '적용 예외: 원문을 그대로 옮기는 인용과, 프로젝트의 기존 표기 관례를 따라야 하는 커밋 메시지와 로그 문자열입니다.',
+    '쓰기 시점에 기계 검사가 함께 돌아갑니다. 위반을 알리면 그 파일을 고친 뒤에 다음 작업으로 넘어가십시오.',
+  ];
+}
+
 export function koreanStyleInjection({ cfg = loadConfig() } = {}) {
   if (!koreanStyleEnabled(cfg)) return null;
   const text = koreanStyleText();
@@ -124,8 +145,7 @@ export function koreanStyleInjection({ cfg = loadConfig() } = {}) {
   return [
     '[claude-token-saver korean-style] 이 세션에서 한국어를 출력할 때는 아래 지침을 따르십시오.',
     '이 지침은 사용자가 claude-token-saver에 설정한 것입니다.',
-    '적용 대상: 대화 답변, 그리고 새로 작성하거나 수정하는 마크다운·문서·보고서의 한국어 산문을 모두 포함합니다.',
-    '적용 예외: 원문을 그대로 옮기는 인용, 코드, 코드 주석, 그리고 프로젝트의 기존 표기 관례를 따라야 하는 커밋 메시지와 로그 문자열입니다.',
+    ...koreanScopeLines(cfg),
     '표기 규칙(예외 없이 적용): 도구 호출 인자에 한국어를 비롯한 비ASCII 문자열을 담을 때에는 반드시 리터럴 UTF-8로 작성하고, \\uXXXX 유니코드 이스케이프로는 절대 작성하지 마십시오. 이스케이프로 작성하면 글자가 깨진 채 파일에 기록되는 사례가 자주 발생합니다.',
     `(출처: ${KOREAN_STYLE_SOURCE})`,
     '',