avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/agent-enforcement.js

@@ -0,0 +1,765 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { ensureCcoDirs, safeReadJson, safeWriteJson, nowIso } = require("./fsx");
+const { canExportReports, getCurrentPlan } = require("./entitlements");
+const { buildTaskContinuation } = require("./task-continuation");
+const { buildPolicyProfile, describePolicyProfile } = require("./agent-policy-profile");
+const {
+  buildGovernanceReceipt,
+  writeGovernanceReceipt,
+  applyGovernanceDecisionFloor,
+  buildAgentAccessGovernanceSurface,
+} = require("./agent-access-governance");
+const {
+  buildSafePathReceipt,
+  writeSafePathReceipt,
+  buildSafePathSurface,
+  recordSafePathLearningSignals,
+} = require("./safe-path-engine");
+const {
+  buildActionIntakeContext,
+  LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH,
+} = require("./install-intake-risk");
+const { appendProductLearningEvent } = require("./product-learning-events");
+const {
+  maxRisk,
+  classifyActionRisk,
+  classifyPathRisk,
+  classifyCommandRisk,
+  classifyToolRisk,
+  classifyBrowserRisk,
+  classifyInstructionRisk,
+  classifyPromptInjectionRisk,
+  classifySourceTrustRisk,
+  classifyIntentMismatchRisk,
+  classifySecretExposureRisk,
+  classifyExternalExportRisk,
+} = require("./security-risk-classifier");
+
+const DECISIONS = Object.freeze(["allow", "warn", "approval_required", "block"]);
+const EVIDENCE_DIR_REL_PATH = ".claude/cco/evidence/agent-security";
+const LATEST_EVIDENCE_REL_PATH = `${EVIDENCE_DIR_REL_PATH}/latest-enforcement.json`;
+const HISTORY_DIR_REL_PATH = `${EVIDENCE_DIR_REL_PATH}/history`;
+const EVENT_LOG_REL_PATH = ".claude/cco/events/agent-security-enforcement.jsonl";
+const SCHEMA_VERSION = 1;
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+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 unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function normalizeActionType(value) {
+  const actionType = String(value || "unknown").trim().toLowerCase();
+  return actionType || "unknown";
+}
+
+function normalizePathList(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list.map((item) => String(item || "").replace(/\\/g, "/").trim()).filter(Boolean);
+}
+
+function redactSecrets(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSecrets(item));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    Object.keys(value).forEach((key) => {
+      out[key] = redactSecrets(value[key]);
+    });
+    return out;
+  }
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  return value
+    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted-openai-key]")
+    .replace(/ghp_[A-Za-z0-9]{20,}/g, "[redacted-github-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-aws-key]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]")
+    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]")
+    .replace(/(-----BEGIN [A-Z ]+-----)[\s\S]{0,4000}?(-----END [A-Z ]+-----)/g, "$1 [redacted] $2");
+}
+
+function appendJsonl(cwd, relPathValue, entry) {
+  const absPath = path.join(cwd, relPathValue);
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.appendFileSync(absPath, `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+function buildDecisionId(input, plan) {
+  return `guard-${sha256(stableStringify({ plan, input })).slice(0, 12)}`;
+}
+
+function buildSanitizedInputSummary(input = {}) {
+  return redactSecrets({
+    actionType: normalizeActionType(input.actionType),
+    requestedBy: input.requestedBy || "unknown",
+    taskType: input.taskType || null,
+    userIntent: input.userIntent || null,
+    targetPaths: normalizePathList(input.targetPaths || input.target || []),
+    command: input.command || null,
+    toolName: input.toolName || null,
+    mcpServer: input.mcpServer || null,
+    domain: input.domain || null,
+    url: input.url || input.target || null,
+    skillPackIds: Array.isArray(input.skillPackIds) ? input.skillPackIds : [],
+    sourceTrust: input.sourceTrust || null,
+    instructionText: input.instructionText ? redactSecrets(String(input.instructionText).slice(0, 300)) : null,
+  });
+}
+
+function classifyAction(input = {}) {
+  const actionType = normalizeActionType(input.actionType);
+  const pathRisk = classifyPathRisk(input.targetPaths || input.target || [], input);
+  const commandRisk = classifyCommandRisk(input.command || input.target || "");
+  const toolRisk = classifyToolRisk({
+    toolName: input.toolName,
+    mcpServer: input.mcpServer,
+    metadata: input.toolMetadata,
+  });
+  const browserRisk = classifyBrowserRisk({
+    url: input.url || input.target,
+    domain: input.domain,
+    domainBoundaryReady: input.domainBoundaryReady,
+    cookieAccess: input.cookieAccess,
+    sessionAccess: input.sessionAccess,
+    secretAccess: input.secretAccess,
+  });
+  const instructionRisk = classifyInstructionRisk({
+    text: input.instructionText,
+    sourceTrust: input.sourceTrust,
+    sourceType: input.sourceType,
+  });
+  const promptInjectionRisk = classifyPromptInjectionRisk({
+    text: input.instructionText,
+    sourceTrust: input.sourceTrust,
+    sourceType: input.sourceType,
+  });
+  const sourceTrustRisk = classifySourceTrustRisk(input);
+  const intentMismatchRisk = classifyIntentMismatchRisk(input);
+  const secretExposureRisk = classifySecretExposureRisk(input);
+  const externalExportRisk = classifyExternalExportRisk(input);
+  const combined = classifyActionRisk(input);
+
+  return {
+    actionType,
+    pathRisk,
+    commandRisk,
+    toolRisk,
+    browserRisk,
+    instructionRisk,
+    promptInjectionRisk,
+    sourceTrustRisk,
+    intentMismatchRisk,
+    secretExposureRisk,
+    externalExportRisk,
+    combined,
+  };
+}
+
+function getMatchedRules(input = {}, classification, profile) {
+  const actionType = classification.actionType;
+  const rules = [];
+  const risk = classification.combined;
+  const reasons = new Set(risk.reasonCodes || []);
+  const intakeReasons = new Set(input.intakeContext?.reasonCodes || []);
+  const isSensitiveFileWrite = (actionType === "file_write" || actionType === "config_change")
+    && (reasons.has("SENSITIVE_ENV_FILE") || reasons.has("SECRET_LIKE_TARGET") || reasons.has("AUTH_OR_BILLING_SCOPE") || reasons.has("DEPLOYMENT_CONFIG") || reasons.has("CI_CONFIG"));
+  const hasPromptInjection = input.hasPromptInjectionSignal === true || reasons.has("PROMPT_INJECTION_SIGNAL");
+  const hasIntentMismatch = input.hasIntentMismatchSignal === true || reasons.has("INTENT_MISMATCH") || reasons.has("OUT_OF_SCOPE_FILE_CHANGE");
+  const browserExternal = (actionType === "browser_action" || actionType === "visual_qa_run") && reasons.has("BROWSER_EXTERNAL_DOMAIN");
+  const browserSecretRisk = reasons.has("BROWSER_COOKIE_OR_SESSION_RISK");
+  const unknownTool = reasons.has("UNKNOWN_MCP_TOOL");
+  const writeCapableTool = reasons.has("WRITE_CAPABLE_TOOL");
+  const destructiveCommand = reasons.has("DESTRUCTIVE_COMMAND") || reasons.has("FORCE_PUSH_OR_HISTORY_REWRITE");
+  const externalExport = reasons.has("EXTERNAL_REPO_EXPORT");
+  const externalNetwork = reasons.has("EXTERNAL_NETWORK_REQUEST");
+  const localhostVisualQa = actionType === "visual_qa_run" && reasons.has("VISUAL_QA_LOCAL_TARGET");
+  const secretExposure = actionType === "secret_access" || reasons.has("SECRET_LIKE_TARGET") && (actionType === "network_request" || actionType === "tool_call" || actionType === "mcp_tool_call");
+  const blockedIntake = input.intakeContext?.matchedItems?.some((item) => item.reviewStatus === "blocked");
+  const riskyInstallIntake =
+    intakeReasons.has("UNKNOWN_PACKAGE_INSTALL")
+    || intakeReasons.has("PACKAGE_NON_REGISTRY_SOURCE")
+    || intakeReasons.has("INSTALL_SCRIPT_PRESENT")
+    || intakeReasons.has("NETWORK_SCRIPT_PRESENT")
+    || intakeReasons.has("DESTRUCTIVE_SCRIPT_PRESENT")
+    || intakeReasons.has("UNKNOWN_MCP_SOURCE")
+    || intakeReasons.has("UNKNOWN_EXTENSION_SOURCE");
+
+  if (actionType === "prompt_compile") {
+    rules.push({ id: "safe_prompt_compile_allow", outcome: "allow", summary: "Safe prompt compilation stays local." });
+  }
+
+  if (localhostVisualQa) {
+    rules.push({
+      id: "local_visual_qa_allow",
+      outcome: input.runnerAvailable === false ? "warn" : "allow",
+      summary: input.runnerAvailable === false
+        ? "Local Visual QA target is safe, but the local runner is unavailable."
+        : "Local Visual QA target stays inside localhost scope.",
+    });
+  }
+
+  if (isSensitiveFileWrite) {
+    rules.push({
+      id: "sensitive_file_write_guard",
+      outcome: reasons.has("SECRET_LIKE_TARGET") || reasons.has("SENSITIVE_ENV_FILE") ? "approval_required" : "warn",
+      summary: "Sensitive file writes need a narrower scope or explicit approval.",
+    });
+  }
+
+  if (secretExposure) {
+    rules.push({
+      id: "secret_exposure_block",
+      outcome: "block",
+      summary: "Secret access or exposure is not allowed.",
+    });
+  }
+
+  if (blockedIntake) {
+    rules.push({
+      id: "blocked_intake_guard",
+      outcome: "block",
+      summary: "The requested runtime surface is blocked by local intake review and must not be trusted automatically.",
+    });
+  }
+
+  if (hasPromptInjection && (isSensitiveFileWrite || writeCapableTool || externalExport || browserExternal || externalNetwork)) {
+    rules.push({
+      id: "prompt_injection_sensitive_action_guard",
+      outcome: risk.riskLevel === "critical" ? "block" : "approval_required",
+      summary: "Prompt-injection signals plus a sensitive action require a hard stop or approval.",
+    });
+  }
+
+  if (hasIntentMismatch) {
+    rules.push({
+      id: "intent_mismatch_guard",
+      outcome: profile.plan === "pro" && risk.riskLevel !== "low" ? "approval_required" : "warn",
+      summary: "The requested action does not match the user’s stated task.",
+    });
+  }
+
+  if (browserExternal) {
+    rules.push({
+      id: "browser_external_domain_guard",
+      outcome: profile.plan === "pro" ? "approval_required" : "warn",
+      summary: "External browser targets need a boundary or review before proceeding.",
+    });
+  }
+
+  if (browserSecretRisk) {
+    rules.push({
+      id: "browser_cookie_session_block",
+      outcome: "block",
+      summary: "Browser actions touching cookies, sessions, or secrets are blocked.",
+    });
+  }
+
+  if (unknownTool) {
+    rules.push({
+      id: "unknown_tool_guard",
+      outcome: profile.plan === "pro" ? "approval_required" : "warn",
+      summary: "Unknown tools and MCP targets should not be blindly trusted.",
+    });
+  }
+
+  if (riskyInstallIntake) {
+    rules.push({
+      id: "install_intake_review_guard",
+      outcome: profile.plan === "pro" || blockedIntake ? "approval_required" : "warn",
+      summary: "Local intake signals show this package, MCP, extension, or guidance surface needs review before normal runtime trust.",
+    });
+  }
+
+  if (writeCapableTool) {
+    rules.push({
+      id: "write_capable_tool_guard",
+      outcome: profile.plan === "pro" ? "approval_required" : "warn",
+      summary: "Write-capable tools require a narrower reviewed scope.",
+    });
+  }
+
+  if (destructiveCommand) {
+    rules.push({
+      id: "destructive_command_block",
+      outcome: "block",
+      summary: "Destructive commands are blocked.",
+    });
+  }
+
+  if (externalExport) {
+    rules.push({
+      id: "external_export_guard",
+      outcome: "block",
+      summary: "External repository export is blocked by default.",
+    });
+  } else if (externalNetwork) {
+    rules.push({
+      id: "external_network_guard",
+      outcome: profile.plan === "pro" ? "approval_required" : "warn",
+      summary: "External network requests need scoped review.",
+    });
+  }
+
+  if ((actionType === "tool_call" || actionType === "mcp_tool_call") && !unknownTool && !writeCapableTool && risk.riskLevel === "low") {
+    rules.push({
+      id: "trusted_tool_allow",
+      outcome: "allow",
+      summary: "Trusted local tool usage stays within normal scope.",
+    });
+  }
+
+  if ((actionType === "file_read" || actionType === "unknown") && risk.riskLevel === "low") {
+    rules.push({
+      id: "low_risk_local_read_allow",
+      outcome: "allow",
+      summary: "The action looks like a low-risk local read or inspection.",
+    });
+  }
+
+  if (!rules.length && risk.riskLevel === "medium") {
+    rules.push({
+      id: "medium_risk_default_warn",
+      outcome: "warn",
+      summary: "The action carries moderate uncertainty and should stay visible.",
+    });
+  }
+
+  if (!rules.length && risk.riskLevel === "high") {
+    rules.push({
+      id: "high_risk_default_review",
+      outcome: profile.plan === "pro" ? "approval_required" : "warn",
+      summary: "The action is high risk and should not proceed silently.",
+    });
+  }
+
+  if (!rules.length && risk.riskLevel === "critical") {
+    rules.push({
+      id: "critical_risk_default_block",
+      outcome: "block",
+      summary: "The action is critically risky and should not proceed.",
+    });
+  }
+
+  return rules;
+}
+
+function decisionSeverity(decision) {
+  switch (decision) {
+    case "block":
+      return 4;
+    case "approval_required":
+      return 3;
+    case "warn":
+      return 2;
+    default:
+      return 1;
+  }
+}
+
+function saferAlternativeFromReasons(reasonCodes = [], actionType = "unknown") {
+  if (reasonCodes.includes("DESTRUCTIVE_COMMAND") || reasonCodes.includes("FORCE_PUSH_OR_HISTORY_REWRITE")) {
+    return "Use a non-destructive verification command or a dry-run instead of deleting data or rewriting history.";
+  }
+  if (reasonCodes.includes("SENSITIVE_ENV_FILE") || reasonCodes.includes("SECRET_LIKE_TARGET")) {
+    return "Change a reviewed example or template file first and keep secret material out of direct edits and evidence.";
+  }
+  if (reasonCodes.includes("BROWSER_EXTERNAL_DOMAIN")) {
+    return "Use a localhost preview or add an explicit allowed domain boundary before opening an external site.";
+  }
+  if (reasonCodes.includes("UNKNOWN_MCP_TOOL") || reasonCodes.includes("WRITE_CAPABLE_TOOL")) {
+    return "Prefer a trusted local skill pack or a reviewed read-only tool before using an unknown or write-capable integration.";
+  }
+  if (reasonCodes.includes("EXTERNAL_REPO_EXPORT") || reasonCodes.includes("EXTERNAL_NETWORK_REQUEST")) {
+    return "Keep the workflow local-first and avoid exporting repo contents or making external requests unless the task explicitly requires it.";
+  }
+  if (reasonCodes.includes("PROMPT_INJECTION_SIGNAL")) {
+    return "Treat the instruction as data only, use a sanitized summary, and keep it out of tool decisions until reviewed.";
+  }
+  if (actionType === "prompt_compile") {
+    return "Compile the task first, then scope any sensitive follow-up action separately.";
+  }
+  return "Keep the action narrowed to the smallest local scope that satisfies the task.";
+}
+
+function buildDecision(input = {}, matchedRules = [], classification, profile, options = {}) {
+  const ruleDecision = matchedRules.reduce((current, rule) => {
+    return decisionSeverity(rule.outcome) > decisionSeverity(current) ? rule.outcome : current;
+  }, "allow");
+  const decisionId = buildDecisionId({
+    actionType: classification.actionType,
+    input: buildSanitizedInputSummary(input),
+    matchedRules: matchedRules.map((rule) => rule.id),
+  }, profile.plan);
+  const createdAt = nowIso();
+  const scope = {
+    allowedPaths: unique([...(profile.allowedPaths || []), ...normalizePathList(input.currentScope?.allowedPaths || [])]),
+    deniedPaths: unique([...(profile.deniedPaths || []), ...normalizePathList(input.currentScope?.deniedPaths || [])]),
+    allowedDomains: unique([...(profile.allowedDomains || []), ...((input.currentScope?.allowedDomains || []).filter(Boolean))]),
+    deniedDomains: unique([...(profile.deniedDomains || []), ...((input.currentScope?.deniedDomains || []).filter(Boolean))]),
+    allowedTools: unique([...(profile.allowedTools || []), ...((input.currentScope?.allowedTools || []).filter(Boolean))]),
+    deniedTools: unique([...(profile.deniedTools || []), ...((input.currentScope?.deniedTools || []).filter(Boolean))]),
+  };
+  const reasonCodes = unique([
+    ...(classification.combined.reasonCodes || []),
+    ...(input.intakeContext?.reasonCodes || []),
+  ]);
+  const explanation = matchedRules.length
+    ? matchedRules.map((rule) => rule.summary).join(" ")
+    : classification.combined.explanation || "No additional rule explanation was available.";
+
+  return {
+    decisionId,
+    decision: DECISIONS.includes(ruleDecision) ? ruleDecision : "warn",
+    actionType: classification.actionType,
+    riskLevel: classification.combined.riskLevel,
+    reasonCodes,
+    matchedRules: matchedRules.map((rule) => rule.id),
+    explanation,
+    saferAlternative: (() => {
+      const ruleDecisionFinal = DECISIONS.includes(ruleDecision) ? ruleDecision : "warn";
+      const continuation = buildTaskContinuation({
+        actionType: classification.actionType,
+        target: input.target || input.command || input.url || input.toolName || "",
+        task: input.userIntent || input.taskType || "",
+        riskLevel: classification.combined.riskLevel,
+        decision: ruleDecisionFinal,
+        reasonCodes,
+      });
+      // Task-continuation is primary; fall back to intake action only as a supplement
+      const intakeAction = input.intakeContext?.safeNextAction;
+      const taskAction = continuation.safeNextAction;
+      return sanitizeText(taskAction || intakeAction || "Keep the action narrowed to the smallest local scope.");
+    })(),
+    requiresApproval: ruleDecision === "approval_required",
+    blocked: ruleDecision === "block",
+    scope,
+    ttlSeconds: ruleDecision === "approval_required" ? Number(profile.ttlSeconds || 0) : null,
+    evidencePath: null,
+    createdAt,
+    plan: profile.plan,
+    mode: profile.mode,
+    sanitizedInputSummary: buildSanitizedInputSummary(input),
+    schemaVersion: SCHEMA_VERSION,
+  };
+}
+
+function sanitizeText(value) {
+  return redactSecrets(String(value || ""));
+}
+
+function recordGovernanceLearningSignals(cwd, receipt) {
+  const events = [
+    {
+      eventName: "access_governance_evaluated",
+      category: "access_governance",
+      status: receipt.decision,
+      payload: {
+        subjectType: receipt.subjectSummary.type,
+        trustStatus: receipt.subjectSummary.trustStatus,
+        actionType: receipt.requestedActionSummary.type,
+        decision: receipt.decision,
+        reasonCodes: receipt.reasonCodes,
+      },
+    },
+    {
+      eventName: "access_receipt_written",
+      category: "access_governance",
+      status: "recorded",
+      payload: {
+        decisionId: receipt.decisionId,
+        subjectType: receipt.subjectSummary.type,
+        trustStatus: receipt.subjectSummary.trustStatus,
+      },
+    },
+  ];
+
+  if (receipt.subjectSummary.trustStatus === "unknown") {
+    events.push({
+      eventName: "access_subject_unknown",
+      category: "access_governance",
+      status: receipt.decision,
+      payload: {
+        subjectType: receipt.subjectSummary.type,
+        requestedActionType: receipt.requestedActionSummary.type,
+      },
+    });
+  }
+
+  if (receipt.decision === "approval_required") {
+    events.push({
+      eventName: "access_scope_requires_approval",
+      category: "access_governance",
+      status: "approval_required",
+      payload: {
+        subjectType: receipt.subjectSummary.type,
+        requestedActionType: receipt.requestedActionSummary.type,
+      },
+    });
+  }
+
+  if (receipt.decision === "block") {
+    events.push({
+      eventName: "access_blocked",
+      category: "access_governance",
+      status: "blocked",
+      payload: {
+        subjectType: receipt.subjectSummary.type,
+        reasonCodes: receipt.reasonCodes,
+      },
+    });
+  } else if (receipt.decision === "warn") {
+    events.push({
+      eventName: "access_warned",
+      category: "access_governance",
+      status: "warned",
+      payload: {
+        subjectType: receipt.subjectSummary.type,
+        reasonCodes: receipt.reasonCodes,
+      },
+    });
+  }
+
+  events.forEach((event) => {
+    try {
+      appendProductLearningEvent(cwd, event);
+    } catch {}
+  });
+}
+
+function writeEnforcementEvidence(decision, options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  ensureCcoDirs(cwd);
+
+  const payload = redactSecrets({
+    schemaVersion: SCHEMA_VERSION,
+    decisionId: decision.decisionId,
+    timestamp: decision.createdAt,
+    plan: decision.plan,
+    mode: decision.mode,
+    actionType: decision.actionType,
+    sanitizedInputSummary: decision.sanitizedInputSummary,
+    decision: decision.decision,
+    riskLevel: decision.riskLevel,
+    reasonCodes: decision.reasonCodes,
+    matchedRules: decision.matchedRules,
+    saferAlternative: decision.saferAlternative,
+    source: options.source || decision.sanitizedInputSummary.requestedBy || "cli",
+  });
+
+  safeWriteJson(cwd, LATEST_EVIDENCE_REL_PATH, payload);
+  appendJsonl(cwd, EVENT_LOG_REL_PATH, payload);
+
+  let historyPath = null;
+  if (canExportReports(decision.plan)) {
+    historyPath = `${HISTORY_DIR_REL_PATH}/${decision.decisionId}.json`;
+    safeWriteJson(cwd, historyPath, payload);
+  }
+
+  return historyPath || LATEST_EVIDENCE_REL_PATH;
+}
+
+function readLatestEnforcementEvidence(cwd) {
+  return safeReadJson(cwd, LATEST_EVIDENCE_REL_PATH, null);
+}
+
+function summarizeEnforcementEvidence(cwd) {
+  try {
+    const latest = readLatestEnforcementEvidence(cwd);
+    if (!latest) return null;
+    return {
+      decisionId: latest.decisionId || null,
+      decision: latest.decision || null,
+      riskLevel: latest.riskLevel || null,
+      reasonCodes: Array.isArray(latest.reasonCodes) ? latest.reasonCodes : [],
+      matchedRules: Array.isArray(latest.matchedRules) ? latest.matchedRules : [],
+      createdAt: latest.timestamp || null,
+      summary: latest.decision
+        ? `${latest.decision} ${latest.actionType || "action"} (${latest.riskLevel || "unknown"} risk)`
+        : "Latest enforcement evidence is present.",
+    };
+  } catch {
+    return {
+      decisionId: null,
+      decision: null,
+      riskLevel: null,
+      reasonCodes: [],
+      matchedRules: [],
+      createdAt: null,
+      summary: "Latest enforcement evidence is unreadable.",
+    };
+  }
+}
+
+function explainDecision(decision) {
+  return `${decision.decision} ${decision.actionType} (${decision.riskLevel} risk): ${decision.explanation}`;
+}
+
+function isApprovalRequired(decision) {
+  return decision?.decision === "approval_required";
+}
+
+function isBlocked(decision) {
+  return decision?.decision === "block";
+}
+
+function evaluateAgentAction(input = {}, options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const plan = String(input.plan || options.plan || getCurrentPlan({ cwd })).trim().toLowerCase() === "pro" ? "pro" : "free";
+  const profile = buildPolicyProfile({
+    cwd,
+    plan,
+    overrides: options.profileOverrides,
+  });
+  const intakeContext = buildActionIntakeContext(cwd, input, {
+    writeReceipt: options.writeEvidence !== false,
+    plan,
+  });
+  const enrichedInput = {
+    ...input,
+    subject: input.subject || intakeContext.subject || undefined,
+    toolMetadata: {
+      ...(input.toolMetadata || {}),
+      ...(intakeContext.toolMetadata || {}),
+    },
+    intakeContext,
+  };
+  const classification = classifyAction(enrichedInput);
+  classification.combined = {
+    ...classification.combined,
+    riskLevel: maxRisk(classification.combined.riskLevel, intakeContext.riskLevel || "low"),
+    reasonCodes: unique([
+      ...(classification.combined.reasonCodes || []),
+      ...(intakeContext.reasonCodes || []),
+    ]),
+    explanation: [
+      classification.combined.explanation,
+      intakeContext.reasonCodes?.length ? `Install intake signals: ${(intakeContext.reasonCodes || []).join(", ")}.` : null,
+    ].filter(Boolean).join(" "),
+    recommendedAction: unique([
+      classification.combined.recommendedAction,
+      intakeContext.safeNextAction,
+    ]).filter(Boolean).join(" "),
+  };
+  const matchedRules = getMatchedRules(enrichedInput, classification, profile);
+  const initialDecision = buildDecision(enrichedInput, matchedRules, classification, profile, options);
+  const initialReceipt = buildGovernanceReceipt(enrichedInput, initialDecision, classification);
+  const decision = applyGovernanceDecisionFloor(initialDecision, initialReceipt);
+  const governanceReceipt = buildGovernanceReceipt(enrichedInput, decision, classification);
+  const safePathReceipt = buildSafePathReceipt(enrichedInput, decision, governanceReceipt, {
+    cwd,
+    classification,
+    profile,
+    intakeContext,
+  });
+
+  if (options.writeEvidence !== false) {
+    decision.evidencePath = writeEnforcementEvidence(decision, {
+      cwd,
+      source: input.requestedBy || options.source || "cli",
+    });
+    governanceReceipt.evidencePath = writeGovernanceReceipt(cwd, governanceReceipt, { plan });
+    decision.governanceReceiptPath = governanceReceipt.evidencePath;
+    decision.governance = governanceReceipt;
+    decision.safePathReceiptPath = writeSafePathReceipt(cwd, safePathReceipt, { plan });
+    decision.safePath = safePathReceipt;
+    decision.installIntakeReceiptPath = intakeContext.receiptPath || LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH;
+    decision.installIntake = {
+      summary: intakeContext.receipt.summary,
+      matchedItems: intakeContext.matchedItems.map((item) => ({
+        id: item.id,
+        type: item.type,
+        name: item.name,
+        reviewStatus: item.reviewStatus,
+        riskLevel: item.riskLevel,
+        reasonCodes: item.reasonCodes,
+      })),
+      nextAction: intakeContext.safeNextAction || intakeContext.receipt.nextAction,
+      topReasonCodes: intakeContext.receipt.topReasonCodes || [],
+    };
+    recordGovernanceLearningSignals(cwd, governanceReceipt);
+    recordSafePathLearningSignals(cwd, safePathReceipt);
+  } else {
+    decision.governanceReceiptPath = null;
+    decision.governance = governanceReceipt;
+    decision.safePathReceiptPath = null;
+    decision.safePath = safePathReceipt;
+    decision.installIntakeReceiptPath = null;
+    decision.installIntake = {
+      summary: intakeContext.receipt.summary,
+      matchedItems: intakeContext.matchedItems,
+      nextAction: intakeContext.safeNextAction || intakeContext.receipt.nextAction,
+      topReasonCodes: intakeContext.receipt.topReasonCodes || [],
+    };
+  }
+
+  return decision;
+}
+
+function buildPlanSecuritySurface(cwd, options = {}) {
+  const plan = String(options.plan || getCurrentPlan({ cwd })).trim().toLowerCase() === "pro" ? "pro" : "free";
+  const profile = buildPolicyProfile({ cwd, plan });
+  const description = describePolicyProfile(profile);
+  const latestEvidence = summarizeEnforcementEvidence(cwd);
+
+  return {
+    plan,
+    headline: "Powerful AI agents, safer by default.",
+    customerPromise: "Avorelo helps protect AI coding workflows with prompt-injection defense, risky-skill detection, destructive-action blocking, and local evidence, while access-reduction paths stay scoped to the surfaces that support them.",
+    mode: profile.mode,
+    profileId: profile.profileId,
+    zeroStandingPermissions: profile.zeroStandingPermissions === true,
+    scopedJitStyleAccess: profile.scopedJitStyleAccess === true,
+    enforcementAvailability: profile.enforcementAvailable,
+    headlineLine: description.headline,
+    postureLine: plan === "pro"
+      ? "Security posture: approve/enforce where supported."
+      : "Security posture: visibility and warnings first, with blocks for clearly unsafe actions.",
+    summary: description.summary,
+    latestEvidence,
+  };
+}
+
+module.exports = {
+  DECISIONS,
+  EVIDENCE_DIR_REL_PATH,
+  LATEST_EVIDENCE_REL_PATH,
+  HISTORY_DIR_REL_PATH,
+  EVENT_LOG_REL_PATH,
+  redactSecrets,
+  classifyAction,
+  getMatchedRules,
+  buildDecision,
+  writeEnforcementEvidence,
+  readLatestEnforcementEvidence,
+  summarizeEnforcementEvidence,
+  explainDecision,
+  isApprovalRequired,
+  isBlocked,
+  evaluateAgentAction,
+  buildPlanSecuritySurface,
+  buildAgentAccessGovernanceSurface,
+  buildSafePathSurface,
+};