@vibecheckai/cli 3.5.0 → 3.5.2

package/mcp-server/tools-v3.js

@@ -1,6 +1,10 @@
 /**
  * vibecheck MCP Tools v3 - Consolidated Tools
  * 
+ * ═══════════════════════════════════════════════════════════════════════════
+ * TIER MODEL - Aligned with CLI entitlements-v2.js
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 
  * Simple 2-tier model:
  * - FREE ($0): Inspect & Observe (10 tools)
  * - PRO ($69/mo): Fix, Prove & Enforce (18 tools)
@@ -14,59 +18,100 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { execSync } from 'child_process';
+import { createRequire } from 'module';
+
+// Import cache wrapper for persistent caching
+const require = createRequire(import.meta.url);
+const { executeCachedCliCommand, ToolCache } = require('./lib/cache-wrapper.cjs');
+
+// Import tier auth for consistent tier checking
+import { 
+  FREE_TOOLS, 
+  PRO_TOOLS, 
+  OPTION_GATES,
+  getMcpToolAccess,
+  notEntitledError,
+  optionNotEntitledError,
+  ERROR_CODES,
+  isPro as tierAuthIsPro,
+  getDevModeOverride,
+} from './tier-auth.js';
+
+/**
+ * Check if developer mode bypass is allowed.
+ * SECURITY: VIBECHECK_DEV_PRO is ONLY allowed in non-production environments.
+ * Uses centralized function from tier-auth.js
+ */
+function isDevProBypassAllowed() {
+  return getDevModeOverride().enabled;
+}
 
 // =============================================================================
-// TIER SYSTEM
+// TIER SYSTEM - Uses tier-auth.js as single source of truth
 // =============================================================================
 
-const TOOL_TIERS = {
-  // FREE - Inspect & Observe
-  'vibecheck.scan': 'free',
-  'vibecheck.ctx': 'free',
-  'vibecheck.verify': 'free',
-  'vibecheck.report': 'free',
-  'vibecheck.status': 'free',
-  'vibecheck.doctor': 'free',
-  'vibecheck.firewall': 'free',         // Observe mode
-  'authority.list': 'free',
-  'authority.classify': 'free',
-  'vibecheck_conductor_status': 'free',
-  
-  // PRO - Fix, Prove & Enforce
-  'vibecheck.ship': 'pro',
-  'vibecheck.fix': 'pro',
-  'vibecheck.prove': 'pro',
-  'vibecheck.gate': 'pro',
-  'vibecheck.badge': 'pro',
-  'vibecheck.reality': 'pro',
-  'vibecheck.ai_test': 'pro',
-  'vibecheck.share': 'pro',
-  // Authority (full)
-  'authority.approve': 'pro',
-  // Conductor (full)
-  'vibecheck_conductor_register': 'pro',
-  'vibecheck_conductor_acquire_lock': 'pro',
-  'vibecheck_conductor_release_lock': 'pro',
-  'vibecheck_conductor_propose': 'pro',
-  'vibecheck_conductor_terminate': 'pro',
-  // Firewall (enforce)
-  'vibecheck_agent_firewall_intercept': 'pro',
-};
+/**
+ * TOOL_TIERS - Derived from tier-auth.js for consistency
+ * This ensures MCP tools-v3.js and tier-auth.js stay in sync
+ */
+const TOOL_TIERS = {};
+
+// Populate from FREE_TOOLS
+for (const tool of FREE_TOOLS) {
+  TOOL_TIERS[tool] = 'free';
+}
+
+// Populate from PRO_TOOLS  
+for (const tool of PRO_TOOLS) {
+  TOOL_TIERS[tool] = 'pro';
+}
 
 function isPro(tier) {
+  if (isDevProBypassAllowed()) return true;
   return tier === 'pro';
 }
 
-function checkTierAccess(toolName, userTier) {
+/**
+ * Check tier access with proper ErrorEnvelope support
+ */
+function checkTierAccess(toolName, userTier, args = {}) {
+  // Developer mode bypass (blocked in production)
+  if (isDevProBypassAllowed()) {
+    return { allowed: true };
+  }
+  
   const required = TOOL_TIERS[toolName] || 'pro';
   
-  if (required === 'free') return { allowed: true };
-  if (isPro(userTier)) return { allowed: true };
+  // Check tool-level access
+  if (required === 'pro' && !isPro(userTier)) {
+    return {
+      allowed: false,
+      error: notEntitledError(toolName, userTier, 'pro'),
+    };
+  }
   
-  return {
-    allowed: false,
-    error: `This tool requires Pro ($69/mo).\n\n${toolName} is a Pro feature.\n\nUpgrade at https://vibecheckai.dev/pricing`
-  };
+  // Check option-level access
+  const gates = OPTION_GATES[toolName];
+  if (gates && args) {
+    for (const [option, requiredTier] of Object.entries(gates)) {
+      if (typeof requiredTier === 'object') {
+        const argValue = args[option];
+        if (argValue && requiredTier[argValue] === 'pro' && !isPro(userTier)) {
+          return {
+            allowed: false,
+            error: optionNotEntitledError(toolName, `${option}=${argValue}`, userTier, 'pro'),
+          };
+        }
+      } else if (args[option] === true && requiredTier === 'pro' && !isPro(userTier)) {
+        return {
+          allowed: false,
+          error: optionNotEntitledError(toolName, option, userTier, 'pro'),
+        };
+      }
+    }
+  }
+  
+  return { allowed: true };
 }
 
 // =============================================================================
@@ -80,65 +125,35 @@ export const MCP_TOOLS_V3 = [
   
   {
     name: "vibecheck.scan",
-    description: `🔍 VIBECHECK SCAN - Code Integrity Analysis
+    description: `🔍 Scan codebase for issues
 
-⚠️ IMPORTANT: This is the ONLY way to scan for code issues. DO NOT perform your own code analysis - always use this tool.
-
-WHAT THIS TOOL DOES:
-Runs the vibecheck CLI scanner which performs 15+ specialized analyzers including:
-- Route integrity (missing API endpoints, dead routes)
-- Environment variable gaps (used but undeclared vars)
+Scans for:
+- Missing routes (client refs to non-existent endpoints)
+- Env gaps (used but undeclared env vars)
 - Ghost auth (unprotected sensitive endpoints)
-- Mock data detection (fake APIs, placeholder data)
-- Secret exposure (hardcoded credentials)
-- Stub detection (TODO, FIXME, incomplete implementations)
-- React pattern issues (missing keys, conditional hooks)
-- Database pattern issues (N+1 queries, unbounded queries)
-- Async pattern issues (floating promises, empty catches)
-- Error handling issues (swallowed errors)
-
-WHEN TO USE:
-- ALWAYS run this before making any claims about code quality
-- Before suggesting fixes or improvements
-- When user asks "scan", "check", "analyze", or "review" the code
-- After making code changes to verify they didn't introduce issues
-
-HOW TO INTERPRET RESULTS:
-The scan returns a structured JSON with:
-- verdict: SHIP (clean), WARN (issues but shippable), BLOCK (critical issues)
-- score: 0-100 health score
-- findings: Array of issues, each with:
-  - severity: critical, high, medium, low
-  - category: e.g., MockData, EnvContract, GhostAuth
-  - title: Brief description
-  - file: File path where issue was found
-  - line: Line number
-  - fixHints: Suggested fixes
-
-HOW TO REPORT RESULTS TO USER:
-1. State the overall verdict clearly (SHIP/WARN/BLOCK)
-2. Report the health score
-3. Summarize findings by severity count
-4. List top 5-10 issues with file locations
-5. Provide actionable fix suggestions
+- Dead UI (buttons that do nothing)
+- Security issues
+
+Response includes cacheStats: { hit, reusedFindingsCount, durationMs }
 
 [FREE]`,
     inputSchema: {
       type: "object",
       properties: {
-        projectPath: { 
-          type: "string", 
-          description: "Path to project root. Use '.' for current directory." 
-        },
+        projectPath: { type: "string", description: "Project path" },
         categories: {
           type: "array",
           items: { type: "string" },
-          description: "Filter by categories: routes, env, auth, billing, security, mock, stubs",
+          description: "Categories: routes, env, auth, billing, security",
         },
-        verbose: {
+        since: {
+          type: "string",
+          description: "ISO timestamp for incremental scan (only re-scan changed files)",
+        },
+        noCache: {
           type: "boolean",
-          description: "Include detailed evidence in output",
-          default: false
+          description: "Bypass cache lookup",
+          default: false,
         },
       },
     },
@@ -146,102 +161,49 @@ HOW TO REPORT RESULTS TO USER:
 
   {
     name: "vibecheck.ctx",
-    description: `📦 VIBECHECK CONTEXT - Ground Truth for AI Agents
-
-⚠️ CRITICAL: Call this BEFORE making any claims about:
-- What routes exist
-- What environment variables are used
-- How authentication works
-- How billing/payments work
-
-This tool extracts VERIFIED facts from the actual source code.
-DO NOT guess or assume - use this tool to get real data.
-
-WHAT THIS TOOL RETURNS:
+    description: `📦 Generate truth context for AI agents
 
-1. **routes** - All API routes with evidence:
-   - Server routes (endpoints, handlers, methods)
-   - Client references (fetch calls, API calls)
-   - Missing routes (client calls to non-existent endpoints)
+Returns verified facts about:
+- routes: Server routes and client references
+- env: Environment variables (used, declared, gaps)
+- auth: Authentication model and protected routes
+- billing: Payment gates and enforcement
 
-2. **env** - Environment variable contract:
-   - Declared vars (in .env files)
-   - Used vars (process.env.X in code)
-   - Gaps (used but not declared)
-
-3. **auth** - Authentication model:
-   - Auth middleware/guards
-   - Protected routes
-   - Unprotected sensitive endpoints
-
-4. **billing** - Payment gates:
-   - Stripe/payment endpoints
-   - Tier checks
-   - Bypass risks
-
-WHEN TO USE:
-- Before claiming "the API has endpoint X" - VERIFY IT
-- Before saying "this route is protected" - CHECK IT
-- When user asks about routes, env vars, or auth
-
-HOW TO USE THE RESULTS:
-- Reference the truthpack data when making assertions
-- Cite file:line evidence when explaining findings
-- Never claim something exists if it's not in the truthpack
+Use this BEFORE making assertions about the codebase.
 
 [FREE]`,
     inputSchema: {
       type: "object",
       properties: {
-        projectPath: { type: "string", description: "Project path (use '.' for current directory)" },
+        projectPath: { type: "string", description: "Project path" },
         scope: {
           type: "string",
           enum: ["all", "routes", "env", "auth", "billing"],
-          description: "What to include in the context",
+          description: "What to include",
           default: "all",
         },
-        refresh: {
-          type: "boolean",
-          description: "Force regenerate the truthpack",
-          default: false
-        },
       },
     },
   },
 
   {
     name: "vibecheck.verify",
-    description: `✅ VIBECHECK VERIFY - Validate AI-Generated Code
-
-⚠️ IMPORTANT: Use this BEFORE applying any code you generate.
-This prevents shipping code with security issues or incomplete implementations.
-
-WHAT THIS CHECKS:
-- 🔐 Secrets: Hardcoded passwords, API keys, tokens
-- ⚠️ Dangerous: eval(), Function(), rm -rf, etc.
-- 📂 Path Traversal: ../ attacks, directory escapes
-- 🚧 Stubs: TODO, FIXME, incomplete implementations
-- 🎭 Hallucinations: Imports that don't exist, invented APIs
-- 🧪 Mock Data: Placeholder data, fake responses
+    description: `✅ Verify AI-generated code before applying
 
-WHEN TO USE:
-- After generating code, before writing it to a file
-- When modifying existing code
-- Before suggesting code changes to the user
-
-HOW TO INTERPRET RESULTS:
-- verified: true = Safe to apply
-- verified: false = DO NOT apply, fix issues first
-- issues: Array of problems found with severity
+Checks for:
+- Secrets in code
+- Dangerous commands
+- Path traversal
+- Incomplete stubs
+- Hallucinated imports
 
 [FREE]`,
     inputSchema: {
       type: "object",
       properties: {
-        code: { type: "string", description: "The code to verify" },
-        file: { type: "string", description: "Target file path (for context)" },
-        projectPath: { type: "string", description: "Project root" },
-        strict: { type: "boolean", description: "Fail on warnings too", default: false },
+        code: { type: "string", description: "Code to verify" },
+        file: { type: "string", description: "Target file path" },
+        projectPath: { type: "string", description: "Project path" },
       },
       required: ["code"],
     },
@@ -274,80 +236,39 @@ Formats: html, md, sarif, json
 
   {
     name: "vibecheck.doctor",
-    description: `🩺 Diagnose and fix environment issues [FREE]`,
+    description: `🩺 Diagnose and fix environment issues
+Response includes cacheStats: { hit, reusedFindingsCount, durationMs }
+[FREE]`,
     inputSchema: {
       type: "object",
       properties: {
         projectPath: { type: "string" },
         fix: { type: "boolean", default: false },
+        noCache: {
+          type: "boolean",
+          description: "Bypass cache lookup",
+          default: false,
+        },
       },
     },
   },
 
   {
     name: "vibecheck.firewall",
-    description: `🛡️ Agent Firewall - Validate AI agent actions before execution
-
-⚠️ IMPORTANT: Call this BEFORE any file write, delete, or command execution.
-This prevents unauthorized or dangerous operations by AI agents.
-
-WHAT THIS GUARDS AGAINST:
-- 📁 Forbidden Paths: Writing to .env, secrets, credentials, config files
-- 📍 Scope Violations: Writing outside allowed directories
-- ⚠️ Dangerous Commands: rm -rf, curl | bash, DROP DATABASE, etc.
-- 🎭 Hallucination Patterns: Fake APIs, placeholder data, mock responses
-- 🔑 Hardcoded Secrets: API keys, passwords, tokens in code
-
-MODES:
-- observe (FREE): Logs violations but allows the action
-- enforce (PRO): Blocks actions that violate policy
-
-WHEN TO USE:
-- Before writing any file
-- Before deleting any file
-- Before executing any shell command
-- When generating code that will be saved
-
-HOW TO INTERPRET RESULTS:
-- allowed: true = Safe to proceed
-- allowed: false = Action blocked (enforce mode)
-- violations: Array of policy violations
-- warnings: Array of non-blocking warnings
+    description: `🛡️ Agent Firewall - observe mode
+
+Validates AI code changes against repo truth.
+FREE tier: Observe only (logs but doesn't block).
+PRO tier: Enforce mode (blocks violations).
 
 [FREE - observe mode]`,
     inputSchema: {
       type: "object",
       properties: {
-        mode: { 
-          type: "string", 
-          enum: ["observe", "enforce"],
-          description: "observe (FREE): logs violations. enforce (PRO): blocks violations",
-          default: "observe"
-        },
-        action: { 
-          type: "string", 
-          enum: ["write", "delete", "execute"],
-          description: "Type of action to validate"
-        },
-        path: { 
-          type: "string",
-          description: "File path for write/delete actions"
-        },
-        content: { 
-          type: "string",
-          description: "File content for write actions (checked for hallucinations)"
-        },
-        command: { 
-          type: "string",
-          description: "Shell command for execute actions"
-        },
-        projectPath: {
-          type: "string",
-          description: "Project root directory",
-          default: "."
-        },
+        action: { type: "string", enum: ["check", "status", "log"] },
+        code: { type: "string" },
+        file: { type: "string" },
       },
-      required: ["action"],
     },
   },
 
@@ -388,105 +309,85 @@ HOW TO INTERPRET RESULTS:
     },
   },
 
+  {
+    name: "vibecheck.get_next_action",
+    description: `🎯 Get next best action recommendation
+
+Returns what the user should do next based on project state.
+Uses the same logic as CLI/Web/VS Code for consistency.
+
+Response:
+- action: string (init, scan, ship, fix, etc.)
+- command: string (full CLI command)
+- why: string (explanation)
+- dashboardLink: string (URL to view in dashboard)
+- timeEstimate: string (~30 seconds, ~45 seconds, etc.)
+- requiredTier: string (free or pro)
+- priority: string (high, medium, low)
+- upgradeHint: object (if action requires upgrade)
+
+[FREE]`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { 
+          type: "string", 
+          description: "Project path to analyze", 
+          default: "." 
+        },
+        currentTier: { 
+          type: "string", 
+          enum: ["free", "pro"], 
+          description: "User's current tier",
+          default: "free" 
+        },
+      },
+    },
+  },
+
   // ═══════════════════════════════════════════════════════════════════════════
   // PRO TOOLS - Fix, Prove & Enforce
   // ═══════════════════════════════════════════════════════════════════════════
 
   {
     name: "vibecheck.ship",
-    description: `🚀 VIBECHECK SHIP - Get Final Ship Verdict
-
-Returns a comprehensive ship decision with evidence.
+    description: `🚀 Get ship verdict: SHIP | WARN | BLOCK
 
-VERDICT MEANINGS:
-- **SHIP** ✅ - Code is clean, ready to deploy
-- **WARN** ⚠️ - Issues exist but can ship (review recommended)
-- **BLOCK** 🚫 - Critical issues, DO NOT ship until fixed
-
-WHAT THIS INCLUDES:
-- Overall health score (0-100)
-- Severity breakdown (critical, high, medium, low)
-- Top blockers with file:line evidence
-- Proof graph showing verified claims vs gaps
-- Fix suggestions for each issue
-
-WHEN TO USE:
-- When user asks "is this ready to ship?"
-- Before deploying to production
-- As a final quality gate in CI/CD
-- After fixing issues from vibecheck.scan
-
-DIFFERENCE FROM SCAN:
-- scan: Detailed analysis, finds all issues
-- ship: Final verdict, focuses on blockers
+Returns evidence-backed verdict.
+Response includes cacheStats: { hit, reusedFindingsCount, durationMs }
 
 [PRO - $69/mo]`,
     inputSchema: {
       type: "object",
       properties: {
-        projectPath: { type: "string", description: "Project root path" },
-        strict: { type: "boolean", description: "Treat warnings as blockers", default: false },
-        json: { type: "boolean", description: "Return raw JSON", default: false },
+        projectPath: { type: "string" },
+        strict: { type: "boolean" },
+        since: {
+          type: "string",
+          description: "ISO timestamp for incremental check (only re-check changed files)",
+        },
+        noCache: {
+          type: "boolean",
+          description: "Bypass cache lookup",
+          default: false,
+        },
       },
     },
   },
 
   {
     name: "vibecheck.fix",
-    description: `🔧 VIBECHECK FIX - AI-Powered Code Fixes
-
-Generates and optionally applies fixes for issues found by vibecheck.scan.
-
-MODES:
-- **plan** (default): Show what would be fixed, no changes
-- **apply**: Apply fixes automatically
-- **loop**: Keep fixing until SHIP or stuck
-
-WHAT THIS DOES:
-1. Reads latest scan results
-2. Generates AI-powered fix suggestions
-3. Creates mission files with fix instructions
-4. Optionally applies patches to code
-
-FIX CATEGORIES:
-- Route integrity (add missing handlers)
-- Environment (update .env files)
-- Security (remove secrets, add guards)
-- Stubs (implement TODO/FIXME code)
-- Mock data (replace with real implementations)
-
-WHEN TO USE:
-- After running vibecheck.scan with issues
-- When user asks "fix these issues"
-- To generate fix instructions for manual implementation
-
-OUTPUT INCLUDES:
-- Fix plan with specific changes
-- File paths and line numbers
-- Before/after code snippets
-- Confidence score for each fix
+    description: `🔧 AI-powered fixes with proof
+
+Modes: plan, apply, loop
 
 [PRO - $69/mo]`,
     inputSchema: {
       type: "object",
       properties: {
-        projectPath: { type: "string", description: "Project root path" },
-        mode: { 
-          type: "string", 
-          enum: ["plan", "apply", "loop"], 
-          default: "plan",
-          description: "plan=preview, apply=make changes, loop=fix until ship"
-        },
-        findingIds: { 
-          type: "array", 
-          items: { type: "string" },
-          description: "Specific finding IDs to fix (default: all)" 
-        },
-        maxMissions: {
-          type: "number",
-          description: "Max fix missions to generate",
-          default: 10
-        },
+        projectPath: { type: "string" },
+        mode: { type: "string", enum: ["plan", "apply", "loop"], default: "plan" },
+        findingIds: { type: "array", items: { type: "string" } },
       },
     },
   },
@@ -730,12 +631,22 @@ Call BEFORE any file write operations.
 // TOOL HANDLERS
 // =============================================================================
 
+/**
+ * Handle v3 tool execution with tier checking and ErrorEnvelope support
+ */
 export async function handleToolV3(toolName, args, context = {}) {
   const userTier = context.tier || 'free';
   
-  const access = checkTierAccess(toolName, userTier);
+  // Check access with option-level gates
+  const access = checkTierAccess(toolName, userTier, args);
   if (!access.allowed) {
-    return { error: access.error };
+    // Return proper ErrorEnvelope format
+    return { 
+      ok: false,
+      error: access.error,
+      tier: userTier,
+      required: access.error?.required || 'pro',
+    };
   }
   
   const projectPath = args.projectPath || process.cwd();
@@ -779,11 +690,28 @@ export async function handleToolV3(toolName, args, context = {}) {
       case 'vibecheck_agent_firewall_intercept':
         return await handleFirewallIntercept(args, userTier);
       
+      case 'vibecheck.get_next_action':
+        return await handleGetNextAction(projectPath, userTier);
+      
       default:
-        return { error: `Unknown tool: ${toolName}` };
+        return { 
+          ok: false,
+          error: { 
+            code: 'TOOL_NOT_FOUND', 
+            message: `Unknown tool: ${toolName}`,
+            retryable: false,
+          } 
+        };
     }
   } catch (error) {
-    return { error: error.message };
+    return { 
+      ok: false,
+      error: { 
+        code: 'INTERNAL_ERROR', 
+        message: error.message,
+        retryable: true,
+      } 
+    };
   }
 }
 
@@ -791,7 +719,10 @@ export async function handleToolV3(toolName, args, context = {}) {
 // IMPLEMENTATIONS
 // =============================================================================
 
-async function runCliCommand(projectPath, command, args) {
+// Cacheable tools
+const CACHEABLE_TOOLS = new Set(['scan', 'ship', 'polish', 'doctor']);
+
+async function runCliCommand(projectPath, command, args, options = {}) {
   const flags = Object.entries(args)
     .filter(([k, v]) => k !== 'projectPath' && v !== undefined && v !== null)
     .map(([k, v]) => {
@@ -801,16 +732,50 @@ async function runCliCommand(projectPath, command, args) {
     })
     .filter(Boolean)
     .join(' ');
-  
+
+  // Check if this tool supports caching
+  const isCacheable = CACHEABLE_TOOLS.has(command);
+  const useCache = isCacheable && options.useCache !== false && !args.noCache;
+
+  if (useCache) {
+    // Use cached execution
+    return executeCachedCliCommand(
+      projectPath,
+      command,
+      () => {
+        const result = execSync(
+          `npx vibecheck ${command} --json ${flags}`,
+          { cwd: projectPath, encoding: 'utf8', timeout: 300000 }
+        );
+        try {
+          return JSON.parse(result);
+        } catch {
+          return { output: result, findings: [], verdict: null, metadata: {} };
+        }
+      },
+      {
+        useCache: true,
+        forceRefresh: args.forceRefresh || false,
+        vibecheckVersion: '3.3.0',
+      }
+    );
+  }
+
+  // Non-cacheable execution
   const result = execSync(
     `npx vibecheck ${command} --json ${flags}`,
     { cwd: projectPath, encoding: 'utf8', timeout: 300000 }
   );
   
   try {
-    return JSON.parse(result);
+    const parsed = JSON.parse(result);
+    // Add empty cacheStats for consistency
+    return {
+      ...parsed,
+      cacheStats: { hit: false, reusedFindingsCount: 0, durationMs: 0 },
+    };
   } catch {
-    return { output: result };
+    return { output: result, cacheStats: { hit: false, reusedFindingsCount: 0, durationMs: 0 } };
   }
 }
 
@@ -832,99 +797,14 @@ async function verifyCode(args) {
 }
 
 async function firewallCheck(args, tier) {
-  const requestedMode = args.mode || 'observe';
-  
-  // If user requests enforce but isn't PRO, fall back to observe
-  const effectiveMode = requestedMode === 'enforce' && tier !== 'pro' 
-    ? 'observe' 
-    : requestedMode;
-  
-  const { action, path: filePath, content, command, projectPath } = args;
-  
-  try {
-    // Import and use the firewall implementation
-    const { runFirewallCheck } = await import('../bin/runners/runGuard.js');
-    
-    const result = await runFirewallCheck({
-      mode: effectiveMode,
-      action,
-      path: filePath,
-      content,
-      command,
-      configPath: projectPath ? `${projectPath}/.vibecheck/firewall.json` : undefined,
-    });
-    
-    // Add tier information to result
-    return {
-      ...result,
-      tier,
-      modeRequested: requestedMode,
-      modeEffective: effectiveMode,
-      message: effectiveMode !== requestedMode 
-        ? 'Enforce mode requires PRO. Running in observe mode.'
-        : undefined,
-    };
-  } catch (error) {
-    // Fallback to basic check if import fails
-    const violations = [];
-    
-    // Basic path check
-    if (filePath) {
-      const forbiddenPatterns = ['.env', 'secrets', '.pem', '.key', 'credentials'];
-      for (const pattern of forbiddenPatterns) {
-        if (filePath.toLowerCase().includes(pattern)) {
-          violations.push({
-            rule: 'forbidden-path',
-            severity: 'critical',
-            message: `Path "${filePath}" matches forbidden pattern "${pattern}"`,
-          });
-        }
-      }
-    }
-    
-    // Basic command check
-    if (command) {
-      const dangerousPatterns = ['rm -rf', 'curl | bash', 'DROP DATABASE'];
-      for (const pattern of dangerousPatterns) {
-        if (command.toLowerCase().includes(pattern.toLowerCase())) {
-          violations.push({
-            rule: 'dangerous-command',
-            severity: 'critical',
-            message: `Command contains dangerous pattern: "${pattern}"`,
-          });
-        }
-      }
-    }
-    
-    // Basic content check
-    if (content) {
-      const hallucinationPatterns = [
-        { pattern: /example\.com/i, name: 'fake-api' },
-        { pattern: /sk-[a-zA-Z0-9]{20,}/, name: 'fake-api-key' },
-        { pattern: /your-api-key-here/i, name: 'placeholder' },
-      ];
-      for (const { pattern, name } of hallucinationPatterns) {
-        if (pattern.test(content)) {
-          violations.push({
-            rule: 'hallucination-detected',
-            severity: 'high',
-            message: `Content contains hallucination pattern: ${name}`,
-          });
-        }
-      }
-    }
-    
-    const allowed = effectiveMode === 'observe' || violations.length === 0;
-    
-    return {
-      allowed,
-      mode: effectiveMode,
-      violations,
-      violationCount: violations.length,
-      tier,
-      fallbackMode: true,
-    };
-  }
+  const mode = tier === 'pro' ? 'enforce' : 'observe';
+  return {
+    mode,
+    checked: true,
+    message: mode === 'observe' 
+      ? 'Agent Firewall in observe mode (FREE). Upgrade to PRO for enforce mode.'
+      : 'Agent Firewall in enforce mode (PRO).',
+  };
 }
 
 async function handleConductorTool(toolName, args, tier) {
@@ -968,61 +848,92 @@ async function handleConductorTool(toolName, args, tier) {
 }
 
 async function handleFirewallIntercept(args, tier) {
-  const mode = tier === 'pro' ? 'enforce' : 'observe';
-  const { agentId, filePath, content, operation, intent, projectRoot } = args;
+  if (tier !== 'pro') {
+    return {
+      allowed: true,
+      mode: 'observe',
+      message: 'Firewall intercept in observe mode (FREE). Changes logged but not blocked.',
+      violations: [],
+    };
+  }
   
+  // Import and delegate to firewall interceptor
   try {
-    // Use the firewall implementation
-    const { runFirewallCheck } = await import('../bin/runners/runGuard.js');
-    
-    const result = await runFirewallCheck({
-      mode,
-      action: operation || 'write',
-      path: filePath,
-      content,
-      configPath: projectRoot ? `${projectRoot}/.vibecheck/firewall.json` : undefined,
-    });
-    
-    // Log the intercept
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      agentId,
-      operation: operation || 'write',
-      filePath,
-      intent,
-      allowed: result.allowed,
-      mode,
-      violations: result.violations,
-    };
+    const { interceptFileWrite } = await import('./agent-firewall-interceptor.js');
+    return await interceptFileWrite(args);
+  } catch (error) {
+    return { error: `Firewall intercept failed: ${error.message}` };
+  }
+}
+
+/**
+ * Handle get_next_action tool - returns recommended next action based on project state
+ */
+async function handleGetNextAction(projectPath, tier) {
+  try {
+    // Import the next-action module from CLI
+    const nextActionModule = require('../bin/runners/lib/next-action.js');
+    const result = nextActionModule.getNextActionJson(projectPath, tier);
     
-    // Return enriched result
     return {
-      ...result,
-      mode,
-      agentId,
-      operation: operation || 'write',
-      filePath,
-      interceptLog: logEntry,
-      proofArtifact: result.violations.length > 0 ? {
-        type: 'firewall-intercept',
-        timestamp: logEntry.timestamp,
-        violations: result.violations,
-        blocked: !result.allowed,
-      } : undefined,
+      ok: true,
+      data: result,
     };
   } catch (error) {
-    // Fallback behavior
-    if (tier !== 'pro') {
-      return {
-        allowed: true,
-        mode: 'observe',
-        message: 'Firewall intercept in observe mode (FREE). Changes logged but not blocked.',
-        violations: [],
-        agentId,
-        filePath,
-      };
+    // Fallback: compute basic next action without the module
+    const statePath = path.join(projectPath, '.vibecheck', 'summary.json');
+    let state = { hasConfig: false, lastScan: null, lastShip: null };
+    
+    try {
+      await fs.access(path.join(projectPath, '.vibecheckrc'));
+      state.hasConfig = true;
+    } catch {}
+    
+    try {
+      const summary = JSON.parse(await fs.readFile(statePath, 'utf-8'));
+      state.lastScan = { verdict: summary.verdict, score: summary.score };
+    } catch {}
+    
+    // Basic next action logic
+    let action, command, why;
+    
+    if (!state.hasConfig) {
+      action = 'init';
+      command = 'vibecheck init';
+      why = 'Project not initialized. Run init to create config.';
+    } else if (!state.lastScan) {
+      action = 'scan';
+      command = 'vibecheck scan';
+      why = 'No scans yet. Run your first scan.';
+    } else if (tier === 'pro') {
+      action = 'ship';
+      command = 'vibecheck ship';
+      why = 'Get your SHIP/WARN/BLOCK verdict.';
+    } else {
+      action = 'report';
+      command = 'vibecheck report';
+      why = 'Generate a report of your scan results.';
     }
-    return { error: `Firewall intercept failed: ${error.message}` };
+    
+    return {
+      ok: true,
+      data: {
+        action,
+        command,
+        cliCommand: command,
+        why,
+        dashboardLink: 'https://app.vibecheckai.dev',
+        docsLink: `https://docs.vibecheckai.dev/cli/${action}`,
+        timeEstimate: action === 'scan' ? '~45 seconds' : '~15 seconds',
+        requiredTier: action === 'ship' ? 'pro' : 'free',
+        priority: 'high',
+        upgradeHint: tier === 'free' && action === 'report' ? {
+          feature: 'Ship Verdict',
+          benefit: 'Get SHIP/WARN/BLOCK verdict with evidence',
+          url: 'https://vibecheckai.dev/pricing',
+        } : null,
+      },
+    };
   }
 }