feat: expose --max-cost CLI flag with cost threshold warnings

src/cli.ts

@@ -92,6 +92,7 @@ program
     '--context-budget <n>',
     'Max input tokens per iteration for smart context trimming (0 = unlimited)'
   )
+  .option('--max-cost <amount>', 'Maximum cost in USD before stopping (0 = unlimited)', parseFloat)
   // Figma integration options
   .option('--figma-mode <mode>', 'Figma mode: spec, tokens, components, assets, content')
   .option(

src/commands/run.ts

@@ -221,6 +221,7 @@ export interface RunCommandOptions {
   circuitBreakerErrors?: number;
   contextBudget?: number;
   validationWarmup?: number;
+  maxCost?: number;
   // Figma options
   figmaMode?: 'spec' | 'tokens' | 'components' | 'assets' | 'content';
   figmaFramework?: 'react' | 'vue' | 'svelte' | 'astro' | 'nextjs' | 'nuxt' | 'html';
@@ -653,6 +654,7 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
     model: agent.type === 'claude-code' ? 'claude-3-sonnet' : 'default',
     checkFileCompletion: true, // Always check for file-based completion
     contextBudget: options.contextBudget ? Number(options.contextBudget) : undefined,
+    maxCost: options.maxCost,
     circuitBreaker: preset?.circuitBreaker
       ? {
           maxConsecutiveFailures:

src/loop/executor.ts

@@ -883,6 +883,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
 
     // Track cost for this iteration (silent - summary shown at end)
     if (costTracker) {
+      const prevTotal = costTracker.getStats().totalCost.totalCost;
       costTracker.recordIteration(options.task, result.output);
 
       // Post-iteration cost ceiling check — prevent starting another expensive iteration
@@ -897,6 +898,21 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
         exitReason = 'cost_ceiling';
         break;
       }
+
+      // Warn at cost thresholds when no --max-cost is set
+      if (!options.maxCost) {
+        const total = costTracker.getStats().totalCost.totalCost;
+        const thresholds = [2, 5, 10];
+        for (const t of thresholds) {
+          if (total >= t && prevTotal < t) {
+            console.log(
+              chalk.yellow(
+                `\n  ⚠ Estimated cost has reached $${t}. Use --max-cost to set a budget limit.`
+              )
+            );
+          }
+        }
+      }
     }
 
     // Check for completion using enhanced detection (single-pass: status + reason)