mergen-server 1.4.0

package/dist/intelligence/tool-guard.js

@@ -0,0 +1,708 @@
+import { randomUUID, createHash } from "crypto";
+import { hostname } from "os";
+import { CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { evaluateEnterprisePolicy, loadEnterprisePolicy } from "./enterprise-policy-engine.js";
+import { isPolicyDryRun } from "./execution-mode.js";
+import { getTraceId } from "./trace-context.js";
+import { computeRiskScore, getRiskHoldThreshold } from "./risk-score.js";
+import { verifyNoExecve } from "./ebpf-verify.js";
+import { findSimilarIncidents } from "./incident-similarity.js";
+import { parseShellCommand } from "./shell-ast.js";
+import { detectScriptInvocation, detectScriptInvocationFromRawText, evaluateScriptTrust } from "./script-trust.js";
+import { computeBlastRadius, mostSevereBlast } from "./blast-radius.js";
+import { getStores } from "../storage/store-registry.js";
+import {
+  recordGateBlock,
+  recordGatePass,
+  recordGateCoverage,
+  recordGateEvent,
+  recordHitlHold
+} from "./gate-analytics.js";
+import { trackBlock, trackSuccessfulCall } from "../sensor/bypass-tracker.js";
+import { recordActivity } from "./activity-feed.js";
+import { checkAgentProfile } from "./agent-profiles.js";
+import { resolveAgentIdentity } from "./agent-identity.js";
+import {
+  detectSequenceThreat,
+  recordSessionCall,
+  markContaminated,
+  isSessionContaminated,
+  getContaminationSource,
+  updateAgentReputation,
+  getAgentScrutinyTier,
+  READ_ONLY_TOOLS
+} from "./session-threat-tracker.js";
+import logger from "../sensor/logger.js";
+import { assertGateHeartbeatFresh } from "../sensor/gate-heartbeat.js";
+import { registerBypassBlock, checkAndConsumeBypass } from "./bypass.js";
+import { holdToolCall } from "./hitl-hold.js";
+import { detectInjection, extractAllStrings, getSuggestedAlternative } from "./gate-decision.js";
+import {
+  setBypassSecret,
+  registerBypassBlock as registerBypassBlock2,
+  approveBypass,
+  checkAndConsumeBypass as checkAndConsumeBypass2,
+  getPendingBypasses,
+  getPendingBypassDetail,
+  invalidateBypassToken,
+  persistBypasses,
+  loadBypasses
+} from "./bypass.js";
+import {
+  denyStaleHoldsOnStartup,
+  approveToolCall,
+  approveToolCallConstrained,
+  denyToolCall,
+  getPendingHolds
+} from "./hitl-hold.js";
+let _warnedNoAgentId = false;
+function _resolveAgentId() {
+  const { agentId } = resolveAgentIdentity();
+  if (agentId && agentId !== "agent") return agentId;
+  const fp = createHash("sha256").update(`${hostname()}:${process.ppid ?? 0}`).digest("hex").slice(0, 8);
+  if (!_warnedNoAgentId) {
+    logger.info({ fingerprint: `env_${fp}` }, "tool-guard: no agent identity configured \u2014 using process fingerprint for reputation tracking");
+    _warnedNoAgentId = true;
+  }
+  return `env_${fp}`;
+}
+async function _checkScriptTrustForRaw(raw) {
+  const parsed = parseShellCommand(raw);
+  if (!parsed) {
+    const heuristic = detectScriptInvocationFromRawText(raw);
+    if (!heuristic) return { escalate: false };
+    const trust = await evaluateScriptTrust(heuristic.scriptPath, process.cwd());
+    if (!trust.trusted) {
+      return {
+        escalate: true,
+        reason: `Script invocation \`${heuristic.interpreter} ${heuristic.scriptPath}\` (matched via raw-text fallback \u2014 command could not be fully structurally parsed) is not trusted: ${trust.reasons.join("; ")}`
+      };
+    }
+    return { escalate: false };
+  }
+  for (const cmd of parsed) {
+    const invocation = detectScriptInvocation(cmd);
+    if (!invocation) continue;
+    const trust = await evaluateScriptTrust(invocation.scriptPath, process.cwd());
+    if (!trust.trusted) {
+      return {
+        escalate: true,
+        reason: `Script invocation \`${invocation.interpreter} ${invocation.scriptPath}\` is not trusted: ${trust.reasons.join("; ")}`
+      };
+    }
+  }
+  return { escalate: false };
+}
+async function _checkScriptTrustEscalation(argStrings, toolName) {
+  const candidates = argStrings.filter((s) => s && s.length > 0);
+  const toScan = candidates.length > 0 ? candidates : [toolName];
+  for (const raw of toScan) {
+    const res = await _checkScriptTrustForRaw(raw);
+    if (res.escalate) return res;
+  }
+  return { escalate: false };
+}
+async function applyGate(toolName, args, next, port, opts) {
+  try {
+    return await applyGateInner(toolName, args, next, port, opts);
+  } catch (err) {
+    logger.error({ err, toolName }, "tool-guard: applyGate threw an unexpected error \u2014 failing closed");
+    await getStores().blunders.record({
+      blunderType: "pipeline_block",
+      command: toolName,
+      blockReason: `Gate threw an unexpected error and failed closed: ${err instanceof Error ? err.message : String(err)}`,
+      service: "mcp",
+      tag: "gate_internal_error",
+      actor: "agent",
+      pid: null,
+      confidenceScore: null
+    });
+    return {
+      content: [{
+        type: "text",
+        text: [
+          `\u{1F6AB} **Mergen fail-closed: the local execution gate hit an internal error while evaluating this call.**`,
+          ``,
+          `**Tool:** \`${toolName}\``,
+          ``,
+          `_The tool call was not executed. This event has been logged to the Agent Blunder Log._`
+        ].join("\n")
+      }],
+      isError: true
+    };
+  }
+}
+async function applyGateInner(toolName, args, next, port, opts) {
+  const t0 = Date.now();
+  const heartbeat = assertGateHeartbeatFresh();
+  if (!heartbeat.ok) {
+    recordGateBlock(["gate_heartbeat_stale"]);
+    await getStores().blunders.record({
+      blunderType: "pipeline_block",
+      command: toolName,
+      blockReason: `Gate heartbeat fail-closed: ${heartbeat.reason}`,
+      service: "mcp",
+      tag: "gate_heartbeat",
+      actor: "agent",
+      pid: null,
+      confidenceScore: null,
+      triggeredRules: ["gate_heartbeat_stale"]
+    });
+    logger.error({ toolName, reason: heartbeat.reason }, "tool-guard: gate heartbeat stale \u2014 failing closed");
+    return {
+      content: [{
+        type: "text",
+        text: [
+          `\u{1F6AB} **Mergen fail-closed: local execution gate heartbeat is not fresh.**`,
+          ``,
+          `**Tool:** \`${toolName}\``,
+          `**Why:** ${heartbeat.reason}`,
+          ``,
+          `_Restart Mergen or restore the gate heartbeat before executing agent actions._`
+        ].join("\n")
+      }],
+      isError: true
+    };
+  }
+  const argsSnapshot = JSON.stringify(args ?? {});
+  const argsObj = args && typeof args === "object" ? args : {};
+  const commandArg = argsObj.command ?? argsObj.cmd ?? argsObj.fix ?? "";
+  const allArgStrings = extractAllStrings(args);
+  const agentId = _resolveAgentId();
+  const sessionId = agentId;
+  const identity = opts?.verifiedAgentId ? void 0 : resolveAgentIdentity();
+  const verifiedAgentId = opts?.verifiedAgentId ?? (identity?.verified ? identity.agentId : void 0);
+  const agentIdLabel = opts?.verifiedAgentId ?? identity?.agentId ?? void 0;
+  const parentAgentId = opts?.verifiedAgentId ? opts?.verifiedParentAgentId : identity?.parentAgentId;
+  const traceId = getTraceId();
+  const { threat: sequenceThreat, label: sequenceLabel } = detectSequenceThreat(sessionId, commandArg || argsSnapshot.slice(0, 200));
+  if (sequenceThreat) {
+    updateAgentReputation(agentId, "sequence");
+    recordGateBlock(["sequence_threat"]);
+    await getStores().blunders.record({
+      blunderType: "pipeline_block",
+      command: toolName,
+      blockReason: `Multi-turn threat sequence detected: ${sequenceLabel}`,
+      service: "mcp",
+      tag: "sequence_threat",
+      actor: agentId,
+      pid: null,
+      confidenceScore: null,
+      triggeredRules: ["sequence_threat"]
+    });
+    recordSessionCall(sessionId, toolName, commandArg, "BLOCK");
+    recordActivity({ toolName, commandArg, verdict: "BLOCK", triggeredRules: ["sequence_threat"], ruleNames: ["Multi-Turn Threat Sequence"] });
+    recordGateEvent({
+      ts: Date.now(),
+      toolName,
+      command: commandArg || null,
+      actor: "agent",
+      agentId: agentIdLabel ?? null,
+      service: "mcp",
+      environment: process.env.MERGEN_ENVIRONMENT ?? null,
+      verdict: "block",
+      triggeredRules: ["sequence_threat"],
+      guidedAlternative: null,
+      reason: `Multi-turn threat sequence detected: ${sequenceLabel}`,
+      traceId
+    });
+    return {
+      content: [{
+        type: "text",
+        text: [
+          `\u{1F6AB} **Mergen blocked this tool call: multi-turn threat sequence detected.**`,
+          ``,
+          `**Tool:** \`${toolName}\``,
+          `**Pattern:** \`${sequenceLabel}\``,
+          `**Why:** The sequence of recent tool calls matches a known multi-step attack chain.`,
+          ``,
+          `_This event has been logged to the Agent Blunder Log._`
+        ].join("\n")
+      }],
+      isError: true
+    };
+  }
+  const injectionMatch = detectInjection(argsSnapshot);
+  if (injectionMatch) {
+    updateAgentReputation(agentId, "injection");
+    markContaminated(sessionId, injectionMatch, 5);
+    recordGateBlock(["injection_attempt"]);
+    await getStores().blunders.record({
+      blunderType: "injection_attempt",
+      command: toolName,
+      blockReason: `Prompt injection pattern detected in tool arguments: ${injectionMatch}`,
+      service: "mcp",
+      tag: "injection",
+      actor: agentId,
+      pid: null,
+      confidenceScore: null,
+      triggeredRules: ["injection_attempt"]
+    });
+    logger.warn({ toolName, injectionMatch }, "tool-guard: prompt injection attempt detected in args");
+    recordSessionCall(sessionId, toolName, commandArg, "BLOCK");
+    recordActivity({ toolName, commandArg, verdict: "BLOCK", triggeredRules: ["injection_attempt"], ruleNames: ["Prompt Injection"] });
+    recordGateEvent({
+      ts: Date.now(),
+      toolName,
+      command: commandArg || null,
+      actor: "agent",
+      agentId: agentIdLabel ?? null,
+      service: "mcp",
+      environment: process.env.MERGEN_ENVIRONMENT ?? null,
+      verdict: "block",
+      triggeredRules: ["injection_attempt"],
+      guidedAlternative: null,
+      reason: `Prompt injection pattern detected in tool arguments: ${injectionMatch}`,
+      traceId
+    });
+    return {
+      content: [{
+        type: "text",
+        text: `\u{1F6AB} **Mergen blocked this tool call: prompt injection pattern detected.**
+
+**Tool:** \`${toolName}\`
+
+_This event has been logged to the Agent Blunder Log._`
+      }],
+      isError: true
+    };
+  }
+  if (checkAndConsumeBypass(toolName, commandArg)) {
+    const hardEval = evaluateEnterprisePolicy({
+      files: [toolName],
+      commands: [toolName, ...allArgStrings],
+      actor: "agent",
+      service: "mcp",
+      timestamp: Date.now(),
+      environment: process.env.MERGEN_ENVIRONMENT ?? void 0,
+      repo: process.env.MERGEN_REPO ?? void 0,
+      agentId: verifiedAgentId
+    });
+    if (hardEval.verdict === "block") {
+      const hardReason = hardEval.reasons.join("; ");
+      recordGateBlock(hardEval.triggeredRules);
+      await getStores().blunders.record({
+        blunderType: "pipeline_block",
+        command: toolName,
+        blockReason: `Hard policy block \u2014 bypass cannot override: ${hardReason}`,
+        service: "mcp",
+        tag: "tool_guard",
+        actor: "agent",
+        pid: null,
+        confidenceScore: null,
+        triggeredRules: hardEval.triggeredRules
+      });
+      logger.warn({ toolName, reason: hardReason }, "tool-guard: hard block rule rejected bypass approval");
+      recordGateEvent({
+        ts: Date.now(),
+        toolName,
+        command: commandArg || null,
+        actor: "agent",
+        agentId: agentIdLabel ?? null,
+        service: "mcp",
+        environment: process.env.MERGEN_ENVIRONMENT ?? null,
+        verdict: "block",
+        triggeredRules: hardEval.triggeredRules,
+        guidedAlternative: null,
+        reason: `Hard policy block \u2014 bypass cannot override: ${hardReason}`,
+        traceId
+      });
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `\u{1F6AB} **Hard policy block \u2014 this action cannot be bypassed by operator approval.**`,
+            ``,
+            `**Tool:** \`${toolName}\``,
+            `**Why:** ${hardReason}`,
+            ``,
+            `_Hard blocks are immutable safety guardrails. Modify \`~/.mergen/enterprise-policy.json\` to change the rule itself._`
+          ].join("\n")
+        }],
+        isError: true
+      };
+    }
+    logger.info({ toolName, commandArg }, "tool-guard: approved bypass consumed, tool call passing");
+    recordGatePass();
+    trackSuccessfulCall(toolName);
+    recordGateEvent({
+      ts: Date.now(),
+      toolName,
+      command: commandArg || null,
+      actor: "agent",
+      agentId: agentIdLabel ?? null,
+      service: "mcp",
+      environment: process.env.MERGEN_ENVIRONMENT ?? null,
+      verdict: "pass",
+      triggeredRules: [],
+      guidedAlternative: null,
+      reason: "operator bypass approved",
+      traceId
+    });
+    return next();
+  }
+  const profileBlock = checkAgentProfile(toolName, void 0, verifiedAgentId);
+  if (profileBlock) {
+    recordGateBlock([]);
+    await getStores().blunders.record({
+      blunderType: "rbac_block",
+      command: toolName,
+      blockReason: profileBlock,
+      service: "mcp",
+      tag: "agent_profile",
+      actor: agentIdLabel ?? "agent",
+      pid: null,
+      confidenceScore: null,
+      triggeredRules: ["agent_profile"]
+    });
+    recordActivity({ toolName, commandArg, verdict: "BLOCK", triggeredRules: ["agent_profile"], ruleNames: ["Agent Profile Block"] });
+    recordGateEvent({
+      ts: Date.now(),
+      toolName,
+      command: commandArg || null,
+      actor: "agent",
+      agentId: agentIdLabel ?? null,
+      service: "mcp",
+      environment: process.env.MERGEN_ENVIRONMENT ?? null,
+      verdict: "block",
+      triggeredRules: ["agent_profile"],
+      guidedAlternative: null,
+      reason: profileBlock,
+      traceId
+    });
+    return {
+      content: [{
+        type: "text",
+        text: `\u{1F6AB} **Mergen agent profile gate blocked this tool call.**
+
+**Tool:** \`${toolName}\`
+**Why:** ${profileBlock}
+
+_Adjust permissions at: mergen-server agent-update ${verifiedAgentId ?? ""}_`
+      }],
+      isError: true
+    };
+  }
+  const evaluation = evaluateEnterprisePolicy({
+    files: [toolName],
+    commands: [toolName, ...allArgStrings],
+    actor: "agent",
+    service: "mcp",
+    timestamp: Date.now(),
+    environment: process.env.MERGEN_ENVIRONMENT ?? void 0,
+    repo: process.env.MERGEN_REPO ?? void 0,
+    agentId: verifiedAgentId
+  });
+  const evalMs = Date.now() - t0;
+  if (evalMs > 10) {
+    logger.warn({ evalMs, toolName }, "tool-guard: policy evaluation exceeded 10ms target");
+  }
+  recordGateCoverage(toolName, evaluation.triggeredRules);
+  if (evaluation.verdict === "pass") {
+    const blastCandidates = (allArgStrings.length > 0 ? allArgStrings : [commandArg || toolName]).map((s) => computeBlastRadius(s));
+    const blast = mostSevereBlast(blastCandidates);
+    if (!blast.reversible && blast.dataAtRisk && blast.scope === "data-destructive") {
+      evaluation.verdict = "warn";
+      evaluation.triggeredRules.push("blast_radius_gate");
+      evaluation.reasons.push(`Auto-hold: irreversible data operation detected (scope: ${blast.scope})`);
+      logger.info({ toolName, scope: blast.scope }, "tool-guard: blast radius gate upgraded pass \u2192 hold");
+    } else {
+      const contaminated = isSessionContaminated(sessionId);
+      if (contaminated) {
+        const source = getContaminationSource(sessionId);
+        evaluation.verdict = "warn";
+        evaluation.triggeredRules.push("contamination_hold");
+        evaluation.reasons.push(`Session contaminated by prior injection attempt (pattern: ${source}). Human review required.`);
+        logger.info({ sessionId, toolName }, "tool-guard: contamination hold \u2014 upgrading PASS to HOLD");
+      } else {
+        const scriptTrust = await _checkScriptTrustEscalation(allArgStrings, toolName);
+        if (scriptTrust.escalate) {
+          evaluation.verdict = "warn";
+          evaluation.triggeredRules.push("script_trust_hold");
+          evaluation.reasons.push(scriptTrust.reason ?? "Untrusted script invocation requires human review.");
+          logger.info({ toolName, reason: scriptTrust.reason }, "tool-guard: script-trust check upgraded pass \u2192 hold");
+        } else {
+          const tier = getAgentScrutinyTier(agentId);
+          if (tier === "high" && !READ_ONLY_TOOLS.has(toolName)) {
+            evaluation.verdict = "warn";
+            evaluation.triggeredRules.push("high_scrutiny_hold");
+            evaluation.reasons.push(`Agent ${agentId} is under high scrutiny (repeated injection/sequence threats). Human review required.`);
+            logger.info({ agentId, toolName }, "tool-guard: high-scrutiny hold applied");
+          } else if (tier === "elevated" && !blast.reversible && blast.scope !== "unknown") {
+            evaluation.verdict = "warn";
+            evaluation.triggeredRules.push("elevated_scrutiny_hold");
+            evaluation.reasons.push(`Agent ${agentId} is under elevated scrutiny (repeated blocks). Non-reversible command requires human review.`);
+            logger.info({ agentId, toolName, scope: blast.scope }, "tool-guard: elevated-scrutiny hold applied");
+          } else {
+            const riskThreshold = getRiskHoldThreshold();
+            let riskEscalated = false;
+            if (riskThreshold !== null) {
+              const similarIncidentCount = findSimilarIncidents({ commandText: commandArg || toolName }).length;
+              const risk = computeRiskScore({
+                blastReversible: blast.reversible,
+                blastDataAtRisk: blast.dataAtRisk,
+                blastScope: blast.scope,
+                contaminated: false,
+                // already checked false to reach this branch
+                scrutinyTier: getAgentScrutinyTier(agentId),
+                similarIncidentCount
+              }, riskThreshold);
+              if (risk.escalateToHold) {
+                riskEscalated = true;
+                evaluation.verdict = "warn";
+                evaluation.triggeredRules.push("risk_score_hold");
+                evaluation.reasons.push(`Auto-hold: composite risk score ${risk.riskScore} met the configured threshold (${riskThreshold}). Human review required.`);
+                logger.info({ toolName, riskScore: risk.riskScore, threshold: riskThreshold }, "tool-guard: risk score upgraded pass \u2192 hold");
+              }
+            }
+            if (!riskEscalated) {
+              recordGatePass();
+              trackSuccessfulCall(toolName);
+              recordSessionCall(sessionId, toolName, commandArg, "PASS");
+              recordActivity({ toolName, commandArg, verdict: "PASS", triggeredRules: [], ruleNames: [] });
+              recordGateEvent({
+                ts: Date.now(),
+                toolName,
+                command: commandArg || null,
+                actor: "agent",
+                agentId: agentIdLabel ?? null,
+                service: "mcp",
+                environment: process.env.MERGEN_ENVIRONMENT ?? null,
+                verdict: "pass",
+                triggeredRules: [],
+                guidedAlternative: null,
+                traceId
+              });
+              return next();
+            }
+          }
+        }
+      }
+    }
+  }
+  const reason = evaluation.reasons.join("; ");
+  const alternative = getSuggestedAlternative(evaluation.triggeredRules, commandArg);
+  if (isPolicyDryRun()) {
+    const gateEventVerdict = evaluation.verdict === "block" ? "block" : "hold";
+    logger.info(
+      { toolName, verdict: evaluation.verdict, reason, triggeredRules: evaluation.triggeredRules },
+      `tool-guard: [DRY RUN] would have ${evaluation.verdict} \u2014 passing through`
+    );
+    await getStores().blunders.record({
+      blunderType: "pipeline_block",
+      command: toolName,
+      blockReason: `[DRY RUN] ${reason}`,
+      service: "mcp",
+      tag: "policy_dry_run",
+      actor: "agent",
+      pid: null,
+      confidenceScore: null,
+      triggeredRules: evaluation.triggeredRules,
+      agentId: agentIdLabel ?? null,
+      parentAgentId: parentAgentId ?? null,
+      traceId
+    });
+    recordGateEvent({
+      ts: Date.now(),
+      toolName,
+      command: commandArg || null,
+      actor: "agent",
+      agentId: agentIdLabel ?? null,
+      service: "mcp",
+      environment: process.env.MERGEN_ENVIRONMENT ?? null,
+      verdict: gateEventVerdict,
+      triggeredRules: evaluation.triggeredRules,
+      guidedAlternative: alternative,
+      reason: reason || null,
+      traceId
+    });
+    return next();
+  }
+  if (evaluation.verdict === "block") {
+    updateAgentReputation(agentId, "block");
+    recordGateBlock(evaluation.triggeredRules);
+    trackBlock(toolName, evaluation.triggeredRules);
+    await getStores().blunders.record({
+      blunderType: "pipeline_block",
+      command: toolName,
+      blockReason: reason,
+      service: "mcp",
+      tag: "tool_guard",
+      actor: "agent",
+      pid: null,
+      confidenceScore: null,
+      triggeredRules: evaluation.triggeredRules,
+      agentId: agentIdLabel ?? null,
+      parentAgentId: parentAgentId ?? null,
+      traceId
+    });
+    logger.warn({ toolName, reason }, "tool-guard: tool call blocked by local policy");
+    const ebpfCommandHint = (commandArg || toolName).trim().split(/\s+/)[0] || toolName;
+    void verifyNoExecve(ebpfCommandHint).then((verified) => {
+      if (verified === "verified-executed") {
+        logger.error({ toolName, commandHint: ebpfCommandHint, reason }, "ebpf-verify: BLOCKED command executed anyway \u2014 gate bypass or race condition, investigate immediately");
+      } else if (verified === "verified-not-executed") {
+        logger.info({ toolName, commandHint: ebpfCommandHint }, "ebpf-verify: confirmed the blocked execve never occurred");
+      }
+    }).catch(() => {
+    });
+    recordSessionCall(sessionId, toolName, commandArg, "BLOCK");
+    recordGateEvent({
+      ts: Date.now(),
+      toolName,
+      command: commandArg || null,
+      actor: "agent",
+      agentId: agentIdLabel ?? null,
+      service: "mcp",
+      environment: process.env.MERGEN_ENVIRONMENT ?? null,
+      verdict: "block",
+      triggeredRules: evaluation.triggeredRules,
+      guidedAlternative: alternative,
+      reason: reason || null,
+      traceId
+    });
+    const bypassToken = registerBypassBlock(toolName, commandArg, evaluation.triggeredRules);
+    logger.info(
+      { bypassToken, toolName, commandArg },
+      `tool-guard: bypass approval required \u2014 operator can run: mergen approve ${bypassToken}`
+    );
+    const ruleNames = loadEnterprisePolicy().rules.filter((r) => evaluation.triggeredRules.includes(r.id)).map((r) => r.name);
+    recordActivity({ toolName, commandArg, verdict: "BLOCK", triggeredRules: evaluation.triggeredRules, ruleNames });
+    return {
+      content: [{
+        type: "text",
+        text: [
+          `\u{1F6AB} **Mergen policy gate blocked this tool call.**`,
+          ``,
+          `**Tool:** \`${toolName}\``,
+          `**Why:** ${reason}`,
+          ``,
+          `**What to do instead:** ${alternative}`,
+          ``,
+          `_Action logged to the Agent Blunder Log. An operator must approve this action via the Mergen terminal or Slack. To modify this policy: \`~/.mergen/enterprise-policy.json\`._`
+        ].join("\n")
+      }],
+      isError: true
+    };
+  }
+  recordSessionCall(sessionId, toolName, commandArg, "HOLD");
+  const token = randomUUID();
+  const heldAt = Date.now();
+  logger.info({ toolName, token, reason }, "tool-guard: tool call held for HITL approval");
+  recordGateEvent({
+    ts: heldAt,
+    toolName,
+    command: commandArg || null,
+    actor: "agent",
+    agentId: agentIdLabel ?? null,
+    service: "mcp",
+    environment: process.env.MERGEN_ENVIRONMENT ?? null,
+    verdict: "hold",
+    triggeredRules: evaluation.triggeredRules,
+    guidedAlternative: alternative,
+    reason: reason || null,
+    traceId
+  });
+  recordHitlHold();
+  const holdRuleNames = loadEnterprisePolicy().rules.filter((r) => evaluation.triggeredRules.includes(r.id)).map((r) => r.name);
+  recordActivity({ toolName, commandArg, verdict: "HOLD", triggeredRules: evaluation.triggeredRules, ruleNames: holdRuleNames });
+  return holdToolCall({
+    token,
+    toolName,
+    argsSnapshot,
+    reason,
+    triggeredRules: evaluation.triggeredRules,
+    heldAt,
+    commandArg,
+    suggestedAlt: alternative,
+    port
+  });
+}
+let _gateInstalled = false;
+function isGateInstalled() {
+  return _gateInstalled;
+}
+function _resetGateInstalledForTesting() {
+  _gateInstalled = false;
+}
+const _installedGatedHandlers = /* @__PURE__ */ new WeakMap();
+function createGuardedServer(server, port) {
+  if (server._toolHandlersInitialized) {
+    throw new Error(
+      "createGuardedServer: a tool was already registered on this McpServer before the gate was installed \u2014 the tools/call dispatch handler is already active and unpatched. Call createGuardedServer(mcp, port) before any registerTool/tool/registerToolTask call, never after."
+    );
+  }
+  const lowLevel = server.server;
+  const originalSetRequestHandler = lowLevel.setRequestHandler.bind(lowLevel);
+  lowLevel.setRequestHandler = (schema, handler) => {
+    if (schema !== CallToolRequestSchema) {
+      return originalSetRequestHandler(schema, handler);
+    }
+    const gated = (request, extra) => {
+      const r = request;
+      const toolName = r?.params?.name ?? "unknown_tool";
+      const args = r?.params?.arguments;
+      return applyGate(toolName, args, () => Promise.resolve(handler(request, extra)), port);
+    };
+    _installedGatedHandlers.set(server, gated);
+    return originalSetRequestHandler(schema, gated);
+  };
+  _gateInstalled = true;
+  return server;
+}
+async function assertGateCoversRegisteredTools(server) {
+  if (!isGateInstalled()) {
+    throw new Error("assertGateCoversRegisteredTools: createGuardedServer was never called on this server.");
+  }
+  const registeredTools = server._registeredTools ?? {};
+  const toolNames = Object.keys(registeredTools);
+  if (toolNames.length === 0) {
+    throw new Error(
+      `assertGateCoversRegisteredTools: no tools are registered on this server \u2014 registerTools() appears to have registered nothing. Refusing to start with an empty, unverifiable tool set. If you are building this repository from source without the closed-source intelligence/tools.ts (the proprietary MCP tool registry \u2014 see intelligence/LICENSE), this is expected: registerTools() resolves to a no-op stub (__stubs__/closed-source.ts) and the server correctly refuses to boot with zero verifiable tools rather than silently running ungoverned. See this repo's CONTRIBUTING.md, "Running the server locally", for what an external contributor can do without the private layer.`
+    );
+  }
+  const installedHandler = _installedGatedHandlers.get(server);
+  if (!installedHandler) {
+    throw new Error(
+      "assertGateCoversRegisteredTools: no tools/call dispatch handler is installed \u2014 setToolRequestHandlers() may never have run despite tools being present in _registeredTools."
+    );
+  }
+  const syntheticRequest = {
+    params: { name: toolNames[0], arguments: { command: "terraform destroy prod-mergen-selftest" } }
+  };
+  let result;
+  try {
+    result = await installedHandler(syntheticRequest, { signal: new AbortController().signal });
+  } catch (err) {
+    throw new Error(
+      `assertGateCoversRegisteredTools: self-test call raised instead of being cleanly blocked by the gate: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const isBlocked = !!(result && typeof result === "object" && result.isError === true);
+  if (!isBlocked) {
+    throw new Error(
+      'assertGateCoversRegisteredTools: a synthetic "terraform destroy" call was NOT blocked by the live tools/call dispatch handler \u2014 the gate is not enforcing on this server. Refusing to start.'
+    );
+  }
+}
+export {
+  _resetGateInstalledForTesting,
+  applyGate,
+  approveBypass,
+  approveToolCall,
+  approveToolCallConstrained,
+  assertGateCoversRegisteredTools,
+  checkAndConsumeBypass2 as checkAndConsumeBypass,
+  createGuardedServer,
+  denyStaleHoldsOnStartup,
+  denyToolCall,
+  getPendingBypassDetail,
+  getPendingBypasses,
+  getPendingHolds,
+  invalidateBypassToken,
+  isGateInstalled,
+  loadBypasses,
+  persistBypasses,
+  registerBypassBlock2 as registerBypassBlock,
+  setBypassSecret
+};