claude-token-saver 3.26.2 → 3.27.0

package/README.en.md

@@ -384,6 +384,16 @@ Installs with nobody attached — npm `postinstall`, CI, piped stdin — skip th
 
 **This is opt-in.** Installing the CLI does not turn it on: both commands below are required, and a registered hook with no converter behind it does nothing at all.
 
+Three situations, three different interception points:
+
+| Situation | Where it is caught |
+|---|---|
+| A document path typed in the prompt (`@path`, quoted, or relative) | `UserPromptSubmit`: converted, and the conversion's path is handed back as context |
+| A document opened with `Read` mid-task | PDFs are caught by `PreToolUse(Read)`. pptx/xlsx/docx are not: Claude Code refuses them as binary *before* any hook runs, so the session-start note tells the model to run `doc2md <path>` instead |
+| A document attached to the message | **Not catchable.** No hook event receives attachment content. The session-start note has the model ask for a path next time |
+
+That second row is measured, not assumed: a `.pdf` Read fires the hook, and a `.pptx` Read in the same session leaves no hook log entry at all.
+
 ```bash
 claude-token-saver doc2md install-converter   # markitdown into a dedicated venv
 claude-token-saver doc2md on                  # register the Read hook
@@ -502,6 +512,11 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.27.0 (2026-09-04)
+- **A document path in the prompt is finally caught.** The 3.26.x `PreToolUse(Read)` hook never reached the formats it was written for: Claude Code refuses pptx/xlsx/docx as binary *before* running any hook. Measured — a `.pdf` Read fires the hook, a `.pptx` Read in the same session leaves no hook log entry. Interception now also happens at `UserPromptSubmit`, which sees the raw prompt: paths there are converted and the conversion is handed back as context. `@path`, quoted and relative forms all count.
+- **A session-start note was added.** It tells the model two things it cannot work out alone: that a binary-file refusal is answered by `doc2md <path>`, and that if the user attached a document, they should be asked for a path next time. An attachment bills its entire contents into the context, and no hook event receives attachment content, so there is nothing the tool itself can do about it.
+- **`doc2md on` registers both hooks**, and `off` removes only its own entries from both.
+
 ### v3.26.2 (2026-09-04)
 - **The converter installs itself.** The old instruction was `pip install`, which asks the user to modify a system interpreter — and if they skipped it, the hook sat registered and did nothing. `doc2md install-converter` builds a dedicated venv and puts markitdown in it.
 - **`doc2md` status now reports hook registration too.** Showing only the converter made "hook but no converter" and "converter but no hook" look identical, and both look like a broken feature.

package/README.md

@@ -374,6 +374,16 @@ pptx·xlsx·pdf·docx 를 그대로 `Read` 하면 모델이 읽지 못하는 바
 
 **이 기능은 옵트인입니다.** 설치만으로는 켜지지 않고, 아래 두 명령을 모두 실행해야 동작합니다. 훅만 등록하고 변환기가 없으면 아무 일도 일어나지 않습니다.
 
+세 가지 경로를 덮습니다. 각각 걸리는 지점이 다릅니다.
+
+| 상황 | 개입 지점 |
+|---|---|
+| 프롬프트에 문서 경로를 적음 (`@경로`·따옴표·상대 경로 모두) | `UserPromptSubmit`. 변환한 뒤 변환본 경로를 컨텍스트로 넣습니다 |
+| 작업 도중 문서를 `Read` | pdf 는 `PreToolUse(Read)` 가 잡습니다. pptx·xlsx·docx 는 Claude Code 가 이진 파일이라며 훅보다 먼저 거부하므로, 세션 시작 안내문이 모델에게 `doc2md <경로>` 를 실행하도록 지시합니다 |
+| 문서를 메시지에 직접 첨부 | **훅으로 잡을 수 없습니다.** 어떤 훅 이벤트도 첨부 내용을 받지 못합니다. 세션 시작 안내문이 다음부터 경로로 달라고 사용자에게 안내하도록 모델에게 지시합니다 |
+
+두 번째 줄의 제약은 실측으로 확인한 것입니다. `.pdf` 를 Read 하면 훅이 실행되고, 같은 세션에서 `.pptx` 를 Read 하면 훅 로그에 아무 기록도 남지 않습니다.
+
 ```bash
 claude-token-saver doc2md install-converter   # 전용 venv에 markitdown 설치
 claude-token-saver doc2md on                  # Read 훅 등록
@@ -468,6 +478,11 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.27.0 (2026-09-04)
+- **문서 경로를 프롬프트에 적으면 이제 실제로 걸립니다.** 3.26.x 의 `PreToolUse(Read)` 훅은 정작 목표한 형식에 닿지 못했습니다. Claude Code 가 pptx·xlsx·docx 를 이진 파일이라며 훅보다 먼저 거부하기 때문입니다(실측: `.pdf` Read 는 훅이 실행되고 `.pptx` Read 는 훅 기록이 남지 않습니다). 개입 지점을 `UserPromptSubmit` 으로 넓혀, 프롬프트에 적힌 경로를 변환한 뒤 변환본 경로를 컨텍스트로 넣습니다. `@경로`·따옴표·상대 경로를 모두 인식합니다.
+- **세션 시작 안내문을 추가했습니다.** 두 가지를 모델에게 알립니다. `Read` 가 이진 파일이라며 거부하면 `doc2md <경로>` 를 실행할 것, 그리고 사용자가 문서를 직접 첨부했으면 다음부터 경로로 달라고 안내할 것입니다. 첨부는 내용 전체가 컨텍스트에 실려 토큰을 크게 쓰는데, 어떤 훅 이벤트도 첨부 내용을 받지 못해 도구가 개입할 방법이 없습니다.
+- **`doc2md on` 이 훅 두 개를 함께 등록합니다.** `off` 는 자기 항목만 골라 양쪽에서 지웁니다.
+
 ### v3.26.2 (2026-09-04)
 - **doc2md 변환기를 도구가 직접 설치합니다.** 지금까지의 안내는 `pip install` 이었는데, 시스템 파이썬을 건드리라는 요구인 데다 실행하지 않으면 훅만 등록된 채 아무 일도 일어나지 않았습니다. `doc2md install-converter` 가 전용 venv 를 만들어 markitdown 을 넣습니다.
 - **`doc2md` 상태 출력에 훅 등록 여부를 함께 적습니다.** 변환기만 알려 주면 "훅은 있는데 변환기가 없다"와 "변환기는 있는데 훅이 없다"가 똑같이 아무 일도 안 하는 상태로 보여서, 어느 쪽이 빠졌는지 알 수 없었습니다.

package/package.json

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

@@ -69,6 +69,24 @@ export async function run({ args, hasFlag }) {
     return;
   }
 
+  // UserPromptSubmit entry point. Separate from `--hook` because the two speak
+  // different protocols: PreToolUse answers with a permission decision, this
+  // one answers with plain text that becomes context the model can act on.
+  if (hasFlag?.('--hook-prompt') || sub === '--hook-prompt') {
+    const { readStdinJson } = await import('../stdin-payload.js');
+    const payload = readStdinJson();
+    if (!payload) return;
+    const { userLanguage } = await import('../config.js');
+    try {
+      const context = doc2md.contextForPrompt(payload, { lang: userLanguage() });
+      if (context) console.log(context);
+    } catch {
+      // Never break a prompt over a conversion. Silence leaves the session
+      // exactly as it would have been without this feature.
+    }
+    return;
+  }
+
   if (sub === 'on') {
     const { installDoc2mdHook } = await import('../installer.js');
     const res = installDoc2mdHook();

package/src/commands/route-scan.js

@@ -5,9 +5,34 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
 import { readStdinJson } from '../stdin-payload.js';
 import { debug } from '../debug.js';
 
+/**
+ * Whether the user turned doc2md on.
+ *
+ * Read from settings.json rather than from a config flag because the hook
+ * registration *is* the switch: a note telling the model how to convert
+ * documents is noise in a session where nothing will convert them.
+ */
+function doc2mdHookRegistered() {
+  try {
+    const { homedir } = require('node:os');
+    const settings = JSON.parse(readFileSync(join(homedir(), '.claude', 'settings.json'), 'utf8'));
+    return Object.values(settings?.hooks || {}).some((matchers) =>
+      (matchers || []).some((m) =>
+        (m.hooks || []).some((h) => typeof h.command === 'string' && h.command.includes('doc2md --hook')),
+      ),
+    );
+  } catch (e) {
+    debug('route-scan:doc2md-registered', e);
+    return false;
+  }
+}
+
 /** This package's own version — the baseline the upgrade offer compares against. */
 function readPackageVersion() {
   try {
@@ -218,6 +243,17 @@ export async function run({ args, hasFlag, numArg }) {
         koreanBlock = koreanStyleInjection();
       } catch (e) { debug('route-scan:korean-style', e); /* style is optional */ }
 
+      // doc2md's standing note, only when the user turned the feature on.
+      // Rides the same SessionStart round-trip as the style block for the same
+      // reason: one injection, one cached prefix. It carries the two things the
+      // model cannot work out for itself — that a binary-file refusal has a
+      // one-command answer, and that an attached document costs far more than
+      // the path to it.
+      let doc2mdBlock = null;
+      try {
+        if (doc2mdHookRegistered()) doc2mdBlock = require('../doc2md.cjs').sessionNote(lang);
+      } catch (e) { debug('route-scan:doc2md-note', e); /* the note 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
@@ -252,10 +288,12 @@ export async function run({ args, hasFlag, numArg }) {
 
       if (open.length === 0 && reviewRules.length === 0) {
         if (updateBlock) console.log(updateBlock);
+        if (doc2mdBlock) console.log(doc2mdBlock);
         if (koreanBlock) console.log(koreanBlock);
         return; // nothing else to inject
       }
       if (updateBlock) console.log(updateBlock);
+      if (doc2mdBlock) console.log(doc2mdBlock);
       // 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/doc2md.cjs

@@ -419,6 +419,119 @@ function decideForRead(context, opts = {}) {
   return null;
 }
 
+/**
+ * Document paths mentioned in a prompt.
+ *
+ * This exists because the PreToolUse hook cannot reach the formats it was
+ * written for. Claude Code rejects pptx/xlsx/docx as binary *before* running
+ * the hook — verified: a `.pdf` Read fires the hook, a `.pptx` Read never
+ * does — so by the time doc2md could speak, the tool call is already refused.
+ * UserPromptSubmit runs earlier than any of that and sees the raw text, so a
+ * path the user typed can be converted before the model tries to open it.
+ *
+ * Quoted, `@`-prefixed and bare paths all count. Windows drive letters are
+ * matched too, since the rest of the module is path-agnostic.
+ */
+function documentPathsIn(text) {
+  if (typeof text !== 'string' || !text) return [];
+  const exts = TARGET_EXTENSIONS.map((e) => e.slice(1)).join('|');
+  const re = new RegExp(`[@'"\`]?((?:[A-Za-z]:)?[~./][^\\s'"\`]*\\.(?:${exts}))`, 'gi');
+  const found = [];
+  for (const m of text.matchAll(re)) {
+    const raw = m[1];
+    const abs = raw.startsWith('~') ? path.join(os.homedir(), raw.slice(1)) : path.resolve(raw);
+    if (!found.includes(abs)) found.push(abs);
+  }
+  return found;
+}
+
+// One prompt naming a dozen decks should not turn a keystroke into a minute of
+// conversion. The rest are named in the note so nothing disappears quietly.
+const MAX_PROMPT_CONVERSIONS = 3;
+
+/**
+ * Context to inject for a UserPromptSubmit payload, or null.
+ *
+ * Returns plain text because that is what this hook can give the model:
+ * stdout becomes context it can act on. There is no decision to make here —
+ * the prompt is not blocked, it is answered better.
+ */
+function contextForPrompt(payload, opts = {}) {
+  const lang = opts.lang === 'ko' ? 'ko' : 'en';
+  if (!payload || typeof payload.prompt !== 'string') return null;
+  const paths = documentPathsIn(payload.prompt).filter((p) => {
+    try { return fs.statSync(p).isFile(); } catch { return false; }
+  });
+  if (paths.length === 0) return null;
+
+  const lines = [];
+  const targets = paths.slice(0, MAX_PROMPT_CONVERSIONS);
+  for (const p of targets) {
+    const name = path.basename(p);
+    const result = convert(p, opts);
+    if (result.ok) {
+      lines.push(`  ${name} → ${result.cacheFile}`);
+      if (result.meta && result.meta.note) lines.push(`      ${result.meta.note}`);
+      if (result.meta && result.meta.clipped) {
+        lines.push('      변환 결과가 너무 커서 뒷부분을 잘랐습니다. 전체가 필요하면 원본을 직접 다루십시오.');
+      }
+    } else if (result.reason === 'no-markitdown') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: 변환기가 없어 변환하지 못했습니다. 설치: ${INSTALL_HINT}`
+        : `  ${name}: no converter installed. Install it with: ${INSTALL_HINT}`);
+    } else if (result.reason === 'sensitive') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: 파일명이 민감 문서 패턴에 걸려 변환하지 않았습니다.`
+        : `  ${name}: skipped — the filename matches a sensitive-document pattern.`);
+    } else {
+      lines.push(lang === 'ko'
+        ? `  ${name}: 변환하지 못했습니다 (${result.reason}).`
+        : `  ${name}: conversion failed (${result.reason}).`);
+    }
+  }
+  if (paths.length > targets.length) {
+    lines.push(lang === 'ko'
+      ? `  (문서 ${paths.length}개 가운데 앞 ${targets.length}개만 변환했습니다. 나머지는 \`claude-token-saver doc2md <경로>\` 로 변환하십시오.)`
+      : `  (converted the first ${targets.length} of ${paths.length} documents; run \`claude-token-saver doc2md <path>\` for the rest.)`);
+  }
+
+  return lang === 'ko'
+    ? [
+      '[doc2md] 이 프롬프트에 문서 경로가 있어 Markdown 으로 변환해 두었습니다.',
+      ...lines,
+      '원본 대신 위 변환본을 Read 하십시오. pptx·xlsx·docx 는 Read 도구가 이진 파일이라며 거부하므로 원본을 직접 열 수 없습니다.',
+      '경로가 주어지지 않은 문서를 열어야 할 때는 `claude-token-saver doc2md <경로>` 를 실행해 변환본 경로를 얻으십시오.',
+    ].join('\n')
+    : [
+      '[doc2md] This prompt names document paths, which have been converted to Markdown:',
+      ...lines,
+      'Read the conversions above rather than the originals: Read refuses pptx/xlsx/docx as binary files, so the originals cannot be opened directly.',
+      'For a document whose path was not given here, run `claude-token-saver doc2md <path>` to get its conversion.',
+    ].join('\n');
+}
+
+/**
+ * The standing note injected at session start.
+ *
+ * Two things the model cannot work out on its own: that attaching a document
+ * costs far more than naming its path, and that the binary-file refusal it
+ * will meet on a pptx has a one-command answer.
+ */
+function sessionNote(lang = 'en') {
+  if (lang === 'ko') {
+    return [
+      '[doc2md] 문서(pptx·xlsx·pdf·docx)를 다룰 때의 규칙입니다.',
+      '  문서를 열어야 하는데 Read 가 이진 파일이라며 거부하면, `claude-token-saver doc2md <경로>` 를 실행하고 그 결과로 나온 .md 를 Read 하십시오.',
+      '  사용자가 문서를 메시지에 직접 첨부했다면, 첨부는 내용 전체가 컨텍스트에 실려 토큰을 크게 씁니다. 다음부터는 첨부 대신 파일 경로를 적어 달라고 안내하십시오. 경로로 주면 변환본만 읽습니다.',
+    ].join('\n');
+  }
+  return [
+    '[doc2md] Handling documents (pptx/xlsx/pdf/docx):',
+    '  If Read refuses a document as a binary file, run `claude-token-saver doc2md <path>` and Read the .md it prints.',
+    '  If the user attached a document to their message, its full contents were billed into the context. Tell them that naming the file path instead is far cheaper, since only the converted Markdown gets read.',
+  ].join('\n');
+}
+
 /** The decision rendered as the JSON Claude Code expects on stdout. */
 function formatHookOutput(decision) {
   if (!decision) return null;
@@ -444,6 +557,9 @@ module.exports = {
   metaPathFor,
   isTargetPath,
   isSensitivePath,
+  documentPathsIn,
+  contextForPrompt,
+  sessionNote,
   findInterpreter,
   readCache,
   writeCache,

package/src/installer.js

@@ -358,6 +358,7 @@ export function removeKoreanLintHook() {
 // 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';
+const DOC2MD_PROMPT_HOOK_COMMAND = 'claude-token-saver doc2md --hook-prompt';
 
 export function installDoc2mdHook() {
   const dir = claudeUserDir();
@@ -388,6 +389,23 @@ export function installDoc2mdHook() {
     hooks: [{ type: 'command', command: DOC2MD_HOOK_COMMAND }],
   });
   settings.hooks.PreToolUse = list;
+
+  // The Read hook alone covers only PDFs. Claude Code refuses pptx/xlsx/docx
+  // as binary before any PreToolUse hook runs, so for exactly the formats this
+  // feature exists for, the tool call is dead before doc2md is consulted.
+  // UserPromptSubmit runs earlier and sees the raw prompt text, which is where
+  // a path the user typed can still be turned into Markdown.
+  if (settings.hooks.UserPromptSubmit === undefined || Array.isArray(settings.hooks.UserPromptSubmit)) {
+    const prompts = Array.isArray(settings.hooks.UserPromptSubmit) ? settings.hooks.UserPromptSubmit : [];
+    const hasPromptHook = prompts.some((m) =>
+      Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('doc2md --hook-prompt')),
+    );
+    if (!hasPromptHook) {
+      prompts.push({ hooks: [{ type: 'command', command: DOC2MD_PROMPT_HOOK_COMMAND }] });
+      settings.hooks.UserPromptSubmit = prompts;
+    }
+  }
+
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
   return { path: file, action: 'created' };
 }
@@ -401,16 +419,22 @@ export function removeDoc2mdHook() {
   } 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;
+  // Both entries go, and only this tool's own: anything else registered under
+  // either event stays exactly where the user put it. The substring covers
+  // `--hook` and `--hook-prompt` alike.
+  let touched = false;
+  for (const event of ['PreToolUse', 'UserPromptSubmit']) {
+    const list = settings?.hooks?.[event];
+    if (!Array.isArray(list)) continue;
+    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) continue;
+    touched = true;
+    if (kept.length === 0) delete settings.hooks[event];
+    else settings.hooks[event] = kept;
+  }
+  if (!touched) return { path: file, action: 'absent' };
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
   return { path: file, action: 'removed' };
 }