claude-token-saver 3.6.4 → 3.7.0

package/README.en.md

@@ -243,6 +243,9 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.7.0 (2026-07-29)
+- **Fixed: delegation rules named subagents that may not exist** — generated T2 rules hard-coded preset names like `haiku-explore` / `haiku-runner`, which live in each user's own `~/.claude/agents/` and are not shipped by this package. On a machine without them, the rule told the model to delegate to a nonexistent agent. The default phrasing is now `model: haiku` (matching T1's `model: sonnet`), and the name is added only when the agent file is really present, e.g. `haiku-explore(model: haiku)`. Project-level `.claude/agents/` counts too. `ratchet-model.md` re-renders with the new phrasing on the next `route-scan`.
+
 ### v3.6.4 (2026-07-29)
 - **Fixed: false `🅷⚠ ratchet-unloaded`** — the import check looked at a single CLAUDE.md. When the project file carried the harness block, only that file was inspected, so the common layout of block-in-project + `@` imports-in-global raised the warning even though the rules loaded fine. Claude Code loads both files, so the flags are now the union of the two, and `importSource` (`project`/`global`/`both`) says which file carries them. The warning fires only when neither file imports.
 

package/README.md

@@ -200,6 +200,9 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.7.0 (2026-07-29)
+- **위임 룰이 없는 서브에이전트를 가리키던 문제 수정** — 생성되는 T2 룰이 `haiku-explore`·`haiku-runner` 같은 이름을 직접 적었는데, 이 preset 에이전트들은 각자의 `~/.claude/agents/`에 있는 것이라 패키지가 배포하지 않습니다. 그래서 해당 파일이 없는 환경에서는 "존재하지 않는 에이전트로 위임하라"는 룰이 자동 생성됐습니다. 이제 기본 표현은 `model: haiku`(T1의 `model: sonnet`과 통일)이고, 에이전트 파일이 실제로 있을 때만 `haiku-explore(model: haiku)`처럼 이름을 병기합니다. 프로젝트 `.claude/agents/`도 인식합니다. 다음 `route-scan` 때 `ratchet-model.md`가 새 표현으로 다시 렌더됩니다.
+
 ### v3.6.4 (2026-07-29)
 - **`🅷⚠ ratchet-unloaded`가 잘못 뜨던 버그 수정** — import 여부를 CLAUDE.md 한 파일에서만 확인했습니다. 프로젝트 `CLAUDE.md`에 harness 블록이 있으면 그 파일만 보고 판정했기 때문에, `@` import가 글로벌 `~/.claude/CLAUDE.md`에 있는 흔한 조합에서는 룰이 정상 로드되는데도 경고가 떴습니다. Claude Code는 두 파일을 모두 로드하므로 이제 양쪽의 import를 합쳐서 판정하고, 어느 쪽이 들고 있는지는 `importSource`(`project`/`global`/`both`)로 알려줍니다. 두 파일 다 import가 없을 때만 경고합니다.
 

package/package.json

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

package/presets/ratchet-rules.md

@@ -13,4 +13,4 @@
 - 자동화 도구가 grep·정규식으로 찾는 마커 텍스트(헤더·앵커·키워드 라인)는 리팩터링·압축·수정 금지 — 정확 매칭 검출은 한 글자만 바뀌어도 깨짐
 - 자동화 설계에서 vision/screenshot 루프가 보이면 → 호출 가능한 함수·API·MCP tool부터 찾는다. 통제 가능한 내부 도구는 무조건 API, 통제 불가 외부 SaaS만 vision 차선책. 인터페이스를 바꾼 뒤에 모델을 내린다 — 거꾸로 가면 토큰 폭발
 - 입력 데이터(ground-truth) 변경 시 그에 의존하는 모든 파생 자산을 끝까지 재생성한다 — 중간 단계를 생략하면 stale 산출물이 새 입력 위에 얹혀 결과가 깨짐
-- 탐색·조회·상태 확인·명령 실행 같은 단순 요청은 haiku 서브에이전트(haiku-explore·haiku-runner 등)로 위임해 상위 모델 토큰을 아낀다
+- 탐색·조회·상태 확인·명령 실행 같은 단순 요청은 `model: haiku` 서브에이전트로 위임해 상위 모델 토큰을 아낀다 (읽기 전용 preset 에이전트가 이미 있으면 그걸 쓰고, 없으면 티어만 내려서 위임)

package/src/agents.js

@@ -0,0 +1,52 @@
+/**
+ * How a delegation target is phrased in generated rules.
+ *
+ * Rules used to name concrete subagents (`haiku-explore`, `haiku-runner`, …).
+ * Those live in the user's own `~/.claude/agents/` and are NOT shipped by this
+ * package, so on any machine that never created them the generated rule told
+ * the model to delegate to an agent that does not exist. The model tier is the
+ * part that actually saves tokens and it is universal, so `model: haiku` is the
+ * default phrasing — the agent name is only added when the file is really
+ * there, which keeps the tool-restricted preset in play for users who have it.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { claudeUserDir } from './paths.js';
+
+/** Tier each preset agent is pinned to, for the `model:` half of the phrase. */
+const AGENT_MODEL = {
+  'haiku-explore': 'haiku',
+  'haiku-runner': 'haiku',
+  'haiku-translate': 'haiku',
+  'sonnet-worker': 'sonnet',
+};
+
+/** True when `<name>.md` exists in the project or user agents directory. */
+export function agentExists(name, root = process.cwd()) {
+  if (!name) return false;
+  return existsSync(join(root, '.claude', 'agents', `${name}.md`)) ||
+    existsSync(join(claudeUserDir(), 'agents', `${name}.md`));
+}
+
+/**
+ * Korean phrase for a delegation target, e.g.
+ *   agent present → `haiku-explore(model: haiku)`
+ *   agent absent  → `model: haiku`
+ */
+export function agentPhrase(name, { model, root } = {}) {
+  const tier = model || AGENT_MODEL[name] || 'haiku';
+  return agentExists(name, root) ? `${name}(model: ${tier})` : `model: ${tier}`;
+}
+
+/**
+ * English phrase, including the article, e.g.
+ *   agent present → `the haiku-explore (model: haiku) subagent`
+ *   agent absent  → `a model: haiku subagent`
+ */
+export function agentPhraseEn(name, { model, root } = {}) {
+  const tier = model || AGENT_MODEL[name] || 'haiku';
+  return agentExists(name, root)
+    ? `the ${name} (model: ${tier}) subagent`
+    : `a model: ${tier} subagent`;
+}

package/src/model-rules.js

@@ -33,6 +33,7 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { userDataDir } from './paths.js';
 import { userLanguage } from './config.js';
+import { agentPhrase, agentPhraseEn } from './agents.js';
 
 // Post-promotion delegated-category error rate above this flags the rule
 // for review (rule-health). Calibrated against local T0 avg error incidence.
@@ -144,10 +145,10 @@ export function renderModelRatchet(rules, lang = userLanguage()) {
     const t1 = group.find((r) => r.tier === 'T1');
     if (t2 && t1) {
       const rule = ko
-        ? `"${t2.label}" 유형 요청은 기본적으로 ${t2.agent}(haiku) 서브에이전트로 위임한다(예: "${t2.example}"). ` +
+        ? `"${t2.label}" 유형 요청은 기본적으로 ${agentPhrase(t2.agent)} 서브에이전트로 위임한다(예: "${t2.example}"). ` +
           `여러 단계·여러 파일 수정이 얽힌 중간 난도 요청(예: "${t1.example}")은 model: sonnet 서브에이전트로 위임한다. ` +
           `설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이거나 위임 중 에러가 반복되면 위임하지 말고 메인 모델이 직접 처리한다`
-        : `Delegate "${t2.labelEn || t2.label}" requests to the ${t2.agent} (haiku) subagent by default (e.g. "${t2.example}"). ` +
+        : `Delegate "${t2.labelEn || t2.label}" requests to ${agentPhraseEn(t2.agent)} by default (e.g. "${t2.example}"). ` +
           `Escalate moderate ones that span multiple steps or file edits (e.g. "${t1.example}") to a model: sonnet subagent. ` +
           `Do not delegate at all — handle it on the main model — when the request mixes in design judgement or irreversible work (deploy, release, store submission), or when errors repeat during delegation`;
       lines.push(`- ${rule}${healthOf(t2)}${healthOf(t1)} <!-- T2 ${statsOf(t2)} / T1 ${statsOf(t1)} -->`);

package/src/route-scan.js

@@ -22,6 +22,7 @@ import { join } from 'node:path';
 import { userDataDir } from './paths.js';
 import { discoverSessionFiles } from './parser.js';
 import { collectSessionRecords } from './session-records.js';
+import { agentPhrase, agentPhraseEn } from './agents.js';
 
 // ── Tier bands (docs/TIER_CRITERIA.md §3) ────────────────────────────────
 // T2 (haiku): finished in few calls, tiny output, near-zero mutation, no
@@ -373,10 +374,10 @@ export async function runRouteScan({ days = 14 } = {}) {
   // switching `language` later re-renders (and promotes) correctly without
   // waiting for a rescan.
   const ruleText = (g) => g.tier === 'T2'
-    ? `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${g.agent}(haiku) 서브에이전트로 위임한다 (설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이면 위임하지 않음)`
+    ? `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${agentPhrase(g.agent)} 서브에이전트로 위임한다 (설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이면 위임하지 않음)`
     : `"${g.label}" 유형의 중간 난도 요청(예: "${g.example}")은 model: sonnet 서브에이전트로 위임한다 (설계 판단·비가역 작업·반복 에러 발생 시 메인 모델이 이어받음)`;
   const ruleTextEn = (g) => g.tier === 'T2'
-    ? `Delegate simple "${g.labelEn}" requests (e.g. "${g.example}") to the ${g.agent} (haiku) subagent — never when the request mixes in design judgement or irreversible work like deploy/release/submission`
+    ? `Delegate simple "${g.labelEn}" requests (e.g. "${g.example}") to ${agentPhraseEn(g.agent)} — never when the request mixes in design judgement or irreversible work like deploy/release/submission`
     : `Delegate moderate "${g.labelEn}" requests (e.g. "${g.example}") to a model: sonnet subagent — hand back to the main model on design judgement, irreversible work, or repeated errors`;
 
   const candidates = [...groups.values()]