@cat-factory/executor-harness 1.64.4 → 1.66.0

package/dist/agent-runner.js

@@ -574,7 +574,11 @@ function claudeUsage(raw) {
 export async function runCodex(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
-    let usage;
+    // The running CUMULATIVE total, kept in its reported (inclusive) form plus the cached share
+    // it contains. `PiRunOutcome.usage` needs the inclusive figure — it is the key-rotation
+    // weight — while the fallback call metric below needs the split, so both are derived from
+    // this one value rather than one being reconstructed from the other.
+    let cumulative;
     // Codex reads its credentials from $CODEX_HOME/auth.json with file-backed
     // storage. CRITICAL: this home must live OUTSIDE the cloned checkout (`opts.cwd`)
     // — the blueprint/requirements/conflict-resolver handlers finish with
@@ -635,7 +639,7 @@ export async function runCodex(opts) {
             opts.onProgress(progress);
         const turnUsage = codexUsage(event);
         if (turnUsage)
-            usage = turnUsage;
+            cumulative = turnUsage;
         // A `token_count` event closes a model turn: pair its per-turn usage with the
         // assistant text seen since the previous turn as one telemetry call.
         const perTurn = codexLastTurnUsage(event);
@@ -647,7 +651,8 @@ export async function runCodex(opts) {
                 responseText: redactBody(pendingText, secrets),
                 reasoningText: '',
                 inputTokens: perTurn.inputTokens,
-                cachedInputTokens: perTurn.cachedInputTokens,
+                cacheReadTokens: perTurn.cacheReadTokens,
+                cacheWriteTokens: perTurn.cacheWriteTokens,
                 outputTokens: perTurn.outputTokens,
                 finishReason: null,
             }, opts.onCallMetric);
@@ -673,19 +678,29 @@ export async function runCodex(opts) {
         }, prompt, opts, { ...opts.extraEnv, ...(codexHome ? { CODEX_HOME: codexHome } : {}) }, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
         // single call from the cumulative total + final text so the run is still observable.
-        if (calls.length === 0 && (usage || summary)) {
+        // The cumulative total is inclusive of its cached share exactly as a per-turn one is, so
+        // it is split the same way rather than being filed wholesale as fresh — which would report
+        // a cache-heavy run as if nothing had been cached, the one reading this telemetry exists
+        // to rule out.
+        if (calls.length === 0 && (cumulative || summary)) {
             publishCallMetric(calls, {
                 model: opts.model,
                 promptText: redactBody(JSON.stringify(messages), secrets),
                 messageCount: messages.length,
                 responseText: redactBody(summary, secrets),
                 reasoningText: '',
-                inputTokens: usage?.inputTokens ?? 0,
-                cachedInputTokens: 0,
-                outputTokens: usage?.outputTokens ?? 0,
+                inputTokens: Math.max(0, (cumulative?.inputTokens ?? 0) - (cumulative?.cachedInputTokens ?? 0)),
+                cacheReadTokens: cumulative?.cachedInputTokens ?? 0,
+                // Codex reports no separate cache-WRITE class; 0 rather than guessed.
+                cacheWriteTokens: 0,
+                outputTokens: cumulative?.outputTokens ?? 0,
                 finishReason: null,
             }, opts.onCallMetric);
         }
+        // The outcome's usage is the key-rotation WEIGHT, so it keeps the inclusive input count.
+        const usage = cumulative
+            ? { inputTokens: cumulative.inputTokens, outputTokens: cumulative.outputTokens }
+            : undefined;
         return {
             summary,
             stats,
@@ -765,8 +780,6 @@ function codexPlanProgress(event) {
  * other shapes put it on `usage` / `info.usage` directly. We read the cumulative
  * total when present so the caller can simply overwrite (not sum) — summing
  * cumulative totals across events would multiply-count. Checked most-likely first.
- * `input_tokens` is the TOTAL prompt count (OpenAI semantics: `cached_input_tokens`
- * is a subset already inside it), so it is NOT summed with the cached share.
  */
 function codexUsage(event) {
     const info = isObject(event.info) ? event.info : undefined;
@@ -780,14 +793,21 @@ function codexUsage(event) {
     const output = numberOf(raw.output_tokens);
     if (input === 0 && output === 0)
         return undefined;
-    return { inputTokens: input, outputTokens: output };
+    return {
+        inputTokens: input,
+        cachedInputTokens: numberOf(raw.cached_input_tokens),
+        outputTokens: output,
+    };
 }
 /**
  * Per-TURN Codex token usage off a `token_count` event's `info.last_token_usage` (the
  * delta for the turn just completed, as opposed to `codexUsage`'s cumulative total).
- * `input_tokens` is the total prompt count for the turn and already INCLUDES the cached
- * share (OpenAI semantics), so `cachedInputTokens` is surfaced as the subset it is —
- * NOT added on top (adding it would double-count every cached token).
+ *
+ * OpenAI semantics: `input_tokens` is the turn's WHOLE prompt count and already INCLUDES
+ * the cached share, so the fresh figure is the difference. Clamped at 0 because the two
+ * counts come off the same event and a vendor inconsistency must not mint a negative token
+ * count. Codex reports no separate cache-WRITE class, so that class is 0 here rather than
+ * guessed.
  */
 function codexLastTurnUsage(event) {
     const info = isObject(event.info) ? event.info : undefined;
@@ -799,7 +819,12 @@ function codexLastTurnUsage(event) {
     const output = numberOf(raw.output_tokens);
     if (input === 0 && output === 0)
         return undefined;
-    return { inputTokens: input, cachedInputTokens: cached, outputTokens: output };
+    return {
+        inputTokens: Math.max(0, input - cached),
+        cacheReadTokens: cached,
+        cacheWriteTokens: 0,
+        outputTokens: output,
+    };
 }
 /** Dispatch to the configured subscription harness runner. */
 export function runSubscriptionHarness(harness, opts) {

package/dist/claude-call-aggregator.js

@@ -45,7 +45,8 @@ export function createClaudeCallAggregator(handlers) {
                     reasoning: '',
                     stopReason: null,
                     inputTokens: 0,
-                    cachedInputTokens: 0,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
                     outputTokens: 0,
                     toolResults: [],
                     toolUses: 0,
@@ -57,7 +58,8 @@ export function createClaudeCallAggregator(handlers) {
             pending.reasoning += reasoning;
             pending.toolUses += toolUses;
             pending.inputTokens = Math.max(pending.inputTokens, usage.inputTokens);
-            pending.cachedInputTokens = Math.max(pending.cachedInputTokens, usage.cachedInputTokens);
+            pending.cacheReadTokens = Math.max(pending.cacheReadTokens, usage.cacheReadTokens);
+            pending.cacheWriteTokens = Math.max(pending.cacheWriteTokens, usage.cacheWriteTokens);
             pending.outputTokens = Math.max(pending.outputTokens, usage.outputTokens);
             // A block-split response reports its stop reason on the envelope that carries the end of the
             // message; earlier ones report none. Keep the first non-null rather than the last seen.
@@ -114,7 +116,8 @@ export function createClaudeStreamTelemetry(opts) {
                 responseText: redactBody(call.text, opts.secrets),
                 reasoningText: redactBody(call.reasoning, opts.secrets),
                 inputTokens: call.inputTokens,
-                cachedInputTokens: call.cachedInputTokens,
+                cacheReadTokens: call.cacheReadTokens,
+                cacheWriteTokens: call.cacheWriteTokens,
                 outputTokens: call.outputTokens,
                 finishReason: call.stopReason,
             });

package/dist/claude-stream.js

@@ -51,16 +51,22 @@ export function claudeAssistantContent(content) {
 }
 /**
  * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
- * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
- * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
+ * the cumulative `result` total).
+ *
+ * Anthropic reports all three input classes SEPARATELY and `input_tokens` is already
+ * exclusive of both caches, so the three fields here are orthogonal and additive:
+ * total input = `inputTokens + cacheReadTokens + cacheWriteTokens`. Do NOT re-lump the
+ * reads and the writes — a cache write costs 1.25–2× base input while a read costs ~0.1×,
+ * so a turn that keeps invalidating the prefix and one that rides a warm cache are
+ * indistinguishable once they are summed.
  */
 export function claudeCallUsage(raw) {
     if (!isObject(raw))
-        return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 };
-    const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens);
+        return { inputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0 };
     return {
-        inputTokens: numberOf(raw.input_tokens) + cached,
-        cachedInputTokens: cached,
+        inputTokens: numberOf(raw.input_tokens),
+        cacheReadTokens: numberOf(raw.cache_read_input_tokens),
+        cacheWriteTokens: numberOf(raw.cache_creation_input_tokens),
         outputTokens: numberOf(raw.output_tokens),
     };
 }

package/dist/inline.js

@@ -48,7 +48,7 @@ export async function handleInline(job, opts) {
         return {
             text: outcome.summary,
             finishReason: deriveFinishReason(outcome.callMetrics),
-            ...(outcome.usage ? { usage: outcome.usage } : {}),
+            ...(outcome.usage ? { usage: inlineUsage(outcome.usage, outcome.callMetrics) } : {}),
             ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
         };
     }
@@ -56,3 +56,31 @@ export async function handleInline(job, opts) {
         await rm(cwd, { recursive: true, force: true }).catch(() => { });
     }
 }
+/**
+ * Split the run's coarse usage into the three orthogonal input classes an {@link InlineResult}
+ * carries. `outcome.usage` is the ROTATION-window weight — every billed input bucket summed —
+ * so the split has to come from the per-call metrics, the only channel that kept the classes
+ * apart. Fresh input is likewise taken from the calls rather than derived by subtraction, so a
+ * CLI whose per-call and cumulative counts disagree can never produce a negative class.
+ *
+ * With no per-call telemetry (an older CLI build that streams nothing) the coarse total is
+ * reported as fresh with both cache classes 0. That is the honest reading: nothing is KNOWN to
+ * have been cached, and inventing a split would be worse than admitting the channel is silent.
+ */
+function inlineUsage(usage, calls) {
+    if (!calls?.length) {
+        return {
+            inputTokens: usage.inputTokens,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+            outputTokens: usage.outputTokens,
+        };
+    }
+    const sum = (pick) => calls.reduce((total, call) => total + pick(call), 0);
+    return {
+        inputTokens: sum((call) => call.inputTokens),
+        cacheReadTokens: sum((call) => call.cacheReadTokens),
+        cacheWriteTokens: sum((call) => call.cacheWriteTokens),
+        outputTokens: usage.outputTokens,
+    };
+}

package/dist/subagents.js

@@ -137,7 +137,13 @@ export function startSubagentWatcher(root, opts) {
             return;
         const message = event.message;
         const u = claudeCallUsage(message.usage);
-        if (u.inputTokens === 0 && u.outputTokens === 0)
+        // Every input class counts towards "did this turn report usage at all": a turn riding a
+        // warm cache legitimately reports 0 fresh input, and skipping it would drop precisely the
+        // cache-heavy calls this telemetry exists to weigh.
+        if (u.inputTokens === 0 &&
+            u.cacheReadTokens === 0 &&
+            u.cacheWriteTokens === 0 &&
+            u.outputTokens === 0)
             return;
         const content = Array.isArray(message.content) ? message.content : [];
         const { text, reasoning } = claudeAssistantContent(content);
@@ -154,11 +160,16 @@ export function startSubagentWatcher(root, opts) {
             responseText: redactBody(text, secrets),
             reasoningText: redactBody(reasoning, secrets),
             inputTokens: u.inputTokens,
-            cachedInputTokens: u.cachedInputTokens,
+            cacheReadTokens: u.cacheReadTokens,
+            cacheWriteTokens: u.cacheWriteTokens,
             outputTokens: u.outputTokens,
             finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
         }, opts.onCallMetric);
-        usage.inputTokens += u.inputTokens;
+        // The run-level `usage` is the COARSE rotation-window weight, which counts every billed
+        // input bucket — unlike the per-call metric above, whose `inputTokens` is fresh-only. Sum
+        // all three classes back together here or a cache-heavy subagent looks nearly free to the
+        // rotation.
+        usage.inputTokens += u.inputTokens + u.cacheReadTokens + u.cacheWriteTokens;
         usage.outputTokens += u.outputTokens;
     };
     const NEWLINE = 0x0a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.64.4",
+  "version": "1.66.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,9 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.171.0",
-    "@cat-factory/server": "0.162.1",
-    "@cat-factory/spend": "0.12.100"
+    "@cat-factory/kernel": "0.175.0",
+    "@cat-factory/server": "0.165.0",
+    "@cat-factory/spend": "0.12.104"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -747,7 +747,11 @@ function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number
 export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
-  let usage: { inputTokens: number; outputTokens: number } | undefined
+  // The running CUMULATIVE total, kept in its reported (inclusive) form plus the cached share
+  // it contains. `PiRunOutcome.usage` needs the inclusive figure — it is the key-rotation
+  // weight — while the fallback call metric below needs the split, so both are derived from
+  // this one value rather than one being reconstructed from the other.
+  let cumulative: CodexCumulativeUsage | undefined
 
   // Codex reads its credentials from $CODEX_HOME/auth.json with file-backed
   // storage. CRITICAL: this home must live OUTSIDE the cloned checkout (`opts.cwd`)
@@ -812,7 +816,7 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
     const progress = codexPlanProgress(event)
     if (progress && opts.onProgress) opts.onProgress(progress)
     const turnUsage = codexUsage(event)
-    if (turnUsage) usage = turnUsage
+    if (turnUsage) cumulative = turnUsage
     // A `token_count` event closes a model turn: pair its per-turn usage with the
     // assistant text seen since the previous turn as one telemetry call.
     const perTurn = codexLastTurnUsage(event)
@@ -826,7 +830,8 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
           responseText: redactBody(pendingText, secrets),
           reasoningText: '',
           inputTokens: perTurn.inputTokens,
-          cachedInputTokens: perTurn.cachedInputTokens,
+          cacheReadTokens: perTurn.cacheReadTokens,
+          cacheWriteTokens: perTurn.cacheWriteTokens,
           outputTokens: perTurn.outputTokens,
           finishReason: null,
         },
@@ -862,7 +867,11 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
 
     // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
     // single call from the cumulative total + final text so the run is still observable.
-    if (calls.length === 0 && (usage || summary)) {
+    // The cumulative total is inclusive of its cached share exactly as a per-turn one is, so
+    // it is split the same way rather than being filed wholesale as fresh — which would report
+    // a cache-heavy run as if nothing had been cached, the one reading this telemetry exists
+    // to rule out.
+    if (calls.length === 0 && (cumulative || summary)) {
       publishCallMetric(
         calls,
         {
@@ -871,14 +880,23 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
           messageCount: messages.length,
           responseText: redactBody(summary, secrets),
           reasoningText: '',
-          inputTokens: usage?.inputTokens ?? 0,
-          cachedInputTokens: 0,
-          outputTokens: usage?.outputTokens ?? 0,
+          inputTokens: Math.max(
+            0,
+            (cumulative?.inputTokens ?? 0) - (cumulative?.cachedInputTokens ?? 0),
+          ),
+          cacheReadTokens: cumulative?.cachedInputTokens ?? 0,
+          // Codex reports no separate cache-WRITE class; 0 rather than guessed.
+          cacheWriteTokens: 0,
+          outputTokens: cumulative?.outputTokens ?? 0,
           finishReason: null,
         },
         opts.onCallMetric,
       )
     }
+    // The outcome's usage is the key-rotation WEIGHT, so it keeps the inclusive input count.
+    const usage = cumulative
+      ? { inputTokens: cumulative.inputTokens, outputTokens: cumulative.outputTokens }
+      : undefined
     return {
       summary,
       stats,
@@ -949,6 +967,19 @@ function codexPlanProgress(event: Record<string, unknown>): TodoProgress | undef
   return toProgress(items)
 }
 
+/**
+ * Codex's running cumulative usage, kept in the form the CLI reports it: `inputTokens` is the
+ * TOTAL prompt count (OpenAI semantics) with `cachedInputTokens` a SUBSET already inside it,
+ * never a bucket to add on top. The cached share is carried rather than discarded so a
+ * consumer that needs the fresh figure can subtract it at the point of use, instead of the
+ * only two readings of this number being "inclusive" and "lost".
+ */
+interface CodexCumulativeUsage {
+  inputTokens: number
+  cachedInputTokens: number
+  outputTokens: number
+}
+
 /**
  * Best-effort: pull token usage out of a Codex usage event. Codex `exec --json`
  * reports a running CUMULATIVE total on `token_count` events under
@@ -956,12 +987,8 @@ function codexPlanProgress(event: Record<string, unknown>): TodoProgress | undef
  * other shapes put it on `usage` / `info.usage` directly. We read the cumulative
  * total when present so the caller can simply overwrite (not sum) — summing
  * cumulative totals across events would multiply-count. Checked most-likely first.
- * `input_tokens` is the TOTAL prompt count (OpenAI semantics: `cached_input_tokens`
- * is a subset already inside it), so it is NOT summed with the cached share.
  */
-function codexUsage(
-  event: Record<string, unknown>,
-): { inputTokens: number; outputTokens: number } | undefined {
+function codexUsage(event: Record<string, unknown>): CodexCumulativeUsage | undefined {
   const info = isObject(event.info) ? (event.info as Record<string, unknown>) : undefined
   const raw =
     (info && isObject(info.total_token_usage) ? info.total_token_usage : undefined) ??
@@ -972,20 +999,28 @@ function codexUsage(
   const input = numberOf(raw.input_tokens)
   const output = numberOf(raw.output_tokens)
   if (input === 0 && output === 0) return undefined
-  return { inputTokens: input, outputTokens: output }
+  return {
+    inputTokens: input,
+    cachedInputTokens: numberOf(raw.cached_input_tokens),
+    outputTokens: output,
+  }
 }
 
 /**
  * Per-TURN Codex token usage off a `token_count` event's `info.last_token_usage` (the
  * delta for the turn just completed, as opposed to `codexUsage`'s cumulative total).
- * `input_tokens` is the total prompt count for the turn and already INCLUDES the cached
- * share (OpenAI semantics), so `cachedInputTokens` is surfaced as the subset it is —
- * NOT added on top (adding it would double-count every cached token).
+ *
+ * OpenAI semantics: `input_tokens` is the turn's WHOLE prompt count and already INCLUDES
+ * the cached share, so the fresh figure is the difference. Clamped at 0 because the two
+ * counts come off the same event and a vendor inconsistency must not mint a negative token
+ * count. Codex reports no separate cache-WRITE class, so that class is 0 here rather than
+ * guessed.
  */
 function codexLastTurnUsage(event: Record<string, unknown>):
   | {
       inputTokens: number
-      cachedInputTokens: number
+      cacheReadTokens: number
+      cacheWriteTokens: number
       outputTokens: number
     }
   | undefined {
@@ -996,7 +1031,12 @@ function codexLastTurnUsage(event: Record<string, unknown>):
   const cached = numberOf(raw.cached_input_tokens)
   const output = numberOf(raw.output_tokens)
   if (input === 0 && output === 0) return undefined
-  return { inputTokens: input, cachedInputTokens: cached, outputTokens: output }
+  return {
+    inputTokens: Math.max(0, input - cached),
+    cacheReadTokens: cached,
+    cacheWriteTokens: 0,
+    outputTokens: output,
+  }
 }
 
 /** Dispatch to the configured subscription harness runner. */

package/src/claude-call-aggregator.ts

@@ -22,7 +22,8 @@ export interface AggregatedClaudeCall {
   reasoning: string
   stopReason: string | null
   inputTokens: number
-  cachedInputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
   outputTokens: number
   /** The `user` turns carrying this call's tool_result blocks, in arrival order. */
   toolResults: unknown[][]
@@ -95,7 +96,8 @@ export function createClaudeCallAggregator(handlers: {
           reasoning: '',
           stopReason: null,
           inputTokens: 0,
-          cachedInputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
           outputTokens: 0,
           toolResults: [],
           toolUses: 0,
@@ -107,7 +109,8 @@ export function createClaudeCallAggregator(handlers: {
       pending.reasoning += reasoning
       pending.toolUses += toolUses
       pending.inputTokens = Math.max(pending.inputTokens, usage.inputTokens)
-      pending.cachedInputTokens = Math.max(pending.cachedInputTokens, usage.cachedInputTokens)
+      pending.cacheReadTokens = Math.max(pending.cacheReadTokens, usage.cacheReadTokens)
+      pending.cacheWriteTokens = Math.max(pending.cacheWriteTokens, usage.cacheWriteTokens)
       pending.outputTokens = Math.max(pending.outputTokens, usage.outputTokens)
       // A block-split response reports its stop reason on the envelope that carries the end of the
       // message; earlier ones report none. Keep the first non-null rather than the last seen.
@@ -185,7 +188,8 @@ export function createClaudeStreamTelemetry(opts: {
         responseText: redactBody(call.text, opts.secrets),
         reasoningText: redactBody(call.reasoning, opts.secrets),
         inputTokens: call.inputTokens,
-        cachedInputTokens: call.cachedInputTokens,
+        cacheReadTokens: call.cacheReadTokens,
+        cacheWriteTokens: call.cacheWriteTokens,
         outputTokens: call.outputTokens,
         finishReason: call.stopReason,
       })

package/src/claude-stream.ts

@@ -59,19 +59,27 @@ export function claudeAssistantContent(content: unknown[]): {
 
 /**
  * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
- * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
- * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
+ * the cumulative `result` total).
+ *
+ * Anthropic reports all three input classes SEPARATELY and `input_tokens` is already
+ * exclusive of both caches, so the three fields here are orthogonal and additive:
+ * total input = `inputTokens + cacheReadTokens + cacheWriteTokens`. Do NOT re-lump the
+ * reads and the writes — a cache write costs 1.25–2× base input while a read costs ~0.1×,
+ * so a turn that keeps invalidating the prefix and one that rides a warm cache are
+ * indistinguishable once they are summed.
  */
 export function claudeCallUsage(raw: unknown): {
   inputTokens: number
-  cachedInputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
   outputTokens: number
 } {
-  if (!isObject(raw)) return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }
-  const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens)
+  if (!isObject(raw))
+    return { inputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0 }
   return {
-    inputTokens: numberOf(raw.input_tokens) + cached,
-    cachedInputTokens: cached,
+    inputTokens: numberOf(raw.input_tokens),
+    cacheReadTokens: numberOf(raw.cache_read_input_tokens),
+    cacheWriteTokens: numberOf(raw.cache_creation_input_tokens),
     outputTokens: numberOf(raw.output_tokens),
   }
 }

package/src/inline.ts

@@ -54,10 +54,43 @@ export async function handleInline(job: InlineJob, opts: RunOptions): Promise<In
     return {
       text: outcome.summary,
       finishReason: deriveFinishReason(outcome.callMetrics),
-      ...(outcome.usage ? { usage: outcome.usage } : {}),
+      ...(outcome.usage ? { usage: inlineUsage(outcome.usage, outcome.callMetrics) } : {}),
       ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
     }
   } finally {
     await rm(cwd, { recursive: true, force: true }).catch(() => {})
   }
 }
+
+/**
+ * Split the run's coarse usage into the three orthogonal input classes an {@link InlineResult}
+ * carries. `outcome.usage` is the ROTATION-window weight — every billed input bucket summed —
+ * so the split has to come from the per-call metrics, the only channel that kept the classes
+ * apart. Fresh input is likewise taken from the calls rather than derived by subtraction, so a
+ * CLI whose per-call and cumulative counts disagree can never produce a negative class.
+ *
+ * With no per-call telemetry (an older CLI build that streams nothing) the coarse total is
+ * reported as fresh with both cache classes 0. That is the honest reading: nothing is KNOWN to
+ * have been cached, and inventing a split would be worse than admitting the channel is silent.
+ */
+function inlineUsage(
+  usage: { inputTokens: number; outputTokens: number },
+  calls: HarnessCallMetric[] | undefined,
+): NonNullable<InlineResult['usage']> {
+  if (!calls?.length) {
+    return {
+      inputTokens: usage.inputTokens,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      outputTokens: usage.outputTokens,
+    }
+  }
+  const sum = (pick: (call: HarnessCallMetric) => number): number =>
+    calls.reduce((total, call) => total + pick(call), 0)
+  return {
+    inputTokens: sum((call) => call.inputTokens),
+    cacheReadTokens: sum((call) => call.cacheReadTokens),
+    cacheWriteTokens: sum((call) => call.cacheWriteTokens),
+    outputTokens: usage.outputTokens,
+  }
+}

package/src/job.ts

@@ -1251,7 +1251,20 @@ export interface InlineResult {
   text: string
   /** `length` when the model hit its output cap (the reviewer rejects a truncated doc). */
   finishReason?: 'stop' | 'length'
-  usage?: { inputTokens: number; outputTokens: number }
+  /**
+   * The job's token usage with the input side split into its three ORTHOGONAL classes:
+   * `inputTokens` is FRESH input only, so the total input is
+   * `inputTokens + cacheReadTokens + cacheWriteTokens`. Folded from the per-call metrics below,
+   * which is the only channel that knows the split; a CLI that streamed none falls back to the
+   * coarse total with both cache classes 0 — honest, since on that shape nothing is known to
+   * have been cached.
+   */
+  usage?: {
+    inputTokens: number
+    cacheReadTokens: number
+    cacheWriteTokens: number
+    outputTokens: number
+  }
   /** Per-model-call telemetry lifted from the CLI stream (recorded into `llm_call_metrics`). */
   callMetrics?: HarnessCallMetric[]
   /** A structured failure marks a job-level failure even on a clean HTTP exit (see JobResultBase). */

package/src/pi.ts

@@ -509,8 +509,21 @@ export interface HarnessCallMetric {
   responseText: string
   /** The reasoning/thinking trace, as a plain string (`''` when none). */
   reasoningText: string
+  /**
+   * FRESH (uncached) input tokens: exclusive of BOTH cache classes below, so the three
+   * are orthogonal and additive. Every producer normalises to this — reading the already
+   * exclusive field where the vendor reports the classes apart (Anthropic), subtracting
+   * the cached share where the vendor reports an inclusive prompt count (Codex/OpenAI).
+   */
   inputTokens: number
-  cachedInputTokens: number
+  /** Input tokens served from the vendor's prompt cache (~0.1× base input). */
+  cacheReadTokens: number
+  /**
+   * Input tokens written INTO the vendor's cache (1.25–2× base input — dearer than fresh),
+   * kept apart from the reads so a loop that keeps re-writing the prefix is distinguishable
+   * from one riding a warm cache. 0 where the CLI reports no separate write class.
+   */
+  cacheWriteTokens: number
   outputTokens: number
   /** The provider finish/stop reason when the CLI reports one (else null). */
   finishReason: string | null

package/src/subagents.ts

@@ -236,7 +236,16 @@ export function startSubagentWatcher(root: string, opts: SubagentWatcherOptions)
     if (event.type !== 'assistant' || !isObject(event.message)) return
     const message = event.message as Record<string, unknown>
     const u = claudeCallUsage(message.usage)
-    if (u.inputTokens === 0 && u.outputTokens === 0) return
+    // Every input class counts towards "did this turn report usage at all": a turn riding a
+    // warm cache legitimately reports 0 fresh input, and skipping it would drop precisely the
+    // cache-heavy calls this telemetry exists to weigh.
+    if (
+      u.inputTokens === 0 &&
+      u.cacheReadTokens === 0 &&
+      u.cacheWriteTokens === 0 &&
+      u.outputTokens === 0
+    )
+      return
     const content = Array.isArray(message.content) ? message.content : []
     const { text, reasoning } = claudeAssistantContent(content)
     publishCallMetric(
@@ -254,13 +263,18 @@ export function startSubagentWatcher(root: string, opts: SubagentWatcherOptions)
         responseText: redactBody(text, secrets),
         reasoningText: redactBody(reasoning, secrets),
         inputTokens: u.inputTokens,
-        cachedInputTokens: u.cachedInputTokens,
+        cacheReadTokens: u.cacheReadTokens,
+        cacheWriteTokens: u.cacheWriteTokens,
         outputTokens: u.outputTokens,
         finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
       },
       opts.onCallMetric,
     )
-    usage.inputTokens += u.inputTokens
+    // The run-level `usage` is the COARSE rotation-window weight, which counts every billed
+    // input bucket — unlike the per-call metric above, whose `inputTokens` is fresh-only. Sum
+    // all three classes back together here or a cache-heavy subagent looks nearly free to the
+    // rotation.
+    usage.inputTokens += u.inputTokens + u.cacheReadTokens + u.cacheWriteTokens
     usage.outputTokens += u.outputTokens
   }