claude-token-saver 3.8.2 → 3.9.1

package/README.en.md

@@ -144,19 +144,21 @@ An auto `.bak` is kept, but **the session context that earned the rule its place
 
 ## 📦 compact-window — pin where a 1M session compacts
 
-Claude Code compacts when usage approaches `min(autoCompactWindow, model max context)`. On a 1M window, with that value unset, compaction only fires near 800k — and until then every request re-bills the whole context. Pinning 400k keeps twice a 200k session's headroom for the genuinely large pastes while cutting off the runaway tail.
+Claude Code compacts when usage approaches `min(autoCompactWindow, model max context)`. On a 1M window, with that value unset, compaction only fires near 800k — and until then every request re-bills the whole context. **1M is too large; the recommendation is a 400k–700k band** — 2–3.5x a 200k session's headroom for the genuinely large pastes, with the runaway tail cut off.
+
+**Anything inside the band is left alone.** 400k is the floor where the saving beats the extra compactions, and long sessions often want more room than that. Only an unset window, or one above 700k, is warned about (a smaller one is a deliberate, more aggressive choice).
 
 **200k sessions are never warned** — their window is already at or below 200k, so the setting cannot change anything.
 
 ```bash
 claude-token-saver compact-window                       # status (model, window, value, source)
-claude-token-saver compact-window set --global          # pin 400k in ~/.claude/settings.json
+claude-token-saver compact-window set --global          # pin 500k (mid-band) in ~/.claude/settings.json
 claude-token-saver compact-window set --project         # pin it in <root>/.claude/settings.json
-claude-token-saver compact-window set --global --value 250k   # explicit value (100k–1M)
+claude-token-saver compact-window set --global --value 600k   # explicit value (100k–1M)
 claude-token-saver compact-window off | on              # toggle the warning
 ```
 
-- On a 1M model with the value unset or above 400k, the statusline shows `🅷⚠ compact-window?` and the session briefing hands the model the exact registration command.
+- On a 1M model with the value unset or above 700k, the statusline shows `🅷⚠ compact-window?` and the session briefing hands the model the exact registration command.
 - Scope (`--global`/`--project`) is **required** for `set` — a global settings file is never edited on a guess.
 - Every other key in `settings.json` is preserved and a `.bak` is written first. Malformed JSON aborts the write untouched.
 - An exported `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats settings.json; `set` detects that and says so.
@@ -263,6 +265,18 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.9.1 (2026-08-01)
+- **compact-window now recommends a 400k–700k band instead of a single 400k** — 400k proved too tight in practice and compacted too often. The advice is a range now, and **a window inside it (or below it) is never warned about**; only an unset value or one above 700k raises `🅷⚠ compact-window?` and the briefing. `set` defaults to 500k (mid-band); pick your own with `--value 600k`.
+
+### v3.9.0 (2026-08-01)
+
+Compared this tool's design against manifest.build's "Everyone is building LLM routers, we deprecated ours" (a retrospective on 4 months across 7,000 users) and closed the four of their failure modes that were not already ruled out here. Full comparison in [TIER_CRITERIA.md §3.9](./docs/TIER_CRITERIA.md).
+
+- **rule-health now watches real delegations** — the old error rate's denominator was "episodes the expensive model handled directly that merely *looked* delegable by shape". It never measured whether a rule succeeded **when it actually fired**, so a rule could fail every single time without moving the signal. Claude Code writes each subagent run to `<session>/subagents/`, and its meta `toolUseId` joins exactly onto the parent's Task call — so the outcome of a real delegation is now counted directly. Once 5 measured runs accumulate, they replace the shape-based proxy, and the warning says which evidence it is using. (Author's 14-day log: 4 of 106 sessions, 18 runs, 100% join rate.)
+- **Per-rule savings** — the tokens a delegated run spent are re-priced at the session model's rate, and the difference is reported over the 14-day window as `~$` in `route-scan rules` and `ratchet-model.md`. You can only prune rules that aren't worth their keep if you can see which ones those are. A rule with no measured delegations shows `—`, not `$0` — the two mean opposite things.
+- **Tiers are now relative to the session model** — the only gate used to be "is it haiku?", so a Sonnet session produced T1 rules telling it to delegate to Sonnet: a subagent rebuilding context for zero price difference, which is a net loss. Candidates are now only created when the target tier is genuinely cheaper (haiku 0 · sonnet 1 · opus 2 · fable 3).
+- **Probe-then-commit budgets** — a rule is derived from statistics but **fires on the request text alone**, and most of what makes a task hard only shows up after the first tool call. That gap can't be closed, so the cost of getting it wrong is capped instead: every rule now carries a calibrated limit (T2: 8 tool calls / p25 output, T1: p75 output), and a run likely to exceed it — or hitting an error — stops there, reports partial progress, and hands back to the main model. The clause is composed at render time rather than baked into the stored rule, so **rules promoted before this release get it too**, and the promote preview can never drift from what lands in the file.
+
 ### v3.8.2 (2026-08-01)
 - **Fixed: the context tier never came back down after compaction** — the tier was kept as a high-water mark, so a session that compacted at 80% stayed at tier 1 even though its context had just been emptied, and it refilled to the cap with no signal at all. The tier now follows the measurement down and warns again on the next climb.
 - **Both windows are named** — with `autoCompactWindow` at 400k the briefing measured against 400k (80%) while Claude Code's own display measured against 1M (33%); two irreconcilable numbers for one session. The text now reads `자동 압축 창(400k)의 80% (… 화면의 1M 창 기준으로는 33%)`.

package/README.md

@@ -125,15 +125,17 @@ ratchet의 가치는 **한 방향 누적**에 있습니다. 룰을 가볍게 지
 
 ## 📦 compact-window — 1M 컨텍스트의 자동 압축 지점 고정
 
-Claude Code는 `min(autoCompactWindow, 모델 최대 창)`에 가까워지면 대화를 자동 압축합니다. 1M 창을 쓰면 이 값이 잡혀 있지 않은 한 80만 토큰 근처까지 가서야 압축이 걸리고, 그전까지 모든 요청이 전체 컨텍스트를 통째로 재과금합니다. 40만으로 고정하면 큰 붙여넣기용 여유는 200k 세션의 두 배로 남기면서 꼬리만 잘라냅니다.
+Claude Code는 `min(autoCompactWindow, 모델 최대 창)`에 가까워지면 대화를 자동 압축합니다. 1M 창을 쓰면 이 값이 잡혀 있지 않은 한 80만 토큰 근처까지 가서야 압축이 걸리고, 그전까지 모든 요청이 전체 컨텍스트를 통째로 재과금합니다. **1M은 너무 크니 40만~70만 범위를 권장합니다** — 큰 붙여넣기용 여유는 200k 세션의 2~3.5배로 남기면서 꼬리만 잘라냅니다.
+
+**권장 범위 안이면 경고하지 않습니다.** 40만은 절감이 압축 횟수를 이기는 하한이고, 긴 세션은 그보다 여유가 더 필요한 경우가 많습니다. 미설정이거나 70만을 넘을 때만 알립니다(그보다 낮게 잡은 건 더 공격적으로 아끼겠다는 선택이라 그냥 둡니다).
 
 **200k 컨텍스트는 경고 대상이 아닙니다** — 창이 이미 200k 이하라 이 설정이 바꿀 게 없습니다.
 
 ```bash
 claude-token-saver compact-window                       # 현재 상태 (모델·창·설정값·출처)
-claude-token-saver compact-window set --global          # ~/.claude/settings.json 에 40만 고정
+claude-token-saver compact-window set --global          # ~/.claude/settings.json 에 50만 고정 (범위 중간)
 claude-token-saver compact-window set --project         # <root>/.claude/settings.json 에 고정
-claude-token-saver compact-window set --global --value 250k   # 값 직접 지정 (10만~1M)
+claude-token-saver compact-window set --global --value 600k    # 값 직접 지정 (10만~1M)
 claude-token-saver compact-window off | on              # 경고 표시 토글
 ```
 
@@ -220,6 +222,18 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.9.1 (2026-08-01)
+- **compact-window 권장값이 단일 40만에서 40만~70만 범위로** — 40만은 실사용에서 너무 빡빡해 압축이 잦았습니다. 이제 범위를 제안하고, **그 안(또는 그보다 낮게) 잡아둔 세션은 경고하지 않습니다.** 미설정이거나 70만 초과일 때만 `🅷⚠ compact-window?`와 브리핑이 뜹니다. `set`의 기본값도 범위 중간인 50만으로 올렸고, 원하는 값은 `--value 600k`로 지정합니다.
+
+### v3.9.0 (2026-08-01)
+
+manifest.build의 "다들 LLM 라우터 만드는데 우리는 폐기했다"(7천 사용자·4개월 실사용 회고)와 이 도구의 설계를 대조해, 그쪽 실패 요인 중 아직 안 막혀 있던 것 4개를 메웠습니다. 자세한 대조는 [TIER_CRITERIA.md §3.9](./docs/TIER_CRITERIA.md).
+
+- **rule-health가 이제 실제 위임 결과를 봅니다** — 기존 에러율의 분모는 "비싼 모델이 직접 처리했는데 형태상 위임 가능해 보이던 에피소드"였습니다. 즉 룰이 **실제로 발동했을 때 잘 됐는지는 한 번도 재지 않았고**, 매번 실패하는 룰이 있어도 신호가 안 움직였습니다. Claude Code가 서브에이전트 실행을 `<세션>/subagents/`에 따로 남기고 그 메타의 `toolUseId`가 부모의 Task 호출과 정확히 맞물리므로, 이제 실제 위임의 성패를 직접 셉니다. 실측 5건 이상 쌓인 룰은 추정 대신 실측으로 판정하고, 경고에도 어느 쪽 근거인지 표시합니다. (저자 로그 14일: 106세션 중 4세션·18런, 조인 성공률 100%)
+- **룰별 절감액 표시** — 위임 실행의 토큰을 세션 모델 단가로 되돌린 차액을 14일 창으로 계산해 `route-scan rules`와 `ratchet-model.md`에 `~$` 표기로 붙입니다. 값어치 없는 룰이 눈에 보여야 정리할 수 있습니다. 위임 기록이 없는 룰은 `$0`이 아니라 `—` — 둘은 정반대를 뜻합니다.
+- **세션 모델 기준 상대 티어** — 기존 게이트가 "haiku인가?" 하나뿐이라, Sonnet 세션에서도 "sonnet한테 위임하라"는 T1 룰이 만들어졌습니다. 컨텍스트만 새로 쌓고 단가 차이는 0인 순손해입니다. 이제 목표 티어가 실제로 더 싼 경우에만 후보를 만듭니다 (haiku 0 · sonnet 1 · opus 2 · fable 3).
+- **위임 예산 문구(probe-then-commit)** — 룰은 통계로 만들어지지만 **발동은 요청 텍스트만 보고** 일어나고, 난이도는 대개 첫 도구 호출 뒤에야 드러납니다. 이 불일치는 못 없애니 오판 비용에 상한을 겁니다: 각 룰에 캘리브레이션된 상한(T2는 호출 8회·출력 p25, T1은 출력 p75)이 붙고, 넘길 것 같거나 에러가 나면 서브에이전트가 멈춰 진행분만 보고하고 메인 모델이 이어받습니다. 문구는 저장된 룰에 굽지 않고 렌더 시점에 조립하므로 **예전에 등록한 룰도 자동으로 적용**받고, promote 프리뷰와 실제 파일이 어긋날 수 없습니다.
+
 ### v3.8.2 (2026-08-01)
 - **압축 뒤에도 경고 티어가 안 내려가던 문제 수정** — 컨텍스트 티어를 최고치로만 기억해서, 80%에서 자동 압축이 돌아 컨텍스트가 다시 비어도 티어가 1로 남았습니다. 그 세션은 창을 다시 꽉 채워도 아무 신호를 못 받았습니다. 이제 측정치가 내려가면 티어도 같이 내려가고, 다시 차오르면 정상적으로 경고합니다.
 - **두 가지 창 표기 혼선 정리** — `autoCompactWindow`를 40만으로 잡으면 브리핑은 40만 기준(80%)인데 Claude Code 화면은 1M 기준(33%)이라, 같은 세션의 두 숫자가 서로 안 맞아 보였습니다. 이제 `자동 압축 창(400k)의 80%(… 화면의 1M 창 기준으로는 33%)`처럼 둘 다 적습니다.

package/package.json

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

package/src/brief.js

@@ -246,7 +246,7 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
         briefed.add(sig);
         s.briefed = [...briefed];
         const now = st.window ? `현재 ${fmtK(st.window)}` : '현재 미설정';
-        items.push(`1M 컨텍스트 모델(${st.model})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 40만으로 고정하면 1M 창은 그대로 두고 압축 시점만 앞당깁니다. 등록: claude-token-saver compact-window set --global|--project (적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
+        items.push(`1M 컨텍스트 모델(${st.model})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmtK(st.recommendedMin)}~${fmtK(st.recommendedMax)} 범위를 권장합니다(그 범위 안이면 경고하지 않습니다). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다. 등록: claude-token-saver compact-window set --global|--project [--value ${fmtK(st.recommendedMax)}] (기본 ${fmtK(st.recommended)}, 적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
       }
     }
   } catch { /* settings unreadable — other briefings above still apply */ }

package/src/commands/compact-window.js

@@ -1,9 +1,9 @@
 /**
  * Subcommand: compact-window — audit / pin Claude Code's `autoCompactWindow`.
  *   claude-token-saver compact-window                      # status
- *   claude-token-saver compact-window set --global         # pin 400k in ~/.claude/settings.json
- *   claude-token-saver compact-window set --project        # pin 400k in <root>/.claude/settings.json
- *   claude-token-saver compact-window set --global --value 250k
+ *   claude-token-saver compact-window set --global         # pin 500k in ~/.claude/settings.json
+ *   claude-token-saver compact-window set --project        # pin 500k in <root>/.claude/settings.json
+ *   claude-token-saver compact-window set --global --value 600k
  *   claude-token-saver compact-window off | on             # toggle the statusline warning
  *
  * Scope is deliberately explicit for `set`: writing a global settings.json is
@@ -69,22 +69,25 @@ export async function run({ args, hasFlag }) {
       return;
     }
     if (s.ok) {
-      console.log(ko ? '\n✅ 압축 창이 400k 이하로 고정돼 있습니다.' : '\n✅ Compaction window is pinned at or below 400k.');
+      console.log(ko
+        ? `\n✅ 압축 창이 권장 범위(${fmt(s.recommendedMin)}~${fmt(s.recommendedMax)}) 상한 이하입니다.`
+        : `\n✅ Compaction window is at or below the top of the recommended ${fmt(s.recommendedMin)}–${fmt(s.recommendedMax)} band.`);
       return;
     }
     console.log(ko
       ? `\n⚠ 1M 컨텍스트인데 autoCompactWindow가 ${s.reason === 'unset' ? '설정되지 않았습니다' : `${fmt(s.window)}로 너무 큽니다`} — 자동 압축이 80만 토큰 근처에서야 걸립니다.`
       : `\n⚠ 1M context with autoCompactWindow ${s.reason === 'unset' ? 'unset' : `at ${fmt(s.window)}`} — compaction only fires near 800k.`);
     console.log(ko
-      ? '  그 전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 40만으로 고정하면 1M 창은 유지하면서 압축 시점만 앞당깁니다.'
-      : '  Until then every request re-bills the whole context. Pinning 400k keeps the 1M window while capping the runaway tail.');
-    console.log('\n  claude-token-saver compact-window set --global     (~/.claude/settings.json)');
-    console.log('  claude-token-saver compact-window set --project    (<root>/.claude/settings.json)');
+      ? `  그 전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmt(s.recommendedMin)}~${fmt(s.recommendedMax)} 범위를 권장합니다 (기본값 ${fmt(s.recommended)}, --value로 조절). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다.`
+      : `  Until then every request re-bills the whole context. 1M is too large — pick something in ${fmt(s.recommendedMin)}–${fmt(s.recommendedMax)} (default ${fmt(s.recommended)}, override with --value). The 1M window itself stays.`);
+    console.log(`\n  claude-token-saver compact-window set --global     (~/.claude/settings.json, ${fmt(s.recommended)})`);
+    console.log(`  claude-token-saver compact-window set --project    (<root>/.claude/settings.json, ${fmt(s.recommended)})`);
+    console.log(`  claude-token-saver compact-window set --global --value ${fmt(s.recommendedMax)}`);
     console.log(ko ? '  (적용 범위는 사용자에게 먼저 확인할 것)' : '  (confirm the scope with the user first)');
     return;
   }
 
   console.error(`Unknown compact-window subcommand: ${sub}`);
-  console.error('Usage: claude-token-saver compact-window [status|set --global|--project [--value 400k]|off|on]');
+  console.error('Usage: claude-token-saver compact-window [status|set --global|--project [--value 500k]|off|on]');
   process.exit(1);
 }

package/src/commands/harness.js

@@ -228,6 +228,9 @@ export async function run({ args, hasFlag }) {
           rule: lang === 'ko' ? routeCandidate.rule : (routeCandidate.ruleEn || routeCandidate.rule),
           example: routeCandidate.example,
           count: routeCandidate.count,
+          // Calibrated budget snapshot — ratchet-model.md restates it when it
+          // merges a category's T2 and T1 rules into one conditional rule.
+          budget: routeCandidate.budget || null,
           promotedAt: new Date().toISOString().slice(0, 10),
           lastSeen: new Date().toISOString().slice(0, 10),
         });

package/src/commands/route-scan.js

@@ -40,7 +40,18 @@ export async function run({ args, hasFlag, numArg }) {
           ? `${r.tier} (${rs.tierLabel(r.tier)}) · ${rs.scopeLabel(r.scope)} · 반복 ${r.count || 0}회 · 에러율 ${Math.round((r.errRate || 0) * 100)}%`
           : `${r.tier} (${rs.tierLabel(r.tier, 'en')}) · ${rs.scopeLabel(r.scope, 'en')} · seen ×${r.count || 0} · err ${Math.round((r.errRate || 0) * 100)}%`;
         console.log(`  #${i + 1} ${stat}${health}`);
-        console.log(`      ${r.rule}`);
+        // Measured outcome of the rule actually firing, plus what it saved.
+        // A rule with no measured delegations shows "—", never "$0.00": the
+        // two mean opposite things (no data vs. data showing no value).
+        const measured = r.delegatedRuns
+          ? (lang === 'ko'
+            ? `실제 위임 ${r.delegatedRuns}건 · 에러율 ${Math.round((r.delegatedErrRate || 0) * 100)}% · 절감 ~$${(r.savedUsd || 0).toFixed(2)}`
+            : `measured ×${r.delegatedRuns} · err ${Math.round((r.delegatedErrRate || 0) * 100)}% · saved ~$${(r.savedUsd || 0).toFixed(2)}`)
+          : (lang === 'ko' ? '실제 위임 기록 — (아직 없음)' : 'measured delegations — (none yet)');
+        console.log(`      ${measured}`);
+        // Same composer the md file uses, so what is listed here is exactly
+        // what the model reads.
+        console.log(`      ${mr.composeRuleText(r.rule, r, lang)}`);
       });
       console.log(lang === 'ko'
         ? '\n제거: claude-token-saver route-scan rules rm <N>'
@@ -79,12 +90,17 @@ export async function run({ args, hasFlag, numArg }) {
         } catch (e) { debug('route-scan:spawn-refresh', e); /* stale cache is still usable below */ }
       }
       const open = rs.openCandidates(cache);
+      // Rule text shown to the model must be composed the same way the md file
+      // composes it, budget clause included — otherwise the briefing promises
+      // one rule and the file carries another.
+      const mrHook = await import('../model-rules.js');
+      const composed = (base, c) => mrHook.composeRuleText(base, c, lang);
       // Registered rules whose delegated-category error rate crossed the
       // health threshold since promotion — the user approved these, so a
       // status change must be briefed, not just written into the md file.
       let reviewRules = [];
       try {
-        const mr = await import('../model-rules.js');
+        const mr = mrHook;
         reviewRules = mr.loadModelRules().rules
           .map((r, i) => ({ ...r, n: i + 1 }))
           .filter((r) => r.status === 'review');
@@ -105,7 +121,7 @@ export async function run({ args, hasFlag, numArg }) {
         for (const c of open) {
           const tier = c.tier || 'T2';
           const label = lang === 'ko' ? c.label : (c.labelEn || c.label);
-          const rule = lang === 'ko' ? c.rule : (c.ruleEn || c.rule);
+          const rule = composed(lang === 'ko' ? c.rule : (c.ruleEn || c.rule), c);
           if (lang === 'ko') {
             lines.push(`  후보 R${c.id} — "${label}" 유형, ${c.count}회 반복 (프로젝트: ${c.project})`);
             lines.push(`      판정: ${tier} (${rs.tierLabel(tier)}) → ${c.agent} 서브에이전트 위임 권장 · 적용 범위 제안: ${rs.scopeLabel(c.suggestedScope)}`);
@@ -133,9 +149,17 @@ export async function run({ args, hasFlag, numArg }) {
           ? '[claude-token-saver rule-health] 사용자가 승인한 위임 룰 중, 위임 대상 유형의 최근 에러율이 기준(20%)을 넘어 재검토가 필요한 룰이 있습니다 — 사용자에게 브리핑하고 조건 좁히기/제거를 상의하세요:'
           : '[claude-token-saver rule-health] Some user-approved delegation rules now exceed the 20% error-rate threshold for their delegated category — brief the user and discuss narrowing or removing them:');
         for (const r of reviewRules) {
+          // Say WHICH signal tripped: a measured delegation failure rate is a
+          // much stronger claim than the shape-based proxy, and the user's
+          // decision (narrow vs. remove) depends on knowing which it is.
+          const measured = r.healthSource === 'delegated';
+          const rate = Math.round(((measured ? r.delegatedErrRate : r.errRate) || 0) * 100);
+          const evidence = lang === 'ko'
+            ? (measured ? `실제 위임 ${r.delegatedRuns}건 실측 에러율 ${rate}%` : `유형 에러율 ${rate}% (형태 기반 추정)`)
+            : (measured ? `${rate}% measured across ${r.delegatedRuns} real delegations` : `${rate}% for the category (shape-based proxy)`);
           lines.push(lang === 'ko'
-            ? `  룰 #${r.n} (${r.tier} ${rs.tierLabel(r.tier)} · ${rs.scopeLabel(r.scope)}) — 최근 에러율 ${Math.round((r.errRate || 0) * 100)}%`
-            : `  rule #${r.n} (${r.tier} ${rs.tierLabel(r.tier, 'en')} · ${rs.scopeLabel(r.scope, 'en')}) — recent error rate ${Math.round((r.errRate || 0) * 100)}%`);
+            ? `  룰 #${r.n} (${r.tier} ${rs.tierLabel(r.tier)} · ${rs.scopeLabel(r.scope)}) — ${evidence}`
+            : `  rule #${r.n} (${r.tier} ${rs.tierLabel(r.tier, 'en')} · ${rs.scopeLabel(r.scope, 'en')}) — ${evidence}`);
           lines.push(`      "${r.rule}"`);
         }
         lines.push(lang === 'ko'
@@ -191,7 +215,9 @@ export async function run({ args, hasFlag, numArg }) {
         console.log(`       verdict: ${tier} (${rs.tierLabel(tier, 'en')}) → delegate to ${c.agent} · suggested scope: ${rs.scopeLabel(c.suggestedScope, 'en')}`);
       }
       console.log(`       ${lang === 'ko' ? '예시' : 'example'}: "${c.example}"`);
-      console.log(`       ${lang === 'ko' ? '룰' : 'rule'}: ${lang === 'ko' ? c.rule : (c.ruleEn || c.rule)}`);
+      const mrList = await import('../model-rules.js');
+      const base = lang === 'ko' ? c.rule : (c.ruleEn || c.rule);
+      console.log(`       ${lang === 'ko' ? '룰' : 'rule'}: ${mrList.composeRuleText(base, c, lang)}`);
     }
     console.log('');
     console.log(lang === 'ko' ? '등록 / 무시:' : 'Promote / dismiss:');

package/src/compact-window.js

@@ -5,8 +5,13 @@
  * `min(settings.autoCompactWindow, model max context)`. On a 1M window the
  * default lets a session grow past 800k before compaction ever fires, so every
  * later request re-bills a context most sessions never needed. Pinning
- * `autoCompactWindow: 400000` keeps twice the headroom of a 200k session for
- * the genuinely large ones while capping the runaway tail.
+ * `autoCompactWindow` somewhere in 400k–700k keeps 2–3.5x the headroom of a
+ * 200k session for the genuinely large ones while capping the runaway tail.
+ *
+ * The recommendation is a range, not a number: 400k is the floor where the
+ * saving is worth the extra compactions, and in practice long sessions often
+ * want more room than that. Anything at or below 700k is left alone — only an
+ * unset window, or one above 700k, is a real config defect.
  *
  * 200k sessions are exempt by design: their window is already <= 200k, so the
  * setting changes nothing and a warning would be pure noise.
@@ -28,7 +33,13 @@ import { debug } from './debug.js';
 // the app would honor.
 export const MIN_WINDOW = 100_000;
 export const MAX_WINDOW = 1_000_000;
-export const RECOMMENDED_WINDOW = 400_000;
+// Recommended band. Warn only outside it on the high side (or when unset) —
+// a window below RECOMMENDED_MIN is a deliberate, more aggressive choice and
+// costs nothing, so it stays silent.
+export const RECOMMENDED_MIN = 400_000;
+export const RECOMMENDED_MAX = 700_000;
+// What `compact-window set` writes when no --value is given: middle of the band.
+export const RECOMMENDED_WINDOW = 500_000;
 
 // A model id whose context is the 1M variant. Claude Code spells it as a
 // suffix on the model id (`claude-opus-5[1m]`); the beta header form
@@ -116,10 +127,10 @@ export function effectiveWindow(root) {
 /**
  * Full audit result. `ok` is true when there is nothing to warn about — either
  * the session is not on a 1M model (exempt), or the window is already pinned at
- * or below the recommended 400k.
+ * or below the top of the recommended band (700k).
  *
  * `reason` names why it is not ok: 'unset' (no autoCompactWindow anywhere) or
- * 'too-large' (set, but above 400k — still lets context run away).
+ * 'too-large' (set, but above 700k — still lets context run away).
  */
 export function compactWindowStatus({ root = process.cwd() } = {}) {
   const { model, source: modelSource } = resolveModelId(root);
@@ -133,10 +144,12 @@ export function compactWindowStatus({ root = process.cwd() } = {}) {
     windowSource: win.source,
     windowPath: win.path || null,
     recommended: RECOMMENDED_WINDOW,
+    recommendedMin: RECOMMENDED_MIN,
+    recommendedMax: RECOMMENDED_MAX,
   };
   if (!is1m) return { ...base, ok: true, reason: 'not-1m' };
   if (win.value === null) return { ...base, ok: false, reason: 'unset' };
-  if (win.value > RECOMMENDED_WINDOW) return { ...base, ok: false, reason: 'too-large' };
+  if (win.value > RECOMMENDED_MAX) return { ...base, ok: false, reason: 'too-large' };
   return { ...base, ok: true, reason: 'configured' };
 }
 

package/src/cost.js

@@ -100,6 +100,45 @@ function detectPricingTier(model) {
   return 'claude-sonnet';
 }
 
+/**
+ * Relative price rank of a model's pricing tier. Delegation only pays off
+ * when the target tier is genuinely cheaper than the model that did the work,
+ * so route-scan needs an ORDER, not just "is it haiku?" — a Sonnet session
+ * must not produce "delegate to Sonnet" rules (the subagent would rebuild
+ * context for zero price difference).
+ */
+const TIER_RANK = {
+  'claude-fable-5': 3,
+  'claude-opus-legacy': 2,
+  'claude-opus-new': 2,
+  'claude-sonnet': 1,
+  'claude-haiku-4-5': 0,
+  'claude-haiku-3-5': 0,
+  'claude-haiku-3': 0,
+};
+
+export function modelRank(model) {
+  const rank = TIER_RANK[detectPricingTier(model)];
+  // Unknown ids fall through detectPricingTier to the Sonnet tier; ranking
+  // them 1 keeps the conservative reading (cheap enough that a Sonnet-target
+  // rule is not worth it, expensive enough that a haiku one still is).
+  return rank ?? 1;
+}
+
+/** Price rank each delegation tier targets: T2 → haiku, T1 → sonnet. */
+export const TIER_TARGET_RANK = { T2: 0, T1: 1 };
+
+/**
+ * Which delegation tier a subagent run at this price rank represents.
+ * null = the run was NOT a downgrade (same tier or higher), so it carries no
+ * delegation saving to attribute to a rule.
+ */
+export function tierForRank(rank) {
+  if (rank === 0) return 'T2';
+  if (rank === 1) return 'T1';
+  return null;
+}
+
 function tokensToMillions(n) {
   return n / 1_000_000;
 }

package/src/model-rules.js

@@ -42,6 +42,46 @@ export const HEALTH_ERR_RATE = 0.2;
 // noise (1 error in 4 episodes = 25% — instant flag), so the review flag is
 // withheld until the sample is large enough to mean something.
 export const HEALTH_MIN_SAMPLE = 10;
+// Measured delegations needed before the real outcome replaces the proxy.
+// Lower than HEALTH_MIN_SAMPLE on purpose: a delegated run is DIRECT evidence
+// of the rule firing, so far fewer are needed to mean something than episodes
+// that merely resemble the rule's shape.
+export const HEALTH_MIN_SAMPLE_DELEGATED = 5;
+
+// Fallback budget for rules promoted before budgets were recorded — matches
+// route-scan's pre-calibration defaults. Kept as local constants rather than
+// imported: route-scan imports this module, and a static back-import would
+// close the cycle.
+const DEFAULT_BUDGET = { T2: { calls: 8, out: 1500 }, T1: { calls: null, out: 8000 } };
+
+/** The cap half of a budget clause, e.g. "도구 호출 8회·출력 1500 토큰". */
+export function budgetCapPhrase(rule, lang = userLanguage()) {
+  const b = rule.budget || DEFAULT_BUDGET[rule.tier] || DEFAULT_BUDGET.T2;
+  if (lang === 'ko') {
+    return b.calls ? `도구 호출 ${b.calls}회·출력 ${b.out} 토큰` : `출력 ${b.out} 토큰`;
+  }
+  return b.calls ? `${b.calls} tool calls / ${b.out} output tokens` : `${b.out} output tokens`;
+}
+
+/**
+ * Append the probe-then-commit budget to a rule's text.
+ *
+ * Kept here — not baked into the stored rule string — so it is composed in ONE
+ * place: rules promoted before budgets existed gain the clause too, and the
+ * promote preview and the written file can never drift apart (both call this).
+ *
+ * Why the clause matters: a rule is chosen from past statistics but FIRES on
+ * the request text alone, and difficulty mostly surfaces after the first tool
+ * call. Naming a cap turns an unavoidable mis-fire into a bounded probe
+ * instead of a cheap model grinding at work it cannot finish.
+ */
+export function composeRuleText(baseText, rule, lang = userLanguage()) {
+  const cap = budgetCapPhrase(rule, lang);
+  const clause = lang === 'ko'
+    ? `위임 상한은 ${cap}이며, 넘길 것 같거나 에러가 나면 거기서 멈춰 진행분만 보고하고 메인 모델이 이어받는다. 세션 모델이 이미 위임 목표와 같은 급 이하면 위임하지 않는다`
+    : `Cap the run at ${cap}; if it looks likely to exceed that or hits an error, it stops there and reports partial progress while the main model takes over. Skip delegation entirely when the session model is already at or below the target tier`;
+  return `${baseText.replace(/\s*$/, '')}. ${clause}`;
+}
 
 // See the note in route-scan.js — paths.js is the only place that resolves
 // this, so an XDG_CONFIG_HOME override moves every state file together.
@@ -124,10 +164,34 @@ export function renderModelRatchet(rules, lang = userLanguage()) {
     '## Rules',
     '',
   ];
-  const healthOf = (r) => r.status !== 'review' ? '' : (ko
-    ? ` ⚠ rule-health: 최근 위임 대상 에러율 ${Math.round((r.errRate || 0) * 100)}% — 조건을 좁히거나 제거 검토`
-    : ` ⚠ rule-health: recent error rate ${Math.round((r.errRate || 0) * 100)}% for the delegated category — narrow the condition or remove`);
-  const statsOf = (r) => `×${r.count || 0}, err ${Math.round((r.errRate || 0) * 100)}%, seen ${r.lastSeen || r.promotedAt}`;
+  // Which number drove the review flag matters to the reader: a measured
+  // delegated error rate is evidence the rule itself is failing, while the
+  // proxy only says work of that shape tends to go wrong.
+  const pct = (v) => Math.round((v || 0) * 100);
+  const healthOf = (r) => {
+    if (r.status !== 'review') return '';
+    const measured = r.healthSource === 'delegated';
+    const rate = pct(measured ? r.delegatedErrRate : r.errRate);
+    if (ko) {
+      return measured
+        ? ` ⚠ rule-health: 실제 위임 ${r.delegatedRuns}건 중 에러율 ${rate}% — 조건을 좁히거나 제거 검토`
+        : ` ⚠ rule-health: 최근 위임 대상 에러율 ${rate}% — 조건을 좁히거나 제거 검토`;
+    }
+    return measured
+      ? ` ⚠ rule-health: ${rate}% error rate across ${r.delegatedRuns} measured delegations — narrow the condition or remove`
+      : ` ⚠ rule-health: recent error rate ${rate}% for the delegated category — narrow the condition or remove`;
+  };
+  const statsOf = (r) => {
+    const base = `×${r.count || 0}, err ${pct(r.errRate)}%, seen ${r.lastSeen || r.promotedAt}`;
+    if (!r.delegatedRuns) return base;
+    const saved = r.savedUsd ? `, saved ~$${r.savedUsd.toFixed(2)}` : '';
+    return `${base}, delegated ×${r.delegatedRuns} err ${pct(r.delegatedErrRate)}%${saved}`;
+  };
+  // Merged T2+T1 rules carry two caps, so they state both once rather than
+  // repeating the whole stop-condition per tier.
+  const mergedBudget = (t2, t1) => ko
+    ? `위임 상한은 haiku ${budgetCapPhrase(t2, 'ko')}, sonnet ${budgetCapPhrase(t1, 'ko')}이며, 넘길 것 같거나 에러가 나면 거기서 멈춰 진행분만 보고하고 메인 모델이 이어받는다. 세션 모델이 이미 위임 목표와 같은 급 이하면 위임하지 않는다`
+    : `Cap haiku runs at ${budgetCapPhrase(t2, 'en')} and sonnet runs at ${budgetCapPhrase(t1, 'en')}; a run likely to exceed its cap, or hitting an error, stops there and reports partial progress while the main model takes over. Skip delegation entirely when the session model is already at or below the target tier`;
 
   // A category can carry both a T2 (haiku) and a T1 (sonnet) rule. Tier is
   // only known after an episode finishes, so two separate bullets give the
@@ -147,16 +211,18 @@ export function renderModelRatchet(rules, lang = userLanguage()) {
       const rule = ko
         ? `"${t2.label}" 유형 요청은 기본적으로 ${agentPhrase(t2.agent)} 서브에이전트로 위임한다(예: "${t2.example}"). ` +
           `여러 단계·여러 파일 수정이 얽힌 중간 난도 요청(예: "${t1.example}")은 model: sonnet 서브에이전트로 위임한다. ` +
-          `설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이거나 위임 중 에러가 반복되면 위임하지 말고 메인 모델이 직접 처리한다`
+          `설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이거나 위임 중 에러가 반복되면 위임하지 말고 메인 모델이 직접 처리한다. ` +
+          mergedBudget(t2, t1)
         : `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`;
+          `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. ` +
+          mergedBudget(t2, t1);
       lines.push(`- ${rule}${healthOf(t2)}${healthOf(t1)} <!-- T2 ${statsOf(t2)} / T1 ${statsOf(t1)} -->`);
       for (const r of group) {
-        if (r !== t2 && r !== t1) lines.push(`- ${r.rule}${healthOf(r)} <!-- ${statsOf(r)} -->`);
+        if (r !== t2 && r !== t1) lines.push(`- ${composeRuleText(r.rule, r, lang)}${healthOf(r)} <!-- ${statsOf(r)} -->`);
       }
     } else {
-      for (const r of group) lines.push(`- ${r.rule}${healthOf(r)} <!-- ${statsOf(r)} -->`);
+      for (const r of group) lines.push(`- ${composeRuleText(r.rule, r, lang)}${healthOf(r)} <!-- ${statsOf(r)} -->`);
     }
   }
   return lines.join('\n') + '\n';
@@ -229,17 +295,51 @@ export function syncAllFiles({ previousPaths = [] } = {}) {
  * an expensive model handled directly that still look T1/T2 by shape (tier
  * judged with the error signal zeroed; see route-scan's rule-health pass).
  */
-export function refreshModelRules(episodeStats, { now } = {}) {
+export function refreshModelRules(episodeStats, delegatedStats = new Map(), { now } = {}) {
   const data = loadModelRules();
   let changed = false;
+  const pick = (stats, r) => stats.get(`${r.tier}|${r.category}|${r.project}`)
+    || (r.scope === 'global' ? stats.get(`${r.tier}|${r.category}|*`) : null);
+
   for (const r of data.rules) {
-    const s = episodeStats.get(`${r.tier}|${r.category}|${r.project}`)
-      || (r.scope === 'global' ? episodeStats.get(`${r.tier}|${r.category}|*`) : null);
-    if (!s) continue;
-    r.count = s.count;
-    r.errRate = s.epCount > 0 ? s.errCount / s.epCount : 0;
+    const s = pick(episodeStats, r);
+    const d = pick(delegatedStats, r);
+    if (!s && !d) {
+      // A rule whose category didn't appear at all this window keeps its last
+      // known recurrence, but its measured-delegation fields must still read
+      // as "nothing measured" rather than stay undefined — the CLI and the
+      // rendered md both branch on them.
+      r.delegatedRuns = r.delegatedRuns ?? 0;
+      r.delegatedErrRate = r.delegatedErrRate ?? 0;
+      r.savedUsd = r.savedUsd ?? 0;
+      r.healthSource = r.healthSource ?? 'proxy';
+      continue;
+    }
+
+    if (s) {
+      r.count = s.count;
+      r.errRate = s.epCount > 0 ? s.errCount / s.epCount : 0;
+    }
+    // Window snapshot, not a running total: these describe the current scan
+    // window so a rule that stopped firing decays to zero instead of coasting
+    // on old credit.
+    r.delegatedRuns = d ? d.runs : 0;
+    r.delegatedErrRate = d && d.runs > 0 ? d.errRuns / d.runs : 0;
+    r.savedUsd = d ? Math.round(d.savedUsd * 100) / 100 : 0;
     r.lastSeen = now || r.lastSeen;
-    r.status = r.errRate > HEALTH_ERR_RATE && s.epCount >= HEALTH_MIN_SAMPLE ? 'review' : 'active';
+
+    // Measured outcome beats the proxy once there is enough of it. The proxy
+    // asks "does work SHAPED like this tend to fail?"; the measurement asks
+    // "does this rule fail when it actually fires?" — only the second can
+    // catch a rule that is mis-firing on requests it should never have taken.
+    if (r.delegatedRuns >= HEALTH_MIN_SAMPLE_DELEGATED) {
+      r.healthSource = 'delegated';
+      r.status = r.delegatedErrRate > HEALTH_ERR_RATE ? 'review' : 'active';
+    } else {
+      r.healthSource = 'proxy';
+      r.status = s && r.errRate > HEALTH_ERR_RATE && s.epCount >= HEALTH_MIN_SAMPLE
+        ? 'review' : 'active';
+    }
     changed = true;
   }
   if (changed) {

package/src/route-scan.js

@@ -22,6 +22,8 @@ import { join } from 'node:path';
 import { userDataDir } from './paths.js';
 import { discoverSessionFiles } from './parser.js';
 import { collectSessionRecords } from './session-records.js';
+import { collectSubagentRuns, indexRuns, runsForEpisode } from './subagent-records.js';
+import { estimateCost, modelRank, TIER_TARGET_RANK, tierForRank } from './cost.js';
 import { agentPhrase, agentPhraseEn } from './agents.js';
 
 // ── Tier bands (docs/TIER_CRITERIA.md §3) ────────────────────────────────
@@ -211,7 +213,13 @@ function toEpisodes(records) {
   for (const r of records) {
     const text = (r.userText || '').trim();
     if (!cur || cur.text !== text) {
-      cur = { text, calls: 0, out: 0, mutating: 0, errors: 0, delegated: 0, models: new Set(), cwd: '', tools: {} };
+      cur = {
+        text, calls: 0, out: 0, mutating: 0, errors: 0, delegated: 0,
+        models: new Set(), cwd: '', tools: {},
+        // Delegation attribution (subagent-records): exact join key, plus the
+        // episode's time span for the fallback when a run has no meta file.
+        delegationToolUseIds: [], startedAt: null, endedAt: null,
+      };
       episodes.push(cur);
     }
     cur.calls += 1;
@@ -222,14 +230,61 @@ function toEpisodes(records) {
     for (const [name, n] of Object.entries(r.toolCounts || {})) {
       cur.tools[name] = (cur.tools[name] || 0) + n;
     }
+    for (const id of r.delegationToolUseIds || []) cur.delegationToolUseIds.push(id);
+    if (r.timestamp) {
+      const t = Date.parse(r.timestamp);
+      if (Number.isFinite(t)) {
+        if (cur.startedAt === null || t < cur.startedAt) cur.startedAt = t;
+        if (cur.endedAt === null || t > cur.endedAt) cur.endedAt = t;
+      }
+    }
     cur.models.add(r.model);
     if (!cur.cwd && r.cwd) cur.cwd = r.cwd;
   }
   return episodes;
 }
 
-function isExpensiveModel(model) {
-  return !/haiku/i.test(model);
+/**
+ * Price rank of the model that actually handled the episode (the most
+ * expensive one, when a session switched models mid-episode).
+ */
+export function episodeRank(ep) {
+  let rank = -1;
+  for (const m of ep.models) rank = Math.max(rank, modelRank(m));
+  return rank;
+}
+
+/**
+ * Delegation only pays when the target tier is strictly cheaper than what ran
+ * the work. Without this a Sonnet session produced "delegate to sonnet" T1
+ * rules — a subagent rebuilding context for zero price difference, which is a
+ * net loss. (Replaces the old boolean "is it haiku?" test, which could not
+ * tell a Sonnet session from a Fable one.)
+ */
+export function worthDelegating(tier, rank) {
+  const target = TIER_TARGET_RANK[tier];
+  return target !== undefined && rank > target;
+}
+
+/**
+ * USD a delegated run saved versus the session model doing the same work.
+ * Approximation, deliberately stated as one: it holds token counts constant,
+ * which a cheaper model would not reproduce exactly. Directionally right and
+ * enough to rank rules by value, so it is rendered as "~$X".
+ */
+export function runSaving(run, mainModel) {
+  if (!run.model || !mainModel) return 0;
+  const totals = {
+    input: run.input,
+    cacheCreation: run.cacheCreation,
+    cacheRead: run.cacheRead,
+    ephemeral5m: run.ephemeral5m,
+    ephemeral1h: run.ephemeral1h,
+    output: run.out,
+  };
+  const actual = estimateCost(totals, run.model).actual;
+  const counterfactual = estimateCost(totals, mainModel).actual;
+  return Math.max(0, counterfactual - actual);
 }
 
 const clamp = (v, [lo, hi]) => Math.min(hi, Math.max(lo, v));
@@ -278,8 +333,9 @@ export async function runRouteScan({ days = 14 } = {}) {
 
   // Pass 1 — collect episodes (needed up front: thresholds are calibrated
   // from the full window's output distribution before any tiering).
-  const all = []; // { ep, projectDir }
+  const all = []; // { ep, projectDir, sessionPath }
   let dataBytes = 0; // window size snapshot — the rescan gate diffs against it
+  const runIndexBySession = new Map(); // sessionPath → indexRuns() result
   for (const f of files) {
     let records;
     try {
@@ -290,7 +346,17 @@ export async function runRouteScan({ days = 14 } = {}) {
     }
     for (const ep of toEpisodes(records)) {
       if (!ep.text) continue;
-      all.push({ ep, projectDir: f.projectDir });
+      all.push({ ep, projectDir: f.projectDir, sessionPath: f.path });
+    }
+    // Subagent transcripts of this session — the real outcome of every
+    // delegation it made. Best-effort: sessions that never delegated have no
+    // directory and cost one failed readdir.
+    const runs = await collectSubagentRuns(f.path);
+    if (runs.length > 0) {
+      runIndexBySession.set(f.path, indexRuns(runs));
+      // Subagent bytes count toward the window size so the rescan gate stays
+      // accurate for delegation-heavy workloads.
+      for (const r of runs) dataBytes += r.bytes || 0;
     }
   }
   const totalEpisodes = all.length;
@@ -311,7 +377,8 @@ export async function runRouteScan({ days = 14 } = {}) {
 
   for (const { ep, projectDir } of all) {
     if (isSkippable(ep.text)) continue;
-    if (![...ep.models].some(isExpensiveModel)) continue; // already cheap
+    const epRank = episodeRank(ep);
+    if (!worthDelegating('T2', epRank)) continue; // already at the cheapest tier
     const cat = categorize(ep.text, ep.tools);
     if (cat) {
       // rule-health denominator: episodes that LOOK delegable by shape
@@ -323,13 +390,16 @@ export async function runRouteScan({ days = 14 } = {}) {
       // and sharing one category-wide stat would double-count every episode
       // into both rules (identical ×N / err% on unrelated tiers).
       const shapeTier = tierOf({ ...ep, errors: 0 }, cat, thresholds);
-      if (shapeTier === 'T1' || shapeTier === 'T2') {
+      // Same rank gate as the candidate path below — a denominator counting
+      // episodes that can't produce a rule would skew that rule's error rate.
+      if ((shapeTier === 'T1' || shapeTier === 'T2') && worthDelegating(shapeTier, epRank)) {
         bumpStats(`${shapeTier}|${cat.id}|${projectDir}`, ep);
         bumpStats(`${shapeTier}|${cat.id}|*`, ep);
       }
     }
     const tier = tierOf(ep, cat, thresholds);
     if (tier !== 'T1' && tier !== 'T2') continue;
+    if (!worthDelegating(tier, epRank)) continue;
     tieredEpisodes += 1;
     const key = `${tier}|${cat.id}|${projectDir}`;
     const g = groups.get(key) || {
@@ -353,6 +423,50 @@ export async function runRouteScan({ days = 14 } = {}) {
     groups.set(key, g);
   }
 
+  // Pass 3 — measured delegation outcomes (rule-health v2). Episodes that
+  // DID delegate are excluded from tiering by design (tierOf returns T0 when
+  // ep.delegated > 0: there is nothing left to route). But they are exactly
+  // where a promoted rule's real success rate lives, so they get their own
+  // pass: join each episode to the subagent transcripts it spawned, and file
+  // the outcome under the tier that run's model represents — a haiku run is a
+  // T2 rule firing, a sonnet run a T1 one. Runs that were not a downgrade
+  // (same tier or higher) carry no delegation saving and are skipped.
+  const delegatedStats = new Map(); // "tier|category|project" → outcome aggregate
+  const bumpDelegated = (key, run, saved) => {
+    const d = delegatedStats.get(key) || { runs: 0, errRuns: 0, outTokens: 0, savedUsd: 0 };
+    d.runs += 1;
+    if (run.toolErrors > 0) d.errRuns += 1;
+    d.outTokens += run.out || 0;
+    d.savedUsd += saved;
+    delegatedStats.set(key, d);
+  };
+  for (const [sessionPath, index] of runIndexBySession) {
+    const used = new Set();
+    for (const { ep, projectDir, sessionPath: epSession } of all) {
+      if (epSession !== sessionPath) continue;
+      if (!ep.delegationToolUseIds.length && index.unjoined.length === 0) continue;
+      const runs = runsForEpisode(index, ep, used);
+      if (runs.length === 0) continue;
+      const cat = categorize(ep.text, ep.tools);
+      if (!cat) continue;
+      // Counterfactual = the priciest model on the episode, i.e. what would
+      // have done the work had it not been handed off.
+      let mainModel = null;
+      let mainRank = -1;
+      for (const m of ep.models) {
+        const r = modelRank(m);
+        if (r > mainRank) { mainRank = r; mainModel = m; }
+      }
+      for (const run of runs) {
+        const runTier = tierForRank(modelRank(run.model));
+        if (!runTier || !worthDelegating(runTier, mainRank)) continue;
+        const saved = runSaving(run, mainModel);
+        bumpDelegated(`${runTier}|${cat.id}|${projectDir}`, run, saved);
+        bumpDelegated(`${runTier}|${cat.id}|*`, run, saved);
+      }
+    }
+  }
+
   // Keep prior dismissed/promoted signatures across rescans.
   const prev = readRouteScan();
   const resolved = new Set(prev?.resolved || []);
@@ -373,6 +487,16 @@ export async function runRouteScan({ days = 14 } = {}) {
   // Both languages are computed at scan time and stored on the candidate, so
   // switching `language` later re-renders (and promotes) correctly without
   // waiting for a rescan.
+  // The probe-then-commit budget is deliberately NOT baked into this text:
+  // model-rules composes it on (composeRuleText), so rules promoted before
+  // budgets existed gain the clause too, and the promote preview can never
+  // drift from what lands in the file. What the candidate carries is the
+  // calibrated budget itself — the user's own thresholds, snapshotted at scan
+  // time rather than hardcoded downstream.
+  const budgetOf = (g) => ({
+    calls: g.tier === 'T2' ? T2_MAX_CALLS + 2 : null,
+    out: g.tier === 'T2' ? thresholds.t2Out : thresholds.t1Out,
+  });
   const ruleText = (g) => g.tier === 'T2'
     ? `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${agentPhrase(g.agent)} 서브에이전트로 위임한다 (설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이면 위임하지 않음)`
     : `"${g.label}" 유형의 중간 난도 요청(예: "${g.example}")은 model: sonnet 서브에이전트로 위임한다 (설계 판단·비가역 작업·반복 에러 발생 시 메인 모델이 이어받음)`;
@@ -400,6 +524,10 @@ export async function runRouteScan({ days = 14 } = {}) {
       count: g.count,
       models: [...g.models],
       example: g.example,
+      // Snapshot of the calibrated budget this rule was written against, so
+      // the merged T2+T1 rendering in ratchet-model.md can restate it without
+      // re-running a scan.
+      budget: budgetOf(g),
       // Concentrated in one project dir → project rule; the scan groups by
       // project already, so scope suggestion is per-candidate 'project' unless
       // the same category recurs across 2+ projects (then 'global').
@@ -441,7 +569,7 @@ export async function runRouteScan({ days = 14 } = {}) {
   // rates, and rule-health flags — and rewrites their managed blocks.
   try {
     const { refreshModelRules } = await import('./model-rules.js');
-    refreshModelRules(episodeStats, { now: cache.scannedAt });
+    refreshModelRules(episodeStats, delegatedStats, { now: cache.scannedAt });
   } catch { /* registry unwritable — scan result still valid */ }
 
   return cache;

package/src/session-records.js

@@ -112,11 +112,18 @@ export async function collectSessionRecords(filePath, { includeContent = true }
     // Per-tool call histogram — what the call actually DID. route-scan's
     // categorizer trusts this over the prompt's wording (behavior-first).
     const toolCounts = { ...(prev?.toolCounts || {}) };
+    // tool_use ids of Task/Agent calls: the join key to the subagent
+    // transcripts under <session>/subagents/*.meta.json, which is how the
+    // outcome of a delegation is measured (rule-health v2).
+    const delegationToolUseIds = [...(prev?.delegationToolUseIds || [])];
     if (Array.isArray(msg.content)) {
       for (const b of msg.content) {
         if (!b || b.type !== 'tool_use') continue;
         if (MUTATING_TOOLS.has(b.name)) mutatingToolCalls += 1;
-        if (DELEGATION_TOOLS.has(b.name)) delegationCalls += 1;
+        if (DELEGATION_TOOLS.has(b.name)) {
+          delegationCalls += 1;
+          if (typeof b.id === 'string') delegationToolUseIds.push(b.id);
+        }
         if (typeof b.name === 'string') toolCounts[b.name] = (toolCounts[b.name] || 0) + 1;
       }
     }
@@ -129,6 +136,14 @@ export async function collectSessionRecords(filePath, { includeContent = true }
         (usage.cache_creation_input_tokens || 0) +
         (usage.cache_read_input_tokens || 0),
       completion_tokens: usage.output_tokens || 0,
+      // Per-bucket split, kept alongside the collapsed prompt_tokens: pricing
+      // differs per bucket, so costing a delegated run against what the
+      // session model would have charged needs them separated.
+      input_tokens: usage.input_tokens || 0,
+      cache_creation_tokens: usage.cache_creation_input_tokens || 0,
+      cache_read_tokens: usage.cache_read_input_tokens || 0,
+      ephemeral5m: usage.cache_creation?.ephemeral_5m_input_tokens || 0,
+      ephemeral1h: usage.cache_creation?.ephemeral_1h_input_tokens || 0,
       depth,
       userText: includeContent ? lastUserText : '',
       assistantText: includeContent ? contentText(msg.content) : '',
@@ -136,6 +151,7 @@ export async function collectSessionRecords(filePath, { includeContent = true }
       // Entries of the same request accumulate tool blocks and errors.
       mutatingToolCalls: (prev?.mutatingToolCalls || 0) + mutatingToolCalls,
       delegationCalls: (prev?.delegationCalls || 0) + delegationCalls,
+      delegationToolUseIds,
       toolErrors: prev?.toolErrors || 0,
       toolCounts,
     };

package/src/subagent-records.js

@@ -0,0 +1,185 @@
+/**
+ * subagent-records — read the transcripts of subagent runs a session spawned.
+ *
+ * Why this exists: rule-health used to be a PROXY. It measured the error rate
+ * of episodes the expensive model handled DIRECTLY that merely *looked*
+ * delegable by shape — never the outcome of an actual delegation. So a rule
+ * could be quietly failing every time it fired and the signal would not move.
+ * Claude Code writes each subagent run to its own transcript, which makes the
+ * real outcome measurable:
+ *
+ *   ~/.claude/projects/<munged>/<sessionId>/subagents/agent-<id>.jsonl
+ *   ~/.claude/projects/<munged>/<sessionId>/subagents/agent-<id>.meta.json
+ *
+ * The .jsonl is byte-identical in shape to a main transcript (`isSidechain:
+ * true`, assistant entries carrying `message.model` + `message.usage`,
+ * tool_result blocks carrying `is_error`), so collectSessionRecords parses it
+ * unchanged — including the rejection / self-corrected error filters, which
+ * must apply here for the same reason they apply to main sessions.
+ *
+ * The .meta.json carries `{ agentType, description, toolUseId, spawnDepth }`.
+ * `toolUseId` is the join key back to the Task/Agent tool_use block in the
+ * parent transcript, which is how a run is attributed to the episode (and
+ * therefore the category) that caused it.
+ *
+ * Everything is best-effort: this layout is a Claude Code internal, so a
+ * missing directory, an absent meta file, or an unparseable line degrades to
+ * less data, never to a throw. route-scan keeps its proxy signal as fallback.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { collectSessionRecords, normalizeModelId } from './session-records.js';
+
+/** Directory holding a session's subagent transcripts (may not exist). */
+export function subagentDirFor(sessionPath) {
+  return join(dirname(sessionPath), basename(sessionPath, '.jsonl'), 'subagents');
+}
+
+async function readMeta(metaPath) {
+  try {
+    return JSON.parse(await readFile(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A run's model when several appear in one transcript (a harness retry can
+ * switch tiers mid-run): the one that produced the most output, since that is
+ * what dominates both the bill and the counterfactual.
+ */
+function primaryModel(byModelOut) {
+  let best = null;
+  let bestOut = -1;
+  for (const [model, out] of byModelOut) {
+    if (out > bestOut) { best = model; bestOut = out; }
+  }
+  return best;
+}
+
+/**
+ * Aggregate one subagent transcript into a single run record.
+ * Returns null when the file carries no billable API call.
+ */
+export async function collectSubagentRun(jsonlPath) {
+  let records;
+  try {
+    records = await collectSessionRecords(jsonlPath, { includeContent: false });
+  } catch {
+    return null;
+  }
+  if (records.length === 0) return null;
+
+  const run = {
+    path: jsonlPath,
+    agentId: basename(jsonlPath, '.jsonl').replace(/^agent-/, ''),
+    agentType: null,
+    toolUseId: null,
+    spawnDepth: null,
+    model: null,
+    calls: records.length,
+    out: 0,
+    input: 0,
+    cacheCreation: 0,
+    cacheRead: 0,
+    ephemeral5m: 0,
+    ephemeral1h: 0,
+    toolErrors: 0,
+    startedAt: null,
+    endedAt: null,
+    bytes: 0,
+  };
+  const byModelOut = new Map();
+  for (const r of records) {
+    run.out += r.completion_tokens || 0;
+    run.input += r.input_tokens || 0;
+    run.cacheCreation += r.cache_creation_tokens || 0;
+    run.cacheRead += r.cache_read_tokens || 0;
+    run.ephemeral5m += r.ephemeral5m || 0;
+    run.ephemeral1h += r.ephemeral1h || 0;
+    run.toolErrors += r.toolErrors || 0;
+    const model = normalizeModelId(r.model);
+    byModelOut.set(model, (byModelOut.get(model) || 0) + (r.completion_tokens || 0));
+    if (r.timestamp) {
+      const t = Date.parse(r.timestamp);
+      if (Number.isFinite(t)) {
+        if (run.startedAt === null || t < run.startedAt) run.startedAt = t;
+        if (run.endedAt === null || t > run.endedAt) run.endedAt = t;
+      }
+    }
+  }
+  run.model = primaryModel(byModelOut);
+
+  const meta = await readMeta(jsonlPath.replace(/\.jsonl$/, '.meta.json'));
+  if (meta) {
+    run.agentType = meta.agentType ?? null;
+    run.toolUseId = meta.toolUseId ?? null;
+    run.spawnDepth = meta.spawnDepth ?? null;
+  }
+  try {
+    run.bytes = (await stat(jsonlPath)).size;
+  } catch { /* size only feeds the rescan gate — 0 is a safe under-estimate */ }
+
+  return run;
+}
+
+/**
+ * All subagent runs a session spawned. Empty array when the session never
+ * delegated (the common case) or the directory is unreadable.
+ */
+export async function collectSubagentRuns(sessionPath) {
+  const dir = subagentDirFor(sessionPath);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const runs = [];
+  for (const e of entries) {
+    if (!e.endsWith('.jsonl')) continue;
+    const run = await collectSubagentRun(join(dir, e));
+    if (run) runs.push(run);
+  }
+  return runs;
+}
+
+/**
+ * Index a session's runs for attribution: exact join by tool_use id first,
+ * with the un-joinable ones kept aside for the timestamp fallback (a run
+ * whose .meta.json is missing or predates toolUseId still happened, and
+ * dropping it would silently under-count a rule's real error rate).
+ */
+export function indexRuns(runs) {
+  const byToolUse = new Map();
+  const unjoined = [];
+  for (const r of runs) {
+    if (r.toolUseId) byToolUse.set(r.toolUseId, r);
+    else unjoined.push(r);
+  }
+  return { byToolUse, unjoined, all: runs };
+}
+
+/**
+ * Runs attributable to one episode. Exact tool_use ids win; anything left
+ * unjoined is matched by start time falling inside the episode's span. `used`
+ * is a shared Set of run paths across the session so no run is counted twice
+ * (an episode's span can overlap a neighbouring episode's runs).
+ */
+export function runsForEpisode(index, ep, used) {
+  const out = [];
+  for (const id of ep.delegationToolUseIds || []) {
+    const r = index.byToolUse.get(id);
+    if (r && !used.has(r.path)) { used.add(r.path); out.push(r); }
+  }
+  if (ep.startedAt === null || ep.endedAt === null) return out;
+  for (const r of index.unjoined) {
+    if (used.has(r.path) || r.startedAt === null) continue;
+    if (r.startedAt >= ep.startedAt && r.startedAt <= ep.endedAt) {
+      used.add(r.path);
+      out.push(r);
+    }
+  }
+  return out;
+}