avorelo 0.1.0

package/scripts/lib/agent-security/action-evaluator.js

@@ -0,0 +1,507 @@
+"use strict";
+
+const crypto = require("crypto");
+const {
+  contentHashFromAction,
+  normalizePath,
+  classifyFilesystemWriteTarget,
+  isSensitiveWriteTarget,
+  isWorkflowWriteTarget,
+  targetHashFromAction,
+} = require("./file-write-rules");
+const { classifyPackageAction } = require("./package-action-rules");
+const { classifyMcpAction, argsHashFromAction, targetHashFromMcpAction } = require("./mcp-action-rules");
+
+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 buildScopeKey(normalized) {
+  return sha256(stableStringify({
+    componentId: normalized.componentId || "",
+    componentType: normalized.componentType || "",
+    actionType: normalized.actionType || "",
+    cwd: normalized.context?.cwd || "",
+    target: normalized.target || "",
+    commandHash: normalized.commandHash || "",
+    targetHash: normalized.targetHash || "",
+    contentHash: normalized.contentHash || "",
+    argsHash: normalized.argsHash || "",
+    packageManager: normalized.packageManager || "",
+    scriptName: normalized.scriptName || "",
+    packageName: normalized.packageName || "",
+    mcpServer: normalized.mcpServer || "",
+    toolName: normalized.toolName || "",
+  })).slice(0, 16);
+}
+
+function buildActionIdFromNormalized(normalized) {
+  return `action-${sha256(stableStringify({
+    componentId: normalized.componentId || "",
+    componentType: normalized.componentType || "",
+    actionType: normalized.actionType || "",
+    target: normalized.target || "",
+    commandHash: normalized.commandHash || "",
+    targetHash: normalized.targetHash || "",
+    contentHash: normalized.contentHash || "",
+    argsHash: normalized.argsHash || "",
+    scopeKey: normalized.scopeKey || "",
+    source: normalized.source || "",
+  })).slice(0, 12)}`;
+}
+
+function normalizeAgentSecurityAction(action) {
+  const actionType = String(action?.actionType || "filesystem.read");
+  const target = normalizePath(action?.target || "");
+  const command = String(action?.command || "");
+  const contentHash = contentHashFromAction(action);
+  const targetHash = actionType === "filesystem.write"
+    ? targetHashFromAction(action)
+    : actionType.startsWith("mcp.")
+      ? targetHashFromMcpAction(action)
+      : target
+        ? sha256(target)
+        : null;
+  const argsHash = actionType.startsWith("mcp.") ? argsHashFromAction(action) : null;
+  const normalized = {
+    componentId: action?.componentId || null,
+    componentType: action?.componentType || "config",
+    actionType,
+    target,
+    command,
+    commandHash: command ? sha256(command) : null,
+    targetHash,
+    contentHash,
+    argsHash,
+    source: normalizePath(action?.source || ""),
+    context: {
+      cwd: normalizePath(action?.context?.cwd || process.cwd()),
+      task: String(action?.context?.task || ""),
+      sessionId: String(action?.context?.sessionId || ""),
+    },
+    relatedSourceIds: Array.isArray(action?.relatedSourceIds)
+      ? action.relatedSourceIds.map((item) => String(item || "")).filter(Boolean)
+      : Array.isArray(action?.context?.relatedSourceIds)
+        ? action.context.relatedSourceIds.map((item) => String(item || "")).filter(Boolean)
+        : [],
+    content: typeof action?.content === "string" ? action.content : null,
+    packageManager: String(action?.packageManager || ""),
+    scriptName: String(action?.scriptName || ""),
+    packageName: String(action?.packageName || ""),
+    mcpServer: String(action?.mcpServer || ""),
+    toolName: String(action?.toolName || ""),
+    resource: action?.resource && typeof action.resource === "object" ? action.resource : null,
+    args: action?.args && typeof action.args === "object" ? action.args : null,
+  };
+  normalized.scopeKey = buildScopeKey(normalized);
+  normalized.actionId = action?.actionId || buildActionIdFromNormalized(normalized);
+  return normalized;
+}
+
+function buildActionId(action) {
+  return normalizeAgentSecurityAction(action).actionId;
+}
+
+function hasPattern(text, pattern) {
+  return pattern.test(String(text || ""));
+}
+
+function isSensitivePath(value) {
+  return isSensitiveWriteTarget(value);
+}
+
+function isWorkflowPath(value) {
+  return isWorkflowWriteTarget(value);
+}
+
+function isSafeTestCommand(command) {
+  const normalized = String(command || "").trim().toLowerCase();
+  if (!normalized) return false;
+  if (/[|;&><]/.test(normalized)) return false;
+  return /^(npm test|npm run test\b|pnpm test\b|pnpm run test\b|yarn test\b|node tests[\\/]|node --test\b|pytest\b|vitest\b|cargo test\b|go test\b)/i.test(normalized);
+}
+
+function inferActionCapabilities(action, componentCard) {
+  const capabilities = new Set();
+  const actionType = String(action?.actionType || "");
+  const text = `${actionType}\n${action?.target || ""}\n${action?.command || ""}\n${action?.source || ""}`;
+
+  if (actionType.startsWith("filesystem.read")) capabilities.add("filesystemRead");
+  if (actionType.startsWith("filesystem.write")) capabilities.add("filesystemWrite");
+  if (actionType === "shell.run") capabilities.add("shell");
+  if (actionType === "package.run" || actionType === "package.script" || actionType === "package.install") capabilities.add("shell");
+  if (actionType === "network.call") capabilities.add("network");
+  if (actionType === "mcp.read") capabilities.add("mcpRead");
+  if (actionType === "mcp.write" || actionType === "mcp.delete" || actionType === "mcp.admin" || actionType === "mcp.externalMutation" || actionType === "mcp.unknown") {
+    capabilities.add("mcpWrite");
+    capabilities.add("externalMutation");
+  }
+  if (actionType === "mcp.read" || actionType === "mcp.unknown") capabilities.add("mcpRead");
+  if (
+    actionType === "workflow.modify" ||
+    actionType === "config.modify" ||
+    actionType === "package.install" ||
+    actionType === "package.script" ||
+    actionType === "package.lockfile.modify"
+  ) {
+    capabilities.add("filesystemWrite");
+  }
+  if (actionType === "package.install") capabilities.add("network");
+
+  if (hasPattern(text, /\bhttps?:\/\/|curl|wget|invoke-webrequest|invoke-restmethod|downloadstring\b/i)) {
+    capabilities.add("network");
+  }
+  if (isSensitivePath(text)) capabilities.add("sensitiveAccess");
+  if (isWorkflowPath(text)) capabilities.add("externalMutation");
+
+  const componentCapabilities = componentCard?.capabilities || {};
+  Object.keys(componentCapabilities).forEach((key) => {
+    if (componentCapabilities[key]) capabilities.add(key);
+  });
+
+  return Array.from(capabilities);
+}
+
+function collectSensitiveTargets(action) {
+  const sensitiveTargets = [];
+  [action?.target, action?.source, action?.command].forEach((value) => {
+    if (!value || !isSensitivePath(value)) return;
+    const nextValue = String(value);
+    if (!sensitiveTargets.includes(nextValue)) sensitiveTargets.push(nextValue);
+  });
+  return sensitiveTargets;
+}
+
+function buildIntentMismatchSignal(normalizedAction, relatedSources = []) {
+  const task = String(normalizedAction?.context?.task || "").toLowerCase();
+  const target = String(normalizedAction?.target || "").toLowerCase();
+  const command = String(normalizedAction?.command || "").toLowerCase();
+  const toolName = String(normalizedAction?.toolName || "").toLowerCase();
+  const actionType = String(normalizedAction?.actionType || "").toLowerCase();
+  const sourceRisky = relatedSources.some((source) => source && source.instructionRisk === "high");
+
+  if (!task) return null;
+
+  const stylingTask = /\b(style|styling|css|button|ui|frontend|layout|color|spacing|font)\b/.test(task);
+  const targetLooksSensitive = /\.env\b|id_rsa|private.?key|credential|secret/.test(target) || /\.env\b|id_rsa|private.?key|credential|secret/.test(command);
+  const workflowLike = /\.github\/workflows\//.test(target) || /\bworkflow|github actions|ci\b/.test(command);
+  const packageInstallLike = actionType === "package.install" || /\bnpm install|pnpm add|yarn add|bun add\b/.test(command);
+  const destructiveMcp = actionType === "mcp.delete" || actionType === "mcp.admin" || /\bdelete|admin\b/.test(toolName);
+  const remoteScript = /\bcurl\b[^\n]*\|\s*(bash|sh|pwsh|powershell)\b/.test(command);
+
+  if (stylingTask && (targetLooksSensitive || workflowLike || packageInstallLike || destructiveMcp || remoteScript || sourceRisky)) {
+    return {
+      signal: "intent_mismatch",
+      message: "The requested action does not match the stated task.",
+    };
+  }
+  if (!/\b(dependen|install|package|npm|pnpm|yarn)\b/.test(task) && packageInstallLike) {
+    return {
+      signal: "intent_mismatch",
+      message: "Package installation does not match the stated task.",
+    };
+  }
+  if (!/\b(workflow|ci|release|deploy|github actions)\b/.test(task) && workflowLike) {
+    return {
+      signal: "intent_mismatch",
+      message: "Workflow modification does not match the stated task.",
+    };
+  }
+  if (!/\b(secret|credential|env|config)\b/.test(task) && targetLooksSensitive) {
+    return {
+      signal: "intent_mismatch",
+      message: "Sensitive file access does not match the stated task.",
+    };
+  }
+  return null;
+}
+
+function evaluateAgentSecurityAction(action, options = {}) {
+  const componentCard = options.componentCard || null;
+  const relatedSources = Array.isArray(options.relatedSources) ? options.relatedSources : [];
+  const normalizedAction = {
+    ...normalizeAgentSecurityAction(action),
+    componentId: action?.componentId || componentCard?.id || null,
+    componentType: action?.componentType || componentCard?.type || "config",
+    source: normalizePath(action?.source || componentCard?.source || ""),
+  };
+
+  const reasons = [];
+  const capabilities = inferActionCapabilities(normalizedAction, componentCard);
+  const sensitiveTargets = collectSensitiveTargets(normalizedAction);
+  const explicitRelatedSourceIds = normalizedAction.relatedSourceIds.length > 0
+    ? normalizedAction.relatedSourceIds
+    : componentCard?.id
+      ? [componentCard.id]
+      : [];
+  const componentStatus = componentCard?.status || "known";
+  const componentTrust = componentCard
+    ? (componentCard.trustLevel || "unknown")
+    : (normalizedAction.actionType.startsWith("package.") ? "local" : "unknown");
+  const permissionExpansion = capabilities.some((capability) => componentCard?.capabilities?.[capability] === false);
+  const targetAndCommand = `${normalizedAction.target}\n${normalizedAction.command}`.toLowerCase();
+  const highRiskRelatedSource = relatedSources.find((source) => source && source.instructionRisk === "high");
+  const suspiciousExternalSource = relatedSources.find((source) => source && ["external_untrusted", "tool_returned_untrusted", "unknown"].includes(source.trustLevel));
+  const quarantinedSource = relatedSources.find((source) => Array.isArray(source.remediationActions) && source.remediationActions.includes("quarantine_source"));
+  const dataOnlySource = relatedSources.find((source) => source && source.allowedToInfluenceTools === false);
+  const trustedOverrideSource = relatedSources.find((source) => Array.isArray(source.remediationActions) && source.remediationActions.includes("trust_source"));
+  const writeProfile = normalizedAction.actionType === "filesystem.write"
+    ? classifyFilesystemWriteTarget(normalizedAction.context?.cwd || process.cwd(), normalizedAction.target)
+    : null;
+  const packageProfile = normalizedAction.actionType.startsWith("package.")
+    ? classifyPackageAction(normalizedAction)
+    : null;
+  const mcpProfile = normalizedAction.actionType.startsWith("mcp.")
+    ? classifyMcpAction({
+      ...normalizedAction,
+      target: action?.target || normalizedAction.target,
+      resource: action?.resource,
+      args: action?.args,
+      mcpServer: action?.mcpServer || normalizedAction.mcpServer,
+      toolName: action?.toolName || normalizedAction.toolName,
+    })
+    : null;
+
+  let riskScore = 1;
+  let recommendedDecision = "approve";
+
+  if (normalizedAction.actionType === "filesystem.read" && sensitiveTargets.length === 0 && componentStatus === "known" && componentTrust !== "unknown") {
+    reasons.push("Local read-only action on non-sensitive files.");
+  }
+
+  if (isSafeTestCommand(normalizedAction.command) && componentStatus === "known" && componentTrust !== "unknown") {
+    reasons.push("Known local test command.");
+  }
+
+  if (sensitiveTargets.length > 0) {
+    reasons.push("Sensitive files or secret-like targets are involved.");
+    riskScore = Math.max(riskScore, 3);
+    recommendedDecision = normalizedAction.actionType === "filesystem.read" ? "limit" : "deny";
+  }
+
+  if (highRiskRelatedSource && !trustedOverrideSource) {
+    reasons.push("A related source contains high-risk instruction-like content.");
+    riskScore = Math.max(riskScore, 3);
+    if (
+      normalizedAction.actionType === "filesystem.write" ||
+      normalizedAction.actionType === "shell.run" ||
+      normalizedAction.actionType.startsWith("package.") ||
+      normalizedAction.actionType.startsWith("mcp.") ||
+      normalizedAction.actionType === "network.call"
+    ) {
+      recommendedDecision = normalizedAction.actionType === "filesystem.read" ? "limit" : "deny";
+    }
+  }
+
+  if (quarantinedSource) {
+    reasons.push("A related source is quarantined.");
+    riskScore = Math.max(riskScore, 3);
+    recommendedDecision = normalizedAction.actionType === "filesystem.read" ? "limit" : "deny";
+  }
+
+  if (suspiciousExternalSource && dataOnlySource) {
+    reasons.push("A related untrusted source must be treated as data only.");
+    riskScore = Math.max(riskScore, 2);
+    if (recommendedDecision === "approve") recommendedDecision = "limit";
+  }
+
+  if (normalizedAction.actionType === "workflow.modify" || isWorkflowPath(normalizedAction.target)) {
+    reasons.push("Workflow modification can change automation or release behavior.");
+    riskScore = Math.max(riskScore, 3);
+    recommendedDecision = "limit";
+  }
+
+  if (normalizedAction.actionType === "filesystem.write") {
+    writeProfile.reasons.forEach((reason) => {
+      if (!reasons.includes(reason)) reasons.push(reason);
+    });
+
+    if (writeProfile.riskLevel === "high") {
+      riskScore = Math.max(riskScore, 3);
+      recommendedDecision = writeProfile.workflow ? "limit" : "deny";
+    } else if (writeProfile.riskLevel === "medium") {
+      riskScore = Math.max(riskScore, 2);
+      recommendedDecision = recommendedDecision === "approve" ? "limit" : recommendedDecision;
+    } else {
+      riskScore = Math.max(riskScore, 1);
+      recommendedDecision = recommendedDecision === "approve" ? "limit" : recommendedDecision;
+    }
+  }
+
+  if (packageProfile) {
+    packageProfile.reasons.forEach((reason) => {
+      if (!reasons.includes(reason)) reasons.push(reason);
+    });
+
+    if (packageProfile.riskLevel === "high") {
+      riskScore = Math.max(riskScore, 3);
+      recommendedDecision = packageProfile.recommendedDecision || "deny";
+    } else if (packageProfile.riskLevel === "medium") {
+      riskScore = Math.max(riskScore, 2);
+      recommendedDecision = recommendedDecision === "approve"
+        ? (packageProfile.recommendedDecision || "limit")
+        : recommendedDecision;
+    } else {
+      riskScore = Math.max(riskScore, 1);
+      recommendedDecision = recommendedDecision === "approve"
+        ? (packageProfile.recommendedDecision || "limit")
+        : recommendedDecision;
+    }
+  }
+
+  if (mcpProfile) {
+    mcpProfile.reasons.forEach((reason) => {
+      if (!reasons.includes(reason)) reasons.push(reason);
+    });
+
+    if (mcpProfile.riskLevel === "high") {
+      riskScore = Math.max(riskScore, 3);
+      recommendedDecision = mcpProfile.recommendedDecision || "deny";
+    } else if (mcpProfile.riskLevel === "medium") {
+      riskScore = Math.max(riskScore, 2);
+      recommendedDecision = recommendedDecision === "approve"
+        ? (mcpProfile.recommendedDecision || "limit")
+        : recommendedDecision;
+    } else {
+      riskScore = Math.max(riskScore, 1);
+      recommendedDecision = recommendedDecision === "approve"
+        ? (mcpProfile.recommendedDecision || "limit")
+        : recommendedDecision;
+    }
+  }
+
+  if (hasPattern(targetAndCommand, /\b(curl|wget)\b[^\n]*\|\s*(bash|sh|pwsh|powershell)\b|\b(invoke-webrequest|invoke-restmethod|downloadstring)\b/i)) {
+    reasons.push("Remote script execution was detected.");
+    riskScore = Math.max(riskScore, 3);
+    recommendedDecision = "deny";
+  }
+
+  if (hasPattern(targetAndCommand, /\brm\s+-rf\b|\bdel\s+\/[qs]\b|\bdelete\b|\bforce push\b|\bgit push\b[^\n]*--force\b|\bremove-item\b/i)) {
+    reasons.push("Destructive command behavior was detected.");
+    riskScore = Math.max(riskScore, 3);
+    recommendedDecision = "deny";
+  }
+
+  if (!mcpProfile && (normalizedAction.actionType === "mcp.write" || normalizedAction.actionType === "mcp.delete" || hasPattern(targetAndCommand, /\badmin\b|\bdelete\b/))) {
+    reasons.push("External mutation through MCP requires approval.");
+    riskScore = Math.max(riskScore, 3);
+    recommendedDecision = normalizedAction.actionType === "mcp.delete" || hasPattern(targetAndCommand, /\badmin\b|\bdelete\b/) ? "deny" : "limit";
+  }
+
+  if (normalizedAction.actionType === "network.call" || capabilities.includes("network")) {
+    reasons.push("Remote network access is involved.");
+    riskScore = Math.max(riskScore, 2);
+    recommendedDecision = recommendedDecision === "approve" ? "limit" : recommendedDecision;
+  }
+
+  if (normalizedAction.actionType === "shell.run" && !isSafeTestCommand(normalizedAction.command)) {
+    reasons.push("Shell execution is involved.");
+    riskScore = Math.max(riskScore, 2);
+    recommendedDecision = recommendedDecision === "approve" ? "limit" : recommendedDecision;
+  }
+
+  if (normalizedAction.actionType === "filesystem.write" || normalizedAction.actionType === "config.modify") {
+    reasons.push("Filesystem write access is requested.");
+    if (!writeProfile || writeProfile.riskLevel !== "low") {
+      riskScore = Math.max(riskScore, 2);
+    }
+    recommendedDecision = recommendedDecision === "approve" ? "limit" : recommendedDecision;
+  }
+
+  if (componentStatus === "new" || componentStatus === "changed") {
+    reasons.push("The component is new or changed since the last recorded scan.");
+    riskScore = Math.max(riskScore, 2);
+  }
+
+  if (componentTrust === "unknown" || componentTrust === "review-needed") {
+    reasons.push("The component trust level still needs review.");
+    riskScore = Math.max(riskScore, 2);
+  }
+
+  if (permissionExpansion) {
+    reasons.push("This action expands beyond the component's recorded posture.");
+    riskScore = Math.max(riskScore, 2);
+    recommendedDecision = recommendedDecision === "approve" ? "limit" : recommendedDecision;
+  }
+
+  const intentMismatch = buildIntentMismatchSignal(normalizedAction, relatedSources);
+  if (intentMismatch) {
+    reasons.push(intentMismatch.message);
+    riskScore = Math.max(riskScore, 3);
+    recommendedDecision = normalizedAction.actionType === "filesystem.read" ? "limit" : "deny";
+  }
+
+  if (reasons.length === 0) {
+    reasons.push("No elevated risk indicators were detected.");
+  }
+
+  const riskLevel = riskScore >= 3 ? "high" : riskScore >= 2 ? "medium" : "low";
+  const decisionRequired =
+    riskLevel === "high" ||
+    riskLevel === "medium" && (
+      normalizedAction.actionType !== "filesystem.read" ||
+      sensitiveTargets.length > 0 ||
+      capabilities.includes("shell") ||
+      capabilities.includes("network") ||
+      capabilities.includes("externalMutation")
+    );
+
+  return {
+    actionId: normalizedAction.actionId,
+    riskLevel,
+    decisionRequired,
+    recommendedDecision,
+    reasons,
+    capabilities,
+    sensitiveTargets,
+    availableChoices: decisionRequired ? ["approve_once", "deny", "let_wuz_limit"] : [],
+    componentId: normalizedAction.componentId,
+    componentType: normalizedAction.componentType,
+    actionType: normalizedAction.actionType,
+    target: normalizedAction.target,
+    command: normalizedAction.command,
+    packageManager: packageProfile?.packageManager || normalizedAction.packageManager || "unknown",
+    scriptName: packageProfile?.scriptName || normalizedAction.scriptName || "",
+    packageName: packageProfile?.packageName || normalizedAction.packageName || "",
+    mcpServer: mcpProfile?.mcpServer || normalizedAction.mcpServer || "unknown",
+    toolName: mcpProfile?.toolName || normalizedAction.toolName || "",
+    argsHash: mcpProfile?.argsHash || normalizedAction.argsHash || null,
+    targetHash: mcpProfile?.targetHash || normalizedAction.targetHash || null,
+    commandHash: normalizedAction.commandHash || null,
+    contentHash: normalizedAction.contentHash || null,
+    scopeKey: normalizedAction.scopeKey || null,
+    context: normalizedAction.context,
+    relatedSourceIds: explicitRelatedSourceIds,
+    relatedSources: relatedSources.map((source) => ({
+      sourceId: source.sourceId,
+      sourceType: source.sourceType,
+      trustLevel: source.trustLevel,
+      instructionRisk: source.instructionRisk,
+      allowedToInfluenceTools: source.allowedToInfluenceTools,
+      remediationActions: Array.isArray(source.remediationActions) ? source.remediationActions : [],
+    })),
+    instructionRisk: highRiskRelatedSource ? "high" : suspiciousExternalSource ? "medium" : "low",
+    intentMismatch: intentMismatch ? intentMismatch.signal : null,
+  };
+}
+
+module.exports = {
+  buildActionId,
+  normalizeAgentSecurityAction,
+  evaluateAgentSecurityAction,
+  isSafeTestCommand,
+  stableStringify,
+};

package/scripts/lib/agent-security/adapter-registry.js

@@ -0,0 +1,98 @@
+"use strict";
+
+const { safeWriteJson } = require("../fsx");
+const { SHELL_COMMAND_ADAPTER } = require("./enforcement-adapter");
+const { FILE_WRITE_ADAPTER } = require("./file-write-adapter");
+const { PACKAGE_ACTION_ADAPTER } = require("./package-action-adapter");
+const { MCP_ACTION_ADAPTER } = require("./mcp-action-adapter");
+
+const ENFORCEMENT_CAPABILITIES_REL_PATH = ".claude/cco/security/agent-enforcement-capabilities.json";
+
+function buildAdapterRegistry(adapters) {
+  const normalizedAdapters = [];
+  const byActionType = new Map();
+
+  for (const adapter of Array.isArray(adapters) ? adapters : []) {
+    if (!adapter || typeof adapter !== "object") continue;
+    const normalized = {
+      adapterId: String(adapter.adapterId || ""),
+      canEvaluate: adapter.canEvaluate === true,
+      canEnforce: adapter.canEnforce === true,
+      supportedActionTypes: Array.isArray(adapter.supportedActionTypes)
+        ? adapter.supportedActionTypes.map((item) => String(item))
+        : [],
+      enforce: typeof adapter.enforce === "function" ? adapter.enforce : null,
+    };
+
+    if (!normalized.adapterId) {
+      throw new Error("Agent Security adapter registry requires adapterId.");
+    }
+
+    normalized.supportedActionTypes.forEach((actionType) => {
+      if (!actionType) return;
+      if (byActionType.has(actionType)) {
+        throw new Error(`Duplicate Agent Security adapter mapping for action type: ${actionType}`);
+      }
+      byActionType.set(actionType, normalized);
+    });
+
+    normalizedAdapters.push(Object.freeze(normalized));
+  }
+
+  return Object.freeze({
+    adapters: normalizedAdapters,
+    byActionType,
+  });
+}
+
+const ADAPTER_REGISTRY = buildAdapterRegistry([
+  SHELL_COMMAND_ADAPTER,
+  FILE_WRITE_ADAPTER,
+  PACKAGE_ACTION_ADAPTER,
+  MCP_ACTION_ADAPTER,
+]);
+
+function listAgentSecurityAdapters() {
+  return ADAPTER_REGISTRY.adapters.map((adapter) => ({
+    adapterId: adapter.adapterId,
+    supportedActionTypes: adapter.supportedActionTypes.slice(),
+    canEvaluate: adapter.canEvaluate,
+    canEnforce: adapter.canEnforce,
+  }));
+}
+
+function resolveAgentSecurityAdapter(actionType) {
+  return ADAPTER_REGISTRY.byActionType.get(String(actionType || "")) || null;
+}
+
+function buildEnforcementCapabilityMatrix(timestamp, mode = "warn", unsupportedActionTypes = []) {
+  return {
+    generatedAt: timestamp || null,
+    mode: String(mode || "warn"),
+    adapters: listAgentSecurityAdapters().map((adapter) => ({
+      adapterId: adapter.adapterId,
+      actionTypes: adapter.supportedActionTypes,
+      status: adapter.canEnforce ? "available" : "unavailable",
+    })),
+    unsupportedActionTypes: Array.from(new Set(
+      (Array.isArray(unsupportedActionTypes) ? unsupportedActionTypes : [])
+        .map((item) => String(item || ""))
+        .filter(Boolean),
+    )),
+  };
+}
+
+function writeEnforcementCapabilityMatrix(cwd, timestamp, mode = "warn", unsupportedActionTypes = []) {
+  const matrix = buildEnforcementCapabilityMatrix(timestamp, mode, unsupportedActionTypes);
+  safeWriteJson(cwd, ENFORCEMENT_CAPABILITIES_REL_PATH, matrix);
+  return matrix;
+}
+
+module.exports = {
+  ENFORCEMENT_CAPABILITIES_REL_PATH,
+  buildAdapterRegistry,
+  listAgentSecurityAdapters,
+  resolveAgentSecurityAdapter,
+  buildEnforcementCapabilityMatrix,
+  writeEnforcementCapabilityMatrix,
+};