@miphamai/cli 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/agent/message-bus.ts

@@ -11,6 +11,8 @@
  *   const unread = bus.poll('bg-1')  // messages addressed TO bg-1
  */
 
+export type AgentMessageType = 'message' | 'warning' | 'error'
+
 export interface AgentMessage {
   id: string
   from: string
@@ -19,6 +21,7 @@ export interface AgentMessage {
   message: string
   timestamp: Date
   read: boolean
+  type: AgentMessageType
 }
 
 export class AgentMessageBus {
@@ -29,7 +32,7 @@ export class AgentMessageBus {
    * Post a message from one agent to another.
    * Returns the message ID.
    */
-  post(from: string, to: string, summary: string, message: string): string {
+  post(from: string, to: string, summary: string, message: string, type: AgentMessageType = 'message'): string {
     const id = `msg-${++this.idCounter}`
     this.messages.push({
       id,
@@ -39,6 +42,7 @@ export class AgentMessageBus {
       message,
       timestamp: new Date(),
       read: false,
+      type,
     })
     return id
   }
@@ -91,6 +95,14 @@ export class AgentMessageBus {
     return this.messages.filter((m) => m.to === agentId && !m.read).length
   }
 
+  /**
+   * Get all unread warning messages for an agent.
+   * Does NOT mark them as read — use markRead() for that.
+   */
+  getWarnings(agentId: string): AgentMessage[] {
+    return this.messages.filter((m) => m.to === agentId && m.type === 'warning' && !m.read)
+  }
+
   /**
    * Prune messages older than maxAgeMs. Returns the number pruned.
    */

package/src/agent/sub-agent.ts

@@ -3,7 +3,9 @@ import type { ToolDefinition } from '../shared/index.ts'
 import type { SubAgentType, SubAgentOptions, AgentDefinition } from './types'
 import { createAgentContext } from './agent-context'
 import { getBackgroundAgentRegistry } from './background-registry'
+import { getMessageBus } from './message-bus'
 import type { HookEngine } from '../core/hooks'
+import type { PermissionSystem } from '../core/permission'
 
 const TYPE_SYSTEM_PROMPTS: Record<SubAgentType, string> = {
   general: 'You are a focused sub-agent. Complete the assigned task thoroughly and return results.',
@@ -27,6 +29,7 @@ export class SubAgent {
   constructor(
     private registry: ProviderRegistry,
     private toolRegistry: Map<string, ToolDefinition>,
+    private permission?: PermissionSystem,
     private hookEngine?: HookEngine,
   ) {}
 
@@ -113,6 +116,9 @@ export class SubAgent {
     const agentType = options.type || 'general'
     const agentDef = options.agentDef
 
+    // Resolve execution directory: worktree isolation or process cwd
+    const execCwd = options.worktreePath || process.cwd()
+
     // Resolve system prompt: agentDef > options.systemPrompt > builtin type
     const systemPrompt =
       agentDef?.systemPrompt || options.systemPrompt || TYPE_SYSTEM_PROMPTS[agentType]
@@ -151,6 +157,22 @@ export class SubAgent {
     // 'inherit' means use parent model
     const resolvedModel = modelToUse === 'inherit' ? model : modelToUse
 
+    // Validate resolved model exists in registry; fall back to parent model with warning
+    let finalModel = resolvedModel
+    if (resolvedModel !== model) {
+      const modelExists = this.registry.findModel(resolvedModel) !== undefined
+      if (!modelExists) {
+        const warnMsg = `Warning: model "${resolvedModel}" not found in provider registry. Falling back to "${model}".`
+        console.warn(warnMsg)
+
+        // Post warning to message bus for UI display
+        const bus = getMessageBus()
+        bus.post('system', 'main', `Sub-agent model fallback: ${resolvedModel} → ${model}`, warnMsg, 'warning')
+
+        finalModel = model
+      }
+    }
+
     const chunks: string[] = []
     const MAX_TOOL_TURNS = options.maxTurns || 5
 
@@ -168,7 +190,7 @@ export class SubAgent {
         let turnText = ''
 
         for await (const chunk of provider.chat({
-          model: resolvedModel,
+          model: finalModel,
           messages: currentMessages,
           systemPrompt: currentSystemPrompt,
           tools: toolDefs,
@@ -229,12 +251,24 @@ export class SubAgent {
             continue
           }
 
+          // Security: check permission before executing
+          // Sub-agents run without user interaction — tools requiring approval are rejected
+          if (this.permission?.needsApproval(tool, tu.input)) {
+            currentMessages.push({
+              role: 'user' as const,
+              content:
+                `Tool "${tu.name}" requires user approval (permission: ask). ` +
+                `Cannot execute in non-interactive sub-agent context.`,
+            })
+            continue
+          }
+
           try {
             const result = await tool.execute(tu.input, {
-              cwd: process.cwd(),
+              cwd: execCwd,
               sessionId: 'sub-agent',
               provider: '',
-              model: resolvedModel,
+              model: finalModel,
             })
 
             currentMessages.push({

package/src/agent/types.ts

@@ -44,4 +44,6 @@ export interface SubAgentOptions {
   runInBackground?: boolean
   /** Optional callback for streaming progress chunks during background execution. */
   onProgress?: (chunk: string) => void
+  /** When set, tool executions use this path as cwd (git worktree isolation). */
+  worktreePath?: string
 }

package/src/config/defaults.ts

@@ -13,6 +13,10 @@ export const DEFAULT_CONFIG: MiphamConfig = {
   defaultModel: 'deepseek-v4-pro',
   permission: 'auto',
   providers: DEFAULT_PROVIDERS,
+  marketplace: {
+    strictKnownMarketplaces: [],
+    blockedMarketplaces: [],
+  },
 }
 
 export const DEFAULT_INFERENCE_HOOK_CONFIG: InferenceHookConfig = {

package/src/config/preferences.ts

@@ -0,0 +1,45 @@
+/**
+ * Lightweight preferences store backed by ~/.mipham/preferences.json.
+ * Used for persisting user-level UI state (e.g. last code review effort).
+ *
+ * NOT for config.yml settings — those belong in the YAML config system.
+ * NOT for secrets — this file is plain JSON, not encrypted.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const PREFS_PATH = join(homedir(), '.mipham', 'preferences.json')
+
+function readPrefs(): Record<string, string> {
+  try {
+    if (!existsSync(PREFS_PATH)) return {}
+    const raw = readFileSync(PREFS_PATH, 'utf-8')
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {}
+    return parsed as Record<string, string>
+  } catch {
+    return {}
+  }
+}
+
+function writePrefs(prefs: Record<string, string>): void {
+  try {
+    const dir = join(homedir(), '.mipham')
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
+    writeFileSync(PREFS_PATH, JSON.stringify(prefs, null, 2), { mode: 0o600, encoding: 'utf-8' })
+  } catch {
+    // best-effort; never crash because preferences failed to save
+  }
+}
+
+export function getPreference(key: string, defaultValue: string): string {
+  const prefs = readPrefs()
+  return prefs[key] ?? defaultValue
+}
+
+export function setPreference(key: string, value: string): void {
+  const prefs = readPrefs()
+  prefs[key] = value
+  writePrefs(prefs)
+}

package/src/core/context.ts

@@ -55,6 +55,15 @@ export class ContextManager {
 
   constructor(private config: ContextConfig) {}
 
+  /** Dynamically update the max token limit (e.g., when switching models). */
+  updateMaxTokens(maxTokens: number): void {
+    this.config.maxTokens = maxTokens
+  }
+
+  getMaxTokens(): number {
+    return this.config.maxTokens
+  }
+
   /** Set an optional LLM summarizer for intelligent compaction. */
   setSummarizer(fn: Summarizer): void {
     this.summarizer = fn

package/src/core/engine.ts

@@ -16,6 +16,7 @@ import type { AgentViewManager } from '../agent-view/agent-view-manager'
 import type { SkillsLoader } from '../skills/loader'
 import { getBackgroundAgentRegistry } from '../agent/background-registry'
 import { RulesLoader } from './rules-loader'
+import { UsageTracker } from './usage-tracker'
 import { buildRequest, sendInferenceCheck, isInferenceHookEnabled } from './inference-hook'
 
 export class QueryEngine {
@@ -40,7 +41,7 @@ export class QueryEngine {
     private registry: ProviderRegistry,
     private context: ContextManager,
     private tools: Map<string, ToolDefinition>,
-    private permission: PermissionSystem = new PermissionSystem('bypass'),
+    private permission: PermissionSystem = new PermissionSystem('default'),
   ) {}
 
   /** Register a hook engine for pre/post tool-use lifecycle events. */
@@ -82,6 +83,7 @@ export class QueryEngine {
   private rulesLoader?: RulesLoader
   /** Files touched in the current turn (for rules matching). */
   private touchedFiles: Set<string> = new Set()
+  private usageTracker = new UsageTracker()
   /** Inference hook (DLP) configuration. */
   private inferenceHookConfig?: InferenceHookConfig
 
@@ -238,6 +240,10 @@ export class QueryEngine {
     return this.permission
   }
 
+  getUsageTracker(): UsageTracker {
+    return this.usageTracker
+  }
+
   async *process(userInput: string, signal?: AbortSignal): AsyncGenerator<StreamChunk> {
     // Fire UserPromptSubmit hooks before processing
     if (this.hookEngine) {
@@ -293,6 +299,8 @@ export class QueryEngine {
     let assistantContent = ''
     let reasoningContent = ''
     let thinkingContent = ''
+    let turnApiInputTokens = 0
+    let turnApiOutputTokens = 0
     const toolUses: Array<{ id: string; name: string; input: Record<string, unknown> }> = []
 
     // Stream model response
@@ -331,6 +339,12 @@ export class QueryEngine {
           })
         }
 
+        if (chunk.type === 'usage' && chunk.inputTokens !== undefined) {
+          // Accumulate API-reported token counts for this turn
+          turnApiInputTokens += chunk.inputTokens
+          turnApiOutputTokens += chunk.outputTokens || 0
+        }
+
         if (chunk.type === 'stop') {
           // Add assistant response to context
           if (assistantContent || reasoningContent || thinkingContent) {
@@ -417,6 +431,31 @@ export class QueryEngine {
       })
     }
 
+    // Record API token usage for this turn, attributed to executed tools
+    if (turnApiInputTokens > 0 || turnApiOutputTokens > 0) {
+      if (toolUses.length > 0) {
+        // Attribute tokens equally across all tools invoked this turn
+        const perTool = toolUses.length
+        for (const tu of toolUses) {
+          this.usageTracker.recordApiUsage(
+            Math.round(turnApiInputTokens / perTool),
+            Math.round(turnApiOutputTokens / perTool),
+            tu.name,
+          )
+        }
+      } else {
+        this.usageTracker.recordApiUsage(turnApiInputTokens, turnApiOutputTokens, 'chat')
+      }
+    } else {
+      // Fallback: API doesn't report usage — use char-based estimate
+      const estimated = Math.round((assistantContent.length + userInput.length) / 4)
+      if (toolUses.length > 0) {
+        for (const tu of toolUses) {
+          this.usageTracker.recordEstimatedUsage(Math.round(estimated / toolUses.length), tu.name)
+        }
+      }
+    }
+
     // Inject path-scoped rules for touched files
     this.injectRules()
 
@@ -721,6 +760,7 @@ export class QueryEngine {
         artifactServer: this.artifactServer,
         agentRegistry: this.agentRegistry,
         backgroundAgentRegistry: getBackgroundAgentRegistry(),
+        permissionSystem: this.permission,
       })
 
       // Track touched files for rules matching
@@ -781,6 +821,17 @@ export class QueryEngine {
 
   switchProvider(providerId: string, modelId?: string): void {
     this.registry.switchProvider(providerId, modelId)
+    // Update context manager's max tokens to match the new model's context window
+    if (modelId) {
+      const model = this.registry.findModel(modelId)
+      if (model) {
+        const DISABLE_1M = process.env.MIPHAM_DISABLE_1M_CONTEXT === '1'
+        const maxTokens = (DISABLE_1M && model.contextWindow > 200_000)
+          ? 200_000
+          : model.contextWindow
+        this.context.updateMaxTokens(maxTokens)
+      }
+    }
   }
 
   /** Wrap context compaction with PreCompact/PostCompact hooks. */

package/src/core/permission-config.ts

@@ -1,4 +1,4 @@
-import type { PermissionConfig, PermissionMode } from '../shared/index.ts'
+import type { PermissionConfig, PermissionMode, PermissionRestrictions } from '../shared/index.ts'
 
 const DEFAULT_CONFIG: PermissionConfig = {
   mode: 'default',
@@ -15,11 +15,15 @@ export function loadPermissionConfig(raw: Partial<PermissionConfig> = {}): Permi
     mode: (raw.mode as PermissionMode) || DEFAULT_CONFIG.mode,
     allow: Array.isArray(raw.allow) ? raw.allow : [...DEFAULT_CONFIG.allow],
     deny: Array.isArray(raw.deny) ? raw.deny : [...DEFAULT_CONFIG.deny],
+    restrictions: raw.restrictions ?? undefined,
   }
 }
 
-/** Valid mode transition order for Shift+Tab cycling. */
-export const MODE_CYCLE: PermissionMode[] = [
+/**
+ * Permission modes ordered from least to most permissive.
+ * Used to enforce maxAllowedMode: any mode ranked higher than the cap is forbidden.
+ */
+export const PERMISSION_MODE_HIERARCHY: PermissionMode[] = [
   'default',
   'acceptEdits',
   'plan',
@@ -28,7 +32,67 @@ export const MODE_CYCLE: PermissionMode[] = [
   'bypassPermissions',
 ]
 
-export function nextMode(current: PermissionMode): PermissionMode {
-  const idx = MODE_CYCLE.indexOf(current)
-  return MODE_CYCLE[(idx + 1) % MODE_CYCLE.length]!
+/** Valid mode transition order for Shift+Tab cycling. */
+export const MODE_CYCLE: PermissionMode[] = [...PERMISSION_MODE_HIERARCHY]
+
+/** Resolve which modes are actually permitted given the restrictions. */
+export function getAllowedModes(restrictions?: PermissionRestrictions): PermissionMode[] {
+  let allowed = [...MODE_CYCLE]
+
+  if (restrictions?.forbiddenModes && restrictions.forbiddenModes.length > 0) {
+    const forbidden = new Set(restrictions.forbiddenModes)
+    allowed = allowed.filter((m) => !forbidden.has(m))
+  }
+
+  if (restrictions?.maxAllowedMode) {
+    const capIdx = PERMISSION_MODE_HIERARCHY.indexOf(restrictions.maxAllowedMode)
+    if (capIdx >= 0) {
+      allowed = allowed.filter((m) => PERMISSION_MODE_HIERARCHY.indexOf(m) <= capIdx)
+    }
+  }
+
+  return allowed
+}
+
+/** Check whether a given mode is permitted under the restrictions. */
+export function isModeAllowed(
+  mode: PermissionMode,
+  restrictions?: PermissionRestrictions,
+): boolean {
+  return getAllowedModes(restrictions).includes(mode)
+}
+
+/**
+ * Return the highest allowed mode at or below `desired` given the restrictions.
+ * Used to silently downgrade when a forbidden mode is requested.
+ */
+export function clampMode(
+  desired: PermissionMode,
+  restrictions?: PermissionRestrictions,
+): PermissionMode {
+  const allowed = getAllowedModes(restrictions)
+  if (allowed.includes(desired)) return desired
+
+  // Walk downward through the hierarchy to find the closest allowed mode
+  const desiredIdx = PERMISSION_MODE_HIERARCHY.indexOf(desired)
+  for (let i = desiredIdx - 1; i >= 0; i--) {
+    const candidate = PERMISSION_MODE_HIERARCHY[i]!
+    if (allowed.includes(candidate)) return candidate
+  }
+
+  // Fallback: return the first allowed mode (should always be at least 'default')
+  return allowed[0] ?? 'default'
+}
+
+export function nextMode(
+  current: PermissionMode,
+  restrictions?: PermissionRestrictions,
+): PermissionMode {
+  const allowed = getAllowedModes(restrictions)
+  const idx = allowed.indexOf(current)
+  if (idx === -1) {
+    // Current mode is not in the allowed set — clamp then find next
+    return clampMode(current, restrictions)
+  }
+  return allowed[(idx + 1) % allowed.length]!
 }

package/src/core/permission.ts

@@ -3,10 +3,11 @@ import type {
   PermissionMode,
   PermissionLevel,
   PermissionRule,
+  PermissionRestrictions,
 } from '../shared/index.ts'
 import type { PermissionRuleEntry } from '../shared/index.ts'
 import { matchBashRule, compileRule } from './permission-rules'
-import { loadPermissionConfig, nextMode, MODE_CYCLE } from './permission-config'
+import { loadPermissionConfig, nextMode, clampMode, MODE_CYCLE } from './permission-config'
 
 const VALID_MODES: Set<string> = new Set<string>(MODE_CYCLE)
 
@@ -25,6 +26,9 @@ export class PermissionSystem {
   private checkCache = new Map<string, PermissionLevel>()
   private cacheMode: PermissionMode | null = null
 
+  // ── Org-level restrictions (P0 security) ──
+  private restrictions: PermissionRestrictions | undefined = undefined
+
   /** Invalidate the permission cache (called on any rule/mode change). */
   private invalidateCache(): void {
     this.checkCache.clear()
@@ -44,7 +48,7 @@ export class PermissionSystem {
   // ── Mode management ──
 
   setMode(mode: PermissionMode): void {
-    this.mode = mode
+    this.mode = clampMode(mode, this.restrictions)
     this.invalidateCache()
   }
 
@@ -53,10 +57,26 @@ export class PermissionSystem {
   }
 
   cycleMode(): PermissionMode {
-    this.mode = nextMode(this.mode)
+    this.mode = nextMode(this.mode, this.restrictions)
     return this.mode
   }
 
+  // ── Restrictions (P0: org-level policy gap) ──
+
+  /** Apply org-level permission restrictions. Overwrites any previous restrictions. */
+  setRestrictions(restrictions: PermissionRestrictions | undefined): void {
+    this.restrictions = restrictions
+    // Re-clamp current mode against new restrictions
+    if (restrictions) {
+      this.mode = clampMode(this.mode, restrictions)
+    }
+    this.invalidateCache()
+  }
+
+  getRestrictions(): PermissionRestrictions | undefined {
+    return this.restrictions
+  }
+
   // ── Rule management ──
 
   allow(rule: string): void {
@@ -71,11 +91,21 @@ export class PermissionSystem {
     this.askRules.push(compileRule(rule, 'ask'))
   }
 
-  loadConfig(raw: { mode?: string; allow?: string[]; deny?: string[] }): void {
+  loadConfig(raw: {
+    mode?: string
+    allow?: string[]
+    deny?: string[]
+    restrictions?: PermissionRestrictions
+  }): void {
     const config = loadPermissionConfig(
-      raw as Partial<{ mode: PermissionMode; allow: string[]; deny: string[] }>,
+      raw as Partial<{
+        mode: PermissionMode
+        allow: string[]
+        deny: string[]
+        restrictions: PermissionRestrictions
+      }>,
     )
-    this.mode = config.mode
+    this.mode = clampMode(config.mode, config.restrictions ?? this.restrictions)
 
     this.allowRules = []
     this.denyRules = []
@@ -88,6 +118,10 @@ export class PermissionSystem {
       this.denyRules.push(compileRule(rule, 'deny'))
     }
 
+    if (config.restrictions) {
+      this.restrictions = config.restrictions
+    }
+
     this.invalidateCache()
   }
 
@@ -223,6 +257,11 @@ export class PermissionSystem {
       case 'auto':
         // Safety checks handled by hook layer (PreToolUse hooks).
         // Bypass the static permission system so hooks are the sole gate.
+        // Exception: SendMessage always goes through the permission classifier
+        // so deny/allow rules are honored for cross-session messages.
+        if (tool.name === 'SendMessage') {
+          return 'mode-baseline'
+        }
         return 'bypass'
 
       case 'dontAsk':
@@ -241,9 +280,11 @@ export class PermissionSystem {
 
   setDefaultLevel(level: PermissionLevel): void {
     // Map legacy 3-level to new mode
-    if (level === 'auto') this.mode = 'auto'
-    else if (level === 'bypass') this.mode = 'bypassPermissions'
-    else this.mode = 'default'
+    let newMode: PermissionMode
+    if (level === 'auto') newMode = 'auto'
+    else if (level === 'bypass') newMode = 'bypassPermissions'
+    else newMode = 'default'
+    this.mode = clampMode(newMode, this.restrictions)
     this.invalidateCache()
   }
 

package/src/core/session-store.ts

@@ -17,6 +17,7 @@ export interface SessionMetadata {
   provider: string
   model: string
   messageCount: number
+  cwd?: string
 }
 
 export interface StoredSession {
@@ -44,7 +45,7 @@ export class SessionStore {
   static save(
     name: string,
     messages: Message[],
-    metadata?: { provider?: string; model?: string },
+    metadata?: { provider?: string; model?: string; cwd?: string },
   ): void {
     ensureDir()
     const path = filePath(name)
@@ -57,6 +58,7 @@ export class SessionStore {
         provider: metadata?.provider || 'unknown',
         model: metadata?.model || 'unknown',
         messageCount: messages.length,
+        cwd: metadata?.cwd,
       },
       messages,
     }
@@ -132,7 +134,7 @@ export class SessionStore {
   /**
    * Auto-save with timestamp-based name.
    */
-  static autoSave(messages: Message[], metadata?: { provider?: string; model?: string }): string {
+  static autoSave(messages: Message[], metadata?: { provider?: string; model?: string; cwd?: string }): string {
     const name = `session-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`
     SessionStore.save(name, messages, metadata)
     return name

package/src/core/usage-tracker.ts

@@ -0,0 +1,103 @@
+/**
+ * UsageTracker — per-session token usage tracking with per-tool attribution.
+ *
+ * Tracks actual API-reported token counts (when available) and falls back
+ * to character-estimated counts. Token costs are attributed to the tool
+ * invoked in each turn — MCP tools (prefixed `mcp__`) get correct
+ * per-invocation attribution, not inflated cumulative costs.
+ */
+
+export interface ToolUsage {
+  /** Total input tokens attributed to this tool. */
+  inputTokens: number
+  /** Total output tokens attributed to this tool. */
+  outputTokens: number
+  /** Number of times this tool was invoked. */
+  calls: number
+}
+
+export interface UsageSummary {
+  /** Total input tokens from API (0 if API data unavailable). */
+  apiInputTokens: number
+  /** Total output tokens from API (0 if API data unavailable). */
+  apiOutputTokens: number
+  /** Estimated total tokens (chars/4 heuristic, always available). */
+  estimatedTokens: number
+  /** Per-tool breakdown, keyed by tool name. "chat" = text-only turns. */
+  tools: Record<string, ToolUsage>
+}
+
+export class UsageTracker {
+  private _apiInputTokens = 0
+  private _apiOutputTokens = 0
+  private _estimatedTokens = 0
+  private _toolUsage = new Map<string, ToolUsage>()
+
+  /** Record API-reported token usage for a turn, attributed to the given tool. */
+  recordApiUsage(inputTokens: number, outputTokens: number, toolName?: string): void {
+    this._apiInputTokens += inputTokens
+    this._apiOutputTokens += outputTokens
+    this._recordTool(toolName || 'chat', inputTokens, outputTokens)
+  }
+
+  /** Record character-estimated token usage for a turn. */
+  recordEstimatedUsage(tokenCount: number, toolName?: string): void {
+    this._estimatedTokens += tokenCount
+    this._recordToolEstimated(toolName || 'chat', tokenCount)
+  }
+
+  /** Get a summary of all usage for the current session. */
+  getSummary(): UsageSummary {
+    const tools: Record<string, ToolUsage> = {}
+    for (const [name, usage] of this._toolUsage) {
+      tools[name] = { ...usage }
+    }
+    return {
+      apiInputTokens: this._apiInputTokens,
+      apiOutputTokens: this._apiOutputTokens,
+      estimatedTokens: this._estimatedTokens,
+      tools,
+    }
+  }
+
+  /** Reset all counters for a new session. */
+  reset(): void {
+    this._apiInputTokens = 0
+    this._apiOutputTokens = 0
+    this._estimatedTokens = 0
+    this._toolUsage.clear()
+  }
+
+  /** Total API tokens (input + output). */
+  get totalApiTokens(): number {
+    return this._apiInputTokens + this._apiOutputTokens
+  }
+
+  /** Whether any real API usage data has been recorded. */
+  get hasApiData(): boolean {
+    return this._apiInputTokens > 0 || this._apiOutputTokens > 0
+  }
+
+  // ── Private helpers ──
+
+  private _recordTool(name: string, inputTokens: number, outputTokens: number): void {
+    const existing = this._toolUsage.get(name)
+    if (existing) {
+      existing.inputTokens += inputTokens
+      existing.outputTokens += outputTokens
+      existing.calls++
+    } else {
+      this._toolUsage.set(name, { inputTokens, outputTokens, calls: 1 })
+    }
+  }
+
+  private _recordToolEstimated(name: string, tokenCount: number): void {
+    const existing = this._toolUsage.get(name)
+    if (existing) {
+      existing.inputTokens += tokenCount
+      existing.calls++
+    } else {
+      this._toolUsage.set(name, { inputTokens: tokenCount, outputTokens: 0, calls: 1 })
+    }
+  }
+}