@saccolabs/pi-claude-cli 0.4.10 → 0.4.12

package/README.md

@@ -48,7 +48,7 @@ Requires the `claude` binary on your login-shell PATH (`npm install -g @anthropi
 - Native tool execution: the CLI runs its own tools; guards are injected as Claude Code PreToolUse hooks via `PI_CLAUDE_CLI_SETTINGS`
 - Reports account rate-limit state (window, reset, overage) to the front-end
   on the `claude-rate-limit` status key — never mixed into turn content
-- Configurable thinking effort across the full ladder (low to max) for all models, with elevated mapping for Opus
+- Configurable thinking effort across the full ladder (low to max), mapped 1:1 for every model: the level the host asks for is the level the CLI gets
 - Cross-platform subprocess management (Windows, macOS, Linux)
 - Inactivity timeout and process registry for cleanup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/event-bridge.ts

@@ -1,6 +1,7 @@
 import type {
   ClaudeApiEvent,
   ClaudeAssistantEnvelope,
+  ClaudeModelUsage,
   ClaudeResultMessage,
   ClaudeUsage,
   TrackedContentBlock,
@@ -151,6 +152,40 @@ export function createEventBridge(
   /** Tool ids already surfaced as markers (envelope arrives once per block). */
   const markedToolIds = new Set<string>();
 
+  /**
+   * Fold per-model spend into one `ClaudeUsage`.
+   *
+   * Every entry counts, including models the session did not pick: a
+   * sub-agent may run a different model, and the auto-titler always does.
+   * Returns undefined when the CLI sent no `modelUsage` (older versions), so
+   * the caller can fall back to the main-agent-only `usage`.
+   *
+   * The folded tokens are priced at the SESSION's model rates by
+   * `calculateCost`. That is exact for sub-agents, which inherit the session
+   * model, and slightly off for a cheaper helper model — a known skew worth
+   * far less than the tokens it stops hiding.
+   */
+  function sumModelUsage(
+    modelUsage: Record<string, ClaudeModelUsage> | undefined,
+  ): ClaudeUsage | undefined {
+    if (!modelUsage) return undefined;
+    const entries = Object.values(modelUsage);
+    if (entries.length === 0) return undefined;
+    const total = {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    };
+    for (const entry of entries) {
+      total.input_tokens += entry.inputTokens ?? 0;
+      total.output_tokens += entry.outputTokens ?? 0;
+      total.cache_read_input_tokens += entry.cacheReadInputTokens ?? 0;
+      total.cache_creation_input_tokens += entry.cacheCreationInputTokens ?? 0;
+    }
+    return total;
+  }
+
   /** Prompt size of one cycle: everything the model read, excluding output. */
   function contextOf(usage: ClaudeUsage): number {
     return (
@@ -569,19 +604,28 @@ export function createEventBridge(
   }
 
   function applyResult(result: ClaudeResultMessage): void {
-    // Authoritative cumulative usage for the whole episode (verified to
-    // equal the per-cycle sums on captured streams; trusted over them).
-    const usage = result.usage;
-    if (usage) {
+    // Authoritative spend for the whole episode. `modelUsage` is preferred
+    // over `usage` because `usage` is the MAIN AGENT ONLY: sub-agents run
+    // inside the CLI and never appear in the parent stream, so their tokens
+    // — often the majority — were simply missing from what the host billed.
+    // Same for helper models like the haiku auto-titler.
+    //
+    // Measured 2026-08-27: a lane's turn reported $2.34 while seven
+    // sub-agents spent 28.6M cache-read tokens on top of it, a 10x
+    // under-report. On a captured single-sub-agent episode `modelUsage`
+    // summed to exactly main + sub-agent (102,641 cache-read / 56,920
+    // cache-write), which is why it is trusted here.
+    const totals = sumModelUsage(result.modelUsage) ?? result.usage;
+    if (totals) {
       cumulativeUsage.input_tokens =
-        usage.input_tokens ?? cumulativeUsage.input_tokens;
+        totals.input_tokens ?? cumulativeUsage.input_tokens;
       cumulativeUsage.output_tokens =
-        usage.output_tokens ?? cumulativeUsage.output_tokens;
+        totals.output_tokens ?? cumulativeUsage.output_tokens;
       cumulativeUsage.cache_read_input_tokens =
-        usage.cache_read_input_tokens ??
+        totals.cache_read_input_tokens ??
         cumulativeUsage.cache_read_input_tokens;
       cumulativeUsage.cache_creation_input_tokens =
-        usage.cache_creation_input_tokens ??
+        totals.cache_creation_input_tokens ??
         cumulativeUsage.cache_creation_input_tokens;
       cycleUsage = {};
       recomputeUsage();

package/src/thinking-config.ts

@@ -2,8 +2,8 @@
  * Thinking effort configuration for mapping pi's ThinkingLevel to Claude CLI --effort flags.
  *
  * Maps pi's reasoning levels (minimal/low/medium/high/xhigh/max) to the CLI's effort
- * levels (low/medium/high/xhigh/max). Opus models keep the elevated mapping where
- * medium becomes high and high becomes max; all other models pass through 1:1.
+ * levels (low/medium/high/xhigh/max). Every model passes through 1:1 apart from
+ * `minimal`, which the CLI has no rung for and which floors at `low`.
  *
  * IMPORTANT: The CLI does NOT support --thinking-budget. Only --effort is supported.
  */
@@ -14,12 +14,23 @@ import type { ThinkingLevel, ThinkingBudgets } from "@earendil-works/pi-ai";
 export type CliEffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
 
 /**
- * Standard model mapping: pi ThinkingLevel -> CLI effort.
- * The CLI accepts the full ladder (low/medium/high/xhigh/max) for current
- * models (verified with claude-fable-5 and claude-sonnet-5 on claude CLI
- * 2.x), so levels pass through 1:1 instead of capping at high.
+ * pi ThinkingLevel -> CLI effort, 1:1 for every rung the CLI has.
+ *
+ * The CLI accepts the full ladder (low/medium/high/xhigh/max) on every current
+ * model — verified with claude-fable-5 and claude-sonnet-5, and on 2026-08-27
+ * with claude-opus-5, where `--effort high`, `xhigh` and `max` were each
+ * accepted and recorded distinctly in the session transcript's `effort` field.
+ *
+ * Opus used to be shifted up a rung here (medium→high, high→max) to compensate
+ * for a cap that no longer exists. That made `high` unrequestable on opus and
+ * was not a private detail: Claude Code skills size their own sub-agent fan-out
+ * from this flag, so a host asking for `high` silently got the widest tier the
+ * skill offered. See https://github.com/agustinsacco/pi-claude-cli/issues/22.
+ *
+ * `minimal` has no CLI rung and floors at `low`. That is a floor, not a shift:
+ * it maps down, and no level maps above what the host asked for.
  */
-const STANDARD_EFFORT_MAP: Record<ThinkingLevel, CliEffortLevel> = {
+const EFFORT_MAP: Record<ThinkingLevel, CliEffortLevel> = {
   minimal: "low",
   low: "low",
   medium: "medium",
@@ -28,30 +39,6 @@ const STANDARD_EFFORT_MAP: Record<ThinkingLevel, CliEffortLevel> = {
   max: "max",
 };
 
-/**
- * Opus model mapping: shifted up for elevated reasoning.
- * Opus models get max capability at high/xhigh/max levels.
- */
-const OPUS_EFFORT_MAP: Record<ThinkingLevel, CliEffortLevel> = {
-  minimal: "low",
-  low: "low",
-  medium: "high", // shifted: standard high
-  high: "max", // shifted: maximum capability
-  xhigh: "max", // Opus gets max
-  max: "max",
-};
-
-/**
- * Detect whether a model ID refers to an Opus model.
- * Uses includes('opus') for forward-compatibility with future Opus versions.
- *
- * @param modelId - The model identifier string
- * @returns true if the model is an Opus variant
- */
-export function isOpusModel(modelId: string): boolean {
-  return modelId.includes("opus");
-}
-
 /**
  * Map pi's ThinkingLevel to a CLI effort string.
  *
@@ -61,13 +48,13 @@ export function isOpusModel(modelId: string): boolean {
  * not token budgets.
  *
  * @param reasoning - Pi's thinking level (undefined = omit flag)
- * @param modelId - Model ID for Opus detection
+ * @param _modelId - Unused; kept so callers need not change. Every model maps alike.
  * @param thinkingBudgets - Custom budgets (logged as unsupported, not applied)
  * @returns CLI effort level string, or undefined if flag should be omitted
  */
 export function mapThinkingEffort(
   reasoning?: ThinkingLevel,
-  modelId?: string,
+  _modelId?: string,
   thinkingBudgets?: ThinkingBudgets,
 ): CliEffortLevel | undefined {
   if (reasoning === undefined) {
@@ -81,7 +68,5 @@ export function mapThinkingEffort(
     );
   }
 
-  const isOpus = modelId ? isOpusModel(modelId) : false;
-  const map = isOpus ? OPUS_EFFORT_MAP : STANDARD_EFFORT_MAP;
-  return map[reasoning];
+  return EFFORT_MAP[reasoning];
 }

package/src/types.ts

@@ -7,14 +7,37 @@ export interface ClaudeStreamEventMessage {
   event: ClaudeApiEvent;
 }
 
+/**
+ * Per-model spend for the episode, keyed by model id.
+ *
+ * This is the ONLY place the CLI accounts for work done outside the main
+ * agent's own transcript: sub-agents (which run inside the CLI and never
+ * appear in the parent stream) and helper models such as the haiku
+ * auto-titler. `result.usage` covers the main agent alone.
+ *
+ * Verified 2026-08-27 on a captured episode with one synchronous sub-agent:
+ * main agent 74,562 cache-read / 26,808 cache-write, sub-agent 28,079 /
+ * 30,112, and `modelUsage` reported exactly the two summed — 102,641 /
+ * 56,920.
+ */
+export interface ClaudeModelUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  costUSD?: number;
+}
+
 export interface ClaudeResultMessage {
   type: "result";
   subtype: "success" | "error";
   result?: string;
   error?: string;
   session_id?: string;
-  /** Cumulative usage across every cycle of the episode (authoritative). */
+  /** Cumulative usage for the MAIN agent across every cycle of the episode. */
   usage?: ClaudeUsage;
+  /** Per-model spend, including sub-agents and helper models. */
+  modelUsage?: Record<string, ClaudeModelUsage>;
   num_turns?: number;
   total_cost_usd?: number;
 }