feat: expose full CLI metadata in SDK types and responses

src/_internal/client.ts

@@ -1,5 +1,5 @@
 import { SubprocessCLITransport } from './transport/subprocess-cli.js';
-import type { ClaudeCodeOptions, Message, CLIOutput, AssistantMessage, CLIAssistantOutput, CLIErrorOutput } from '../types.js';
+import type { ClaudeCodeOptions, Message, CLIOutput, AssistantMessage, CLIAssistantOutput, CLIErrorOutput, CLISystemOutput, CLIResultOutput, SystemMessage, ResultMessage } from '../types.js';
 import { detectErrorType, createTypedError } from '../errors.js';
 import { loadSafeEnvironmentOptions } from '../environment.js';
 import { applyEnvironmentOptions } from './options-merger.js';
@@ -53,33 +53,58 @@ export class InternalClient {
           session_id: assistantMsg.session_id
         } as AssistantMessage;
       }
-
-      case 'system':
-        // System messages (like init) - skip these
-        return null;
-
+
+      case 'system': {
+        // System init messages - now expose full capabilities data
+        const systemMsg = output as CLISystemOutput;
+        return {
+          type: 'system',
+          subtype: systemMsg.subtype,
+          session_id: systemMsg.session_id,
+          model: systemMsg.model,
+          claude_code_version: systemMsg.claude_code_version,
+          permissionMode: systemMsg.permissionMode,
+          apiKeySource: systemMsg.apiKeySource,
+          output_style: systemMsg.output_style,
+          cwd: systemMsg.cwd,
+          uuid: systemMsg.uuid,
+          tools: systemMsg.tools,
+          mcp_servers: systemMsg.mcp_servers,
+          slash_commands: systemMsg.slash_commands,
+          agents: systemMsg.agents,
+          skills: systemMsg.skills
+        } as SystemMessage;
+      }
+
       case 'result': {
-        // Result message with usage stats - return it
-        const resultMsg = output as any; // Type assertion for now
+        // Result message with full metadata - return all fields
+        const resultMsg = output as CLIResultOutput;
         return {
           type: 'result',
           subtype: resultMsg.subtype,
           content: resultMsg.content || '',
           session_id: resultMsg.session_id,
+          duration_ms: resultMsg.duration_ms,
+          duration_api_ms: resultMsg.duration_api_ms,
+          num_turns: resultMsg.num_turns,
+          is_error: resultMsg.is_error,
+          result: resultMsg.result,
           usage: resultMsg.usage,
-          cost: {
-            total_cost: resultMsg.cost?.total_cost_usd
-          }
-        } as Message;
+          cost: resultMsg.cost,
+          modelUsage: resultMsg.modelUsage,
+          permission_denials: resultMsg.permission_denials,
+          uuid: resultMsg.uuid,
+          total_cost_usd: resultMsg.total_cost_usd
+        } as ResultMessage;
       }
-        
+
       case 'error': {
         const errorOutput = output as CLIErrorOutput;
         const errorMessage = errorOutput.error?.message || 'Unknown error';
         const errorType = detectErrorType(errorMessage);
         throw createTypedError(errorType, errorMessage, errorOutput.error);
       }
-      
+
       default:
         // Skip unknown message types
         return null;

src/index.ts

@@ -58,7 +58,15 @@ export { API_KEY_SAFETY_WARNING } from './environment.js';
 
 // Export new fluent API (backward compatible - original query function still available)
 export { claude, QueryBuilder } from './fluent.js';
-export { ResponseParser, type ToolExecution, type UsageStats } from './parser.js';
+export { 
+  ResponseParser, 
+  type ToolExecution, 
+  type UsageStats,
+  type PerformanceMetrics,
+  type SystemCapabilities,
+  type WebSearchUsage,
+  type CacheBreakdown
+} from './parser.js';
 export { 
   Logger, 
   LogLevel, 

src/parser.ts

@@ -1,4 +1,4 @@
-import type { Message, ToolUseBlock, ResultMessage } from './types.js';
+import type { Message, ToolUseBlock, ResultMessage, SystemMessage, ModelUsageInfo } from './types.js';
 import type { Logger } from './logger.js';
 
 /**
@@ -188,6 +188,122 @@ export class ResponseParser {
     return null;
   }
 
+  /**
+   * Get performance metrics (duration, turns, etc)
+   */
+  async getPerformanceMetrics(): Promise<PerformanceMetrics | null> {
+    await this.consume();
+
+    const resultMsg = this.messages.findLast((msg): msg is ResultMessage => msg.type === 'result');
+    if (!resultMsg) return null;
+
+    return {
+      durationMs: resultMsg.duration_ms,
+      durationApiMs: resultMsg.duration_api_ms,
+      numTurns: resultMsg.num_turns
+    };
+  }
+
+  /**
+   * Get permission denials if any
+   */
+  async getPermissionDenials(): Promise<string[]> {
+    await this.consume();
+
+    const resultMsg = this.messages.findLast((msg): msg is ResultMessage => msg.type === 'result');
+    return resultMsg?.permission_denials ?? [];
+  }
+
+  /**
+   * Get system capabilities and metadata
+   */
+  async getSystemCapabilities(): Promise<SystemCapabilities | null> {
+    await this.consume();
+
+    const systemMsg = this.messages.find((msg): msg is SystemMessage => msg.type === 'system');
+    if (!systemMsg) return null;
+
+    return {
+      model: systemMsg.model,
+      claudeCodeVersion: systemMsg.claude_code_version,
+      permissionMode: systemMsg.permissionMode,
+      apiKeySource: systemMsg.apiKeySource,
+      outputStyle: systemMsg.output_style,
+      cwd: systemMsg.cwd,
+      uuid: systemMsg.uuid,
+      tools: systemMsg.tools ?? [],
+      mcpServers: systemMsg.mcp_servers ?? [],
+      slashCommands: systemMsg.slash_commands ?? [],
+      agents: systemMsg.agents ?? [],
+      skills: systemMsg.skills ?? []
+    };
+  }
+
+  /**
+   * Get per-model usage breakdown
+   */
+  async getModelUsageBreakdown(): Promise<Record<string, ModelUsageInfo> | null> {
+    await this.consume();
+
+    const resultMsg = this.messages.findLast((msg): msg is ResultMessage => msg.type === 'result');
+    return resultMsg?.modelUsage ?? null;
+  }
+
+  /**
+   * Get request UUID for tracking
+   */
+  async getRequestUUID(): Promise<string | null> {
+    await this.consume();
+
+    const resultMsg = this.messages.findLast((msg): msg is ResultMessage => msg.type === 'result');
+    if (resultMsg?.uuid) return resultMsg.uuid;
+
+    // Fallback to system message UUID
+    const systemMsg = this.messages.find((msg): msg is SystemMessage => msg.type === 'system');
+    return systemMsg?.uuid ?? null;
+  }
+
+  /**
+   * Get web search usage statistics
+   */
+  async getWebSearchUsage(): Promise<WebSearchUsage | null> {
+    await this.consume();
+
+    const resultMsg = this.messages.findLast((msg): msg is ResultMessage => msg.type === 'result');
+    if (!resultMsg) return null;
+
+    const totalSearches = resultMsg.usage?.server_tool_use?.web_search_requests ?? 0;
+    const byModel: Record<string, number> = {};
+
+    if (resultMsg.modelUsage) {
+      for (const [model, stats] of Object.entries(resultMsg.modelUsage)) {
+        if (stats.webSearchRequests) {
+          byModel[model] = stats.webSearchRequests;
+        }
+      }
+    }
+
+    return {
+      total: totalSearches,
+      byModel
+    };
+  }
+
+  /**
+   * Get cache tier breakdown (ephemeral 5m vs 1h)
+   */
+  async getCacheBreakdown(): Promise<CacheBreakdown | null> {
+    await this.consume();
+
+    const resultMsg = this.messages.findLast((msg): msg is ResultMessage => msg.type === 'result');
+    if (!resultMsg?.usage?.cache_creation) return null;
+
+    return {
+      ephemeral5m: resultMsg.usage.cache_creation.ephemeral_5m_input_tokens ?? 0,
+      ephemeral1h: resultMsg.usage.cache_creation.ephemeral_1h_input_tokens ?? 0
+    };
+  }
+
   /**
    * Stream messages with a callback (doesn't consume for other methods)
    */
@@ -313,4 +429,47 @@ export interface UsageStats {
   cacheReadTokens: number;
   totalTokens: number;
   totalCost: number;
+}
+
+/**
+ * Performance metrics for a query
+ */
+export interface PerformanceMetrics {
+  durationMs?: number;
+  durationApiMs?: number;
+  numTurns?: number;
+}
+
+/**
+ * System capabilities and metadata
+ */
+export interface SystemCapabilities {
+  model?: string;
+  claudeCodeVersion?: string;
+  permissionMode?: string;
+  apiKeySource?: string;
+  outputStyle?: string;
+  cwd?: string;
+  uuid?: string;
+  tools: string[];
+  mcpServers: Array<{ name: string; status: string }>;
+  slashCommands: string[];
+  agents: string[];
+  skills: string[];
+}
+
+/**
+ * Web search usage statistics
+ */
+export interface WebSearchUsage {
+  total: number;
+  byModel: Record<string, number>;
+}
+
+/**
+ * Cache tier breakdown (ephemeral 5m vs 1h)
+ */
+export interface CacheBreakdown {
+  ephemeral5m: number;
+  ephemeral1h: number;
 }