sprag-cli 3.55.0 → 3.57.0

package/README.ko.md

@@ -185,7 +185,7 @@ JetBrains IDE 내장 터미널에서는 이모지 대신 한 칸 글리프로
 
 | 명령 | 하는 일 |
 |---|---|
-| `sprag` | 최근 1일 진단 리포트 |
+| `sprag` | 최근 30일 진단 리포트 |
 | `sprag handoff` | 한도에 막히기 전에 작업 상태를 백업 |
 | `sprag route-scan` | 내 기록에서 위임 후보 찾기 (LLM 호출 0회) |
 | `sprag route-scan savings` | 라우팅 절감 원장 조회 |
@@ -209,6 +209,10 @@ JetBrains IDE 내장 터미널에서는 이모지 대신 한 칸 글리프로
 | [한국어 문체 지침](https://github.com/rootstudioyaml/sprag/blob/main/docs/KOREAN-STYLE.ko.md) | 주입 내용, 쓰기 시점 검사, 적용 전후 비교 |
 | [라우터가 아닌 이유](https://github.com/rootstudioyaml/sprag/blob/main/docs/NOT-A-ROUTER.ko.md) | 실시간 라우팅이 캐시를 깨서 비용을 키우는 구조 |
 | [게이트웨이와 환경](https://github.com/rootstudioyaml/sprag/blob/main/docs/GATEWAYS.ko.md) | Bedrock·Vertex·LiteLLM, 가격표, FAQ, 동작 원리 |
+| [클로드 코드 토큰 줄이는 법](https://sprag.io/docs/ko/reduce-claude-code-tokens/) | 압축·초기화 타이밍, 서브에이전트 탐색, 문서 변환, 캐시 TTL |
+| [클로드 코드 사용 한도](https://sprag.io/docs/ko/claude-code-usage-limits/) | 5시간·7일 윈도우, 함께 지켜보는 법, 턴당 비용 줄이기 |
+| [코덱스 토큰 사용량](https://sprag.io/docs/ko/codex-token-usage/) | 세션 범위 나누기, 네이티브 서브에이전트 위임, 코덱스 문서 변환 |
+| [도구 비교](https://sprag.io/docs/ko/compare/) | ccusage·claude-usage·CCometixLine 같은 스테이터스라인 도구와 Sprag의 차이 |
 
 LiteLLM 게이트웨이 환경에서는 `sprag profile-map --refresh` 가 게이트웨이의 `GET /model/info` 에서 모델 별칭을 바로 읽어 오므로, route-scan 이 위임 투표가 쌓이길 기다리거나 `profile-map.json` 을 손으로 편집할 필요가 없어졌습니다. 이 갱신은 LiteLLM 예산 게이지와 같은 5분 점검·24시간 캐시 주기를 씁니다. 인증 토큰은 저장하지 않으며, 호출 시점마다 `apiKeyHelper` 에서 읽어 그 헬퍼의 수명 그대로 만료되게 둡니다. 자세한 내용은 [route-scan](https://github.com/rootstudioyaml/sprag/blob/main/docs/ROUTE_SCAN.md) 문서에 있습니다.
 

package/README.md

@@ -229,7 +229,7 @@ work types, and once each has a rule there is nothing left to promote.
 
 | Command | What it does |
 |---|---|
-| `sprag` | Last-1-day diagnostic report |
+| `sprag` | Last-30-day diagnostic report |
 | `sprag handoff` | Back work up to markdown before a cap blocks you |
 | `sprag route-scan` | Find delegation candidates in your own history (0 LLM calls) |
 | `sprag route-scan savings` | The routing-savings ledger |
@@ -254,6 +254,10 @@ Every subcommand, flag and the output-language setting: [command reference](http
 | [Korean style](https://github.com/rootstudioyaml/sprag/blob/main/docs/KOREAN-STYLE.md) | What gets injected, the write-time check, before/after |
 | [Not a router](https://github.com/rootstudioyaml/sprag/blob/main/docs/NOT-A-ROUTER.md) | Why realtime routing breaks the cache and costs more |
 | [Gateways & environment](https://github.com/rootstudioyaml/sprag/blob/main/docs/GATEWAYS.md) | Bedrock, Vertex, LiteLLM budgets, pricing table, FAQ, how it works |
+| [Reduce Claude Code tokens](https://sprag.io/docs/reduce-claude-code-tokens/) | Compact/clear timing, subagent exploration, document conversion, cache TTL |
+| [Claude Code usage limits](https://sprag.io/docs/claude-code-usage-limits/) | The 5-hour and 7-day windows, watching both, cutting per-turn cost |
+| [Codex token usage](https://sprag.io/docs/codex-token-usage/) | Session scoping, native subagent delegation, document conversion for Codex |
+| [Compare](https://sprag.io/docs/compare/) | Sprag vs ccusage, claude-usage, and statusline tools like CCometixLine |
 
 Behind a LiteLLM gateway, `sprag profile-map --refresh` now reads model aliases straight from the gateway's own `GET /model/info`, so route-scan no longer needs to wait on learned votes or a hand-edited `profile-map.json`. The refresh uses the same 5-minute check and 24-hour cache as the LiteLLM budget gauge. It never stores your auth token: each refresh reads it from `apiKeyHelper` at call time and lets it expire on the helper's own schedule. Details: [route-scan](https://github.com/rootstudioyaml/sprag/blob/main/docs/ROUTE_SCAN.md).
 

package/bin/cli.js

@@ -36,12 +36,13 @@ import {
   extractContextUsage,
   extractEffort,
   extractModel,
+  extractSessionId,
   extractTranscriptPath,
 } from '../src/stdin-payload.js';
 
 import { effortChipLevel } from '../src/ultracode.js';
 
-import { parseAllSessions, getLastUserMessageTime } from '../src/parser.js';
+import { parseAllSessions, sessionsSince, getLastUserMessageTime } from '../src/parser.js';
 import {
   dailyTrend,
   ttlBreakdown,
@@ -52,7 +53,7 @@ import {
   sessionMetrics,
   diagnoseSession,
 } from '../src/stats.js';
-import { estimateCostAcross } from '../src/cost.js';
+import { sessionCostAcross } from '../src/claude-price.js';
 import { chipForIssues } from '../src/advice.js';
 import { debug } from '../src/debug.js';
 import { createArgs } from '../src/cli-args.js';
@@ -92,6 +93,15 @@ function readUpdateChip() {
   }
 }
 
+/**
+ * Whether the table report may use ANSI codes. The formatter looked at NO_COLOR
+ * alone, so `--no-color` did nothing there and a piped report (`sprag | less`,
+ * a redirect to a file) carried escape codes into its output.
+ */
+function tableColor() {
+  return !hasFlag('--no-color') && !process.env.NO_COLOR && !!process.stdout.isTTY;
+}
+
 // Subcommands this build knows how to run. Used only by the guard below.
 const KNOWN_SUBCOMMANDS = new Set([
   'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean', 'cohesion',
@@ -131,6 +141,16 @@ Usage:
   sprag last               most recent warning + how to handle it
   sprag history            recent warning transitions
   sprag handoff            write a session handoff file
+  sprag mode [keywords]    statusline preferences (icon/text, en/ko, window, ttl)
+  sprag seed               register the bundled starter rules, one answer at a time
+  sprag korean on|off|status     Korean writing guidance + write-time check
+  sprag cohesion on|off|status   English sentence-connection guidance
+  sprag doc2md on|off|<file>     convert documents to Markdown before the model reads them
+  sprag delegate on|off|status   add bounds and context to Task/Agent delegation prompts
+  sprag compact-window     audit or pin autoCompactWindow for 1M sessions
+  sprag litellm-budget     LiteLLM gateway key budget and spend
+  sprag update-check       is a newer version out?
+  sprag brief --hook       internal: the UserPromptSubmit hook entry point
   sprag feedback "<msg>"   file a bug report / feature request (no browser needed)
   sprag upgrade            install the latest release
   sprag --install-hook     install cache-monitor PostToolUse hook
@@ -434,7 +454,7 @@ async function main() {
     const { buildTableDemoData } = await import('../src/demo.js');
     const { formatReport } = await import('../src/formatters/table.js');
     const data = buildTableDemoData({ version: PKG_VERSION });
-    console.log(formatReport(data));
+    console.log(formatReport(data, { color: tableColor() }));
     return;
   }
 
@@ -529,7 +549,10 @@ async function main() {
   const excludeSessionPath =
     getArg('--exclude-session') || process.env.CACHE_MONITOR_EXCLUDE_SESSION || undefined;
 
-  const sessions = await parseAllSessions({ days, projectFilter });
+  // The statusline also reports this month's spend. Naming the month start here
+  // lets the one pass over the transcripts trim boundary sessions to it too.
+  const monthSince = isStatusline ? (await import('../src/month-spend.js')).monthStartMs() : undefined;
+  const sessions = await parseAllSessions({ days, projectFilter, sinceMs: monthSince });
 
   if (sessions.length === 0) {
     // Statusline must always emit a single line (no multi-line help spam every
@@ -552,6 +575,15 @@ async function main() {
       // Resolved the same way as on the populated line below, so the chip does
       // not change its mind about the level when the analysis window empties.
       const effort = effortChipLevel(extractEffort(stdinJson), extractTranscriptPath(stdinJson));
+      // Recorded here too: a fresh session can render before it has any request
+      // in the analysis window, and its first prompt is briefed from this.
+      const ctxLive = extractContextUsage(stdinJson);
+      if (ctxLive?.size) {
+        try {
+          const { recordLiveWindow } = await import('../src/ctx-window-cache.js');
+          recordLiveWindow(extractSessionId(stdinJson), ctxLive.size);
+        } catch (e) { debug('ctx-window-cache:record', e); }
+      }
       if (caps || model) {
         try {
           const { persistSnapshot } = await import('../src/caps-cache.js');
@@ -592,7 +624,7 @@ async function main() {
   const ttl = ttlBreakdown(sessions);
   const sum = summary(sessions);
   const anomalies = detectAnomalies(trend);
-  const cost = estimateCostAcross(sessions);
+  const cost = sessionCostAcross(sessions);
   const spikeReport = detectSpikes(sessions, { recentHours: 24, multiplier: 3 });
   const contextWindow = detectContextWindow(sessions, { recentHours: 24 });
 
@@ -618,6 +650,16 @@ async function main() {
     ? effortChipLevel(extractEffort(stdinJson), extractTranscriptPath(stdinJson))
     : extractEffort(stdinJson);
   const ctxLive = extractContextUsage(stdinJson);
+  // The prompt-submit briefing has no payload field for the window, so it reads
+  // back what this render was told (see src/ctx-window-cache.js).
+  if (isStatusline && ctxLive?.size) {
+    try {
+      const { recordLiveWindow } = await import('../src/ctx-window-cache.js');
+      recordLiveWindow(extractSessionId(stdinJson), ctxLive.size);
+    } catch (e) {
+      debug('ctx-window-cache:record', e);
+    }
+  }
   if (isStatusline && (caps || model)) {
     try {
       const { persistSnapshot } = await import('../src/caps-cache.js');
@@ -730,28 +772,23 @@ async function main() {
   if (isStatusline) {
     try {
       const { monthSpend, monthStartMs } = await import('../src/month-spend.js');
-      const daysNeeded = (Date.now() - monthStartMs()) / 86400000;
+      const since = monthStartMs();
+      const daysNeeded = (Date.now() - since) / 86400000;
       const monthSessions = days >= daysNeeded
         ? sessions
-        : await parseAllSessions({ days: Math.max(1, Math.ceil(daysNeeded)), projectFilter });
-      monthSpendInfo = monthSpend(monthSessions);
+        : await parseAllSessions({ days: Math.max(1, Math.ceil(daysNeeded)), projectFilter, sinceMs: since });
+      // 월 경계에 걸친 세션은 월초 이후 요청만 남긴다. 그러지 않으면 1일 자정을
+      // 넘긴 세션의 전월분이 이번 달 지출에 그대로 들어온다.
+      monthSpendInfo = monthSpend(await sessionsSince(monthSessions, since));
     } catch (e) {
       debug('month-spend', e);
     }
   }
 
-  // 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
-  }
   // Rolling week/month/lifetime totals from the delegation ledger — the
   // statusline's headline line. Falls back to null (chip hidden) on any error.
+  // A lookup, never a scan: the statusline re-renders every few seconds and a
+  // scan parses tens of MB of transcripts.
   let delegationTotals = null;
   try {
     const { delegationSavedTotals } = await import('../src/savings-ledger.js');
@@ -759,6 +796,10 @@ async function main() {
   } catch (e) {
     debug('savings-ledger:totals', e);
   }
+  // The single-line layout shows the same lifetime figure as the headline
+  // line. It used to sum the rule registry instead, a scan-window snapshot
+  // priced against another baseline, so one label carried two amounts.
+  const delegationSaved = Number(delegationTotals?.total) || 0;
   // Document conversions, same shape as the delegation totals: a lifetime sum
   // plus a document count. A lookup of a small JSON file, never a scan.
   let doc2mdTotals = null;
@@ -857,7 +898,7 @@ async function main() {
     });
   } else {
     const { formatReport } = await import('../src/formatters/table.js');
-    output = formatReport(data);
+    output = formatReport(data, { color: tableColor() });
   }
 
   console.log(output);

package/bin/postinstall.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * npm `postinstall` entry point: runs `sprag install` for a global install and
+ * says why it did not for anything else. See src/postinstall.js.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { postinstallDecision } from '../src/postinstall.js';
+
+const decision = postinstallDecision(process.env);
+if (!decision.run) {
+  console.log(`sprag: setup skipped (${decision.reason}). Run \`sprag install\` to register the hooks and the statusline.`);
+  process.exit(0);
+}
+const cli = join(dirname(fileURLToPath(import.meta.url)), 'cli.js');
+spawnSync(process.execPath, [cli, 'install'], { stdio: 'inherit' });
+// A failed setup must not fail the package install: the CLI is still usable
+// and `sprag install` can be run again by hand.
+process.exit(0);

package/docs/CODEX.ko.md

@@ -51,7 +51,7 @@ macOS zsh 환경에서는 설치가 tmux 설치 여부를 먼저 확인합니다
 | 한국어 검사 | 파일 쓰기 후 문체 위반을 검사하며 block·warn·off를 지원합니다 |
 | 상태 표시 | 별도 패널, tmux 패널, 일회성 상태줄을 제공합니다 |
 | 브리핑·이력 | 최신 컨텍스트와 사용량 경고를 알리고 세션별로 저장합니다 |
-| 위임 원장 | Sprag가 위임한 하위 실행과 LiteLLM 단가로 예상 차액을 계산합니다 |
+| 위임 원장 | Sprag가 위임한 하위 실행의 토큰에 호출 경로의 단가를 적용해 예상 차액을 계산합니다. 직접 호출은 OpenAI 정가를, LiteLLM 공급자는 그 게이트웨이의 단가를 씁니다 |
 
 ## 패널과 보고서
 
@@ -108,8 +108,38 @@ sprag seed reset --agent codex
 등록할 때 `--model ID`를 요구합니다. 모델 사용 가능 여부는 실제 공급자 설정에 달려 있습니다.
 명시한 모델과 사용자 정의 역할은 유지하며, 사용할 수 없는 하위 에이전트 도구를 만들어 내지 않습니다.
 
+Codex 0.159.2에서는 `spawn_agent`가 `PreToolUse`를 거치지 않습니다(기록용 훅을 붙여 직접
+확인한 결과입니다). 그래서 실제로 동작하는 경로는 프롬프트 시점입니다. 규칙에 맞는 프롬프트가
+오면 `[Sprag model routing]` 안내가 붙고, `harness init`이 넣는 AGENTS.md 블록이 이 안내를
+"사용자가 위임을 요청했다"는 뜻으로 읽게 합니다. 자식은 `fork_turns "none"`으로 뜨고, 부모는
+같은 일을 직접 하지 않고 `wait_agent`(제한 시간 120초 이상)로 자식이 끝나기를 기다립니다. 귀속은
+자식이 route id를 되받아 적는 것에 기대지 않습니다. 대신 `SubagentStart`가 대기 중인 기록(같은
+부모 세션, 같은 목표 모델, 30분 이내)에 새로 뜬 자식을 매칭해 묶습니다. 어떤 자식도 가져가지
+않은 안내는 부모 세션에 다음 프롬프트가 들어올 때 닫히므로, 나중에 다른 이유로 뜬 자식이 그
+안내의 절감으로 잡히지 않습니다. 같은 프롬프트 시점에 아직 장부에 반영되지 않은 위임 실행도
+별도 프로세스로 계산하므로, `Routing saved`는 다음 route-scan을 기다리지 않고 위임 뒤 첫
+프롬프트에서 갱신됩니다.
+
+이 안내는 부모 세션의 컨텍스트가 `codex.delegateMinContext`(기본 60000 토큰) 아래면 붙지
+않습니다. 2026-09-30 실측에서 작은 세션은 스폰·대기·검증이라는 조율 비용이 자식이 아끼는
+비용보다 커서, 문턱 아래에서는 안내를 붙이는 쪽이 오히려 손해였습니다. 아직 전용 CLI 명령은
+없고, `sprag mode` 실행 시 "Stored config file"로 나오는 설정 파일(맥은
+`~/Library/Application Support/claude-token-saver/config.json`)에서 `codex.delegateMinContext`
+값을 직접 고치면 됩니다. `PreToolUse` 재작성은 spawn을 훅으로 보내는 Codex 버전을 위해 남아
+있을 뿐, 0.159.2에서는 호출되지 않습니다. 위임 원장은 자식이 쓴 토큰을 부모 모델 단가로 환산한
+추정치이며, 부모가 조율에 쓴 턴은 빼지 않습니다. 끝나기 전에 중단된 자식은 부모의 일을 대신하지
+못했으므로, 그 비용 전액을 손실로 기록하고 항목에 `aborted`를 표시합니다.
+
 SessionStart는 캐시된 후보를 읽고 필요할 때 별도 프로세스에서 갱신합니다. 명시적인 `--refresh`는
-대기 주기를 건너뜁니다. `seed`는 Claude의 Haiku·Sonnet 프리셋을 가져오지 않으며,
+대기 주기를 건너뜁니다.
+
+Codex 0.159.2는 훅 하나가 넘긴 컨텍스트를 약 2,450토큰까지만 보존하고, 그보다 길면 가운데를
+잘라 냅니다. 그래서 SessionStart는 추정치 2,000토큰 안에 들어가는 항목만 잘리지 않은 상태로
+넣습니다. 우선순위는 ratchet 룰, 한국어 지침, 응집성 지침, 문서 변환 안내, 제안 순입니다. 들어가지
+못한 룰과 지침은 Sprag 데이터 디렉터리의 프로젝트별 파일에 쓰고, 컨텍스트 첫머리에서 그 파일을
+먼저 읽으라고 안내합니다. rollout의 `originator`로 `codex exec` 실행을 알아보며, 답할 사람이
+없으므로 seed 제안과 route 안내를 넣지 않습니다.
+ `seed`는 Claude의 Haiku·Sonnet 프리셋을 가져오지 않으며,
 Codex의 수락·거절 기록도 Claude 기록과 분리합니다.
 
 ## 래칫 규칙
@@ -158,9 +188,18 @@ sprag capabilities --agent codex
 하위 실행의 토큰을 고정하고 부모·자식 단가를 각각 적용한 차이이므로, 실제 청구서의 절감액은
 아닙니다. 손해는 음수로 남기며 단가나 사용량이 없으면 0 대신 미상으로 표시합니다.
 
-단가는 설정된 LiteLLM의 `/model/info`에서 읽습니다. 공급자가 다른 동명 모델을 섞지 않고,
-같은 별칭 아래 배포 단가가 다르면 계산하지 않습니다. 단가 캐시는 7일 동안 사용하며 이미
-계산한 실행은 단가 사본을 보존합니다. 직접 OpenAI 연결이나 구독 요금은 추정하지 않습니다.
+단가는 호출이 실제로 거친 경로로 정하며, 두 출처는 서로를 대신하지 않습니다.
+
+- ChatGPT·OpenAI 로그인이나 `api.openai.com`으로 바로 가는 API 키는 내장된 OpenAI 정가를
+  씁니다. 정가는 Standard 등급의 짧은 컨텍스트 단가이고 2026-10-01에 확인했습니다. 긴 컨텍스트
+  할증은 반영하지 않으므로, 그 기준을 넘는 요청은 실제보다 낮게 계산됩니다.
+- LiteLLM 공급자는 그 게이트웨이의 `/model/info` 단가를 씁니다. 같은 별칭 아래 배포 단가가
+  다르면 계산하지 않고, 단가 캐시는 7일 동안 사용합니다. 게이트웨이가 단가를 주지 않는 모델은
+  정가로 채우지 않고 미상으로 둡니다.
+
+공급자가 다른 동명 모델은 섞지 않으며, 이미 계산한 실행은 단가 사본을 보존합니다.
+`sprag delegate rules --agent codex`는 룰마다 실측 위임 건수와 실패율, 절감액을 보여 줍니다.
+실패율의 95% 신뢰 하한이 20%를 넘으면(실측 5건 이상) 조건을 좁히거나 룰을 지우라고 알립니다.
 위임 후 `--refresh`로 원장을 갱신할 수 있고, 아직 일치하지 않은 기록은 7일 동안 찾습니다.
 
 캐시 타이머는 확인된 공급자 정책과 기록된 캐시 사용 시각을 보여 줍니다. 정확한 만료 시각이나

package/docs/CODEX.md

@@ -76,14 +76,14 @@ shared hooks needed by other features.
 | Token report | Table, JSON, or CSV from local Codex rollout logs, with time and project filters |
 | Statusline | `--statusline` or `--format statusline` renders the compact panel once, with wrapping and label/color preferences |
 | Briefing | UserPromptSubmit reports fresh context/limit threshold crossings once per session and threshold cycle |
-| Warning history | `last` and `history` read Codex-only, per-session warning records |
+| Warning history | `last` and `history` read Codex-only, per-session records of context (80%/95%) and rate-limit (90%) warnings and handoffs; cache and TTL chips are not recorded |
 | Handoff | Git state, session/model, recorded context/tokens/limits, and fillable remaining-work sections |
 | Subagents | Opt-in native spawn model routing, scoped category rules, and SubagentStart guidance |
 | Cache timer | Resolved provider retention policy after recorded cache usage; exact expiry is unknown |
 | Route discovery | Repeated simple turns grouped by project, provider, and parent model; no automatic registration |
 | Ratchet detection | Recent repeated command/patch failures produce `ratchet?` candidates |
 | Seed presets | Compatible ratchet rules, separate decisions, explicit registration scope |
-| Routing saved | Sprag-attributed child tokens priced with matching LiteLLM rates; an estimate, not billed savings |
+| Routing saved | Sprag-attributed child tokens priced by the path the call took (OpenAI list prices for direct calls, the gateway's `/model/info` prices for a LiteLLM provider); signed, so a pricier child is a loss; an estimate, not billed savings |
 | Diagnostics | `doctor` checks user config, hook registration, harness, logs, panel activity, and preferences |
 | Capability matrix | `capabilities` lists supported, partial, native, and unsupported areas without invoking a model |
 
@@ -151,12 +151,44 @@ warning records. A handoff file is never overwritten and identifies quota
 values as recorded snapshots, not live responses. Fill in its remaining-work
 sections before using it to continue in another session.
 
-Delegation is independently opt-in via `delegate on`. PreToolUse rewrites native
-`spawn_agent` arguments using Codex's `message`, `model`, and `reasoning_effort`
-fields. It preserves explicit model choices and custom roles, including custom
-overrides of built-in roles. SubagentStart injects scoped ratchets and enabled
-writing guidance. Bounds are instructions, not an enforced tool-call budget.
-Normal Codex sandbox and approval rules still apply. Review new hooks in `/hooks`.
+Delegation is independently opt-in via `delegate on`. As of Codex 0.159.2,
+`spawn_agent` never reaches `PreToolUse` (measured directly: a recording hook
+saw only `Bash` calls while a spawn happened), so the rewrite below cannot see
+or steer it. The live path instead runs at prompt time: `UserPromptSubmit`
+checks the prompt against your category rules and, on a match, appends a
+`[Sprag model routing]` note naming the target model, effort, and a route id.
+That note by itself changes nothing, because Codex's own instructions tell it not to
+spawn subagents unless something explicitly asked for it. So `harness init`'s
+AGENTS.md block adds the missing half: a `[Sprag model routing]` note *is* the
+user's delegation request, and the agent should spawn exactly what it describes
+with `fork_turns "none"`, then wait for it (`wait_agent` with a timeout of at least
+120 seconds) instead of doing the same task itself. Attribution does not depend on the child echoing the
+route id back: `SubagentStart` binds the id to whichever spawned child matches
+the pending route (same parent thread, same target model, within 30 minutes),
+so a route is credited even when the child's own first message never repeats it.
+A hint that no child claimed is closed when the parent's next prompt arrives, so
+a child spawned later for some other reason is not credited to it. That same
+prompt also prices any delegated run the ledger has not joined yet, in a
+detached process, so `Routing saved` follows a delegation by one prompt instead
+of waiting for the next route scan.
+
+The hint is withheld below `codex.delegateMinContext` (default 60000 input
+tokens, read from the parent's own rollout). Measured 2026-09-30: a small
+parent session spends more on the coordinating turn (spawning, waiting,
+verifying) than a delegated child saves, so under the floor Sprag leaves the
+request on the main agent instead of proposing a loss. There is no CLI flag for
+it yet; set it by editing `codex.delegateMinContext` (an integer) in the config
+file `sprag mode` prints under "Stored config file" (`~/Library/Application
+Support/claude-token-saver/config.json` on macOS, `$XDG_CONFIG_HOME/claude-token-saver/config.json`
+or `~/.config/claude-token-saver/config.json` on Linux).
+
+The `PreToolUse` rewrite (native `spawn_agent` arguments using Codex's
+`message`, `model`, and `reasoning_effort` fields, preserving explicit model
+choices and custom roles) is kept for Codex versions that do route spawns
+through hooks; on 0.159.2 it simply never fires. `SubagentStart` injects scoped
+ratchets and enabled writing guidance regardless of which path routed the
+child. Bounds are instructions, not an enforced tool-call budget. Normal Codex
+sandbox and approval rules still apply. Review new hooks in `/hooks`.
 
 ```sh
 sprag delegate on --agent codex
@@ -174,6 +206,13 @@ exact parent model, and prefer project rules over global rules. Matching prompts
 request native delegation; unavailable subagent tools leave work on the main
 agent. Claude tier presets and history are not imported.
 
+The routing ledger (`Routing Saved` below) prices a child's own tokens at the
+parent model's rate as the counterfactual; it does not charge or subtract the
+parent's coordination turn, so a delegation that barely clears the context
+floor can still show a positive but overstated saving. A child that was
+interrupted before it finished replaced no parent work, so its whole cost is
+booked as a loss and the entry is marked `aborted`.
+
 ## Harness Commands
 
 ```sh
@@ -231,6 +270,15 @@ SessionStart reads cached candidates and schedules an eligible refresh outside
 the hook. Small log changes refresh at most daily; a 5 MiB increase can refresh
 after an hour. `--refresh` bypasses that schedule.
 
+Codex 0.159.2 keeps about 2,450 tokens of one hook's context and cuts the
+middle of anything longer. SessionStart therefore fits its parts whole within a
+2,000-token estimate, in priority order: ratchet rules, Korean guidance,
+cohesion guidance, the document note, then offers. Rules and guidance that do
+not fit are written to a per-project file under the Sprag data directory, and
+the context opens with an instruction to read it. `codex exec` runs, recognized
+from the rollout's `originator`, get no seed offer or route notice, since no one
+can answer them.
+
 `seed` offers only compatible ratchet presets, not Claude model-tier presets.
 Accept and skip decisions are separate from Claude. Both seed acceptance and
 route approval require the user's choice of global or project scope. A project
@@ -306,10 +354,24 @@ subagent earns no credit. The estimate holds the child's measured tokens
 constant and prices them at the parent and child rates. Negative differences
 remain negative; this is not a comparison of actual billed totals.
 
-Rates come from the configured LiteLLM `/model/info` endpoint, with agreement
-required across deployments behind an alias. Price snapshots last seven days.
-Providers are kept separate; direct OpenAI/subscription pricing is not inferred.
-Missing rates or usage produce unpriced entries, never invented zeroes. A priced
+Prices follow the path each call took, and the two sources never fall back to
+each other:
+
+- ChatGPT/OpenAI login or an API key straight to `api.openai.com` uses the
+  built-in OpenAI list prices (Standard tier, short-context rates, checked
+  2026-10-01). Long-context surcharges are not modeled, so requests past the
+  long-context threshold are under-priced.
+- A LiteLLM provider uses that gateway's `/model/info` prices, with agreement
+  required across deployments behind an alias. Price snapshots last seven days.
+  A model the gateway does not price stays unpriced; it is not filled in from
+  the list prices.
+
+`sprag delegate rules --agent codex` shows each rule's measured runs, failure
+rate and signed saving. A rule is flagged for review when the 95% lower bound
+of its failure rate exceeds 20% over at least five runs, as on the Claude side.
+
+Providers are kept separate. Negative values are losses: the child ran on a
+pricier model than the parent, and the loss reduces the totals. Missing rates or usage produce unpriced entries, never invented zeroes. A priced
 entry keeps its rate snapshot across later outages. Pending route records are
 matched for seven days; saved ledger entries remain afterward. Run `--refresh`
 after delegation to update the ledger without waiting for the next route scan.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.55.0",
+  "version": "3.57.0",
   "description": "Cut the tokens Claude Code and Codex spend: routes simple work to cheaper models, converts documents to compact Markdown, and shows spend and savings live. Ratchet rules and Korean writing checks included.",
   "type": "module",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "deploy": "node scripts/deploy.mjs",
     "docs:statusline": "node scripts/docs-statusline.mjs",
-    "postinstall": "node bin/cli.js install || true",
+    "postinstall": "node bin/postinstall.js || true",
     "publish:legacy": "node scripts/publish-legacy.mjs",
     "release:notes": "node scripts/release-notes.mjs",
     "site:docs": "node scripts/build-site-docs.mjs",

package/src/agents.js

@@ -20,12 +20,26 @@ const AGENT_MODEL = {
   'haiku-runner': 'haiku',
   'haiku-translate': 'haiku',
   'sonnet-worker': 'sonnet',
+  // A T1 rule names its target by tier alone (`agent: 'sonnet'`), with no
+  // preset agent behind it. Without these the phrase fell through to the
+  // haiku default, and a sonnet rule told the session to delegate to haiku.
+  sonnet: 'sonnet',
+  haiku: 'haiku',
 };
 
-/** True when `<name>.md` exists in the project or user agents directory. */
+/**
+ * True when `<name>.md` exists in the project or user agents directory.
+ *
+ * `root: null` asks about the user directory alone. Text that every project
+ * reads (the global ratchet-model.md) has to be worded from what every project
+ * can see: checked against the current directory, the same rule read
+ * `haiku-explore(model: haiku)` when the scan ran in a project that defines
+ * the agent and `model: haiku` when it ran anywhere else, and each flip
+ * rewrote a file sitting in the prompt-cache prefix of every session.
+ */
 export function agentExists(name, root = process.cwd()) {
   if (!name) return false;
-  return existsSync(join(root, '.claude', 'agents', `${name}.md`)) ||
+  return (root !== null && existsSync(join(root, '.claude', 'agents', `${name}.md`))) ||
     existsSync(join(claudeUserDir(), 'agents', `${name}.md`));
 }
 

package/src/brief.js

@@ -29,6 +29,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, openSync,
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
 import { resolveModelId, isOneMillionModel, effectiveWindow } from './compact-window.js';
+import { liveWindowFor } from './ctx-window-cache.js';
 
 // Context tiers as a fraction of the session's context window. Tier 1 warns
 // (compaction/cost territory ahead), tier 2 urges wrapping up. A session only
@@ -83,14 +84,21 @@ function saveState(state, now) {
  *
  * `observedMax` stays as a floor: it proves a 1M window even when the model id
  * is unreadable (env override, settings we do not resolve).
+ *
+ * `liveWindow` outranks both. It is the size Claude Code reported to the
+ * statusline for this session, so the briefing and the statusline count against
+ * the same window. The model id cannot stand in for it: a model that is 1M
+ * without a `[1m]` suffix reads as 200k there.
  */
-export function ctxWindowFor(observedMax = 0, root = process.cwd()) {
+export function ctxWindowFor(observedMax = 0, root = process.cwd(), { liveWindow = null } = {}) {
   let modelWindow = observedMax > WINDOW_1M_MIN_INPUT ? 1_000_000 : 200_000;
+  const reported = Number.isFinite(liveWindow) && liveWindow > 0;
+  if (reported) modelWindow = liveWindow;
   let window = modelWindow;
   let compactCapped = false;
   try {
     const { model } = resolveModelId(root);
-    if (isOneMillionModel(model)) modelWindow = window = 1_000_000;
+    if (!reported && isOneMillionModel(model)) modelWindow = window = 1_000_000;
     const cap = effectiveWindow(root).value;
     if (cap !== null && cap < window) {
       window = cap;
@@ -104,7 +112,7 @@ export function ctxWindowFor(observedMax = 0, root = process.cwd()) {
  * Last request's input size for THIS session, from the transcript tail.
  * Reads at most TAIL_BYTES — prompt-submit hooks must stay fast.
  */
-export function sessionCtx(transcriptPath, { root = process.cwd() } = {}) {
+export function sessionCtx(transcriptPath, { root = process.cwd(), liveWindow = null } = {}) {
   let size;
   try { size = statSync(transcriptPath).size; } catch { return null; }
   const start = Math.max(0, size - TAIL_BYTES);
@@ -130,7 +138,7 @@ export function sessionCtx(transcriptPath, { root = process.cwd() } = {}) {
     if (total > 0) { input = total; maxInput = Math.max(maxInput, total); }
   }
   if (input == null) return null;
-  const { window, modelWindow, compactCapped } = ctxWindowFor(maxInput, root);
+  const { window, modelWindow, compactCapped } = ctxWindowFor(maxInput, root, { liveWindow });
   return { input, window, modelWindow, compactCapped, pct: input / window };
 }
 
@@ -166,14 +174,15 @@ export function seedSessionBriefed(sessionId, signatures, now = Date.now()) {
  * (recorded via seedSessionBriefed) are skipped; every other fresh signature
  * is emitted, including on the session's first event.
  */
-export async function runBrief({ sessionId, transcriptPath, now = Date.now() }) {
+export async function runBrief({ sessionId, transcriptPath, root = process.cwd(), now = Date.now() }) {
   if (!sessionId) return null;
+  const liveWindow = liveWindowFor(sessionId);
   const state = loadState();
   const s = state.sessions[sessionId] || { ctxTier: 0, briefed: [] };
   const items = [];
 
   // ── context tier crossing (per-session) ──
-  const ctx = transcriptPath ? sessionCtx(transcriptPath) : null;
+  const ctx = transcriptPath ? sessionCtx(transcriptPath, { root, liveWindow }) : null;
   if (ctx) {
     const tier = ctxTierOf(ctx.pct);
     // The tier is not monotonic: auto-compaction drops the live context back to
@@ -238,7 +247,7 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
   // never needed. 200k sessions are exempt (their window is already <= 200k).
   try {
     const cw = await import('./compact-window.js');
-    const st = cw.compactWindowStatus({ root: process.cwd() });
+    const st = cw.compactWindowStatus({ root, liveWindow });
     if (!st.ok) {
       const sig = `compact-window|${st.reason}`;
       const briefed = new Set(s.briefed || []);
@@ -246,7 +255,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만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmtK(st.recommendedMin)}~${fmtK(st.recommendedMax)} 범위를 권장합니다(그 범위 안이면 경고하지 않습니다). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다. 등록: sprag compact-window set --global|--project [--value ${fmtK(st.recommendedMax)}] (기본 ${fmtK(st.recommended)}, 적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
+        items.push(`1M 컨텍스트 모델(${st.model || 'Claude Code 기본 모델'})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmtK(st.recommendedMin)}~${fmtK(st.recommendedMax)} 범위를 권장합니다(그 범위 안이면 경고하지 않습니다). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다. 등록: sprag 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/claude-price.js

@@ -0,0 +1,49 @@
+/**
+ * Claude-side cost by the path the call took. A session on a LiteLLM gateway
+ * (gatewayBase(env) set) is billed by the gateway, so it is priced from its
+ * /model/info table and stays unpriced (null) when the table has no entry;
+ * the Anthropic list table is never a fallback there. Every other session is a
+ * direct call and uses the list table. Kept apart from cost.js because
+ * litellm-models.js imports cost.js, and this needs both.
+ */
+import { estimateCost, estimateCostAcross } from './cost.js';
+import { gatewayPriceFor } from './litellm-models.js';
+import { gatewayBase } from './gateway-auth.js';
+
+export function sessionCost(totals, model, { env = process.env, now } = {}) {
+  if (!gatewayBase(env)) return estimateCost(totals, model);
+  const price = gatewayPriceFor(model, env, now);
+  return price ? estimateCost(totals, model, { price }) : null;
+}
+
+/** One priced part per model that spent tokens, or the whole at its one model. */
+function partsByModel(x) {
+  if (!x.modelTotals) return [{ totals: x.totals, model: x.model }];
+  return Object.entries(x.modelTotals).map(([model, totals]) => ({ totals, model }));
+}
+
+/**
+ * What a session's cost is made of: the session itself and each subagent run
+ * it spawned (parser.js attaches them as `subagentRuns`). A run has its own
+ * model, so it is priced on its own instead of at the session's rate, and a
+ * session or run that switched model is split again so each model's tokens
+ * meet that model's rate. `own` marks the parts that are the session itself.
+ */
+export function pricedParts(session) {
+  if (!session) return [];
+  return [
+    ...partsByModel(session).map((part) => ({ ...part, own: true })),
+    ...(session.subagentRuns || []).flatMap(partsByModel),
+  ];
+}
+
+/** Like estimateCostAcross, plus how many priced parts (a session, a subagent run, or one model's share of either) had no price and were left out. */
+export function sessionCostAcross(sessions, opts = {}) {
+  let unpriced = 0;
+  const total = estimateCostAcross((sessions || []).flatMap(pricedParts), (totals, model) => {
+    const c = sessionCost(totals, model, opts);
+    if (!c) unpriced++;
+    return c;
+  });
+  return { ...total, unpriced };
+}