@amplitude/wizard 1.0.0-beta.0

package/dist/src/lib/agent-interface.js

@@ -0,0 +1,1217 @@
+"use strict";
+/**
+ * Shared agent interface for Amplitude wizards
+ * Uses Claude Agent SDK directly with Amplitude LLM gateway
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentErrorType = exports.AgentSignals = void 0;
+exports.checkClaudeSettingsOverrides = checkClaudeSettingsOverrides;
+exports.backupAndFixClaudeSettings = backupAndFixClaudeSettings;
+exports.restoreClaudeSettings = restoreClaudeSettings;
+exports.createStopHook = createStopHook;
+exports.buildWizardMetadata = buildWizardMetadata;
+exports.isSkillInstallCommand = isSkillInstallCommand;
+exports.matchesAllowedPrefix = matchesAllowedPrefix;
+exports.wizardCanUseTool = wizardCanUseTool;
+exports.initializeAgent = initializeAgent;
+exports.getAgent = getAgent;
+exports.runAgentLocally = runAgentLocally;
+exports.runAgent = runAgent;
+const path_1 = __importDefault(require("path"));
+const fs = __importStar(require("fs"));
+const ui_1 = require("../ui");
+const debug_1 = require("../utils/debug");
+const analytics_1 = require("../utils/analytics");
+const constants_1 = require("./constants");
+const wizard_session_1 = require("./wizard-session");
+const wizard_abort_1 = require("../utils/wizard-abort");
+const custom_headers_1 = require("../utils/custom-headers");
+const urls_1 = require("../utils/urls");
+const ampli_settings_1 = require("../utils/ampli-settings");
+const safe_tools_1 = require("./safe-tools");
+const wizard_tools_1 = require("./wizard-tools");
+const commandments_1 = require("./commandments");
+const zod_1 = require("zod");
+const schemas_1 = require("./middleware/schemas");
+const agent_hooks_1 = require("./agent-hooks");
+// Dynamic import cache for ESM module
+let _sdkModule = null;
+async function getSDKModule() {
+    if (!_sdkModule) {
+        const mod = await import('@anthropic-ai/claude-agent-sdk');
+        _sdkModule = { query: mod.query };
+    }
+    return _sdkModule;
+}
+/**
+ * Get the path to the bundled Claude Code CLI from the SDK package.
+ * This ensures we use the SDK's bundled version rather than the user's installed Claude Code.
+ */
+function getClaudeCodeExecutablePath() {
+    // require.resolve finds the package's main entry, then we get cli.js from same dir
+    const sdkPackagePath = require.resolve('@anthropic-ai/claude-agent-sdk');
+    return path_1.default.join(path_1.default.dirname(sdkPackagePath), 'cli.js');
+}
+exports.AgentSignals = {
+    /** Signal emitted when the agent reports progress to the user */
+    STATUS: '[STATUS]',
+    /** Signal emitted when the agent cannot access the Amplitude MCP server */
+    ERROR_MCP_MISSING: '[ERROR-MCP-MISSING]',
+    /** Signal emitted when the agent cannot access the setup resource */
+    ERROR_RESOURCE_MISSING: '[ERROR-RESOURCE-MISSING]',
+    /** Signal emitted when the agent provides a remark about its run */
+    WIZARD_REMARK: '[WIZARD-REMARK]',
+    /** Signal prefix for benchmark logging */
+    BENCHMARK: '[BENCHMARK]',
+};
+/**
+ * Error types that can be returned from agent execution.
+ * These correspond to the error signals that the agent emits.
+ */
+var AgentErrorType;
+(function (AgentErrorType) {
+    /** Agent could not access the Amplitude MCP server */
+    AgentErrorType["MCP_MISSING"] = "WIZARD_MCP_MISSING";
+    /** Agent could not access the setup resource */
+    AgentErrorType["RESOURCE_MISSING"] = "WIZARD_RESOURCE_MISSING";
+    /** API rate limit exceeded */
+    AgentErrorType["RATE_LIMIT"] = "WIZARD_RATE_LIMIT";
+    /** Generic API error */
+    AgentErrorType["API_ERROR"] = "WIZARD_API_ERROR";
+    /** Authentication failed — bearer token invalid or expired */
+    AgentErrorType["AUTH_ERROR"] = "WIZARD_AUTH_ERROR";
+})(AgentErrorType || (exports.AgentErrorType = AgentErrorType = {}));
+const BLOCKING_ENV_KEYS = ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN'];
+/**
+ * Check if .claude/settings.json in the project directory contains env
+ * overrides for blocking keys that block the Wizard from accessing the Amplitude LLM Gateway.
+ * Returns the list of matched key names, or an empty array if none found.
+ */
+function checkClaudeSettingsOverrides(workingDirectory) {
+    const candidates = [
+        path_1.default.join(workingDirectory, '.claude', 'settings.json'),
+        path_1.default.join(workingDirectory, '.claude', 'settings'),
+    ];
+    const claudeSettingsSchema = zod_1.z.object({
+        env: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    });
+    for (const filePath of candidates) {
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const result = claudeSettingsSchema.safeParse(JSON.parse(raw));
+            if (result.success) {
+                return BLOCKING_ENV_KEYS.filter((key) => key in result.data.env);
+            }
+        }
+        catch {
+            // File doesn't exist or isn't valid JSON — skip
+        }
+    }
+    return [];
+}
+/**
+ * Copy .claude/settings.json to .wizard-backup (overwriting if it exists),
+ * then remove the original so the SDK doesn't load the blocking overrides.
+ */
+function backupAndFixClaudeSettings(workingDirectory) {
+    for (const name of ['settings.json', 'settings']) {
+        const filePath = path_1.default.join(workingDirectory, '.claude', name);
+        const backupPath = `${filePath}.wizard-backup`;
+        analytics_1.analytics.wizardCapture('backedup-claude-settings');
+        try {
+            fs.copyFileSync(filePath, backupPath);
+            fs.unlinkSync(filePath);
+            (0, wizard_abort_1.registerCleanup)(() => {
+                try {
+                    restoreClaudeSettings(workingDirectory);
+                }
+                catch (error) {
+                    analytics_1.analytics.captureException(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+            return true;
+        }
+        catch {
+            // File doesn't exist — try next candidate
+        }
+    }
+    return false;
+}
+/**
+ * Restore .claude/settings.json from .wizard-backup.
+ * Copies (not moves) so the backup is preserved.
+ */
+function restoreClaudeSettings(workingDirectory) {
+    for (const name of ['settings.json', 'settings']) {
+        const backup = path_1.default.join(workingDirectory, '.claude', `${name}.wizard-backup`);
+        try {
+            fs.copyFileSync(backup, path_1.default.join(workingDirectory, '.claude', name));
+            analytics_1.analytics.wizardCapture('restored-claude-settings');
+            return;
+        }
+        catch (error) {
+            analytics_1.analytics.captureException(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+}
+/**
+ * Create a stop hook callback that drains the additional feature queue,
+ * then collects a remark, then allows stop.
+ *
+ * Three-phase logic using closure state:
+ *   Phase 1 — drain queue: block with each feature prompt in order
+ *   Phase 2 — collect remark (once): block with remark prompt
+ *   Phase 3 — allow stop: return {}
+ *
+ * If `isAuthError()` returns true, all phases are skipped and stop is
+ * allowed immediately — the agent cannot respond when auth has failed.
+ */
+function createStopHook(featureQueue, isAuthError = () => false) {
+    let featureIndex = 0;
+    let remarkRequested = false;
+    return (input) => {
+        const stop_hook_active = input.stop_hook_active;
+        (0, debug_1.logToFile)('Stop hook triggered', {
+            stop_hook_active,
+            featureIndex,
+            remarkRequested,
+            queueLength: featureQueue.length,
+        });
+        // If an auth error occurred, allow stop immediately — the agent cannot
+        // make further API calls to process feature prompts or reflection requests.
+        if (isAuthError()) {
+            (0, debug_1.logToFile)('Stop hook: allowing stop (auth error detected)');
+            return Promise.resolve({});
+        }
+        // Phase 1: drain feature queue
+        if (featureIndex < featureQueue.length) {
+            const feature = featureQueue[featureIndex++];
+            const prompt = wizard_session_1.ADDITIONAL_FEATURE_PROMPTS[feature];
+            (0, debug_1.logToFile)(`Stop hook: injecting feature prompt for ${feature}`);
+            return Promise.resolve({ decision: 'block', reason: prompt });
+        }
+        // Phase 2: collect remark (once)
+        if (!remarkRequested) {
+            remarkRequested = true;
+            (0, debug_1.logToFile)('Stop hook: requesting reflection');
+            return Promise.resolve({
+                decision: 'block',
+                reason: `Before concluding, provide a brief remark about what information or guidance would have been useful to have in the integration prompt or documentation for this run. Specifically cite anything that would have prevented tool failures, erroneous edits, or other wasted turns. Format your response exactly as: ${exports.AgentSignals.WIZARD_REMARK} Your remark here`,
+            });
+        }
+        // Phase 3: allow stop
+        (0, debug_1.logToFile)('Stop hook: allowing stop');
+        return Promise.resolve({});
+    };
+}
+const GATEWAY_LIVENESS_TIMEOUT_MS = 8_000;
+/**
+ * Ping the gateway URL with a short timeout.
+ * Any HTTP response (even 4xx/5xx) means the gateway is reachable.
+ * A timeout or connection error means it's down.
+ */
+async function checkGatewayLiveness(gatewayUrl) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), GATEWAY_LIVENESS_TIMEOUT_MS);
+    try {
+        await fetch(gatewayUrl, { method: 'HEAD', signal: controller.signal });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(id);
+    }
+}
+/**
+ * Select wizard metadata from WIZARD_VARIANTS using the variant feature flag.
+ * If the flag is missing or the value is not in config, returns the "base" variant (VARIANT: "base").
+ */
+function buildWizardMetadata(flags = {}) {
+    const variantKey = flags[constants_1.WIZARD_VARIANT_FLAG_KEY];
+    const variant = (variantKey && constants_1.WIZARD_VARIANTS[variantKey]) ?? constants_1.WIZARD_VARIANTS['base'];
+    return { ...variant };
+}
+/**
+ * Build env for the SDK subprocess: process.env plus ANTHROPIC_CUSTOM_HEADERS from wizard metadata/flags.
+ */
+function buildAgentEnv(wizardMetadata, wizardFlags) {
+    const headers = (0, custom_headers_1.createCustomHeaders)();
+    for (const [key, value] of Object.entries(wizardMetadata)) {
+        headers.add(key.startsWith(constants_1.AMPLITUDE_PROPERTY_HEADER_PREFIX)
+            ? key
+            : `${constants_1.AMPLITUDE_PROPERTY_HEADER_PREFIX}${key}`, value);
+    }
+    for (const [flagKey, variant] of Object.entries(wizardFlags)) {
+        if (!flagKey.toLowerCase().startsWith('wizard'))
+            continue;
+        headers.addFlag(flagKey, variant);
+    }
+    const encoded = headers.encode();
+    (0, debug_1.logToFile)('ANTHROPIC_CUSTOM_HEADERS', encoded);
+    return encoded;
+}
+/**
+ * Executables that can be used to run build commands.
+ * Includes package managers, language build tools, and static site generators.
+ */
+const PACKAGE_MANAGERS = [
+    // JavaScript / Node
+    'npm',
+    'pnpm',
+    'yarn',
+    'bun',
+    'npx',
+    'deno',
+    // Python
+    'pip',
+    'pip3',
+    'poetry',
+    'pipenv',
+    'uv',
+    // Ruby
+    'gem',
+    'bundle',
+    'bundler',
+    'rake',
+    // PHP
+    'composer',
+    // Go
+    'go',
+    // Rust
+    'cargo',
+    // Java / Kotlin / Android
+    'gradle',
+    './gradlew',
+    'mvn',
+    './mvnw',
+    // .NET
+    'dotnet',
+    // Swift
+    'swift',
+    // Haskell
+    'stack',
+    'cabal',
+    // Elixir
+    'mix',
+    // Flutter / Dart
+    'flutter',
+    'dart',
+    // Make
+    'make',
+    // Static site generators
+    'zola',
+    'hugo',
+    'jekyll',
+    'eleventy',
+    'hexo',
+    'pelican',
+    'mkdocs',
+];
+/**
+ * Commands that are safe to run with no sub-command (the executable alone builds the project).
+ */
+const STANDALONE_BUILD_COMMANDS = ['hugo', 'make', 'eleventy'];
+/**
+ * Safe sub-commands/scripts that can be run with any executable in PACKAGE_MANAGERS.
+ * Uses startsWith matching, so 'build' matches 'build', 'build:prod', etc.
+ * Note: Linting tools are in LINTING_TOOLS and checked separately.
+ */
+const SAFE_SCRIPTS = [
+    // Package / dependency installation
+    'install',
+    'add',
+    'ci',
+    'get',
+    'restore',
+    'fetch',
+    'deps',
+    'update',
+    // Build / compile / generate
+    'build',
+    'compile',
+    'assemble',
+    'package',
+    'generate',
+    'bundle',
+    // Type checking (various naming conventions)
+    'tsc',
+    'typecheck',
+    'type-check',
+    'check-types',
+    'types',
+    // Check / verify
+    'check',
+    // Test
+    'test',
+    // Serve (for build verification with static site tools)
+    'serve',
+    // Module / dependency management sub-commands
+    'mod',
+    'pub',
+    // Make targets
+    'all',
+    // Linting/formatting script names (actual tools are in LINTING_TOOLS)
+    'lint',
+    'format',
+];
+/**
+ * Dangerous shell operators that could allow command injection.
+ * Note: We handle `2>&1` and `| tail/head` separately as safe patterns.
+ * Note: `&&` is allowed for specific safe patterns like skill installation.
+ */
+const DANGEROUS_OPERATORS = /[;`$()]/;
+/**
+ * Check if command is a Amplitude skill installation from MCP.
+ * We control the MCP server, so we only need to verify:
+ * 1. It installs to .claude/skills/
+ * 2. It downloads from our GitHub releases or localhost (dev)
+ */
+function isSkillInstallCommand(command) {
+    if (!command.startsWith('mkdir -p .claude/skills/'))
+        return false;
+    const urlMatch = command.match(/curl -sL ['"]([^'"]+)['"]/);
+    if (!urlMatch)
+        return false;
+    const url = urlMatch[1];
+    return (url.startsWith('https://github.com/Amplitude/context-mill/releases/') ||
+        /^http:\/\/localhost:\d+\//.test(url));
+}
+/**
+ * Check if command is an allowed package manager command.
+ * Matches: <pkg-manager> [run|exec] <safe-script> [args...]
+ */
+function matchesAllowedPrefix(command) {
+    const parts = command.split(/\s+/);
+    if (parts.length === 0 || !PACKAGE_MANAGERS.includes(parts[0])) {
+        return false;
+    }
+    // Allow tools that are safe to invoke with no sub-command (e.g. `hugo`, `make`)
+    if (parts.length === 1 && STANDALONE_BUILD_COMMANDS.includes(parts[0])) {
+        return true;
+    }
+    // Skip 'run' or 'exec' if present
+    let scriptIndex = 1;
+    if (parts[scriptIndex] === 'run' || parts[scriptIndex] === 'exec') {
+        scriptIndex++;
+    }
+    // Get the script/command portion (may include args)
+    const scriptPart = parts.slice(scriptIndex).join(' ');
+    // Check if script starts with any safe script name or linting tool
+    return (SAFE_SCRIPTS.some((safe) => scriptPart.startsWith(safe)) ||
+        safe_tools_1.LINTING_TOOLS.some((tool) => scriptPart.startsWith(tool)));
+}
+/**
+ * Permission hook that allows only safe commands.
+ * - Package manager install commands
+ * - Build/typecheck/lint commands for verification
+ * - Piping to tail/head for output limiting is allowed
+ * - Stderr redirection (2>&1) is allowed
+ * - Amplitude skill installation commands from MCP
+ */
+function wizardCanUseTool(toolName, input) {
+    // Block direct reads/writes of .env files — use wizard-tools MCP instead
+    if (toolName === 'Read' || toolName === 'Write' || toolName === 'Edit') {
+        const filePath = typeof input.file_path === 'string' ? input.file_path : '';
+        const basename = path_1.default.basename(filePath);
+        if (basename.startsWith('.env')) {
+            (0, debug_1.logToFile)(`Denying ${toolName} on env file: ${filePath}`);
+            return {
+                behavior: 'deny',
+                message: `Direct ${toolName} of ${basename} is not allowed. Use the wizard-tools MCP server (check_env_keys / set_env_values) to read or modify environment variables.`,
+            };
+        }
+        return { behavior: 'allow', updatedInput: input };
+    }
+    // Block Grep when it directly targets a .env file.
+    // Note: ripgrep skips dotfiles (like .env*) by default during directory traversal,
+    // so broad searches like `Grep { path: "." }` are already safe.
+    if (toolName === 'Grep') {
+        const grepPath = typeof input.path === 'string' ? input.path : '';
+        if (grepPath && path_1.default.basename(grepPath).startsWith('.env')) {
+            (0, debug_1.logToFile)(`Denying Grep on env file: ${grepPath}`);
+            return {
+                behavior: 'deny',
+                message: `Grep on ${path_1.default.basename(grepPath)} is not allowed. Use the wizard-tools MCP server (check_env_keys) to check environment variables.`,
+            };
+        }
+        return { behavior: 'allow', updatedInput: input };
+    }
+    // Allow all other non-Bash tools
+    if (toolName !== 'Bash') {
+        return { behavior: 'allow', updatedInput: input };
+    }
+    const command = (typeof input.command === 'string' ? input.command : '').trim();
+    // Check for Amplitude skill installation command (before dangerous operator check)
+    // These commands use && chaining but are generated by MCP with a strict format
+    if (isSkillInstallCommand(command)) {
+        (0, debug_1.logToFile)(`Allowing skill installation command: ${command}`);
+        (0, debug_1.debug)(`Allowing skill installation command: ${command}`);
+        return { behavior: 'allow', updatedInput: input };
+    }
+    // Block definitely dangerous operators: ; ` $ ( )
+    if (DANGEROUS_OPERATORS.test(command)) {
+        (0, debug_1.logToFile)(`Denying bash command with dangerous operators: ${command}`);
+        (0, debug_1.debug)(`Denying bash command with dangerous operators: ${command}`);
+        analytics_1.analytics.wizardCapture('bash denied', {
+            reason: 'dangerous operators',
+            command,
+        });
+        return {
+            behavior: 'deny',
+            message: `Bash command not allowed. Shell operators like ; \` $ ( ) are not permitted.`,
+        };
+    }
+    // Normalize: remove safe stderr redirection (2>&1, 2>&2, etc.)
+    const normalized = command.replace(/\s*\d*>&\d+\s*/g, ' ').trim();
+    // Check for pipe to tail/head (safe output limiting)
+    const pipeMatch = normalized.match(/^(.+?)\s*\|\s*(tail|head)(\s+\S+)*\s*$/);
+    if (pipeMatch) {
+        const baseCommand = pipeMatch[1].trim();
+        // Block if base command has pipes or & (multiple chaining)
+        if (/[|&]/.test(baseCommand)) {
+            (0, debug_1.logToFile)(`Denying bash command with multiple pipes: ${command}`);
+            (0, debug_1.debug)(`Denying bash command with multiple pipes: ${command}`);
+            analytics_1.analytics.wizardCapture('bash denied', {
+                reason: 'multiple pipes',
+                command,
+            });
+            return {
+                behavior: 'deny',
+                message: `Bash command not allowed. Only single pipe to tail/head is permitted.`,
+            };
+        }
+        if (matchesAllowedPrefix(baseCommand)) {
+            (0, debug_1.logToFile)(`Allowing bash command with output limiter: ${command}`);
+            (0, debug_1.debug)(`Allowing bash command with output limiter: ${command}`);
+            return { behavior: 'allow', updatedInput: input };
+        }
+    }
+    // Block remaining pipes and & (not covered by tail/head case above)
+    if (/[|&]/.test(normalized)) {
+        (0, debug_1.logToFile)(`Denying bash command with pipe/&: ${command}`);
+        (0, debug_1.debug)(`Denying bash command with pipe/&: ${command}`);
+        analytics_1.analytics.wizardCapture('bash denied', {
+            reason: 'disallowed pipe',
+            command,
+        });
+        return {
+            behavior: 'deny',
+            message: `Bash command not allowed. Pipes are only permitted with tail/head for output limiting.`,
+        };
+    }
+    // Check if command starts with any allowed prefix (package manager commands)
+    if (matchesAllowedPrefix(normalized)) {
+        (0, debug_1.logToFile)(`Allowing bash command: ${command}`);
+        (0, debug_1.debug)(`Allowing bash command: ${command}`);
+        return { behavior: 'allow', updatedInput: input };
+    }
+    (0, debug_1.logToFile)(`Denying bash command: ${command}`);
+    (0, debug_1.debug)(`Denying bash command: ${command}`);
+    analytics_1.analytics.wizardCapture('bash denied', {
+        reason: 'not in allowlist',
+        command,
+    });
+    return {
+        behavior: 'deny',
+        message: `Bash command not allowed. Only install, build, typecheck, lint, and formatting commands are permitted.`,
+    };
+}
+/**
+ * Initialize agent configuration for the LLM gateway
+ */
+async function initializeAgent(config, options) {
+    // Initialize log file for this run
+    (0, debug_1.initLogFile)();
+    (0, debug_1.logToFile)('Agent initialization starting');
+    (0, debug_1.logToFile)('Install directory:', options.installDir);
+    (0, ui_1.getUI)().log.step('Initializing Claude agent...');
+    try {
+        const useDirectApiKey = !!process.env.ANTHROPIC_API_KEY;
+        const useLocalClaude = !config.amplitudeBearerToken && !useDirectApiKey;
+        if (useDirectApiKey) {
+            (0, debug_1.logToFile)('ANTHROPIC_API_KEY found — bypassing Amplitude gateway');
+        }
+        else if (useLocalClaude) {
+            (0, debug_1.logToFile)('No Amplitude API key — using local claude CLI');
+        }
+        else {
+            // Configure LLM gateway environment variables (inherited by SDK subprocess)
+            const gatewayUrl = (0, urls_1.getLlmGatewayUrlFromHost)(config.amplitudeApiHost);
+            // Fail fast if the gateway isn't responding rather than hanging indefinitely
+            const alive = await checkGatewayLiveness(gatewayUrl);
+            if (!alive) {
+                throw new Error(`Could not reach the Amplitude LLM gateway (${gatewayUrl}). ` +
+                    `Check your network connection, or set ANTHROPIC_API_KEY to use the Anthropic API directly.`);
+            }
+            process.env.ANTHROPIC_BASE_URL = gatewayUrl;
+            process.env.ANTHROPIC_AUTH_TOKEN = config.amplitudeBearerToken;
+            // Use CLAUDE_CODE_OAUTH_TOKEN to override any stored /login credentials
+            process.env.CLAUDE_CODE_OAUTH_TOKEN = config.amplitudeBearerToken;
+            // Disable experimental betas (like input_examples) that the LLM gateway doesn't support
+            process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = 'true';
+            (0, debug_1.logToFile)('Configured LLM gateway:', gatewayUrl);
+        }
+        // Configure MCP servers
+        const mcpServers = {};
+        if (!config.skipAmplitudeMcp) {
+            mcpServers['amplitude-wizard'] = {
+                type: 'http',
+                url: config.amplitudeMcpUrl,
+                headers: {
+                    Authorization: `Bearer ${config.amplitudeBearerToken}`,
+                    'User-Agent': constants_1.WIZARD_USER_AGENT,
+                },
+            };
+        }
+        for (const [name, { url }] of Object.entries(config.additionalMcpServers ?? {})) {
+            mcpServers[name] = { type: 'http', url };
+        }
+        // Add in-process wizard tools (env files, package manager detection)
+        const wizardToolsServer = await (0, wizard_tools_1.createWizardToolsServer)({
+            workingDirectory: config.workingDirectory,
+            detectPackageManager: config.detectPackageManager,
+            skillsBaseUrl: config.skillsBaseUrl,
+        });
+        mcpServers['wizard-tools'] = wizardToolsServer;
+        const agentRunConfig = {
+            workingDirectory: config.workingDirectory,
+            mcpServers,
+            // Gateway expects 'anthropic/claude-sonnet-4-6'; direct Anthropic API expects 'claude-sonnet-4-6'
+            model: useDirectApiKey
+                ? 'claude-sonnet-4-6'
+                : 'anthropic/claude-sonnet-4-6',
+            wizardFlags: config.wizardFlags,
+            wizardMetadata: config.wizardMetadata,
+            useLocalClaude,
+            useDirectApiKey,
+        };
+        (0, debug_1.logToFile)('Agent config:', {
+            workingDirectory: agentRunConfig.workingDirectory,
+            amplitudeMcpUrl: config.amplitudeMcpUrl,
+            useLocalClaude,
+            useDirectApiKey,
+            bearerTokenPresent: !!config.amplitudeBearerToken,
+        });
+        if (options.debug) {
+            (0, debug_1.debug)('Agent config:', {
+                workingDirectory: agentRunConfig.workingDirectory,
+                amplitudeMcpUrl: config.amplitudeMcpUrl,
+                useLocalClaude,
+                useDirectApiKey,
+                bearerTokenPresent: !!config.amplitudeBearerToken,
+            });
+        }
+        (0, ui_1.getUI)().log.step(`Verbose logs: ${(0, debug_1.getLogFilePath)()}`);
+        (0, ui_1.getUI)().log.success("Agent initialized. Let's get cooking!");
+        return agentRunConfig;
+    }
+    catch (error) {
+        (0, debug_1.logToFile)('Agent initialization error:', error);
+        (0, debug_1.debug)('Agent initialization error:', error);
+        throw error;
+    }
+}
+let _agentPromise = null;
+function buildDefaultAgentConfig() {
+    const storedToken = (0, ampli_settings_1.getStoredToken)()?.accessToken ?? '';
+    const host = (0, urls_1.getHostFromRegion)('us');
+    const mcpUrl = process.env.MCP_URL ?? 'https://mcp.amplitude.com/mcp';
+    return {
+        workingDirectory: process.cwd(),
+        amplitudeMcpUrl: mcpUrl,
+        amplitudeApiKey: storedToken,
+        amplitudeBearerToken: storedToken,
+        amplitudeApiHost: host,
+        skipAmplitudeMcp: !storedToken,
+        detectPackageManager: () => Promise.resolve({ detected: [], primary: null, recommendation: '' }),
+    };
+}
+const DEFAULT_WIZARD_OPTIONS = {
+    debug: false,
+    forceInstall: false,
+    installDir: process.cwd(),
+    default: false,
+    signup: false,
+    localMcp: false,
+    ci: false,
+    menu: false,
+    benchmark: false,
+};
+/**
+ * Return the already-initialized agent config, or call initializeAgent to create it.
+ * Concurrent calls during initialization share the same Promise.
+ * On error the cached Promise is cleared so the next call retries.
+ *
+ * Omitting config/options reads the bearer token from ~/.ampli.json and uses production
+ * defaults (MCP disabled if no token found, cwd as working directory).
+ */
+async function getAgent(config = buildDefaultAgentConfig(), options = DEFAULT_WIZARD_OPTIONS) {
+    if (!_agentPromise) {
+        _agentPromise = initializeAgent(config, options).catch((err) => {
+            _agentPromise = null;
+            throw err;
+        });
+    }
+    return _agentPromise;
+}
+/**
+ * Run the agent by spawning the user's local `claude` CLI with --continue.
+ * Used when no Amplitude API key is present (local development).
+ * Streams stdout line-by-line and forwards text to the spinner.
+ */
+async function runAgentLocally(prompt, workingDirectory, spinner, successMessage, errorMessage) {
+    const { spawn } = await import('child_process');
+    (0, debug_1.logToFile)('Running agent via local claude CLI');
+    return new Promise((resolve, reject) => {
+        const proc = spawn('claude', ['--continue', prompt], {
+            cwd: workingDirectory,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        proc.stdout.setEncoding('utf8');
+        proc.stderr.setEncoding('utf8');
+        proc.stdout.on('data', (chunk) => {
+            const lines = chunk.split('\n').filter((l) => l.trim());
+            for (const line of lines) {
+                (0, debug_1.logToFile)('claude stdout:', line);
+                spinner.message(line.slice(0, 80));
+                (0, ui_1.getUI)().pushStatus(line.slice(0, 80));
+            }
+        });
+        proc.stderr.on('data', (chunk) => {
+            (0, debug_1.logToFile)('claude stderr:', chunk);
+        });
+        proc.on('close', (code) => {
+            if (code === 0) {
+                spinner.stop(successMessage);
+                resolve({});
+            }
+            else {
+                spinner.stop(errorMessage);
+                reject(new Error(`claude exited with code ${code ?? 'unknown'}`));
+            }
+        });
+        proc.on('error', (err) => {
+            spinner.stop(errorMessage);
+            reject(err);
+        });
+    });
+}
+/**
+ * Execute an agent with the provided prompt and options
+ * Handles the full lifecycle: spinner, execution, error handling
+ *
+ * @returns An object containing any error detected in the agent's output
+ */
+async function runAgent(agentConfig, prompt, options, spinner, config, middleware) {
+    const { spinnerMessage = 'Customizing your Amplitude setup...', successMessage = 'Amplitude integration complete', errorMessage = 'Integration failed', } = config ?? {};
+    spinner.start(spinnerMessage);
+    if (agentConfig.useLocalClaude) {
+        return runAgentLocally(prompt, agentConfig.workingDirectory, spinner, successMessage, errorMessage);
+    }
+    const { query } = await getSDKModule();
+    const cliPath = getClaudeCodeExecutablePath();
+    (0, debug_1.logToFile)('Starting agent run');
+    (0, debug_1.logToFile)('Claude Code executable:', cliPath);
+    (0, debug_1.logToFile)('Prompt:', prompt);
+    const startTime = Date.now();
+    const collectedText = [];
+    const recentStatuses = []; // rolling last-3 STATUS messages for heartbeat
+    // Track if we received a successful result (before any cleanup errors)
+    let receivedSuccessResult = false;
+    let lastResultMessage = null;
+    // Workaround for SDK bug: stdin closes before canUseTool responses can be sent.
+    // The fix is to use an async generator for the prompt that stays open until
+    // the result is received, keeping the stdin stream alive for permission responses.
+    // signalDone is reassigned each retry attempt — the outer catch always has the latest.
+    // See: https://github.com/anthropics/claude-code/issues/4775
+    // See: https://github.com/anthropics/claude-agent-sdk-typescript/issues/41
+    let signalDone = Function.prototype;
+    // Helper to handle successful completion (used in normal path and race condition recovery)
+    const completeWithSuccess = (suppressedError) => {
+        const durationMs = Date.now() - startTime;
+        const durationSeconds = Math.round(durationMs / 1000);
+        if (suppressedError) {
+            (0, debug_1.logToFile)(`Ignoring post-completion error, agent completed successfully in ${durationSeconds}s`);
+            (0, debug_1.logToFile)('Suppressed error:', suppressedError.message);
+        }
+        else {
+            (0, debug_1.logToFile)(`Agent run completed in ${durationSeconds}s`);
+        }
+        // Extract and capture the agent's reflection on the run
+        const outputText = collectedText.join('\n');
+        const remarkRegex = new RegExp(`${exports.AgentSignals.WIZARD_REMARK.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*(.+?)(?:\\n|$)`, 's');
+        const remarkMatch = outputText.match(remarkRegex);
+        if (remarkMatch && remarkMatch[1]) {
+            const remark = remarkMatch[1].trim();
+            if (remark) {
+                analytics_1.analytics.capture(constants_1.WIZARD_REMARK_EVENT_NAME, { remark });
+            }
+        }
+        analytics_1.analytics.wizardCapture('agent completed', {
+            duration_ms: durationMs,
+            duration_seconds: durationSeconds,
+        });
+        try {
+            if (lastResultMessage) {
+                middleware?.finalize(lastResultMessage, durationMs);
+            }
+        }
+        catch (e) {
+            (0, debug_1.logToFile)(`${exports.AgentSignals.BENCHMARK} Middleware finalize error:`, e);
+        }
+        spinner.stop(successMessage);
+        return {};
+    };
+    // Heartbeat interval — every 10s print the last 3 STATUS messages so the
+    // user can see progress in the CLI without waiting for the next update.
+    const heartbeatInterval = setInterval(() => {
+        if (recentStatuses.length > 0) {
+            (0, ui_1.getUI)().heartbeat([...recentStatuses]);
+        }
+    }, 10_000);
+    // Event plan file watcher — cleaned up in finally block
+    let eventPlanWatcher;
+    let eventPlanInterval;
+    try {
+        // Tools needed for the wizard:
+        // - File operations: Read, Write, Edit
+        // - Search: Glob, Grep
+        // - Commands: Bash (with restrictions via canUseTool)
+        // - MCP discovery: ListMcpResourcesTool (to find available skills)
+        // - Skills: Skill (to load installed Amplitude skills)
+        // MCP tools (Amplitude) come from mcpServers, not allowedTools
+        const allowedTools = [
+            'Read',
+            'Write',
+            'Edit',
+            'Glob',
+            'Grep',
+            'Bash',
+            'ListMcpResourcesTool',
+            'Skill',
+            ...wizard_tools_1.WIZARD_TOOL_NAMES,
+        ];
+        // Watch for .amplitude-events.json and feed into the store (set up once, before retries)
+        const eventPlanPath = path_1.default.join(agentConfig.workingDirectory, '.amplitude-events.json');
+        const eventPlanSchema = zod_1.z.array(zod_1.z.looseObject({
+            name: zod_1.z.string().optional(),
+            event: zod_1.z.string().optional(),
+            eventName: zod_1.z.string().optional(),
+            description: zod_1.z.string().optional(),
+            eventDescriptionAndReasoning: zod_1.z.string().optional(),
+        }));
+        const readEventPlan = () => {
+            try {
+                const content = fs.readFileSync(eventPlanPath, 'utf-8');
+                const result = eventPlanSchema.safeParse(JSON.parse(content));
+                if (result.success) {
+                    (0, ui_1.getUI)().setEventPlan(result.data.map((e) => ({
+                        name: e.name ?? e.event ?? e.eventName ?? '',
+                        description: e.description ?? e.eventDescriptionAndReasoning ?? '',
+                    })));
+                }
+            }
+            catch {
+                // File doesn't exist or isn't valid JSON yet
+            }
+        };
+        try {
+            eventPlanWatcher = fs.watch(eventPlanPath, () => readEventPlan());
+            readEventPlan();
+        }
+        catch {
+            // File doesn't exist yet — poll until it appears
+            eventPlanInterval = setInterval(() => {
+                try {
+                    fs.accessSync(eventPlanPath);
+                    readEventPlan();
+                    clearInterval(eventPlanInterval);
+                    eventPlanInterval = undefined;
+                    eventPlanWatcher = fs.watch(eventPlanPath, () => readEventPlan());
+                }
+                catch {
+                    // Still waiting
+                }
+            }, 1000);
+        }
+        // Retry loop: if the agent stalls (no message for STALL_TIMEOUT_MS), abort and
+        // re-run with a fresh AbortController and prompt stream. Up to MAX_RETRIES retries.
+        const MAX_RETRIES = 2;
+        const STALL_TIMEOUT_MS = 20_000;
+        // Tracks whether an authentication failure was detected in the current attempt.
+        // Passed to createStopHook so it can skip reflection when auth is broken.
+        let authErrorDetected = false;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            if (attempt > 0) {
+                (0, debug_1.logToFile)(`Agent stall retry: attempt ${attempt + 1} of ${MAX_RETRIES + 1}`);
+                analytics_1.analytics.wizardCapture('agent stall retry', { attempt });
+                // Clear per-attempt output so stale error markers don't affect the fresh run
+                collectedText.length = 0;
+                recentStatuses.length = 0;
+                authErrorDetected = false;
+            }
+            // Fresh prompt stream per attempt — stdin stays open until result received
+            const resultReceived = new Promise((resolve) => {
+                signalDone = resolve;
+            });
+            const createPromptStream = async function* () {
+                yield {
+                    type: 'user',
+                    session_id: '',
+                    message: { role: 'user', content: prompt },
+                    parent_tool_use_id: null,
+                };
+                await resultReceived;
+            };
+            // AbortController lets us cancel a stalled query so we can retry
+            const controller = new AbortController();
+            let staleTimer;
+            const resetStaleTimer = () => {
+                if (staleTimer)
+                    clearTimeout(staleTimer);
+                staleTimer = setTimeout(() => {
+                    (0, debug_1.logToFile)(`Agent stalled — no message for ${STALL_TIMEOUT_MS / 1000}s (attempt ${attempt + 1})`);
+                    analytics_1.analytics.wizardCapture('agent stall detected', {
+                        attempt: attempt + 1,
+                        stall_timeout_ms: STALL_TIMEOUT_MS,
+                    });
+                    controller.abort('stall');
+                }, STALL_TIMEOUT_MS);
+            };
+            try {
+                const response = query({
+                    prompt: createPromptStream(),
+                    options: {
+                        model: agentConfig.model,
+                        cwd: agentConfig.workingDirectory,
+                        permissionMode: 'acceptEdits',
+                        mcpServers: agentConfig.mcpServers,
+                        // Load skills from project's .claude/skills/ directory
+                        settingSources: ['project'],
+                        // Explicitly enable required tools including Skill
+                        allowedTools,
+                        systemPrompt: {
+                            type: 'preset',
+                            preset: 'claude_code',
+                            // Append wizard-wide commandments (from YAML) rather than replacing
+                            // the preset so we keep default Claude Code behaviors.
+                            append: (0, commandments_1.getWizardCommandments)(),
+                        },
+                        env: {
+                            ...process.env,
+                            // When using the Amplitude gateway, block ANTHROPIC_API_KEY so it doesn't
+                            // override the gateway's OAuth token. When using a direct API key, pass it through.
+                            ...(agentConfig.useDirectApiKey
+                                ? {}
+                                : { ANTHROPIC_API_KEY: undefined }),
+                            ANTHROPIC_CUSTOM_HEADERS: buildAgentEnv(agentConfig.wizardMetadata ?? {}, agentConfig.wizardFlags ?? {}),
+                        },
+                        canUseTool: (toolName, input) => {
+                            (0, debug_1.logToFile)('canUseTool called:', { toolName, input });
+                            const result = wizardCanUseTool(toolName, input);
+                            (0, debug_1.logToFile)('canUseTool result:', result);
+                            return Promise.resolve(result);
+                        },
+                        tools: { type: 'preset', preset: 'claude_code' },
+                        // Capture stderr from CLI subprocess for debugging
+                        stderr: (data) => {
+                            (0, debug_1.logToFile)('CLI stderr:', data);
+                            if (options.debug) {
+                                (0, debug_1.debug)('CLI stderr:', data);
+                            }
+                        },
+                        hooks: (0, agent_hooks_1.buildHooksConfig)({
+                            Stop: createStopHook(config?.additionalFeatureQueue ?? [], () => authErrorDetected),
+                        }),
+                        // Allow aborting a stalled query so we can retry cleanly
+                        abortSignal: controller.signal,
+                    },
+                });
+                // Start stale timer — reset on each received message
+                resetStaleTimer();
+                // Process the async generator — validate each message at the boundary
+                for await (const rawMessage of response) {
+                    resetStaleTimer();
+                    const parsed = (0, schemas_1.safeParseSDKMessage)(rawMessage);
+                    if (!parsed.ok) {
+                        (0, debug_1.logToFile)('Skipping malformed SDK message:', parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`));
+                        continue;
+                    }
+                    const message = parsed.message;
+                    // Pass receivedSuccessResult so handleSDKMessage can suppress user-facing error
+                    // output for post-success cleanup errors while still logging them to file
+                    handleSDKMessage(message, options, spinner, collectedText, receivedSuccessResult, recentStatuses);
+                    try {
+                        middleware?.onMessage(message);
+                    }
+                    catch (e) {
+                        (0, debug_1.logToFile)(`${exports.AgentSignals.BENCHMARK} Middleware onMessage error:`, e);
+                    }
+                    // Detect authentication failures so the stop hook can skip reflection
+                    if (message.type === 'result' &&
+                        message.is_error &&
+                        JSON.stringify(message).includes('authentication_failed')) {
+                        authErrorDetected = true;
+                        (0, debug_1.logToFile)('Auth error detected: authentication_failed in result');
+                    }
+                    if (message.type === 'system' && message.subtype === 'init') {
+                        for (const server of message.mcp_servers ?? []) {
+                            if (server.name === 'amplitude-wizard' &&
+                                server.status === 'needs-auth') {
+                                authErrorDetected = true;
+                                (0, debug_1.logToFile)('Auth error detected: amplitude-wizard MCP needs-auth');
+                            }
+                        }
+                    }
+                    // Signal completion when result received
+                    if (message.type === 'result') {
+                        // Track successful results before any potential cleanup errors
+                        // The SDK may emit a second error result during cleanup due to a race condition
+                        if (message.subtype === 'success' && !message.is_error) {
+                            receivedSuccessResult = true;
+                            lastResultMessage = message;
+                        }
+                        signalDone();
+                    }
+                }
+                // Clean completion — exit the retry loop
+                clearTimeout(staleTimer);
+                break;
+            }
+            catch (innerError) {
+                clearTimeout(staleTimer);
+                signalDone(); // unblock the prompt stream for this attempt
+                // Stall-aborted with retries remaining — try again
+                if (controller.signal.aborted && attempt < MAX_RETRIES) {
+                    (0, debug_1.logToFile)(`Retrying after stall (next attempt: ${attempt + 2} of ${MAX_RETRIES + 1})`);
+                    continue;
+                }
+                // Already received a successful result — this is an SDK cleanup race condition
+                if (receivedSuccessResult) {
+                    return completeWithSuccess(innerError);
+                }
+                // Re-throw to the outer catch for API error handling / spinner cleanup
+                throw innerError;
+            }
+        }
+        const outputText = collectedText.join('\n');
+        // Auth error takes priority — the agent cannot recover without re-authentication
+        if (authErrorDetected) {
+            (0, debug_1.logToFile)('Agent error: AUTH_ERROR');
+            spinner.stop('Authentication failed');
+            return { error: AgentErrorType.AUTH_ERROR };
+        }
+        // Check for error markers in the agent's output
+        if (outputText.includes(exports.AgentSignals.ERROR_MCP_MISSING)) {
+            (0, debug_1.logToFile)('Agent error: MCP_MISSING');
+            spinner.stop('Agent could not access Amplitude MCP');
+            return { error: AgentErrorType.MCP_MISSING };
+        }
+        if (outputText.includes(exports.AgentSignals.ERROR_RESOURCE_MISSING)) {
+            (0, debug_1.logToFile)('Agent error: RESOURCE_MISSING');
+            spinner.stop('Agent could not access setup resource');
+            return { error: AgentErrorType.RESOURCE_MISSING };
+        }
+        // Check for API errors (rate limits, etc.)
+        // Extract just the API error line(s), not the entire output
+        const apiErrorMatch = outputText.match(/API Error: [^\n]+/g);
+        const apiErrorMessage = apiErrorMatch
+            ? apiErrorMatch.join('\n')
+            : 'Unknown API error';
+        if (outputText.includes('API Error: 429')) {
+            (0, debug_1.logToFile)('Agent error: RATE_LIMIT');
+            spinner.stop('Rate limit exceeded');
+            return { error: AgentErrorType.RATE_LIMIT, message: apiErrorMessage };
+        }
+        if (outputText.includes('API Error:')) {
+            (0, debug_1.logToFile)('Agent error: API_ERROR');
+            spinner.stop('API error occurred');
+            return { error: AgentErrorType.API_ERROR, message: apiErrorMessage };
+        }
+        return completeWithSuccess();
+    }
+    catch (error) {
+        // Signal done to unblock the async generator
+        signalDone();
+        // If we already received a successful result, the error is from SDK cleanup
+        // This happens due to a race condition: the SDK tries to send a cleanup command
+        // after the prompt stream closes, but streaming mode is still active.
+        // See: https://github.com/anthropics/claude-agent-sdk-typescript/issues/41
+        if (receivedSuccessResult) {
+            return completeWithSuccess(error);
+        }
+        // Check if we collected an API error before the exception was thrown
+        const outputText = collectedText.join('\n');
+        // Extract just the API error line(s), not the entire output
+        const apiErrorMatch = outputText.match(/API Error: [^\n]+/g);
+        const apiErrorMessage = apiErrorMatch
+            ? apiErrorMatch.join('\n')
+            : 'Unknown API error';
+        if (outputText.includes('API Error: 429')) {
+            (0, debug_1.logToFile)('Agent error (caught): RATE_LIMIT');
+            spinner.stop('Rate limit exceeded');
+            return { error: AgentErrorType.RATE_LIMIT, message: apiErrorMessage };
+        }
+        if (outputText.includes('API Error:')) {
+            (0, debug_1.logToFile)('Agent error (caught): API_ERROR');
+            spinner.stop('API error occurred');
+            return { error: AgentErrorType.API_ERROR, message: apiErrorMessage };
+        }
+        // No API error found, re-throw the original exception
+        spinner.stop(errorMessage);
+        (0, ui_1.getUI)().log.error(`Error: ${error.message}`);
+        (0, debug_1.logToFile)('Agent run failed:', error);
+        (0, debug_1.debug)('Full error:', error);
+        throw error;
+    }
+    finally {
+        clearInterval(heartbeatInterval);
+        eventPlanWatcher?.close();
+        if (eventPlanInterval)
+            clearInterval(eventPlanInterval);
+    }
+}
+/**
+ * Handle SDK messages and provide user feedback
+ *
+ * @param receivedSuccessResult - If true, suppress user-facing error output for cleanup errors
+ *                          while still logging to file. The SDK may emit a second error
+ *                          result after success due to cleanup race conditions.
+ */
+function handleSDKMessage(message, options, spinner, collectedText, receivedSuccessResult = false, recentStatuses) {
+    (0, debug_1.logToFile)(`SDK Message: ${message.type}`, JSON.stringify(message, null, 2));
+    if (options.debug) {
+        (0, debug_1.debug)(`SDK Message type: ${message.type}`);
+    }
+    switch (message.type) {
+        case 'assistant': {
+            // Extract text content from assistant messages
+            const content = message.message?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === 'text' && typeof block.text === 'string') {
+                        collectedText.push(block.text);
+                        // Check for [STATUS] markers
+                        const statusRegex = new RegExp(`^.*${exports.AgentSignals.STATUS.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*(.+?)$`, 'm');
+                        const statusMatch = block.text.match(statusRegex);
+                        if (statusMatch) {
+                            const statusText = statusMatch[1].trim();
+                            spinner.message(statusText);
+                            if (recentStatuses) {
+                                recentStatuses.push(statusText);
+                                if (recentStatuses.length > 3)
+                                    recentStatuses.shift();
+                            }
+                        }
+                    }
+                    // Intercept TodoWrite tool_use blocks for task progression
+                    if (block.type === 'tool_use' &&
+                        block.name === 'TodoWrite' &&
+                        block.input &&
+                        Array.isArray(block.input.todos)) {
+                        (0, ui_1.getUI)().syncTodos(block.input.todos);
+                    }
+                }
+            }
+            break;
+        }
+        case 'result': {
+            // Check is_error flag - can be true even when subtype is 'success'
+            if (message.is_error) {
+                (0, debug_1.logToFile)('Agent result with error:', message.result);
+                if (typeof message.result === 'string') {
+                    collectedText.push(message.result);
+                }
+                // Only show errors to user if we haven't already succeeded.
+                // Post-success errors are SDK cleanup noise (telemetry failures, streaming
+                // mode race conditions). Full message already logged above via JSON dump.
+                if (message.errors && !receivedSuccessResult) {
+                    for (const err of message.errors) {
+                        (0, ui_1.getUI)().log.error(`Error: ${err}`);
+                        (0, debug_1.logToFile)('ERROR:', err);
+                    }
+                }
+            }
+            else if (message.subtype === 'success') {
+                (0, debug_1.logToFile)('Agent completed successfully');
+                if (typeof message.result === 'string') {
+                    collectedText.push(message.result);
+                }
+            }
+            else {
+                (0, debug_1.logToFile)('Agent result with error:', message.result);
+                // Error result - only show to user if we haven't already succeeded.
+                // Full message already logged above via JSON dump.
+                if (message.errors && !receivedSuccessResult) {
+                    for (const err of message.errors) {
+                        (0, ui_1.getUI)().log.error(`Error: ${err}`);
+                        (0, debug_1.logToFile)('ERROR:', err);
+                    }
+                }
+            }
+            break;
+        }
+        case 'system': {
+            if (message.subtype === 'init') {
+                const mcpStatuses = message.mcp_servers ?? [];
+                (0, debug_1.logToFile)('Agent session initialized', {
+                    model: message.model,
+                    tools: message.tools?.length,
+                    mcpServers: mcpStatuses,
+                });
+                for (const server of mcpStatuses) {
+                    (0, debug_1.logToFile)(`MCP "${server.name}": ${server.status}`);
+                    if (server.status !== 'connected') {
+                        (0, ui_1.getUI)().log.warn(`MCP server "${server.name}" is not connected (${server.status})`);
+                    }
+                }
+            }
+            break;
+        }
+        default:
+            // Log other message types for debugging
+            if (options.debug) {
+                (0, debug_1.debug)(`Unhandled message type: ${message.type}`);
+            }
+            break;
+    }
+}