karajan-code 3.2.0 → 3.4.0

package/node_modules/yoctocolors/readme.md

@@ -0,0 +1,138 @@
+<sup>yoctocolors 🌈</sup>
+
+> The smallest and fastest command-line coloring package on the internet
+
+*Check out [Chalk](https://github.com/chalk/chalk) if you want something more mature and comprehensive.*
+
+## Highlights
+
+- Tiny
+- Fast
+- Handles nested colors
+- Tree-shakeable
+- No dependencies
+- Actively maintained
+
+## Install
+
+ESM:
+
+```sh
+npm install yoctocolors
+```
+
+Or CommonJS:
+
+```sh
+npm install yoctocolors-cjs
+```
+
+## Usage
+
+```js
+import colors from 'yoctocolors';
+
+console.log(colors.red('Yo!'));
+
+console.log(colors.blue(`Welcome to the ${colors.green('yoctocolors')} package!`));
+```
+
+You can also import colors as named imports:
+
+```js
+import {red, blue, green} from 'yoctocolors';
+
+console.log(red('Yo!'));
+
+console.log(blue(`Welcome to the ${green('yoctocolors')} package!`));
+```
+
+*This package supports [basic color detection](https://nodejs.org/api/tty.html#writestreamhascolorscount-env). Colors can be forcefully enabled by setting the `FORCE_COLOR` environment variable to `1` and can be forcefully disabled by setting `NO_COLOR` or `NODE_DISABLE_COLORS` to any value. [More info.](https://nodejs.org/api/tty.html#writestreamgetcolordepthenv)*
+
+## Styles
+
+### Modifiers
+
+- `reset` - Reset the current style.
+- `bold` - Make the text bold.
+- `dim` - Make the text have lower opacity.
+- `italic` - Make the text italic. *(Not widely supported)*
+- `underline` - Put a horizontal line above the text. *(Not widely supported)*
+- `overline` - Put a horizontal line below the text. *(Not widely supported)*
+- `inverse`- Invert background and foreground colors.
+- `hidden` - Print the text but make it invisible.
+- `strikethrough` - Put a horizontal line through the center of the text. *(Not widely supported)*
+
+### Colors
+
+- `black`
+- `red`
+- `green`
+- `yellow`
+- `blue`
+- `magenta`
+- `cyan`
+- `white`
+- `gray`
+- `redBright`
+- `greenBright`
+- `yellowBright`
+- `blueBright`
+- `magentaBright`
+- `cyanBright`
+- `whiteBright`
+
+### Background colors
+
+- `bgBlack`
+- `bgRed`
+- `bgGreen`
+- `bgYellow`
+- `bgBlue`
+- `bgMagenta`
+- `bgCyan`
+- `bgWhite`
+- `bgGray`
+- `bgRedBright`
+- `bgGreenBright`
+- `bgYellowBright`
+- `bgBlueBright`
+- `bgMagentaBright`
+- `bgCyanBright`
+- `bgWhiteBright`
+
+## Prior art
+
+Yes
+
+## Benchmark
+
+```sh
+$ ./benchmark.js
+┌─────────┬────────────────┬─────────────┐
+│ (index) │ library        │ ops/sec     │
+├─────────┼────────────────┼─────────────┤
+│ 0       │ 'yoctocolors'  │ '8,000,000' │
+│ 1       │ 'colorette'    │ '8,000,000' │
+│ 2       │ 'picocolors'   │ '8,000,000' │
+│ 3       │ 'nanocolors'   │ '5,988,024' │
+│ 4       │ 'chalk'        │ '4,807,692' │
+│ 5       │ 'kleur/colors' │ '4,807,692' │
+│ 6       │ 'kleur'        │ '4,784,689' │
+│ 7       │ 'ansi-colors'  │ '2,178,649' │
+│ 8       │ 'cli-color'    │ '585,138'   │
+└─────────┴────────────────┴─────────────┘
+```
+
+*See [benchmark.js](benchmark.js).*
+
+## FAQ
+
+### What is yocto?
+
+[It was the smallest official unit prefix in the metric system until 2022.](https://en.wikipedia.org/wiki/Yocto-) Much smaller than nano.
+
+## Related
+
+- [yoctodelay](https://github.com/sindresorhus/yoctodelay) - Delay a promise a given amount of time
+- [chalk](https://github.com/chalk/chalk) - Terminal string styling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -84,6 +84,7 @@
   },
   "dependencies": {
     "@babel/parser": "^7.29.7",
+    "@karajan/core": "*",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
@@ -99,6 +100,9 @@
     "valibot": "^1.4.1",
     "web-tree-sitter": "^0.26.9"
   },
+  "bundleDependencies": [
+    "@karajan/core"
+  ],
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.1.8",

package/packages/hu-board/public/utils/board-view.js

@@ -40,6 +40,9 @@ async function renderBoard() {
       api(`/api/projects/${encodeURIComponent(selectedProject)}/cost`).catch(() => null),
     ]);
     const costSummary = projectCost ? formatProjectCostSummary(projectCost) : null;
+    // Φ0-G (KJC-TSK-0525): aggregated cache-hit badge at the project
+    // header, rendered alongside the project cost chip.
+    const cacheSummary = projectCost ? formatCacheRatio(projectCost.cachedTokens, projectCost.tokensIn) : null;
 
     // Pre-resolve project initials + name for every distinct project_id in
     // the fetched stories so `renderStoryCard` is synchronous and the header
@@ -101,6 +104,7 @@ async function renderBoard() {
         ` : ''}
         <span class="section-header__count">${stories.length} stories</span>
         ${costSummary ? `<span class="section-header__cost" title="${esc(costSummary.tooltip)}">💵 ${esc(costSummary.label)}</span>` : ''}
+        ${cacheSummary ? `<span class="section-header__cache" title="${esc(cacheSummary.tooltip)}">${esc(cacheSummary.label)}</span>` : ''}
         ${isRunning ? `
           <button id="running-badge-btn" class="section-header__badge"
                 style="margin-left:auto;padding:4px 10px;font-size:0.8rem;background:var(--color-yellow,#eab308);color:#000;border-radius:var(--radius-sm);font-weight:600;border:none;cursor:pointer;"
@@ -381,6 +385,13 @@ function renderStoryCard(story) {
           const c = formatCost(story.cost_usd);
           return c ? `<span class="story-card__cost" title="${esc(c.tooltip)}">💵 ${esc(c.label)}</span>` : '';
         })()}
+        ${(() => {
+          // Φ0-G (KJC-TSK-0525): per-HU cache hit badge. Rendered next to
+          // the cost so users can correlate "this run cost $X and 73% of
+          // input was served from cache" in one glance.
+          const r = formatCacheRatio(story.cached_tokens, story.tokens_in);
+          return r ? `<span class="story-card__cache" title="${esc(r.tooltip)}">${esc(r.label)}</span>` : '';
+        })()}
       </div>
       ${missingTestContract ? `
         <div class="story-card__meta" style="margin-top:4px;font-size:0.75rem;color:var(--color-yellow,#eab308);font-weight:600" title="This HU has no acceptance_tests declared — Run plan will reject it until you add at least one.">

package/packages/hu-board/public/utils/formatters.js

@@ -55,6 +55,26 @@ function formatCost(costUsd) {
   };
 }
 
+// Φ0-G (KJC-TSK-0525): mirror of formatCacheRatio in src/format.js.
+// Kept duplicated because this file is a classic script loaded into
+// the browser, while src/format.js uses ES modules and is consumed by
+// Node tests. See KJC-TSK-0501 header notes above.
+function formatCacheRatio(cachedTokens, tokensIn) {
+  if (cachedTokens === null || cachedTokens === undefined) return null;
+  if (tokensIn === null || tokensIn === undefined) return null;
+  const c = Number(cachedTokens);
+  const t = Number(tokensIn);
+  if (!Number.isFinite(c) || !Number.isFinite(t)) return null;
+  if (t <= 0 || c < 0) return null;
+  const pct = Math.round((c / t) * 1000) / 10;
+  const num = c.toLocaleString("en-US");
+  const den = t.toLocaleString("en-US");
+  return {
+    label: `🎯 ${pct}%`,
+    tooltip: `Cache hits: ${num} / ${den} input tokens (${pct}%)`,
+  };
+}
+
 function formatProjectCostSummary(cost) {
   if (!cost || typeof cost !== "object") return null;
   const total = Number(cost.totalUsd);
@@ -63,6 +83,9 @@ function formatProjectCostSummary(cost) {
   if (total === 0 && byPlan.length === 0) return null;
 
   const lines = [`Total: $${total.toFixed(4)}`];
+  // Φ0-G (KJC-TSK-0525): aggregate cache hits line + per-plan suffix.
+  const projCache = formatCacheRatio(cost.cachedTokens, cost.tokensIn);
+  if (projCache) lines.push(`Cache: ${projCache.tooltip.split(": ")[1]}`);
   if (byPlan.length > 0) {
     lines.push("By plan:");
     for (const p of byPlan) {
@@ -70,7 +93,11 @@ function formatProjectCostSummary(cost) {
       if (!Number.isFinite(planTotal)) continue;
       const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
       const planLabel = p?.planId || "unassigned";
-      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})`);
+      const cachePct = p?.cachedRatioPct;
+      const cacheSuffix = (cachePct !== null && cachePct !== undefined && Number.isFinite(Number(cachePct)))
+        ? ` 🎯 ${cachePct}%`
+        : "";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})${cacheSuffix}`);
     }
   }
   const unk = cost.unknownModelTokens;

package/packages/hu-board/src/db.js

@@ -328,6 +328,13 @@ export function initDb() {
   // renders "—" while NULL. Stored as REAL so the SQL aggregations in
   // Cost E (/api/projects/:id/cost) can SUM directly without parsing.
   try { db.exec('ALTER TABLE stories ADD COLUMN cost_usd REAL'); } catch { /* already migrated */ }
+  // KJC-TSK-0525 (Φ0-G): persisted cached/input tokens per HU so the
+  // board can render the "🎯 N% cached" badge without re-parsing the
+  // session summary. NULL = unmeasured (older runs, cold runs without
+  // cache support). INTEGER because providers report token counts as
+  // ints. Ratio is computed at read time as cached_tokens / tokens_in.
+  try { db.exec('ALTER TABLE stories ADD COLUMN cached_tokens INTEGER'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN tokens_in INTEGER'); } catch { /* already migrated */ }
   try { db.exec('CREATE INDEX IF NOT EXISTS idx_stories_plan ON stories(plan_id)'); } catch { /* ignore */ }
 
   // is_test (KJC-TSK-0371 — board polish #3): per-project flag that
@@ -530,6 +537,35 @@ export function setStoryCost(storyId, costUsd) {
   return res.changes > 0;
 }
 
+/**
+ * Persist cached/input tokens for a HU (KJC-TSK-0525, Φ0-G). Called by
+ * the orchestrator alongside `setStoryCost` once the HU finishes. Both
+ * values come from `BudgetTracker.since(huCursor)` (Φ0-E). Pass `null`
+ * to clear either cell. Non-finite numbers throw so callers don't
+ * silently null-out real telemetry.
+ *
+ * @param {string} storyId
+ * @param {number|null} cachedTokens
+ * @param {number|null} tokensIn
+ * @returns {boolean} true when the row existed and was updated
+ */
+export function setStoryCachedTokens(storyId, cachedTokens, tokensIn) {
+  const coerce = (v, name) => {
+    if (v === null || v === undefined) return null;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n < 0) {
+      throw new Error(`setStoryCachedTokens: ${name} must be a non-negative finite number or null (got ${v})`);
+    }
+    return Math.round(n);
+  };
+  const cached = coerce(cachedTokens, 'cachedTokens');
+  const tin = coerce(tokensIn, 'tokensIn');
+  const res = getDb()
+    .prepare('UPDATE stories SET cached_tokens = ?, tokens_in = ?, updated_at = ? WHERE id = ?')
+    .run(cached, tin, new Date().toISOString(), storyId);
+  return res.changes > 0;
+}
+
 /**
  * List every distinct `plan_id` stamped on the stories of a given project.
  * Used by "mark plan ready" so the board can act on each plan of a project
@@ -643,9 +679,13 @@ export function getProjectCost(projectId) {
     .get(projectId);
   if (!project) return null;
 
+  // Φ0-G: cached_tokens / tokens_in are nullable independently of
+  // cost_usd, so we read all three columns but keep cost as the
+  // primary filter (a row with only cache telemetry but no $ should
+  // not appear in the per-plan totals — cost rules the byPlan list).
   const rows = getDb()
     .prepare(
-      `SELECT plan_id, cost_usd FROM stories
+      `SELECT plan_id, cost_usd, cached_tokens, tokens_in FROM stories
        WHERE project_id = ? AND cost_usd IS NOT NULL`
     )
     .all(projectId);
@@ -653,24 +693,43 @@ export function getProjectCost(projectId) {
   const round4 = (n) => Math.round(n * 10000) / 10000;
   const byPlanMap = new Map();
   let totalUsd = 0;
+  let totalCached = 0;
+  let totalTokensIn = 0;
   for (const r of rows) {
     const planId = r.plan_id || 'unassigned';
     const cost = Number(r.cost_usd);
     if (!Number.isFinite(cost)) continue;
     totalUsd += cost;
-    const cur = byPlanMap.get(planId) || { planId, totalUsd: 0, huCount: 0 };
+    const cached = Number(r.cached_tokens);
+    const tin = Number(r.tokens_in);
+    if (Number.isFinite(cached) && cached >= 0) totalCached += cached;
+    if (Number.isFinite(tin) && tin >= 0) totalTokensIn += tin;
+    const cur = byPlanMap.get(planId) || { planId, totalUsd: 0, huCount: 0, cachedTokens: 0, tokensIn: 0 };
     cur.totalUsd += cost;
     cur.huCount += 1;
+    if (Number.isFinite(cached) && cached >= 0) cur.cachedTokens += cached;
+    if (Number.isFinite(tin) && tin >= 0) cur.tokensIn += tin;
     byPlanMap.set(planId, cur);
   }
 
+  const ratio = (cached, tin) => tin > 0 ? Math.round((cached / tin) * 1000) / 10 : null;
   const byPlan = Array.from(byPlanMap.values())
-    .map((p) => ({ planId: p.planId, totalUsd: round4(p.totalUsd), huCount: p.huCount }))
+    .map((p) => ({
+      planId: p.planId,
+      totalUsd: round4(p.totalUsd),
+      huCount: p.huCount,
+      cachedTokens: p.cachedTokens,
+      tokensIn: p.tokensIn,
+      cachedRatioPct: ratio(p.cachedTokens, p.tokensIn),
+    }))
     .sort((a, b) => b.totalUsd - a.totalUsd);
 
   return {
     totalUsd: round4(totalUsd),
     byPlan,
+    cachedTokens: totalCached,
+    tokensIn: totalTokensIn,
+    cachedRatioPct: ratio(totalCached, totalTokensIn),
     unknownModelTokens: { tokensIn: 0, tokensOut: 0, models: [] },
     currency: 'USD',
   };

package/packages/hu-board/src/format.js

@@ -87,6 +87,42 @@ export function formatCost(costUsd) {
   };
 }
 
+/**
+ * Φ0-G (KJC-TSK-0525): per-HU and per-plan cached-tokens badge.
+ *
+ * Returns `{ label, tooltip }` for "🎯 23%" with a tooltip showing the
+ * exact numerator/denominator. Same "don't render 0% when there is no
+ * data" stance as formatCost — returns null when:
+ *   - either arg is null/undefined/non-finite,
+ *   - tokens_in is 0 (no input → ratio undefined, not zero),
+ *   - cached is negative (would only happen from corrupted telemetry).
+ *
+ * The badge intentionally shows 1 decimal to keep narrow runs (e.g.
+ * a 73-token cache out of 1 200) readable without rounding to 0%.
+ *
+ * @param {number|null|undefined} cachedTokens
+ * @param {number|null|undefined} tokensIn
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatCacheRatio(cachedTokens, tokensIn) {
+  // Reject null/undefined explicitly — Number(null) coerces to 0,
+  // which would otherwise render an honest-looking "🎯 0%" badge for
+  // runs where we simply have no telemetry. Same stance as formatCost.
+  if (cachedTokens === null || cachedTokens === undefined) return null;
+  if (tokensIn === null || tokensIn === undefined) return null;
+  const c = Number(cachedTokens);
+  const t = Number(tokensIn);
+  if (!Number.isFinite(c) || !Number.isFinite(t)) return null;
+  if (t <= 0 || c < 0) return null;
+  const pct = Math.round((c / t) * 1000) / 10;
+  const num = c.toLocaleString("en-US");
+  const den = t.toLocaleString("en-US");
+  return {
+    label: `🎯 ${pct}%`,
+    tooltip: `Cache hits: ${num} / ${den} input tokens (${pct}%)`,
+  };
+}
+
 /**
  * Format the aggregated project-level cost chip rendered in the board
  * header. Cost G (KJC-TSK-0518). Consumes the shape returned by
@@ -116,6 +152,11 @@ export function formatProjectCostSummary(cost) {
   if (total === 0 && byPlan.length === 0) return null;
 
   const lines = [`Total: $${total.toFixed(4)}`];
+  // Φ0-G (KJC-TSK-0525): when the API includes project-level cache
+  // counters, show the aggregate cached% line right under the total
+  // so users can see at a glance how much was served from cache.
+  const projCache = formatCacheRatio(cost.cachedTokens, cost.tokensIn);
+  if (projCache) lines.push(`Cache: ${projCache.tooltip.split(": ")[1]}`);
   if (byPlan.length > 0) {
     lines.push("By plan:");
     for (const p of byPlan) {
@@ -123,7 +164,11 @@ export function formatProjectCostSummary(cost) {
       if (!Number.isFinite(planTotal)) continue;
       const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
       const planLabel = p?.planId || "unassigned";
-      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})`);
+      const cachePct = p?.cachedRatioPct;
+      const cacheSuffix = (cachePct !== null && cachePct !== undefined && Number.isFinite(Number(cachePct)))
+        ? ` 🎯 ${cachePct}%`
+        : "";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})${cacheSuffix}`);
     }
   }
   const unk = cost.unknownModelTokens;

package/src/agents/aider-agent.js

@@ -1,6 +1,46 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract token usage from Aider's stdout. Two shapes are supported:
+ *
+ *   1. LiteLLM passthrough — an OpenAI-style JSON `usage` block surfaces
+ *      `prompt_tokens_details.cached_tokens` for prompt-cache hits.
+ *   2. Aider's native footer "Tokens: <sent> sent, <received> received
+ *      [, <cached> cache hit]." (supports comma-separated and `k` suffix).
+ *
+ * Returns `{tokens_in, tokens_out, cached_tokens}` or null when no usage
+ * is found (= unmeasured; callers leave the fields undefined).
+ */
+export function extractAiderUsage(text) {
+  if (!text) return null;
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(t); } catch { continue; }
+    const u = obj?.usage ?? (typeof obj?.prompt_tokens === "number" ? obj : null);
+    if (!u || typeof u.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: u.prompt_tokens,
+      tokens_out: u.completion_tokens ?? 0,
+      cached_tokens: u.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  const m = text.match(/Tokens:\s*([\d.,]+k?)\s*sent,\s*([\d.,]+k?)\s*received(?:,\s*([\d.,]+k?)\s*cache\s*hit)?/i);
+  if (!m) return null;
+  const parse = (s) => {
+    const c = s.replaceAll(",", "");
+    return c.toLowerCase().endsWith("k")
+      ? Math.round(parseFloat(c.slice(0, -1)) * 1000)
+      : Number(c);
+  };
+  const sent = parse(m[1]);
+  const recv = parse(m[2]);
+  if (!Number.isFinite(sent) || !Number.isFinite(recv)) return null;
+  return { tokens_in: sent, tokens_out: recv, cached_tokens: m[3] ? parse(m[3]) : 0 };
+}
+
 export class AiderAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -32,6 +72,7 @@ export class AiderAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractAiderUsage(res.stdout) ?? extractAiderUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/claude-agent.js

@@ -68,8 +68,16 @@ function collectAssistantText(obj) {
 /**
  * Extract usage metrics from stream-json/json NDJSON output.
  * Looks for the "result" line which contains total_cost_usd,
- * usage.input_tokens/output_tokens, and modelUsage.
- * Returns an object with tokens_in, tokens_out, cost_usd, model or null if not found.
+ * usage.input_tokens/output_tokens, cache_read_input_tokens,
+ * cache_creation_input_tokens, and modelUsage.
+ *
+ * `cached_tokens` aggregates both cache_read_input_tokens (tokens served
+ * from Anthropic's automatic prompt cache) and cache_creation_input_tokens
+ * (tokens just written to the cache during this call). The sum represents
+ * the total volume of input that benefited from prompt-caching machinery.
+ *
+ * Returns an object with tokens_in, tokens_out, cached_tokens, cost_usd,
+ * model or null if not found.
  */
 function extractUsageFromStreamJson(raw) {
   const events = parseClaudeEvents(raw);
@@ -79,11 +87,14 @@ function extractUsageFromStreamJson(raw) {
 
     const tokens_in = obj.usage?.input_tokens ?? 0;
     const tokens_out = obj.usage?.output_tokens ?? 0;
+    const cache_read = obj.usage?.cache_read_input_tokens ?? 0;
+    const cache_creation = obj.usage?.cache_creation_input_tokens ?? 0;
+    const cached_tokens = cache_read + cache_creation;
     const cost_usd = obj.total_cost_usd ?? undefined;
     const modelUsage = obj.modelUsage;
     const model = modelUsage ? Object.keys(modelUsage)[0] || null : null;
 
-    return { tokens_in, tokens_out, cost_usd, model };
+    return { tokens_in, tokens_out, cached_tokens, cost_usd, model };
   }
   return null;
 }
@@ -310,6 +321,21 @@ const ALLOWED_TOOLS = [
   "Read", "Write", "Edit", "Bash", "Glob", "Grep"
 ];
 
+/**
+ * Base CLI args for a task (Φ1-D, KJC-PCS-0057). When the role provides the
+ * prompt split in stable/volatile buckets, the stable block travels via
+ * --append-system-prompt — the CLI places cache breakpoints on the system
+ * block, so Anthropic's prompt cache hits on it across iterations — and only
+ * the volatile block goes in the -p message. Without the split, legacy
+ * single-prompt behavior is unchanged.
+ */
+function buildPromptArgs(task) {
+  if (task.stablePrompt && task.volatilePrompt) {
+    return ["-p", task.volatilePrompt, "--append-system-prompt", task.stablePrompt, "--allowedTools", ...ALLOWED_TOOLS];
+  }
+  return ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
+}
+
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -334,7 +360,7 @@ export class ClaudeAgent extends BaseAgent {
   }
 
   async _runTaskExec(task, model, _role) {
-    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
+    const args = buildPromptArgs(task);
     if (model) args.push("--model", model);
 
     // Use stream-json when onOutput is provided to get real-time feedback
@@ -362,7 +388,7 @@ export class ClaudeAgent extends BaseAgent {
   }
 
   async _reviewTaskExec(task, model) {
-    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json", "--verbose"];
+    const args = [...buildPromptArgs(task), "--output-format", "stream-json", "--verbose"];
     if (model) args.push("--model", model);
     const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
       onOutput: task.onOutput,

package/src/agents/codex-agent.js

@@ -2,18 +2,55 @@ import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
 /**
- * Extract token usage from Codex CLI stdout.
- * Codex prints "tokens used\n<number>" at the end, where number may have comma separators.
- * Returns { tokens_out } with the total token count, or null if not found.
- * Since Codex doesn't split input/output, we assign the total to tokens_out
- * as a conservative estimate for cost calculation.
+ * Try to extract an OpenAI-style `usage` JSON block from codex stdout.
+ *
+ * OpenAI's Chat Completions API exposes prompt-cache hits via
+ * `usage.prompt_tokens_details.cached_tokens` (since Aug 2024). Codex
+ * CLI doesn't surface this in its default footer, but newer flags or a
+ * wrapper may emit a JSON `usage` line. We scan stdout line-by-line and
+ * accept the first parseable object that carries `prompt_tokens`.
+ *
+ * Returns `{tokens_in, tokens_out, cached_tokens}` or null when absent.
+ */
+function extractJsonUsage(stdout) {
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(trimmed); } catch { continue; }
+    const usage = obj?.usage ?? (typeof obj?.prompt_tokens === "number" ? obj : null);
+    if (!usage || typeof usage.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: usage.prompt_tokens,
+      tokens_out: usage.completion_tokens ?? 0,
+      cached_tokens: usage.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  return null;
+}
+
+/**
+ * Extract token usage from Codex CLI stdout. Two shapes are supported:
+ *
+ *   1. OpenAI-style JSON `usage` block (preferred):
+ *      `{"usage":{"prompt_tokens":N,"completion_tokens":M,
+ *                 "prompt_tokens_details":{"cached_tokens":C}}}`
+ *      → `{tokens_in:N, tokens_out:M, cached_tokens:C}`.
+ *
+ *   2. Legacy "tokens used\n<number>" footer (codex's default total,
+ *      no cache visibility) → `{tokens_in:0, tokens_out, cached_tokens:0}`.
+ *
+ * Returns null when neither shape is found.
  */
 function extractCodexTokens(stdout) {
-  const match = (stdout || "").match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
+  if (!stdout) return null;
+  const json = extractJsonUsage(stdout);
+  if (json) return json;
+  const match = stdout.match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
   if (!match) return null;
   const total = Number(match[1].replaceAll(/,/g, ""));
   if (!Number.isFinite(total) || total <= 0) return null;
-  return { tokens_in: 0, tokens_out: total };
+  return { tokens_in: 0, tokens_out: total, cached_tokens: 0 };
 }
 
 export class CodexAgent extends BaseAgent {

package/src/agents/gemini-agent.js

@@ -1,6 +1,41 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract Gemini's `usageMetadata` from stdout, including
+ * `cachedContentTokenCount` (Gemini's context-caching API metric,
+ * https://ai.google.dev/api/caching).
+ *
+ * The gemini CLI emits `usageMetadata` as part of its JSON response
+ * shape (today: only `--output-format json`, used in reviewTask; in
+ * plain runTask mode no usage is surfaced). When absent, returns null
+ * so the caller leaves `cached_tokens` undefined (= unmeasured,
+ * distinct from a measured 0).
+ */
+export function extractGeminiUsage(text) {
+  if (!text) return null;
+  const candidates = [];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("{") || t.startsWith("[")) candidates.push(t);
+  }
+  candidates.push(text.trim());
+  for (const candidate of candidates) {
+    let obj;
+    try { obj = JSON.parse(candidate); } catch { continue; }
+    const meta = obj?.usageMetadata
+      ?? obj?.usage_metadata
+      ?? obj?.response?.usageMetadata;
+    if (!meta || typeof meta.promptTokenCount !== "number") continue;
+    return {
+      tokens_in: meta.promptTokenCount,
+      tokens_out: meta.candidatesTokenCount ?? 0,
+      cached_tokens: meta.cachedContentTokenCount ?? 0
+    };
+  }
+  return null;
+}
+
 export class GeminiAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -33,6 +68,7 @@ export class GeminiAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractGeminiUsage(res.stdout) ?? extractGeminiUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }