infraweaver 0.1.0

package/src/mcp/terraform/tools/readFindings.ts

@@ -0,0 +1,138 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import { PRODUCT_NAME } from "#app/brand";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { buildConcernResult } from "#app/mcp/terraform/concernResult";
+import { docUrlsForGroup, ruleDocUrl } from "#app/mcp/terraform/decisions";
+import { parseFindingsFile } from "#app/mcp/terraform/findings";
+import {
+  type Concern,
+  SEVERITY_RANK,
+  type Severity,
+  skipResult,
+} from "#app/mcp/terraform/types";
+import { UNTRUSTED_DATA_NOTICE } from "#app/mcp/untrustedContent";
+import { log } from "#app/utils/cli";
+
+export const ReadFindingsParams = type({
+  "path?": type.string.describe(
+    "path to the Assessor's findings.json. Defaults to $INFRAWEAVER_FINDINGS_PATH, then ./findings.json in the workspace.",
+  ),
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to report (default: the run's configured threshold, else low).",
+  ),
+  "group_by?": type("'file' | 'rule'").describe(
+    "'file' (default) makes one group per file; 'rule' groups a single rule across all files into one group.",
+  ),
+});
+
+export function ReadFindingsTool(ctx: LocalToolContext) {
+  return tool({
+    name: "read_findings",
+    description:
+      "Load best-practice concerns from a terraform-reviewer (Assessor) findings.json INSTEAD of running " +
+      "the scanners. Returns the SAME { concerns, groups, summary } shape as terraform_scan, so Remediate " +
+      "consumes it identically. `human_only` findings and non-Terraform files are dropped. Concerns from " +
+      "checkov / tflint / terraform-fmt re-verify deterministically (✗→✓); findings exclusive to the reviewer " +
+      `(tfsec / infracost / llm) carry source \`reviewer\` and can't be reproduced by ${PRODUCT_NAME}'s scanners, so ` +
+      "terraform_verify_remediation will report them unresolved — rely on terraform_validate + your explanation " +
+      "for those. Returns `found: false` (never an error) when no findings.json is present.",
+    parameters: ReadFindingsParams,
+    execute: execute(async ({ path, severity_threshold, group_by }) => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      // SECURITY: confine the agent-supplied `path` to the workspace so it can't
+      // be used as an arbitrary file-read primitive. The env-var fallback is
+      // operator-controlled (not agent-controlled), so it stays unconfined.
+      const findingsPath = path
+        ? resolveWithinCwd(cwd, path)
+        : process.env.INFRAWEAVER_FINDINGS_PATH || join(cwd, "findings.json");
+      let raw: string;
+      try {
+        raw = readFileSync(findingsPath, "utf8");
+      } catch {
+        return skipResult(
+          "findings_not_found",
+          `no findings.json at ${findingsPath} (set the path arg or $INFRAWEAVER_FINDINGS_PATH)`,
+          {
+            key: "found",
+            reasonKey: "reason",
+            extra: { concerns: [], groups: [] },
+          },
+        );
+      }
+      let parsed: Concern[];
+      try {
+        // accept BOTH a terraform-reviewer findings.json AND a standard SARIF
+        // report (Trivy/Checkov/tflint -o sarif) — the dispatcher detects which.
+        parsed = parseFindingsFile(raw, cwd);
+      } catch {
+        return skipResult(
+          "findings_parse_error",
+          `could not parse findings file at ${findingsPath}`,
+          {
+            key: "found",
+            reasonKey: "reason",
+            extra: { concerns: [], groups: [] },
+          },
+        );
+      }
+
+      const configured = ctx.payload.severityThreshold as Severity | undefined;
+      const threshold: Severity = severity_threshold ?? configured ?? "low";
+      const minRank = SEVERITY_RANK[threshold];
+
+      // same concerns→result pipeline as terraform_scan (baseline, filter,
+      // suppress, group, batch, tally), so the rest of the Remediate checklist is
+      // source-agnostic. No diff-scope filter — a findings.json is already scoped.
+      const grouping = group_by ?? ctx.payload.grouping ?? "file";
+      const autonomyThreshold =
+        (ctx.payload.autonomyThreshold as Severity | undefined) ?? "high";
+      const {
+        active,
+        suppressed,
+        groups,
+        batchPlan,
+        bySeverity: by_severity,
+      } = buildConcernResult(ctx, parsed, {
+        cwd,
+        minRank,
+        grouping,
+        autonomyThreshold,
+      });
+
+      log.info(
+        `» read_findings: ${active.length} concern(s) ≥ ${threshold} from ${findingsPath}` +
+          (suppressed.length ? ` (${suppressed.length} suppressed)` : "") +
+          ` (${groups.length} ${grouping}-group(s))`,
+      );
+
+      return toolOk({
+        found: true,
+        source_file: findingsPath,
+        grouping,
+        summary: {
+          total: active.length,
+          suppressed: suppressed.length,
+          groups: groups.length,
+          by_severity,
+        },
+        groups: groups.map((g) => ({
+          ...g,
+          doc_urls: docUrlsForGroup(g, active),
+        })),
+        batch_plan: batchPlan,
+        concerns: active.map((c) => ({ ...c, doc_url: ruleDocUrl(c) })),
+        // LLM01. These concerns were parsed out of a file in the workspace —
+        // a SARIF or findings.json the repo supplied — so every `evidence`
+        // string arrives from outside with no provenance at all. Same notice as
+        // the other concern-producing tools; see `mcp/untrustedContent.ts`.
+        untrusted_data: UNTRUSTED_DATA_NOTICE,
+      });
+    }),
+  });
+}

package/src/mcp/terraform/tools/scan.ts

@@ -0,0 +1,303 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { walkTfFiles } from "#app/mcp/modules";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { buildConcernResult } from "#app/mcp/terraform/concernResult";
+import {
+  classifyRefusal,
+  clusterByLocation,
+  docUrlsForGroup,
+  type PreventiveControl,
+  preventiveControlFor,
+  ruleDocUrl,
+} from "#app/mcp/terraform/decisions";
+import {
+  EMPTY_NOISE_PROFILE,
+  explainNoiseAdjustment,
+} from "#app/mcp/terraform/noiseProfile";
+import { scoreConcern, topRisks } from "#app/mcp/terraform/risk";
+import { runScannersCached } from "#app/mcp/terraform/scannerCache";
+import { changedTerraformFiles } from "#app/mcp/terraform/scanners";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { auditNativeSkips } from "#app/mcp/terraform/suppressions";
+import {
+  type Concern,
+  SEVERITY_RANK,
+  type Severity,
+} from "#app/mcp/terraform/types";
+import { UNTRUSTED_DATA_NOTICE } from "#app/mcp/untrustedContent";
+import { log } from "#app/utils/cli";
+import { resolveModuleCredentialEnv } from "#app/utils/registryAuth";
+import { resolveToolSelection } from "#app/utils/toolSelection";
+
+export const TerraformScanParams = type({
+  "scan_scope?": type("'full' | 'diff'").describe(
+    "'full' (default) scans the whole workspace; 'diff' limits concerns to Terraform files changed vs the base branch.",
+  ),
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to report (default: low). 'info' includes everything.",
+  ),
+  "group_by?": type("'file' | 'rule'").describe(
+    "'file' (default) makes one group per file (smaller blast radius per PR). 'rule' groups a single rule's concerns across ALL files into one group — use for sweeping, low-risk rules (e.g. 'add tags everywhere') so they become one PR instead of many.",
+  ),
+  "download_external_modules?": type("boolean").describe(
+    "default false. When true, checkov resolves and scans INSIDE registry/git modules — REQUIRED for the refactor b.4 path (adopting a third-party module): scanning with it OFF would stop looking inside the adopted module and silently drop its findings (a false ✗→✓ / 'finding-laundering'). Leave off for normal Terraform-only scans (faster, offline).",
+  ),
+});
+
+export interface ScanScanners {
+  runScannersCached: typeof runScannersCached;
+  changedTerraformFiles: typeof changedTerraformFiles;
+}
+
+const realScanners: ScanScanners = { runScannersCached, changedTerraformFiles };
+
+export async function runScan(
+  ctx: LocalToolContext,
+  {
+    scan_scope,
+    severity_threshold,
+    group_by,
+    download_external_modules,
+  }: typeof TerraformScanParams.infer,
+  scanners: ScanScanners = realScanners,
+) {
+  const cwd = ctx.payload.cwd ?? process.cwd();
+  // precedence: explicit tool arg > the run's configured severity_threshold > "low"
+  const configured = ctx.payload.severityThreshold as Severity | undefined;
+  const threshold: Severity = severity_threshold ?? configured ?? "low";
+  const minRank = SEVERITY_RANK[threshold];
+  const scope = scan_scope ?? ctx.payload.scanScope ?? "full";
+
+  // the unified tool selection (licence gate + allow/deny) and the optional
+  // module credentials (git-transport + private-registry token), both derived
+  // from the run payload so the scan and its ✗→✓ verification re-scan see the
+  // identical toolchain.
+  const selection = resolveToolSelection(ctx.payload);
+  const terraformEnv = resolveModuleCredentialEnv(ctx.payload, {
+    sshKeyDir: ctx.tmpdir,
+  });
+  if (selection.unknownTokens.length > 0) {
+    log.warning(
+      `» tools_enabled: ignoring unrecognised tool(s) [${selection.unknownTokens.join(", ")}]`,
+    );
+  }
+
+  // read-only scan path: cache by Terraform-tree content hash so a repeated
+  // scan on an UNCHANGED tree is instant. Self-invalidating (any edit busts the
+  // hash). The ✗→✓ verifier below uses runScanners DIRECTLY — never the cache —
+  // so verification always re-scans fresh.
+  const outcomes = scanners.runScannersCached(cwd, {
+    selection,
+    terraformEnv,
+    downloadExternalModules: download_external_modules,
+    toolsNetwork: ctx.payload.toolsNetwork,
+  });
+  if (ctx.payload.toolsNetwork?.unknown.length) {
+    log.warning(
+      `» tools_network: ignoring unrecognised token(s) [${ctx.payload.toolsNetwork.unknown.join(", ")}]`,
+    );
+  }
+
+  // diff scope: keep only concerns in Terraform files changed vs the base.
+  let scopeNote: string | undefined;
+  let changed: Set<string> | null = null;
+  if (scope === "diff") {
+    changed = scanners.changedTerraformFiles(cwd);
+    if (changed === null) {
+      scopeNote =
+        "diff scope requested but the base branch could not be determined — scanned full instead";
+    }
+  }
+  const inScope = (c: Concern): boolean =>
+    changed === null
+      ? true
+      : changed.has(c.location.file.replace(/\\/g, "/").replace(/^\.\//, ""));
+
+  // grouping mode: by-file (default, smaller per-PR blast radius) or
+  // by-rule (one PR per rule across all files — for sweeping low-risk rules).
+  const grouping = group_by ?? ctx.payload.grouping ?? "file";
+  const autonomyThreshold =
+    (ctx.payload.autonomyThreshold as Severity | undefined) ?? "high";
+  // shared concerns→result pipeline (baseline capture, filter, suppress, group,
+  // batch, tally) — also backs read_findings so both stay source-agnostic.
+  const result = buildConcernResult(
+    ctx,
+    outcomes.flatMap((o) => o.concerns),
+    {
+      cwd,
+      minRank,
+      grouping,
+      autonomyThreshold,
+      inScope,
+    },
+  );
+  const {
+    active,
+    suppressed,
+    groups,
+    batchPlan,
+    bySeverity: by_severity,
+  } = result;
+  // the reported (post-filter) set — read at end-of-run by finalizeSuccessRun
+  // to emit the SARIF artifact + findings outputs.
+  scanSessionOf(ctx.toolState).lastScanConcerns = result.annotated;
+  // G7: the org's fleet-wide dismissal record, seeded at run start. Affects the
+  // ORDER of `top_risks` / `risk_score` only — every concern above is already
+  // final by this point, and nothing here can remove one.
+  const noiseProfile =
+    scanSessionOf(ctx.toolState).noiseProfile ?? EMPTY_NOISE_PROFILE;
+
+  // Native scanner-skip directives (#checkov:skip / #tfsec:ignore / #trivy:ignore)
+  // are honoured by their OWN scanner — so the finding never reaches Infraweaver's
+  // gate or posture. Surface the ORPHANS (a skip with no corresponding concern)
+  // so a directive that silently hides a real issue stays auditable. Matched
+  // against the raw scan set (pre-threshold) so a below-threshold concern that
+  // DID fire isn't reported as a false orphan.
+  const nativeSkipAudit = auditNativeSkips(
+    walkTfFiles(cwd),
+    outcomes.flatMap((o) => o.concerns),
+    (rel) => {
+      try {
+        return readFileSync(join(cwd, rel), "utf-8");
+      } catch {
+        return null;
+      }
+    },
+  );
+
+  // concerns different scanners flagged at the same file:line (one
+  // canonical fix); concerns whose fix needs a human decision (prefer
+  // a structured refusal); the preventive control per distinct rule.
+  const coLocated = clusterByLocation(active);
+  const refusalCandidates = active
+    .map((c) => ({ id: c.id, ...classifyRefusal(c) }))
+    .filter((r) => r.refuse)
+    .map((r) => ({ concern_id: r.id, reason: r.reason }));
+  const prevention: Record<string, PreventiveControl> = {};
+  for (const c of active) {
+    if (prevention[c.rule_id]) continue;
+    const control = preventiveControlFor(c);
+    if (control) prevention[c.rule_id] = control;
+  }
+
+  const ran = outcomes.filter((o) => o.ran).map((o) => o.source);
+  const skippedScanners = outcomes
+    .filter((o) => !o.ran)
+    .map((o) => ({ source: o.source, reason: o.skipped_reason }));
+  const partialScanners = outcomes.flatMap((o) =>
+    o.partial ? [o.partial] : [],
+  );
+
+  log.info(
+    `» terraform_scan: ${active.length} concern(s) ≥ ${threshold} from [${ran.join(", ")}] ` +
+      `(${groups.length} ${grouping}-group(s))` +
+      (suppressed.length ? ` (${suppressed.length} suppressed)` : "") +
+      (skippedScanners.length
+        ? ` (skipped: ${skippedScanners.map((s) => s.source).join(", ")})`
+        : ""),
+  );
+
+  return toolOk({
+    scanned_dir: cwd,
+    scope: changed === null ? "full" : "diff",
+    ...(scopeNote ? { scope_note: scopeNote } : {}),
+    grouping,
+    scanners_ran: ran,
+    scanners_skipped: skippedScanners,
+    // A scanner can RUN and still be partially blind (e.g. the native pack's
+    // persisted-secret rule without a provider schema). Listing that here keeps
+    // `scanners_ran` from implying full coverage; omitted entirely when empty so
+    // the common result shape is unchanged.
+    ...(partialScanners.length ? { scanners_partial: partialScanners } : {}),
+    // licence-aware tool posture: which non-permissive tools are off
+    // for want of an explicit opt-in, and which were explicitly disabled.
+    tool_selection: {
+      licence_gated: selection.gated,
+      disabled: selection.disabled,
+    },
+    summary: {
+      total: active.length,
+      suppressed: suppressed.length,
+      groups: groups.length,
+      by_severity,
+    },
+    groups: groups.map((g) => ({
+      ...g,
+      doc_urls: docUrlsForGroup(g, active),
+    })),
+    batch_plan: batchPlan,
+    // cross-tool co-location, refusal candidates, prevention.
+    co_located: coLocated,
+    refusal_candidates: refusalCandidates,
+    prevention,
+    top_risks: topRisks(active, 5, noiseProfile),
+    concerns: active.map((c) => {
+      const risk = scoreConcern(c, noiseProfile);
+      return {
+        ...c,
+        doc_url: ruleDocUrl(c),
+        risk_score: risk.score,
+        // G7: never demote silently — the reason travels with the finding.
+        ...(risk.noise
+          ? { noise_reason: explainNoiseAdjustment(risk.noise) }
+          : {}),
+      };
+    }),
+    ...(nativeSkipAudit.orphans.length
+      ? {
+          orphan_native_skips: nativeSkipAudit.orphans.map((s) => ({
+            file: s.file,
+            line: s.line,
+            tool: s.tool,
+            rule: s.rule,
+            reason: s.reason,
+            ...(s.expires ? { expires: s.expires } : {}),
+          })),
+        }
+      : {}),
+    ...(suppressed.length
+      ? {
+          suppressed: suppressed.map((c) => ({
+            id: c.id,
+            rule_id: c.rule_id,
+            severity: c.severity,
+            location: c.location,
+            suppression: c.suppression,
+          })),
+        }
+      : {}),
+    // LLM01. `evidence`, `remediation_hint` and `code_snippet` are written by
+    // third-party scanners over source authored by the party under examination,
+    // and `orphan_native_skips[].reason` / `suppression.reason` come straight
+    // out of a comment in that source (`# checkov:skip=CKV_X: <anything>`). This
+    // result is structurally identical to `ingest_external_findings`, which has
+    // carried the notice since it shipped — the asymmetry was the defect, not
+    // the presence of the field.
+    untrusted_data: UNTRUSTED_DATA_NOTICE,
+  });
+}
+
+export function TerraformScanTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_scan",
+    description:
+      "Scan the Terraform in the workspace against best practices using the deterministic check tools " +
+      "(terraform fmt, terraform validate, tflint, trivy, checkov). Returns a stable, severity-ranked " +
+      "list of `concerns` — each is one best-practice issue with a content-derived `id`, the producing " +
+      "`source`, `rule_id`, `severity`, the `location` (file + line), and a `remediation_hint`. Concerns " +
+      "are also rolled up into `groups` (one per file): different scanners flag the same defect under " +
+      "different rule ids, so remediate ONE group per PR (its `id` is the branch/PR key; its `concern_ids` " +
+      "are what the ✗→✓ re-scan must confirm cleared) rather than one PR per concern. Scanners that aren't " +
+      "installed are reported as skipped (they never fail the scan). Also returns `co_located` (concerns " +
+      "different scanners flagged at the same file:line — fix as ONE canonical change), " +
+      "`refusal_candidates` (concerns whose fix needs a human decision — prefer a structured refusal over " +
+      "guessing), and `prevention` (a CI guardrail per rule that stops it recurring).",
+    parameters: TerraformScanParams,
+    execute: execute(async (input) => runScan(ctx, input)),
+  });
+}

package/src/mcp/terraform/tools/validate.ts

@@ -0,0 +1,160 @@
+import { type } from "arktype";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { resolveRoots } from "#app/mcp/terraform/paths";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import {
+  checkArgumentsAgainstSchema,
+  collectProviderRequirements,
+  scanFmt,
+  scanTflint,
+  scanValidate,
+} from "#app/mcp/terraform/scanners";
+import { dedupe, skipped, sortConcerns } from "#app/mcp/terraform/types";
+import { UNTRUSTED_DATA_NOTICE } from "#app/mcp/untrustedContent";
+import { resolveModuleCredentialEnv } from "#app/utils/registryAuth";
+import { resolveToolSelection } from "#app/utils/toolSelection";
+
+export const TerraformValidateParams = type({
+  "paths?": type.string
+    .array()
+    .describe(
+      "optional list of file globs/paths to limit fmt+lint to; omit to check the whole workspace",
+    ),
+});
+
+export interface ValidateScanners {
+  scanFmt: typeof scanFmt;
+  scanValidate: typeof scanValidate;
+  scanTflint: typeof scanTflint;
+  collectProviderRequirements: typeof collectProviderRequirements;
+  checkArgumentsAgainstSchema: typeof checkArgumentsAgainstSchema;
+}
+
+const realScanners: ValidateScanners = {
+  scanFmt,
+  scanValidate,
+  scanTflint,
+  collectProviderRequirements,
+  checkArgumentsAgainstSchema,
+};
+
+export async function runValidate(
+  ctx: LocalToolContext,
+  scanners: ValidateScanners = realScanners,
+) {
+  const cwd = ctx.payload.cwd ?? process.cwd();
+  // honour the same licence gate + module-fetch credential as
+  // terraform_scan: tflint (MPL-2.0) runs only when opted in; validate's init
+  // gets the credential so a private cross-repo module resolves.
+  const selection = resolveToolSelection(ctx.payload);
+  const terraformEnv = resolveModuleCredentialEnv(ctx.payload, {
+    sshKeyDir: ctx.tmpdir,
+  });
+  // `terraform validate` runs per-root (multi-root aware); fmt + tflint are
+  // recursive over the whole tree.
+  const fmtOutcome = scanners.scanFmt(cwd);
+  const validateOutcome = scanners.scanValidate(cwd, terraformEnv);
+  const tflintOutcome = selection.enabled("tflint")
+    ? scanners.scanTflint(cwd)
+    : skipped(
+        "tflint",
+        selection.offReason("tflint") ?? "disabled by tools_enabled",
+      );
+
+  // PRE-EXISTING `terraform fmt` drift (captured by the pre-fix scan, before
+  // any edit) is not this run's to fix: forcing a whole-file reformat to
+  // clear style drift the file already had is exactly what bloats a scoped
+  // remediation diff. Such drift is surfaced as advisory `preexisting_fmt_drift`
+  // and kept out of the `passed` gate; only NEW drift (a file the agent's
+  // edit left unformatted) gates. With no baseline captured (validate called
+  // before any scan), fall back to gating on all drift — pre-change behaviour.
+  const baselineDrift = scanSessionOf(ctx.toolState).baselineFmtDriftFiles;
+  const isPreexisting = (c: (typeof fmtOutcome.concerns)[number]) =>
+    baselineDrift?.includes(c.location.file) ?? false;
+  const gatingFmtConcerns = fmtOutcome.concerns.filter((c) => !isPreexisting(c));
+  const preexistingFmtDrift = [
+    ...new Set(
+      fmtOutcome.concerns.filter(isPreexisting).map((c) => c.location.file),
+    ),
+  ];
+
+  const remaining = sortConcerns(
+    dedupe([
+      ...gatingFmtConcerns,
+      ...validateOutcome.concerns,
+      ...tflintOutcome.concerns,
+    ]),
+  );
+  const ran = [fmtOutcome, validateOutcome, tflintOutcome]
+    .filter((c) => c.ran)
+    .map((c) => c.source);
+  // count of roots where terraform ran but `validate -json` couldn't be
+  // parsed — a real failure, not a clean tree. We genuinely don't know if
+  // those roots are valid, so `passed` must fail closed below rather than
+  // silently treating an un-validated root as passing.
+  const unvalidatedRoots = validateOutcome.unvalidated ?? 0;
+  // surface the pinned provider majors so the fix targets the right
+  // argument schema (deterministic, read straight from required_providers).
+  const providers = scanners.collectProviderRequirements(cwd);
+  const roots = resolveRoots(cwd).map((r) => r.relDir || ".");
+  // cross-check the arguments actually written in the workspace
+  // against the INSTALLED provider's schema, so an argument that's invalid
+  // for the pinned provider major (a "correct" fix for the wrong version) is
+  // caught here, before the PR, instead of surfacing as a `plan` failure.
+  // Deterministic and degrades green (omitted) when the schema isn't
+  // available (terraform not installed / dir not init-ed).
+  const schemaCheck = scanners.checkArgumentsAgainstSchema(cwd);
+  return toolOk({
+    // `passed` stays gated on fmt + validate + tflint only — those are
+    // authoritative (fmt counts only NEW drift; see preexisting_fmt_drift).
+    // The schema cross-check is a high-signal ADVISORY (a conservative HCL
+    // parse), surfaced separately so a parser edge case can never wrongly
+    // block a valid fix. Fails closed when a root ran but couldn't be
+    // validated: an un-validated root is "unknown", not "clean".
+    passed: remaining.length === 0 && unvalidatedRoots === 0,
+    checks_ran: ran,
+    // true when ≥1 Terraform root could not be validated (terraform ran but
+    // its `-json` output was unparseable). When set, `passed` is false even
+    // with no remaining_issues — re-run after fixing the root's init/state,
+    // or inspect it by hand; do NOT treat the clean issue list as a pass.
+    validate_incomplete: unvalidatedRoots > 0,
+    remaining_issues: remaining,
+    // ADVISORY (does not gate `passed`): files that already failed
+    // `terraform fmt` at the pre-fix baseline. Reformatting them would pull
+    // unrelated lines into a scoped fix — leave them, or sweep repo-wide
+    // formatting in a separate `fix rule terraform-fmt` PR.
+    preexisting_fmt_drift: preexistingFmtDrift,
+    providers,
+    // arguments written in the workspace that are NOT in the
+    // installed provider's schema (would break `plan` on the pinned major).
+    // `schema_checked` is false when the schema was unavailable (terraform
+    // not installed / dir not init-ed) — then `unknown_arguments` is empty
+    // and you should rely on `terraform_plan` to catch a bad argument.
+    schema_checked: schemaCheck.checked,
+    unknown_arguments: schemaCheck.unknown_arguments,
+    // the Terraform roots `validate` covered (each was init+validate'd).
+    roots_validated: roots,
+    // LLM01. `remaining_issues[].evidence` is a `terraform validate` diagnostic
+    // or a tflint message, and both quote the workspace's own HCL back — an
+    // identifier, a string literal, a heredoc. Same channel as the other
+    // concern-producing tools; see `mcp/untrustedContent.ts`.
+    untrusted_data: UNTRUSTED_DATA_NOTICE,
+  });
+}
+
+export function TerraformValidateTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_validate",
+    description:
+      "Fast pre-PR gate. Runs `terraform fmt -check`, `terraform validate` (per Terraform root — " +
+      "multi-root aware, see `roots_validated`), and `tflint` over the " +
+      "workspace and returns whether the Terraform is well-formed and idiomatic. Also reports `providers` " +
+      "— the pinned provider requirements (name + source + version constraint + resolved `major`): " +
+      "honour the pinned major when writing a fix, because argument names and valid blocks differ across " +
+      "provider majors, and a 'correct' fix for the wrong major just breaks `plan`. Call this AFTER " +
+      "applying a fix and BEFORE opening a PR — never open a PR whose `terraform_validate` did not pass.",
+    parameters: TerraformValidateParams,
+    execute: execute(async () => runValidate(ctx)),
+  });
+}