security-mcp 1.1.0 → 1.1.2

package/dist/gate/checks/scanners.js

@@ -9,6 +9,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { tmpdir } from "node:os";
 import { z } from "zod";
+import { sanitizeErrorMessage } from "../result.js";
 const execFileAsync = promisify(execFile);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, "../../..");
@@ -29,7 +30,12 @@ const ScannerConfigSchema = z.object({
 async function loadScannerConfig() {
     const overridePath = process.env["SECURITY_GATE_SCANNERS"];
     if (overridePath) {
-        const raw = await readFile(join(process.cwd(), overridePath), "utf-8");
+        // CWE-22: resolve to absolute path and ensure it stays within cwd
+        const resolved = resolve(process.cwd(), overridePath);
+        if (!resolved.startsWith(process.cwd() + "/") && resolved !== process.cwd()) {
+            throw new Error(`SECURITY_GATE_SCANNERS path '${overridePath}' escapes the project directory`);
+        }
+        const raw = await readFile(resolved, "utf-8");
         return ScannerConfigSchema.parse(JSON.parse(raw));
     }
     try {
@@ -433,7 +439,7 @@ export async function runScanners(opts) {
             allFindings.push(...res.value);
         }
         else {
-            console.warn(`[scanners] Scanner ${taskId} failed: ${String(res.reason)}`);
+            console.warn(`[scanners] Scanner ${taskId} failed: ${sanitizeErrorMessage(String(res.reason))}`);
             allFindings.push({
                 id: "SCANNER_EXECUTION_ERROR",
                 title: `Security scanner '${taskId}' failed unexpectedly`,

package/dist/gate/diff.js

@@ -1,6 +1,8 @@
 import { execa } from "execa";
 // Allowlist for git ref strings. Blocks option injection (e.g. --upload-pack=…)
 // and git pathspec magic characters. CWE-88 / MITRE ATT&CK T1059.
+// Note: ~ and ^ are intentionally included — they are safe because { and } are NOT
+// in the allowlist, which blocks ^{} tag-dereferencing and $(...) command substitution.
 const SAFE_REF_RE = /^[a-zA-Z0-9_./~^-]+$/;
 function validateRef(name, value) {
     if (!value || !SAFE_REF_RE.test(value)) {

package/dist/gate/exceptions.js

@@ -22,7 +22,12 @@ const ExceptionFileSchema = z.object({
 async function readExceptionsJson() {
     const overridePath = process.env["SECURITY_GATE_EXCEPTIONS"];
     if (overridePath) {
-        return await readFile(join(process.cwd(), overridePath), "utf-8");
+        // CWE-22: ensure path stays within the project directory
+        const resolved = resolve(process.cwd(), overridePath);
+        if (!resolved.startsWith(process.cwd() + "/") && resolved !== process.cwd()) {
+            throw new Error(`SECURITY_GATE_EXCEPTIONS path '${overridePath}' escapes the project directory`);
+        }
+        return await readFile(resolved, "utf-8");
     }
     try {
         return await readFile(join(process.cwd(), ".mcp", "exceptions", "security-exceptions.json"), "utf-8");

package/dist/gate/policy.js

@@ -25,6 +25,10 @@ import { runSbomChecks } from "./checks/sbom.js";
 import { runPlaybookChecks } from "./checks/playbook.js";
 import { runAiRedteamChecks } from "./checks/ai-redteam.js";
 import { runRuntimeChecks } from "./checks/runtime.js";
+import { runCiPipelineChecks } from "./checks/ci-pipeline.js";
+import { runNucleiChecks } from "./checks/nuclei.js";
+import { getCommitHash, loadBaseline, saveBaseline, compareBaseline } from "./baseline.js";
+import { randomUUID } from "node:crypto";
 const PolicySchema = z.object({
     name: z.string(),
     version: z.string(),
@@ -107,8 +111,22 @@ function classifyChangeType(files) {
         return "config";
     return "general";
 }
+const SLA_MAP = {
+    CRITICAL: "24h",
+    HIGH: "7d",
+    MEDIUM: "30d",
+    LOW: "90d"
+};
+function assignRiskSlas(findings) {
+    const now = new Date().toISOString();
+    return findings.map((f) => ({ ...f, sla: SLA_MAP[f.severity], slaAssignedAt: now }));
+}
 export async function runPrGate(opts) {
-    const policy = await loadPolicy(opts.policyPath);
+    const [policy, commitHash, previousBaseline] = await Promise.all([
+        loadPolicy(opts.policyPath),
+        getCommitHash(),
+        loadBaseline()
+    ]);
     const mode = opts.mode ?? "recent_changes";
     const targets = normalizeTargets(opts.targets);
     const changedFiles = await resolveScopedFiles({
@@ -150,7 +168,9 @@ export async function runPrGate(opts) {
             runSbomChecks({ changedFiles, targets }),
             runPlaybookChecks({ changedFiles, surfaces }),
             surfaces.ai ? runAiRedteamChecks({ changedFiles }) : Promise.resolve([]),
-            process.env["SECURITY_STAGING_URL"] ? runRuntimeChecks({ targets, changedFiles }) : Promise.resolve([])
+            process.env["SECURITY_STAGING_URL"] ? runRuntimeChecks({ targets, changedFiles }) : Promise.resolve([]),
+            runCiPipelineChecks({ changedFiles }),
+            process.env["SECURITY_STAGING_URL"] ? runNucleiChecks({ changedFiles }) : Promise.resolve([])
         ]);
         rawFindings = [];
         for (const result of checkResults) {
@@ -162,6 +182,7 @@ export async function runPrGate(opts) {
             }
         }
     }
+    rawFindings = assignRiskSlas(rawFindings);
     const toolingCoverage = catalog.controls
         .filter((control) => control.automation === "tooling" && controlApplies(control, surfaces))
         .map((control) => {
@@ -213,10 +234,28 @@ export async function runPrGate(opts) {
         : Math.round(((scannerReadiness.configured.length - scannerReadiness.missing.length) / scannerReadiness.configured.length) * 100);
     const confidenceScore = Math.max(0, Math.min(100, Math.round((automatedCoverage * 0.7) + (scannerScore * 0.3))));
     const missingControls = relevantControls.filter((control) => control.status === "missing").length;
+    // Baseline regression detection: compare current run against previous baseline
+    let baselineDiff;
+    if (previousBaseline) {
+        baselineDiff = compareBaseline({ findings: effectiveFindings, controlCoverage: controlCoverageWithExceptions, confidence: { automatedCoverage, score: 0, missingControls: 0, scannerReadiness: 0, summary: "" }, status: "PASS", policyVersion: "", evaluatedAt: "", scope: { changedFiles, surfaces } }, previousBaseline);
+        if (baselineDiff.regressions.length > 0) {
+            const regressionFindings = baselineDiff.regressions.map((r) => ({
+                id: "BASELINE_REGRESSION",
+                title: `Security regression: control "${r.controlId}" was previously satisfied but is now missing`,
+                severity: "HIGH",
+                evidence: [`Control ${r.controlId}: "satisfied" → "missing" since last gate run`],
+                requiredActions: [
+                    `Restore control "${r.controlId}" to a satisfied state.`,
+                    "Investigate what change caused this regression and revert or remediate."
+                ]
+            }));
+            effectiveFindings = [...regressionFindings, ...effectiveFindings];
+        }
+    }
     const status = effectiveFindings.some((f) => f.severity === "HIGH" || f.severity === "CRITICAL")
         ? "FAIL"
         : "PASS";
-    return {
+    const result = {
         status,
         policyVersion: policy.version,
         evaluatedAt: new Date().toISOString(),
@@ -235,6 +274,10 @@ export async function runPrGate(opts) {
             riskAcceptedControls,
             scannerReadiness: scannerScore,
             summary: `Automated coverage ${automatedCoverage}%, scanner readiness ${scannerScore}%, missing controls ${missingControls}, risk-accepted controls ${riskAcceptedControls}. Change type: ${changeType}.`
-        }
+        },
+        baselineDiff
     };
+    // Persist as new baseline — fire-and-forget, never blocks the gate result
+    saveBaseline(randomUUID(), result, commitHash).catch(() => { });
+    return result;
 }

package/dist/gate/result.js

@@ -1 +1,7 @@
-export {};
+// CWE-209: strip absolute file system paths from error messages before logging
+// to prevent leaking internal directory structure to observers of stderr/stdout.
+export function sanitizeErrorMessage(msg) {
+    return msg
+        .replace(/\/[^\s:'"]+/g, "[path]") // Unix: /foo/bar/baz
+        .replace(/[A-Za-z]:\\[^\s:'"]+/g, "[path]"); // Windows: C:\Users\...
+}

package/dist/mcp/audit-chain.js

@@ -0,0 +1,253 @@
+/**
+ * Audit Chain — per-agent attestation with SHA-256 hash chaining.
+ *
+ * Each agent that completes work on an agent run produces an AttestationRecord
+ * that:
+ *   1. Hashes the agent's findings output
+ *   2. Includes the hash of the previous link in the chain (parent hash)
+ *   3. Signs both together to produce a chain hash
+ *
+ * This creates a tamper-evident audit log: if any prior attestation is modified,
+ * all subsequent chain hashes become invalid and `verifyChain()` will detect it.
+ *
+ * Chain is persisted to .mcp/agent-runs/{agentRunId}/attestation-chain.json.
+ *
+ * The genesis block (link 0) contains only the agentRunId and a timestamp —
+ * its parent hash is all-zeros.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const AGENT_RUNS_DIR = join(".mcp", "agent-runs");
+const GENESIS_PARENT_HASH = "0".repeat(64);
+// CWE-22: agentRunId used as a path component — must be the 32-char hex digest
+// produced by orchestration.createAgentRun, or a UUID (36-char with hyphens).
+const SAFE_AGENT_RUN_ID_RE = /^[0-9a-f]{32}$|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function validateAgentRunId(agentRunId) {
+    if (!agentRunId || !SAFE_AGENT_RUN_ID_RE.test(agentRunId)) {
+        throw new Error(`Invalid agentRunId "${agentRunId}" — must be a 32-char hex digest or UUID`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Hash helpers
+// ---------------------------------------------------------------------------
+function sha256(data) {
+    return createHash("sha256").update(data, "utf-8").digest("hex");
+}
+function hashFindings(findings) {
+    return sha256(JSON.stringify(findings));
+}
+function computeChainHash(record) {
+    const payload = [
+        record.agentRunId,
+        record.agentName,
+        record.completedAt,
+        record.findingsHash,
+        record.parentHash
+    ].join("|");
+    return sha256(payload);
+}
+// ---------------------------------------------------------------------------
+// Storage helpers
+// ---------------------------------------------------------------------------
+async function ensureRunDir(agentRunId) {
+    const dir = join(AGENT_RUNS_DIR, agentRunId);
+    await mkdir(dir, { recursive: true });
+}
+function chainPath(agentRunId) {
+    return join(AGENT_RUNS_DIR, agentRunId, "attestation-chain.json");
+}
+async function loadChain(agentRunId) {
+    validateAgentRunId(agentRunId); // CWE-22: guard before any path operation
+    try {
+        const raw = await readFile(chainPath(agentRunId), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        const now = new Date().toISOString();
+        return { agentRunId, createdAt: now, updatedAt: now, links: [] };
+    }
+}
+async function saveChain(chain) {
+    await ensureRunDir(chain.agentRunId);
+    chain.updatedAt = new Date().toISOString();
+    await writeFile(chainPath(chain.agentRunId), JSON.stringify(chain, null, 2) + "\n", "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Initialise the attestation chain for a new agent run.
+ * Creates the genesis block (link 0) with all-zero parent hash.
+ * Idempotent — returns the existing chain if already initialised.
+ */
+export async function initChain(agentRunId) {
+    const chain = await loadChain(agentRunId);
+    if (chain.links.length > 0)
+        return chain; // already initialised
+    const completedAt = new Date().toISOString();
+    const genesis = {
+        link: 0,
+        agentRunId,
+        agentName: "genesis",
+        completedAt,
+        findingsHash: sha256("genesis:" + agentRunId),
+        parentHash: GENESIS_PARENT_HASH,
+        findingCount: 0,
+        criticalCount: 0,
+        highCount: 0
+    };
+    const record = {
+        ...genesis,
+        chainHash: computeChainHash(genesis)
+    };
+    chain.links.push(record);
+    await saveChain(chain);
+    return chain;
+}
+/**
+ * Append a new attestation to the chain for the named agent.
+ * The parent hash is taken from the last link already in the chain.
+ * If the chain hasn't been initialised, `initChain` is called first.
+ */
+export async function attestAgent(params) {
+    const chain = await loadChain(params.agentRunId);
+    if (chain.links.length === 0) {
+        await initChain(params.agentRunId);
+        return attestAgent(params); // retry after init
+    }
+    // length === 0 is already guarded above; this satisfies TypeScript narrowing
+    const parent = chain.links.at(-1) ?? chain.links[0];
+    const completedAt = new Date().toISOString();
+    const partial = {
+        link: parent.link + 1,
+        agentRunId: params.agentRunId,
+        agentName: params.agentName,
+        completedAt,
+        findingsHash: hashFindings(params.findings),
+        parentHash: parent.chainHash,
+        findingCount: params.findings.length,
+        criticalCount: params.findings.filter((f) => f.severity === "CRITICAL").length,
+        highCount: params.findings.filter((f) => f.severity === "HIGH").length
+    };
+    const record = {
+        ...partial,
+        chainHash: computeChainHash(partial)
+    };
+    chain.links.push(record);
+    await saveChain(chain);
+    return record;
+}
+/**
+ * Verify the integrity of the entire attestation chain for an agent run.
+ * Recomputes every chain hash from scratch and checks parent linkage.
+ * Returns `valid: true` only if every link is intact.
+ */
+export async function verifyChain(agentRunId) {
+    const chain = await loadChain(agentRunId);
+    const verifiedAt = new Date().toISOString();
+    if (chain.links.length === 0) {
+        return {
+            agentRunId,
+            valid: false,
+            linkCount: 0,
+            verifiedAt,
+            broken: {
+                linkIndex: 0,
+                agentName: "genesis",
+                reason: "Chain is empty — no genesis block found."
+            }
+        };
+    }
+    // Verify genesis parent hash
+    if (chain.links[0].parentHash !== GENESIS_PARENT_HASH) {
+        return {
+            agentRunId,
+            valid: false,
+            linkCount: chain.links.length,
+            verifiedAt,
+            broken: {
+                linkIndex: 0,
+                agentName: chain.links[0].agentName,
+                reason: "Genesis block has non-zero parent hash — chain has been tampered."
+            }
+        };
+    }
+    for (let i = 0; i < chain.links.length; i++) {
+        const link = chain.links[i];
+        // Recompute chain hash
+        const { chainHash: _stored, ...rest } = link;
+        const recomputed = computeChainHash(rest);
+        if (recomputed !== link.chainHash) {
+            return {
+                agentRunId,
+                valid: false,
+                linkCount: chain.links.length,
+                verifiedAt,
+                broken: {
+                    linkIndex: i,
+                    agentName: link.agentName,
+                    reason: `Chain hash mismatch at link ${i} — findings or metadata may have been modified.`
+                }
+            };
+        }
+        // Verify parent linkage
+        if (i > 0 && link.parentHash !== chain.links[i - 1].chainHash) {
+            return {
+                agentRunId,
+                valid: false,
+                linkCount: chain.links.length,
+                verifiedAt,
+                broken: {
+                    linkIndex: i,
+                    agentName: link.agentName,
+                    reason: `Parent hash at link ${i} does not match chain hash of link ${i - 1} — chain is broken.`
+                }
+            };
+        }
+    }
+    return {
+        agentRunId,
+        valid: true,
+        linkCount: chain.links.length,
+        verifiedAt,
+        broken: null
+    };
+}
+/**
+ * Read the attestation chain for inspection (without verification).
+ */
+export async function getChain(agentRunId) {
+    return loadChain(agentRunId);
+}
+// ---------------------------------------------------------------------------
+// Zod schemas for MCP tool params
+// ---------------------------------------------------------------------------
+export const InitChainParams = {
+    agentRunId: z.string().min(1).max(128).describe("Agent run ID to initialise the attestation chain for.")
+};
+export const InitChainSchema = z.object(InitChainParams);
+export const AttestAgentParams = {
+    agentRunId: z.string().min(1).max(128).describe("Agent run ID this attestation belongs to."),
+    agentName: z.string().min(1).max(128).describe("Name of the agent completing its work."),
+    findings: z.array(z.object({
+        id: z.string(),
+        title: z.string(),
+        severity: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]),
+        remediated: z.boolean(),
+        requiredActions: z.array(z.string())
+    }).passthrough()).describe("Agent findings to attest. Must match AgentFinding shape.")
+};
+export const AttestAgentSchema = z.object(AttestAgentParams);
+export const VerifyChainParams = {
+    agentRunId: z.string().min(1).max(128).describe("Agent run ID whose chain should be verified.")
+};
+export const VerifyChainSchema = z.object(VerifyChainParams);
+export const GetChainParams = {
+    agentRunId: z.string().min(1).max(128).describe("Agent run ID to retrieve the attestation chain for.")
+};
+export const GetChainSchema = z.object(GetChainParams);

package/dist/mcp/learning.js

@@ -0,0 +1,228 @@
+/**
+ * Learning Engine — pattern memory and agent routing.
+ *
+ * Tracks which agents resolve which finding types most successfully.
+ * Routes future findings to the highest-performing agent automatically.
+ * Persists to .mcp/memory/patterns.json (per-project, gitignore-safe).
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MEMORY_DIR = join(".mcp", "memory");
+const PATTERNS_FILE = join(MEMORY_DIR, "patterns.json");
+const MIN_SAMPLE_SIZE = 3; // need ≥3 outcomes before routing is trusted
+const HIGH_CONFIDENCE = 0.85; // route automatically above this success rate
+const LOW_CONFIDENCE = 0.40; // escalate below this success rate
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+export const OutcomeSchema = z.object({
+    findingId: z.string().min(1).max(128).regex(/^[A-Z][A-Z0-9_]{0,127}$/, "findingId must be SCREAMING_SNAKE_CASE"),
+    agentName: z.string().min(1).max(128),
+    resolved: z.boolean(),
+    falsePositive: z.boolean().default(false),
+    remediationTemplate: z.string().max(512).optional(),
+    durationMs: z.number().int().min(0).optional()
+});
+// ---------------------------------------------------------------------------
+// Storage helpers
+// ---------------------------------------------------------------------------
+async function ensureMemoryDir() {
+    await mkdir(MEMORY_DIR, { recursive: true });
+}
+async function loadStore() {
+    try {
+        const raw = await readFile(PATTERNS_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { version: 1, updatedAt: new Date().toISOString(), patterns: {} };
+    }
+}
+async function saveStore(store) {
+    await ensureMemoryDir();
+    store.updatedAt = new Date().toISOString();
+    await writeFile(PATTERNS_FILE, JSON.stringify(store, null, 2) + "\n", "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Record the outcome of an agent resolving (or failing to resolve) a finding.
+ * Called after every agent completes work on a specific finding.
+ */
+export async function recordOutcome(outcome) {
+    const validated = OutcomeSchema.parse(outcome);
+    const store = await loadStore();
+    const existing = store.patterns[validated.findingId] ?? {
+        findingId: validated.findingId,
+        bestAgent: validated.agentName,
+        sampleSize: 0,
+        successRate: 0,
+        falsePositiveRate: 0,
+        avgDurationMs: 0,
+        remediationTemplate: "",
+        lastSeen: new Date().toISOString(),
+        agentStats: {}
+    };
+    // Update agent-specific stats
+    const agentStat = existing.agentStats[validated.agentName] ?? {
+        attempts: 0,
+        successes: 0,
+        falsePositives: 0,
+        totalDurationMs: 0,
+        remediationTemplates: []
+    };
+    agentStat.attempts += 1;
+    if (validated.resolved && !validated.falsePositive)
+        agentStat.successes += 1;
+    if (validated.falsePositive)
+        agentStat.falsePositives += 1;
+    if (validated.durationMs)
+        agentStat.totalDurationMs += validated.durationMs;
+    if (validated.remediationTemplate && !agentStat.remediationTemplates.includes(validated.remediationTemplate)) {
+        agentStat.remediationTemplates.push(validated.remediationTemplate);
+    }
+    existing.agentStats[validated.agentName] = agentStat;
+    // Recompute aggregate stats
+    let totalAttempts = 0;
+    let totalSuccesses = 0;
+    let totalFalsePositives = 0;
+    let totalDuration = 0;
+    let bestAgentName = validated.agentName;
+    let bestRate = 0;
+    for (const [name, stat] of Object.entries(existing.agentStats)) {
+        totalAttempts += stat.attempts;
+        totalSuccesses += stat.successes;
+        totalFalsePositives += stat.falsePositives;
+        totalDuration += stat.totalDurationMs;
+        const rate = stat.attempts > 0 ? stat.successes / stat.attempts : 0;
+        if (rate > bestRate || (rate === bestRate && stat.attempts > (existing.agentStats[bestAgentName]?.attempts ?? 0))) {
+            bestRate = rate;
+            bestAgentName = name;
+        }
+    }
+    // Best remediation template comes from the best agent
+    const bestStat = existing.agentStats[bestAgentName];
+    const template = bestStat?.remediationTemplates[0] ?? existing.remediationTemplate;
+    const updated = {
+        ...existing,
+        bestAgent: bestAgentName,
+        sampleSize: totalAttempts,
+        successRate: totalAttempts > 0 ? totalSuccesses / totalAttempts : 0,
+        falsePositiveRate: totalAttempts > 0 ? totalFalsePositives / totalAttempts : 0,
+        avgDurationMs: totalAttempts > 0 ? Math.round(totalDuration / totalAttempts) : 0,
+        remediationTemplate: template,
+        lastSeen: new Date().toISOString(),
+        agentStats: existing.agentStats
+    };
+    store.patterns[validated.findingId] = updated;
+    await saveStore(store);
+    return { recorded: true, pattern: updated };
+}
+/**
+ * Get the routing recommendation for a finding type.
+ * Returns which agent to use, or signals escalation if confidence is low.
+ */
+export async function getRouting(findingId) {
+    if (!findingId || !/^[A-Z][A-Z0-9_]{0,127}$/.test(findingId)) {
+        return {
+            findingId,
+            recommendation: "insufficient_data",
+            bestAgent: null,
+            successRate: null,
+            sampleSize: 0,
+            reason: "Invalid findingId format — no routing data available."
+        };
+    }
+    const store = await loadStore();
+    const pattern = store.patterns[findingId];
+    if (!pattern || pattern.sampleSize < MIN_SAMPLE_SIZE) {
+        return {
+            findingId,
+            recommendation: "insufficient_data",
+            bestAgent: null,
+            successRate: null,
+            sampleSize: pattern?.sampleSize ?? 0,
+            reason: `Fewer than ${MIN_SAMPLE_SIZE} outcomes recorded — using standard agent selection.`
+        };
+    }
+    if (pattern.successRate >= HIGH_CONFIDENCE) {
+        return {
+            findingId,
+            recommendation: "route",
+            bestAgent: pattern.bestAgent,
+            successRate: pattern.successRate,
+            sampleSize: pattern.sampleSize,
+            reason: `${Math.round(pattern.successRate * 100)}% success rate across ${pattern.sampleSize} runs — routing to ${pattern.bestAgent}.`
+        };
+    }
+    if (pattern.successRate < LOW_CONFIDENCE) {
+        return {
+            findingId,
+            recommendation: "escalate",
+            bestAgent: pattern.bestAgent,
+            successRate: pattern.successRate,
+            sampleSize: pattern.sampleSize,
+            reason: `Low success rate (${Math.round(pattern.successRate * 100)}%) — escalate to senior-security-engineer or manual review.`
+        };
+    }
+    return {
+        findingId,
+        recommendation: "route",
+        bestAgent: pattern.bestAgent,
+        successRate: pattern.successRate,
+        sampleSize: pattern.sampleSize,
+        reason: `Moderate confidence (${Math.round(pattern.successRate * 100)}%) — routing to ${pattern.bestAgent} with monitoring.`
+    };
+}
+/**
+ * Generate a full report of learned patterns and agent performance.
+ */
+export async function getPatternReport() {
+    const store = await loadStore();
+    const patterns = Object.values(store.patterns);
+    const agentMap = new Map();
+    for (const p of patterns) {
+        const existing = agentMap.get(p.bestAgent) ?? { count: 0, totalRate: 0 };
+        agentMap.set(p.bestAgent, {
+            count: existing.count + 1,
+            totalRate: existing.totalRate + p.successRate
+        });
+    }
+    const topAgents = Array.from(agentMap.entries())
+        .map(([agentName, stats]) => ({
+        agentName,
+        findingsCovered: stats.count,
+        avgSuccessRate: stats.count > 0 ? stats.totalRate / stats.count : 0
+    }))
+        .sort((a, b) => b.findingsCovered - a.findingsCovered)
+        .slice(0, 10);
+    return {
+        totalPatterns: patterns.length,
+        highConfidence: patterns.filter((p) => p.successRate >= HIGH_CONFIDENCE && p.sampleSize >= MIN_SAMPLE_SIZE).length,
+        lowConfidence: patterns.filter((p) => p.successRate < LOW_CONFIDENCE && p.sampleSize >= MIN_SAMPLE_SIZE).length,
+        insufficientData: patterns.filter((p) => p.sampleSize < MIN_SAMPLE_SIZE).length,
+        topAgents,
+        patterns: patterns.sort((a, b) => b.sampleSize - a.sampleSize)
+    };
+}
+// ---------------------------------------------------------------------------
+// Zod schemas for MCP tool params
+// ---------------------------------------------------------------------------
+export const RecordOutcomeParams = {
+    findingId: z.string().min(1).max(128).describe("Finding ID in SCREAMING_SNAKE_CASE (e.g. CI_UNPINNED_ACTION)."),
+    agentName: z.string().min(1).max(128).describe("Name of the agent that worked on this finding."),
+    resolved: z.boolean().describe("True if the finding was successfully remediated."),
+    falsePositive: z.boolean().optional().describe("True if this was a false positive. Default false."),
+    remediationTemplate: z.string().max(512).optional().describe("One-line description of what was done to fix it."),
+    durationMs: z.number().int().min(0).optional().describe("Time taken to resolve in milliseconds.")
+};
+export const RecordOutcomeSchema = z.object(RecordOutcomeParams);
+export const GetRoutingParams = {
+    findingId: z.string().min(1).max(128).describe("Finding ID to look up routing recommendation for.")
+};
+export const GetRoutingSchema = z.object(GetRoutingParams);