claude-token-saver 3.6.3 → 3.7.0

package/README.en.md

@@ -243,6 +243,12 @@ 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.
+
 ### v3.6.3 (2026-07-27)
 - **Fixed: approved ratchet rules never reached the session** — `harness promote` appended rules to `ratchet.md`, but nothing ever read that file. Claude Code loads `CLAUDE.md` (plus whatever it imports) and the harness block carried no import line, so "approved rules apply automatically from the next session" was unimplemented. The block now imports `@.claude/ratchet.md` (project) / `@~/.claude/ratchet.md` (global). Re-running `harness init` upgrades an existing block in place.
 - **`ratchet-model.md` is imported explicitly too** — delegation rules now travel the same declared path instead of relying on a host that happens to pick the file up. To keep the import from dangling, `harness init` seeds an empty file and `syncAllFiles` empties rather than deletes a target that loses its last rule.

package/README.md

@@ -200,6 +200,12 @@ 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가 없을 때만 경고합니다.
+
 ### v3.6.3 (2026-07-27)
 - **승인한 ratchet 룰이 세션에 전달되지 않던 버그 수정** — `harness promote`는 룰을 `ratchet.md`에 append했지만, 그 파일을 읽는 소비자가 어디에도 없었습니다. Claude Code는 `CLAUDE.md`(와 그것이 import하는 파일)만 로드하는데 harness 블록에 import 라인이 없었기 때문에, "승인된 룰은 다음 세션부터 자동 적용"은 사실상 미구현 상태였습니다. 이제 harness 블록이 `@.claude/ratchet.md`(project) / `@~/.claude/ratchet.md`(global)를 import합니다. `harness init`을 다시 돌리면 기존 블록도 제자리에서 갱신됩니다.
 - **`ratchet-model.md`도 명시적으로 import** — 모델 피팅 룰도 호스트가 알아서 읽어주길 기대하지 않고 같은 경로로 전달합니다. import가 끊기지 않도록 `harness init`이 빈 파일을 미리 만들고, 마지막 룰이 사라져도 `syncAllFiles`가 파일을 지우는 대신 비웁니다.

package/package.json

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

@@ -153,15 +153,37 @@ function statusForFile(filePath) {
  *     relies on a globally-installed harness report 🅷 5/5 (covered by global),
  *     matching reality: Claude Code loads ~/.claude/CLAUDE.md for every project.
  * The returned `source` ('project'|'global') tells callers which file was used.
+ *
+ * The `@` import flags are the union of both files, not just the source one:
+ * Claude Code loads ~/.claude/CLAUDE.md for every project *and* the project
+ * CLAUDE.md, so a project-scope block with the imports living in the global
+ * file still gets the ratchet rules. Checking only the source file made that
+ * layout report a false `ratchet-unloaded`. `importSource` says which file
+ * actually carries them ('project' | 'global' | 'both' | null).
  */
 export function harnessStatus(root = findProjectRoot(), { scope = 'auto' } = {}) {
-  if (scope === 'project') return { ...statusForFile(claudeMdPath(root)), root, source: 'project' };
-  if (scope === 'global') return { ...statusForFile(globalClaudeMdPath()), root, source: 'global' };
   const project = statusForFile(claudeMdPath(root));
-  if (project.hasBlock) return { ...project, root, source: 'project' };
   const global = statusForFile(globalClaudeMdPath());
-  if (global.hasBlock) return { ...global, root, source: 'global' };
-  return { ...project, root, source: 'project' };
+  const pick = (s, source) => ({ ...s, ...unionImports(project, global), root, source });
+  if (scope === 'project') return pick(project, 'project');
+  if (scope === 'global') return pick(global, 'global');
+  if (project.hasBlock) return pick(project, 'project');
+  if (global.hasBlock) return pick(global, 'global');
+  return pick(project, 'project');
+}
+
+// Union the two files' import flags. Same file read twice (project root === ~)
+// is harmless — OR is idempotent.
+function unionImports(project, global) {
+  const samePath = project.file === global.file;
+  const g = samePath ? { hasRatchetImport: false, hasModelRatchetImport: false } : global;
+  const inProject = project.hasRatchetImport || project.hasModelRatchetImport;
+  const inGlobal = g.hasRatchetImport || g.hasModelRatchetImport;
+  return {
+    hasRatchetImport: project.hasRatchetImport || g.hasRatchetImport,
+    hasModelRatchetImport: project.hasModelRatchetImport || g.hasModelRatchetImport,
+    importSource: inProject && inGlobal ? 'both' : inProject ? 'project' : inGlobal ? 'global' : null,
+  };
 }
 
 /**

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()]