@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/agent/loop.js

@@ -0,0 +1,1535 @@
+/**
+ * Core Agentic Loop
+ *
+ * Implements the autonomous agent loop:
+ * 1. Build context (system prompt + history + tools)
+ * 2. Send to LLM with tools enabled
+ * 3. Stream text response
+ * 4. If tool_use: check permissions → execute → collect results
+ * 5. Append messages → loop back to LLM
+ * 6. Exit when LLM returns end_turn (no more tool calls)
+ *
+ * This is the heart of the Nimbus agent. Every user message enters
+ * {@link runAgentLoop}, which orchestrates a multi-turn conversation with
+ * the LLM, executing tools on its behalf until it signals completion by
+ * returning a response with no further tool calls.
+ *
+ * @module agent/loop
+ */
+import { join } from 'node:path';
+import { toOpenAITool, } from '../tools/schemas/types';
+import { buildSystemPrompt } from './system-prompt';
+import { runCompaction } from './compaction-agent';
+import { SnapshotManager } from '../snapshots/manager';
+import { calculateCost } from '../llm/cost-calculator';
+import { runPreToolHooks, runPostToolHooks, } from '../hooks/engine';
+import { maskSecrets } from '../audit/security-scanner';
+import { classifyTaskComplexity, routeModel } from '../llm/router';
+import { mkdirSync as _cpMkdirSync, writeFileSync as _cpWriteFileSync } from 'node:fs';
+import { homedir as _cpHomedir } from 'node:os';
+// ---------------------------------------------------------------------------
+// C2: Infra state checkpoint helper
+// ---------------------------------------------------------------------------
+/**
+ * Write a checkpoint JSON file to ~/.nimbus/infra-checkpoints/<timestamp>.json
+ * before a mutating terraform or helm operation. Non-blocking — errors are swallowed.
+ */
+function writeInfraCheckpoint(tool, action, input) {
+    try {
+        const checkpointsDir = join(_cpHomedir(), '.nimbus', 'infra-checkpoints');
+        _cpMkdirSync(checkpointsDir, { recursive: true });
+        // Sanitize: remove any field that looks like a secret
+        const sanitized = {};
+        for (const [k, v] of Object.entries(input)) {
+            const lower = k.toLowerCase();
+            if (lower.includes('secret') || lower.includes('password') || lower.includes('token') || lower.includes('key')) {
+                sanitized[k] = '[redacted]';
+            }
+            else {
+                sanitized[k] = v;
+            }
+        }
+        const timestamp = new Date().toISOString();
+        const checkpoint = {
+            timestamp,
+            tool,
+            action,
+            input: sanitized,
+            cwd: process.cwd(),
+            workdir: input.workdir ?? undefined,
+        };
+        const fileName = timestamp.replace(/[:.]/g, '-') + '.json';
+        _cpWriteFileSync(join(checkpointsDir, fileName), JSON.stringify(checkpoint, null, 2), 'utf-8');
+    }
+    catch { /* non-critical */ }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Module-level compiled regex constants for classifyDevOpsError (PERF-1d).
+// Hoisted here so they compile once at module load rather than per-call.
+// ---------------------------------------------------------------------------
+const _RE_CREDENTIAL_EXPIRY_AWS = /ExpiredTokenException|TokenExpiredException|token.*has.*expired/i;
+const _RE_CREDENTIAL_EXPIRY_GCP = /credentials.*expired|Application Default Credentials.*expired|re-authenticate/i;
+const _RE_CREDENTIAL_EXPIRY_AZURE = /AADSTS70008|InteractionRequired|credential.*expired/i;
+const _RE_CMD_NOT_FOUND = /command not found|not found|no such file or directory/i;
+/**
+ * Classify a DevOps tool error and return an actionable hint for the LLM.
+ * Returns null for unrecognized errors so we don't pollute the context.
+ */
+function classifyDevOpsError(toolName, errorOutput, nimbusInstructions) {
+    const e = errorOutput.toLowerCase();
+    // GAP-13: Credential expiry patterns — must come first for fast matching
+    const CREDENTIAL_EXPIRY = [
+        { re: _RE_CREDENTIAL_EXPIRY_AWS, provider: 'aws' },
+        { re: _RE_CREDENTIAL_EXPIRY_GCP, provider: 'gcp' },
+        { re: _RE_CREDENTIAL_EXPIRY_AZURE, provider: 'azure' },
+    ];
+    for (const { re, provider } of CREDENTIAL_EXPIRY) {
+        if (re.test(errorOutput)) {
+            return `Your ${provider.toUpperCase()} credentials have expired.\n\nRun: \`nimbus auth-refresh --provider ${provider}\` to refresh them.`;
+        }
+    }
+    // G3: "command not found" — provide installation hints for DevOps CLIs
+    const INSTALL_HINTS = {
+        terraform: 'brew install terraform  OR  https://developer.hashicorp.com/terraform/install',
+        kubectl: 'brew install kubectl    OR  https://kubernetes.io/docs/tasks/tools/',
+        helm: 'brew install helm       OR  https://helm.sh/docs/intro/install/',
+        docker: 'brew install --cask docker  OR  https://docs.docker.com/get-docker/',
+        aws: 'brew install awscli     OR  pip install awscli',
+        gcloud: 'brew install --cask google-cloud-sdk',
+        az: 'brew install azure-cli',
+    };
+    if (_RE_CMD_NOT_FOUND.test(errorOutput)) {
+        for (const [cmd, hint] of Object.entries(INSTALL_HINTS)) {
+            if (toolName.includes(cmd) || e.includes(`'${cmd}'`) || e.includes(`"${cmd}"`)) {
+                return `\`${cmd}\` is not installed.\n\nInstall: ${hint}`;
+            }
+        }
+    }
+    // Terraform errors
+    if (toolName === 'terraform' || e.includes('terraform')) {
+        if (e.includes('no such file or directory') && e.includes('.terraform')) {
+            return 'HINT: Run `terraform init` first — the .terraform directory is missing.';
+        }
+        if (e.includes('provider') && e.includes('required') && e.includes('terraform')) {
+            return 'HINT: Run `terraform init -upgrade` to download or upgrade required providers.';
+        }
+        if (e.includes('no valid credential') || e.includes('no credentials')) {
+            return 'HINT: AWS/cloud credentials are missing. Check `aws configure` or environment variables.';
+        }
+        if (e.includes('state lock') || e.includes('lock file')) {
+            return 'HINT: Terraform state is locked. If no other operation is running, use `terraform force-unlock <lock-id>`.';
+        }
+        if (e.includes('module not installed') || e.includes('module source')) {
+            return 'HINT: Run `terraform init` to install required modules.';
+        }
+        if (e.includes('quota') || e.includes('limit exceeded') || e.includes('vcpu')) {
+            return 'HINT: Cloud resource quota exceeded. Request a limit increase in the cloud console.';
+        }
+    }
+    // Kubernetes errors
+    if (toolName === 'kubectl' || toolName === 'kubectl_context') {
+        if (e.includes('connection refused') || e.includes('unable to connect')) {
+            return 'HINT: Cannot reach the Kubernetes API server. Check `kubectl config current-context` and ensure the cluster is accessible.';
+        }
+        if (e.includes('unauthorized') || e.includes('forbidden')) {
+            return 'HINT: Insufficient permissions. Check your kubeconfig credentials or RBAC roles.';
+        }
+        if (e.includes('not found') && e.includes('namespace')) {
+            return 'HINT: The namespace does not exist. Create it with `kubectl create namespace <name>` first.';
+        }
+        if (e.includes('image') && (e.includes('not found') || e.includes('pull'))) {
+            return 'HINT: Container image pull failed. Verify the image name, tag, and registry credentials (imagePullSecret).';
+        }
+    }
+    // Helm errors
+    if (toolName === 'helm' || toolName === 'helm_values') {
+        if (e.includes('chart not found') || e.includes('no such chart')) {
+            return 'HINT: Chart not found. Run `helm repo update` and verify the chart name.';
+        }
+        if (e.includes('release not found')) {
+            return 'HINT: Helm release not found. Use `helm list -A` to see all releases across namespaces.';
+        }
+        if (e.includes('unable to build kubernetes objects') || e.includes('manifest')) {
+            return 'HINT: Helm template rendering failed. Run `helm template <release> <chart>` to debug the manifests.';
+        }
+    }
+    // Cloud CLI errors
+    if (toolName === 'cloud_discover' || toolName === 'cloud_action') {
+        if (e.includes('not authorized') || e.includes('access denied') || e.includes('unauthorized')) {
+            return 'HINT: Cloud credentials lack required permissions. Check IAM policies/roles for the operation.';
+        }
+        if (e.includes('region') && e.includes('not found')) {
+            return 'HINT: Invalid region. Check `aws configure get region` or pass --region explicitly.';
+        }
+    }
+    // Docker errors
+    if (toolName === 'docker') {
+        if (e.includes('cannot connect to the docker daemon') || e.includes('docker daemon') || e.includes('docker.sock')) {
+            return 'HINT: Docker daemon is not running. Start it with `colima start` (macOS) or `sudo systemctl start docker` (Linux).';
+        }
+        if (e.includes('manifest unknown') || e.includes('manifest not found') || e.includes('not found')) {
+            return 'HINT: Image not found. Verify the image name and tag. Check registry credentials with `docker login`.';
+        }
+        if (e.includes('no space left on device') || e.includes('no space left')) {
+            return 'HINT: Docker disk space exhausted. Run `docker system prune -f` to reclaim space.';
+        }
+        if (e.includes('permission denied') && e.includes('docker')) {
+            return 'HINT: Docker permission denied. Add your user to the docker group: `sudo usermod -aG docker $USER`.';
+        }
+    }
+    // Secrets errors
+    if (toolName === 'secrets') {
+        if (e.includes('permission denied') || e.includes('403') || e.includes('accessdenied')) {
+            return 'HINT: Secrets access denied. Check Vault policy with `vault policy read <policy>` or IAM role permissions.';
+        }
+        if (e.includes('secret not found') || e.includes('no such secret') || e.includes('resourcenotfoundexception')) {
+            return 'HINT: Secret not found. Verify the secret path/name and namespace. Use `vault kv list <mount>` to browse.';
+        }
+        if (e.includes('invalid token') || e.includes('token expired')) {
+            return 'HINT: Vault/cloud token expired. Run `vault login` or refresh cloud credentials with `nimbus auth-refresh`.';
+        }
+    }
+    // CI/CD errors
+    if (toolName === 'cicd') {
+        if (e.includes('workflow not found') || e.includes('could not find workflow')) {
+            return 'HINT: Workflow not found. Check the workflow filename in .github/workflows/ and the branch name.';
+        }
+        if (e.includes('rate limit') || e.includes('429') || e.includes('too many requests')) {
+            return 'HINT: API rate limited. Wait 60 seconds and retry. Check rate limit headers for reset time.';
+        }
+        if (e.includes('unauthorized') || e.includes('401') || e.includes('bad credentials')) {
+            return 'HINT: CI/CD authentication failed. Check GITHUB_TOKEN, GITLAB_TOKEN, or CIRCLECI_TOKEN environment variables.';
+        }
+    }
+    // GitOps errors
+    if (toolName === 'gitops') {
+        if (e.includes('not found') || e.includes('not logged in') || e.includes('unauthenticated')) {
+            return 'HINT: ArgoCD/Flux not accessible. Check ARGOCD_SERVER and ARGOCD_TOKEN env vars, or run `argocd login`.';
+        }
+        if (e.includes('comparisonerror') || e.includes('sync error')) {
+            return 'HINT: GitOps sync error. Validate manifests: `kubectl apply --dry-run=client -f <manifest>` to find issues.';
+        }
+        if (e.includes('health') && e.includes('degraded')) {
+            return 'HINT: Application is degraded. Check pod logs with `kubectl logs -n <ns>` and events with `kubectl get events -n <ns>`.';
+        }
+    }
+    // Monitoring errors
+    if (toolName === 'monitor') {
+        if (e.includes('connection refused') || e.includes('could not connect')) {
+            return 'HINT: Cannot connect to monitoring endpoint. Check PROMETHEUS_URL, GRAFANA_URL, or cloud region configuration.';
+        }
+        if (e.includes('unauthorized') || e.includes('403')) {
+            return 'HINT: Monitoring authentication failed. Check DD_API_KEY, GRAFANA_TOKEN, or NEW_RELIC_API_KEY environment variables.';
+        }
+    }
+    // L3: Parse NIMBUS.md custom error hints section
+    if (nimbusInstructions) {
+        const hintsMatch = nimbusInstructions.match(/##\s*Custom Error Hints\s*\n([\s\S]*?)(?=\n##|\n$|$)/i);
+        if (hintsMatch) {
+            const hintsSection = hintsMatch[1];
+            const hintLines = hintsSection.split('\n').filter(l => l.trim().startsWith('-'));
+            for (const line of hintLines) {
+                // Format: "- pattern: hint message"
+                const colonIdx = line.indexOf(':');
+                if (colonIdx > 0) {
+                    const pattern = line.slice(1, colonIdx).trim();
+                    const hint = line.slice(colonIdx + 1).trim();
+                    if (pattern && hint && errorOutput.toLowerCase().includes(pattern.toLowerCase())) {
+                        return `HINT: ${hint}`;
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+/** DevOps tool names that get self-diagnosis hints on unrecognized errors. */
+const DEVOPS_TOOL_NAMES = new Set([
+    'terraform', 'kubectl', 'kubectl_context', 'helm', 'helm_values',
+    'bash', 'cloud_discover', 'drift_detect', 'deploy_preview',
+    'docker', 'secrets', 'cicd', 'monitor', 'gitops', 'cloud_action',
+    'logs', 'certs', 'mesh', 'cfn', 'k8s_rbac',
+]);
+/**
+ * Format a Zod (or generic) tool-input validation error into a human-readable
+ * message that tells the LLM exactly which fields are wrong and how to fix them.
+ */
+function formatToolInputError(toolName, err) {
+    if (err && typeof err === 'object' && 'issues' in err) {
+        // ZodError
+        const issues = err.issues;
+        const details = issues
+            .map(i => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('\n');
+        return `Tool "${toolName}" received invalid input:\n${details}\n\nPlease correct the arguments and retry.`;
+    }
+    return `Tool "${toolName}" failed: ${err instanceof Error ? err.message : String(err)}`;
+}
+/** Determine whether a streaming error is transient and worth retrying. */
+function isRetryableStreamError(err) {
+    if (err && typeof err === 'object') {
+        const e = err;
+        const status = (typeof e.status === 'number' ? e.status : undefined) ??
+            (typeof e.statusCode === 'number' ? e.statusCode : undefined);
+        if (status === 429 || (status !== undefined && status >= 500 && status < 600))
+            return true;
+        const msg = typeof e.message === 'string' ? e.message : '';
+        if (/rate.?limit|429|too many requests|overloaded|503/i.test(msg))
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// G3: Runaway protection helpers
+// ---------------------------------------------------------------------------
+/** Patterns that indicate a destructive operation in tool arguments. */
+const DESTRUCTIVE_PATTERNS = /\b(apply|destroy|delete|terminate|stop|remove|drop|truncate|purge)\b/i;
+/** Tool names whose destructive operations should be counted at the session level. */
+const DESTRUCTIVE_TOOL_NAMES = new Set([
+    'terraform', 'kubectl', 'docker', 'aws', 'gcloud', 'az', 'cloud_action', 'cfn',
+]);
+/**
+ * Returns true if the tool call looks like a destructive infrastructure operation.
+ * Used to enforce the session-level destructive ops counter (G3).
+ */
+function isDestructiveOp(toolName, inputStr) {
+    return DESTRUCTIVE_TOOL_NAMES.has(toolName) && DESTRUCTIVE_PATTERNS.test(inputStr);
+}
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default model when none is specified. */
+const DEFAULT_MODEL = 'anthropic/claude-sonnet-4-20250514';
+// ---------------------------------------------------------------------------
+// H5: Cost delta hint after terraform apply / helm upgrade
+// ---------------------------------------------------------------------------
+/**
+ * Extract a lightweight cost hint from tool output for display after
+ * infrastructure operations (terraform apply, helm install/upgrade).
+ */
+function extractCostHintFromToolOutput(toolName, input, output) {
+    // terraform apply: parse "Apply complete! Resources: N added, M changed, K destroyed."
+    if (toolName === 'terraform' && String(input.action) === 'apply') {
+        const m = output.match(/Resources:\s*(\d+) added,\s*(\d+) changed,\s*(\d+) destroyed/);
+        if (m) {
+            const added = Number(m[1]);
+            const changed = Number(m[2]);
+            const destroyed = Number(m[3]);
+            const parts = [];
+            if (added > 0)
+                parts.push(`+${added} resources created`);
+            if (changed > 0)
+                parts.push(`${changed} updated`);
+            if (destroyed > 0)
+                parts.push(`${destroyed} destroyed`);
+            return parts.length > 0
+                ? `${parts.join(', ')} — run "nimbus cost" for monthly cost estimate`
+                : null;
+        }
+    }
+    // helm install/upgrade
+    if (toolName === 'helm' && ['install', 'upgrade'].includes(String(input.action))) {
+        const releaseName = String(input.releaseName ?? input.release ?? '');
+        if (!output.includes('Error') && !output.includes('FAILED')) {
+            return `Helm release "${releaseName}" deployed — run "nimbus cost" for estimated cost impact`;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// M4: Session-scoped error tracking for NIMBUS.md persistence
+// ---------------------------------------------------------------------------
+const sessionErrorCounts = new Map();
+function trackAndPersistError(toolName, errorHint, cwd) {
+    const key = `${toolName}:${errorHint.slice(0, 60)}`;
+    const count = (sessionErrorCounts.get(key) ?? 0) + 1;
+    sessionErrorCounts.set(key, count);
+    if (count === 3) {
+        try {
+            const { existsSync, readFileSync, writeFileSync, appendFileSync } = require('node:fs');
+            const { join } = require('node:path');
+            const nimbusPath = join(cwd, 'NIMBUS.md');
+            if (!existsSync(nimbusPath))
+                return;
+            const existing = readFileSync(nimbusPath, 'utf-8');
+            if (existing.includes(errorHint.slice(0, 40)))
+                return; // already recorded
+            const entry = `- ${toolName}: ${errorHint}\n`;
+            if (existing.includes('## Observed Issues')) {
+                writeFileSync(nimbusPath, existing.replace('## Observed Issues\n', `## Observed Issues\n${entry}`));
+            }
+            else {
+                appendFileSync(nimbusPath, `\n## Observed Issues\n${entry}`);
+            }
+        }
+        catch { /* non-critical */ }
+    }
+}
+// ---------------------------------------------------------------------------
+// M6: Destructive action guard — force confirmation before terraform destroy / kubectl delete
+// ---------------------------------------------------------------------------
+function isDestructiveAction(toolName, input) {
+    const action = String(input.action ?? input.command ?? '');
+    if (toolName === 'terraform' && action === 'destroy') {
+        return 'terraform destroy will PERMANENTLY DELETE all managed infrastructure. Explicitly confirm with the user before proceeding.';
+    }
+    if (toolName === 'kubectl' && action === 'delete') {
+        const resource = String(input.resource ?? '');
+        return `kubectl delete ${resource} is IRREVERSIBLE. Explicitly confirm with the user before proceeding.`;
+    }
+    if (toolName === 'helm' && action === 'uninstall') {
+        return 'helm uninstall will remove the release and its resources. Explicitly confirm with the user before proceeding.';
+    }
+    return null;
+}
+const PLAN_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const terraformPlanCache = new Map();
+/** Store a terraform plan output for a workdir. */
+function cacheTerraformPlan(workdir, output) {
+    terraformPlanCache.set(workdir, { output, workdir, timestamp: Date.now() });
+}
+/** Retrieve a cached terraform plan for a workdir, or null if expired/missing. */
+function getCachedTerraformPlan(workdir) {
+    const entry = terraformPlanCache.get(workdir);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.timestamp > PLAN_CACHE_TTL_MS) {
+        terraformPlanCache.delete(workdir);
+        return null;
+    }
+    return entry.output;
+}
+/**
+ * Background interval that evicts expired terraform plan cache entries every 60s.
+ * `.unref()` ensures this does not prevent the process from exiting.
+ * Exported for test teardown.
+ */
+export const _planCacheCleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of terraformPlanCache) {
+        if (now - entry.timestamp > PLAN_CACHE_TTL_MS) {
+            terraformPlanCache.delete(key);
+        }
+    }
+}, 60_000).unref();
+/** Default max output tokens per LLM call. */
+const DEFAULT_MAX_TOKENS = 8192;
+/** Default maximum number of agent turns. */
+const DEFAULT_MAX_TURNS = 50;
+/** Maximum characters of tool output to include in conversation history.
+ *  Anything beyond this is truncated to prevent context window overflow. */
+const MAX_TOOL_OUTPUT_CHARS = 100_000;
+// ---------------------------------------------------------------------------
+// Main Entry Point
+// ---------------------------------------------------------------------------
+/**
+ * Run the agentic loop.
+ *
+ * Takes a user message and existing conversation history, then runs
+ * the LLM in a loop until it stops requesting tool calls.
+ *
+ * The loop terminates when any of the following conditions are met:
+ * - The LLM returns a response with no tool calls (natural end).
+ * - The maximum number of turns is reached.
+ * - The AbortSignal fires (e.g. user presses Ctrl+C).
+ * - An unrecoverable LLM API error occurs.
+ *
+ * @param userMessage - The new user message to process.
+ * @param history - Prior conversation messages (may be empty for a fresh session).
+ * @param options - Configuration for the loop.
+ * @returns The final conversation state, turn count, usage, and cost.
+ */
+export async function runAgentLoop(userMessage, history, options) {
+    const { router, toolRegistry, mode, maxTurns = DEFAULT_MAX_TURNS, model, cwd, nimbusInstructions, onText, onToolCallStart, onToolCallEnd, onToolOutputChunk, checkPermission, signal, } = options;
+    // -----------------------------------------------------------------------
+    // 1. Prepare tools and system prompt
+    // -----------------------------------------------------------------------
+    const tools = getToolsForMode(toolRegistry.getAll(), mode);
+    // H3: Auto-discover infra context if not provided and cwd is set (best-effort, cached per cwd)
+    let resolvedInfraContext = options.infraContext;
+    if (!resolvedInfraContext && cwd) {
+        try {
+            const { discoverInfraContext } = await import('../cli/init');
+            resolvedInfraContext = await Promise.race([
+                discoverInfraContext(cwd),
+                new Promise(r => setTimeout(() => r(undefined), 5000)),
+            ]);
+        }
+        catch { /* best-effort */ }
+    }
+    const systemPrompt = buildSystemPrompt({
+        mode,
+        tools,
+        nimbusInstructions,
+        cwd,
+        infraContext: resolvedInfraContext,
+        dryRun: options.dryRun,
+    });
+    // Convert agentic ToolDefinitions to the LLM-level format expected by
+    // the router's routeWithTools() method (OpenAI function-calling shape).
+    const llmTools = tools.map(toOpenAITool);
+    // -----------------------------------------------------------------------
+    // 2. Initialize conversation state
+    // -----------------------------------------------------------------------
+    // PERF-4a: Capacity-hinted pre-allocation avoids repeated V8 array reallocation
+    // as messages accumulate during a long conversation.
+    const messages = new Array(Math.max(history.length + 1, 10));
+    messages.length = 0;
+    messages.push(...history, { role: 'user', content: userMessage });
+    let turns = 0;
+    let interrupted = false;
+    const totalUsage = {
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+    };
+    let totalCost = 0;
+    // G3: Session-level destructive operation counter and per-turn tool call counter
+    let sessionDestructiveOps = 0;
+    const MAX_TOOL_CALLS_PER_TURN = options.maxToolCallsPerTurn ?? 20;
+    const MAX_DESTRUCTIVE_OPS_PER_SESSION = options.maxDestructiveOpsPerSession ?? 5;
+    // M2/M5: Track tool calls that have already received a credential-error retry message
+    // to avoid spamming the auth-refresh hint on repeated failures.
+    const credentialRetried = new Set();
+    // G8: Track which terraform workdirs have had a plan run in this session.
+    // Used to warn when apply is run without a prior plan.
+    const terraformPlannedWorkdirs = new Set();
+    // G10: One-time kubectl RBAC pre-flight check state.
+    // kubectlRbacChecked: ensures we only run `kubectl auth can-i --list` once per session.
+    // rbacPreamble: stores the RBAC output to inject into the first kubectl tool result.
+    let kubectlRbacChecked = false;
+    let rbacPreamble = '';
+    // G10: Pre-import async exec utilities so they're available inside the loop.
+    // Using async execFile avoids blocking the Node.js event loop for kubectl/terraform calls.
+    const { execFile: _execFile, exec: _exec } = await import('node:child_process');
+    const { promisify: _promisify } = await import('node:util');
+    const _execFileAsync = _promisify(_execFile);
+    const _execAsync = _promisify(_exec);
+    // PERF-4a: Pre-build the system message once so it can be reused every turn
+    // without allocating a new object on each loop iteration.
+    const _systemMessageObj = { role: 'system', content: systemPrompt };
+    // Shared mutable ref: set to true by 'apply-all' diff decision to skip further prompts
+    const skipRemainingDiffPrompts = { value: options.skipRemainingDiffPrompts ?? false };
+    // Shared mutable ref: set to true by 'reject-all' diff decision to auto-reject further prompts
+    const rejectRemainingDiffPrompts = { value: options.rejectRemainingDiffPrompts ?? false };
+    // -----------------------------------------------------------------------
+    // 3. Main agent loop
+    // -----------------------------------------------------------------------
+    while (turns < maxTurns) {
+        // Check for cancellation before each turn
+        if (signal?.aborted) {
+            interrupted = true;
+            break;
+        }
+        turns++;
+        try {
+            // Gap 18: Auto-route model based on task complexity when no explicit model set
+            let effectiveModel = model ?? DEFAULT_MODEL;
+            if (!model && options.autoRouteModel) {
+                const lastUserMsg = [...messages].reverse().find(m => m.role === 'user');
+                const lastMsgText = lastUserMsg
+                    ? typeof lastUserMsg.content === 'string'
+                        ? lastUserMsg.content
+                        : JSON.stringify(lastUserMsg.content)
+                    : '';
+                const complexity = classifyTaskComplexity(lastMsgText);
+                effectiveModel = routeModel(complexity);
+                if (onText && turns === 1) {
+                    onText(`\n[auto: ${effectiveModel.split('/').pop()?.replace('anthropic/', '') ?? effectiveModel}]\n`);
+                }
+            }
+            // Build the completion request with tool definitions.
+            // The systemMessageObj is pre-built before the loop (PERF-4a) — reuse it.
+            const allMessages = new Array(messages.length + 1);
+            allMessages.length = 0;
+            allMessages.push(_systemMessageObj, ...messages);
+            const request = {
+                messages: allMessages,
+                model: effectiveModel,
+                tools: llmTools,
+                maxTokens: DEFAULT_MAX_TOKENS,
+            };
+            // Stream text tokens incrementally via routeStreamWithTools.
+            // Tokens are forwarded to onText as they arrive; tool calls
+            // are accumulated from the final chunk.
+            let responseContent = '';
+            let responseToolCalls;
+            let responseUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            // A1: Retry on transient errors (rate-limit / 5xx) with exponential backoff
+            const MAX_STREAM_RETRIES = 2;
+            let streamAttempt = 0;
+            while (true) {
+                // A2: Silence timeout — abort if no chunk arrives (G21: configurable)
+                const STREAM_SILENCE_MS = options.streamSilenceTimeoutMs ?? 60_000;
+                const silenceAbort = new AbortController();
+                let silenceTimer;
+                const resetSilence = () => {
+                    clearTimeout(silenceTimer);
+                    silenceTimer = setTimeout(() => silenceAbort.abort('Stream timeout'), STREAM_SILENCE_MS);
+                };
+                resetSilence();
+                try {
+                    // Pass silence abort signal via request cast (non-standard but supported by most providers)
+                    const requestWithSignal = { ...request, signal: silenceAbort.signal };
+                    for await (const chunk of router.routeStreamWithTools(requestWithSignal)) {
+                        resetSilence(); // reset on every chunk
+                        if (chunk.content) {
+                            responseContent += chunk.content;
+                            if (onText) {
+                                onText(chunk.content);
+                            }
+                        }
+                        if (chunk.toolCallStart && onText) {
+                            // Show early feedback when the LLM starts composing a tool call
+                            onText(`\n[Preparing tool: ${chunk.toolCallStart.name}...]\n`);
+                        }
+                        if (chunk.toolCalls) {
+                            responseToolCalls = chunk.toolCalls;
+                        }
+                        if (chunk.usage) {
+                            responseUsage = chunk.usage;
+                        }
+                    }
+                    clearTimeout(silenceTimer);
+                    break; // success — exit retry loop
+                }
+                catch (streamErr) {
+                    clearTimeout(silenceTimer);
+                    if (streamAttempt < MAX_STREAM_RETRIES && isRetryableStreamError(streamErr)) {
+                        const delay = 1000 * Math.pow(2, streamAttempt);
+                        if (onText) {
+                            onText(`\n[Retrying after error (attempt ${streamAttempt + 1})...]\n`);
+                        }
+                        await new Promise(r => setTimeout(r, delay));
+                        streamAttempt++;
+                        // Reset partial accumulation before retry
+                        responseContent = '';
+                        responseToolCalls = undefined;
+                        responseUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+                        continue;
+                    }
+                    // G24: Graceful network error message instead of raw Node.js error
+                    const streamErrObj = streamErr;
+                    const isNetworkError = /ECONNREFUSED|ETIMEDOUT|ENOTFOUND|fetch failed|network/i.test(streamErrObj?.message ?? '');
+                    if (isNetworkError) {
+                        const netMsg = '\n[!!] Network unreachable — cannot reach the LLM API.\nCheck your internet connection and API key validity, then try again.\n';
+                        if (onText)
+                            onText(netMsg);
+                        // Re-throw a specially-marked error so the outer turn catch block can handle it
+                        const netErr = new Error(netMsg);
+                        netErr._nimbusNetworkError = true;
+                        throw netErr;
+                    }
+                    throw streamErr; // non-retryable — propagate to outer catch
+                }
+            }
+            // Accumulate usage and cost
+            totalUsage.promptTokens += responseUsage.promptTokens;
+            totalUsage.completionTokens += responseUsage.completionTokens;
+            totalUsage.totalTokens += responseUsage.totalTokens;
+            // Estimate cost for this turn
+            const resolvedModel = effectiveModel;
+            const providerName = resolvedModel.includes('/') ? resolvedModel.split('/')[0] : 'anthropic';
+            const modelName = resolvedModel.includes('/')
+                ? resolvedModel.split('/').slice(1).join('/')
+                : resolvedModel;
+            const turnCost = calculateCost(providerName, modelName, responseUsage.promptTokens, responseUsage.completionTokens);
+            totalCost += turnCost.costUSD;
+            // Notify caller of accumulated usage/cost after each turn
+            if (options.onUsage) {
+                options.onUsage(totalUsage, totalCost);
+            }
+            // M2: Emit per-turn token/cost stats as a dim system message in the TUI.
+            // Only emit when there was actual token usage (skip turns with 0 tokens).
+            if (onText && (responseUsage.promptTokens > 0 || responseUsage.completionTokens > 0)) {
+                const statsLine = `\n[${responseUsage.promptTokens} in / ${responseUsage.completionTokens} out — $${turnCost.costUSD.toFixed(4)}]\n`;
+                onText(statsLine);
+            }
+            // G16: Cost budget enforcement — stop if cumulative cost exceeds the limit
+            if (options.costBudgetUSD !== undefined && totalCost >= options.costBudgetUSD) {
+                const budgetMsg = `\n\n[!!] Cost budget of $${options.costBudgetUSD.toFixed(2)} reached (used: $${totalCost.toFixed(3)}). Stopping to prevent overspend.\n`;
+                if (onText)
+                    onText(budgetMsg);
+                messages.push({ role: 'assistant', content: budgetMsg });
+                break;
+            }
+            // -----------------------------------------------------------------
+            // No tool calls → the LLM is done
+            // -----------------------------------------------------------------
+            if (!responseToolCalls || responseToolCalls.length === 0) {
+                messages.push({
+                    role: 'assistant',
+                    content: responseContent,
+                });
+                break;
+            }
+            // -----------------------------------------------------------------
+            // Tool calls present → execute each one
+            // -----------------------------------------------------------------
+            // Append the assistant message that contains the tool calls
+            messages.push({
+                role: 'assistant',
+                content: responseContent,
+                toolCalls: responseToolCalls,
+            });
+            // G3: Per-turn tool call counter — reset at the start of each tool-call batch
+            let turnToolCallCount = 0;
+            // H2: Parallel dispatch for read-only tools (safe to run concurrently)
+            const READ_ONLY_TOOLS = new Set([
+                'read_file', 'glob', 'grep', 'cloud_discover', 'terraform_plan_analyze',
+                'kubectl_context', 'helm_values', 'cost_estimate', 'drift_detect',
+            ]);
+            const canRunInParallel = (tc) => READ_ONLY_TOOLS.has(tc.function.name);
+            const allReadOnly = responseToolCalls.every(canRunInParallel);
+            if (allReadOnly && responseToolCalls.length > 1) {
+                // All tools are read-only — dispatch in parallel
+                const parallelChunkCallback = onToolOutputChunk
+                    ? (id) => (chunk) => onToolOutputChunk(id, chunk)
+                    : undefined;
+                const parallelResults = await Promise.allSettled(responseToolCalls.map(tc => executeToolCall(tc, toolRegistry, onToolCallStart, onToolCallEnd, checkPermission, options.lspManager, options.snapshotManager, options.sessionId, signal, options.hookEngine, mode, options.requestFileDiff, skipRemainingDiffPrompts, rejectRemainingDiffPrompts, parallelChunkCallback ? parallelChunkCallback(tc.id) : undefined, options.toolTimeouts, options.infraContext)));
+                for (let pi = 0; pi < responseToolCalls.length; pi++) {
+                    const tc = responseToolCalls[pi];
+                    const pResult = parallelResults[pi];
+                    const pContent = pResult.status === 'fulfilled'
+                        ? (pResult.value.isError ? `Error: ${pResult.value.error}` : pResult.value.output)
+                        : `Error: ${pResult.reason}`;
+                    messages.push({ role: 'tool', toolCallId: tc.id, name: tc.function.name, content: pContent });
+                }
+                // Skip sequential processing — jump directly to next LLM turn
+                continue;
+            }
+            // Process tool calls sequentially (order may matter for side effects)
+            for (const toolCall of responseToolCalls) {
+                // Check for cancellation between tool calls
+                if (signal?.aborted) {
+                    interrupted = true;
+                    break;
+                }
+                // G3: Enforce per-turn tool call limit to prevent runaway loops
+                turnToolCallCount++;
+                if (turnToolCallCount > MAX_TOOL_CALLS_PER_TURN) {
+                    messages.push({
+                        role: 'tool',
+                        toolCallId: toolCall.id,
+                        name: toolCall.function.name,
+                        content: `[Tool limit reached: ${MAX_TOOL_CALLS_PER_TURN} tool calls in this turn. Summarizing progress and stopping to avoid runaway execution.]`,
+                    });
+                    break;
+                }
+                // G3: Count destructive operations at the session level
+                if (isDestructiveOp(toolCall.function.name, toolCall.function.arguments)) {
+                    sessionDestructiveOps++;
+                }
+                // G10: One-time kubectl RBAC pre-flight check — runs before the first kubectl call
+                // in this session. Stores the RBAC permissions summary in rbacPreamble so it can
+                // be injected into the first kubectl tool result (keeps conversation structure valid).
+                // Uses async execFile to avoid blocking the Node.js event loop (up to 5s call).
+                if (!kubectlRbacChecked && toolCall.function.name === 'kubectl') {
+                    kubectlRbacChecked = true;
+                    try {
+                        const { stdout: rbacOut } = await _execFileAsync('kubectl', ['auth', 'can-i', '--list'], {
+                            encoding: 'utf-8', timeout: 5000,
+                        });
+                        const truncated = rbacOut.length > 1500
+                            ? `${rbacOut.slice(0, 1500)}\n...[truncated]`
+                            : rbacOut;
+                        rbacPreamble = `[kubectl RBAC context: permissions available in current context]\n${truncated}\n\n`;
+                    }
+                    catch { /* non-critical — RBAC check failure does not block kubectl */ }
+                }
+                // M6: Destructive action guard — inject warning into LLM context before executing
+                try {
+                    const m6Input = JSON.parse(toolCall.function.arguments);
+                    const destructiveWarning = isDestructiveAction(toolCall.function.name, m6Input);
+                    if (destructiveWarning) {
+                        messages.push({
+                            role: 'tool',
+                            toolCallId: toolCall.id + '-guard',
+                            name: toolCall.function.name,
+                            content: `[SAFETY] ${destructiveWarning}`,
+                        });
+                    }
+                }
+                catch { /* ignore parse errors */ }
+                // Build chunk callback that forwards tool output to the TUI in real-time
+                const chunkCallback = onToolOutputChunk
+                    ? (chunk) => onToolOutputChunk(toolCall.id, chunk)
+                    : undefined;
+                const result = await executeToolCall(toolCall, toolRegistry, onToolCallStart, onToolCallEnd, checkPermission, options.lspManager, options.snapshotManager, options.sessionId, signal, options.hookEngine, mode, options.requestFileDiff, skipRemainingDiffPrompts, rejectRemainingDiffPrompts, chunkCallback, options.toolTimeouts, options.infraContext);
+                // Append each tool result as a separate message so the LLM can
+                // match it to the corresponding tool_use block by toolCallId.
+                let toolContent = result.isError ? `Error: ${result.error}` : result.output;
+                // G10: Inject RBAC context preamble into the first kubectl result
+                if (rbacPreamble && toolCall.function.name === 'kubectl') {
+                    toolContent = rbacPreamble + toolContent;
+                    rbacPreamble = ''; // consume once — only injected into the first kubectl result
+                }
+                // Inject DevOps error classification hints to guide self-correction
+                if (result.isError && result.error) {
+                    const hint = classifyDevOpsError(toolCall.function.name, result.error, options.nimbusInstructions);
+                    if (hint) {
+                        toolContent += `\n\n${hint}`;
+                        // C4: Also show hint in TUI error output (not just LLM context)
+                        result.output += `\n\n${hint}`;
+                        // M2/M5: Auto-retry signal on credential expiry errors
+                        // If the classified hint indicates a credential/auth problem, append
+                        // a structured prompt so the agent knows to run auth-refresh, and
+                        // set provider-specific env hints for the auth-refresh command.
+                        const isCredentialError = hint.toLowerCase().includes('credential') ||
+                            hint.toLowerCase().includes('expired') ||
+                            hint.toLowerCase().includes('auth') ||
+                            hint.toLowerCase().includes('login required');
+                        if (isCredentialError && !credentialRetried.has(toolCall.id ?? toolCall.function.name)) {
+                            credentialRetried.add(toolCall.id ?? toolCall.function.name);
+                            // M5: Set provider-specific refresh hint env vars so auth-refresh
+                            // can surface targeted guidance when invoked by the user.
+                            const errorLower = (result.error ?? '').toLowerCase();
+                            if (errorLower.includes('aws')) {
+                                process.env.NIMBUS_AWS_REFRESH_HINT = '1';
+                            }
+                            if (errorLower.includes('gcp') || errorLower.includes('google')) {
+                                process.env.NIMBUS_GCP_REFRESH_HINT = '1';
+                            }
+                            if (errorLower.includes('azure')) {
+                                process.env.NIMBUS_AZURE_REFRESH_HINT = '1';
+                            }
+                            const refreshMsg = [
+                                '[!!] Credential expired. Run: nimbus auth-refresh',
+                                '[Nimbus] Credential error detected on tool: ' + toolCall.function.name,
+                                'Run "nimbus auth-refresh" to refresh cloud credentials, then retry.',
+                            ].join('\n');
+                            toolContent += '\n\n' + refreshMsg;
+                            result.output += '\n\n' + refreshMsg;
+                        }
+                    }
+                    else if (DEVOPS_TOOL_NAMES.has(toolCall.function.name)) {
+                        // Unknown DevOps error — provide structured self-diagnosis steps
+                        toolContent += [
+                            '\n\n--- Self-Diagnosis Steps ---',
+                            '1. Check tool is installed: `which terraform` / `kubectl version` / `helm version`',
+                            '2. Check credentials: `aws sts get-caller-identity` / `gcloud auth list` / `az account show`',
+                            '3. Check network connectivity to the cluster/cloud provider',
+                            '4. Retry with verbose flag if available (e.g., TF_LOG=DEBUG, kubectl --v=6)',
+                            '5. If the error persists, report the exact error message and the command that caused it.',
+                        ].join('\n');
+                    }
+                    // M4: Track recurring errors and persist to NIMBUS.md after 3 occurrences
+                    const m4Hint = classifyDevOpsError(toolCall.function.name, result.error ?? '', options.nimbusInstructions);
+                    if (m4Hint) {
+                        trackAndPersistError(toolCall.function.name, m4Hint, options.cwd ?? process.cwd());
+                    }
+                }
+                // H5: Inject cost delta hint after successful infra operations
+                if (!result.isError) {
+                    try {
+                        const h5Input = JSON.parse(toolCall.function.arguments);
+                        const costHint = extractCostHintFromToolOutput(toolCall.function.name, h5Input, result.output);
+                        if (costHint) {
+                            onText?.(`\n[cost] ${costHint}\n`);
+                        }
+                    }
+                    catch { /* ignore parse errors */ }
+                }
+                // L6: Auto-generate runbook after terraform apply success
+                if (!result.isError && toolCall.function.name === 'terraform') {
+                    try {
+                        const l6Input = JSON.parse(toolCall.function.arguments);
+                        if (String(l6Input.action) === 'apply') {
+                            const l6Match = result.output.match(/Resources:\s*(\d+) added/);
+                            if (l6Match && parseInt(l6Match[1] ?? '0', 10) > 0) {
+                                const { join: _l6Join } = require('node:path');
+                                const { homedir: _l6Homedir } = require('node:os');
+                                const { mkdirSync: _l6MkdirSync, writeFileSync: _l6WriteFileSync } = require('node:fs');
+                                const runbookDir = _l6Join(_l6Homedir(), '.nimbus', 'runbooks');
+                                _l6MkdirSync(runbookDir, { recursive: true });
+                                const ts = new Date().toISOString().replace(/[:.]/g, '-');
+                                const runbookPath = _l6Join(runbookDir, `terraform-apply-${ts}.md`);
+                                const runbookContent = [
+                                    '# Terraform Apply Runbook',
+                                    '',
+                                    `Date: ${new Date().toLocaleString()}`,
+                                    '',
+                                    'Apply output:',
+                                    '```',
+                                    result.output.slice(0, 2000),
+                                    '```',
+                                    '',
+                                    '## Rollback',
+                                    '',
+                                    'To rollback, run `terraform destroy` or restore from a previous state.',
+                                ].join('\n');
+                                _l6WriteFileSync(runbookPath, runbookContent, 'utf-8');
+                                options.onText?.(`\n[runbook] Saved to ${runbookPath}\n`);
+                            }
+                        }
+                    }
+                    catch { /* non-critical */ }
+                }
+                // GAP-25: Structured audit trail for destructive operations
+                if (!result.isError && isDestructiveOp(toolCall.function.name, toolCall.function.arguments)) {
+                    try {
+                        const { appendFileSync, mkdirSync } = await import('node:fs');
+                        const { homedir } = await import('node:os');
+                        const { join } = await import('node:path');
+                        const auditDir = join(homedir(), '.nimbus');
+                        mkdirSync(auditDir, { recursive: true });
+                        const event = JSON.stringify({
+                            type: 'infra-change',
+                            tool: toolCall.function.name,
+                            action: JSON.parse(toolCall.function.arguments).action,
+                            sessionId: options.sessionId ?? 'unknown',
+                            cwd: options.cwd ?? process.cwd(),
+                            timestamp: new Date().toISOString(),
+                        });
+                        appendFileSync(join(auditDir, 'audit.jsonl'), event + '\n', 'utf-8');
+                    }
+                    catch { /* audit logging is non-critical */ }
+                }
+                // G3: Append a warning when session-level destructive op threshold is reached
+                if (sessionDestructiveOps >= MAX_DESTRUCTIVE_OPS_PER_SESSION) {
+                    toolContent += `\n\n[Warning: ${sessionDestructiveOps} destructive operations executed in this session. Review changes carefully.]`;
+                }
+                // Cache terraform plan output so a subsequent apply can reference it.
+                // Also track planned workdirs (G8) and warn on unplanned applies.
+                if (toolCall.function.name === 'terraform' && !result.isError) {
+                    try {
+                        const tfArgs = JSON.parse(toolCall.function.arguments);
+                        if (tfArgs.action === 'plan' && tfArgs.workdir) {
+                            cacheTerraformPlan(String(tfArgs.workdir), result.output);
+                            // G8: Track that a plan was run for this workdir in this session
+                            terraformPlannedWorkdirs.add(String(tfArgs.workdir));
+                        }
+                        // G8: Warn if apply ran without a prior plan in this session
+                        if (tfArgs.action === 'apply' && tfArgs.workdir && !terraformPlannedWorkdirs.has(String(tfArgs.workdir))) {
+                            toolContent = `[Note: terraform apply ran without a prior terraform plan in this session for ${String(tfArgs.workdir)}. Always run terraform plan first to review changes before applying.]\n\n${toolContent}`;
+                        }
+                        // Inject cached plan into apply context for the LLM
+                        if (tfArgs.action === 'apply' && tfArgs.workdir) {
+                            const cached = getCachedTerraformPlan(String(tfArgs.workdir));
+                            if (cached) {
+                                toolContent = `[Apply succeeded. This was the plan that was applied:]\n${cached.slice(0, 3000)}\n\n[Apply output:]\n${toolContent}`;
+                            }
+                        }
+                    }
+                    catch { /* ignore parse errors */ }
+                }
+                // GAP-11: trigger FileDiff UI after terraform plan shows resource changes
+                if (toolCall.function.name === 'terraform' && !result.isError && options.requestFileDiff) {
+                    try {
+                        const tfArgs11 = JSON.parse(toolCall.function.arguments);
+                        if (tfArgs11.action === 'plan') {
+                            const { parseTerraformPlanOutput, buildFileDiffBatchFromPlan } = await import('./deploy-preview');
+                            const changes = parseTerraformPlanOutput(toolContent);
+                            if (changes.length > 0) {
+                                const batchFiles = buildFileDiffBatchFromPlan({ changes });
+                                for (const file of batchFiles) {
+                                    const decision = await options.requestFileDiff(file.filePath, file.toolName ?? 'terraform', file.diff ?? '');
+                                    if (decision === 'reject-all')
+                                        break;
+                                }
+                            }
+                        }
+                    }
+                    catch { /* non-critical — FileDiff UI not always available */ }
+                }
+                // GAP-18: auto-validate terraform files after write/edit tool calls
+                if (['write_file', 'edit_file', 'multi_edit'].includes(toolCall.function.name) && !result.isError) {
+                    const gap18Input = JSON.parse(toolCall.function.arguments);
+                    const gap18FilePath = gap18Input.path ?? gap18Input.file_path ?? '';
+                    if (gap18FilePath.endsWith('.tf')) {
+                        try {
+                            // Use async exec to avoid blocking the event loop (up to 10s for terraform validate)
+                            const { stdout: validateOut } = await _execAsync('terraform validate -json 2>/dev/null', {
+                                cwd: options.cwd ?? process.cwd(),
+                                encoding: 'utf-8',
+                                timeout: 10_000,
+                            });
+                            const parsed = JSON.parse(validateOut);
+                            if (!parsed.valid && parsed.diagnostics && parsed.diagnostics.length > 0) {
+                                const errors = parsed.diagnostics
+                                    .filter(d => d.severity === 'error')
+                                    .map(d => `  ${d.summary}: ${d.detail}`)
+                                    .join('\n');
+                                toolContent += `\n\nTerraform validation errors (please fix):\n${errors}`;
+                            }
+                        }
+                        catch { /* terraform not available or not in tf project — ignore */ }
+                    }
+                }
+                // Truncate excessively large tool outputs to prevent context overflow
+                if (toolContent.length > MAX_TOOL_OUTPUT_CHARS) {
+                    let head;
+                    let tail;
+                    let omitted;
+                    const lines = toolContent.split('\n');
+                    // C3: Smart truncation for terraform plan — preserve all diff lines
+                    const isTerraformPlan = toolCall.function.name === 'terraform' && (() => {
+                        try {
+                            const tfArgs = JSON.parse(toolCall.function.arguments);
+                            return tfArgs.action === 'plan';
+                        }
+                        catch {
+                            return false;
+                        }
+                    })();
+                    if (isTerraformPlan) {
+                        // Keep all diff lines (create/update/destroy/replace) and the plan summary
+                        const diffLines = [];
+                        const contextLines = [];
+                        for (const line of lines) {
+                            const trimmed = line.trimStart();
+                            const isDiffLine = trimmed.startsWith('+') || trimmed.startsWith('-') ||
+                                trimmed.startsWith('~') || trimmed.startsWith('!') ||
+                                line.includes('will be created') || line.includes('will be destroyed') ||
+                                line.includes('will be updated') || line.includes('will be replaced') ||
+                                line.includes('Plan:') || line.includes('No changes') ||
+                                line.includes('Error:') || line.includes('Warning:');
+                            if (isDiffLine) {
+                                diffLines.push(line);
+                            }
+                            else {
+                                contextLines.push(line);
+                            }
+                        }
+                        // Allow up to 500 diff lines + first 50 context lines
+                        const keptDiff = diffLines.slice(0, 500);
+                        const keptCtx = contextLines.slice(0, 50);
+                        omitted = Math.max(0, lines.length - keptDiff.length - keptCtx.length);
+                        head = [...keptCtx, ...keptDiff].join('\n');
+                        tail = '';
+                    }
+                    else {
+                        const headLines = 100, tailLines = 20;
+                        head = lines.slice(0, headLines).join('\n');
+                        tail = lines.slice(-tailLines).join('\n');
+                        omitted = Math.max(0, lines.length - headLines - tailLines);
+                    }
+                    // Save full output to disk for reference
+                    try {
+                        const { mkdirSync: _mkdirSync, writeFileSync: _writeFileSync } = await import('node:fs');
+                        const { homedir: _homedir } = await import('node:os');
+                        const outDir = join(_homedir(), '.nimbus', 'tool-outputs');
+                        _mkdirSync(outDir, { recursive: true });
+                        const outFile = join(outDir, `${Date.now()}-${toolCall.function.name}.log`);
+                        _writeFileSync(outFile, toolContent, 'utf-8');
+                        toolContent = omitted > 0
+                            ? `${head}${tail ? '\n\n... [' + omitted + ' lines omitted — full output saved to ' + outFile + '] ...\n\n' + tail : '\n\n... [full output saved to ' + outFile + ']'}`
+                            : `${head}${tail ? '\n\n' + tail : ''}`;
+                    }
+                    catch {
+                        toolContent = omitted > 0
+                            ? `${head}${tail ? '\n\n... [' + omitted + ' lines omitted — output too large for context] ...\n\n' + tail : '\n\n... [' + omitted + ' lines omitted]'}`
+                            : `${head}${tail ? '\n\n' + tail : ''}`;
+                    }
+                }
+                messages.push({
+                    role: 'tool',
+                    toolCallId: toolCall.id,
+                    name: toolCall.function.name,
+                    content: toolContent,
+                });
+            }
+            // If we broke out of the tool-call loop due to cancellation, exit
+            // the main loop as well.
+            if (interrupted) {
+                break;
+            }
+            // -----------------------------------------------------------------
+            // Auto-compact check
+            // -----------------------------------------------------------------
+            // After tool results are appended, check whether the conversation
+            // has grown past the context window threshold. If so, summarize
+            // older messages to free up space for future turns.
+            if (options.contextManager) {
+                const toolTokens = llmTools.reduce((sum, t) => sum + Math.ceil(JSON.stringify(t).length / 4), 0);
+                if (options.contextManager.shouldCompact(systemPrompt, messages, toolTokens)) {
+                    try {
+                        const compactResult = await runCompaction(messages, options.contextManager, {
+                            router,
+                            ...(options.infraContext ? { infraContext: options.infraContext } : {}),
+                        });
+                        // Replace messages with the compacted version
+                        messages.length = 0;
+                        messages.push(...compactResult.messages);
+                        // Clear the token cache after compaction — old message entries are no longer valid
+                        options.contextManager.clearTokenCache();
+                        if (options.onCompact) {
+                            options.onCompact(compactResult.result);
+                        }
+                    }
+                    catch (compactErr) {
+                        // Compaction failed — notify user visibly and continue with original messages
+                        const compactErrMsg = compactErr instanceof Error ? compactErr.message : String(compactErr);
+                        if (onText) {
+                            onText(`\n[Warning: Auto-compaction failed: ${compactErrMsg}. Context may exceed budget on the next turn.]\n`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // LLM API error — report to the caller and break
+            const msg = error instanceof Error ? error.message : String(error);
+            // G24: Network errors already printed via onText above — skip duplicate output
+            const isNetworkErr = (error instanceof Error) && error._nimbusNetworkError;
+            if (!isNetworkErr && onText) {
+                onText(`\n[Error: ${msg}]\n`);
+            }
+            messages.push({
+                role: 'assistant',
+                content: isNetworkErr ? msg : `I encountered an error: ${msg}`,
+            });
+            break;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 4. Post-loop bookkeeping
+    // -----------------------------------------------------------------------
+    if (turns >= maxTurns && !interrupted) {
+        if (onText) {
+            onText(`\n[Agent reached maximum turns limit (${maxTurns}). Stopping.]\n`);
+        }
+    }
+    // GAP-19: Session summary after multi-step deploy
+    if (options.mode === 'deploy' && options.onText) {
+        // Collect tool calls from messages
+        const allToolCalls = [];
+        for (const msg of messages) {
+            if (msg.role === 'assistant' && Array.isArray(msg.toolCalls)) {
+                for (const tc of msg.toolCalls) {
+                    try {
+                        allToolCalls.push({ name: tc.function.name, input: JSON.parse(tc.function.arguments) });
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+        if (allToolCalls.length > 3) {
+            const terraform = allToolCalls.filter(c => c.name === 'terraform');
+            const kubectl = allToolCalls.filter(c => c.name === 'kubectl');
+            const helm = allToolCalls.filter(c => c.name === 'helm');
+            const summaryLines = ['---', '**Session Summary**'];
+            if (terraform.length)
+                summaryLines.push(`• Terraform: ${terraform.map(c => String(c.input.action ?? '')).join(', ')}`);
+            if (kubectl.length)
+                summaryLines.push(`• Kubectl: ${kubectl.map(c => String(c.input.action ?? '')).join(', ')}`);
+            if (helm.length)
+                summaryLines.push(`• Helm: ${helm.map(c => String(c.input.action ?? '')).join(', ')}`);
+            if (summaryLines.length > 2) {
+                options.onText('\n\n' + summaryLines.join('\n'));
+            }
+        }
+    }
+    return {
+        messages,
+        turns,
+        interrupted,
+        usage: totalUsage,
+        totalCost,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool Execution
+// ---------------------------------------------------------------------------
+/** Tools that modify files and should trigger LSP diagnostics. */
+const FILE_EDITING_TOOLS = new Set(['edit_file', 'multi_edit', 'write_file']);
+/** Tools that mutate files and may require a pre-approval diff. */
+const FILE_MUTATING_TOOLS = new Set(['edit_file', 'multi_edit', 'write_file']);
+/**
+ * Generate a simple unified diff between two strings.
+ * Suitable for display; uses a greedy line-by-line approach.
+ */
+function generateUnifiedDiff(filename, before, after) {
+    const beforeLines = before.split('\n');
+    const afterLines = after.split('\n');
+    const lines = [`--- a/${filename}`, `+++ b/${filename}`];
+    let i = 0;
+    let j = 0;
+    while (i < beforeLines.length || j < afterLines.length) {
+        if (beforeLines[i] === afterLines[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        const hunkBefore = [];
+        const hunkAfter = [];
+        const start = i;
+        while (i < beforeLines.length && beforeLines[i] !== afterLines[j]) {
+            hunkBefore.push(beforeLines[i++]);
+        }
+        while (j < afterLines.length &&
+            (i >= beforeLines.length || beforeLines[i] !== afterLines[j])) {
+            hunkAfter.push(afterLines[j++]);
+        }
+        lines.push(`@@ -${start + 1},${hunkBefore.length} +${start + 1},${hunkAfter.length} @@`);
+        hunkBefore.forEach(l => lines.push(`-${l}`));
+        hunkAfter.forEach(l => lines.push(`+${l}`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Compute a proposed diff for a file-mutating tool call without writing to disk.
+ * Returns the unified diff string, or null if it cannot be computed.
+ */
+async function computeProposedDiff(toolName, args) {
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const path = args.path;
+        if (!path)
+            return null;
+        const currentContent = await readFile(path, 'utf-8').catch(() => '');
+        let proposed = currentContent;
+        if (toolName === 'edit_file') {
+            proposed = currentContent.replace(args.old_string, args.new_string);
+        }
+        else if (toolName === 'multi_edit') {
+            const edits = args.edits;
+            if (Array.isArray(edits)) {
+                for (const e of edits) {
+                    proposed = proposed.replace(e.old_string, e.new_string);
+                }
+            }
+        }
+        else if (toolName === 'write_file') {
+            proposed = args.content;
+        }
+        if (proposed === currentContent)
+            return null; // no change
+        return generateUnifiedDiff(path, currentContent, proposed);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract the file path from a tool call's parsed arguments.
+ *
+ * File-editing tools all have a `path` parameter that identifies
+ * the target file. Returns `null` for non-file tools.
+ */
+function extractFilePath(toolName, input) {
+    if (!FILE_EDITING_TOOLS.has(toolName)) {
+        return null;
+    }
+    if (input && typeof input === 'object' && 'path' in input) {
+        return input.path;
+    }
+    return null;
+}
+/**
+ * Execute a single tool call.
+ *
+ * Handles:
+ * - Looking up the tool in the registry.
+ * - Parsing the JSON arguments string from the LLM response.
+ * - Validating input against the Zod schema.
+ * - Checking permissions via the caller-supplied callback.
+ * - Invoking the tool and returning the result.
+ * - Notifying start/end callbacks.
+ * - Querying the LSP for diagnostics after file edits.
+ *
+ * @param toolCall - The raw tool call from the LLM response.
+ * @param registry - The tool registry to look up the tool definition.
+ * @param onStart - Optional callback fired before execution.
+ * @param onEnd - Optional callback fired after execution (or error).
+ * @param checkPermission - Optional permission gate.
+ * @param lspManager - Optional LSP manager for post-edit diagnostics.
+ * @returns The tool result (always succeeds; errors are captured inside the result).
+ */
+async function executeToolCall(toolCall, registry, onStart, onEnd, checkPermission, lspManager, snapshotManager, sessionId, signal, hookEngine, mode, requestFileDiff, skipRemainingDiffPrompts, rejectRemainingDiffPrompts, onChunk, toolTimeouts, infraContext) {
+    const toolName = toolCall.function.name;
+    // Parse the JSON arguments string from the LLM
+    let parsedArgs;
+    try {
+        parsedArgs = JSON.parse(toolCall.function.arguments);
+    }
+    catch {
+        const result = {
+            output: '',
+            error: `Tool '${toolName}' received malformed JSON arguments — please retry the tool call with valid JSON. Received: ${toolCall.function.arguments.slice(0, 200)}`,
+            isError: true,
+        };
+        return result;
+    }
+    const callInfo = {
+        id: toolCall.id,
+        name: toolName,
+        input: parsedArgs,
+        startTime: Date.now(),
+    };
+    // Look up the tool definition
+    const tool = registry.get(toolName);
+    if (!tool) {
+        const result = {
+            output: '',
+            error: `Unknown tool: ${toolName}`,
+            isError: true,
+        };
+        if (onEnd) {
+            onEnd(callInfo, result);
+        }
+        return result;
+    }
+    // Notify start
+    if (onStart) {
+        onStart(callInfo);
+    }
+    // Build shared hook context for PreToolUse and PostToolUse
+    const hookContext = {
+        tool: toolName,
+        input: parsedArgs && typeof parsedArgs === 'object' ? parsedArgs : {},
+        sessionId: sessionId ?? 'default',
+        agent: mode ?? 'build',
+        timestamp: new Date().toISOString(),
+    };
+    // PreToolUse hooks — may block the tool call
+    if (hookEngine) {
+        const preResult = await runPreToolHooks(hookEngine, hookContext);
+        if (!preResult.allowed) {
+            const result = {
+                output: '',
+                error: `Tool '${toolName}' blocked by hook: ${preResult.message ?? 'no reason given'}`,
+                isError: true,
+            };
+            if (onEnd) {
+                onEnd(callInfo, result);
+            }
+            return result;
+        }
+    }
+    // Permission check
+    if (checkPermission) {
+        const decision = await checkPermission(tool, parsedArgs);
+        if (decision === 'deny' || decision === 'block') {
+            const result = {
+                output: '',
+                error: decision === 'block'
+                    ? `Tool '${toolName}' is blocked by permission policy.`
+                    : `User denied permission for tool '${toolName}'.`,
+                isError: true,
+            };
+            if (onEnd) {
+                onEnd(callInfo, result);
+            }
+            return result;
+        }
+    }
+    // B1: Pre-approval diff — show proposed change before writing files
+    if (FILE_MUTATING_TOOLS.has(toolName) &&
+        requestFileDiff &&
+        !(skipRemainingDiffPrompts?.value)) {
+        // Auto-reject if 'reject-all' was previously chosen
+        if (rejectRemainingDiffPrompts?.value) {
+            const rejResult = {
+                output: 'User rejected this change (reject-all).',
+                error: undefined,
+                isError: false,
+            };
+            if (onEnd)
+                onEnd(callInfo, rejResult);
+            return rejResult;
+        }
+        const diff = await computeProposedDiff(toolName, parsedArgs);
+        if (diff) {
+            const targetPath = parsedArgs.path ?? '(file)';
+            const decision = await requestFileDiff(targetPath, toolName, diff);
+            if (decision === 'reject') {
+                const rejResult = {
+                    output: 'User rejected this change.',
+                    error: undefined,
+                    isError: false,
+                };
+                if (onEnd)
+                    onEnd(callInfo, rejResult);
+                return rejResult;
+            }
+            if (decision === 'reject-all') {
+                if (rejectRemainingDiffPrompts) {
+                    rejectRemainingDiffPrompts.value = true;
+                }
+                const rejResult = {
+                    output: 'User rejected this change (reject-all).',
+                    error: undefined,
+                    isError: false,
+                };
+                if (onEnd)
+                    onEnd(callInfo, rejResult);
+                return rejResult;
+            }
+            if (decision === 'apply-all' && skipRemainingDiffPrompts) {
+                skipRemainingDiffPrompts.value = true;
+            }
+        }
+    }
+    // Capture snapshot before file-modifying tools for undo/redo support
+    if (snapshotManager &&
+        SnapshotManager.shouldSnapshot(toolName, parsedArgs)) {
+        try {
+            await snapshotManager.captureSnapshot({
+                sessionId: sessionId || 'default',
+                messageId: toolCall.id,
+                toolCallId: toolCall.id,
+                description: `${toolName}: ${extractFilePath(toolName, parsedArgs) || '(bash command)'}`,
+            });
+        }
+        catch {
+            // Snapshot failure should never block the tool call
+        }
+    }
+    // Validate input against the tool's Zod schema and execute
+    let result;
+    try {
+        const validatedInput = tool.inputSchema.parse(parsedArgs);
+        // Thread AbortSignal into bash tool for Ctrl+C child process killing
+        if (signal && toolName === 'bash' && validatedInput && typeof validatedInput === 'object') {
+            validatedInput._signal = signal;
+        }
+        // GAP-20: Build tool execute context, including per-tool timeout from toolTimeouts map
+        // C2: Also pass infraContext from session so tools can use it as fallback
+        const toolCtx = onChunk || toolTimeouts?.[toolName] || infraContext
+            ? {
+                ...(onChunk ? { onProgress: onChunk } : {}),
+                ...(toolTimeouts?.[toolName] !== undefined ? { timeout: toolTimeouts[toolName] } : {}),
+                ...(infraContext ? { infraContext } : {}),
+            }
+            : undefined;
+        // C2: Write infra checkpoint before mutating terraform/helm operations
+        if (toolName === 'terraform' || toolName === 'helm') {
+            const _cpArgs = parsedArgs && typeof parsedArgs === 'object'
+                ? parsedArgs
+                : {};
+            const _cpAction = String(_cpArgs.action ?? '');
+            const _cpNeedCheckpoint = (toolName === 'terraform' && _cpAction === 'apply') ||
+                (toolName === 'helm' && ['install', 'upgrade', 'rollback'].includes(_cpAction));
+            if (_cpNeedCheckpoint) {
+                writeInfraCheckpoint(toolName, _cpAction, _cpArgs);
+            }
+        }
+        result = await tool.execute(validatedInput, toolCtx);
+    }
+    catch (error) {
+        result = {
+            output: '',
+            error: formatToolInputError(toolName, error),
+            isError: true,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // LSP diagnostics injection
+    // -----------------------------------------------------------------------
+    // After a successful file edit, notify the language server and collect
+    // any diagnostics (type errors, lint issues). If errors exist they are
+    // appended to the tool output so the LLM sees them on its next turn
+    // and can self-correct.
+    if (lspManager && !result.isError) {
+        const filePath = extractFilePath(toolName, parsedArgs);
+        if (filePath) {
+            try {
+                await lspManager.touchFile(filePath);
+                const diagnostics = await lspManager.getDiagnostics(filePath);
+                if (diagnostics.length > 0) {
+                    const formatted = lspManager.formatDiagnosticsForAgent(diagnostics);
+                    if (formatted) {
+                        result = {
+                            ...result,
+                            output: result.output ? `${result.output}\n\n${formatted}` : formatted,
+                        };
+                    }
+                }
+            }
+            catch (lspErr) {
+                // LSP errors should never block the agent loop.
+                // Append a note to the tool result so the LLM (and user) can see it.
+                const lspErrMsg = lspErr instanceof Error ? lspErr.message : String(lspErr);
+                result = {
+                    ...result,
+                    output: result.output
+                        ? `${result.output}\n\n[Note: LSP diagnostics unavailable: ${lspErrMsg}]`
+                        : `[Note: LSP diagnostics unavailable: ${lspErrMsg}]`,
+                };
+            }
+        }
+    }
+    // Gap 12: Mask secrets in tool output before forwarding to callbacks/history
+    if (!result.isError && result.output) {
+        result = { ...result, output: maskSecrets(result.output) };
+    }
+    // PostToolUse hooks — fire-and-forget (audit, auto-format, etc.)
+    if (hookEngine) {
+        await runPostToolHooks(hookEngine, {
+            ...hookContext,
+            result: {
+                output: result.isError ? (result.error ?? '') : result.output,
+                isError: result.isError,
+            },
+        });
+    }
+    // Notify end
+    if (onEnd) {
+        onEnd(callInfo, result);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Mode-Based Tool Filtering
+// ---------------------------------------------------------------------------
+/**
+ * Set of tool names allowed in `plan` mode.
+ *
+ * Plan mode is strictly read-only: the agent can inspect files, search
+ * the codebase, read tasks, estimate costs, and detect drift -- but it
+ * cannot write files, run commands, or mutate infrastructure.
+ */
+const PLAN_MODE_TOOLS = new Set([
+    'read_file',
+    'glob',
+    'grep',
+    'list_dir',
+    'webfetch',
+    'todo_read',
+    'todo_write',
+    'task',
+    'cost_estimate',
+    'drift_detect',
+    'cloud_discover',
+]);
+/**
+ * Set of tool names blocked in `build` mode.
+ *
+ * Build mode allows reads and writes (file edits, code generation) but
+ * blocks infrastructure-mutating operations that could affect live
+ * environments.  The permission engine provides fine-grained control on
+ * top of this coarse filter.
+ */
+const BUILD_MODE_BLOCKED_TOOLS = new Set(['terraform', 'kubectl', 'helm']);
+/**
+ * Filter tools based on the current agent mode.
+ *
+ * - **plan**: Only read-only tools + cost/drift analysis.
+ * - **build**: All tools except infrastructure mutation commands.
+ * - **deploy**: All tools are available.
+ *
+ * @param allTools - Every tool registered in the system.
+ * @param mode - The active agent mode.
+ * @returns The subset of tools available in the given mode.
+ */
+export function getToolsForMode(allTools, mode) {
+    switch (mode) {
+        case 'plan':
+            return allTools.filter(t => PLAN_MODE_TOOLS.has(t.name));
+        case 'build':
+            return allTools.filter(t => !BUILD_MODE_BLOCKED_TOOLS.has(t.name));
+        case 'deploy':
+            // All tools available
+            return allTools;
+        default: {
+            // Exhaustive check -- if a new mode is added this becomes a compile
+            // error (assuming AgentMode is a union type).
+            const _exhaustive = mode;
+            return allTools;
+        }
+    }
+}