@miphamai/cli 0.13.0 → 0.15.0

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 })
+    }
+  }
+}

package/src/providers/anthropic.ts

@@ -194,7 +194,15 @@ export class AnthropicProvider implements ProviderInstance {
             }
 
             case 'message_delta': {
-              // Contains stop_reason and usage info
+              // Capture token usage for accurate cost tracking
+              if (event.usage) {
+                yield {
+                  type: 'usage',
+                  inputTokens: event.usage.input_tokens,
+                  outputTokens: event.usage.output_tokens,
+                }
+              }
+              // Contains stop_reason; also handles late input_json_delta
               if (event.delta?.type === 'input_json_delta' && event.delta.partial_json) {
                 accumulatedToolInput += event.delta.partial_json
               }

package/src/providers/openai-compat.ts

@@ -99,6 +99,16 @@ export class OpenAICompatProvider implements ProviderInstance {
         try {
           const parsed = JSON.parse(data)
           const choice = parsed.choices?.[0]
+
+          // Capture token usage when available (final chunk with stream_options.include_usage)
+          if (parsed.usage) {
+            yield {
+              type: 'usage',
+              inputTokens: parsed.usage.prompt_tokens,
+              outputTokens: parsed.usage.completion_tokens,
+            }
+          }
+
           if (!choice) continue
 
           const delta = choice.delta

package/src/shared/types.ts

@@ -81,6 +81,7 @@ export interface ToolContext {
   artifactServer?: import('../artifacts/server').ArtifactServer
   agentRegistry?: import('../agent/agent-registry').AgentRegistry
   backgroundAgentRegistry?: import('../agent/background-registry').BackgroundAgentRegistry
+  permissionSystem?: import('../core/permission').PermissionSystem
 }
 
 // ── Artifact Types ──
@@ -128,7 +129,15 @@ export interface TaskNotification {
 
 // ── Stream Types ──
 export interface StreamChunk {
-  type: 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'stop' | 'error' | 'task_notification'
+  type:
+    | 'text'
+    | 'tool_use'
+    | 'tool_result'
+    | 'thinking'
+    | 'stop'
+    | 'error'
+    | 'task_notification'
+    | 'usage'
   content?: string
   toolUse?: ToolUseContent
   tool_use_id?: string
@@ -139,6 +148,10 @@ export interface StreamChunk {
   thinking?: string
   /** Background task notification payload (type: 'task_notification'). */
   taskNotification?: TaskNotification
+  /** API-reported input token count (type: 'usage'). */
+  inputTokens?: number
+  /** API-reported output token count (type: 'usage'). */
+  outputTokens?: number
 }
 
 // ── Config Types ──

package/src/skills/fork-executor.ts

@@ -2,6 +2,7 @@ import { SubAgent } from '../agent/sub-agent'
 import type { ProviderRegistry } from '../providers/registry'
 import type { ToolDefinition, SkillDefinition } from '../shared/index.ts'
 import type { AgentDefinition } from '../agent/types'
+import type { PermissionSystem } from '../core/permission'
 
 /**
  * Execute a skill in an isolated subagent context (context: fork).
@@ -15,6 +16,7 @@ export async function executeForkedSkill(
   args: string,
   registry: ProviderRegistry,
   toolRegistry: Map<string, ToolDefinition>,
+  permissionSystem?: PermissionSystem,
 ): Promise<string> {
   const agentDef: AgentDefinition = {
     name: `skill:${skill.name}`,
@@ -27,7 +29,7 @@ export async function executeForkedSkill(
     source: 'builtin',
   }
 
-  const sub = new SubAgent(registry, toolRegistry)
+  const sub = new SubAgent(registry, toolRegistry, permissionSystem)
   const prompt = args
     ? `Execute the "${skill.name}" skill with arguments: ${args}`
     : `Execute the "${skill.name}" skill.`

package/src/tools/agent/agent.ts

@@ -60,7 +60,7 @@ export const agentTool: ToolDefinition = {
     const agentDef = ctx.agentRegistry?.resolve(agentType)
 
     try {
-      const sub = new SubAgent(registry, toolRegistry)
+      const sub = new SubAgent(registry, toolRegistry, ctx.permissionSystem)
       const result = await sub.execute(prompt, description, {
         type: agentType,
         agentDef,

package/src/tools/agent/skill.ts

@@ -52,6 +52,7 @@ export const skillTool: ToolDefinition = {
             args,
             registry,
             ctx.toolRegistry || new Map(),
+            ctx.permissionSystem,
           )
           // Return to AI as internal context
           return { success: true, content: `[Forked skill "${skillName}" result]:\n${result}` }

package/src/tools/agent/workflow.ts

@@ -5,9 +5,56 @@ import type { QueryEngine } from '../../core/engine'
 export const workflowTool: ToolDefinition = {
   name: 'Workflow',
   description:
-    'Execute a multi-agent workflow script. The script uses agent(), parallel(), pipeline(), phase(), log(), args, budget primitives. ' +
-    'Pass resumeFromRunId to resume a prior run — cached agent() calls are replayed from the journal, ' +
-    'and only new/changed calls execute live.',
+    'Execute a workflow script that orchestrates multiple subagents deterministically. ' +
+    'Workflows run in the background — this tool returns immediately with a task ID, ' +
+    'and a <task-notification> arrives when the workflow completes. Use /workflows to watch live progress.\n\n' +
+    'A workflow structures work across many agents — to be comprehensive (decompose and cover in parallel), ' +
+    'to be confident (independent perspectives and adversarial checks before committing), ' +
+    'or to take on scale one context cannot hold (migrations, audits, broad sweeps). ' +
+    'The script is where you encode that structure: what fans out, what verifies, what synthesizes.\n\n' +
+    'ONLY call this tool when the task benefits from multi-agent orchestration. ' +
+    'For a simple single-agent lookup or edit, use the Agent tool or direct tools instead.\n\n' +
+    '## Primitives\n\n' +
+    '- agent(prompt: string, opts?: {label?, phase?, schema?, model?, effort?, isolation?}): Promise<any> — spawn a subagent. ' +
+    'Without schema, returns final text as string. With schema (JSON Schema), returns validated object — retries on mismatch.\n' +
+    '- parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — BARRIER: runs all thunks concurrently, waits for all. ' +
+    'Failed thunks resolve to null. Use filter(Boolean) before consuming results.\n' +
+    '- pipeline(items: T[], ...stages): Promise<any[]> — NO barrier: each item flows through all stages independently. ' +
+    'Item A can be in stage 3 while item B is still in stage 1. DEFAULT choice for multi-stage work.\n' +
+    '- verify(finding, opts): Promise<VerifyResult> — adversarial/perspective/consensus quality gate. ' +
+    'Spawns skeptics or lens-based judges, applies threshold, returns {survives, votes, score}.\n' +
+    '- judge(attempts, opts): Promise<JudgeResult> — judge panel: N attempts scored by M judges across K criteria. ' +
+    'Returns winner with optional synthesis grafting runner-up ideas.\n' +
+    '- loopUntilConvergence(opts): Promise<LoopUntilConvergenceResult> — convergent discovery loop. ' +
+    'Fans out finders repeatedly, deduplicates against seen-set (NOT confirmed-set), ' +
+    'stops after N consecutive dry rounds or maxRounds. Optionally verifies each finding.\n' +
+    '- phase(title: string): void — start a new progress group\n' +
+    '- log(message: string): void — emit progress message\n' +
+    '- args: any — verbatim args passed to Workflow tool\n' +
+    '- budget: {total, spent(), remaining()} — token budget tracking\n\n' +
+    '## Topology Selection Guide\n\n' +
+    'DEFAULT TO pipeline(). Only reach for a barrier (parallel between stages) when you genuinely ' +
+    'need ALL prior-stage results together.\n\n' +
+    'A barrier is correct ONLY when stage N needs cross-item context from all of stage N-1: ' +
+    'dedup/merge across the full result set, early-exit if total count is zero, cross-finding comparison.\n\n' +
+    'A barrier is NOT justified by: flatten/map/filter (do it inside a pipeline stage), ' +
+    'conceptually separate stages, cleaner code — barrier latency is real and measurable.\n\n' +
+    '- Diamond (fan-out → reduce → synthesize): market scans, audits, research\n' +
+    '- Pipeline (no barrier): each item flows independently — DEFAULT\n' +
+    '- Loop-until-convergence: unknown-size discovery (bugs, vulnerabilities, edge cases)\n' +
+    '- Judge panel: multiple competing approaches, pick best + graft runner-ups\n' +
+    '- Verifier-on-edge: quality gates before results reach downstream\n\n' +
+    '## Critical Rules\n\n' +
+    '- EDGE LOGIC IS FREE: flatten, dedupe, filter in plain JavaScript — NOT agent calls. ' +
+    'results.flatMap(...) and a Set are deterministic, instant, zero tokens.\n' +
+    '- seen-set dedup for loops, NOT confirmed-set — rejected findings would otherwise revive every round.\n' +
+    '- Each node should have bounded input, validated output (schema), and one clear purpose.\n' +
+    '- Model tiering: use cheaper models for repetitive extraction/classification nodes, ' +
+    'expensive models for synthesis/judgment nodes.\n\n' +
+    '## Script Format\n\n' +
+    'Every script MUST begin with: export const meta = { name, description, phases: [{title, detail}] }\n' +
+    'The meta object must be a PURE LITERAL — no variables, function calls, or template interpolation.\n' +
+    'Use the SAME phase titles in meta.phases as in phase() calls.',
   category: 'agent',
   permission: 'ask',
   parameters: {
@@ -60,6 +107,23 @@ export const workflowTool: ToolDefinition = {
         resumeFromRunId,
       )
 
+      // Persist last-run state for /workflow save
+      try {
+        const { existsSync, mkdirSync, writeFileSync } = await import('node:fs')
+        const { join } = await import('node:path')
+        const workflowsDir = join(process.cwd(), '.claude', 'workflows')
+        if (!existsSync(workflowsDir)) {
+          mkdirSync(workflowsDir, { recursive: true })
+        }
+        writeFileSync(
+          join(workflowsDir, '.last-run.json'),
+          JSON.stringify({ runId, script, timestamp: new Date().toISOString() }),
+          'utf-8',
+        )
+      } catch {
+        // best-effort — don't fail the workflow if state persistence fails
+      }
+
       let content = `Workflow ${runId} completed.\n\n`
       if (resumeFromRunId) {
         content += `Cache: ${cacheHits} hits · ${cacheMisses} live\n\n`

package/src/ui/commands.ts

@@ -689,22 +689,47 @@ const recapCmd: CommandHandler = (ctx) => {
 
 const usageCmd: CommandHandler = (ctx) => {
   const c = ctx.engine.getContext()
-  const tokens = c.getEstimatedTokens()
+  const estTokens = c.getEstimatedTokens()
   const msgs = c.getMessages()
   const maxTokens = 200_000
-  const pct = ((tokens / maxTokens) * 100).toFixed(1)
+  const pct = ((estTokens / maxTokens) * 100).toFixed(1)
+
+  const tracker = ctx.engine.getUsageTracker()
+  const summary = tracker.getSummary()
+
+  // Build per-tool breakdown
+  const toolLines: string[] = []
+  const sortedTools = Object.entries(summary.tools).sort(
+    (a, b) => b[1].inputTokens + b[1].outputTokens - (a[1].inputTokens + a[1].outputTokens),
+  )
+  for (const [name, usage] of sortedTools) {
+    const total = usage.inputTokens + usage.outputTokens
+    const prefix = name.startsWith('mcp__') ? '🔌 ' : '  '
+    toolLines.push(
+      `${prefix}${name.padEnd(18)} ${total.toLocaleString().padStart(8)} tokens (${usage.calls} call${usage.calls !== 1 ? 's' : ''})`,
+    )
+  }
+
+  const apiTotal = summary.apiInputTokens + summary.apiOutputTokens
+  const apiLine =
+    summary.apiInputTokens > 0 || summary.apiOutputTokens > 0
+      ? `API tokens:      ${summary.apiInputTokens.toLocaleString().padStart(8)} in / ${summary.apiOutputTokens.toLocaleString().padStart(6)} out (${apiTotal.toLocaleString()} total)`
+      : 'API tokens:      (no API usage data yet)'
+
+  const toolSection = toolLines.length > 0 ? `\n── Per-Tool ──\n${toolLines.join('\n')}` : ''
 
   return {
     content: stripIndent`
       ── Usage Dashboard ──
-      Context tokens:  ~${tokens.toLocaleString()} / ${maxTokens.toLocaleString()}  (${pct}%)
+      ${apiLine}
+      Context tokens:  ~${estTokens.toLocaleString()} / ${maxTokens.toLocaleString()}  (${pct}%)
       Messages:         ${msgs.length}
       Provider:         ${ctx.providerId}
       Model:            ${ctx.modelId}
 
       ${'█'.repeat(Math.ceil(Number(pct) / 5))}${'░'.repeat(20 - Math.ceil(Number(pct) / 5))} ${pct}%
+      ${toolSection}
 
-      Note: Token counting is approximate (chars/4).
       Use /context for detailed stats, /compact to free space.
     `,
   }
@@ -2388,6 +2413,111 @@ const workflowsCmd: CommandHandler = async () => {
   return { content: lines.join('\n') }
 }
 
+// ═══════════════════════════════════════════════════════════════
+// /workflow <task> — auto-generate + execute
+// ═══════════════════════════════════════════════════════════════
+
+const workflowSaveCmd = async (name: string): Promise<CommandResult> => {
+  const { existsSync, mkdirSync, writeFileSync, readFileSync } = await import('node:fs')
+  const { join } = await import('node:path')
+
+  const targetDir = join(process.cwd(), '.claude', 'workflows')
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true })
+  }
+
+  // Read the last-run state persisted by the Workflow tool
+  const stateFile = join(targetDir, '.last-run.json')
+  if (!existsSync(stateFile)) {
+    return { content: 'No recent workflow run found. Run a workflow first with /workflow <task>.' }
+  }
+
+  try {
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+    const script = state.script as string
+    if (!script) {
+      return { content: 'No script found in last run state.' }
+    }
+
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '-')
+    const scriptPath = join(targetDir, `${safeName}.js`)
+    writeFileSync(scriptPath, script, 'utf-8')
+
+    return {
+      content: `Workflow saved to ${scriptPath}\nUse /workflow run ${safeName} to run it again.`,
+    }
+  } catch (err) {
+    return { content: `Failed to save workflow: ${String(err)}` }
+  }
+}
+
+const workflowRunCmd = async (name: string): Promise<CommandResult> => {
+  const { existsSync } = await import('node:fs')
+  const { join } = await import('node:path')
+
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '-')
+
+  const locations = [
+    join(process.cwd(), '.claude', 'workflows'),
+    join(process.env.HOME || '~', '.claude', 'workflows'),
+  ]
+
+  for (const loc of locations) {
+    const scriptPath = join(loc, `${safeName}.js`)
+    if (existsSync(scriptPath)) {
+      return {
+        content: '',
+        forwardToAI:
+          `Read the workflow script at ${scriptPath}, then call the Workflow tool with ` +
+          `the file contents as the "script" parameter to execute it. Report the results.`,
+      }
+    }
+  }
+
+  return {
+    content: `Workflow "${safeName}" not found in .claude/workflows/ or ~/.claude/workflows/`,
+  }
+}
+
+const workflowAutoCmd: CommandHandler = async (_ctx, args) => {
+  const task = args.join(' ').trim()
+
+  if (!task) {
+    return {
+      content:
+        'Usage: /workflow <task description>\n\n' +
+        'Describes the task, and the AI will generate a workflow script to execute it.\n' +
+        'Examples:\n' +
+        '  /workflow audit all routes for missing auth\n' +
+        '  /workflow research the impact of React 19 on our codebase\n' +
+        '  /workflow find all hardcoded credentials in the codebase\n\n' +
+        'Sub-commands:\n' +
+        '  /workflow save <name>  — save last successful workflow script\n' +
+        '  /workflow run <name>    — run a saved workflow by name\n' +
+        '  /workflows              — list all saved workflow scripts',
+    }
+  }
+
+  // Sub-commands
+  const firstArg = args[0] || ''
+  if (firstArg === 'save' && args[1]) {
+    return workflowSaveCmd(args.slice(1).join(' '))
+  }
+  if (firstArg === 'run' && args[1]) {
+    return workflowRunCmd(args.slice(1).join(' '))
+  }
+
+  // Default: forward to AI to generate + execute workflow
+  return {
+    content: '',
+    forwardToAI:
+      `Write and execute a workflow script for this task: ${task}\n\n` +
+      `Use the Workflow tool to execute the generated script. ` +
+      `After the workflow completes, summarize the results and offer to save the script ` +
+      `with /workflow save <name> if it is reusable.`,
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════
 // Permissions
 // ═══════════════════════════════════════════════════════════════
@@ -3988,8 +4118,14 @@ const forkCmd: CommandHandler = async (ctx, args) => {
     'general',
     async (_signal) => {
       const { SubAgent } = await import('../agent/sub-agent')
-      const sa = new SubAgent(ctx.engine.getRegistry(), ctx.engine.getTools())
-      const result = await sa.execute(prompt, 'fork: ' + prompt.slice(0, 60), {})
+      const sa = new SubAgent(
+        ctx.engine.getRegistry(),
+        ctx.engine.getTools(),
+        ctx.engine.getPermission(),
+      )
+      const result = await sa.execute(prompt, 'fork: ' + prompt.slice(0, 60), {
+        worktreePath: wtPath,
+      })
       try {
         const { execSync: ex } = await import('node:child_process')
         ex(`git -C ${wtPath} add -A`, { stdio: 'ignore', timeout: 10_000 })
@@ -4318,6 +4454,7 @@ registry.set('/tasks', tasksCmd)
 registry.set('/diff', diffCmd)
 registry.set('/loop', loopCmd)
 registry.set('/no-plan', noPlanCmd)
+registry.set('/workflow', workflowAutoCmd)
 registry.set('/workflows', workflowsCmd)
 registry.set('/review', reviewCmd)
 registry.set('/pr-comments', prCommentsCmd)