refactor(claude): improve telemetry logging and token calculation

add debug logging throughout telemetry pipeline for better observability
update comments to clarify token calculation per Anthropic docs

Author: moazbuilds

src/cli/tui/routes/workflow/state/utils.ts

@@ -9,9 +9,9 @@ export function updateAgentTelemetryInList(
   return agents.map((agent) => {
     if (agent.id !== agentId) return agent
 
-    // Context = input tokens (total)
-    // Note: cached tokens are already INCLUDED in tokensIn, not separate
-    // cached is just metadata showing how many of those tokens were served from cache
+    // Per Anthropic docs: total_input = input_tokens + cache_read + cache_creation
+    // tokensIn is pre-calculated as this total by the runner
+    // cached is metadata showing how many tokens were served from/written to cache
     const currentContext = telemetry.tokensIn ?? 0
     const newTokensIn = currentContext > 0 ? currentContext : agent.telemetry.tokensIn
     const newTokensOut = telemetry.tokensOut ?? agent.telemetry.tokensOut
@@ -58,9 +58,9 @@ export function updateControllerTelemetry(
   controller: ControllerState,
   telemetry: Partial<AgentTelemetry>
 ): ControllerState {
-  // Context = input tokens (total)
-  // Note: cached tokens are already INCLUDED in tokensIn, not separate
-  // cached is just metadata showing how many of those tokens were served from cache
+  // Per Anthropic docs: total_input = input_tokens + cache_read + cache_creation
+  // tokensIn is pre-calculated as this total by the runner
+  // cached is metadata showing how many tokens were served from/written to cache
   const currentContext = telemetry.tokensIn ?? 0
   const newTokensIn = currentContext > 0 ? currentContext : controller.telemetry.tokensIn
   const newTokensOut = telemetry.tokensOut ?? controller.telemetry.tokensOut

src/infra/engines/providers/claude/execution/runner.ts

@@ -7,6 +7,7 @@ import { metadata } from '../metadata.js';
 import { expandHomeDir } from '../../../../../shared/utils/index.js';
 import { ENV } from '../config.js';
 import { createTelemetryCapture } from '../../../../../shared/telemetry/index.js';
+import { debug } from '../../../../../shared/logging/logger.js';
 import type { ParsedTelemetry } from '../../../core/types.js';
 import {
   formatThinking,
@@ -104,7 +105,8 @@ function formatStreamJsonLine(line: string): string[] | null {
       // Show status message when session starts
       return [formatStatus('Claude is analyzing your request...')];
     } else if (json.type === 'result') {
-      // Calculate total input tokens (non-cached + cached)
+      // Per Anthropic docs: total_input = input_tokens + cache_read + cache_creation
+      // See: https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance
       const cacheRead = json.usage.cache_read_input_tokens || 0;
       const cacheCreation = json.usage.cache_creation_input_tokens || 0;
       const totalCached = cacheRead + cacheCreation;
@@ -220,9 +222,19 @@ export async function runClaude(options: RunClaudeOptions): Promise<RunClaudeRes
     if (onTelemetry) {
       const captured = telemetryCapture.getCaptured();
       if (captured && captured.tokens) {
-        // tokensIn should be TOTAL input tokens (non-cached + cached)
-        // to match the log output format
+        // Per Anthropic docs: total_input = input_tokens + cache_read + cache_creation
+        // See: https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance
         const totalIn = (captured.tokens.input ?? 0) + (captured.tokens.cached ?? 0);
+
+        debug('[TELEMETRY:2.5-RUNNER] [CLAUDE] Emitting telemetry via onTelemetry callback');
+        debug('[TELEMETRY:2.5-RUNNER] [CLAUDE]   CAPTURED: input=%d, output=%d, cached=%s',
+          captured.tokens.input ?? 0,
+          captured.tokens.output ?? 0,
+          captured.tokens.cached ?? 'none');
+        debug('[TELEMETRY:2.5-RUNNER] [CLAUDE]   TOTAL CONTEXT: %d (input + cached), output=%d',
+          totalIn,
+          captured.tokens.output ?? 0);
+
         onTelemetry({
           tokensIn: totalIn,
           tokensOut: captured.tokens.output ?? 0,

src/infra/engines/providers/claude/telemetryParser.ts

@@ -1,3 +1,5 @@
+import { debug } from '../../../../shared/logging/logger.js';
+
 interface CapturedTelemetry {
   duration?: number;
   cost?: number;
@@ -24,10 +26,18 @@ export function parseTelemetry(json: unknown): CapturedTelemetry | null {
   ) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const data = json as Record<string, any>;
+
+    debug('[TELEMETRY:1-PARSER] [CLAUDE] Received result event with usage data');
+    debug('[TELEMETRY:1-PARSER] [CLAUDE]   RAW: input_tokens=%d, output_tokens=%d, cache_read=%d, cache_creation=%d',
+      data.usage.input_tokens,
+      data.usage.output_tokens,
+      data.usage.cache_read_input_tokens || 0,
+      data.usage.cache_creation_input_tokens || 0);
+
     // Calculate cached tokens from both cache_read_input_tokens and cache_creation_input_tokens
     const cachedTokens = (data.usage.cache_read_input_tokens || 0) + (data.usage.cache_creation_input_tokens || 0);
 
-    return {
+    const result = {
       duration: data.duration_ms,
       cost: data.total_cost_usd,
       tokens: {
@@ -36,6 +46,15 @@ export function parseTelemetry(json: unknown): CapturedTelemetry | null {
         cached: cachedTokens > 0 ? cachedTokens : undefined,
       },
     };
+
+    debug('[TELEMETRY:1-PARSER] [CLAUDE]   PARSED: input=%d, output=%d, cached=%s, duration=%dms, cost=$%s',
+      result.tokens.input,
+      result.tokens.output,
+      result.tokens.cached ?? 'none',
+      result.duration ?? 0,
+      result.cost?.toFixed(6) ?? 'N/A');
+
+    return result;
   }
 
   return null;

src/shared/telemetry/capture.ts

@@ -1,4 +1,5 @@
 import { logTelemetry } from './logger.js';
+import { debug } from '../logging/logger.js';
 import type { EngineType } from '../../infra/engines/index.js';
 import { parseTelemetry as parseClaudeTelemetry } from '../../infra/engines/providers/claude/telemetryParser.js';
 import { parseTelemetry as parseCodexTelemetry } from '../../infra/engines/providers/codex/telemetryParser.js';
@@ -66,6 +67,14 @@ export function createTelemetryCapture(
         const parser = telemetryParsers[engine];
         const result = parser(json);
         if (result) {
+          debug('[TELEMETRY:2-CAPTURE] [%s] Captured telemetry from stream', engine.toUpperCase());
+          if (result.tokens) {
+            debug('[TELEMETRY:2-CAPTURE] [%s]   STORING: input=%d, output=%d, cached=%s',
+              engine.toUpperCase(),
+              result.tokens.input,
+              result.tokens.output,
+              result.tokens.cached ?? 'none');
+          }
           captured = result;
         }
       } catch {
@@ -74,19 +83,40 @@ export function createTelemetryCapture(
     },
 
     getCaptured(): CapturedTelemetry | null {
+      if (captured) {
+        debug('[TELEMETRY:2-CAPTURE] [%s] getCaptured() → input=%d, output=%d, cached=%s',
+          engine.toUpperCase(),
+          captured.tokens?.input ?? 0,
+          captured.tokens?.output ?? 0,
+          captured.tokens?.cached ?? 'none');
+      }
       return captured;
     },
 
     logCapturedTelemetry(exitCode: number): void {
+      debug('[TELEMETRY:2-CAPTURE] [%s] logCapturedTelemetry called (exitCode=%d)', engine.toUpperCase(), exitCode);
+
       if (!captured || !captured.tokens) {
+        debug('[TELEMETRY:2-CAPTURE] [%s]   SKIP: No captured telemetry or tokens', engine.toUpperCase());
         return;
       }
 
       // Validate that token values are actual numbers
       if (typeof captured.tokens.input !== 'number' || typeof captured.tokens.output !== 'number') {
+        debug('[TELEMETRY:2-CAPTURE] [%s]   SKIP: Invalid token types (input=%s, output=%s)',
+          engine.toUpperCase(),
+          typeof captured.tokens.input,
+          typeof captured.tokens.output);
         return;
       }
 
+      debug('[TELEMETRY:2-CAPTURE] [%s]   LOGGING: input=%d, output=%d, cached=%s, cost=$%s',
+        engine.toUpperCase(),
+        captured.tokens.input,
+        captured.tokens.output,
+        captured.tokens.cached ?? 'none',
+        captured.cost?.toFixed(6) ?? 'N/A');
+
       logTelemetry({
         engine,
         model: model || 'default',