avorelo 0.1.0

package/scripts/lib/agent-security/index.js

@@ -0,0 +1,3342 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { safeReadJson, safeWriteJson, nowIso } = require("../fsx");
+const { buildActionId, normalizeAgentSecurityAction, evaluateAgentSecurityAction } = require("./action-evaluator");
+const { buildPermissionLimitPlan } = require("./permission-minimizer");
+const {
+  ENFORCEMENT_SUMMARY_REL_PATH,
+  ENFORCEMENT_CAPABILITIES_REL_PATH,
+  JIT_GRANTS_REL_PATH,
+  ONE_TIME_GRANTS_REL_PATH,
+  ENFORCEMENT_AUDIT_LOG_REL_PATH,
+  loadJitGrantStore,
+  loadEnforcementSummary,
+  recordEnforcementOutcome,
+  enforceAgentSecurityAction,
+} = require("./enforcement-engine");
+const { resolveAgentSecurityAdapter, writeEnforcementCapabilityMatrix } = require("./adapter-registry");
+const { decideAutoAction } = require("./auto-policy");
+const { scanInstructionRisk, sanitizeInstructionLikeContent } = require("./instruction-risk");
+const { buildSourceRecord, sourceTypeForComponentType } = require("./source-trust");
+const {
+  PERFORMANCE_SUMMARY_REL_PATH,
+  PERFORMANCE_GUARDRAILS,
+  createPerformanceTracker,
+  recordPerformanceSummary,
+  buildCompactPerformanceSummary,
+} = require("./performance");
+const { SCAN_CACHE_REL_PATH, cacheLookup, updateScanCache, buildCacheKey } = require("./scan-cache");
+const { createBoundedScanSession } = require("./bounded-scan");
+
+const AGENT_SECURITY_MODES = ["off", "basic", "visibility", "warn", "auto"];
+const SNAPSHOT_REL_PATH = ".claude/cco/security/agent-surface-snapshot.json";
+const SUMMARY_REL_PATH = ".claude/cco/security/agent-basic-check-summary.json";
+const VISIBILITY_SUMMARY_REL_PATH = ".claude/cco/security/agent-visibility-summary.json";
+const TRUST_CARDS_REL_PATH = ".claude/cco/security/agent-trust-cards.json";
+const RISK_DIFF_REL_PATH = ".claude/cco/security/agent-risk-diff.json";
+const PERMISSION_PREVIEW_REL_PATH = ".claude/cco/security/agent-permission-preview.json";
+const INSTRUCTION_RISK_REL_PATH = ".claude/cco/security/agent-instruction-risk.json";
+const SOURCE_TRUST_REL_PATH = ".claude/cco/security/agent-source-trust.json";
+const INSTRUCTION_REMEDIATIONS_REL_PATH = ".claude/cco/security/agent-instruction-remediations.json";
+const SANITIZED_CONTENT_REL_PATH = ".claude/cco/security/agent-sanitized-content.json";
+const AUDIT_LOG_REL_PATH = ".claude/cco/audit/agent-security.jsonl";
+const INSTRUCTION_AUDIT_LOG_REL_PATH = ".claude/cco/audit/agent-instruction-risk.jsonl";
+const ACTION_PREFLIGHT_REL_PATH = ".claude/cco/security/agent-action-preflight.json";
+const DECISION_SUMMARY_REL_PATH = ".claude/cco/security/agent-decision-summary.json";
+const DECISION_AUDIT_LOG_REL_PATH = ".claude/cco/audit/agent-security-decisions.jsonl";
+
+const TEXT_EXTENSIONS = new Set([".md", ".txt", ".json", ".js", ".ts", ".yaml", ".yml", ".sh", ".ps1", ".toml", ".mjs", ".cjs"]);
+const EXCLUDED_DIR_NAMES = new Set([".git", "node_modules", ".claude/cco", "coverage", "dist", "build", ".next", ".turbo", ".cache", ".wasp/out"]);
+const EXCLUDED_DIR_BASENAMES = new Set([".git", "node_modules", "coverage", "dist", "build", ".next", ".turbo", ".cache"]);
+const CAPABILITY_KEYS = [
+  "filesystemRead",
+  "filesystemWrite",
+  "shell",
+  "network",
+  "mcpRead",
+  "mcpWrite",
+  "externalMutation",
+  "sensitiveAccess",
+];
+const AGENT_SECURITY_SCANNER_VERSION = "slice-8-6";
+
+function buildAgentSecurityModeControl(config) {
+  const currentMode = config?.agentSecurity?.mode || "off";
+  return {
+    title: "Agent Security",
+    currentMode,
+    options: [
+      {
+        value: "off",
+        label: "Off",
+        description: "Wuz stays out of the way. No Agent Security scans, warnings, or dashboard section.",
+        available: true,
+      },
+      {
+        value: "basic",
+        label: "Basic Check",
+        description: "Check new Skills and MCP entries. Included in the basic/free layer.",
+        available: true,
+      },
+      {
+        value: "visibility",
+        label: "Visibility",
+        description: "Map the full AI agent surface and show risk diff + permission preview.",
+        available: true,
+      },
+      {
+        value: "warn",
+        label: "Warn & Approve",
+        description: "Warn before sensitive actions. Approve once, deny, or let Wuz limit.",
+        available: true,
+      },
+      {
+        value: "auto",
+        label: "Auto-Minimize",
+        description: "Wuz automatically applies least-privilege limits only for safe, enforceable actions. Risky or unknown actions still require approval.",
+        available: true,
+      },
+    ],
+  };
+}
+
+function normalizePath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function relPath(cwd, absPath) {
+  return normalizePath(path.relative(cwd, absPath));
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort((left, right) => left.localeCompare(right))
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function shortHash(value) {
+  return sha256(String(value || "")).slice(0, 12);
+}
+
+function ensureDir(absPath) {
+  fs.mkdirSync(absPath, { recursive: true });
+}
+
+function readJsonAbs(absPath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return fallback;
+  }
+}
+
+function readTextAbs(absPath) {
+  try {
+    return fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, "");
+  } catch {
+    return "";
+  }
+}
+
+function appendJsonl(cwd, relPathValue, entry) {
+  const absPath = path.join(cwd, relPathValue);
+  ensureDir(path.dirname(absPath));
+  fs.appendFileSync(absPath, `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+function boundedPreview(value, max = 120) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max)}...` : text;
+}
+
+function shouldExcludeDir(cwd, absDir) {
+  const rel = normalizePath(path.relative(cwd, absDir));
+  if (rel === ".claude/cco") return true;
+  if (EXCLUDED_DIR_NAMES.has(rel)) return true;
+  return EXCLUDED_DIR_BASENAMES.has(path.basename(absDir));
+}
+
+function walkFiles(absDir, out, cwd, options = {}, depth = 0) {
+  if (!fs.existsSync(absDir)) return;
+  const scanSession = options.scanSession || null;
+  const entries = fs.readdirSync(absDir, { withFileTypes: true });
+  entries.forEach((entry) => {
+    const entryAbs = path.join(absDir, entry.name);
+    if (entry.isDirectory()) {
+      if (shouldExcludeDir(cwd, entryAbs)) {
+        if (scanSession?.tracker) scanSession.tracker.noteIgnoredDirectory(relPath(cwd, entryAbs));
+        return;
+      }
+      const maxDepth = Number.isFinite(Number(options.maxDepth)) ? Number(options.maxDepth) : Infinity;
+      if (depth >= maxDepth) return;
+      if (scanSession && !scanSession.canDescend(depth, entryAbs)) return;
+      walkFiles(entryAbs, out, cwd, options, depth + 1);
+      return;
+    }
+    if (entry.isFile()) {
+      const stat = fs.statSync(entryAbs);
+      if (scanSession && !scanSession.canReadFile(entryAbs, stat)) return;
+      if (scanSession) scanSession.noteFile(entryAbs, stat);
+      out.push(entryAbs);
+    }
+  });
+}
+
+function listFiles(absDir, cwd, options = {}) {
+  const out = [];
+  walkFiles(absDir, out, cwd, options, 0);
+  return out.sort((left, right) => left.localeCompare(right));
+}
+
+function listTextFiles(absDir, cwd, options = {}) {
+  return listFiles(absDir, cwd, options).filter((absPath) => TEXT_EXTENSIONS.has(path.extname(absPath).toLowerCase()));
+}
+
+function hashDirectory(cwd, absDir, options = {}) {
+  const pieces = listFiles(absDir, cwd, options).map((absPath) => {
+    const fileRel = relPath(cwd, absPath);
+    const content = fs.readFileSync(absPath);
+    return `${fileRel}\n${sha256(content)}\n`;
+  });
+  return sha256(pieces.join(""));
+}
+
+function hashFile(cwd, absPath) {
+  const buffer = fs.readFileSync(absPath);
+  return sha256(`${relPath(cwd, absPath)}\n${buffer.toString("utf8")}`);
+}
+
+function hashPathStat(cwd, absPath) {
+  try {
+    const stat = fs.statSync(absPath);
+    return sha256(`${relPath(cwd, absPath)}\n${stat.isDirectory() ? "dir" : "file"}\n${Number(stat.size || 0)}`);
+  } catch {
+    return sha256(relPath(cwd, absPath));
+  }
+}
+
+function hashNormalizedObject(value) {
+  return sha256(stableStringify(value));
+}
+
+function createComponentId(type, name, sourcePath) {
+  const safeName = String(name || type)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || type;
+  return `${type}-${safeName}-${shortHash(`${type}:${sourcePath}`)}`;
+}
+
+function maybePush(list, message, seen) {
+  if (!message || seen.has(message)) return;
+  seen.add(message);
+  list.push(message);
+}
+
+function emptyCapabilities() {
+  return {
+    filesystemRead: false,
+    filesystemWrite: false,
+    shell: false,
+    network: false,
+    mcpRead: false,
+    mcpWrite: false,
+    externalMutation: false,
+    sensitiveAccess: false,
+  };
+}
+
+function scrubSecretValues(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => scrubSecretValues(item));
+  }
+  if (!value || typeof value !== "object") return value;
+
+  const out = {};
+  Object.keys(value).forEach((key) => {
+    const lowered = String(key || "").toLowerCase();
+    if (lowered === "env" && value[key] && typeof value[key] === "object" && !Array.isArray(value[key])) {
+      out[key] = Object.keys(value[key]).sort();
+      return;
+    }
+    out[key] = scrubSecretValues(value[key]);
+  });
+  return out;
+}
+
+function commandTextFromEntry(entry) {
+  if (!entry || typeof entry !== "object") return "";
+  const command = String(entry.command || "");
+  const args = Array.isArray(entry.args) ? entry.args.map((item) => String(item || "")).join(" ") : "";
+  return `${command} ${args}`.trim();
+}
+
+function envKeyNames(entry) {
+  const env = entry && entry.env && typeof entry.env === "object" && !Array.isArray(entry.env) ? entry.env : null;
+  return env ? Object.keys(env).sort() : [];
+}
+
+function collectSkillDirectories(absDir, cwd, out, options = {}, depth = 0) {
+  if (!fs.existsSync(absDir)) return;
+  const skillRoots = new Set([path.join(cwd, "skills"), path.join(cwd, ".claude/skills")]);
+  if (options.scanSession && !skillRoots.has(absDir) && !options.scanSession.canDescend(depth, absDir)) {
+    return;
+  }
+  const entries = fs.readdirSync(absDir, { withFileTypes: true });
+  const hasSkillFile = entries.some((entry) => entry.isFile() && entry.name.toLowerCase() === "skill.md");
+  if (hasSkillFile) {
+    const textFiles = listTextFiles(absDir, cwd, { scanSession: options.scanSession });
+    out.push({
+      name: path.basename(absDir),
+      type: "skill",
+      sourcePath: relPath(cwd, absDir),
+      sourceKind: "local",
+      contentHash: hashDirectory(cwd, absDir, { scanSession: options.scanSession }),
+      contentText: textFiles.map((filePath) => `# ${relPath(cwd, filePath)}\n${readTextAbs(filePath)}`).join("\n"),
+      mtimeMs: textFiles.reduce((max, filePath) => Math.max(max, statMeta(filePath).mtimeMs), 0),
+    });
+  }
+
+  entries
+    .filter((entry) => entry.isDirectory())
+    .forEach((entry) => {
+      const nextDir = path.join(absDir, entry.name);
+      collectSkillDirectories(nextDir, cwd, out, options, depth + 1);
+    });
+}
+
+function detectSkillComponents(cwd, options = {}) {
+  const out = [];
+  ["skills", ".claude/skills"].forEach((rootRel) => {
+    collectSkillDirectories(path.join(cwd, rootRel), cwd, out, options);
+  });
+  return out;
+}
+
+function detectCommandComponents(cwd, options = {}) {
+  const commandsRoot = path.join(cwd, ".claude", "commands");
+  if (!fs.existsSync(commandsRoot)) return [];
+
+  return listFiles(commandsRoot, cwd, { scanSession: options.scanSession })
+    .filter((absPath) => fs.statSync(absPath).isFile())
+    .map((absPath) => ({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: path.parse(absPath).name,
+      type: "command",
+      sourcePath: relPath(cwd, absPath),
+      sourceKind: "local",
+      contentHash: hashFile(cwd, absPath),
+      contentText: readTextAbs(absPath),
+    }));
+}
+
+function extractNamedEntries(container) {
+  if (!container) return [];
+
+  if (Array.isArray(container)) {
+    return container
+      .map((item, index) => {
+        const name = item && typeof item === "object" ? item.name || item.id || item.server || `server-${index + 1}` : `server-${index + 1}`;
+        return { name: String(name), entry: item };
+      })
+      .filter((item) => item.name);
+  }
+
+  if (typeof container === "object") {
+    return Object.keys(container).map((name) => ({ name, entry: container[name] }));
+  }
+
+  return [];
+}
+
+function extractMcpEntriesFromConfig(config) {
+  const candidates = [
+    config?.mcpServers,
+    config?.servers,
+    config?.mcp?.servers,
+    config?.mcp?.mcpServers,
+  ];
+
+  for (const candidate of candidates) {
+    const entries = extractNamedEntries(candidate);
+    if (entries.length > 0) return entries;
+  }
+
+  return [];
+}
+
+function detectMcpComponents(cwd) {
+  const configFiles = [
+    ".mcp.json",
+    ".cursor/mcp.json",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+  ];
+
+  const out = [];
+  configFiles.forEach((configRel) => {
+    const absPath = path.join(cwd, configRel);
+    if (!fs.existsSync(absPath)) return;
+
+    const parsed = readJsonAbs(absPath, null);
+    if (!parsed || typeof parsed !== "object") return;
+
+    extractMcpEntriesFromConfig(parsed).forEach(({ name, entry }) => {
+      const normalizedEntry = entry && typeof entry === "object" ? scrubSecretValues(entry) : { value: entry };
+      out.push({
+        name: String(name),
+        type: "mcp",
+        sourcePath: normalizePath(`${configRel}#${name}`),
+        sourceKind: "config",
+        contentHash: hashNormalizedObject(normalizedEntry),
+      contentText: stableStringify(normalizedEntry),
+      rawConfigPath: configRel,
+      rawEntry: normalizedEntry,
+      envKeys: envKeyNames(entry),
+      commandText: commandTextFromEntry(entry),
+      mtimeMs: statMeta(absPath).mtimeMs,
+      });
+    });
+  });
+
+  return out;
+}
+
+function detectConfigComponents(cwd) {
+  const configFiles = [
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".mcp.json",
+    ".cursor/mcp.json",
+  ];
+  const out = [];
+
+  configFiles.forEach((configRel) => {
+    const absPath = path.join(cwd, configRel);
+    if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) return;
+    out.push({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: configRel.replace(/[\\/]/g, "-").replace(/^-+|-+$/g, ""),
+      type: "config",
+      sourcePath: configRel,
+      sourceKind: "config",
+      contentHash: hashFile(cwd, absPath),
+      contentText: readTextAbs(absPath),
+    });
+  });
+
+  const packageJsonAbs = path.join(cwd, "package.json");
+  if (fs.existsSync(packageJsonAbs) && fs.statSync(packageJsonAbs).isFile()) {
+    out.push({
+      mtimeMs: statMeta(packageJsonAbs).mtimeMs,
+      name: "package-json",
+      type: "config",
+      sourcePath: "package.json",
+      sourceKind: "config",
+      contentHash: hashFile(cwd, packageJsonAbs),
+      contentText: readTextAbs(packageJsonAbs),
+    });
+  }
+
+  const lockfiles = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
+  lockfiles.forEach((name) => {
+    const absPath = path.join(cwd, name);
+    if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) return;
+    out.push({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: name.replace(/\W+/g, "-"),
+      type: "config",
+      sourcePath: name,
+      sourceKind: "local",
+      contentHash: hashFile(cwd, absPath),
+      contentText: `Lockfile present: ${name}`,
+    });
+  });
+
+  const dockerCandidates = fs
+    .readdirSync(cwd, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => /^dockerfile(?:\..+)?$/i.test(name) || /^(?:docker-)?compose(?:\..+)?\.(?:ya?ml)$/i.test(name));
+
+  dockerCandidates.forEach((name) => {
+    const absPath = path.join(cwd, name);
+    out.push({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: name.replace(/\W+/g, "-").toLowerCase(),
+      type: "config",
+      sourcePath: name,
+      sourceKind: "local",
+      contentHash: hashFile(cwd, absPath),
+      contentText: readTextAbs(absPath),
+    });
+  });
+
+  return out;
+}
+
+function detectCursorRuleComponents(cwd, options = {}) {
+  const rulesRoot = path.join(cwd, ".cursor", "rules");
+  if (!fs.existsSync(rulesRoot)) return [];
+
+  return listFiles(rulesRoot, cwd, { scanSession: options.scanSession })
+    .filter((absPath) => fs.statSync(absPath).isFile())
+    .map((absPath) => ({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: path.parse(absPath).name,
+      type: "cursor-rule",
+      sourcePath: relPath(cwd, absPath),
+      sourceKind: "local",
+      contentHash: hashFile(cwd, absPath),
+      contentText: readTextAbs(absPath),
+    }));
+}
+
+function detectPackageScriptComponents(cwd) {
+  const packageJsonAbs = path.join(cwd, "package.json");
+  if (!fs.existsSync(packageJsonAbs)) return [];
+
+  const pkg = readJsonAbs(packageJsonAbs, null);
+  const scripts = pkg && pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : null;
+  if (!scripts) return [];
+
+  return Object.keys(scripts)
+    .sort((left, right) => left.localeCompare(right))
+    .map((name) => {
+      const command = String(scripts[name] || "");
+      return {
+        mtimeMs: statMeta(packageJsonAbs).mtimeMs,
+        name,
+        type: "package-script",
+        sourcePath: `package.json#scripts.${name}`,
+        sourceKind: "config",
+        contentHash: hashNormalizedObject({ name, command }),
+        contentText: command,
+      };
+    });
+}
+
+function detectWorkflowComponents(cwd, options = {}) {
+  const workflowsRoot = path.join(cwd, ".github", "workflows");
+  if (!fs.existsSync(workflowsRoot)) return [];
+
+  return listFiles(workflowsRoot, cwd, { scanSession: options.scanSession })
+    .filter((absPath) => fs.statSync(absPath).isFile())
+    .map((absPath) => ({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: path.parse(absPath).name,
+      type: "workflow",
+      sourcePath: relPath(cwd, absPath),
+      sourceKind: "local",
+      contentHash: hashFile(cwd, absPath),
+      contentText: readTextAbs(absPath),
+    }));
+}
+
+function detectSensitiveSurfaceComponents(cwd, options = {}) {
+  const out = [];
+  const seen = new Set();
+
+  function pushComponent(component) {
+    if (seen.has(component.sourcePath)) return;
+    seen.add(component.sourcePath);
+    out.push(component);
+  }
+
+  try {
+    fs.readdirSync(cwd, { withFileTypes: true }).forEach((entry) => {
+      if (!entry.isFile()) return;
+      if (!/^\.env(?:\..+)?$/i.test(entry.name)) return;
+      const absPath = path.join(cwd, entry.name);
+      pushComponent({
+        mtimeMs: statMeta(absPath).mtimeMs,
+        name: entry.name,
+        type: "sensitive-surface",
+        sourcePath: entry.name,
+        sourceKind: "local",
+        contentHash: hashPathStat(cwd, absPath),
+        contentText: `Sensitive surface present: ${entry.name}`,
+      });
+    });
+  } catch {
+    // Ignore missing root read access and keep scan local-first.
+  }
+
+  [".ssh", ".aws", ".gcp", ".azure"].forEach((dirName) => {
+    const absPath = path.join(cwd, dirName);
+    if (!fs.existsSync(absPath)) return;
+    pushComponent({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: dirName.replace(/^\./, ""),
+      type: "sensitive-surface",
+      sourcePath: normalizePath(dirName),
+      sourceKind: "local",
+      contentHash: hashPathStat(cwd, absPath),
+      contentText: `Sensitive directory present: ${dirName}`,
+    });
+  });
+
+  listFiles(cwd, cwd, { maxDepth: 3, scanSession: options.scanSession }).forEach((absPath) => {
+    const fileRel = relPath(cwd, absPath);
+    if (fileRel.startsWith(".claude/cco/")) return;
+    const baseName = path.basename(absPath).toLowerCase();
+    if (!/(secret|token|private.?key|id_rsa|id_dsa|id_ed25519|credential)/i.test(baseName)) return;
+    pushComponent({
+      mtimeMs: statMeta(absPath).mtimeMs,
+      name: path.basename(absPath),
+      type: "sensitive-surface",
+      sourcePath: fileRel,
+      sourceKind: "local",
+      contentHash: hashPathStat(cwd, absPath),
+      contentText: `Sensitive file naming pattern detected: ${path.basename(absPath)}`,
+    });
+  });
+
+  return out.sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+}
+
+function hasPattern(text, pattern) {
+  return pattern.test(String(text || ""));
+}
+
+function inferCapabilities(component) {
+  const capabilities = emptyCapabilities();
+  const entry = component.rawEntry || {};
+  const text = `${component.name}\n${component.sourcePath}\n${component.contentText}\n${component.commandText || ""}`;
+  const lowerText = text.toLowerCase();
+
+  if (component.type === "sensitive-surface") {
+    capabilities.filesystemRead = true;
+    capabilities.sensitiveAccess = true;
+  }
+
+  if (component.type === "mcp") {
+    capabilities.mcpRead = true;
+    capabilities.filesystemRead = true;
+  }
+
+  if (component.type === "package-script") {
+    capabilities.shell = true;
+  }
+
+  if (component.type === "command") {
+    capabilities.shell = true;
+  }
+
+  if (/\b(read|cat|open|grep|search|inspect|review|list files|find files|docs)\b/i.test(text)) {
+    capabilities.filesystemRead = true;
+  }
+
+  if (/\b(write|modify|edit|delete|remove-item|rm\s+-rf|touch|truncate|mkdir|copy-item|move-item|tee\b|git commit|git push|workflow file|update workflow)\b/i.test(text)) {
+    capabilities.filesystemWrite = true;
+  }
+
+  if (/\b(shell|terminal|bash|sh\b|pwsh|powershell|cmd(?:\.exe)?\b|subprocess|spawn|exec|npm run|pnpm run|yarn run|make\b)\b/i.test(text)) {
+    capabilities.shell = true;
+  }
+
+  if (/\b(curl|wget|invoke-webrequest|invoke-restmethod|downloadstring|https?:\/\/|gh api|npm install|pnpm add|yarn add|docker pull|npx\b|pnpm dlx|yarn dlx|uvx)\b/i.test(text)) {
+    capabilities.network = true;
+  }
+
+  if (/\b(secret|secrets|token|tokens|private key|private keys|ssh key|ssh keys|\.env\b|credentials?|aws|gcp|azure)\b/i.test(text)) {
+    capabilities.sensitiveAccess = true;
+  }
+
+  if (component.type === "mcp") {
+    const nameAndCommand = `${component.name}\n${component.commandText || ""}\n${stableStringify(entry)}`;
+    if (/\b(write|delete|admin|workflow|workflows|secret|secrets|token|tokens|push|merge|deploy|prod|production|create pr|pull request)\b/i.test(nameAndCommand)) {
+      capabilities.mcpWrite = true;
+      capabilities.externalMutation = true;
+    }
+    if (Array.isArray(entry.capabilities)) {
+      const joined = entry.capabilities.join(" ").toLowerCase();
+      if (/\bwrite|mutate|admin|delete\b/.test(joined)) {
+        capabilities.mcpWrite = true;
+        capabilities.externalMutation = true;
+      }
+    }
+    if (entry.transport && /https?|sse|stream/i.test(String(entry.transport))) {
+      capabilities.network = true;
+    }
+  }
+
+  if (component.type === "workflow" && /\b(deploy|publish|release|workflow_dispatch|secrets?|gh api|actions\/checkout|permissions: write-all)\b/i.test(text)) {
+    capabilities.externalMutation = true;
+  }
+
+  if (component.type === "config" && /\bmcpservers\b/i.test(lowerText)) {
+    capabilities.mcpRead = true;
+  }
+
+  return capabilities;
+}
+
+function deriveTrustLevel(component) {
+  if (component.type !== "mcp") {
+    return component.sourceKind === "local" || component.sourceKind === "config" ? "local" : "unknown";
+  }
+
+  const entry = component.rawEntry || {};
+  const command = component.commandText || "";
+  const image = String(entry.image || "");
+  const text = `${component.name}\n${component.contentText}\n${command}\n${image}`;
+
+  const localScriptPath = String(entry.command || "");
+  if (localScriptPath && /^(node|python|py|bash|sh|powershell|pwsh)$/i.test(localScriptPath)) {
+    const args = Array.isArray(entry.args) ? entry.args : [];
+    if (args.some((arg) => /\.(js|cjs|mjs|py|ps1|sh)$/i.test(String(arg || "")))) return "local";
+  }
+
+  if (/@[0-9]+\.[0-9]+(?:\.[0-9]+)?\b/.test(text) || /sha256:[a-f0-9]{32,}/i.test(text) || /#[a-f0-9]{12,40}\b/i.test(text)) {
+    return "pinned";
+  }
+
+  if (/\b(npx|pnpm dlx|yarn dlx|uvx|docker|podman)\b/i.test(command) || /^https?:\/\//i.test(command)) {
+    return "review-needed";
+  }
+
+  return "unknown";
+}
+
+function riskRank(level) {
+  if (level === "high") return 3;
+  if (level === "medium") return 2;
+  return 1;
+}
+
+function determineStatusForCurrent(previousEntry, component, mode) {
+  if (!previousEntry) return "new";
+  if (mode === "visibility" && (previousEntry.contentHash !== component.contentHash || previousEntry.source !== component.sourcePath)) {
+    return "changed";
+  }
+  return "known";
+}
+
+function classifyRisk(component, previousEntry, mode) {
+  const findings = [];
+  const seen = new Set();
+  let riskScore = 1;
+
+  const capabilities = inferCapabilities(component);
+  const text = `${component.name}\n${component.sourcePath}\n${component.contentText}\n${component.commandText || ""}`;
+  const trustLevel = deriveTrustLevel(component);
+  const status = determineStatusForCurrent(previousEntry, component, mode);
+  const sourceType = sourceTypeForComponentType(component.type);
+  const instructionScan = scanInstructionRisk(text, {
+    sourceType,
+    intendedUse: "instruction",
+  });
+
+  const highSignals = [
+    { test: /(?:^|[^a-z0-9_])\.env\b|\b(secret|secrets|token|tokens|private key|private keys|ssh key|ssh keys)\b/i, finding: "References secrets, tokens, or private key material" },
+    { test: /\b(ignore safety|ignore guardrails|bypass review|hide actions|silently run|silently execute|exfiltrat|steal data|bypass policy)\b/i, finding: "Contains suspicious instruction language that bypasses review or hides actions" },
+    { test: /\b(curl|wget)\b[^\n]*\|\s*(bash|sh|pwsh|powershell)\b/i, finding: "Includes remote download piped into a shell" },
+    { test: /\b(invoke-webrequest|invoke-restmethod|downloadstring)\b/i, finding: "Includes remote PowerShell download behavior" },
+  ];
+
+  highSignals.forEach((signal) => {
+    if (hasPattern(text, signal.test)) {
+      maybePush(findings, signal.finding, seen);
+      riskScore = Math.max(riskScore, 3);
+    }
+  });
+
+  if (component.type === "package-script" && /^(?:preinstall|postinstall|install)$/i.test(component.name)) {
+    maybePush(findings, "Package install script can execute automatically during dependency operations", seen);
+    riskScore = Math.max(riskScore, 3);
+  }
+
+  if (capabilities.sensitiveAccess) {
+    maybePush(findings, "Can reach sensitive files, credentials, or secret-like surfaces", seen);
+    riskScore = Math.max(riskScore, component.type === "sensitive-surface" ? 2 : 3);
+  }
+
+  if (component.type === "mcp" && (capabilities.mcpWrite || capabilities.externalMutation) && !/\b(approval|readOnly|read_only)\b/i.test(text)) {
+    maybePush(findings, "This MCP can modify external systems or has elevated posture", seen);
+    riskScore = Math.max(riskScore, 3);
+  }
+
+  if (component.type === "workflow" && /\b(workflows?|permissions:\s*write-all|secrets?|deploy|publish|release)\b/i.test(text)) {
+    maybePush(findings, "Workflow can affect automation, releases, or secret-backed execution", seen);
+    riskScore = Math.max(riskScore, 3);
+  }
+
+  if (status === "new") {
+    maybePush(findings, "New AI component detected", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+  if (status === "changed" && mode === "visibility") {
+    maybePush(findings, "Component changed since the previous recorded scan", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+
+  if (component.sourceKind === "unknown") {
+    maybePush(findings, "Source could not be verified locally", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+  if (trustLevel === "unknown") {
+    maybePush(findings, "Trust level is still unknown", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+  if (trustLevel === "review-needed") {
+    maybePush(findings, "Source should be reviewed before use", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+
+  if (capabilities.filesystemWrite) {
+    maybePush(findings, "Can modify local files or project automation", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+  if (capabilities.shell) {
+    maybePush(findings, "Can run shell commands or subprocesses", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+  if (capabilities.network) {
+    maybePush(findings, "Can reach remote network resources or pull remote tooling", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+  if (component.type === "package-script" && /\b(build|prepare|compile|bundle)\b/i.test(component.name)) {
+    maybePush(findings, "Package script can mutate generated outputs or build artifacts", seen);
+    riskScore = Math.max(riskScore, 2);
+  }
+
+  instructionScan.findings.forEach((finding) => {
+    maybePush(findings, finding.message, seen);
+  });
+  riskScore = Math.max(riskScore, riskRank(instructionScan.instructionRisk));
+
+  const riskLevel = riskScore >= 3 ? "high" : riskScore >= 2 ? "medium" : "low";
+  if (findings.length === 0) {
+    findings.push("No obvious risky indicators found");
+  }
+
+  let recommendation = "No high-risk findings";
+  if (riskLevel === "high") recommendation = "Review before use";
+  else if (riskLevel === "medium" || status === "new" || status === "changed") recommendation = "Review details before use";
+
+  return {
+    status,
+    trustLevel,
+    riskLevel,
+    findings: findings.slice(0, 6),
+    recommendation,
+    requiresCheck: status === "new" || status === "changed" || riskLevel !== "low",
+    capabilities,
+    instructionRisk: instructionScan.instructionRisk,
+    instructionSignals: instructionScan.signals,
+    instructionFindings: instructionScan.findings.slice(0, 8),
+    sourceType,
+  };
+}
+
+function statMeta(absPath) {
+  try {
+    const stat = fs.statSync(absPath);
+    return {
+      mtimeMs: Number(stat.mtimeMs || 0),
+      size: Number(stat.size || 0),
+    };
+  } catch {
+    return {
+      mtimeMs: 0,
+      size: 0,
+    };
+  }
+}
+
+function classifyRiskCached(cwd, component, previousEntry, mode, tracker) {
+  const size = Buffer.byteLength(String(component.contentText || ""), "utf8");
+  const expectedStatus = determineStatusForCurrent(previousEntry, component, mode);
+  const cacheKey = buildCacheKey({
+    scannerVersion: AGENT_SECURITY_SCANNER_VERSION,
+    type: component.type,
+    path: component.sourcePath,
+    mode,
+    contentHash: component.contentHash,
+  });
+  const cached = cacheLookup(cwd, {
+    cacheKey,
+    path: component.sourcePath,
+    mtimeMs: Number(component.mtimeMs || 0),
+    size,
+    contentHash: component.contentHash,
+    scannerVersion: AGENT_SECURITY_SCANNER_VERSION,
+  });
+  if (cached && cached.result) {
+    if (cached.result.status === expectedStatus) {
+      if (tracker) tracker.noteCacheHit();
+      return cached.result;
+    }
+  }
+
+  if (tracker) tracker.noteCacheMiss();
+  const result = classifyRisk(component, previousEntry, mode);
+  updateScanCache(cwd, AGENT_SECURITY_SCANNER_VERSION, {
+    cacheKey,
+    path: component.sourcePath,
+    mtimeMs: Number(component.mtimeMs || 0),
+    size,
+    contentHash: component.contentHash,
+    scannerVersion: AGENT_SECURITY_SCANNER_VERSION,
+    lastScannedAt: nowIso(),
+    result,
+  });
+  return result;
+}
+
+function toSnapshotComponent(component) {
+  return {
+    id: component.id,
+    type: component.type,
+    name: component.name,
+    source: component.source,
+    sourceKind: component.sourceKind,
+    status: component.status,
+    riskLevel: component.riskLevel,
+    trustLevel: component.trustLevel,
+    sourceType: component.sourceType || null,
+    sourceTrust: component.sourceTrust || null,
+    instructionRisk: component.instructionRisk || "low",
+    instructionSignals: component.instructionSignals || [],
+    instructionFindings: component.instructionFindings || [],
+    contentHash: component.contentHash,
+    capabilities: component.capabilities,
+    findings: component.findings,
+    recommendation: component.recommendation,
+    firstSeenAt: component.firstSeenAt,
+    lastSeenAt: component.lastSeenAt,
+    lastCheckedAt: component.lastCheckedAt,
+  };
+}
+
+function normalizeSnapshotItems(snapshot, mode) {
+  const scoped = snapshot && snapshot.scopedComponents && typeof snapshot.scopedComponents === "object"
+    ? snapshot.scopedComponents
+    : {};
+  const scopedItems = mode && Array.isArray(scoped[mode]) ? scoped[mode] : null;
+  const fallbackItems = Array.isArray(snapshot?.components)
+    ? snapshot.components
+    : snapshot?.components && typeof snapshot.components === "object"
+      ? Object.values(snapshot.components)
+      : [];
+  return scopedItems || fallbackItems;
+}
+
+function loadPreviousSnapshot(cwd, mode = "basic") {
+  const snapshot = safeReadJson(cwd, SNAPSHOT_REL_PATH, null);
+  if (!snapshot || typeof snapshot !== "object") {
+    return {
+      snapshotVersion: 2,
+      generatedAt: null,
+      scope: mode,
+      scanMode: null,
+      scopedComponents: {},
+      components: [],
+      componentsById: {},
+      raw: null,
+    };
+  }
+
+  const componentItems = normalizeSnapshotItems(snapshot, mode);
+  const componentsById = {};
+  componentItems.forEach((item) => {
+    if (item && item.id) componentsById[item.id] = item;
+  });
+
+  return {
+    snapshotVersion: Number(snapshot.snapshotVersion || 1),
+    generatedAt: snapshot.generatedAt || null,
+    scope: mode,
+    scanMode: snapshot.scanMode || null,
+    scopedComponents: snapshot.scopedComponents || {},
+    components: componentItems,
+    componentsById,
+    raw: snapshot,
+  };
+}
+
+function buildMergedSnapshot(previousSnapshot, mode, components, generatedAt) {
+  const snapshotComponents = components.map((component) => toSnapshotComponent(component));
+  const priorScoped = previousSnapshot?.raw?.scopedComponents && typeof previousSnapshot.raw.scopedComponents === "object"
+    ? previousSnapshot.raw.scopedComponents
+    : previousSnapshot?.scopedComponents && typeof previousSnapshot.scopedComponents === "object"
+      ? previousSnapshot.scopedComponents
+      : {};
+  const priorGeneratedAts = previousSnapshot?.raw?.scopedGeneratedAts && typeof previousSnapshot.raw.scopedGeneratedAts === "object"
+    ? previousSnapshot.raw.scopedGeneratedAts
+    : {};
+
+  return {
+    snapshotVersion: 2,
+    generatedAt,
+    scanMode: mode,
+    componentCount: snapshotComponents.length,
+    components: snapshotComponents,
+    scopedComponents: {
+      ...priorScoped,
+      [mode]: snapshotComponents,
+    },
+    scopedGeneratedAts: {
+      ...priorGeneratedAts,
+      [mode]: generatedAt,
+    },
+  };
+}
+
+function sortTrustCards(cards) {
+  return cards.sort((left, right) => {
+    const severityRank = { high: 3, medium: 2, low: 1 };
+    if (severityRank[right.riskLevel] !== severityRank[left.riskLevel]) {
+      return severityRank[right.riskLevel] - severityRank[left.riskLevel];
+    }
+    const statusRank = { new: 0, changed: 1, removed: 2, known: 3 };
+    if ((statusRank[left.status] ?? 99) !== (statusRank[right.status] ?? 99)) {
+      return (statusRank[left.status] ?? 99) - (statusRank[right.status] ?? 99);
+    }
+    if (left.type !== right.type) return left.type.localeCompare(right.type);
+    return left.name.localeCompare(right.name);
+  });
+}
+
+function buildRemovedTrustCard(previousEntry, generatedAt) {
+  return {
+    id: previousEntry.id,
+    type: previousEntry.type,
+    name: previousEntry.name,
+    source: previousEntry.source,
+    sourceKind: previousEntry.sourceKind || "local",
+    status: "removed",
+    requiresCheck: false,
+    riskLevel: previousEntry.riskLevel || "low",
+    trustLevel: previousEntry.trustLevel || "unknown",
+    sourceType: previousEntry.sourceType || sourceTypeForComponentType(previousEntry.type),
+    sourceTrust: previousEntry.sourceTrust || null,
+    instructionRisk: previousEntry.instructionRisk || "low",
+    instructionSignals: previousEntry.instructionSignals || [],
+    instructionFindings: previousEntry.instructionFindings || [],
+    findings: ["Component no longer detected locally"],
+    recommendation: "Confirm removal was intentional",
+    contentHash: previousEntry.contentHash || null,
+    capabilities: previousEntry.capabilities || emptyCapabilities(),
+    firstSeenAt: previousEntry.firstSeenAt || generatedAt,
+    lastSeenAt: previousEntry.lastSeenAt || generatedAt,
+    lastCheckedAt: generatedAt,
+  };
+}
+
+function detectComponentsForMode(cwd, mode, options = {}) {
+  const base = [...detectSkillComponents(cwd, options), ...detectCommandComponents(cwd, options), ...detectMcpComponents(cwd)];
+  if (mode !== "visibility") return base;
+  return [
+    ...base,
+    ...detectConfigComponents(cwd),
+    ...detectCursorRuleComponents(cwd, options),
+    ...detectPackageScriptComponents(cwd),
+    ...detectWorkflowComponents(cwd, options),
+    ...detectSensitiveSurfaceComponents(cwd, options),
+  ];
+}
+
+function buildTrustCardsForMode(cwd, previousSnapshot, generatedAt, mode, options = {}) {
+  const tracker = options.tracker || null;
+  const currentCards = detectComponentsForMode(cwd, mode, options).map((component) => {
+    const id = createComponentId(component.type, component.name, component.sourcePath);
+    const previousEntry = previousSnapshot.componentsById[id] || null;
+    const classification = classifyRiskCached(cwd, component, previousEntry, mode, tracker);
+    const sourceTrust = buildSourceRecord({
+      sourceId: id,
+      sourceType: classification.sourceType,
+      origin: component.type === "mcp" ? component.rawConfigPath || component.sourcePath : component.sourcePath,
+      path: component.sourcePath,
+      content: component.contentText,
+      instructionRisk: classification.instructionRisk,
+      findings: classification.instructionFindings,
+      intendedUse: ["skill_instruction", "claude_command", "cursor_rule", "mcp_config"].includes(classification.sourceType)
+        ? "instruction"
+        : "evidence",
+      createdAt: previousEntry?.sourceTrust?.createdAt || previousEntry?.firstSeenAt || generatedAt,
+      updatedAt: generatedAt,
+      remediationActions: previousEntry?.sourceTrust?.remediationActions || [],
+    });
+    const firstSeenAt = previousEntry?.firstSeenAt || generatedAt;
+
+    return {
+      id,
+      type: component.type,
+      name: component.name,
+      source: component.sourcePath,
+      sourceKind: component.sourceKind,
+      status: classification.status,
+      requiresCheck: classification.requiresCheck,
+      riskLevel: classification.riskLevel,
+      trustLevel: classification.trustLevel,
+      sourceType: classification.sourceType,
+      sourceTrust,
+      instructionRisk: classification.instructionRisk,
+      instructionSignals: classification.instructionSignals,
+      instructionFindings: classification.instructionFindings,
+      findings: classification.findings,
+      recommendation: classification.recommendation,
+      contentHash: component.contentHash,
+      capabilities: classification.capabilities,
+      firstSeenAt,
+      lastSeenAt: generatedAt,
+      lastCheckedAt: generatedAt,
+    };
+  });
+
+  if (mode !== "visibility") {
+    return sortTrustCards(currentCards);
+  }
+
+  const currentIds = new Set(currentCards.map((card) => card.id));
+  const removedCards = previousSnapshot.components
+    .filter((item) => item && item.id && !currentIds.has(item.id))
+    .map((item) => buildRemovedTrustCard(item, generatedAt));
+
+  return sortTrustCards([...currentCards, ...removedCards]);
+}
+
+function summarizeTrustCards(mode, trustCards, generatedAt, persistedSummary = null, extras = {}) {
+  const presentCards = trustCards.filter((card) => card.status !== "removed");
+  const counts = {
+    componentsScanned: presentCards.length,
+    newComponents: trustCards.filter((card) => card.status === "new").length,
+    changedComponents: trustCards.filter((card) => card.status === "changed").length,
+    removedComponents: trustCards.filter((card) => card.status === "removed").length,
+    highRisk: presentCards.filter((card) => card.riskLevel === "high").length,
+    mediumRisk: presentCards.filter((card) => card.riskLevel === "medium").length,
+    lowRisk: presentCards.filter((card) => card.riskLevel === "low").length,
+    suspiciousInstructionSources: presentCards.filter((card) => card.instructionRisk === "medium" || card.instructionRisk === "high").length,
+    highInstructionFindings: presentCards.reduce((sum, card) => sum + (Array.isArray(card.instructionFindings)
+      ? card.instructionFindings.filter((item) => item.severity === "high").length
+      : 0), 0),
+    sourcesTreatedAsData: presentCards.filter((card) => card.sourceTrust && card.sourceTrust.allowedToInfluenceTools === false).length,
+  };
+
+  const newComponents = trustCards
+    .filter((card) => card.status === "new")
+    .slice(0, 5)
+    .map((card) => ({
+      id: card.id,
+      name: card.name,
+      type: card.type,
+    }));
+
+  const topFindings = trustCards
+    .filter((card) => card.riskLevel !== "low" || card.status !== "known")
+    .slice(0, 5)
+    .map((card) => ({
+      id: card.id,
+      name: card.name,
+      type: card.type,
+      riskLevel: card.riskLevel,
+      status: card.status,
+      recommendation: card.recommendation,
+    }));
+
+  if (mode === "visibility") {
+    return {
+      summaryVersion: 2,
+      what: "Agent Security Visibility summary.",
+      mode,
+      generatedAt,
+      lastCompletedCheckAt: persistedSummary?.generatedAt || null,
+      componentsScanned: counts.componentsScanned,
+      newComponents: counts.newComponents,
+      changedComponents: counts.changedComponents,
+      removedComponents: counts.removedComponents,
+      highRisk: counts.highRisk,
+      mediumRisk: counts.mediumRisk,
+      lowRisk: counts.lowRisk,
+      suspiciousInstructionSources: counts.suspiciousInstructionSources,
+      highInstructionFindings: counts.highInstructionFindings,
+      sourcesTreatedAsData: counts.sourcesTreatedAsData,
+      riskIncreases: Number(extras.riskIncreases || 0),
+      permissionExpansions: Number(extras.permissionExpansions || 0),
+      permissionPreviews: Number(extras.permissionPreviews || 0),
+      newComponentNames: newComponents.map((item) => item.name),
+      newComponentsList: newComponents,
+      topFindings,
+      externalScannersRequired: false,
+    };
+  }
+
+  return {
+    summaryVersion: 1,
+    what: "Agent Security Basic Check summary.",
+    mode,
+    generatedAt,
+    lastCompletedCheckAt: persistedSummary?.generatedAt || null,
+    componentsScanned: counts.componentsScanned,
+    newComponents: counts.newComponents,
+    highRisk: counts.highRisk,
+    mediumRisk: counts.mediumRisk,
+    lowRisk: counts.lowRisk,
+    suspiciousInstructionSources: counts.suspiciousInstructionSources,
+    highInstructionFindings: counts.highInstructionFindings,
+    sourcesTreatedAsData: counts.sourcesTreatedAsData,
+    newComponentNames: newComponents.map((item) => item.name),
+    newComponentsList: newComponents,
+    topFindings,
+    externalScannersRequired: false,
+  };
+}
+
+function capabilityExpansions(previousCapabilities, currentCapabilities) {
+  const expansions = [];
+  CAPABILITY_KEYS.forEach((key) => {
+    if (!previousCapabilities?.[key] && currentCapabilities?.[key]) expansions.push(key);
+  });
+  return expansions;
+}
+
+function buildRiskDiff(previousSnapshot, trustCards, generatedAt) {
+  const currentPresent = trustCards.filter((card) => card.status !== "removed");
+  const currentById = {};
+  currentPresent.forEach((card) => {
+    currentById[card.id] = card;
+  });
+
+  const changes = [];
+  let added = 0;
+  let changed = 0;
+  let removed = 0;
+  let riskIncreases = 0;
+  let permissionExpansions = 0;
+
+  currentPresent.forEach((card) => {
+    const previousEntry = previousSnapshot.componentsById[card.id] || null;
+    if (!previousEntry) {
+      added += 1;
+      changes.push({
+        id: card.id,
+        name: card.name,
+        type: card.type,
+        changeType: "added",
+        previousRisk: null,
+        currentRisk: card.riskLevel,
+        reasons: ["New component added to the local agent surface"],
+      });
+      return;
+    }
+
+    const reasons = [];
+    const permissionExpansionKeys = capabilityExpansions(previousEntry.capabilities, card.capabilities);
+    if (previousEntry.contentHash !== card.contentHash) reasons.push("Component content hash changed");
+    if (previousEntry.source !== card.source) reasons.push("Component source path changed");
+    if (permissionExpansionKeys.length > 0) {
+      permissionExpansions += 1;
+      reasons.push(`Permission expansion: ${permissionExpansionKeys.join(", ")}`);
+    }
+    if (riskRank(card.riskLevel) > riskRank(previousEntry.riskLevel)) {
+      riskIncreases += 1;
+      reasons.push(`Risk increased from ${previousEntry.riskLevel || "low"} to ${card.riskLevel}`);
+    }
+    if (!reasons.length) return;
+
+    changed += 1;
+    changes.push({
+      id: card.id,
+      name: card.name,
+      type: card.type,
+      changeType: "changed",
+      previousRisk: previousEntry.riskLevel || "low",
+      currentRisk: card.riskLevel,
+      reasons,
+    });
+  });
+
+  previousSnapshot.components.forEach((previousEntry) => {
+    if (currentById[previousEntry.id]) return;
+    removed += 1;
+    changes.push({
+      id: previousEntry.id,
+      name: previousEntry.name,
+      type: previousEntry.type,
+      changeType: "removed",
+      previousRisk: previousEntry.riskLevel || "low",
+      currentRisk: null,
+      reasons: ["Component was present in the previous recorded scan but is no longer detected"],
+    });
+  });
+
+  return {
+    generatedAt,
+    summary: {
+      added,
+      changed,
+      removed,
+      riskIncreases,
+      permissionExpansions,
+    },
+    changes,
+  };
+}
+
+function buildPermissionPreview(trustCards, generatedAt) {
+  const previews = trustCards
+    .filter((card) => card.status !== "removed")
+    .filter((card) => {
+      const caps = card.capabilities || emptyCapabilities();
+      return (
+        card.type === "mcp" ||
+        card.type === "package-script" ||
+        card.type === "workflow" ||
+        card.type === "sensitive-surface" ||
+        caps.filesystemWrite ||
+        caps.shell ||
+        caps.network ||
+        caps.externalMutation ||
+        caps.sensitiveAccess
+      );
+    })
+    .map((card) => {
+      const currentCapabilities = CAPABILITY_KEYS.filter((key) => card.capabilities?.[key]);
+      let recommendedMode = "read-only";
+      let ttlRecommendation = "No TTL needed for read-only components.";
+      const wouldAllow = [];
+      const wouldLimit = [];
+      let reason = "Local read-only components can stay visible without tighter controls.";
+
+      if (card.capabilities?.externalMutation || card.capabilities?.mcpWrite || card.capabilities?.sensitiveAccess) {
+        recommendedMode = "approval-required";
+        ttlRecommendation = "30 minutes for write actions";
+        reason = "External mutation or sensitive access should be scoped and time-bound.";
+      } else if (card.capabilities?.filesystemWrite || card.capabilities?.shell || card.capabilities?.network) {
+        recommendedMode = "scoped-write";
+        ttlRecommendation = "15 minutes for shell or write-capable actions";
+        reason = "Write-capable or shell-capable components should run with a bounded scope.";
+      }
+
+      if (card.type === "mcp") {
+        wouldAllow.push("read repository metadata");
+        if (card.capabilities?.mcpWrite || card.capabilities?.externalMutation) {
+          wouldAllow.push("create pull request or issue updates with review");
+          wouldLimit.push("no delete actions");
+          wouldLimit.push("no workflow or secrets modification");
+          wouldLimit.push("no push to main without approval");
+        } else {
+          wouldAllow.push("read external system state");
+          wouldLimit.push("no external write actions");
+        }
+      } else if (card.type === "package-script" || card.capabilities?.shell) {
+        wouldAllow.push("run declared local commands");
+        wouldLimit.push("no remote script execution without review");
+        wouldLimit.push("no background shell escalation");
+      } else if (card.type === "sensitive-surface" || card.capabilities?.sensitiveAccess) {
+        wouldAllow.push("inspect presence of sensitive surfaces");
+        wouldLimit.push("no secret value reads");
+        wouldLimit.push("no credential export or copying");
+      } else if (card.capabilities?.filesystemWrite) {
+        wouldAllow.push("modify project files within the working tree");
+        wouldLimit.push("no destructive delete actions");
+      } else {
+        wouldAllow.push("read local configuration");
+        wouldLimit.push("no write actions by default");
+      }
+
+      return {
+        componentId: card.id,
+        name: card.name,
+        type: card.type,
+        currentCapabilities,
+        recommendedMode,
+        wouldAllow,
+        wouldLimit,
+        ttlRecommendation,
+        reason,
+      };
+    });
+
+  return {
+    generatedAt,
+    previews,
+  };
+}
+
+function summaryPathForMode(mode) {
+  return mode === "visibility" ? VISIBILITY_SUMMARY_REL_PATH : SUMMARY_REL_PATH;
+}
+
+function loadLatestAgentSecuritySummary(cwd, mode = "basic") {
+  return safeReadJson(cwd, summaryPathForMode(mode), null);
+}
+
+function loadTrustCardsEvidence(cwd) {
+  const doc = safeReadJson(cwd, TRUST_CARDS_REL_PATH, null);
+  return Array.isArray(doc?.items) ? doc.items : [];
+}
+
+function loadAgentSecurityEvidenceBundle(cwd, mode) {
+  return {
+    summary: loadLatestAgentSecuritySummary(cwd, mode),
+    trustCards: loadTrustCardsEvidence(cwd),
+    riskDiff: mode === "visibility" ? safeReadJson(cwd, RISK_DIFF_REL_PATH, null) : null,
+    permissionPreview: mode === "visibility" ? safeReadJson(cwd, PERMISSION_PREVIEW_REL_PATH, null) : null,
+  };
+}
+
+function loadPersistedInventoryForActions(cwd) {
+  return {
+    trustCards: loadTrustCardsEvidence(cwd),
+    summary: loadLatestAgentSecuritySummary(cwd, "visibility") || loadLatestAgentSecuritySummary(cwd, "basic"),
+  };
+}
+
+function buildSourceTrustDocument(generatedAt, trustCards) {
+  return {
+    sourceTrustVersion: 1,
+    what: "Agent Security source trust classifications.",
+    generatedAt,
+    items: trustCards
+      .filter((card) => card.status !== "removed")
+      .map((card) => ({
+        ...card.sourceTrust,
+        sourceId: card.id,
+      })),
+  };
+}
+
+function buildInstructionRiskDocument(generatedAt, trustCards) {
+  const items = trustCards
+    .filter((card) => card.status !== "removed")
+    .filter((card) => card.instructionRisk !== "low" || (Array.isArray(card.instructionFindings) && card.instructionFindings.length > 0))
+    .map((card) => ({
+      sourceId: card.id,
+      sourceType: card.sourceType,
+      name: card.name,
+      source: card.source,
+      instructionRisk: card.instructionRisk,
+      signals: card.instructionSignals || [],
+      findings: (card.instructionFindings || []).map((finding) => ({
+        category: finding.category,
+        severity: finding.severity,
+        message: finding.message,
+        evidencePreview: boundedPreview(finding.evidencePreview || "", 120),
+        location: finding.location || null,
+      })),
+      recommendation: card.sourceTrust?.recommendation || card.recommendation,
+    }));
+
+  return {
+    instructionRiskVersion: 1,
+    what: "Agent Security instruction risk findings.",
+    generatedAt,
+    counts: {
+      suspiciousSources: items.length,
+      highRiskSources: items.filter((item) => item.instructionRisk === "high").length,
+      highRiskFindings: items.reduce((sum, item) => sum + item.findings.filter((finding) => finding.severity === "high").length, 0),
+    },
+    items,
+  };
+}
+
+function writeInstructionRiskEvidence(cwd, generatedAt, trustCards, mode, options = {}) {
+  const sourceTrustDoc = buildSourceTrustDocument(generatedAt, trustCards);
+  const instructionRiskDoc = buildInstructionRiskDocument(generatedAt, trustCards);
+  safeWriteJson(cwd, SOURCE_TRUST_REL_PATH, sourceTrustDoc);
+  safeWriteJson(cwd, INSTRUCTION_RISK_REL_PATH, instructionRiskDoc);
+
+  if (options.writeAudit !== false) {
+    sourceTrustDoc.items.forEach((item) => {
+      appendJsonl(cwd, INSTRUCTION_AUDIT_LOG_REL_PATH, {
+        eventType: "agent_security_source_trust_classified",
+        mode,
+        sourceId: item.sourceId,
+        sourceType: item.sourceType,
+        trustLevel: item.trustLevel,
+        instructionRisk: item.instructionRisk,
+        signals: [],
+        reason: item.recommendation,
+        timestamp: generatedAt,
+      });
+    });
+    instructionRiskDoc.items.forEach((item) => {
+      appendJsonl(cwd, INSTRUCTION_AUDIT_LOG_REL_PATH, {
+        eventType: "agent_security_instruction_risk_detected",
+        mode,
+        sourceId: item.sourceId,
+        sourceType: item.sourceType,
+        trustLevel: sourceTrustDoc.items.find((source) => source.sourceId === item.sourceId)?.trustLevel || "unknown",
+        instructionRisk: item.instructionRisk,
+        signals: item.signals,
+        reason: item.recommendation,
+        timestamp: generatedAt,
+      });
+    });
+  }
+
+  return {
+    sourceTrustPath: SOURCE_TRUST_REL_PATH,
+    instructionRiskPath: INSTRUCTION_RISK_REL_PATH,
+    auditPath: INSTRUCTION_AUDIT_LOG_REL_PATH,
+  };
+}
+
+function loadInstructionRemediations(cwd) {
+  const doc = safeReadJson(cwd, INSTRUCTION_REMEDIATIONS_REL_PATH, null);
+  if (!doc || typeof doc !== "object" || !Array.isArray(doc.items)) {
+    return {
+      remediationVersion: 1,
+      items: [],
+    };
+  }
+  return doc;
+}
+
+function activeRemediationActionsBySource(cwd) {
+  const doc = loadInstructionRemediations(cwd);
+  const bySource = new Map();
+  doc.items.forEach((item) => {
+    if (!item || !item.sourceId) return;
+    const actions = bySource.get(item.sourceId) || [];
+    actions.push(String(item.action || ""));
+    bySource.set(item.sourceId, actions);
+  });
+  return bySource;
+}
+
+function loadSourceTrustRecords(cwd) {
+  const doc = safeReadJson(cwd, SOURCE_TRUST_REL_PATH, null);
+  if (!doc || typeof doc !== "object" || !Array.isArray(doc.items)) return [];
+  const remediationMap = activeRemediationActionsBySource(cwd);
+  return doc.items.map((item) => ({
+    ...item,
+    remediationActions: remediationMap.get(item.sourceId) || item.remediationActions || [],
+    allowedToInfluenceTools: (remediationMap.get(item.sourceId) || []).includes("trust_source")
+      ? item.allowedToInfluenceTools
+      : item.allowedToInfluenceTools && !(remediationMap.get(item.sourceId) || []).some((action) => action === "treat_as_data_only" || action === "quarantine_source"),
+  }));
+}
+
+function resolveRelatedSourcesForAction(cwd, action, componentCard) {
+  const sourceRecords = loadSourceTrustRecords(cwd);
+  const requestedIds = Array.isArray(action?.relatedSourceIds)
+    ? action.relatedSourceIds
+    : Array.isArray(action?.context?.relatedSourceIds)
+      ? action.context.relatedSourceIds
+      : [];
+  const ids = requestedIds.length > 0
+    ? requestedIds.map((item) => String(item || "")).filter(Boolean)
+    : componentCard?.id
+      ? [componentCard.id]
+      : [];
+  if (!ids.length) return [];
+  const byId = new Map(sourceRecords.map((item) => [item.sourceId, item]));
+  const resolved = ids.map((id) => byId.get(id)).filter(Boolean);
+  if (resolved.length === 0 && componentCard?.sourceTrust && ids.includes(componentCard.id)) {
+    resolved.push({
+      ...componentCard.sourceTrust,
+      sourceId: componentCard.id,
+      sourceType: componentCard.sourceType || componentCard.sourceTrust.sourceType,
+      instructionRisk: componentCard.instructionRisk || componentCard.sourceTrust.instructionRisk || "low",
+      remediationActions: componentCard.sourceTrust.remediationActions || [],
+    });
+  }
+  return resolved;
+}
+
+function recordAgentSecurityOperation(cwd, operation, tracker, details, writeEvidence) {
+  if (writeEvidence === false || !tracker) return null;
+  const entry = tracker.finish({
+    operation,
+    ...details,
+  });
+  recordPerformanceSummary(cwd, entry);
+  return entry;
+}
+
+function writeBasicEvidence(cwd, generatedAt, previousSnapshot, trustCards) {
+  const summary = summarizeTrustCards("basic", trustCards, generatedAt, null);
+  const nextSnapshot = buildMergedSnapshot(previousSnapshot, "basic", trustCards.filter((card) => card.status !== "removed"), generatedAt);
+  const instructionEvidence = writeInstructionRiskEvidence(cwd, generatedAt, trustCards, "basic");
+
+  safeWriteJson(cwd, SNAPSHOT_REL_PATH, nextSnapshot);
+  safeWriteJson(cwd, SUMMARY_REL_PATH, summary);
+  safeWriteJson(cwd, TRUST_CARDS_REL_PATH, {
+    trustCardsVersion: 1,
+    what: "Agent Security trust cards.",
+    generatedAt,
+    items: trustCards,
+  });
+
+  appendJsonl(cwd, AUDIT_LOG_REL_PATH, {
+    eventType: "agent_security_basic_check",
+    mode: "basic",
+    componentsScanned: summary.componentsScanned,
+    newComponents: summary.newComponents,
+    highRisk: summary.highRisk,
+    mediumRisk: summary.mediumRisk,
+    lowRisk: summary.lowRisk,
+    timestamp: generatedAt,
+  });
+
+  return {
+    snapshotPath: SNAPSHOT_REL_PATH,
+    summaryPath: SUMMARY_REL_PATH,
+    trustCardsPath: TRUST_CARDS_REL_PATH,
+    sourceTrustPath: instructionEvidence.sourceTrustPath,
+    instructionRiskPath: instructionEvidence.instructionRiskPath,
+    performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+    scanCachePath: SCAN_CACHE_REL_PATH,
+    auditPath: AUDIT_LOG_REL_PATH,
+    summary,
+  };
+}
+
+function writeVisibilityEvidence(cwd, generatedAt, previousSnapshot, trustCards) {
+  const riskDiff = buildRiskDiff(previousSnapshot, trustCards, generatedAt);
+  const permissionPreview = buildPermissionPreview(trustCards, generatedAt);
+  const summary = summarizeTrustCards("visibility", trustCards, generatedAt, null, {
+    riskIncreases: riskDiff.summary.riskIncreases,
+    permissionExpansions: riskDiff.summary.permissionExpansions,
+    permissionPreviews: permissionPreview.previews.length,
+  });
+  const nextSnapshot = buildMergedSnapshot(previousSnapshot, "visibility", trustCards.filter((card) => card.status !== "removed"), generatedAt);
+  const instructionEvidence = writeInstructionRiskEvidence(cwd, generatedAt, trustCards, "visibility");
+
+  safeWriteJson(cwd, SNAPSHOT_REL_PATH, nextSnapshot);
+  safeWriteJson(cwd, VISIBILITY_SUMMARY_REL_PATH, summary);
+  safeWriteJson(cwd, TRUST_CARDS_REL_PATH, {
+    trustCardsVersion: 2,
+    what: "Agent Security trust cards.",
+    generatedAt,
+    items: trustCards,
+  });
+  safeWriteJson(cwd, RISK_DIFF_REL_PATH, riskDiff);
+  safeWriteJson(cwd, PERMISSION_PREVIEW_REL_PATH, permissionPreview);
+
+  appendJsonl(cwd, AUDIT_LOG_REL_PATH, {
+    eventType: "agent_security_visibility_scan",
+    mode: "visibility",
+    componentsScanned: summary.componentsScanned,
+    newComponents: summary.newComponents,
+    changedComponents: summary.changedComponents,
+    riskIncreases: summary.riskIncreases,
+    permissionExpansions: summary.permissionExpansions,
+    highRisk: summary.highRisk,
+    mediumRisk: summary.mediumRisk,
+    timestamp: generatedAt,
+  });
+
+  return {
+    snapshotPath: SNAPSHOT_REL_PATH,
+    summaryPath: VISIBILITY_SUMMARY_REL_PATH,
+    trustCardsPath: TRUST_CARDS_REL_PATH,
+    sourceTrustPath: instructionEvidence.sourceTrustPath,
+    instructionRiskPath: instructionEvidence.instructionRiskPath,
+    performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+    scanCachePath: SCAN_CACHE_REL_PATH,
+    riskDiffPath: RISK_DIFF_REL_PATH,
+    permissionPreviewPath: PERMISSION_PREVIEW_REL_PATH,
+    auditPath: AUDIT_LOG_REL_PATH,
+    summary,
+    riskDiff,
+    permissionPreview,
+  };
+}
+
+function loadDecisionSummary(cwd) {
+  return safeReadJson(cwd, DECISION_SUMMARY_REL_PATH, null);
+}
+
+function saveDecisionSummary(cwd, summary) {
+  safeWriteJson(cwd, DECISION_SUMMARY_REL_PATH, summary);
+  return summary;
+}
+
+function updateDecisionSummary(cwd, payload) {
+  const previous = loadDecisionSummary(cwd) || {
+    decisionSummaryVersion: 1,
+    what: "Agent Security warn-mode decision summary.",
+    generatedAt: null,
+    mode: "warn",
+    counts: {
+      approveOnce: 0,
+      denied: 0,
+      limited: 0,
+    },
+    latestDecision: null,
+    recentDecisions: [],
+  };
+
+  const counts = {
+    approveOnce: Number(previous.counts?.approveOnce || 0),
+    denied: Number(previous.counts?.denied || 0),
+    limited: Number(previous.counts?.limited || 0),
+  };
+
+  if (payload.decision === "approve_once") counts.approveOnce += 1;
+  if (payload.decision === "deny") counts.denied += 1;
+  if (payload.decision === "let_wuz_limit") counts.limited += 1;
+
+  const nextDecision = {
+    decision: payload.decision,
+    effectiveBehavior: payload.effectiveBehavior,
+    actionId: payload.actionId,
+    componentId: payload.componentId,
+    componentType: payload.componentType,
+    actionType: payload.actionType,
+    riskLevel: payload.riskLevel,
+    timestamp: payload.timestamp,
+  };
+
+  const recentDecisions = [nextDecision, ...(Array.isArray(previous.recentDecisions) ? previous.recentDecisions : [])]
+    .slice(0, 5);
+
+  return saveDecisionSummary(cwd, {
+    decisionSummaryVersion: 1,
+    what: "Agent Security warn-mode decision summary.",
+    generatedAt: payload.timestamp,
+    mode: "warn",
+    counts,
+    latestDecision: nextDecision,
+    recentDecisions,
+  });
+}
+
+function resolveComponentCard(trustCards, action) {
+  if (!Array.isArray(trustCards)) return null;
+  if (action?.componentId) {
+    const exact = trustCards.find((card) => card.id === action.componentId);
+    if (exact) return exact;
+  }
+  if (action?.componentType && action?.source) {
+    const exactSource = trustCards.find((card) => card.type === action.componentType && card.source === action.source);
+    if (exactSource) return exactSource;
+  }
+  if (action?.componentType && action?.target) {
+    const byTarget = trustCards.find((card) => card.type === action.componentType && String(action.target).includes(card.name));
+    if (byTarget) return byTarget;
+  }
+  return null;
+}
+
+function effectiveBehaviorForDecision(decision) {
+  if (decision === "deny") return "deny_recommended";
+  if (decision === "let_wuz_limit") return "limit_plan_only";
+  if (decision === "auto_allow_limited") return "limited";
+  if (decision === "auto_deny") return "blocked";
+  return "allowed";
+}
+
+function ttlSecondsFromRecommendation(value) {
+  const normalized = String(value || "").toLowerCase();
+  if (normalized.includes("30 minute")) return 1800;
+  if (normalized.includes("15 minute")) return 900;
+  if (normalized.includes("this session")) return null;
+  if (normalized.includes("once")) return null;
+  return null;
+}
+
+function buildDecisionRecord(input) {
+  return {
+    decisionId: `decision-${shortHash(`${input.timestamp}:${input.actionId}:${input.decision}`)}`,
+    actionId: input.actionId,
+    componentId: input.componentId || null,
+    decision: input.decision,
+    mode: input.mode || "warn",
+    effectiveBehavior: effectiveBehaviorForDecision(input.decision),
+    ttlSeconds: ttlSecondsFromRecommendation(input.limitPlan?.ttlRecommendation || input.ttlRecommendation),
+    scope: input.limitPlan?.scope || {
+      actionType: input.actionType || null,
+      target: input.target || null,
+    },
+    denied: input.limitPlan?.wouldDeny || [],
+    reason: input.limitPlan?.reason || input.reason || "",
+    timestamp: input.timestamp,
+  };
+}
+
+function writeDecisionAuditEvents(cwd, payload) {
+  const baseEvent = {
+    mode: "warn",
+    actionId: payload.actionId,
+    componentId: payload.componentId || null,
+    componentType: payload.componentType || null,
+    actionType: payload.actionType,
+    riskLevel: payload.riskLevel,
+    recommendedDecision: payload.recommendedDecision,
+    userDecision: payload.userDecision,
+    effectiveBehavior: payload.effectiveBehavior,
+    timestamp: payload.timestamp,
+  };
+
+  appendJsonl(cwd, DECISION_AUDIT_LOG_REL_PATH, {
+    eventType: "agent_security_action_preflight",
+    ...baseEvent,
+  });
+  appendJsonl(cwd, DECISION_AUDIT_LOG_REL_PATH, {
+    eventType: "agent_security_decision_recorded",
+    ...baseEvent,
+  });
+
+  if (payload.userDecision === "let_wuz_limit" && payload.limitPlan) {
+    appendJsonl(cwd, DECISION_AUDIT_LOG_REL_PATH, {
+      eventType: "agent_security_limit_plan_created",
+      ...baseEvent,
+      ttlRecommendation: payload.limitPlan.ttlRecommendation || null,
+      denied: payload.limitPlan.wouldDeny || [],
+    });
+  }
+}
+
+function buildBasicStatusLine(summary, options = {}) {
+  if (!summary) return null;
+  const needsBaselineRecording = options.needsBaselineRecording === true;
+  if (summary.newComponents > 0) {
+    if (needsBaselineRecording) {
+      return "Agent security: New component detected. Run Basic Check to record it as reviewed.";
+    }
+    return `Agent security: ${summary.newComponents} new component${summary.newComponents === 1 ? "" : "s"} need review`;
+  }
+  if (summary.highRisk > 0) {
+    return `Agent security: ${summary.highRisk} high risk component${summary.highRisk === 1 ? "" : "s"} need review`;
+  }
+  if (summary.suspiciousInstructionSources > 0) {
+    return `Agent security: Basic check passed - ${pluralize(summary.suspiciousInstructionSources, "suspicious instruction source")}`;
+  }
+  return `Agent security: Basic check passed - ${summary.componentsScanned} components - 0 high risk`;
+}
+
+function buildBasicDashboardBlurb(summary, options = {}) {
+  if (!summary) return null;
+  const needsBaselineRecording = options.needsBaselineRecording === true;
+  const blurb = {
+    title: "Basic Skill/MCP Check",
+    headline: "Basic Check active",
+    summary: summary.suspiciousInstructionSources > 0
+      ? `${summary.componentsScanned} components - ${pluralize(summary.suspiciousInstructionSources, "suspicious instruction source")}`
+      : `${summary.componentsScanned} components - ${summary.highRisk} high risk`,
+    nextBestAction: needsBaselineRecording && summary.newComponents > 0
+      ? "Run Basic Check to record new components as reviewed."
+      : null,
+    detailsAvailable: true,
+    checkedLabel: `${summary.componentsScanned} components checked`,
+    newLabel: `${summary.newComponents} new component${summary.newComponents === 1 ? "" : "s"}`,
+    riskLabel: `${summary.highRisk} high risk`,
+  };
+  if (needsBaselineRecording && summary.newComponents > 0) {
+    blurb.note = "New AI component detected. Run Basic Check to record it as reviewed.";
+  }
+  return blurb;
+}
+
+function pluralize(count, singular, plural) {
+  return `${count} ${count === 1 ? singular : (plural || `${singular}s`)}`;
+}
+
+function buildProductSummary(mode, fields = {}) {
+  return {
+    mode,
+    headline: fields.headline || "",
+    summary: fields.summary || "",
+    safeActionsLimited: Number(fields.safeActionsLimited || 0),
+    actionsBlocked: Number(fields.actionsBlocked || 0),
+    approvalRequired: Number(fields.approvalRequired || 0),
+    jitGrantsActive: Number(fields.jitGrantsActive || 0),
+    instructionRiskSources: Number(fields.instructionRiskSources || 0),
+    sourcesTreatedAsData: Number(fields.sourcesTreatedAsData || 0),
+    remediationsActive: Number(fields.remediationsActive || 0),
+    performance: fields.performance || { lastOperationMs: null, slow: false },
+    nextBestAction: fields.nextBestAction || null,
+    detailsAvailable: fields.detailsAvailable !== false,
+  };
+}
+
+function buildBasicProductSummary(summary, options = {}) {
+  const needsBaselineRecording = options.needsBaselineRecording === true;
+  return buildProductSummary("basic", {
+    headline: "Basic Check active",
+    summary: needsBaselineRecording && summary.newComponents > 0
+      ? `${pluralize(summary.newComponents, "new component")} needs review`
+      : summary.suspiciousInstructionSources > 0
+        ? `${pluralize(summary.componentsScanned, "component")} - ${pluralize(summary.suspiciousInstructionSources, "suspicious instruction source")}`
+        : `${pluralize(summary.componentsScanned, "component")} - ${summary.highRisk} high risk`,
+    nextBestAction: needsBaselineRecording && summary.newComponents > 0
+      ? "Run Basic Check to record new components as reviewed."
+      : summary.suspiciousInstructionSources > 0
+        ? `Review ${pluralize(summary.suspiciousInstructionSources, "suspicious instruction source")}.`
+      : null,
+    performance: options.performance || { lastOperationMs: null, slow: false },
+  });
+}
+
+function visibilityRiskLabel(summary) {
+  if (summary.highRisk > 0) return "High risk";
+  if (summary.mediumRisk > 0) return "Medium risk";
+  return "Low risk";
+}
+
+function buildVisibilityStatusLine(summary, options = {}) {
+  if (!summary) return null;
+  const needsBaselineRecording = options.needsBaselineRecording === true;
+  if (needsBaselineRecording && summary.newComponents > 0) {
+    return "Agent security: New component detected. Run Visibility Scan to record it as reviewed.";
+  }
+  if (needsBaselineRecording && (summary.changedComponents > 0 || summary.removedComponents > 0)) {
+    return "Agent security: Surface change detected. Run Visibility Scan to record it as reviewed.";
+  }
+  if (summary.highRisk === 0 && summary.permissionExpansions === 0 && summary.newComponents === 0 && summary.changedComponents === 0) {
+    return `Agent security: Visibility clean - ${summary.componentsScanned} components - 0 high risk`;
+  }
+  if (summary.suspiciousInstructionSources > 0) {
+    return `Agent security: Visibility - ${pluralize(summary.suspiciousInstructionSources, "suspicious instruction source")} - ${summary.componentsScanned} components`;
+  }
+  return `Agent security: Visibility - ${summary.componentsScanned} components - ${summary.highRisk} high risk - ${summary.permissionExpansions} permission expansion${summary.permissionExpansions === 1 ? "" : "s"}`;
+}
+
+function buildVisibilityDashboardCard(summary, options = {}) {
+  if (!summary) return null;
+  const needsBaselineRecording = options.needsBaselineRecording === true;
+  const topFinding = (summary.topFindings || []).find((item) => item.riskLevel === "high") || summary.topFindings?.[0] || null;
+  const card = {
+    title: "Agent Security",
+    subtitle: `Full visibility - ${visibilityRiskLabel(summary)}`,
+    headline: "Visibility active",
+    summary: `${pluralize(summary.componentsScanned, "component")} - ${summary.highRisk} high risk - ${pluralize(summary.permissionExpansions, "permission expansion")}`,
+    nextBestAction: needsBaselineRecording && summary.newComponents > 0
+      ? "Run Visibility Scan to record the new baseline."
+      : null,
+    detailsAvailable: true,
+    surfaceLabel: `${summary.componentsScanned} components mapped`,
+    changeLabel: `${summary.newComponents} new - ${summary.changedComponents} changed - ${summary.permissionExpansions} permission expansion${summary.permissionExpansions === 1 ? "" : "s"}`,
+    topRiskLabel: topFinding
+      ? `Top risk: ${topFinding.name} ${topFinding.type === "mcp" ? "MCP" : topFinding.type} ${topFinding.riskLevel === "high" ? "needs review" : "changed"}`
+      : "Top risk: No high-risk findings",
+    previewLabel: `${summary.permissionPreviews || 0} permission preview${summary.permissionPreviews === 1 ? "" : "s"}`,
+  };
+  if (needsBaselineRecording && summary.newComponents > 0) {
+    card.note = "New AI component detected. Run Visibility Scan to record it as reviewed.";
+  } else if (needsBaselineRecording && (summary.changedComponents > 0 || summary.removedComponents > 0)) {
+    card.note = "Agent surface changed. Run Visibility Scan to record the new baseline.";
+  }
+  return card;
+}
+
+function buildWarnEnforcementLabel(enforcementSummary) {
+  const counts = enforcementSummary?.counts || {};
+  const blocked = Number(counts.blocked || 0);
+  const approvedOnce = Number(counts.approvedOnce || 0);
+  const limited = Number(counts.limited || 0);
+  const unavailable = Number(counts.unavailable || 0);
+  const fileWritesBlocked = Number(counts.fileWritesBlocked || 0);
+  const fileWritesLimited = Number(counts.fileWritesLimited || 0);
+  const fileWritesApprovedOnce = Number(counts.fileWritesApprovedOnce || 0);
+  const packageActionsBlocked = Number(counts.packageActionsBlocked || 0);
+  const packageActionsLimited = Number(counts.packageActionsLimited || 0);
+  const packageActionsApprovedOnce = Number(counts.packageActionsApprovedOnce || 0);
+  const mcpActionsBlocked = Number(counts.mcpActionsBlocked || 0);
+  const mcpActionsLimited = Number(counts.mcpActionsLimited || 0);
+  const mcpActionsApprovedOnce = Number(counts.mcpActionsApprovedOnce || 0);
+  const specificBlockedKinds = [
+    mcpActionsBlocked > 0,
+    packageActionsBlocked > 0,
+    fileWritesBlocked > 0,
+  ].filter(Boolean).length;
+  const specificLimitedKinds = [
+    mcpActionsLimited > 0,
+    packageActionsLimited > 0,
+    fileWritesLimited > 0,
+  ].filter(Boolean).length;
+
+  if (specificBlockedKinds > 1) return `${blocked} actions blocked`;
+  if (specificLimitedKinds > 1 && blocked === 0) return `${limited} actions limited`;
+  if (mcpActionsBlocked > 0) return `${mcpActionsBlocked} MCP action blocked`;
+  if (mcpActionsLimited > 0) return `${mcpActionsLimited} MCP action limited`;
+  if (mcpActionsApprovedOnce > 0) return `${mcpActionsApprovedOnce} MCP action approved once`;
+
+  if (packageActionsBlocked > 0) return `${packageActionsBlocked} package action blocked`;
+  if (packageActionsLimited > 0) return `${packageActionsLimited} package action limited`;
+  if (packageActionsApprovedOnce > 0) return `${packageActionsApprovedOnce} package action approved once`;
+
+  if (fileWritesBlocked > 0) return `${fileWritesBlocked} file write blocked`;
+  if (fileWritesLimited > 0) return `${fileWritesLimited} file write limited`;
+  if (fileWritesApprovedOnce > 0) return `${fileWritesApprovedOnce} file write approved once`;
+
+  if (blocked > 0) return `${blocked} action blocked`;
+  if (approvedOnce > 0) return `${approvedOnce} approved once`;
+  if (limited > 0) return `${limited} action limited`;
+  if (unavailable > 0) return `${unavailable} unavailable`;
+  return "no enforced actions yet";
+}
+
+function buildWarnProductSummary(summary, decisionSummary, enforcementSummary) {
+  const enforcementCounts = enforcementSummary?.counts || {};
+  const decisionCounts = decisionSummary?.counts || {};
+  const blocked = Number(enforcementCounts.blocked || 0);
+  const limited = Number(enforcementCounts.limited || 0);
+  const approvedOnce = Number(enforcementCounts.approvedOnce || 0) + Number(decisionCounts.approveOnce || 0);
+  const nextBestAction = summary.highRisk > 0
+    ? `Review ${pluralize(summary.highRisk, "high-risk action")} before proceeding.`
+    : null;
+
+  if (blocked > 0 || limited > 0 || approvedOnce > 0) {
+    const parts = [];
+    if (limited > 0) parts.push(`${pluralize(limited, "action")} limited`);
+    if (blocked > 0) parts.push(`${pluralize(blocked, "action")} blocked`);
+    if (approvedOnce > 0) parts.push(`${pluralize(approvedOnce, "action")} approved once`);
+    return buildProductSummary("warn", {
+      headline: "Warn & Approve active",
+      summary: parts.join(" - "),
+      safeActionsLimited: limited,
+      actionsBlocked: blocked,
+      approvalRequired: summary.highRisk,
+      nextBestAction,
+      performance: buildCompactPerformanceSummary(summary.cwd || "", ["agent_security_preflight", "agent_security_guarded_action"]),
+    });
+  }
+
+  return buildProductSummary("warn", {
+    headline: "Warn & Approve active",
+    summary: "Approvals enabled",
+    approvalRequired: summary.highRisk,
+    nextBestAction,
+    performance: buildCompactPerformanceSummary(summary.cwd || "", ["agent_security_preflight", "agent_security_guarded_action"]),
+  });
+}
+
+function buildWarnStatusLine(summary, decisionSummary, enforcementSummary) {
+  const enforcementCounts = enforcementSummary?.counts || {};
+  const hasEnforcementActivity =
+    Number(enforcementCounts.attempted || 0) > 0 ||
+    Number(enforcementCounts.blocked || 0) > 0 ||
+    Number(enforcementCounts.approvedOnce || 0) > 0 ||
+    Number(enforcementCounts.limited || 0) > 0 ||
+    Number(enforcementCounts.unavailable || 0) > 0;
+
+  if (hasEnforcementActivity) {
+    return `Agent security: Warn mode - approvals enabled - ${buildWarnEnforcementLabel(enforcementSummary)}`;
+  }
+
+  const counts = decisionSummary?.counts || {};
+  const limited = Number(counts.limited || 0);
+  const denied = Number(counts.denied || 0);
+  if (limited > 0 || denied > 0) {
+    return `Agent security: Warn mode - ${limited} action limited - ${denied} denied`;
+  }
+  if (Number(summary?.suspiciousInstructionSources || 0) > 0) {
+    return "Agent security: Warn mode - approval needed for suspicious source";
+  }
+  return "Agent security: Warn mode - approvals enabled";
+}
+
+function buildWarnDashboardCard(summary, decisionSummary, enforcementSummary) {
+  const counts = decisionSummary?.counts || {};
+  const topFinding = (summary.topFindings || []).find((item) => item.riskLevel === "high") || summary.topFindings?.[0] || null;
+  const enforcementCounts = enforcementSummary?.counts || {};
+  const card = {
+    title: "Agent Security",
+    subtitle: `Warn mode active - ${summary.componentsScanned} components mapped - ${summary.highRisk} high risk`,
+    headline: "Warn & Approve active",
+    summary: Number(enforcementCounts.blocked || 0) > 0 || Number(enforcementCounts.limited || 0) > 0
+      ? buildWarnEnforcementLabel(enforcementSummary)
+      : "Approvals enabled",
+    nextBestAction: topFinding ? `Review ${topFinding.name} before continuing.` : null,
+    detailsAvailable: true,
+    surfaceLabel: `${summary.componentsScanned} components mapped`,
+    changeLabel: `${summary.newComponents} new - ${summary.changedComponents} changed - ${summary.permissionExpansions} permission expansion${summary.permissionExpansions === 1 ? "" : "s"}`,
+    decisionsLabel: `${Number(counts.approveOnce || 0)} action approved once - ${Number(counts.limited || 0)} action limited - ${Number(counts.denied || 0)} denied`,
+    pendingRiskLabel: topFinding
+      ? `Top pending risk: ${topFinding.name} ${topFinding.type === "mcp" ? "MCP" : topFinding.type} actions require approval`
+      : "Top pending risk: no high-risk findings",
+  };
+
+  if (
+    Number(enforcementCounts.attempted || 0) > 0 ||
+    Number(enforcementCounts.blocked || 0) > 0 ||
+    Number(enforcementCounts.approvedOnce || 0) > 0 ||
+    Number(enforcementCounts.limited || 0) > 0 ||
+    Number(enforcementCounts.unavailable || 0) > 0
+  ) {
+    card.enforcementLabel = buildWarnEnforcementLabel(enforcementSummary);
+  }
+
+  return card;
+}
+
+function buildAutoStatusLine(summary, enforcementSummary) {
+  const counts = enforcementSummary?.counts || {};
+  const autoLimited = Number(counts.autoLimited || 0);
+  const autoDenied = Number(counts.autoDenied || 0) || Number(counts.blocked || 0);
+  const autoRequiresApproval = Number(counts.autoRequiresApproval || 0);
+  const autoRecommendedOnly = Number(counts.autoRecommendedOnly || 0);
+  const suspiciousSources = Number(summary?.suspiciousInstructionSources || 0);
+
+  if (autoLimited > 0 || autoRequiresApproval > 0 || autoDenied > 0) {
+    const parts = [];
+    if (autoLimited > 0) parts.push(`${pluralize(autoLimited, "safe action")} limited`);
+    if (autoRequiresApproval > 0) {
+      parts.push(autoRequiresApproval === 1 ? "1 approval needed" : `${autoRequiresApproval} approvals needed`);
+    } else if (autoDenied > 0) {
+      parts.push(`${pluralize(autoDenied, "dangerous action")} blocked`);
+    }
+    if (suspiciousSources > 0) parts.push(`${pluralize(suspiciousSources, "suspicious source")} treated as data`);
+    return `Agent security: Auto-Minimize - ${parts.join(" - ")}`;
+  }
+  if (autoRecommendedOnly > 0) {
+    return `Agent security: Auto-Minimize - no safe enforcement available for ${autoRecommendedOnly} action${autoRecommendedOnly === 1 ? "" : "s"}`;
+  }
+  return "Agent security: Auto-Minimize - safe actions limited automatically - risky actions still require approval";
+}
+
+function buildAutoProductSummary(summary, enforcementSummary, options = {}) {
+  const counts = enforcementSummary?.counts || {};
+  const autoLimited = Number(counts.autoLimited || 0);
+  const autoDenied = Number(counts.autoDenied || 0) || Number(counts.blocked || 0);
+  const autoRequiresApproval = Number(counts.autoRequiresApproval || 0);
+  const autoRecommendedOnly = Number(counts.autoRecommendedOnly || 0);
+  const activeJitGrants = Number(counts.activeJitGrants || 0);
+  const suspiciousSources = Number(summary?.suspiciousInstructionSources || 0);
+  const sourcesTreatedAsData = Number(summary?.sourcesTreatedAsData || 0);
+  const activeRemediations = Number(options.activeRemediations || 0);
+  const nextBestAction = autoRequiresApproval > 0
+    ? `Review ${autoRequiresApproval} risky action${autoRequiresApproval === 1 ? "" : "s"}.`
+    : suspiciousSources > 0
+      ? `Review ${pluralize(suspiciousSources, "suspicious instruction source")}.`
+    : autoDenied > 0
+      ? `Review ${autoDenied} blocked risky action${autoDenied === 1 ? "" : "s"}.`
+      : autoRecommendedOnly > 0
+        ? `Review ${autoRecommendedOnly} unsupported action path${autoRecommendedOnly === 1 ? "" : "s"}.`
+        : null;
+
+  let compactSummary = "Safe actions limited automatically";
+  if (autoLimited > 0 || autoRequiresApproval > 0 || autoDenied > 0) {
+    const parts = [];
+    if (autoLimited > 0) parts.push(`${pluralize(autoLimited, "safe action")} limited`);
+    if (autoRequiresApproval > 0) {
+      parts.push(autoRequiresApproval === 1 ? "1 approval needed" : `${autoRequiresApproval} approvals needed`);
+    } else if (autoDenied > 0) {
+      parts.push(`${pluralize(autoDenied, "dangerous action")} blocked`);
+    }
+    compactSummary = parts.join(" - ");
+  } else if (autoRecommendedOnly > 0) {
+    compactSummary = `No safe enforcement available for ${pluralize(autoRecommendedOnly, "action")}`;
+  }
+
+  return buildProductSummary("auto", {
+    headline: "Auto-Minimize active",
+    summary: compactSummary,
+    safeActionsLimited: autoLimited,
+    actionsBlocked: autoDenied,
+    approvalRequired: autoRequiresApproval,
+    jitGrantsActive: activeJitGrants,
+    instructionRiskSources: suspiciousSources,
+    sourcesTreatedAsData,
+    remediationsActive: activeRemediations,
+    performance: options.performance || { lastOperationMs: null, slow: false },
+    nextBestAction,
+  });
+}
+
+function buildAutoDashboardCard(summary, enforcementSummary, productSummary) {
+  return {
+    title: "Agent Security",
+    subtitle: productSummary.headline || "Auto-Minimize active",
+    headline: productSummary.headline || "Auto-Minimize active",
+    summary: productSummary.summary || "Safe actions limited automatically",
+    nextBestAction: productSummary.nextBestAction || null,
+    detailsAvailable: true,
+    surfaceLabel: `${summary.componentsScanned} components mapped`,
+    changeLabel: `${summary.newComponents} new - ${summary.changedComponents} changed - ${summary.permissionExpansions} permission expansion${summary.permissionExpansions === 1 ? "" : "s"}`,
+  };
+}
+
+function buildVisibilityProductSummary(summary, options = {}) {
+  const needsBaselineRecording = options.needsBaselineRecording === true;
+  return buildProductSummary("visibility", {
+    headline: "Visibility active",
+    summary: needsBaselineRecording && summary.newComponents > 0
+      ? `${pluralize(summary.newComponents, "new component")} needs review`
+      : summary.suspiciousInstructionSources > 0
+        ? `${pluralize(summary.suspiciousInstructionSources, "suspicious instruction source")} - ${summary.componentsScanned} components`
+        : `${pluralize(summary.componentsScanned, "component")} - ${summary.highRisk} high risk - ${pluralize(summary.permissionExpansions, "permission expansion")}`,
+    nextBestAction: needsBaselineRecording && summary.newComponents > 0
+      ? "Run Visibility Scan to record the new baseline."
+      : summary.suspiciousInstructionSources > 0
+        ? `Review ${pluralize(summary.suspiciousInstructionSources, "suspicious instruction source")}.`
+      : null,
+    performance: options.performance || { lastOperationMs: null, slow: false },
+  });
+}
+
+function buildAgentSecuritySurface(cwd, config) {
+  const mode = config?.agentSecurity?.mode || "off";
+  const basicCheckEnabled = config?.agentSecurity?.basicCheckEnabled !== false;
+
+  if (mode === "off" || !basicCheckEnabled) return null;
+  if (mode !== "basic" && mode !== "visibility" && mode !== "warn" && mode !== "auto") return null;
+
+  const inventoryMode = mode === "basic" ? "basic" : "visibility";
+  const persisted = loadAgentSecurityEvidenceBundle(cwd, inventoryMode);
+  const persistedSummary = persisted.summary;
+  const trustCards = persisted.trustCards;
+  const generatedAt = persistedSummary?.generatedAt || null;
+  const summary = persistedSummary
+    ? { ...persistedSummary, cwd }
+    : {
+      mode: inventoryMode,
+      generatedAt: null,
+      cwd,
+      componentsScanned: 0,
+      newComponents: 0,
+      changedComponents: 0,
+      removedComponents: 0,
+      highRisk: 0,
+      mediumRisk: 0,
+      lowRisk: 0,
+      suspiciousInstructionSources: 0,
+      highInstructionFindings: 0,
+      sourcesTreatedAsData: 0,
+      permissionExpansions: 0,
+      permissionPreviews: 0,
+      topFindings: [],
+    };
+  const noRecentScanLine = mode === "basic"
+    ? "Agent security: Basic check active - Last checked: never"
+    : mode === "visibility"
+      ? "Agent security: Visibility active - No recent scan"
+      : mode === "warn"
+        ? "Agent security: Warn mode - no recent scan"
+        : "Agent security: Auto-Minimize - no recent scan";
+
+  if (mode === "basic") {
+    const needsBaselineRecording = Boolean(persistedSummary) && summary.newComponents > 0;
+    const showInStatus = true;
+    const productSummary = buildBasicProductSummary(summary, {
+      needsBaselineRecording,
+      performance: buildCompactPerformanceSummary(cwd, "agent_security_basic_check"),
+    });
+
+    return {
+      mode,
+      summary,
+      productSummary,
+      showInDashboard: true,
+      showInStatus,
+      hasRecordedCheck: Boolean(persistedSummary),
+      needsBaselineRecording,
+      statusLine: persistedSummary ? buildBasicStatusLine(summary, { needsBaselineRecording }) : noRecentScanLine,
+      dashboardCard: persistedSummary ? buildBasicDashboardBlurb(summary, { needsBaselineRecording }) : {
+        title: "Basic Skill/MCP Check",
+        headline: "Basic Check active",
+        summary: "No recent scan",
+        nextBestAction: "Run Basic Check.",
+        detailsAvailable: true,
+        checkedLabel: "Last checked: never",
+        newLabel: "0 new components",
+        riskLabel: "0 high risk",
+      },
+      detailsPath: persistedSummary ? SUMMARY_REL_PATH : null,
+    };
+  }
+
+  const riskDiff = persisted.riskDiff;
+  const permissionPreview = persisted.permissionPreview;
+  const needsBaselineRecording = Boolean(persistedSummary) && (summary.newComponents > 0 || summary.changedComponents > 0 || summary.removedComponents > 0);
+
+  if (mode === "warn") {
+    const decisionSummary = loadDecisionSummary(cwd);
+    const enforcementSummary = loadEnforcementSummary(cwd);
+    const jitGrantStore = loadJitGrantStore(cwd);
+    const productSummary = buildWarnProductSummary(summary, decisionSummary, enforcementSummary);
+    return {
+      mode,
+      summary: {
+        ...summary,
+        mode: "warn",
+      },
+      riskDiff,
+      permissionPreview,
+      decisionSummary,
+      enforcementSummary,
+      jitGrantStore,
+      productSummary,
+      showInDashboard: true,
+      showInStatus: true,
+      hasRecordedCheck: Boolean(persistedSummary),
+      needsBaselineRecording,
+      statusLine: persistedSummary ? buildWarnStatusLine(summary, decisionSummary, enforcementSummary) : noRecentScanLine,
+      dashboardCard: persistedSummary ? buildWarnDashboardCard(summary, decisionSummary, enforcementSummary) : {
+        title: "Agent Security",
+        subtitle: "Warn mode active",
+        headline: "Warn & Approve active",
+        summary: "No recent scan",
+        nextBestAction: "Run Visibility Scan.",
+        detailsAvailable: true,
+      },
+      detailsPath: persistedSummary ? VISIBILITY_SUMMARY_REL_PATH : null,
+    };
+  }
+
+  if (mode === "auto") {
+    const enforcementSummary = loadEnforcementSummary(cwd);
+    const jitGrantStore = loadJitGrantStore(cwd);
+    const activeRemediations = loadInstructionRemediations(cwd).items.length;
+    const productSummary = buildAutoProductSummary(summary, enforcementSummary, {
+      activeRemediations,
+      performance: buildCompactPerformanceSummary(cwd, ["agent_security_guarded_action", "agent_security_auto_policy"]),
+    });
+    return {
+      mode,
+      summary: {
+        ...summary,
+        mode: "auto",
+      },
+      riskDiff,
+      permissionPreview,
+      enforcementSummary,
+      jitGrantStore,
+      productSummary,
+      showInDashboard: true,
+      showInStatus: true,
+      hasRecordedCheck: Boolean(persistedSummary),
+      needsBaselineRecording,
+      statusLine: persistedSummary ? buildAutoStatusLine(summary, enforcementSummary) : noRecentScanLine,
+      dashboardCard: persistedSummary ? buildAutoDashboardCard(summary, enforcementSummary, productSummary) : {
+        title: "Agent Security",
+        subtitle: "Auto-Minimize active",
+        headline: "Auto-Minimize active",
+        summary: "No recent scan",
+        nextBestAction: "Run Visibility Scan.",
+        detailsAvailable: true,
+      },
+      detailsPath: persistedSummary ? VISIBILITY_SUMMARY_REL_PATH : null,
+    };
+  }
+
+  const productSummary = buildVisibilityProductSummary(summary, {
+    needsBaselineRecording,
+    performance: buildCompactPerformanceSummary(cwd, "agent_security_visibility_scan"),
+  });
+  return {
+    mode,
+    summary,
+    productSummary,
+    riskDiff,
+    permissionPreview,
+    showInDashboard: true,
+    showInStatus: true,
+    hasRecordedCheck: Boolean(persistedSummary),
+    needsBaselineRecording,
+    statusLine: persistedSummary ? buildVisibilityStatusLine(summary, { needsBaselineRecording }) : noRecentScanLine,
+    dashboardCard: persistedSummary ? buildVisibilityDashboardCard(summary, { needsBaselineRecording }) : {
+      title: "Agent Security",
+      subtitle: "Full visibility",
+      headline: "Visibility active",
+      summary: "No recent scan",
+      nextBestAction: "Run Visibility Scan.",
+      detailsAvailable: true,
+      surfaceLabel: "Last checked: never",
+      changeLabel: "0 new - 0 changed - 0 permission expansions",
+      topRiskLabel: "Top risk: No recent scan",
+      previewLabel: "0 permission previews",
+    },
+    detailsPath: persistedSummary ? VISIBILITY_SUMMARY_REL_PATH : null,
+  };
+}
+
+function runAgentSecurityScan(cwd, options = {}) {
+  const configuredMode = AGENT_SECURITY_MODES.includes(options.mode) ? options.mode : "basic";
+  const explicitMode = options.scanMode === "visibility" || options.scanMode === "basic" ? options.scanMode : null;
+  const mode = explicitMode || (configuredMode === "visibility" || configuredMode === "warn" || configuredMode === "auto" ? "visibility" : "basic");
+  const generatedAt = nowIso();
+  const operation = mode === "visibility" ? "agent_security_visibility_scan" : "agent_security_basic_check";
+  const tracker = createPerformanceTracker(operation);
+  const scanSession = createBoundedScanSession(cwd, tracker, {
+    maxFiles: PERFORMANCE_GUARDRAILS.scanMaxFiles,
+    maxFileBytes: PERFORMANCE_GUARDRAILS.scanMaxFileBytes,
+    maxTotalBytes: PERFORMANCE_GUARDRAILS.scanMaxTotalBytes,
+    maxDepth: PERFORMANCE_GUARDRAILS.scanMaxDepth,
+    maxDurationMs: PERFORMANCE_GUARDRAILS.scanMaxDurationMs,
+  });
+  const previousSnapshot = loadPreviousSnapshot(cwd, mode);
+  const trustCards = buildTrustCardsForMode(cwd, previousSnapshot, generatedAt, mode, { tracker, scanSession });
+
+  let summary;
+  let riskDiff = null;
+  let permissionPreview = null;
+  if (mode === "visibility") {
+    riskDiff = buildRiskDiff(previousSnapshot, trustCards, generatedAt);
+    permissionPreview = buildPermissionPreview(trustCards, generatedAt);
+    summary = summarizeTrustCards(mode, trustCards, generatedAt, null, {
+      riskIncreases: riskDiff.summary.riskIncreases,
+      permissionExpansions: riskDiff.summary.permissionExpansions,
+      permissionPreviews: permissionPreview.previews.length,
+    });
+  } else {
+    summary = summarizeTrustCards(mode, trustCards, generatedAt, null);
+  }
+
+  let evidence = null;
+  if (options.writeEvidence !== false) {
+    evidence = mode === "visibility"
+      ? writeVisibilityEvidence(cwd, generatedAt, previousSnapshot, trustCards)
+      : writeBasicEvidence(cwd, generatedAt, previousSnapshot, trustCards);
+    recordAgentSecurityOperation(cwd, operation, tracker, {
+      operation,
+      mode,
+      componentsScanned: summary.componentsScanned,
+      cachePath: SCAN_CACHE_REL_PATH,
+    }, options.writeEvidence);
+  }
+
+  return {
+    generatedAt,
+    mode,
+    configuredMode,
+    summary,
+    trustCards,
+    riskDiff,
+    permissionPreview,
+    evidence,
+  };
+}
+
+function runAgentSecurityBasicCheck(cwd, options = {}) {
+  return runAgentSecurityScan(cwd, {
+    ...options,
+    scanMode: "basic",
+  });
+}
+
+function runAgentSecurityVisibilityScan(cwd, options = {}) {
+  return runAgentSecurityScan(cwd, {
+    ...options,
+    scanMode: "visibility",
+  });
+}
+
+function inspectAgentSecurityContent(cwd, input, options = {}) {
+  const configuredMode = AGENT_SECURITY_MODES.includes(options.mode) ? options.mode : "off";
+  const mode = configuredMode;
+  const generatedAt = nowIso();
+  const sourceType = input?.sourceType || "unknown_external";
+  const content = String(input?.content || "");
+  const inspection = scanInstructionRisk(content, {
+    sourceType,
+    intendedUse: input?.intendedUse || "unknown",
+  });
+  const sourceRecord = buildSourceRecord({
+    sourceId: input?.sourceId,
+    sourceType,
+    origin: input?.origin || null,
+    path: input?.path || null,
+    content,
+    instructionRisk: inspection.instructionRisk,
+    findings: inspection.findings,
+    intendedUse: input?.intendedUse || "unknown",
+    createdAt: generatedAt,
+    updatedAt: generatedAt,
+  });
+
+  const previousSourceDoc = safeReadJson(cwd, SOURCE_TRUST_REL_PATH, {
+    sourceTrustVersion: 1,
+    what: "Agent Security source trust classifications.",
+    generatedAt,
+    items: [],
+  });
+  const previousRiskDoc = safeReadJson(cwd, INSTRUCTION_RISK_REL_PATH, {
+    instructionRiskVersion: 1,
+    what: "Agent Security instruction risk findings.",
+    generatedAt,
+    counts: {
+      suspiciousSources: 0,
+      highRiskSources: 0,
+      highRiskFindings: 0,
+    },
+    items: [],
+  });
+
+  const nextSourceItems = previousSourceDoc.items.filter((item) => item.sourceId !== sourceRecord.sourceId);
+  nextSourceItems.push(sourceRecord);
+  const nextRiskItems = previousRiskDoc.items.filter((item) => item.sourceId !== sourceRecord.sourceId);
+  nextRiskItems.push({
+    sourceId: sourceRecord.sourceId,
+    sourceType: sourceRecord.sourceType,
+    name: input?.origin || sourceRecord.path || sourceRecord.sourceId,
+    source: sourceRecord.path || sourceRecord.origin || null,
+    instructionRisk: inspection.instructionRisk,
+    signals: inspection.signals,
+    findings: inspection.findings.map((finding) => ({
+      category: finding.category,
+      severity: finding.severity,
+      message: finding.message,
+      evidencePreview: boundedPreview(finding.evidencePreview, 120),
+      location: finding.location || null,
+    })),
+    recommendation: sourceRecord.recommendation,
+  });
+
+  const nextSourceDoc = {
+    sourceTrustVersion: 1,
+    what: "Agent Security source trust classifications.",
+    generatedAt,
+    items: nextSourceItems,
+  };
+  const nextRiskDoc = {
+    instructionRiskVersion: 1,
+    what: "Agent Security instruction risk findings.",
+    generatedAt,
+    counts: {
+      suspiciousSources: nextRiskItems.filter((item) => item.instructionRisk !== "low").length,
+      highRiskSources: nextRiskItems.filter((item) => item.instructionRisk === "high").length,
+      highRiskFindings: nextRiskItems.reduce((sum, item) => sum + item.findings.filter((finding) => finding.severity === "high").length, 0),
+    },
+    items: nextRiskItems,
+  };
+
+  if (options.writeEvidence !== false) {
+    safeWriteJson(cwd, SOURCE_TRUST_REL_PATH, nextSourceDoc);
+    safeWriteJson(cwd, INSTRUCTION_RISK_REL_PATH, nextRiskDoc);
+    appendJsonl(cwd, INSTRUCTION_AUDIT_LOG_REL_PATH, {
+      eventType: "agent_security_source_trust_classified",
+      mode,
+      sourceId: sourceRecord.sourceId,
+      sourceType: sourceRecord.sourceType,
+      trustLevel: sourceRecord.trustLevel,
+      instructionRisk: sourceRecord.instructionRisk,
+      signals: inspection.signals,
+      reason: sourceRecord.recommendation,
+      timestamp: generatedAt,
+    });
+    if (inspection.findings.length > 0) {
+      appendJsonl(cwd, INSTRUCTION_AUDIT_LOG_REL_PATH, {
+        eventType: "agent_security_instruction_risk_detected",
+        mode,
+        sourceId: sourceRecord.sourceId,
+        sourceType: sourceRecord.sourceType,
+        trustLevel: sourceRecord.trustLevel,
+        instructionRisk: sourceRecord.instructionRisk,
+        signals: inspection.signals,
+        reason: sourceRecord.recommendation,
+        timestamp: generatedAt,
+      });
+    }
+  }
+
+  return {
+    generatedAt,
+    mode,
+    sourceRecord,
+    inspection,
+    remediation: {
+      defaultAction: sourceRecord.recommendation,
+      availableActions: ["treat_as_data_only", "use_sanitized_copy", "quarantine_source", "trust_source"],
+    },
+    evidence: options.writeEvidence === false ? null : {
+      sourceTrustPath: SOURCE_TRUST_REL_PATH,
+      instructionRiskPath: INSTRUCTION_RISK_REL_PATH,
+      auditPath: INSTRUCTION_AUDIT_LOG_REL_PATH,
+    },
+  };
+}
+
+function remediateAgentSecurityInstruction(cwd, input, options = {}) {
+  const mode = AGENT_SECURITY_MODES.includes(options.mode) ? options.mode : "warn";
+  const generatedAt = nowIso();
+  const sourceId = String(input?.sourceId || "");
+  const action = String(input?.action || "");
+  const reason = String(input?.reason || "");
+  if (!sourceId) throw new Error("Instruction remediation requires sourceId.");
+  if (!["treat_as_data_only", "use_sanitized_copy", "quarantine_source", "trust_source"].includes(action)) {
+    throw new Error("Unsupported instruction remediation action.");
+  }
+
+  const sourceDoc = safeReadJson(cwd, SOURCE_TRUST_REL_PATH, {
+    sourceTrustVersion: 1,
+    what: "Agent Security source trust classifications.",
+    generatedAt,
+    items: [],
+  });
+  const sourceRecord = sourceDoc.items.find((item) => item.sourceId === sourceId);
+  if (!sourceRecord) throw new Error(`Unknown sourceId: ${sourceId}`);
+
+  const remediations = loadInstructionRemediations(cwd);
+  const remediationRecord = {
+    remediationId: `rem-${shortHash(`${sourceId}:${action}:${generatedAt}`)}`,
+    sourceId,
+    action,
+    mode,
+    reason,
+    createdAt: generatedAt,
+    expiresAt: null,
+    userDecision: action === "trust_source",
+  };
+
+  safeWriteJson(cwd, INSTRUCTION_REMEDIATIONS_REL_PATH, {
+    remediationVersion: 1,
+    what: "Agent Security instruction remediations.",
+    generatedAt,
+    items: [...remediations.items, remediationRecord],
+  });
+
+  let sanitizedCopy = null;
+  if (action === "use_sanitized_copy") {
+    const sanitizedDoc = safeReadJson(cwd, SANITIZED_CONTENT_REL_PATH, {
+      sanitizedContentVersion: 1,
+      what: "Agent Security sanitized content copies.",
+      generatedAt,
+      items: [],
+    });
+    sanitizedCopy = {
+      sourceId,
+      sourceType: sourceRecord.sourceType,
+      contentHash: sourceRecord.contentHash,
+      sanitizedContent: sanitizeInstructionLikeContent(sourceRecord.contentSample || ""),
+      createdAt: generatedAt,
+    };
+    safeWriteJson(cwd, SANITIZED_CONTENT_REL_PATH, {
+      sanitizedContentVersion: 1,
+      what: "Agent Security sanitized content copies.",
+      generatedAt,
+      items: [...sanitizedDoc.items.filter((item) => item.sourceId !== sourceId), sanitizedCopy],
+    });
+    appendJsonl(cwd, INSTRUCTION_AUDIT_LOG_REL_PATH, {
+      eventType: "agent_security_sanitized_copy_created",
+      mode,
+      sourceId,
+      sourceType: sourceRecord.sourceType,
+      trustLevel: sourceRecord.trustLevel,
+      instructionRisk: sourceRecord.instructionRisk,
+      signals: [],
+      remediationAction: action,
+      reason,
+      timestamp: generatedAt,
+    });
+  }
+
+  appendJsonl(cwd, INSTRUCTION_AUDIT_LOG_REL_PATH, {
+    eventType: "agent_security_instruction_remediation_recorded",
+    mode,
+    sourceId,
+    sourceType: sourceRecord.sourceType,
+    trustLevel: sourceRecord.trustLevel,
+    instructionRisk: sourceRecord.instructionRisk,
+    signals: [],
+    remediationAction: action,
+    reason,
+    timestamp: generatedAt,
+  });
+
+  return {
+    generatedAt,
+    mode,
+    remediationRecord,
+    sanitizedCopy,
+    evidence: {
+      remediationPath: INSTRUCTION_REMEDIATIONS_REL_PATH,
+      sanitizedContentPath: action === "use_sanitized_copy" ? SANITIZED_CONTENT_REL_PATH : null,
+      auditPath: INSTRUCTION_AUDIT_LOG_REL_PATH,
+    },
+  };
+}
+
+function runAgentSecurityPreflight(cwd, actionInput, options = {}) {
+  const mode = "warn";
+  const generatedAt = nowIso();
+  const tracker = createPerformanceTracker("agent_security_preflight");
+  const inventory = loadPersistedInventoryForActions(cwd);
+
+  const action = {
+    ...(actionInput && typeof actionInput === "object" ? actionInput : {}),
+  };
+  action.context = action.context && typeof action.context === "object" ? { ...action.context } : {};
+  if (!action.context.cwd) action.context.cwd = cwd;
+  if (!action.actionId) action.actionId = buildActionId(action);
+
+  const componentCard = resolveComponentCard(inventory.trustCards, action);
+  const relatedSources = resolveRelatedSourcesForAction(cwd, action, componentCard);
+  const evaluation = evaluateAgentSecurityAction(action, { componentCard, relatedSources });
+  const requestedDecision = action.decision || options.decision || null;
+  const limitPlan = evaluation.decisionRequired || requestedDecision === "let_wuz_limit"
+    ? buildPermissionLimitPlan({ evaluation, action }, { componentCard })
+    : null;
+
+  const decision = requestedDecision;
+  const decisionRecord = decision
+    ? buildDecisionRecord({
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      decision,
+      actionType: evaluation.actionType,
+      target: evaluation.target,
+      limitPlan,
+      reason: evaluation.reasons[0],
+      timestamp: generatedAt,
+    })
+    : null;
+
+  let decisionSummary = null;
+  if (options.writeEvidence !== false) {
+    writeEnforcementCapabilityMatrix(cwd, generatedAt, mode);
+    safeWriteJson(cwd, ACTION_PREFLIGHT_REL_PATH, {
+      what: "Agent Security preflight result.",
+      generatedAt,
+      mode,
+      action: {
+        actionId: evaluation.actionId,
+        componentId: evaluation.componentId,
+        componentType: evaluation.componentType,
+        actionType: evaluation.actionType,
+        target: evaluation.target,
+        command: evaluation.command,
+        packageManager: evaluation.packageManager || null,
+        scriptName: evaluation.scriptName || null,
+        packageName: evaluation.packageName || null,
+        mcpServer: evaluation.mcpServer || null,
+        toolName: evaluation.toolName || null,
+        argsHash: evaluation.argsHash || null,
+        targetHash: evaluation.targetHash || null,
+        relatedSourceIds: evaluation.relatedSourceIds || [],
+      },
+      evaluation,
+      ...(limitPlan ? { limitPlan } : {}),
+      ...(decisionRecord ? { decisionRecord } : {}),
+    });
+  }
+
+  if (decision && options.writeEvidence !== false) {
+    decisionSummary = updateDecisionSummary(cwd, {
+      decision,
+      effectiveBehavior: decisionRecord.effectiveBehavior,
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      componentType: evaluation.componentType,
+      actionType: evaluation.actionType,
+      riskLevel: evaluation.riskLevel,
+      timestamp: generatedAt,
+    });
+    writeDecisionAuditEvents(cwd, {
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      componentType: evaluation.componentType,
+      actionType: evaluation.actionType,
+      riskLevel: evaluation.riskLevel,
+      recommendedDecision: evaluation.recommendedDecision,
+      userDecision: decision,
+      effectiveBehavior: decisionRecord.effectiveBehavior,
+      limitPlan,
+      timestamp: generatedAt,
+    });
+  }
+
+  recordAgentSecurityOperation(cwd, "agent_security_preflight", tracker, {
+    mode,
+    actionId: evaluation.actionId,
+    actionType: evaluation.actionType,
+    relatedSourceIds: evaluation.relatedSourceIds || [],
+  }, options.writeEvidence);
+
+  return {
+    generatedAt,
+    mode,
+    evaluation,
+    limitPlan,
+    decision: decision || null,
+    decisionRecord,
+    decisionSummary,
+    evidence: options.writeEvidence === false ? null : {
+      preflightPath: ACTION_PREFLIGHT_REL_PATH,
+      decisionSummaryPath: decisionSummary ? DECISION_SUMMARY_REL_PATH : null,
+      decisionAuditPath: decision ? DECISION_AUDIT_LOG_REL_PATH : null,
+      enforcementCapabilitiesPath: ENFORCEMENT_CAPABILITIES_REL_PATH,
+      performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+    },
+  };
+}
+
+function runAgentSecurityGuardedRun(cwd, actionInput, options = {}) {
+  const mode = "warn";
+  const generatedAt = nowIso();
+  const tracker = createPerformanceTracker("agent_security_guarded_action");
+  const inventory = loadPersistedInventoryForActions(cwd);
+
+  const action = {
+    ...(actionInput && typeof actionInput === "object" ? actionInput : {}),
+  };
+  action.context = action.context && typeof action.context === "object" ? { ...action.context } : {};
+  if (!action.context.cwd) action.context.cwd = cwd;
+  if (!action.actionId) action.actionId = buildActionId(action);
+
+  const componentCard = resolveComponentCard(inventory.trustCards, action);
+  const relatedSources = resolveRelatedSourcesForAction(cwd, action, componentCard);
+  const evaluation = evaluateAgentSecurityAction(action, { componentCard, relatedSources });
+  const requestedDecision = action.decision || options.decision || null;
+  const limitPlan = evaluation.decisionRequired || requestedDecision === "let_wuz_limit"
+    ? buildPermissionLimitPlan({ evaluation, action }, { componentCard })
+    : null;
+
+  const decision = requestedDecision;
+  const decisionRecord = decision
+    ? buildDecisionRecord({
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      decision,
+      actionType: evaluation.actionType,
+      target: evaluation.target,
+      limitPlan,
+      reason: evaluation.reasons[0],
+      timestamp: generatedAt,
+    })
+    : null;
+
+  if (options.writeEvidence !== false) {
+    safeWriteJson(cwd, ACTION_PREFLIGHT_REL_PATH, {
+      what: "Agent Security guarded action preflight result.",
+      generatedAt,
+      mode,
+      action: {
+        actionId: evaluation.actionId,
+        componentId: evaluation.componentId,
+        componentType: evaluation.componentType,
+        actionType: evaluation.actionType,
+        target: evaluation.target,
+        command: evaluation.command,
+        packageManager: evaluation.packageManager || null,
+        scriptName: evaluation.scriptName || null,
+        packageName: evaluation.packageName || null,
+        mcpServer: evaluation.mcpServer || null,
+        toolName: evaluation.toolName || null,
+        argsHash: evaluation.argsHash || null,
+        targetHash: evaluation.targetHash || null,
+        relatedSourceIds: evaluation.relatedSourceIds || [],
+      },
+      evaluation,
+      ...(limitPlan ? { limitPlan } : {}),
+      ...(decisionRecord ? { decisionRecord } : {}),
+    });
+  }
+
+  let decisionSummary = null;
+  if (decision && options.writeEvidence !== false) {
+    decisionSummary = updateDecisionSummary(cwd, {
+      decision,
+      effectiveBehavior: decisionRecord.effectiveBehavior,
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      componentType: evaluation.componentType,
+      actionType: evaluation.actionType,
+      riskLevel: evaluation.riskLevel,
+      timestamp: generatedAt,
+    });
+    writeDecisionAuditEvents(cwd, {
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      componentType: evaluation.componentType,
+      actionType: evaluation.actionType,
+      riskLevel: evaluation.riskLevel,
+      recommendedDecision: evaluation.recommendedDecision,
+      userDecision: decision,
+      effectiveBehavior: decisionRecord.effectiveBehavior,
+      limitPlan,
+      timestamp: generatedAt,
+    });
+  }
+
+  const enforcement = enforceAgentSecurityAction(cwd, {
+    action: {
+      ...action,
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      componentType: evaluation.componentType,
+      actionType: evaluation.actionType,
+      target: evaluation.target,
+      command: evaluation.command,
+      packageManager: evaluation.packageManager || action.packageManager || null,
+      scriptName: evaluation.scriptName || action.scriptName || null,
+      packageName: evaluation.packageName || action.packageName || null,
+      mcpServer: evaluation.mcpServer || action.mcpServer || null,
+      toolName: evaluation.toolName || action.toolName || null,
+      args: action.args && typeof action.args === "object" ? action.args : null,
+      resource: action.resource && typeof action.resource === "object" ? action.resource : null,
+    },
+    evaluation,
+    limitPlan,
+    decisionRecord,
+  }, {
+    timestamp: generatedAt,
+    execute: action.execute === true,
+    executor: options.executor,
+    writeEvidence: options.writeEvidence !== false,
+  });
+
+  recordAgentSecurityOperation(cwd, "agent_security_guarded_action", tracker, {
+    mode,
+    actionId: evaluation.actionId,
+    actionType: evaluation.actionType,
+    relatedSourceIds: evaluation.relatedSourceIds || [],
+    enforcementAvailable: enforcement.enforcementAvailable === true,
+  }, options.writeEvidence);
+
+  return {
+    generatedAt,
+    mode,
+    evaluation,
+    limitPlan,
+    decision: decision || null,
+    decisionRecord,
+    decisionSummary,
+    enforcement,
+    evidence: options.writeEvidence === false ? null : {
+      preflightPath: ACTION_PREFLIGHT_REL_PATH,
+      decisionSummaryPath: decisionSummary ? DECISION_SUMMARY_REL_PATH : null,
+      decisionAuditPath: decision ? DECISION_AUDIT_LOG_REL_PATH : null,
+      enforcementSummaryPath: ENFORCEMENT_SUMMARY_REL_PATH,
+      jitGrantsPath: JIT_GRANTS_REL_PATH,
+      grantsPath: ONE_TIME_GRANTS_REL_PATH,
+      enforcementAuditPath: ENFORCEMENT_AUDIT_LOG_REL_PATH,
+      enforcementCapabilitiesPath: ENFORCEMENT_CAPABILITIES_REL_PATH,
+      performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+    },
+  };
+}
+
+function writeGuardedActionPreflight(cwd, generatedAt, mode, evaluation, limitPlan, decisionRecord, autoPolicy, writeEvidence) {
+  if (writeEvidence === false) return;
+  safeWriteJson(cwd, ACTION_PREFLIGHT_REL_PATH, {
+    what: "Agent Security guarded action preflight result.",
+    generatedAt,
+    mode,
+    action: {
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      componentType: evaluation.componentType,
+      actionType: evaluation.actionType,
+      target: evaluation.target,
+      command: evaluation.command,
+      packageManager: evaluation.packageManager || null,
+      scriptName: evaluation.scriptName || null,
+      packageName: evaluation.packageName || null,
+      mcpServer: evaluation.mcpServer || null,
+      toolName: evaluation.toolName || null,
+      argsHash: evaluation.argsHash || null,
+      targetHash: evaluation.targetHash || null,
+      contentHash: evaluation.contentHash || null,
+      scopeKey: evaluation.scopeKey || null,
+    },
+    evaluation,
+    ...(limitPlan ? { limitPlan } : {}),
+    ...(decisionRecord ? { decisionRecord } : {}),
+    ...(autoPolicy ? { autoPolicy } : {}),
+  });
+}
+
+function buildAutoDecisionRecord(input) {
+  if (input.autoDecision === "auto_allow_limited") {
+    return buildDecisionRecord({
+      ...input,
+      decision: "let_wuz_limit",
+      mode: "auto",
+    });
+  }
+  if (input.autoDecision === "auto_allow_once") {
+    return buildDecisionRecord({
+      ...input,
+      decision: "approve_once",
+      mode: "auto",
+    });
+  }
+  if (input.autoDecision === "auto_deny") {
+    return buildDecisionRecord({
+      ...input,
+      decision: "deny",
+      mode: "auto",
+    });
+  }
+  return null;
+}
+
+function buildImplicitGuardedComponentCard(action) {
+  const componentType = String(action?.componentType || "");
+  if (componentType === "file-write" || componentType === "command" || componentType === "package-manager") {
+    return {
+      id: String(action?.componentId || componentType),
+      type: componentType,
+      source: "guarded",
+      status: "known",
+      trustLevel: "local",
+      capabilities: {},
+    };
+  }
+  if (componentType === "mcp" && String(action?.mcpServer || "").toLowerCase() === "github") {
+    return {
+      id: String(action?.componentId || "mcp-github"),
+      type: "mcp",
+      source: "guarded",
+      status: "known",
+      trustLevel: "local",
+      capabilities: {},
+    };
+  }
+  return null;
+}
+
+function runAgentSecurityAutoGuardedAction(cwd, actionInput, options = {}) {
+  const mode = "auto";
+  const generatedAt = nowIso();
+  const tracker = createPerformanceTracker("agent_security_guarded_action");
+  const inventory = loadPersistedInventoryForActions(cwd);
+
+  const action = {
+    ...(actionInput && typeof actionInput === "object" ? actionInput : {}),
+  };
+  action.context = action.context && typeof action.context === "object" ? { ...action.context } : {};
+  if (!action.context.cwd) action.context.cwd = cwd;
+  if (!action.actionId) action.actionId = buildActionId(action);
+
+  const componentCard = resolveComponentCard(inventory.trustCards, action) || buildImplicitGuardedComponentCard(action);
+  const relatedSources = resolveRelatedSourcesForAction(cwd, action, componentCard);
+  const evaluation = evaluateAgentSecurityAction(action, { componentCard, relatedSources });
+  const normalizedAction = normalizeAgentSecurityAction({
+    ...action,
+    actionId: evaluation.actionId,
+    componentId: evaluation.componentId,
+    componentType: evaluation.componentType,
+    actionType: evaluation.actionType,
+    target: evaluation.target,
+    command: evaluation.command,
+    packageManager: evaluation.packageManager || action.packageManager || null,
+    scriptName: evaluation.scriptName || action.scriptName || null,
+    packageName: evaluation.packageName || action.packageName || null,
+    mcpServer: evaluation.mcpServer || action.mcpServer || null,
+    toolName: evaluation.toolName || action.toolName || null,
+    relatedSourceIds: evaluation.relatedSourceIds || [],
+  });
+  const adapter = resolveAgentSecurityAdapter(evaluation.actionType);
+  const limitPlan = buildPermissionLimitPlan({ evaluation, action: normalizedAction }, { componentCard });
+  const explicitDecision = action.decision || options.decision || null;
+
+  if (explicitDecision) {
+    const decisionRecord = buildDecisionRecord({
+      actionId: evaluation.actionId,
+      componentId: evaluation.componentId,
+      decision: explicitDecision,
+      actionType: evaluation.actionType,
+      target: evaluation.target,
+      limitPlan,
+      reason: evaluation.reasons[0],
+      timestamp: generatedAt,
+      mode,
+    });
+    writeGuardedActionPreflight(cwd, generatedAt, mode, evaluation, limitPlan, decisionRecord, null, options.writeEvidence);
+    const enforcement = enforceAgentSecurityAction(cwd, {
+      action: normalizedAction,
+      evaluation,
+      limitPlan,
+      decisionRecord,
+    }, {
+      timestamp: generatedAt,
+      execute: action.execute === true,
+      executor: options.executor,
+      writeEvidence: options.writeEvidence !== false,
+      mode,
+      autoDecision: explicitDecision === "deny"
+        ? "auto_deny"
+        : explicitDecision === "let_wuz_limit"
+          ? "auto_allow_limited"
+          : "auto_allow_once",
+      confidence: "high",
+    });
+
+    recordAgentSecurityOperation(cwd, "agent_security_guarded_action", tracker, {
+      mode,
+      actionId: evaluation.actionId,
+      actionType: evaluation.actionType,
+      autoDecision: explicitDecision === "deny"
+        ? "auto_deny"
+        : explicitDecision === "let_wuz_limit"
+          ? "auto_allow_limited"
+          : "auto_allow_once",
+      relatedSourceIds: evaluation.relatedSourceIds || [],
+      enforcementAvailable: enforcement.enforcementAvailable === true,
+    }, options.writeEvidence);
+
+    return {
+      generatedAt,
+      mode,
+      action: normalizedAction,
+      evaluation,
+      limitPlan,
+      autoDecision: explicitDecision === "deny"
+        ? "auto_deny"
+        : explicitDecision === "let_wuz_limit"
+          ? "auto_allow_limited"
+          : "auto_allow_once",
+      confidence: "high",
+      decision: explicitDecision,
+      decisionRecord,
+      enforcement,
+      evidence: options.writeEvidence === false ? null : {
+        preflightPath: ACTION_PREFLIGHT_REL_PATH,
+        enforcementSummaryPath: ENFORCEMENT_SUMMARY_REL_PATH,
+        jitGrantsPath: JIT_GRANTS_REL_PATH,
+        grantsPath: ONE_TIME_GRANTS_REL_PATH,
+        enforcementAuditPath: ENFORCEMENT_AUDIT_LOG_REL_PATH,
+        enforcementCapabilitiesPath: ENFORCEMENT_CAPABILITIES_REL_PATH,
+        performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+      },
+    };
+  }
+
+  const autoPolicyTracker = createPerformanceTracker("agent_security_auto_policy");
+  const autoPolicy = decideAutoAction(normalizedAction, evaluation, limitPlan, adapter, {
+    mode,
+    cwd,
+  });
+  recordAgentSecurityOperation(cwd, "agent_security_auto_policy", autoPolicyTracker, {
+    mode,
+    actionId: evaluation.actionId,
+    actionType: evaluation.actionType,
+    autoDecision: autoPolicy.autoDecision,
+    relatedSourceIds: evaluation.relatedSourceIds || [],
+  }, options.writeEvidence);
+  writeGuardedActionPreflight(cwd, generatedAt, mode, evaluation, limitPlan, null, autoPolicy, options.writeEvidence);
+
+  if (autoPolicy.autoDecision === "require_approval") {
+    const enforcement = recordEnforcementOutcome(cwd, {
+      actionId: normalizedAction.actionId,
+      componentId: normalizedAction.componentId,
+      componentType: normalizedAction.componentType,
+      actionType: normalizedAction.actionType,
+      target: normalizedAction.target || null,
+      command: normalizedAction.command || "",
+      packageManager: normalizedAction.packageManager || null,
+      scriptName: normalizedAction.scriptName || null,
+      packageName: normalizedAction.packageName || null,
+      mcpServer: normalizedAction.mcpServer || null,
+      toolName: normalizedAction.toolName || null,
+      decision: null,
+      adapterId: adapter?.adapterId || null,
+      enforcementAvailable: adapter?.canEnforce === true,
+      effectiveBehavior: "limit_plan_only",
+      executed: false,
+      exitCode: null,
+      stdoutPreview: "",
+      stderrPreview: "",
+      reason: autoPolicy.reason,
+      timestamp: generatedAt,
+      mode,
+      autoDecision: autoPolicy.autoDecision,
+      confidence: autoPolicy.confidence,
+      jitGrant: null,
+      jitGrantConsumed: null,
+      jitGrantExpired: null,
+    }, {
+      mode,
+      writeEvidence: options.writeEvidence !== false,
+    });
+
+    recordAgentSecurityOperation(cwd, "agent_security_guarded_action", tracker, {
+      mode,
+      actionId: evaluation.actionId,
+      actionType: evaluation.actionType,
+      autoDecision: autoPolicy.autoDecision,
+      relatedSourceIds: evaluation.relatedSourceIds || [],
+      enforcementAvailable: enforcement.enforcementAvailable === true,
+    }, options.writeEvidence);
+
+    return {
+      generatedAt,
+      mode,
+      action: normalizedAction,
+      evaluation,
+      limitPlan,
+      autoDecision: autoPolicy.autoDecision,
+      confidence: autoPolicy.confidence,
+      enforcement,
+      evidence: options.writeEvidence === false ? null : {
+        preflightPath: ACTION_PREFLIGHT_REL_PATH,
+        enforcementSummaryPath: ENFORCEMENT_SUMMARY_REL_PATH,
+        enforcementAuditPath: ENFORCEMENT_AUDIT_LOG_REL_PATH,
+        enforcementCapabilitiesPath: ENFORCEMENT_CAPABILITIES_REL_PATH,
+        performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+      },
+    };
+  }
+
+  if (autoPolicy.autoDecision === "recommended_only" || autoPolicy.autoDecision === "limit_plan_only") {
+    const enforcement = recordEnforcementOutcome(cwd, {
+      actionId: normalizedAction.actionId,
+      componentId: normalizedAction.componentId,
+      componentType: normalizedAction.componentType,
+      actionType: normalizedAction.actionType,
+      target: normalizedAction.target || null,
+      command: normalizedAction.command || "",
+      packageManager: normalizedAction.packageManager || null,
+      scriptName: normalizedAction.scriptName || null,
+      packageName: normalizedAction.packageName || null,
+      mcpServer: normalizedAction.mcpServer || null,
+      toolName: normalizedAction.toolName || null,
+      decision: null,
+      adapterId: adapter?.adapterId || null,
+      enforcementAvailable: adapter?.canEnforce === true,
+      effectiveBehavior: autoPolicy.autoDecision === "recommended_only" ? "recommended_only" : "limit_plan_only",
+      executed: false,
+      exitCode: null,
+      stdoutPreview: "",
+      stderrPreview: "",
+      reason: autoPolicy.reason,
+      timestamp: generatedAt,
+      mode,
+      autoDecision: autoPolicy.autoDecision,
+      confidence: autoPolicy.confidence,
+      jitGrant: null,
+      jitGrantConsumed: null,
+      jitGrantExpired: null,
+    }, {
+      mode,
+      writeEvidence: options.writeEvidence !== false,
+      unsupportedActionTypes: adapter ? [] : [normalizedAction.actionType],
+    });
+
+    recordAgentSecurityOperation(cwd, "agent_security_guarded_action", tracker, {
+      mode,
+      actionId: evaluation.actionId,
+      actionType: evaluation.actionType,
+      autoDecision: autoPolicy.autoDecision,
+      relatedSourceIds: evaluation.relatedSourceIds || [],
+      enforcementAvailable: enforcement.enforcementAvailable === true,
+    }, options.writeEvidence);
+
+    return {
+      generatedAt,
+      mode,
+      action: normalizedAction,
+      evaluation,
+      limitPlan,
+      autoDecision: autoPolicy.autoDecision,
+      confidence: autoPolicy.confidence,
+      enforcement,
+      evidence: options.writeEvidence === false ? null : {
+        preflightPath: ACTION_PREFLIGHT_REL_PATH,
+        enforcementSummaryPath: ENFORCEMENT_SUMMARY_REL_PATH,
+        enforcementAuditPath: ENFORCEMENT_AUDIT_LOG_REL_PATH,
+        enforcementCapabilitiesPath: ENFORCEMENT_CAPABILITIES_REL_PATH,
+        performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+      },
+    };
+  }
+
+  const decisionRecord = buildAutoDecisionRecord({
+    actionId: evaluation.actionId,
+    componentId: evaluation.componentId,
+    actionType: evaluation.actionType,
+    target: evaluation.target,
+    limitPlan,
+    reason: autoPolicy.reason,
+    timestamp: generatedAt,
+    autoDecision: autoPolicy.autoDecision,
+  });
+
+  const enforcement = enforceAgentSecurityAction(cwd, {
+    action: normalizedAction,
+    evaluation,
+    limitPlan,
+    decisionRecord,
+  }, {
+    timestamp: generatedAt,
+    execute: action.execute === true,
+    executor: options.executor,
+    writeEvidence: options.writeEvidence !== false,
+    mode,
+    autoDecision: autoPolicy.autoDecision,
+    confidence: autoPolicy.confidence,
+  });
+
+  recordAgentSecurityOperation(cwd, "agent_security_guarded_action", tracker, {
+    mode,
+    actionId: evaluation.actionId,
+    actionType: evaluation.actionType,
+    autoDecision: autoPolicy.autoDecision,
+    relatedSourceIds: evaluation.relatedSourceIds || [],
+    enforcementAvailable: enforcement.enforcementAvailable === true,
+  }, options.writeEvidence);
+
+  return {
+    generatedAt,
+    mode,
+    action: normalizedAction,
+    evaluation,
+    limitPlan,
+    autoDecision: autoPolicy.autoDecision,
+    confidence: autoPolicy.confidence,
+    decisionRecord,
+    enforcement,
+    evidence: options.writeEvidence === false ? null : {
+      preflightPath: ACTION_PREFLIGHT_REL_PATH,
+      enforcementSummaryPath: ENFORCEMENT_SUMMARY_REL_PATH,
+      jitGrantsPath: JIT_GRANTS_REL_PATH,
+      grantsPath: ONE_TIME_GRANTS_REL_PATH,
+      enforcementAuditPath: ENFORCEMENT_AUDIT_LOG_REL_PATH,
+      enforcementCapabilitiesPath: ENFORCEMENT_CAPABILITIES_REL_PATH,
+      performanceSummaryPath: PERFORMANCE_SUMMARY_REL_PATH,
+    },
+  };
+}
+
+function runGuardedAction(cwd, actionInput, options = {}) {
+  const requestedMode = AGENT_SECURITY_MODES.includes(options.mode) ? options.mode : "warn";
+  if (requestedMode === "auto") {
+    return runAgentSecurityAutoGuardedAction(cwd, actionInput, options);
+  }
+  return runAgentSecurityGuardedRun(cwd, actionInput, options);
+}
+
+module.exports = {
+  AGENT_SECURITY_MODES,
+  SNAPSHOT_REL_PATH,
+  SUMMARY_REL_PATH,
+  VISIBILITY_SUMMARY_REL_PATH,
+  TRUST_CARDS_REL_PATH,
+  RISK_DIFF_REL_PATH,
+  PERMISSION_PREVIEW_REL_PATH,
+  INSTRUCTION_RISK_REL_PATH,
+  SOURCE_TRUST_REL_PATH,
+  INSTRUCTION_REMEDIATIONS_REL_PATH,
+  SANITIZED_CONTENT_REL_PATH,
+  AUDIT_LOG_REL_PATH,
+  INSTRUCTION_AUDIT_LOG_REL_PATH,
+  ACTION_PREFLIGHT_REL_PATH,
+  DECISION_SUMMARY_REL_PATH,
+  DECISION_AUDIT_LOG_REL_PATH,
+  ENFORCEMENT_CAPABILITIES_REL_PATH,
+  ENFORCEMENT_SUMMARY_REL_PATH,
+  JIT_GRANTS_REL_PATH,
+  ONE_TIME_GRANTS_REL_PATH,
+  ENFORCEMENT_AUDIT_LOG_REL_PATH,
+  stableStringify,
+  loadPreviousSnapshot,
+  loadLatestAgentSecuritySummary,
+  loadDecisionSummary,
+  loadJitGrantStore,
+  loadEnforcementSummary,
+  buildAgentSecurityModeControl,
+  buildAgentSecuritySurface,
+  buildRiskDiff,
+  buildPermissionPreview,
+  runAgentSecurityScan,
+  runAgentSecurityBasicCheck,
+  runAgentSecurityVisibilityScan,
+  inspectAgentSecurityContent,
+  remediateAgentSecurityInstruction,
+  runAgentSecurityPreflight,
+  runAgentSecurityGuardedRun,
+  runGuardedAction,
+};