@build-astron-co/nimbus 0.2.0 → 0.4.0

package/src/agent/loop.ts

@@ -17,6 +17,7 @@
  * @module agent/loop
  */
 
+import { join } from 'node:path';
 import type { LLMRouter } from '../llm/router';
 import type {
   LLMMessage,
@@ -27,6 +28,7 @@ import type {
 import {
   toOpenAITool,
   type ToolDefinition,
+  type ToolExecuteContext,
   type ToolResult,
   type ToolRegistry,
 } from '../tools/schemas/types';
@@ -36,6 +38,314 @@ import { runCompaction } from './compaction-agent';
 import type { LSPManager } from '../lsp/manager';
 import { SnapshotManager } from '../snapshots/manager';
 import { calculateCost } from '../llm/cost-calculator';
+import {
+  HookEngine,
+  runPreToolHooks,
+  runPostToolHooks,
+  type HookContext,
+} 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: string, action: string, input: Record<string, unknown>): void {
+  try {
+    const checkpointsDir = join(_cpHomedir(), '.nimbus', 'infra-checkpoints');
+    _cpMkdirSync(checkpointsDir, { recursive: true });
+    // Sanitize: remove any field that looks like a secret
+    const sanitized: Record<string, unknown> = {};
+    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 as string | undefined) ?? 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: string, errorOutput: string, nimbusInstructions?: string): string | null {
+  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: Record<string, string> = {
+    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: string, err: unknown): string {
+  if (err && typeof err === 'object' && 'issues' in err) {
+    // ZodError
+    const issues = (err as { issues: Array<{ path: (string | number)[]; message: string }> }).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: unknown): boolean {
+  if (err && typeof err === 'object') {
+    const e = err as Record<string, unknown>;
+    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: string, inputStr: string): boolean {
+  return DESTRUCTIVE_TOOL_NAMES.has(toolName) && DESTRUCTIVE_PATTERNS.test(inputStr);
+}
 
 // ---------------------------------------------------------------------------
 // Public Types
@@ -55,15 +365,47 @@ export interface AgentLoopOptions {
   /** Maximum number of LLM turns before stopping (default: 50). */
   maxTurns?: number;
 
+  /**
+   * Maximum number of tool calls allowed in a single LLM turn (G3).
+   * Prevents runaway tool call loops. Default: 20.
+   */
+  maxToolCallsPerTurn?: number;
+
+  /**
+   * Maximum number of destructive operations allowed in a single session (G3).
+   * Triggers a warning in the tool result when the threshold is reached. Default: 5.
+   */
+  maxDestructiveOpsPerSession?: number;
+
   /** Model to use (e.g. `'anthropic/claude-sonnet-4-20250514'`). */
   model?: string;
 
+  /**
+   * When true, enables automatic model routing based on task complexity (Gap 18).
+   * Simple queries → haiku, complex → opus, moderate → sonnet.
+   * Overridden if `model` is explicitly set.
+   */
+  autoRouteModel?: boolean;
+
   /** Current working directory. */
   cwd?: string;
 
   /** Custom NIMBUS.md content injected into the system prompt. */
   nimbusInstructions?: string;
 
+  /**
+   * Live infrastructure context (terraform workspace, kubectl context, etc.)
+   * discovered at startup. Injected into the system prompt (Gaps 7 & 10).
+   */
+  infraContext?: {
+    terraformWorkspace?: string;
+    kubectlContext?: string;
+    helmReleases?: string[];
+    awsAccount?: string;
+    awsRegion?: string;
+    gcpProject?: string;
+  };
+
   /** Callback for streaming text output. */
   onText?: (text: string) => void;
 
@@ -73,6 +415,12 @@ export interface AgentLoopOptions {
   /** Callback when a tool call completes. */
   onToolCallEnd?: (toolCall: ToolCallInfo, result: ToolResult) => void;
 
+  /**
+   * Callback fired for each chunk of streamed tool output (Gap 1 — live streaming).
+   * Called with the tool call ID and the chunk text.
+   */
+  onToolOutputChunk?: (toolId: string, chunk: string) => void;
+
   /**
    * Callback to check permission before tool execution.
    * If omitted, all tools are executed without prompting.
@@ -105,10 +453,63 @@ export interface AgentLoopOptions {
    *  call so users can undo/redo changes. */
   snapshotManager?: SnapshotManager;
 
+  /** Optional hook engine for PreToolUse/PostToolUse/PermissionRequest hooks.
+   *  When provided, matching hook scripts are executed around each tool call. */
+  hookEngine?: HookEngine;
+
   /** Callback fired after each LLM turn with accumulated usage and cost.
    *  Allows the TUI to update cost/token display in real-time during
    *  multi-turn agent loops, not just at the end. */
   onUsage?: (usage: AgentLoopUsage, costUSD: number) => void;
+
+  /**
+   * Optional callback to show a diff preview before file-mutating tools.
+   * If provided, the loop calls this before edit_file/multi_edit/write_file.
+   * Returning 'reject' skips the tool call; 'apply-all' disables further prompts.
+   */
+  requestFileDiff?: (
+    path: string,
+    toolName: string,
+    diff: string
+  ) => Promise<FileDiffDecision>;
+
+  /**
+   * Internal flag set by requestFileDiff 'apply-all' — skips remaining diff
+   * prompts for the current turn. Set externally by the TUI launcher.
+   */
+  skipRemainingDiffPrompts?: boolean;
+
+  /**
+   * Internal flag set by requestFileDiff 'reject-all' — auto-rejects remaining
+   * diff prompts for the current turn. Set externally by the TUI launcher.
+   */
+  rejectRemainingDiffPrompts?: boolean;
+
+  /**
+   * M1: Dry-run mode — when true, forces plan mode and prepends a hard
+   * constraint to the system prompt instructing the agent not to execute
+   * any mutating operations.
+   */
+  dryRun?: boolean;
+
+  /**
+   * G16: Maximum cost in USD per session. If the cumulative LLM cost exceeds
+   * this threshold, the loop stops and returns a budget-exceeded message.
+   */
+  costBudgetUSD?: number;
+
+  /**
+   * G21: Override the stream silence timeout in milliseconds.
+   * Defaults to config.agentTurnTimeoutSeconds * 1000, or 60_000 if not set.
+   */
+  streamSilenceTimeoutMs?: number;
+
+  /**
+   * GAP-20: Per-tool timeout overrides from NIMBUS.md Tool Timeouts section.
+   * Maps tool name to timeout in milliseconds. When set, the value is threaded
+   * into the tool's ToolExecuteContext so it can override the built-in default.
+   */
+  toolTimeouts?: Record<string, number>;
 }
 
 /** Information about a tool call in progress. */
@@ -121,6 +522,9 @@ export interface ToolCallInfo {
 
   /** Parsed input arguments. */
   input: unknown;
+
+  /** Unix timestamp (Date.now()) when the tool call started. */
+  startTime: number;
 }
 
 /**
@@ -132,6 +536,15 @@ export interface ToolCallInfo {
  */
 export type PermissionDecision = 'allow' | 'deny' | 'block';
 
+/**
+ * Result of a per-file diff approval request.
+ *
+ * - `apply`     -- apply this change.
+ * - `reject`    -- skip this change.
+ * - `apply-all` -- apply this and all remaining changes without further prompts.
+ */
+export type FileDiffDecision = 'apply' | 'reject' | 'apply-all' | 'reject-all';
+
 /** Aggregate token usage across all LLM turns. */
 export interface AgentLoopUsage {
   /** Total prompt (input) tokens consumed. */
@@ -169,6 +582,134 @@ export interface AgentLoopResult {
 /** 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: string, input: Record<string, unknown>, output: string): string | null {
+  // 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: string[] = [];
+      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<string, number>();
+
+function trackAndPersistError(toolName: string, errorHint: string, cwd: string): void {
+  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') as typeof import('node:fs');
+      const { join } = require('node:path') as typeof import('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: string, input: Record<string, unknown>): string | null {
+  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;
+}
+
+/**
+ * Session-scoped terraform plan cache.
+ * Maps workdir → { output, timestamp } so that within one agent session,
+ * a plan result can be reused for the apply call without re-running tf plan.
+ * Cache expires after 10 minutes.
+ */
+interface TerraformPlanCacheEntry {
+  output: string;
+  workdir: string;
+  timestamp: number;
+}
+
+const PLAN_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const terraformPlanCache = new Map<string, TerraformPlanCacheEntry>();
+
+/** Store a terraform plan output for a workdir. */
+function cacheTerraformPlan(workdir: string, output: string): void {
+  terraformPlanCache.set(workdir, { output, workdir, timestamp: Date.now() });
+}
+
+/** Retrieve a cached terraform plan for a workdir, or null if expired/missing. */
+function getCachedTerraformPlan(workdir: string): string | null {
+  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: ReturnType<typeof setInterval> = 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;
 
@@ -216,6 +757,7 @@ export async function runAgentLoop(
     onText,
     onToolCallStart,
     onToolCallEnd,
+    onToolOutputChunk,
     checkPermission,
     signal,
   } = options;
@@ -226,11 +768,25 @@ export async function runAgentLoop(
 
   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<undefined>(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
@@ -241,7 +797,11 @@ export async function runAgentLoop(
   // 2. Initialize conversation state
   // -----------------------------------------------------------------------
 
-  const messages: LLMMessage[] = [...history, { role: 'user', content: userMessage }];
+  // PERF-4a: Capacity-hinted pre-allocation avoids repeated V8 array reallocation
+  // as messages accumulate during a long conversation.
+  const messages: LLMMessage[] = new Array(Math.max(history.length + 1, 10));
+  messages.length = 0;
+  messages.push(...history, { role: 'user', content: userMessage });
 
   let turns = 0;
   let interrupted = false;
@@ -252,6 +812,41 @@ export async function runAgentLoop(
   };
   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<string>();
+
+  // 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<string>();
+
+  // 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: LLMMessage = { 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
   // -----------------------------------------------------------------------
@@ -266,10 +861,30 @@ export async function runAgentLoop(
     turns++;
 
     try {
-      // Build the completion request with tool definitions
+      // 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: LLMMessage[] = new Array(messages.length + 1);
+      allMessages.length = 0;
+      allMessages.push(_systemMessageObj, ...messages);
       const request: ToolCompletionRequest = {
-        messages: [{ role: 'system', content: systemPrompt }, ...messages],
-        model: model ?? DEFAULT_MODEL,
+        messages: allMessages,
+        model: effectiveModel,
         tools: llmTools,
         maxTokens: DEFAULT_MAX_TOKENS,
       };
@@ -281,22 +896,71 @@ export async function runAgentLoop(
       let responseToolCalls: ToolCall[] | undefined;
       let responseUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
 
-      for await (const chunk of router.routeStreamWithTools(request)) {
-        if (chunk.content) {
-          responseContent += chunk.content;
-          if (onText) {
-            onText(chunk.content);
+      // 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: ReturnType<typeof setTimeout> | undefined;
+        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 } as typeof request;
+          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;
+            }
           }
-        }
-        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 as Error | null;
+          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 as Error & { _nimbusNetworkError?: boolean })._nimbusNetworkError = true;
+            throw netErr;
+          }
+          throw streamErr; // non-retryable — propagate to outer catch
         }
       }
 
@@ -306,7 +970,7 @@ export async function runAgentLoop(
       totalUsage.totalTokens += responseUsage.totalTokens;
 
       // Estimate cost for this turn
-      const resolvedModel = model ?? DEFAULT_MODEL;
+      const resolvedModel = effectiveModel;
       const providerName = resolvedModel.includes('/') ? resolvedModel.split('/')[0] : 'anthropic';
       const modelName = resolvedModel.includes('/')
         ? resolvedModel.split('/').slice(1).join('/')
@@ -324,6 +988,21 @@ export async function runAgentLoop(
         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
       // -----------------------------------------------------------------
@@ -346,6 +1025,59 @@ export async function runAgentLoop(
         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: ToolCall): boolean => 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: string) => (chunk: string) => 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
@@ -354,6 +1086,59 @@ export async function runAgentLoop(
           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) as Record<string, unknown>;
+          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: string) => onToolOutputChunk(toolCall.id, chunk)
+          : undefined;
+
         const result = await executeToolCall(
           toolCall,
           toolRegistry,
@@ -363,17 +1148,286 @@ export async function runAgentLoop(
           options.lspManager,
           options.snapshotManager,
           options.sessionId,
-          signal
+          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) as Record<string, unknown>;
+            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) as Record<string, unknown>;
+            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') as typeof import('node:path');
+                const { homedir: _l6Homedir } = require('node:os') as typeof import('node:os');
+                const { mkdirSync: _l6MkdirSync, writeFileSync: _l6WriteFileSync } = require('node:fs') as typeof import('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) as Record<string, unknown>).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) as Record<string, unknown>;
+            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) as Record<string, unknown>;
+            if (tfArgs11.action === 'plan') {
+              const { parseTerraformPlanOutput, buildFileDiffBatchFromPlan } = await import('./deploy-preview');
+              const changes = parseTerraformPlanOutput(toolContent);
+              if (changes.length > 0) {
+                const batchFiles = buildFileDiffBatchFromPlan({ changes } as import('./deploy-preview').DeployPreview);
+                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) as { path?: string; file_path?: string };
+          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) as { valid: boolean; diagnostics?: Array<{ severity: string; summary: string; detail: string }> };
+              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) {
-          const truncatedLength = toolContent.length;
-          toolContent = `${toolContent.slice(0, MAX_TOOL_OUTPUT_CHARS)}\n\n... [Output truncated: ${truncatedLength.toLocaleString()} chars total, showing first ${MAX_TOOL_OUTPUT_CHARS.toLocaleString()}]`;
+          let head: string;
+          let tail: string;
+          let omitted: number;
+          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) as Record<string, unknown>;
+              return tfArgs.action === 'plan';
+            } catch { return false; }
+          })();
+
+          if (isTerraformPlan) {
+            // Keep all diff lines (create/update/destroy/replace) and the plan summary
+            const diffLines: string[] = [];
+            const contextLines: string[] = [];
+            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({
@@ -403,10 +1457,15 @@ export async function runAgentLoop(
         );
         if (options.contextManager.shouldCompact(systemPrompt, messages, toolTokens)) {
           try {
-            const compactResult = await runCompaction(messages, options.contextManager, { router });
+            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);
             }
@@ -425,12 +1484,14 @@ export async function runAgentLoop(
     } catch (error: unknown) {
       // LLM API error — report to the caller and break
       const msg = error instanceof Error ? error.message : String(error);
-      if (onText) {
+      // G24: Network errors already printed via onText above — skip duplicate output
+      const isNetworkErr = (error instanceof Error) && (error as Error & { _nimbusNetworkError?: boolean })._nimbusNetworkError;
+      if (!isNetworkErr && onText) {
         onText(`\n[Error: ${msg}]\n`);
       }
       messages.push({
         role: 'assistant',
-        content: `I encountered an error: ${msg}`,
+        content: isNetworkErr ? msg : `I encountered an error: ${msg}`,
       });
       break;
     }
@@ -446,6 +1507,33 @@ export async function runAgentLoop(
     }
   }
 
+  // GAP-19: Session summary after multi-step deploy
+  if (options.mode === 'deploy' && options.onText) {
+    // Collect tool calls from messages
+    const allToolCalls: Array<{ name: string; input: Record<string, unknown> }> = [];
+    for (const msg of messages) {
+      if (msg.role === 'assistant' && Array.isArray((msg as {toolCalls?: unknown[]}).toolCalls)) {
+        for (const tc of (msg as {toolCalls: Array<{function: {name: string; arguments: string}}>}).toolCalls) {
+          try {
+            allToolCalls.push({ name: tc.function.name, input: JSON.parse(tc.function.arguments) as Record<string, unknown> });
+          } 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: string[] = ['---', '**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,
@@ -462,6 +1550,79 @@ export async function runAgentLoop(
 /** 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: string, before: string, after: string): string {
+  const beforeLines = before.split('\n');
+  const afterLines = after.split('\n');
+  const lines: string[] = [`--- 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: string[] = [];
+    const hunkAfter: string[] = [];
+    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: string,
+  args: Record<string, unknown>
+): Promise<string | null> {
+  try {
+    const { readFile } = await import('node:fs/promises');
+    const path = args.path as string;
+    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 as string, args.new_string as string);
+    } else if (toolName === 'multi_edit') {
+      const edits = args.edits as Array<{ old_string: string; new_string: string }>;
+      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 as string;
+    }
+    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.
  *
@@ -507,7 +1668,15 @@ async function executeToolCall(
   lspManager?: LSPManager,
   snapshotManager?: SnapshotManager,
   sessionId?: string,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  hookEngine?: HookEngine,
+  mode?: AgentMode,
+  requestFileDiff?: (path: string, toolName: string, diff: string) => Promise<FileDiffDecision>,
+  skipRemainingDiffPrompts?: { value: boolean },
+  rejectRemainingDiffPrompts?: { value: boolean },
+  onChunk?: (chunk: string) => void,
+  toolTimeouts?: Record<string, number>,
+  infraContext?: import('../sessions/manager').SessionInfraContext
 ): Promise<ToolResult> {
   const toolName = toolCall.function.name;
 
@@ -518,7 +1687,7 @@ async function executeToolCall(
   } catch {
     const result: ToolResult = {
       output: '',
-      error: `Failed to parse tool arguments as JSON for '${toolName}': ${toolCall.function.arguments}`,
+      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;
@@ -528,6 +1697,7 @@ async function executeToolCall(
     id: toolCall.id,
     name: toolName,
     input: parsedArgs,
+    startTime: Date.now(),
   };
 
   // Look up the tool definition
@@ -549,6 +1719,31 @@ async function executeToolCall(
     onStart(callInfo);
   }
 
+  // Build shared hook context for PreToolUse and PostToolUse
+  const hookContext: HookContext = {
+    tool: toolName,
+    input: parsedArgs && typeof parsedArgs === 'object' ? (parsedArgs as Record<string, unknown>) : {},
+    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: ToolResult = {
+        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);
@@ -568,6 +1763,55 @@ async function executeToolCall(
     }
   }
 
+  // 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: ToolResult = {
+        output: 'User rejected this change (reject-all).',
+        error: undefined,
+        isError: false,
+      };
+      if (onEnd) onEnd(callInfo, rejResult);
+      return rejResult;
+    }
+
+    const diff = await computeProposedDiff(toolName, parsedArgs as Record<string, unknown>);
+    if (diff) {
+      const targetPath =
+        (parsedArgs as Record<string, unknown>).path as string | undefined ?? '(file)';
+      const decision = await requestFileDiff(targetPath, toolName, diff);
+      if (decision === 'reject') {
+        const rejResult: ToolResult = {
+          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: ToolResult = {
+          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 &&
@@ -595,12 +1839,33 @@ async function executeToolCall(
       (validatedInput as Record<string, unknown>)._signal = signal;
     }
 
-    result = await tool.execute(validatedInput);
+    // 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: ToolExecuteContext | undefined = 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 as Record<string, unknown>)
+        : {};
+      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: unknown) {
-    const msg = error instanceof Error ? error.message : String(error);
     result = {
       output: '',
-      error: `Tool execution failed: ${msg}`,
+      error: formatToolInputError(toolName, error),
       isError: true,
     };
   }
@@ -641,6 +1906,22 @@ async function executeToolCall(
     }
   }
 
+  // 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);