claude-token-saver 3.8.1 → 3.9.0

package/README.en.md

@@ -263,6 +263,20 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### 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%)`.
+- **No "start a new session" advice when a compact window is set** — that threshold is exactly where compaction runs on its own, so the briefing suggests writing decisions and next steps to a file instead.
+
 ### v3.8.1 (2026-07-31)
 - **Fixed: 1M sessions were judged against a 200k window** — the briefing inferred the window from the largest request seen so far, so a 1M session counted as 200k until it had already grown past 250k. At 160k of input it announced "past 80% of the 200k window" — really 16%. The window now comes from the configured model id, and when `autoCompactWindow` is set that is where the session actually turns over, so the percentage is measured against it (the text says `(autoCompactWindow 기준)`). The observed-size heuristic remains only as the fallback for an unreadable model id.
 

package/README.md

@@ -220,6 +220,20 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### 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%)`처럼 둘 다 적습니다.
+- **압축 창이 설정돼 있으면 "새 세션 시작" 권고를 하지 않습니다** — 그 지점은 압축이 자동으로 처리하는 지점이라, 대신 결정·다음 할 일을 파일에 남기라고 안내합니다.
+
 ### v3.8.1 (2026-07-31)
 - **1M 세션을 200k 창으로 오판하던 브리핑 버그 수정** — 세션 창을 "지금까지 본 가장 큰 요청"으로 추정해서, 1M 세션이라도 25만 토큰을 넘기 전까지는 200k로 취급했습니다. 그래서 입력 160k에서 "200k 창의 80%를 넘었습니다" 경고가 떴습니다(실제로는 16%). 이제 설정된 모델 ID로 창을 판정하고, `autoCompactWindow`가 잡혀 있으면 그 값이 실제로 세션이 넘어가는 지점이므로 그쪽을 기준으로 %를 계산합니다(문구에도 `(autoCompactWindow 기준)` 표기). 모델 ID를 못 읽는 경우에만 기존 관측치 추정으로 되돌아갑니다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "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

@@ -85,18 +85,19 @@ function saveState(state, now) {
  * is unreadable (env override, settings we do not resolve).
  */
 export function ctxWindowFor(observedMax = 0, root = process.cwd()) {
-  let window = observedMax > WINDOW_1M_MIN_INPUT ? 1_000_000 : 200_000;
+  let modelWindow = observedMax > WINDOW_1M_MIN_INPUT ? 1_000_000 : 200_000;
+  let window = modelWindow;
   let compactCapped = false;
   try {
     const { model } = resolveModelId(root);
-    if (isOneMillionModel(model)) window = 1_000_000;
+    if (isOneMillionModel(model)) modelWindow = window = 1_000_000;
     const cap = effectiveWindow(root).value;
     if (cap !== null && cap < window) {
       window = cap;
       compactCapped = true;
     }
   } catch { /* settings unreadable — the observed-size fallback still holds */ }
-  return { window, compactCapped };
+  return { window, modelWindow, compactCapped };
 }
 
 /**
@@ -129,8 +130,8 @@ export function sessionCtx(transcriptPath, { root = process.cwd() } = {}) {
     if (total > 0) { input = total; maxInput = Math.max(maxInput, total); }
   }
   if (input == null) return null;
-  const { window, compactCapped } = ctxWindowFor(maxInput, root);
-  return { input, window, compactCapped, pct: input / window };
+  const { window, modelWindow, compactCapped } = ctxWindowFor(maxInput, root);
+  return { input, window, modelWindow, compactCapped, pct: input / window };
 }
 
 function ctxTierOf(pct) {
@@ -175,15 +176,30 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
   const ctx = transcriptPath ? sessionCtx(transcriptPath) : null;
   if (ctx) {
     const tier = ctxTierOf(ctx.pct);
+    // The tier is not monotonic: auto-compaction drops the live context back to
+    // a fraction of the window, which starts a new fill cycle. Holding the old
+    // high-water tier meant a session that compacted at 80% was never warned
+    // again — it silently refilled to the cap with no signal at all.
+    if (tier < (s.ctxTier || 0)) s.ctxTier = tier;
     if (tier > (s.ctxTier || 0)) {
-      // Name the window the percentage was actually computed against — when
-      // autoCompactWindow caps a 1M model at 400k, "1M 창의 80%" would be a
-      // number the user cannot reconcile with anything they configured.
+      // Name both denominators when they differ. Claude Code's own UI counts
+      // against the model window, so a bare "400k 창의 80%" reads as wrong to
+      // anyone looking at a statusline that says 32% of 1M — same session,
+      // two different windows, no way to reconcile them from the text alone.
       const winLabel = ctx.window >= 1_000_000 ? '1M' : fmtK(ctx.window);
-      const capNote = ctx.compactCapped ? ' (autoCompactWindow 기준)' : '';
+      const modelPct = Math.round((ctx.input / ctx.modelWindow) * 100);
+      const modelLabel = ctx.modelWindow >= 1_000_000 ? '1M' : fmtK(ctx.modelWindow);
+      const capNote = ctx.compactCapped ? `, 화면의 ${modelLabel} 창 기준으로는 ${modelPct}%` : '';
+      // With autoCompactWindow set, crossing the threshold means compaction is
+      // about to run on its own. Telling the user to start a new session there
+      // would be advice for a problem the setting already handles.
       items.push(tier === 2
-        ? `이 세션의 컨텍스트가 ${winLabel} 창${capNote}의 95%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 곧 자동 압축으로 맥락 손실이 생길 수 있으니, 진행 중인 작업을 일단락하고 새 세션을 시작하는 편이 좋습니다.`
-        : `이 세션의 컨텍스트가 ${winLabel} 창${capNote}의 80%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 이후 요청은 비용이 커지는 구간입니다 — 작업이 일단락되면 새 세션 시작을 권합니다.`);
+        ? (ctx.compactCapped
+            ? `이 세션의 컨텍스트가 자동 압축 창(${winLabel})의 95%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}${capNote}). 곧 자동 압축이 돌아 이전 대화가 요약으로 바뀝니다 — 지금 단계를 마무리하고 이어서 할 일은 파일에 적어두면 압축 뒤에도 안전합니다.`
+            : `이 세션의 컨텍스트가 ${winLabel} 창의 95%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 곧 자동 압축으로 맥락 손실이 생길 수 있으니, 진행 중인 작업을 일단락하고 새 세션을 시작하는 편이 좋습니다.`)
+        : (ctx.compactCapped
+            ? `이 세션의 컨텍스트가 자동 압축 창(${winLabel})의 80%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}${capNote}). 설정해 둔 압축 지점이 가까워졌습니다 — 압축은 알아서 돌아가니 새 세션을 서두를 필요는 없고, 여기까지의 결정과 다음 할 일만 파일에 남겨두면 됩니다.`
+            : `이 세션의 컨텍스트가 ${winLabel} 창의 80%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 이후 요청은 비용이 커지는 구간입니다 — 작업이 일단락되면 새 세션 시작을 권합니다.`));
       s.ctxTier = tier;
     }
   }

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/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;
+}