claude-token-saver 3.10.0 → 3.11.0

package/README.en.md

@@ -77,6 +77,7 @@ The statusline appears at the bottom of Claude Code right away. If auto-registra
 | `✦ current` / `📅 weekly` | 5-hour / 7-day rate-limit window usage + reset time |
 | `📦` | Context usage (e.g. `Ctx 68% of 1M`) — colored by fill. Current models default to 1M with no premium, but token volume itself drives per-turn cost and 5H/7D burn |
 | `💰` | Cumulative savings from prompt caching |
+| `🔀` | Cumulative savings from delegation — what running work on a cheaper tier saved, a different number from `💰`. Hidden until a delegation has actually been measured |
 
 When something is wrong, a **warning chip leads the line**:
 
@@ -300,6 +301,10 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.11.0 (2026-08-21)
+- **Delegation savings chip in the statusline** — `🔀 Delegated $3.2`. The existing `💰 Cache saved` covers the prompt cache; this one is what running work on a cheaper tier saved. Zero or missing data hides the chip entirely, so nothing changes for direct-API users. The statusline only reads `model-rules.json` — it never triggers a scan (it re-renders every few seconds). Segment name: `delegated`.
+- **Role-learning mis-classification fixed** — subagent records sometimes land in the parent transcript without an `isSidechain` flag, and that circumstantial evidence could outvote stated evidence, confirming a haiku profile as the session model (measured: 16 against 1, agreement exactly at the 80% line). Stated evidence (`Task(model:)` parameters, agent-definition frontmatter) and inferred evidence are now tallied separately, and an inference is not adopted when stated evidence contradicts it. Undecided ids stay `unknown` and leave the aggregate.
+
 ### v3.10.0 (2026-08-20)
 - **Model tiers are detected again behind a Bedrock / LiteLLM gateway** — when the transcript's model id is an inference-profile ARN there is no `opus` or `haiku` in the string, so it fell back to Sonnet. Since `worthDelegating()` requires `rank > target`, **every T1 rule was rejected**, savings aggregated to zero, and cost was under-counted by roughly 1.67x. The profile id is now learned as a role (parent `Task` call joined to the subagent run by `toolUseId`) and mapped back to the alias your environment declares. The pricing table, the ranks, and the tiering logic are untouched.
 - **No confident mapping means no guess** — under three observations, or below 80% agreement, the id stays `unknown` and leaves the delegation aggregate. Quietly calling it Sonnet was the worse failure.

package/README.md

@@ -76,6 +76,7 @@ npm i -g claude-token-saver
 | `✦ current` / `📅 weekly` | 5시간 / 7일 rate-limit 윈도 사용률 + 리셋 시각 |
 | `📦` | 컨텍스트 사용률 (예: `Ctx 68% of 1M`) — 사용률 기준 녹/황/적. 현재 모델은 1M이 기본·프리미엄 없음이지만, 토큰량 자체가 턴당 비용과 5H/7D 한도를 태웁니다 |
 | `💰` | 캐시가 절약해준 누적 금액 |
+| `🔀` | 위임이 절약해준 누적 금액 — 더 싼 티어로 내려서 아낀 몫이며 `💰`와는 다른 수치입니다. 실측 위임이 없으면 표시되지 않습니다 |
 
 문제가 감지되면 **경고 칩이 맨 앞에** 붙습니다:
 
@@ -256,6 +257,10 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.11.0 (2026-08-21)
+- **statusline에 위임 절감 칩 추가** — `🔀 Delegated $3.2`. 기존 `💰 Cache saved`는 프롬프트 캐시 절감이고, 새 칩은 **더 싼 티어로 내려서 아낀 금액**입니다. 값이 0이거나 데이터가 없으면 칩을 아예 그리지 않아 직접 API 사용자에게는 아무것도 늘지 않습니다. statusline은 `model-rules.json`을 읽기만 하며 스캔을 돌리지 않습니다(5초마다 호출되는 자리입니다). 세그먼트 이름은 `delegated`입니다.
+- **역할 학습의 오분류 수정** — 서브에이전트 레코드가 부모 트랜스크립트에 `isSidechain` 없이 섞여 들어오는 경우가 있어, 그 정황 증거가 명시 증거를 이겨 haiku 프로파일이 세션 모델로 확정되곤 했습니다(실측 16건 대 1건, 합의율 정확히 80%). 이제 **명시 증거(`Task(model:)` 파라미터·에이전트 정의 frontmatter)와 정황 증거(sidechain 플래그 부재)를 분리해 집계**하고, 명시 증거가 이를 반박하면 정황 추론을 채택하지 않습니다. 확정이 안 되면 `unknown`으로 남아 집계에서 빠집니다.
+
 ### v3.10.0 (2026-08-20)
 - **게이트웨이(Bedrock·LiteLLM) 환경에서 모델 티어를 다시 인식합니다** — 로그의 모델명이 추론 프로파일 ARN이면 `opus`·`haiku` 단서가 없어 Sonnet으로 폴백했고, `worthDelegating()`이 `rank > target`을 요구하므로 **T1 위임이 전부 기각**됐습니다. 절감 집계는 0, 비용은 약 1.67배 과소 계상이었습니다. 이제 프로파일 ID를 역할로 학습해(부모 `Task` 호출 ↔ 서브에이전트 `toolUseId` 정확 조인) 환경변수가 선언한 별칭으로 되돌립니다. 가격표·랭크·판정 로직은 그대로입니다.
 - **확신이 없으면 숨기지 않고 드러냅니다** — 관측 3건 미만이거나 역할 동의율 80% 미만이면 `unknown`으로 두고 위임 집계에서 제외합니다. Sonnet으로 조용히 틀리던 기존 동작이 더 나빴습니다.

package/bin/cli.js

@@ -433,6 +433,17 @@ async function main() {
   }
   const lastActivity = Math.max(otherLastActivity, currentSessionLastUser);
 
+  // What delegation has measurably saved, read straight from the registry
+  // route-scan maintains. A lookup, never a scan: the statusline re-renders
+  // every few seconds and a scan parses tens of MB of transcripts.
+  let delegationSaved = 0;
+  try {
+    const { delegationSavedUsd } = await import('../src/model-rules.js');
+    delegationSaved = delegationSavedUsd();
+  } catch (e) {
+    debug('model-rules:saved', e); // an unreadable registry just hides the chip
+  }
+
   const data = {
     summary: sum,
     trend,
@@ -447,6 +458,7 @@ async function main() {
     spikeChip,
     caps,
     model,
+    delegationSaved,
   };
 
   let output;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/formatters/statusline.js

@@ -211,7 +211,7 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '' }
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
- * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, harness, model, hit, ttl, saved, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
+ * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, harness, model, hit, ttl, saved, delegated, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
  */
 export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null } = {}) {
   const { summary, ttl, cost, options, lastActivity, contextWindow, ctxLive, spikeChip, caps, model } = data;
@@ -255,6 +255,21 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     : 'Cache saved';
   const saveSeg = `${c(CYAN)}${saveLabel}${c(RESET)} ${formatMoney(savings)}`;
 
+  // Delegation savings — a DIFFERENT number from "Cache saved" above, which
+  // covers the prompt cache only. This one is what running work on a cheaper
+  // tier saved, summed from the rule registry route-scan maintains. Hidden
+  // when zero or absent: a permanent "$0" is noise for direct-API users and
+  // for anyone who has not delegated yet.
+  //   text:       "Delegated $3.2"                   |  same in verbose
+  //   icon:       "🔀 $3.2"                           |  verbose: "🔀 Delegated $3.2"
+  const delegationSaved = Number(data.delegationSaved) || 0;
+  const delegateLabel = isIcon
+    ? (verbose ? '🔀 Delegated' : '🔀')
+    : 'Delegated';
+  const delegateSeg = delegationSaved > 0
+    ? `${c(GREEN)}${delegateLabel}${c(RESET)} ${formatMoney(delegationSaved)}`
+    : null;
+
   // Period label honors hour-precision configs (`mode 6h` → "6h", `mode 1d` → "1d").
   // Fall back to legacy `${days}d` when callers haven't supplied a label.
   const periodLabel = options.windowLabel || `${options.days}d`;
@@ -482,6 +497,8 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // it sits near the tail. The period label closes the line as a quiet
   // timeframe footer.
   if (want('saved')) segs.push(saveSeg);
+  // Both savings numbers sit side by side, then the period label closes the line.
+  if (delegateSeg && want('delegated')) segs.push(delegateSeg);
   if (want('period')) segs.push(periodSeg);
   // Trailing erase-to-end-of-line so any leftover characters from a previous
   // (longer) statusline render don't bleed into ours. \x1b[K is the standard

package/src/model-alias.js

@@ -200,10 +200,21 @@ function roleFromAgentType(agentType, cache) {
   return role;
 }
 
-function addVote(votes, pid, role) {
+/**
+ * Record one observation.
+ *
+ * `kind` matters more than the count. An 'explicit' vote comes from a stated
+ * model — a `Task(model: "haiku")` parameter or an agent definition's
+ * frontmatter. An 'inferred' vote is circumstantial: the record carried no
+ * sidechain flag, so it is *probably* the parent session's own model. Mixing
+ * the two by volume let 4 inferred votes outrank 1 explicit one and stamped a
+ * haiku profile as 'main' — see tallyVotes.
+ */
+function addVote(votes, pid, role, kind) {
   if (!pid || !role) return;
-  const v = (votes[pid] ||= {});
-  v[role] = (v[role] || 0) + 1;
+  const v = (votes[pid] ||= { explicit: {}, inferred: {} });
+  const bucket = v[kind] || (v[kind] = {});
+  bucket[role] = (bucket[role] || 0) + 1;
 }
 
 /**
@@ -235,7 +246,9 @@ async function scanMainTranscript(path, votes, requestedByToolUse, agentTypeCach
         const pid = profileIdFrom(msg.model);
         if (pid) {
           sawGateway = true;
-          addVote(votes, pid, 'main');
+          // Circumstantial: a subagent's records also land in the parent file
+          // without the flag often enough to outvote real evidence.
+          addVote(votes, pid, 'main', 'inferred');
         }
       }
 
@@ -289,18 +302,76 @@ async function subagentFiles(sessionPath) {
   }
 }
 
-/** Decide a role per profile id once the votes are numerous and consistent. */
+/**
+ * Whether two roles describe the same model. 'main' and 'opus' routinely do:
+ * the session model is the opus alias on a default setup, so a Task that asked
+ * for opus does not contradict "this is the parent's own profile".
+ */
+function rolesAgree(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  const pair = new Set([a, b]);
+  return pair.has('main') && pair.has('opus');
+}
+
+/** Winner of one bucket, with the counts needed to judge confidence. */
+function topRole(tally) {
+  let role = null;
+  let top = 0;
+  let total = 0;
+  for (const [r, n] of Object.entries(tally || {})) {
+    total += n;
+    if (n > top) { top = n; role = r; }
+  }
+  return { role, top, total };
+}
+
+/**
+ * Decide a role per profile id.
+ *
+ * Explicit evidence decides alone whenever there is enough of it; inferred
+ * evidence is only consulted when the explicit bucket is too thin. Counting
+ * both together is what produced the original mis-classification: a haiku
+ * profile appeared 16 times in parent transcripts without a sidechain flag
+ * against 1,702 times as a subagent, and those 16 inferred 'main' votes beat
+ * the single explicit 'haiku' one at exactly the 80% line.
+ *
+ * When neither bucket is decisive the id stays unresolved. An 'unknown' that
+ * drops out of the aggregate beats a confident wrong answer that silently
+ * re-tiers every run on that profile.
+ */
 export function tallyVotes(votes, { minVotes = MIN_VOTES, minAgreement = MIN_AGREEMENT } = {}) {
   const learned = {};
-  for (const [pid, tally] of Object.entries(votes)) {
-    const total = Object.values(tally).reduce((a, b) => a + b, 0);
+  for (const [pid, buckets] of Object.entries(votes)) {
+    // Legacy flat shape (`{ haiku: 3 }`) is read as explicit evidence.
+    const split = buckets && (buckets.explicit || buckets.inferred)
+      ? { explicit: buckets.explicit || {}, inferred: buckets.inferred || {} }
+      : { explicit: buckets || {}, inferred: {} };
+
+    const explicit = topRole(split.explicit);
+    const inferred = topRole(split.inferred);
+
     let role = null;
-    let top = 0;
-    for (const [r, n] of Object.entries(tally)) {
-      if (n > top) { top = n; role = r; }
+    let source = null;
+    if (explicit.total >= minVotes && explicit.top / explicit.total >= minAgreement) {
+      role = explicit.role;
+      source = 'explicit';
+    } else if (inferred.total >= minVotes
+      && inferred.top / inferred.total >= minAgreement
+      && (explicit.total === 0 || rolesAgree(explicit.role, inferred.role))) {
+      // Thin explicit evidence still vetoes a contradicting inference: one
+      // stated `Task(model: "haiku")` outweighs any number of "no sidechain
+      // flag, so probably the session model" observations.
+      role = inferred.role;
+      source = 'inferred';
     }
-    const confident = total >= minVotes && top / total >= minAgreement;
-    learned[pid] = { role: confident ? role : null, votes: tally, total };
+
+    learned[pid] = {
+      role,
+      source,
+      votes: split,
+      total: explicit.total + inferred.total,
+    };
   }
   return learned;
 }
@@ -345,7 +416,9 @@ export async function learnProfileMapping({ sessionPaths = [], maxSessions = 40
       const pid = await subagentProfileId(jsonl);
       if (!pid) continue;
       sawGateway = true;
-      addVote(votes, pid, role);
+      // Stated evidence: the Task call named this tier, or the agent
+      // definition it used did.
+      addVote(votes, pid, role, 'explicit');
     }
     if (sawGateway) gateway = true;
   }

package/src/model-rules.js

@@ -100,6 +100,27 @@ export function loadModelRules() {
   }
 }
 
+/**
+ * USD that measured delegations have saved, summed across registered rules.
+ * Reads the file route-scan already wrote — the statusline refreshes every few
+ * seconds and must never start a scan of its own (a scan parses tens of MB of
+ * transcripts).
+ *
+ * Rules with no measured delegation contribute nothing, and an unreadable
+ * registry returns 0 rather than throwing: the statusline reads 0 as "draw no
+ * chip", which is the right outcome for anyone who never delegates.
+ */
+export function delegationSavedUsd() {
+  try {
+    return loadModelRules().rules.reduce(
+      (sum, r) => sum + (r.delegatedRuns ? (Number(r.savedUsd) || 0) : 0),
+      0,
+    );
+  } catch {
+    return 0;
+  }
+}
+
 export function saveModelRules(data) {
   const dir = stateDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });