ft-scout 1.0.8 → 1.1.0

package/bin/src/commands/agent.js

@@ -0,0 +1,1230 @@
+import fs from 'fs';
+import path from 'path';
+import { spinner, text, isCancel, select, confirm } from '@clack/prompts';
+import chalk from 'chalk';
+import { simpleGit } from 'simple-git';
+import { generateMultiCodeFix, identifyTargetFiles, analyzeCommandError, generateCodeScanReport, generateFeaturePlan, generateCodeFile, askRepoQuestion, getActiveModelInfo, } from '../engine/llm.js';
+import { loadContext, recordHistoryAction, saveAgentSession, getDirectoryFiles } from '../utils/config.js';
+import { renderMarkdown, safeNote } from '../utils/markdown.js';
+import { normalizeLanguage } from '../utils/language.js';
+import { createPullRequest } from '../engine/git.js';
+import { consumeCredit, checkTierAccess, loadAuthConfig, isProOrHigher } from '../utils/auth.js';
+import { handleUndo } from './undo.js';
+import { AgentExecutionLoop, buildDirectoryTree, AGENT_TOOLS } from '../engine/agentEngine.js';
+import { verifyAndSelfHealFiles, executeSmartCommand, runProjectVerification } from '../engine/verifier.js';
+import { speakText, listenSpeechToText, promptInteractionMode, cleanTextForSpeech } from '../engine/voiceEngine.js';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+const FT_DIR = path.join(process.cwd(), '.ft', 'scout');
+const SCAN_CACHE = path.join(FT_DIR, 'scan-report.json');
+function getConversationalAcknowledgment(goal) {
+    const lower = goal.toLowerCase().trim();
+    if (/^(hi|hello|hey|sup|namaste)/i.test(lower)) {
+        return "Hey there! How can I help you today?";
+    }
+    if (lower.startsWith('open ') || lower.startsWith('launch ')) {
+        const app = goal.slice(5).trim();
+        return `On it! Opening ${app} for you.`;
+    }
+    if (lower.startsWith('close ') || lower.startsWith('kill ')) {
+        const app = goal.slice(6).trim();
+        return `Sure, closing ${app}.`;
+    }
+    if (lower.startsWith('create ') || lower.startsWith('make ')) {
+        return "Understood! Getting started on creating that.";
+    }
+    if (lower.startsWith('fix ') || lower.startsWith('debug ')) {
+        return "Let's track that down. Inspecting the issue now.";
+    }
+    if (lower.startsWith('run ') || lower.startsWith('test ')) {
+        return "Running that right away.";
+    }
+    const cleanGoal = goal.replace(/["'`]/g, '');
+    const shortGoal = cleanGoal.length > 30 ? cleanGoal.slice(0, 30) + '...' : cleanGoal;
+    return `Got it! Working on ${shortGoal}.`;
+}
+function formatConversationalClosing(summary) {
+    let text = summary.trim();
+    text = text.replace(/^(?:execution|task|action)\s*(?:completed|finished|summary)?\s*:\s*/i, '');
+    text = text.replace(/^mock execution completed successfully for goal:\s*"[^"]*"\.?\s*/i, '');
+    text = cleanTextForSpeech(text);
+    if (!text.endsWith('.') && !text.endsWith('!') && !text.endsWith('?')) {
+        text += '.';
+    }
+    return text;
+}
+export function saveScanReport(issues) {
+    if (!fs.existsSync(FT_DIR)) {
+        fs.mkdirSync(FT_DIR, { recursive: true });
+    }
+    fs.writeFileSync(SCAN_CACHE, JSON.stringify(issues, null, 2));
+}
+export function loadScanReport() {
+    if (!fs.existsSync(SCAN_CACHE))
+        return [];
+    try {
+        return JSON.parse(fs.readFileSync(SCAN_CACHE, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+}
+export function extractCreateTargetFiles(rawGoal) {
+    if (!rawGoal || !rawGoal.trim())
+        return [];
+    const goalLower = rawGoal.toLowerCase().trim();
+    const isCreateIntent = /^(?:create|generate|make|build|add|write|edit|modify|update|implement|populate|fill)\b/i.test(goalLower) ||
+        /\b(?:create|generate|make|build|add|new|edit|modify|update|implement)\s+(?:a\s+)?(?:new\s+)?(?:file|files|code|script)\b/i.test(goalLower) ||
+        /\b(?:in|into|to|called|named|file|files|edit|modify|update)\s+([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+)\b/i.test(rawGoal);
+    if (!isCreateIntent)
+        return [];
+    const validExts = [
+        'ts', 'js', 'py', 'java', 'cpp', 'c', 'h', 'cs', 'go', 'rs', 'php',
+        'rb', 'html', 'css', 'json', 'md', 'sql', 'txt', 'sh', 'yaml', 'yml',
+        'xml', 'jsx', 'tsx', 'vue', 'svelte'
+    ];
+    const foundFiles = [];
+    const directMatches = rawGoal.matchAll(/(?:create|generate|make|build|add|write|edit|modify|update|implement|populate|fill|file|called|named)\s+(?:a\s+)?(?:new\s+)?(?:file\s+)?(?:in\s+)?(?:the\s+)?(?:root\s+)?(?:repo\s+|repository\s+|dir\s+|directory\s+)?(?:called\s+|named\s+)?([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+)\b/gi);
+    for (const match of directMatches) {
+        if (match && match[1]) {
+            const file = match[1].replace(/^\.\//, '');
+            if (file.toLowerCase() !== 'package.json' && !foundFiles.includes(file)) {
+                const ext = path.extname(file).replace('.', '').toLowerCase();
+                if (validExts.includes(ext)) {
+                    foundFiles.push(file);
+                }
+            }
+        }
+    }
+    const tokens = rawGoal.split(/[\s,;]+/).map((w) => w.replace(/["'()]/g, '').trim());
+    for (const token of tokens) {
+        if (token.includes('.') &&
+            !token.startsWith('.') &&
+            !token.startsWith('*') &&
+            /^[a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+$/.test(token)) {
+            const ext = path.extname(token).replace('.', '').toLowerCase();
+            if (validExts.includes(ext) && token.toLowerCase() !== 'package.json') {
+                const cleanPath = token.replace(/^\.\//, '');
+                if (!foundFiles.includes(cleanPath)) {
+                    foundFiles.push(cleanPath);
+                }
+            }
+        }
+    }
+    return foundFiles;
+}
+export function extractCreateTargetFile(rawGoal) {
+    const files = extractCreateTargetFiles(rawGoal);
+    return files.length > 0 ? files[0] : undefined;
+}
+export function parseUserPromptIntent(rawGoal, filesList) {
+    if (!rawGoal || !rawGoal.trim()) {
+        return { cleanGoal: '', intentType: 'question' };
+    }
+    let cleaned = rawGoal.trim();
+    const prefixRegex = /^(?:bro|hey|hi|hello|please|scout|ft|agent|yo|can\s+you|could\s+you|would\s+you|i\s+want\s+to|i\s+wanna|let's|lets|in\s+scout\s+agent\s+mode|so)\b\s*/gi;
+    let prev = '';
+    while (cleaned !== prev) {
+        prev = cleaned;
+        cleaned = cleaned.replace(prefixRegex, '').trim();
+    }
+    if (!cleaned)
+        cleaned = rawGoal.trim();
+    const lowerCleaned = cleaned.toLowerCase();
+    let targetFiles = extractCreateTargetFiles(cleaned);
+    if (targetFiles.length === 0) {
+        targetFiles = extractCreateTargetFiles(rawGoal);
+    }
+    let targetFile = targetFiles.length > 0 ? targetFiles[0] : undefined;
+    if (!targetFile) {
+        const tokens = cleaned.split(/\s+/).map((w) => w.replace(/["'(),;:!]/g, '').trim());
+        const validExts = [
+            'ts', 'js', 'py', 'java', 'cpp', 'c', 'h', 'cs', 'go', 'rs', 'php',
+            'rb', 'html', 'css', 'json', 'md', 'sql', 'txt', 'sh', 'yaml', 'yml',
+            'xml', 'jsx', 'tsx', 'vue', 'svelte'
+        ];
+        for (const token of tokens) {
+            if (token.includes('.') && !token.startsWith('.') && !token.startsWith('*') && /^[a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+$/.test(token)) {
+                const ext = path.extname(token).replace('.', '').toLowerCase();
+                if (validExts.includes(ext) && token.toLowerCase() !== 'package.json') {
+                    targetFile = token.replace(/^\.\//, '');
+                    targetFiles = [targetFile];
+                    break;
+                }
+            }
+        }
+    }
+    if (!targetFile) {
+        const matchedFiles = findTargetFilesFromPrompt(cleaned, undefined, filesList);
+        if (matchedFiles.length > 0) {
+            targetFile = matchedFiles[0];
+            targetFiles = matchedFiles;
+        }
+    }
+    const isScan = /\b(?:scan|bug scan|scan codebase|check for bugs|find bugs|security scan)\b/i.test(lowerCleaned);
+    if (isScan)
+        return { cleanGoal: cleaned, intentType: 'scan', targetFile, targetFiles };
+    const isRun = /^(?:run|exec|execute|terminal)\b/i.test(lowerCleaned);
+    if (isRun)
+        return { cleanGoal: cleaned, intentType: 'run', targetFile, targetFiles };
+    const isPlan = /^(?:plan|roadmap|feasibility|design|architect)\b/i.test(lowerCleaned) || /^add\s+feature\b/i.test(lowerCleaned);
+    if (isPlan)
+        return { cleanGoal: cleaned, intentType: 'plan', targetFile, targetFiles };
+    const creationKeywordsRegex = /\b(?:create|generate|make|build|add\s+file|new\s+file|write\s+file|edit\s+file|populate|write\s+code|implement\s+code|write\s+snippet|add\s+snippet|all\s+necessary\s+files)\b/i;
+    const actionVerbsRegex = /\b(?:create|generate|make|build|write|add|edit|modify|update|fix|refactor|change|delete|remove|patch|implement|populate|fill|code|put|setup)\b/i;
+    const hasActionVerb = actionVerbsRegex.test(lowerCleaned);
+    const isCreationIntent = creationKeywordsRegex.test(lowerCleaned) || Boolean(targetFiles.length > 0 && /\b(?:create|generate|make|build|write|add|edit|modify|update|populate|fill|implement|snippet|game|code)\b/i.test(lowerCleaned));
+    const pureQuestionRegex = /^(?:what|why|where|who|explain|read|display|tell|describe|list|purpose\s+of|how\s+does|how\s+is|show\s+me\s+code)\b/i;
+    const isPureQuestion = pureQuestionRegex.test(lowerCleaned) && !hasActionVerb;
+    if (isPureQuestion) {
+        return { cleanGoal: cleaned, intentType: 'question', targetFile, targetFiles };
+    }
+    if (isCreationIntent) {
+        return { cleanGoal: cleaned, intentType: 'create', targetFile, targetFiles };
+    }
+    if (hasActionVerb || targetFile) {
+        return { cleanGoal: cleaned, intentType: 'modify', targetFile, targetFiles };
+    }
+    return { cleanGoal: cleaned, intentType: 'question', targetFile, targetFiles };
+}
+export function findTargetFilesFromPrompt(userPrompt, specifiedFile, filesList) {
+    const norm = (p) => p.replace(/\\/g, '/').toLowerCase().trim();
+    if (specifiedFile && specifiedFile.trim()) {
+        const raw = specifiedFile.trim();
+        const splitItems = raw.split(',').map((s) => s.trim()).filter(Boolean);
+        const matchedFromFlag = [];
+        for (const item of splitItems) {
+            const normItem = norm(item);
+            const isExplicitExtPattern = item.startsWith('*') ||
+                item.startsWith('.') ||
+                (item.length <= 10 && !item.includes('/') && !item.includes('\\') && !filesList.some((f) => norm(f) === normItem || path.basename(norm(f)) === normItem));
+            if (isExplicitExtPattern) {
+                const cleanExt = normItem.replace(/^(\*|\.)+/, '');
+                if (cleanExt) {
+                    const extFiles = filesList.filter((f) => norm(f).endsWith(`.${cleanExt}`));
+                    matchedFromFlag.push(...extFiles);
+                }
+                continue;
+            }
+            const exact = filesList.find((f) => norm(f) === normItem);
+            if (exact) {
+                matchedFromFlag.push(exact);
+                continue;
+            }
+            const suffixMatches = filesList.filter((f) => norm(f).endsWith('/' + normItem));
+            if (suffixMatches.length > 0) {
+                matchedFromFlag.push(...suffixMatches);
+                continue;
+            }
+            const baseMatches = filesList.filter((f) => path.basename(norm(f)) === path.basename(normItem));
+            if (baseMatches.length > 0) {
+                matchedFromFlag.push(...baseMatches);
+                continue;
+            }
+            matchedFromFlag.push(item);
+        }
+        if (matchedFromFlag.length > 0) {
+            return Array.from(new Set(matchedFromFlag));
+        }
+    }
+    const rawWords = userPrompt.split(/\s+/).map((w) => w.replace(/["'(),;:!]/g, '').trim());
+    const cleanPromptWords = rawWords.map((w) => w.toLowerCase());
+    const lowerPrompt = userPrompt.toLowerCase();
+    const matchedByName = [];
+    for (const word of rawWords) {
+        if (word && word.includes('.')) {
+            const fullP = path.resolve(process.cwd(), word);
+            if (fs.existsSync(fullP) && fs.statSync(fullP).isFile()) {
+                const relP = path.relative(process.cwd(), fullP).replace(/\\/g, '/');
+                matchedByName.push(relP);
+            }
+        }
+    }
+    for (const f of filesList) {
+        const normF = norm(f);
+        const base = path.basename(normF);
+        if (lowerPrompt.includes(normF) ||
+            cleanPromptWords.includes(normF) ||
+            (base.includes('.') && (lowerPrompt.includes(base) || cleanPromptWords.includes(base)))) {
+            matchedByName.push(f);
+        }
+    }
+    if (matchedByName.length > 0) {
+        return Array.from(new Set(matchedByName));
+    }
+    const bulkExtMatch = lowerPrompt.match(/(?:all|\*|in|from|for|across|every)?\s*(?:\*|\.)?([a-zA-Z0-9]{1,10})\s+files?\b|\*\.([a-zA-Z0-9]{1,10})/i);
+    if (bulkExtMatch) {
+        const ext = (bulkExtMatch[1] || bulkExtMatch[2])?.toLowerCase();
+        if (ext) {
+            const extFiles = filesList.filter((f) => norm(f).endsWith(`.${ext}`));
+            if (extFiles.length > 0) {
+                return Array.from(new Set(extFiles));
+            }
+        }
+    }
+    return [];
+}
+export async function getAgentGoalInput(placeholderStr) {
+    return await text({
+        message: chalk.bold('Agent Prompt:'),
+        placeholder: placeholderStr,
+        validate: (val) => (!val || !val.trim() ? 'Please enter a prompt or /exit to quit' : undefined),
+    });
+}
+export async function handleAgent(goalInput, options) {
+    const tierCheck = checkTierAccess('agent');
+    if (!tierCheck.allowed) {
+        console.log(`\n${chalk.bold.red('Credit Quota Exhausted!')}`);
+        console.log(chalk.yellow(tierCheck.reason || 'Credit limit reached for Free Tier.'));
+        if (tierCheck.renewalFormatted) {
+            console.log(`Renewal: ${chalk.bold.cyan(tierCheck.renewalFormatted)}`);
+        }
+        console.log(chalk.cyan('\nTo continue using Scout CLI AI Agent:'));
+        console.log(` 1. Upgrade to ${chalk.bold.green('Pro Tier ($19/mo)')} in dashboard (${chalk.underline('scout dashboard')})`);
+        console.log(` 2. Or enable ${chalk.bold.magenta('BYOK Mode')} in dashboard to use your custom API key / proxy endpoint.\n`);
+        return;
+    }
+    const creditRes = consumeCredit(1);
+    if (!creditRes.success) {
+        console.log(`\n${chalk.bold.red('Credit Quota Exhausted!')}`);
+        console.log(chalk.yellow(creditRes.reason));
+        if (creditRes.renewalFormatted) {
+            console.log(`Renewal: ${chalk.bold.cyan(creditRes.renewalFormatted)}`);
+        }
+        console.log(chalk.cyan('\nRun `scout dashboard` to upgrade your plan or activate BYOK mode.\n'));
+        return;
+    }
+    if (creditRes.isByok) {
+        console.log(`${chalk.bold.magenta('BYOK Mode Active:')} Custom API Key / Proxy Endpoint used (${chalk.dim('Scout credits bypassed')})`);
+    }
+    else {
+        console.log(`${chalk.dim(`Scout Credit Consumed | ${creditRes.remaining} credits remaining`)}`);
+        if (creditRes.isLowCredit) {
+            console.log(`\n${chalk.bold.yellow('Low Credit Warning:')} Only ${chalk.bold(creditRes.remaining)} credits remaining on your current plan.`);
+            console.log(` ${chalk.cyan('Run `scout dashboard` to upgrade your tier or activate BYOK mode.')}\n`);
+        }
+    }
+    const existingContext = loadContext();
+    const targetLang = normalizeLanguage(options?.lang) || normalizeLanguage(existingContext?.language);
+    const cwd = process.cwd();
+    const filesList = getDirectoryFiles(cwd);
+    const projectName = existingContext?.projectName || path.basename(cwd) || 'Codebase';
+    let initialGoal = goalInput || options?.goal;
+    const isOneShot = Boolean(initialGoal || options?.scan || options?.add || options?.plan || options?.run || options?.create || options?.issue);
+    let isFirstRun = true;
+    let isAudioMode = options?.voice;
+    if (isAudioMode === undefined && !initialGoal && process.stdout.isTTY) {
+        const selectedMode = await promptInteractionMode();
+        isAudioMode = selectedMode === 'audio';
+    }
+    const authCfg = loadAuthConfig();
+    const userTier = (authCfg.currentTier || 'free').toLowerCase();
+    const isPro = isProOrHigher(userTier);
+    const agentLoop = new AgentExecutionLoop({
+        autoApprove: options?.yes,
+        maxSteps: options?.steps || options?.maxSteps || 30,
+        language: targetLang,
+        tier: userTier,
+        isAudioMode: Boolean(isAudioMode),
+    });
+    if (options?.resume) {
+        const loaded = agentLoop.getStateManager().loadTaskState(options.resume);
+        if (loaded) {
+            initialGoal = loaded.objective;
+            safeNote(`${chalk.bold.green('Resuming Autonomous Task')} ${chalk.cyan(options.resume)}\n` +
+                `Goal: ${loaded.objective}\n` +
+                `Status: ${loaded.status} (Step ${loaded.current_step})\n` +
+                `Completed Steps: ${loaded.plan.filter((s) => s.status === 'completed').length}/${loaded.plan.length}`, 'Scout Autonomous Task Resumed');
+        }
+        else {
+            safeNote(chalk.yellow(`Could not find saved task state for ID: "${options.resume}" in .ft/tasks/`), 'Scout Agent Resume');
+        }
+    }
+    const modelInfo = getActiveModelInfo();
+    const fallbackPipeline = modelInfo.fallbackChain.slice(1).join(' ➔ ');
+    const tierBadge = isPro
+        ? chalk.bold.magenta(`[Plan: ${userTier.toUpperCase()} - Autonomous & Scratchpad Enabled]`)
+        : chalk.bold.yellow(`[Plan: FREE - Basic Dev Ops (Edit/Create/Run)]`);
+    const welcomeBanner = `
+${chalk.bold.cyan('Scout Autonomous AI Agent')} ${targetLang ? `(${targetLang})` : ''} [${isAudioMode ? '🎤 Audio Mode' : '📝 Text Mode'}] ${tierBadge}
+${chalk.bold('Active Model:')} ${chalk.bold.green(modelInfo.currentActiveModel)}
+${chalk.bold('Capabilities:')} ${isPro ? chalk.green('Autonomous Computer/Browser Control + AI Scratchpad Working Memory') : chalk.dim('Basic Dev Ops (Code editing, creating files/folders, running commands - Max 5 steps)')}
+${chalk.bold('Fallback Pipeline:')} ${chalk.dim(fallbackPipeline)}
+
+${chalk.dim('Type your goal, or use slash commands:')}
+${chalk.cyan('/help')}        - Show agent tools & commands (${AGENT_TOOLS.length} tools)
+${chalk.cyan('/tree')}        - View workspace directory tree
+${chalk.cyan('/stats')}       - View real-time session & model telemetry
+${chalk.cyan('/test')}        - Run automated project test suite
+${chalk.cyan('/diff')}        - Show git diff of uncommitted changes
+${chalk.cyan('/export')}      - Save session report to .ft/
+${chalk.cyan('/undo')}        - Revert last file modifications
+${chalk.cyan('/clear')}       - Reset conversation context
+${chalk.cyan('/scan')}        - Run vulnerability scan
+${chalk.cyan('/plan')}        - Generate implementation roadmap
+${chalk.cyan('/exit')}        - Exit session
+`.trim();
+    safeNote(welcomeBanner, 'Scout Agent Active Session');
+    while (true) {
+        let rawGoal = undefined;
+        if (isFirstRun && (initialGoal || options?.scan || options?.add || options?.plan || options?.run || options?.create || options?.issue)) {
+            rawGoal = initialGoal;
+            isFirstRun = false;
+        }
+        else if (isAudioMode) {
+            isFirstRun = false;
+            options = {};
+            safeNote(chalk.cyan(' Listening to your microphone for audio interaction... Speak your goal clearly!'), ' Scout Audio Interaction');
+            const transcript = await listenSpeechToText();
+            if (transcript && transcript.trim()) {
+                rawGoal = transcript.trim();
+                safeNote(` Voice Command Received: "${chalk.bold.green(rawGoal)}"`, ' Scout STT Input');
+                const ack = getConversationalAcknowledgment(rawGoal);
+                speakText(ack, { async: true });
+            }
+            else {
+                safeNote(chalk.yellow('No speech transcript detected or listener timed out.'), ' Scout Audio Interaction');
+                continue;
+            }
+        }
+        else {
+            isFirstRun = false;
+            options = {};
+            const userGoalInput = await getAgentGoalInput('Ask question, fix bug, run command, scan issues, create file... (/help /exit)');
+            if (isCancel(userGoalInput) || typeof userGoalInput !== 'string') {
+                safeNote(chalk.yellow('Exiting Scout Agent session. see you soon!'), 'Scout Agent Ended');
+                break;
+            }
+            let trimmedInput = userGoalInput.trim();
+            const KNOWN_SLASH_COMMANDS = [
+                '/help', '/tree', '/status', '/stats', '/test', '/explain',
+                '/export', '/save-session', '/diff', '/clear', '/compact',
+                '/undo', '/history', '/scan', '/plan', '/tasks', '/resume', '/voice', '/speak',
+                '/exit', '/quit'
+            ];
+            if (trimmedInput.startsWith('/')) {
+                const cmdName = trimmedInput.split(/\s+/)[0].toLowerCase();
+                if (!KNOWN_SLASH_COMMANDS.includes(cmdName)) {
+                    const filterStr = trimmedInput.toLowerCase();
+                    let availableOptions = [
+                        { value: '/help', label: '/help', hint: 'Show agent tools & commands guide' },
+                        { value: '/tasks', label: '/tasks', hint: 'List saved autonomous tasks in .ft/tasks/' },
+                        { value: '/resume', label: '/resume', hint: 'Resume saved autonomous task by task ID' },
+                        { value: '/voice', label: '/voice', hint: 'Activate microphone STT speech input' },
+                        { value: '/speak', label: '/speak', hint: 'Speak text out loud via TTS' },
+                        { value: '/tree', label: '/tree', hint: 'Display workspace directory tree' },
+                        { value: '/stats', label: '/stats', hint: 'Show session telemetry & model statistics' },
+                        { value: '/test', label: '/test', hint: 'Run project verification test suite' },
+                        { value: '/diff', label: '/diff', hint: 'Display git diff of uncommitted changes' },
+                        { value: '/scan', label: '/scan', hint: 'Run read-only vulnerability scan' },
+                        { value: '/plan', label: '/plan', hint: 'Generate feature roadmap & plan' },
+                        { value: '/explain', label: '/explain', hint: 'Architectural breakdown of a file' },
+                        { value: '/export', label: '/export', hint: 'Save session report to .ft/' },
+                        { value: '/undo', label: '/undo', hint: 'Revert last file modifications' },
+                        { value: '/history', label: '/history', hint: 'View recent action history logs' },
+                        { value: '/clear', label: '/clear', hint: 'Reset conversation context' },
+                        { value: '/exit', label: '/exit', hint: 'Exit Scout Agent session' },
+                    ];
+                    if (filterStr !== '/') {
+                        const filtered = availableOptions.filter(o => o.value.startsWith(filterStr));
+                        if (filtered.length > 0) {
+                            availableOptions = filtered;
+                        }
+                    }
+                    const pickedCmd = await select({
+                        message: chalk.bold('Select a Slash Command:'),
+                        options: availableOptions,
+                    });
+                    if (isCancel(pickedCmd)) {
+                        continue;
+                    }
+                    let chosen = pickedCmd;
+                    if (chosen === '/explain') {
+                        const filePath = await text({
+                            message: chalk.bold('Enter file path to explain (e.g. bin/src/index.ts):'),
+                            placeholder: 'bin/src/index.ts',
+                            validate: (val) => (!val || !val.trim() ? 'File path is required' : undefined),
+                        });
+                        if (isCancel(filePath))
+                            continue;
+                        chosen = `/explain ${filePath.trim()}`;
+                    }
+                    else if (chosen === '/plan') {
+                        const idea = await text({
+                            message: chalk.bold('Enter feature idea or goal for the plan:'),
+                            placeholder: 'Add authentication middleware...',
+                            validate: (val) => (!val || !val.trim() ? 'Goal description is required' : undefined),
+                        });
+                        if (isCancel(idea))
+                            continue;
+                        chosen = `/plan ${idea.trim()}`;
+                    }
+                    else if (chosen === '/tree') {
+                        const dirInput = await text({
+                            message: chalk.bold('Enter directory path & optional depth (default "." 4):'),
+                            placeholder: '. 4',
+                        });
+                        if (!isCancel(dirInput) && typeof dirInput === 'string' && dirInput.trim()) {
+                            chosen = `/tree ${dirInput.trim()}`;
+                        }
+                    }
+                    else if (chosen === '/test') {
+                        const testCmd = await text({
+                            message: chalk.bold('Enter custom test command (press Enter for default):'),
+                            placeholder: 'npm test',
+                        });
+                        if (!isCancel(testCmd) && typeof testCmd === 'string' && testCmd.trim()) {
+                            chosen = `/test ${testCmd.trim()}`;
+                        }
+                    }
+                    trimmedInput = chosen;
+                }
+            }
+            if (['exit', 'quit', 'q', ':q', '/exit', '/quit'].includes(trimmedInput.toLowerCase())) {
+                safeNote(chalk.yellow('Exiting Scout Agent session. see you soon!'), 'Scout Agent Ended');
+                break;
+            }
+            if (trimmedInput.toLowerCase() === '/help') {
+                const helpText = `
+### 🛠️ Basic Developer Tools (Available on All Plans)
+- **read_file**: Read content & line ranges of workspace files.
+- **write_file**: Create new files and directories.
+- **edit_file**: Search & replace exact target code snippets.
+- **multi_edit_file**: Apply batch snippet replacements in a single step.
+- **run_command**: Execute terminal commands (\`npm test\`, \`npm run build\`).
+- **tree_view**: Generate visual ASCII directory tree structures.
+- **file_info**: Get file statistics, size, lines, & modification time.
+- **grep_search**: String/regex pattern search across codebase.
+- **glob_search**: Filter workspace files by file pattern.
+- **git_diff**: Retrieve uncommitted workspace git diff.
+- **ask_user**: Request missing secret credentials or API keys.
+- **task_completed**: Conclude task execution with teardown summary.
+
+### ⚡ Pro & Enterprise Exclusive Features
+- **scratchpad**: Persistent working memory & reasoning scratchpad for multi-phase tasks.
+- **computer_***: Autonomous desktop & GUI app control (screenshot, click, type, open app).
+- **browser_***: Autonomous browser automation (navigate, scrape, interact).
+- **Autonomous Loops**: Extended multi-step execution loops (30+ steps).
+
+### 🚀 Interactive Slash Commands
+- \`/help\`: Show this tools & commands guide.
+- \`/tree [dir]\`: Display workspace directory tree structure.
+- \`/status\` or \`/stats\`: Show session telemetry & statistics.
+- \`/test [cmd]\`: Run project verification test suite.
+- \`/explain <file>\`: Get deep architectural breakdown of a file.
+- \`/export\` or \`/save-session\`: Save session report to \`.ft/session-<timestamp>.md\`.
+- \`/diff\`: Display colorized git diff of uncommitted changes.
+- \`/clear\` or \`/compact\`: Reset agent conversation context.
+- \`/undo\`: Revert last file modifications.
+- \`/history\`: View recent Scout action logs.
+- \`/plan\`: Generate implementation roadmap.
+- \`/voice\`: Speak goal into microphone (STT).
+- \`/speak <text>\`: Speak text out loud (TTS).
+- \`/exit\`: End Scout Agent session.
+ `.trim();
+                safeNote(renderMarkdown(helpText), ' Scout Slash Commands & Tools');
+                continue;
+            }
+            if (trimmedInput.toLowerCase().startsWith('/speak')) {
+                const phrase = trimmedInput.slice(6).trim();
+                if (phrase) {
+                    safeNote(` Speaking text: "${phrase}"...`, ' Scout Voice TTS');
+                    await speakText(phrase);
+                }
+                else {
+                    const textToSpeak = await text({
+                        message: chalk.bold('Enter text to speak out loud:'),
+                        placeholder: 'Hello Scout Agent',
+                    });
+                    if (!isCancel(textToSpeak) && typeof textToSpeak === 'string' && textToSpeak.trim()) {
+                        safeNote(` Speaking text: "${textToSpeak}"...`, ' Scout Voice TTS');
+                        await speakText(textToSpeak.trim());
+                    }
+                }
+                continue;
+            }
+            if (trimmedInput.toLowerCase() === '/voice') {
+                safeNote(chalk.cyan(' Listening to your microphone via browser Web Speech API... Speak your goal clearly!'), ' Scout Voice STT');
+                const transcript = await listenSpeechToText();
+                if (transcript && transcript.trim()) {
+                    safeNote(` Voice Received: "${chalk.bold.green(transcript.trim())}"`, ' Scout STT Transcript');
+                    trimmedInput = transcript.trim();
+                }
+                else {
+                    safeNote(chalk.yellow('No speech transcript detected or listener timed out.'), ' Scout Voice STT');
+                    continue;
+                }
+            }
+            if (trimmedInput.toLowerCase() === '/tasks') {
+                const tasks = agentLoop.getStateManager().listSavedTasks();
+                if (tasks.length === 0) {
+                    safeNote('No saved autonomous tasks found in .ft/tasks/.', 'Saved Autonomous Tasks');
+                }
+                else {
+                    const taskList = tasks.map((t) => `• **${t.id}** [${(t.status || 'unknown').toUpperCase()}]\n  Goal: _${t.objective}_\n  Updated: ${new Date(t.updatedAt).toLocaleString()}`).join('\n\n');
+                    safeNote(renderMarkdown(taskList), `Saved Autonomous Tasks (${tasks.length})`);
+                }
+                continue;
+            }
+            if (trimmedInput.toLowerCase().startsWith('/resume')) {
+                const parts = trimmedInput.split(/\s+/).slice(1);
+                const targetId = parts[0]?.trim();
+                if (!targetId) {
+                    safeNote('Usage: /resume <taskId>', 'Resume Task');
+                    continue;
+                }
+                const loaded = agentLoop.getStateManager().loadTaskState(targetId);
+                if (!loaded) {
+                    safeNote(chalk.yellow(`No task found with ID "${targetId}" in .ft/tasks/`), 'Task Not Found');
+                    continue;
+                }
+                options = { ...options, resume: targetId };
+                trimmedInput = loaded.objective;
+            }
+            if (trimmedInput.toLowerCase().startsWith('/tree')) {
+                const parts = trimmedInput.split(/\s+/).slice(1);
+                let targetDir = '.';
+                let maxDepth = 4;
+                if (parts.length === 1) {
+                    if (/^\d+$/.test(parts[0])) {
+                        maxDepth = parseInt(parts[0], 10);
+                    }
+                    else {
+                        targetDir = parts[0];
+                    }
+                }
+                else if (parts.length >= 2) {
+                    if (/^\d+$/.test(parts[0])) {
+                        maxDepth = parseInt(parts[0], 10);
+                        targetDir = parts[1];
+                    }
+                    else {
+                        targetDir = parts[0];
+                        if (/^\d+$/.test(parts[1])) {
+                            maxDepth = parseInt(parts[1], 10);
+                        }
+                    }
+                }
+                const fullDir = path.resolve(process.cwd(), targetDir);
+                if (!fs.existsSync(fullDir) || !fs.statSync(fullDir).isDirectory()) {
+                    safeNote(chalk.yellow(`Directory not found: "${targetDir}"`), '️ Directory Tree Error');
+                }
+                else {
+                    const treeStr = buildDirectoryTree(fullDir, '', 0, maxDepth);
+                    safeNote(`Directory Tree for "${targetDir}" (depth ${maxDepth}):\n${targetDir}/\n${treeStr}`, ' Workspace Directory Tree');
+                }
+                continue;
+            }
+            if (['/status', '/stats'].includes(trimmedInput.toLowerCase())) {
+                const stats = agentLoop.getStats();
+                const modifiedFiles = agentLoop.getModifiedFiles();
+                const backups = agentLoop.getBackups();
+                const git = simpleGit();
+                let currentBranch = 'main';
+                try {
+                    const branchSummary = await git.branch();
+                    currentBranch = branchSummary.current || 'main';
+                }
+                catch { }
+                const elapsedSec = Math.round(stats.elapsedMs / 1000);
+                const activeModel = getActiveModelInfo();
+                const fallbackStatus = activeModel.lastFallbackInfo
+                    ? `Switched from \`${activeModel.lastFallbackInfo.previousModel}\` ➔ \`${activeModel.lastFallbackInfo.fallbackModel}\` (${activeModel.lastFallbackInfo.reason})`
+                    : 'None (Primary model actively responding)';
+                const statsMd = `
+### 📊 Scout Session & AI Model Telemetry
+- **Active AI Model**: \`${activeModel.currentActiveModel}\`
+- **Primary AI Model**: \`${activeModel.primaryModel}\`
+- **Fallback Chain**: \`${activeModel.fallbackChain.join(' ➔ ')}\`
+- **Last Fallback Event**: ${fallbackStatus}
+- **Active Branch**: \`${currentBranch}\`
+- **Elapsed Session Time**: \`${elapsedSec}s\`
+- **Steps Executed**: \`${stats.totalSteps}\`
+- **Total Tool Calls**: \`${stats.totalToolCalls}\`
+- **Modified Files**: \`${modifiedFiles.length}\` (${modifiedFiles.map(f => `\`${f}\``).join(', ') || 'None'})
+- **Stored File Backups**: \`${backups.length}\`
+`.trim();
+                safeNote(renderMarkdown(statsMd), ' Scout Session & Model Telemetry');
+                continue;
+            }
+            if (trimmedInput.toLowerCase().startsWith('/test')) {
+                const parts = trimmedInput.split(/\s+/);
+                const customCmd = parts.slice(1).join(' ') || options?.verifyCmd;
+                const testSpin = spinner();
+                testSpin.start(`Running project verification test suite ${customCmd ? `(\`${customCmd}\`)` : ''}...`);
+                const testRes = await runProjectVerification(process.cwd(), customCmd);
+                if (testRes.valid) {
+                    testSpin.stop(chalk.green('Project verification tests passed cleanly!'));
+                    safeNote(`${chalk.green(' Verification Passed:')}\n\`\`\`\n${testRes.output.slice(0, 3000)}\n\`\`\``, ' Test Suite Clean');
+                }
+                else {
+                    testSpin.stop(chalk.red('Project verification test suite failed.'));
+                    safeNote(`${chalk.red('️ Verification Failed:')}\n${testRes.errors.join('\n')}\n\`\`\`\n${testRes.output.slice(0, 3000)}\n\`\`\``, ' Test Failure Warning');
+                }
+                continue;
+            }
+            if (trimmedInput.toLowerCase().startsWith('/explain')) {
+                const parts = trimmedInput.split(/\s+/);
+                const targetPath = parts[1];
+                if (!targetPath) {
+                    safeNote(chalk.yellow('Usage: /explain <filePath> (e.g. /explain bin/src/index.ts)'), ' Explain Command');
+                    continue;
+                }
+                const fullP = path.resolve(process.cwd(), targetPath);
+                if (!fs.existsSync(fullP)) {
+                    safeNote(chalk.yellow(`File not found: ${targetPath}`), ' Explain Error');
+                    continue;
+                }
+                const explainSpin = spinner();
+                explainSpin.start(`Analyzing architecture and structure of ${targetPath}...`);
+                const content = fs.readFileSync(fullP, 'utf-8');
+                const explanation = await askRepoQuestion(`Provide a deep architectural breakdown, primary purpose, component breakdown, and code explanation for file "${targetPath}":\n\`\`\`\n${content.slice(0, 6000)}\n\`\`\``, projectName, filesList, '', [], { language: targetLang });
+                explainSpin.stop('Analysis complete.');
+                safeNote(renderMarkdown(explanation), ` Architectural Breakdown: ${targetPath}`);
+                continue;
+            }
+            if (['/export', '/save-session'].includes(trimmedInput.toLowerCase())) {
+                const ftDir = path.join(process.cwd(), '.ft', 'scout');
+                if (!fs.existsSync(ftDir))
+                    fs.mkdirSync(ftDir, { recursive: true });
+                const timeStamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const sessionPath = path.join(ftDir, `session-${timeStamp}.md`);
+                const stats = agentLoop.getStats();
+                const modifiedFiles = agentLoop.getModifiedFiles();
+                const history = (await import('../utils/config.js')).loadHistory();
+                const exportContent = `# Scout Agent Session Report
+Date: ${new Date().toLocaleString()}
+Project: ${projectName}
+
+## Session Statistics
+- Total Steps: ${stats.totalSteps}
+- Tool Calls: ${stats.totalToolCalls}
+- Modified Files Count: ${modifiedFiles.length}
+
+## Modified Files
+${modifiedFiles.map(f => `- ${f}`).join('\n') || 'None'}
+
+## Action History
+${history.slice(0, 15).map(h => `- [${h.timestamp}] ${h.command}: ${h.description}`).join('\n')}
+`;
+                fs.writeFileSync(sessionPath, exportContent, 'utf-8');
+                safeNote(chalk.green(`Session report saved to: ${chalk.bold.cyan(path.relative(process.cwd(), sessionPath))}`), ' Session Exported');
+                continue;
+            }
+            if (trimmedInput.toLowerCase() === '/diff') {
+                try {
+                    const { execSync } = await import('child_process');
+                    const gitDiff = execSync('git diff', { encoding: 'utf-8', cwd: process.cwd() });
+                    if (!gitDiff || !gitDiff.trim()) {
+                        safeNote(chalk.green('No uncommitted changes found in the workspace.'), ' Workspace Git Diff');
+                    }
+                    else {
+                        const previewLines = gitDiff.split('\n');
+                        const truncated = previewLines.length > 200 ? previewLines.slice(0, 200).join('\n') + `\n... [truncated, ${previewLines.length} total lines]` : gitDiff;
+                        safeNote(truncated, ' Workspace Git Diff');
+                    }
+                }
+                catch {
+                    safeNote(chalk.yellow('Could not retrieve git diff. Ensure this directory is a git repository.'), '️ Git Diff Failed');
+                }
+                continue;
+            }
+            if (['/clear', '/compact'].includes(trimmedInput.toLowerCase())) {
+                agentLoop.resetContext();
+                safeNote(chalk.green('Agent context reset successfully.'), ' Session Context Cleared');
+                continue;
+            }
+            if (trimmedInput.toLowerCase() === '/undo') {
+                await handleUndo();
+                continue;
+            }
+            if (['/history', '/sessions'].includes(trimmedInput.toLowerCase())) {
+                const history = (await import('../utils/config.js')).loadHistory();
+                const sessions = (await import('../utils/session.js')).loadAgentSessions(5);
+                let historyMd = '### Agent Session History Memory (Previous 3+ Sessions)\n';
+                if (sessions.length === 0) {
+                    historyMd += '*No previous agent sessions recorded yet.*\n';
+                }
+                else {
+                    historyMd += sessions.map((s, i) => `- **Session #${sessions.length - i}** (${new Date(s.timestamp).toLocaleString()}):\n` +
+                        `  • Goal: "${s.goal}"\n` +
+                        `  • Summary: ${s.summary}\n` +
+                        `  • Modified Files: ${s.modifiedFiles && s.modifiedFiles.length > 0 ? s.modifiedFiles.map(f => `\`${f}\``).join(', ') : 'None'}`).join('\n\n') + '\n';
+                }
+                historyMd += '\n### Recorded File Action Log\n';
+                historyMd += history.slice(0, 10).map((h) => `- **${h.timestamp}**: \`${h.command}\`  ${h.description}`).join('\n') || 'No action history recorded yet.';
+                safeNote(renderMarkdown(historyMd), ' Scout History & Session Memory');
+                continue;
+            }
+            rawGoal = trimmedInput;
+        }
+        if (!rawGoal || !rawGoal.trim()) {
+            continue;
+        }
+        const parsedIntent = parseUserPromptIntent(rawGoal, filesList);
+        const effectiveGoal = parsedIntent.cleanGoal || rawGoal;
+        const goalLower = effectiveGoal.toLowerCase().trim();
+        // -------------------------------------------------------------
+        // Mode 1: Codebase Scan Mode (--scan or /scan)
+        // -------------------------------------------------------------
+        const isScanIntent = Boolean(options?.scan || (rawGoal && rawGoal.trim().startsWith('/scan')));
+        if (isScanIntent) {
+            const s = spinner();
+            s.start(' Scout Agent: Performing read-only bug & vulnerability scan...');
+            let codeSample = '';
+            const pkgPath = path.join(cwd, 'package.json');
+            if (fs.existsSync(pkgPath)) {
+                codeSample += fs.readFileSync(pkgPath, 'utf-8').slice(0, 1000) + '\n';
+            }
+            const issues = await generateCodeScanReport(projectName, filesList, codeSample);
+            saveScanReport(issues);
+            s.stop('Bug scan complete.');
+            const severityBadge = (sev) => {
+                switch (sev.toLowerCase()) {
+                    case 'high':
+                        return chalk.bgRed.white.bold(' HIGH ');
+                    case 'medium':
+                        return chalk.bgYellow.black.bold(' MEDIUM ');
+                    default:
+                        return chalk.bgBlue.white.bold(' LOW ');
+                }
+            };
+            const reportLines = issues.map((iss) => `${chalk.bold.cyan(`[Issue #${iss.id}]`)} ${severityBadge(iss.severity)} ${chalk.bold(iss.title)}\n` +
+                ` • File: ${chalk.yellow(iss.file)}\n` +
+                ` • Detail: ${iss.description}`);
+            safeNote(`Found ${issues.length} potential issues matching past hotfix patterns:\n\n` +
+                reportLines.join('\n\n') +
+                `\n\n${chalk.bold.green(' How to Auto-Fix Any Issue with Agent:')}\n` +
+                ` • Auto-fix Issue #${issues[0]?.id || 1}: ${chalk.bold.cyan(`scout agent --issue ${issues[0]?.id || 1}`)}\n` +
+                ` • Custom prompt auto-fix: ${chalk.bold.cyan('scout agent "Fix null check in src/index.ts"')}`, ' Scout Agent Bug Scan');
+            continue;
+        }
+        // -------------------------------------------------------------
+        // Mode 2: Feature Roadmap Plan Mode (--plan / --add or /plan)
+        // -------------------------------------------------------------
+        const planMatch = rawGoal ? rawGoal.match(/^\/plan\s+(.+)/i) : undefined;
+        const addIdea = options?.add || options?.plan || (planMatch ? planMatch[1] : undefined);
+        if (addIdea && !options?.create) {
+            const s = spinner();
+            s.start(` Scout Agent: Evaluating feasibility & generating roadmap for "${chalk.cyan(addIdea)}"...`);
+            const plan = await generateFeaturePlan(addIdea, projectName, filesList, targetLang, options?.native);
+            s.stop('Feasibility assessment & roadmap complete.');
+            safeNote(renderMarkdown(plan), ` Feature Implementation Roadmap: "${addIdea}"`);
+            continue;
+        }
+        // -------------------------------------------------------------
+        // Mode 3: Run Command Execution & Auto-Fix Mode (--run or /run)
+        // -------------------------------------------------------------
+        const runMatch = rawGoal ? rawGoal.match(/^\/run\s+["']?([^"']+)["']?$/i) : undefined;
+        const runCmdInput = options?.run || (runMatch ? runMatch[1] : undefined);
+        if (runCmdInput) {
+            const fullCommand = Array.isArray(runCmdInput) ? runCmdInput.join(' ') : runCmdInput;
+            safeNote(`Running command: ${chalk.bold.cyan(fullCommand)}\n${chalk.dim('Working directory: ' + cwd)}`, ' Scout Shell Execution');
+            const runSpinner = spinner();
+            runSpinner.start(`Executing \`${fullCommand}\`...`);
+            const res = await executeSmartCommand(fullCommand, cwd, 3000);
+            if (res.isBackgroundServer) {
+                runSpinner.stop(chalk.green(`Command \`${fullCommand}\` started in background (PID ${res.pid}).`));
+                safeNote(`${chalk.green('')} Background server process started (PID ${res.pid}). Output so far:\n\`\`\`\n${res.output}\n\`\`\``, ' Background Execution Active');
+                continue;
+            }
+            const exitCode = res.exitCode;
+            const fullOutput = res.output;
+            if (exitCode === 0) {
+                runSpinner.stop(chalk.green(`Command \`${fullCommand}\` executed successfully (Exit Code 0).`));
+                safeNote(`${chalk.green('')} Process completed with exit code 0.`, ' Execution Successful');
+                continue;
+            }
+            runSpinner.stop(chalk.red(`Command \`${fullCommand}\` failed with exit code ${exitCode}.`));
+            const diagSpinner = spinner();
+            diagSpinner.start('Scout AI is analyzing process failure output...');
+            const analysis = await analyzeCommandError(fullCommand, exitCode, fullOutput, projectName, filesList, targetLang, options?.native);
+            diagSpinner.stop(chalk.yellow('Failure diagnosis complete.'));
+            const diagMarkdown = `
+### Process Failure Diagnosis
+Command: \`${fullCommand}\` (Exit Code ${exitCode})
+
+### Root Cause Analysis
+${analysis.rootCause}
+
+### Suggested Fix
+${analysis.suggestedFix}
+${analysis.targetFileToFix ? `\n### Suspected File\n\`${analysis.targetFileToFix}\`` : ''}
+ `.trim();
+            safeNote(renderMarkdown(diagMarkdown), '️ Scout AI Failure Diagnosis');
+            const shouldFix = await confirm({
+                message: chalk.bold('Would you like Scout Agent to auto-fix the failing code automatically?'),
+                initialValue: true,
+            });
+            if (!isCancel(shouldFix) && shouldFix) {
+                rawGoal = `Fix runtime/build error from command \`${fullCommand}\`. Cause: ${analysis.rootCause}`;
+                options = { ...options, file: analysis.targetFileToFix };
+            }
+            else {
+                continue;
+            }
+        }
+        // -------------------------------------------------------------
+        // Mode 4: Create File Generation Mode (Explicit --create flag only)
+        // -------------------------------------------------------------
+        const targetCreateFiles = options?.create
+            ? options.create.split(',').map((s) => s.trim()).filter(Boolean)
+            : undefined;
+        if (targetCreateFiles && targetCreateFiles.length > 0) {
+            let finalPrompt = effectiveGoal;
+            if (!finalPrompt || !finalPrompt.trim()) {
+                const userPromptInput = await text({
+                    message: chalk.bold(`What should Scout generate inside ${chalk.cyan(targetCreateFiles.join(', '))}?`),
+                    placeholder: 'e.g. Create source files with modules, styles, and logic',
+                    validate: (val) => (!val || !val.trim() ? 'Please provide a prompt describing the file requirements' : undefined),
+                });
+                if (isCancel(userPromptInput)) {
+                    safeNote(chalk.yellow('File creation operation cancelled.'), ' Scout File Creation');
+                    continue;
+                }
+                finalPrompt = userPromptInput.trim();
+            }
+            const createdFilesSummary = [];
+            const backups = [];
+            const affectedFiles = [];
+            const git = simpleGit();
+            const isRepo = await git.checkIsRepo();
+            let currentBranch = 'main';
+            if (isRepo) {
+                try {
+                    const branchSummary = await git.branch();
+                    currentBranch = branchSummary.current || 'main';
+                }
+                catch { }
+            }
+            const s = spinner();
+            s.start(` Scout Agent: Generating ${targetCreateFiles.length} file(s) (${targetCreateFiles.join(', ')})...`);
+            let hasError = false;
+            for (const targetFilePath of targetCreateFiles) {
+                const resolvedPath = path.resolve(cwd, targetFilePath);
+                const fileExists = fs.existsSync(resolvedPath);
+                const originalContent = fileExists ? fs.readFileSync(resolvedPath, 'utf-8') : '__FT_WAS_NEW__';
+                try {
+                    const contextPrompt = finalPrompt + (createdFilesSummary.length > 0 ? `\n\nContext of already generated files in this batch:\n` + createdFilesSummary.map(f => `--- File: ${f.path} ---\n${f.code.slice(0, 1000)}`).join('\n') : '');
+                    const genResult = await generateCodeFile(targetFilePath, contextPrompt, projectName, filesList, targetLang, options?.native);
+                    if (!genResult.code || !genResult.code.trim()) {
+                        continue;
+                    }
+                    const parentDir = path.dirname(resolvedPath);
+                    if (!fs.existsSync(parentDir)) {
+                        fs.mkdirSync(parentDir, { recursive: true });
+                    }
+                    fs.writeFileSync(resolvedPath, genResult.code, 'utf-8');
+                    backups.push({ filePath: targetFilePath, originalContent });
+                    affectedFiles.push(targetFilePath);
+                    createdFilesSummary.push({ path: targetFilePath, code: genResult.code, description: genResult.description });
+                }
+                catch (err) {
+                    hasError = true;
+                    s.stop(chalk.red(`Failed to generate code for ${targetFilePath}.`));
+                    safeNote(chalk.red(`Error: ${err?.message || String(err)}`), '️ Code Generation Error');
+                    break;
+                }
+            }
+            if (hasError || createdFilesSummary.length === 0) {
+                if (!hasError) {
+                    s.stop(chalk.red('Failed to generate code files.'));
+                    safeNote(chalk.yellow(`Scout AI returned empty code content. Please refine your prompt describing what code to write.`), '️ Empty Code Generated');
+                }
+                continue;
+            }
+            recordHistoryAction({
+                command: `scout agent --create "${affectedFiles.join(',')}" "${finalPrompt}"`,
+                description: `Scout created ${createdFilesSummary.length} file(s): ${affectedFiles.join(', ')}`,
+                previousBranch: currentBranch,
+                affectedFiles,
+                backups,
+            });
+            saveAgentSession({
+                goal: `Create file(s) ${affectedFiles.join(', ')}: ${finalPrompt}`,
+                summary: `Scout created ${createdFilesSummary.length} file(s): ${affectedFiles.join(', ')}`,
+                modifiedFiles: affectedFiles,
+            });
+            s.stop(chalk.green(`Successfully created ${createdFilesSummary.length} file(s)!`));
+            // Run automated syntax check and self-healing retries on created files
+            const healRes = await verifyAndSelfHealFiles(affectedFiles, cwd, projectName, filesList, {
+                verifyCmd: options?.verifyCmd,
+                maxRetries: options?.maxRetries || 3,
+                language: targetLang,
+                native: options?.native,
+            });
+            if (healRes.verifiedFiles.length > 0) {
+                safeNote(chalk.green(` Automated Verification Confirmed: ${healRes.verifiedFiles.length} file(s) syntax & build verified clean!`), ' Code Verification Clean');
+            }
+            if (healRes.remainingErrors.length > 0) {
+                safeNote(chalk.yellow(`️ Remaining verification issues:\n${healRes.remainingErrors.join('\n')}`), '️ Verification Warning');
+            }
+            const filePreviews = createdFilesSummary.map((f) => `#### \`${f.path}\`\n${f.description}\n\`\`\`\n${f.code.slice(0, 400)}${f.code.length > 400 ? '\n... (truncated)' : ''}\n\`\`\``).join('\n\n');
+            const teardownContent = `
+### Created Files (${createdFilesSummary.length})
+${createdFilesSummary.map(f => ` • \`${f.path}\``).join('\n')}
+
+### Overview & Previews
+${filePreviews}
+ `.trim();
+            safeNote(renderMarkdown(teardownContent), ' Scout File Creation Teardown');
+            if (options?.yes || !process.stdout.isTTY) {
+                safeNote(`${chalk.green('')} Saved ${chalk.bold.cyan(affectedFiles.length + ' file(s)')} on branch ${chalk.bold.green(currentBranch)}.\n` +
+                    ` ${chalk.dim('You can revert this creation anytime by running:')} ${chalk.cyan('scout undo')}`, ' Creation Confirmed');
+                continue;
+            }
+            const actionChoice = await select({
+                message: chalk.bold('Review Scout Agent\'s generated file(s). What would you like to do?'),
+                options: [
+                    { value: 'keep', label: ' Keep Files', hint: `Retain newly created files directly on current branch (${currentBranch})` },
+                    { value: 'pr', label: ' Create Pull Request', hint: 'Push created files to a new branch & open a Pull Request' },
+                    { value: 'revert', label: '️ Revert / Delete Files', hint: 'Remove created files immediately' },
+                ],
+            });
+            if (isCancel(actionChoice) || actionChoice === 'revert') {
+                const revSpinner = spinner();
+                revSpinner.start('Reverting Scout Agent\'s file creations...');
+                await handleUndo();
+                revSpinner.stop('Creation reverted successfully.');
+                continue;
+            }
+            if (actionChoice === 'pr') {
+                const prSpinner = spinner();
+                prSpinner.start('Creating Pull Request...');
+                const prRes = await createPullRequest({
+                    branchPrefix: 'create',
+                    title: `feat: Create ${affectedFiles.join(', ')}`,
+                    affectedFiles,
+                    commitMessage: `feat: Create ${affectedFiles.join(', ')}`,
+                });
+                prSpinner.stop('Pull Request workflow processed.');
+                safeNote(`${chalk.green('')} ${prRes.message}\n` +
+                    ` ${chalk.dim('You remain on active branch:')} ${chalk.cyan(currentBranch)}`, ' Pull Request Status');
+                continue;
+            }
+            safeNote(`${chalk.green('')} Saved ${chalk.bold.cyan(affectedFiles.length + ' file(s)')} on branch ${chalk.bold.green(currentBranch)}.\n` +
+                ` ${chalk.dim('You can revert this creation anytime by running:')} ${chalk.cyan('scout undo')}`, ' Creation Confirmed');
+            continue;
+        }
+        // -------------------------------------------------------------
+        // Mode 5: Autonomous ReAct Tool-Calling Agent Loop
+        // -------------------------------------------------------------
+        let finalGoal = effectiveGoal || rawGoal;
+        if (!finalGoal && options?.issue) {
+            const report = loadScanReport();
+            const issueId = Number(options.issue);
+            const targetIssue = report.find((i) => i.id === issueId) || report[0];
+            if (targetIssue) {
+                finalGoal = `Fix issue #${targetIssue.id}: ${targetIssue.title}  ${targetIssue.description}`;
+            }
+        }
+        if (!finalGoal || !finalGoal.trim()) {
+            safeNote(chalk.yellow('No active goal specified.'), ' Scout Agent');
+            continue;
+        }
+        const git = simpleGit();
+        const isRepo = await git.checkIsRepo();
+        let currentBranch = 'main';
+        if (isRepo) {
+            try {
+                const branchSummary = await git.branch();
+                currentBranch = branchSummary.current || 'main';
+            }
+            catch { }
+        }
+        // Fast Multi-File Fix path via generateMultiCodeFix if --issue is set
+        if (options?.issue) {
+            const idSpinner = spinner();
+            idSpinner.start('Scout AI: Identifying affected target files...');
+            const targetFiles = await identifyTargetFiles(finalGoal, projectName, filesList, targetLang, options?.native);
+            idSpinner.stop(targetFiles.length > 0 ? `Identified ${targetFiles.length} target file(s): ${targetFiles.join(', ')}` : 'Target identification complete.');
+            if (targetFiles.length > 0) {
+                const targetMap = {};
+                for (const tf of targetFiles) {
+                    const absP = path.resolve(cwd, tf);
+                    if (fs.existsSync(absP)) {
+                        targetMap[tf] = fs.readFileSync(absP, 'utf-8');
+                    }
+                }
+                if (Object.keys(targetMap).length > 0) {
+                    const fixSpinner = spinner();
+                    fixSpinner.start(`Scout AI: Generating multi-file fixes for ${Object.keys(targetMap).join(', ')}...`);
+                    const multiFixRes = await generateMultiCodeFix(finalGoal, projectName, filesList, targetMap, targetLang, options?.native, (done, total, curFile) => {
+                        fixSpinner.message(`Generating fix for ${curFile} (${done}/${total})...`);
+                    });
+                    fixSpinner.stop('Multi-file fixes generated.');
+                    const backups = [];
+                    const affectedFiles = [];
+                    for (const item of multiFixRes.files) {
+                        const absPath = path.resolve(cwd, item.targetFile);
+                        if (fs.existsSync(absPath)) {
+                            backups.push({
+                                filePath: item.targetFile,
+                                originalContent: fs.readFileSync(absPath, 'utf-8'),
+                            });
+                        }
+                        fs.mkdirSync(path.dirname(absPath), { recursive: true });
+                        fs.writeFileSync(absPath, item.fixedCode, 'utf-8');
+                        affectedFiles.push(item.targetFile);
+                    }
+                    recordHistoryAction({
+                        command: `scout agent --issue ${options.issue}`,
+                        description: `Auto-fixed issue on ${affectedFiles.length} file(s)`,
+                        previousBranch: currentBranch,
+                        affectedFiles,
+                        backups,
+                    });
+                    saveAgentSession({
+                        goal: `Auto-fix issue #${options.issue}: ${finalGoal}`,
+                        summary: `Auto-fixed issue on ${affectedFiles.length} file(s): ${affectedFiles.join(', ')}`,
+                        modifiedFiles: affectedFiles,
+                    });
+                    safeNote(`### Fixed Issue\n${multiFixRes.problem}\n\n### Fix Applied\n${multiFixRes.howFixed}\n\n### Modified Files\n${affectedFiles.map(f => ` • \`${f}\``).join('\n')}`, ' Scout Multi-File Auto-Fix Complete');
+                    continue;
+                }
+            }
+        }
+        // Standard Agent Goal Execution: Pre-scan & identify target files ONLY if goal is a code modification task
+        const hasModificationIntent = /\b(fix|edit|modify|update|refactor|patch|change|debug|error|bug|issue|solve|repair)\b/i.test(finalGoal) &&
+            !/\b(lookup|look\s*up|who|what|why|where|how|explain|describe|tell|status|check|github|mcp|open|launch)\b/i.test(finalGoal);
+        let targetFiles = [];
+        if (hasModificationIntent && !options?.file) {
+            const idSpinner = spinner();
+            idSpinner.start('Scout Agent: Thinking');
+            targetFiles = await identifyTargetFiles(finalGoal, projectName, filesList, targetLang, options?.native);
+            idSpinner.stop(targetFiles.length > 0 ? `Target files resolved: ${targetFiles.map(f => `\`${f}\``).join(', ')}` : 'Analysis complete.');
+        }
+        safeNote(`${chalk.bold.cyan(' Scout Autonomous Execution Initialized')}\n` +
+            `${chalk.dim('Goal:')} ${finalGoal}` +
+            (targetFiles.length > 0 ? `\n${chalk.dim('Target Files:')} ${targetFiles.map(f => `\`${f}\``).join(', ')}` : ''), ' Scout Agent Execution');
+        const execResult = options?.resume
+            ? await agentLoop.resumeGoal(options.resume)
+            : await agentLoop.executeGoal(finalGoal);
+        const modifiedFiles = agentLoop.getModifiedFiles();
+        const backups = agentLoop.getBackups();
+        if (isRepo) {
+            try {
+                const branchSummary = await git.branch();
+                currentBranch = branchSummary.current || 'main';
+            }
+            catch { }
+        }
+        if (modifiedFiles.length > 0) {
+            recordHistoryAction({
+                command: `scout agent "${finalGoal}"`,
+                description: `Scout agent completed goal on ${modifiedFiles.length} file(s)`,
+                previousBranch: currentBranch,
+                affectedFiles: modifiedFiles,
+                backups,
+            });
+        }
+        const isCodeModTask = modifiedFiles.length > 0;
+        const resultSectionTitle = isCodeModTask ? 'Execution Summary' : 'Answer & Findings';
+        const teardownMd = `
+### Agent Goal
+${finalGoal}
+
+### Modified File(s)
+${modifiedFiles.map((f) => ` • \`${f}\``).join('\n') || ' • None'}
+
+### ${resultSectionTitle}
+${execResult.summary}
+ `.trim();
+        safeNote(renderMarkdown(teardownMd), isCodeModTask ? ' Scout Execution Teardown Report' : ' Scout Response');
+        if (isAudioMode && execResult?.summary) {
+            safeNote(` Speaking conversational response out loud...`, ' Scout Audio Output');
+            const spokenClosing = formatConversationalClosing(execResult.summary);
+            await speakText(spokenClosing);
+        }
+        if (modifiedFiles.length === 0) {
+            if (isOneShot)
+                break;
+            continue;
+        }
+        if (options?.yes || !process.stdout.isTTY) {
+            safeNote(`${chalk.green('')} Agent changes retained on ${modifiedFiles.length} file(s) (Branch: ${chalk.bold.green(currentBranch)}).\n` +
+                ` ${chalk.dim('You can revert anytime by running:')} ${chalk.cyan('scout undo')}`, ' Agent Execution Confirmed');
+            if (isOneShot)
+                break;
+            continue;
+        }
+        const actionChoice = await select({
+            message: chalk.bold('Review Scout Agent result. What would you like to do?'),
+            options: [
+                { value: 'keep', label: ' Keep Changes', hint: `Retain agent changes on current branch (${currentBranch})` },
+                { value: 'test', label: ' Run Verification Tests', hint: 'Execute test suite to confirm zero regressions' },
+                { value: 'pr', label: ' Create Pull Request', hint: 'Push fix to a new branch & open a Pull Request' },
+                { value: 'export', label: ' Export Session Report', hint: 'Save detailed session teardown report to .ft/' },
+                { value: 'revert', label: '️ Revert Changes', hint: 'Restore original code immediately' },
+            ],
+        });
+        if (actionChoice === 'revert') {
+            const revSpinner = spinner();
+            revSpinner.start('Reverting Agent changes...');
+            await handleUndo();
+            revSpinner.stop('Changes reverted successfully.');
+            continue;
+        }
+        if (actionChoice === 'test') {
+            const testSpin = spinner();
+            testSpin.start('Running project verification test suite...');
+            const testRes = await runProjectVerification(process.cwd(), options?.verifyCmd);
+            if (testRes.valid) {
+                testSpin.stop(chalk.green('Project verification tests passed cleanly!'));
+                safeNote(`${chalk.green(' Verification Passed:')}\n\`\`\`\n${testRes.output.slice(0, 3000)}\n\`\`\``, ' Test Suite Clean');
+            }
+            else {
+                testSpin.stop(chalk.red('Project verification test suite failed.'));
+                safeNote(`${chalk.red('️ Verification Failed:')}\n${testRes.errors.join('\n')}\n\`\`\`\n${testRes.output.slice(0, 3000)}\n\`\`\``, ' Test Failure Warning');
+            }
+            continue;
+        }
+        if (actionChoice === 'export') {
+            const ftDir = path.join(process.cwd(), '.ft', 'scout');
+            if (!fs.existsSync(ftDir))
+                fs.mkdirSync(ftDir, { recursive: true });
+            const timeStamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const sessionPath = path.join(ftDir, `session-${timeStamp}.md`);
+            const stats = agentLoop.getStats();
+            const exportContent = `# Scout Agent Session Report
+Date: ${new Date().toLocaleString()}
+Project: ${projectName}
+Goal: ${finalGoal}
+
+## Session Statistics
+- Total Steps: ${stats.totalSteps}
+- Tool Calls: ${stats.totalToolCalls}
+- Modified Files Count: ${modifiedFiles.length}
+
+## Modified Files
+${modifiedFiles.map(f => `- ${f}`).join('\n') || 'None'}
+
+## Execution Summary
+${execResult.summary}
+`;
+            fs.writeFileSync(sessionPath, exportContent, 'utf-8');
+            safeNote(chalk.green(`Session report saved to: ${chalk.bold.cyan(path.relative(process.cwd(), sessionPath))}`), ' Session Exported');
+            continue;
+        }
+        if (actionChoice === 'pr') {
+            const prSpinner = spinner();
+            prSpinner.start('Creating Pull Request...');
+            const prRes = await createPullRequest({
+                branchPrefix: 'agent',
+                title: finalGoal,
+                affectedFiles: modifiedFiles,
+                commitMessage: `feat: ${finalGoal}`,
+            });
+            prSpinner.stop('Pull Request workflow processed.');
+            safeNote(`${chalk.green('')} ${prRes.message}\n` +
+                ` ${chalk.dim('You remain on active branch:')} ${chalk.cyan(currentBranch)}`, ' Pull Request Status');
+            continue;
+        }
+        safeNote(`${chalk.green('')} Agent changes retained on ${modifiedFiles.length} file(s) (Branch: ${chalk.bold.green(currentBranch)}).\n` +
+            ` ${chalk.dim('You can revert these changes anytime by running:')} ${chalk.cyan('scout undo')}`, ' Agent Workflow Finished');
+        if (isOneShot)
+            break;
+    }
+}
+//# sourceMappingURL=agent.js.map