sprag-cli 3.55.0 → 3.56.0

package/README.ko.md

@@ -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

@@ -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

@@ -52,7 +52,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';
@@ -592,7 +592,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 });
 

package/docs/CODEX.ko.md

@@ -51,7 +51,7 @@ macOS zsh 환경에서는 설치가 tmux 설치 여부를 먼저 확인합니다
 | 한국어 검사 | 파일 쓰기 후 문체 위반을 검사하며 block·warn·off를 지원합니다 |
 | 상태 표시 | 별도 패널, tmux 패널, 일회성 상태줄을 제공합니다 |
 | 브리핑·이력 | 최신 컨텍스트와 사용량 경고를 알리고 세션별로 저장합니다 |
-| 위임 원장 | Sprag가 위임한 하위 실행과 LiteLLM 단가로 예상 차액을 계산합니다 |
+| 위임 원장 | Sprag가 위임한 하위 실행의 토큰에 호출 경로의 단가를 적용해 예상 차액을 계산합니다. 직접 호출은 OpenAI 정가를, LiteLLM 공급자는 그 게이트웨이의 단가를 씁니다 |
 
 ## 패널과 보고서
 
@@ -108,8 +108,34 @@ 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분 이내)에 새로 뜬 자식을 매칭해 묶습니다.
+
+이 안내는 부모 세션의 컨텍스트가 `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 +184,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,39 @@ 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.
+
+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 +201,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 +265,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 +349,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.56.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": {

package/src/claude-price.js

@@ -0,0 +1,28 @@
+/**
+ * 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;
+}
+
+/** Like estimateCostAcross, plus how many sessions had no price and were left out. */
+export function sessionCostAcross(sessions, opts = {}) {
+  let unpriced = 0;
+  const total = estimateCostAcross(sessions, (totals, model) => {
+    const c = sessionCost(totals, model, opts);
+    if (!c) unpriced++;
+    return c;
+  });
+  return { ...total, unpriced };
+}

package/src/codex-brief.js

@@ -77,6 +77,26 @@ export function runCodexBrief({ sessionId, transcriptPath, cwd, now = Date.now()
   return next.length ? ['[Sprag Codex briefing]', ...next.map((issue) => `${issue.message} ${issue.advice}`)].join('\n') : null;
 }
 
+/**
+ * Append one event outside the warning dedup, such as a handoff the user
+ * wrote. Claude's history records handoffs too, so both agents' timelines
+ * show when work was preserved.
+ */
+export function recordCodexHistoryEvent({ sessionId, project = '', key, level = 'info', message, advice = '', now = Date.now(), dir = userDataDir() } = {}) {
+  if (typeof message !== 'string' || !message) return false;
+  const owner = typeof sessionId === 'string' && sessionId ? sessionId : 'no-session';
+  const directory = stateDir(dir);
+  const file = join(directory, `${hash(owner)}.json`);
+  const state = readState(file);
+  const events = [...state.events, { key, tier: 0, signature: key, level, message, advice,
+    at: new Date(now).toISOString(), sessionId: owner, project }].slice(-200);
+  mkdirSync(directory, { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ ...state, events }) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+  return true;
+}
+
 export function readCodexHistory({ days = 7, sessionId, project, dir = userDataDir(), now = Date.now() } = {}) {
   const directory = stateDir(dir);
   let files;

package/src/codex-cache-policy.js

@@ -6,6 +6,10 @@ import { codexUserDir } from './agent.js';
 import { userDataDir } from './paths.js';
 import { codexBudgetProvider, codexProviderKey } from './codex-budget.js';
 import { codexCachePolicy } from './codex-cache.js';
+import { PRICE_MAX_AGE_MS, gatewayPrices } from './gateway-prices.js';
+import { OPENAI_LIST_PRICES, OPENAI_PRICES_CHECKED_AT } from './openai-prices.js';
+
+export { PRICE_MAX_AGE_MS, rate, deploymentPrice, gatewayPrices, codexRunCost } from './gateway-prices.js';
 
 export const CACHE_POLICY_MAX_AGE_MS = 300000;
 const OPENAI_POLICY = 'https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime';
@@ -51,42 +55,6 @@ export function gatewayCachePolicies(payload) {
     policies[0] && policies.every((p) => JSON.stringify(p) === JSON.stringify(policies[0])) ? policies[0] : null]));
 }
 
-export const PRICE_MAX_AGE_MS = 7 * 86400000;
-const rate = (value) => Number.isFinite(value) && value >= 0 && value < 1 ? value : null;
-
-function deploymentPrice(row) {
-  const info = row?.model_info || {};
-  const mode = typeof info.mode === 'string' ? info.mode : null;
-  if (mode && !['chat', 'responses', 'completion'].includes(mode)) return null;
-  const input = rate(info.input_cost_per_token), output = rate(info.output_cost_per_token);
-  if (input === null || output === null) return null;
-  return { input, output, cacheRead: rate(info.cache_read_input_token_cost), cacheWrite: rate(info.cache_creation_input_token_cost) };
-}
-
-/** Per-token prices by alias. Load-balanced deployments must agree, like cache policy. */
-export function gatewayPrices(payload) {
-  if (!Array.isArray(payload?.data)) throw new Error('LiteLLM model/info returned no model list');
-  const groups = new Map();
-  for (const row of payload.data) {
-    if (typeof row?.model_name !== 'string' || row.model_name.length > 256) continue;
-    groups.set(row.model_name, [...(groups.get(row.model_name) || []), deploymentPrice(row)]);
-  }
-  return Object.fromEntries([...groups].map(([name, prices]) => [name,
-    prices[0] && prices.every((p) => JSON.stringify(p) === JSON.stringify(prices[0])) ? prices[0] : null]));
-}
-
-/**
- * USD for a token mix at one model's prices, or null when a needed rate is
- * missing. Cached input without a cache-read rate is unknown, not free.
- */
-export function codexRunCost({ input = 0, cached = 0, cacheWrite = 0, output = 0 }, price) {
-  if (!price || price.input === null || price.output === null) return null;
-  if (cached > 0 && price.cacheRead === null) return null;
-  // cache_write_input_tokens is billed at the creation rate when one is published, else as input.
-  const uncached = Math.max(0, input - cached - cacheWrite);
-  return uncached * price.input + cached * (price.cacheRead ?? 0) + cacheWrite * (price.cacheWrite ?? price.input) + output * price.output;
-}
-
 function cacheFile(provider, { home = codexUserDir(), dir = userDataDir() } = {}) {
   const key = createHash('sha256').update(JSON.stringify([resolve(home), provider.name, provider.base])).digest('hex').slice(0, 24);
   return join(dir, 'codex-cache-policy', `${key}.json`);
@@ -97,14 +65,31 @@ function gatewayProvider(session, opts) {
   return codexBudgetProvider({ ...opts, providerName: session.provider });
 }
 
-function directPolicy(session, { home = codexUserDir(), now = Date.now() } = {}) {
-  if (session?.provider !== 'openai' || !codexCachePolicy(session.model)) return null;
+/** True when Codex's OpenAI provider talks to api.openai.com itself, not to a proxy. No config = direct. */
+export function isDirectOpenAI(provider, { home = codexUserDir() } = {}) {
+  if (provider !== 'openai') return false;
   try {
     let cfg = {};
     try { cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8')); }
-    catch (e) { if (e.code !== 'ENOENT') return null; }
-    if (cfg.openai_base_url && new URL(cfg.openai_base_url).hostname !== 'api.openai.com') return null;
-  } catch { return null; }
+    catch (e) { if (e.code !== 'ENOENT') return false; }
+    if (cfg.openai_base_url && new URL(cfg.openai_base_url).hostname !== 'api.openai.com') return false;
+  } catch { return false; }
+  return true;
+}
+
+/**
+ * The price table a Codex provider's calls are billed by: OpenAI list prices for
+ * direct calls, the gateway's own /model/info prices for a LiteLLM provider.
+ * Never a fallback chain, so a model the gateway does not price stays unpriced.
+ */
+export function codexPriceBook(provider, litellm, opts = {}) {
+  if (isDirectOpenAI(provider, opts)) return { source: 'list', provider: 'openai', checkedAt: OPENAI_PRICES_CHECKED_AT, prices: OPENAI_LIST_PRICES };
+  if (litellm?.provider === provider) return { ...litellm, source: 'litellm' };
+  return null;
+}
+
+function directPolicy(session, { home = codexUserDir(), now = Date.now() } = {}) {
+  if (!codexCachePolicy(session?.model) || !isDirectOpenAI(session?.provider, { home })) return null;
   return { backend: 'OpenAI', model: session.model, seconds: codexCachePolicy(session.model),
     requestedModel: session.model, provider: session.provider, checkedAt: now, reference: OPENAI_POLICY };
 }

package/src/codex-delegation.js

@@ -7,6 +7,7 @@ import { codexUserDir, codexProviderName } from './agent.js';
 import { categorize, ESCALATE_RE, EDIT_RE } from './route-scan.js';
 import { looksPasted } from './route-inject.js';
 import { newRouteId, recordCodexDelegation } from './codex-ledger.js';
+import { readCodexTailLines } from './codex-parser.js';
 
 export const CODEX_ROUTE_CATEGORIES = ['paste', 'translate', 'explore', 'read', 'check', 'run'];
 const MARKER = '<!-- sprag:codex:delegation -->';
@@ -88,13 +89,50 @@ export function matchCodexModelRule(text, { model, root, provider = codexProvide
   return usable.find((r) => r.scope === 'project') || usable[0] || null;
 }
 
+/**
+ * Input tokens from the rollout's last token_count record, or 0 when the
+ * transcript is missing or unreadable. Only the tail is read: the newest
+ * measurement is always near the end of the file.
+ */
+export function codexContextTokens(transcriptPath) {
+  const lines = readCodexTailLines(transcriptPath, 512 * 1024);
+  if (!lines) return 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line || !line.includes('token_count')) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const n = e?.payload?.type === 'token_count' ? e.payload?.info?.last_token_usage?.input_tokens : undefined;
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return 0;
+}
+
+/**
+ * A prompt-time routing suggestion for Codex 0.159.2, where `spawn_agent`
+ * never reaches PreToolUse (see codexDelegationTool below). Gated on parent
+ * context size: a small parent's own coordination overhead outweighs the
+ * savings from a delegated child (measured 2026-09-30, see docs/CODEX.md).
+ */
 export function codexRouteHint(payload, opts = {}) {
-  const rule = matchCodexModelRule(payload?.prompt, { provider: payload?.model_provider || codexProviderName(), ...opts, model: payload?.model, root: opts.root || payload?.cwd });
+  const provider = payload?.model_provider || codexProviderName();
+  const rule = matchCodexModelRule(payload?.prompt, { provider, ...opts, model: payload?.model, root: opts.root || payload?.cwd });
   if (!rule) return null;
-  return `[Sprag model routing] This request matches the approved ${rule.category} rule: delegate the bounded task to model ${rule.model}`
-    + (rule.effort ? ` with reasoning_effort ${rule.effort}` : '')
-    + '. Use the available native Codex subagent tool and a built-in role. Wait for its result, verify it, and report unfinished work. '
-    + 'Do not spawn another CLI process. If subagent tools or the target model are unavailable, keep the task on the main agent and state that delegation was unavailable.';
+  const minContext = opts.minContext ?? 60000;
+  const ctx = opts.contextTokens ?? codexContextTokens(payload?.transcript_path);
+  if (ctx < minContext) return null;
+  const id = newRouteId();
+  const record = opts.record ?? recordCodexDelegation;
+  try {
+    record({ id, parentSessionId: payload?.session_id ?? null, turnId: payload?.turn_id ?? null, via: 'prompt',
+      source: 'rule', category: rule.category, scope: rule.scope, from: payload?.model, to: rule.model,
+      provider, effort: rule.effort ?? null, contextTokens: ctx }, { dir: opts.dir });
+  } catch { /* Accounting is optional; the hint still applies. */ }
+  return `[Sprag model routing] This request matches the approved ${rule.category} rule (route ${id}). `
+    + `Spawn one sub-agent with model ${rule.model}${rule.effort ? `, reasoning_effort ${rule.effort}` : ''} and fork_turns "none". `
+    + `Give it a self-contained task message that ends with the line <!-- sprag:codex:route id=${id} -->. `
+    + 'Wait for it to finish (call wait_agent with timeout_ms of at least 120000, and again if it times out) and do not do the delegated task yourself while it runs; then verify its result and report unfinished work. Do not spawn another CLI process. '
+    + 'If sub-agent tools or the target model are unavailable, keep the task on the main agent and state that delegation was unavailable.';
 }
 
 function customRole(role, root, home) {
@@ -120,6 +158,8 @@ function customRole(role, root, home) {
   return false;
 }
 
+// Kept for Codex versions that do send spawn_agent through PreToolUse; on
+// 0.159.2 the hook never fires for it, so codexRouteHint above is the live path.
 export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules, dir = userDataDir(), record = recordCodexDelegation } = {}) {
   if (cfg.codex?.delegate !== true) return null;
   const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');

package/src/codex-doctor.js

@@ -12,7 +12,7 @@ export const CODEX_CAPABILITIES = [
   { feature: 'reports', support: 'supported', command: 'sprag --agent codex --format json', note: 'Token usage, cached input, reasoning, session and project filters.' },
   { feature: 'harness', support: 'supported', command: 'sprag harness check --agent codex', note: 'AGENTS.md, overrides, explicit-scope ratchet rule management.' },
   { feature: 'brief', support: 'supported', command: 'sprag brief --agent codex', note: 'Fresh context and limit warnings; change-triggered prompt hook.' },
-  { feature: 'history', support: 'supported', command: 'sprag history --agent codex', note: 'Codex-only session warning records; last shows the latest warning.' },
+  { feature: 'history', support: 'supported', command: 'sprag history --agent codex', note: 'Codex-only records of context (80%/95%) and 5h/weekly rate-limit (90%) warnings, plus handoffs. Cache and TTL chips are not recorded; last shows the latest event.' },
   { feature: 'handoff', support: 'supported', command: 'sprag handoff --agent codex', note: 'Git state and recorded Codex session usage; never reads Claude caps.' },
   { feature: 'korean', support: 'supported', command: 'sprag korean status --agent codex', note: 'Session guidance and recognized write-target lint; shared preference.' },
   { feature: 'cohesion', support: 'supported', command: 'sprag cohesion status --agent codex', note: 'Shared English guidance preference.' },

package/src/codex-harness.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { codexUserDir } from './agent.js';
-import { codexToolEvents, codexLegacyToolEvent, readCodexTailLines } from './codex-parser.js';
+import { codexToolEvents, codexLegacyToolEvent, readCodexTailLines, forkedCopyFilter } from './codex-parser.js';
 
 export const CODEX_BEGIN = '<!-- sprag:codex:harness:begin -->';
 export const CODEX_END = '<!-- sprag:codex:harness:end -->';
@@ -23,7 +23,7 @@ export function codexHarnessPaths(root, scope = 'project') {
 }
 
 export function codexHarnessBlock() {
-  return `${CODEX_BEGIN}\n## Sprag Harness\n\n${sections.map(([name, text], i) => `### ${i + 1}. ${name}\n${text}`).join('\n\n')}\n\nRead the global and project Codex ratchet files before working when present. Run \`sprag harness list --agent codex --global\` and \`sprag harness list --agent codex --project\` to retrieve them. These are instructions, not Claude-style @ imports.\nUse \`sprag doc2md <file> --agent codex\` before reading PDF, Office, or Figma documents. Delegate only through available Codex tools and configured roles; do not assume Claude model names or Task/Agent arguments.\n${CODEX_END}\n`;
+  return `${CODEX_BEGIN}\n## Sprag Harness\n\n${sections.map(([name, text], i) => `### ${i + 1}. ${name}\n${text}`).join('\n\n')}\n\nRead the global and project Codex ratchet files before working when present. Run \`sprag harness list --agent codex --global\` and \`sprag harness list --agent codex --project\` to retrieve them. These are instructions, not Claude-style @ imports.\nUse \`sprag doc2md <file> --agent codex\` before reading PDF, Office, or Figma documents. Delegate only through available Codex tools and configured roles; do not assume Claude model names or Task/Agent arguments. A [Sprag model routing] note on a request means the user has asked for that request to be delegated: spawn the sub-agent it describes (its model, reasoning_effort, fork_turns "none", and a self-contained message ending with the route line it gives), wait for it to finish instead of doing the same task yourself, then verify the result before replying.\n${CODEX_END}\n`;
 }
 
 function range(content) {
@@ -133,11 +133,8 @@ function countable(ev) {
   return true;
 }
 
-/**
- * Repeated failures in a rollout's recent turns, newest-first by count. Reads
- * only the file tail, which is where the current session's recent work is.
- */
-export function codexRatchetCandidates(filePath, { now = Date.now(), turns: window = 30, ttlMs = 30 * 60000, tailBytes = 2 * 1024 * 1024, home } = {}) {
+/** Countable failures in one rollout's last `window` turns. Reads only the file tail. */
+function rolloutFailures(filePath, { window, tailBytes }) {
   const lines = readCodexTailLines(filePath, tailBytes);
   if (!lines) return [];
   const order = [];
@@ -147,11 +144,14 @@ export function codexRatchetCandidates(filePath, { now = Date.now(), turns: wind
   const outputs = [];
   let cwd = null;
   let current = null;
+  const copied = forkedCopyFilter();
   for (const line of lines) {
     // Cheap prefilter: these candidate lines are a small share of a rollout.
-    if (!/"(?:item_completed|exec_command_end|patch_apply_end|task_started|turn_context|session_meta|function_call|function_call_output|custom_tool_call|custom_tool_call_output)"/.test(line)) continue;
+    if (!/"(?:item_completed|exec_command_end|patch_apply_end|task_started|turn_context|session_meta|thread_settings_applied|function_call|function_call_output|custom_tool_call|custom_tool_call_output)"/.test(line)) continue;
     let e;
     try { e = JSON.parse(line); } catch { continue; }
+    // A forked child's copy of the parent history holds the parent's failures, not its own.
+    if (copied(e)) continue;
     const p = e?.payload;
     if (e?.type === 'session_meta' && typeof p?.cwd === 'string') cwd ??= p.cwd;
     if (e?.type === 'turn_context' && typeof p?.cwd === 'string') cwd = p.cwd;
@@ -178,9 +178,20 @@ export function codexRatchetCandidates(filePath, { now = Date.now(), turns: wind
     if (countable(ev)) failures.push(ev);
   }
   const recent = new Set(order.slice(-window));
+  return failures.filter((ev) => recent.has(ev.turn));
+}
+
+/**
+ * Repeated failures in recent turns, newest-first by count. `siblings` are
+ * other rollouts of the same project: every `codex exec` run writes its own
+ * file, so a mistake repeated across runs only shows up when they are read
+ * together. The TTL applies to all of them.
+ */
+export function codexRatchetCandidates(filePath, { now = Date.now(), turns: window = 30, ttlMs = 30 * 60000, tailBytes = 2 * 1024 * 1024, home, siblings = [] } = {}) {
+  const failures = [filePath, ...siblings].filter(Boolean).flatMap((file) => rolloutFailures(file, { window, tailBytes }));
   const groups = new Map();
   for (const ev of failures) {
-    if (!recent.has(ev.turn) || !Number.isFinite(ev.at) || now - ev.at > ttlMs) continue;
+    if (!Number.isFinite(ev.at) || now - ev.at > ttlMs) continue;
     const pattern = codexErrorSignature(ev, { cwd: ev.cwd, home });
     const g = groups.get(pattern) || { pattern, count: 0, lastAt: 0 };
     g.count++;