@cirvix_ai/agent-control 0.1.3 → 0.2.0

package/src/core/guard.mjs

@@ -29,7 +29,9 @@ import { classify } from "./risk.mjs";
 import { classifyTool, extractCommand, publicToolName } from "./normalize.mjs";
 import { scan as scanSecrets } from "./secret-detect.mjs";
 import { applyDelegation } from "./delegation.mjs";
+import { assessAuthority, applyAuthority } from "./authority.mjs";
 import { applyEntitlements } from "./entitlement-gate.mjs";
+import { SessionTaint, assessTrifecta, applyTrifecta } from "./trifecta.mjs";
 
 /**
  * A refusal the agent can read and plan around.
@@ -176,6 +178,12 @@ export class Guard {
     runId = null,
     riskFloor = "high",
     delegation = null,
+    /* Mission-scoped authority. Absent by default, and absent means INERT —
+       not "deny everything". Authority is subtractive: it can take away what
+       policy allows and can never add to it, so a Guard built without a
+       mission behaves exactly as before. See core/authority.mjs. */
+    missions = null,
+    mission = null,
     /* Commercial enforcement. All three default to absent, so a Guard built
        without them behaves exactly as before — which is what keeps the SDK's
        library callers and the shared conformance fixture working unchanged.
@@ -192,6 +200,9 @@ export class Guard {
     this.secrets = secrets;
     /** DelegationBroker, when agent-to-agent delegation is in use. */
     this.delegation = delegation;
+    /** MissionRegistry, and/or a single mission this Guard always acts under. */
+    this.missions = missions;
+    this.mission = mission;
     this.licence = licence;
     this.meter = meter;
     this.agents = agents;
@@ -200,12 +211,20 @@ export class Guard {
     this.runId = runId;
     /** Risk level at or above which an unnamed call is escalated to approval. */
     this.riskFloor = riskFloor;
-    /** Set once this session reads secret-shaped material. */
-    this.touchedSecret = false;
+    /** Sequence taint tracking for Lethal Trifecta. */
+    this.taint = new SessionTaint();
     this.stats = { calls: 0, permitted: 0, denied: 0, held: 0, leaks: 0, latencyTotal: 0 };
     this.nextId = 1;
   }
 
+  get touchedSecret() {
+    return this.taint.touchedSecret;
+  }
+
+  set touchedSecret(value) {
+    this.taint.touchedSecret = value;
+  }
+
   /**
    * Decides one call, and brokers any secret handles it carries.
    *
@@ -215,7 +234,8 @@ export class Guard {
    *
    * @returns {Promise<{decision:object, record:object, args:any}>}
    */
-  async authorize({ tool, server = null, args = {}, delegation = null, agent = null }) {
+  async authorize({ tool, server = null, args, arguments: callArguments, delegation = null, agent = null }) {
+    args = args ?? callArguments ?? {};
     const action = actionForTool(server, tool);
     const resource = resourceForCall(args);
     // A caller may act as a specific agent per call — a gateway serving several
@@ -271,7 +291,7 @@ export class Guard {
       secrets: { detected: scanned.length },
     };
 
-    const decision = evaluate(
+    let decision = evaluate(
       { agent: caller, action, resource, context },
       this.rules,
       { cwd: this.cwd },
@@ -308,6 +328,88 @@ export class Guard {
       resource: decision.resource ?? resource,
     });
 
+    /*
+     * AUTHORITY RUNS HERE, ON THE SAME PATH AS EVERYTHING ELSE.
+     *
+     * Mission, capability, constraint and expiry are evaluated for every call,
+     * not only for the ones a caller remembers to check. Placing it beside
+     * delegation is deliberate: both answer "does this principal actually hold
+     * the authority it is exercising", both can only narrow, and both have to
+     * be on the ONE path that `guard.wrap()`, the MCP gateway and the socket
+     * all go through. The three bypasses documented above this line were all
+     * the same mistake — a check that lived on one surface and not the others —
+     * and an authority layer with that shape would be worse than none, because
+     * the console would show a boundary the runtime was not enforcing.
+     *
+     * `assessAuthority` is pure. It reads the mission and reports; it does not
+     * spend the budget. Usage is recorded below and only for a call that was
+     * actually permitted, so a refused call cannot exhaust the allowance it was
+     * refused under — otherwise every constraint doubles as a denial-of-service
+     * against the agent's real work.
+     */
+    const activeMission =
+      this.mission ?? (this.missions ? this.missions.forAgent(caller) : null);
+
+    const authorityAssessment = assessAuthority(
+      {
+        agent: caller,
+        action,
+        resource: decision.resource ?? resource,
+        tool,
+        server,
+        destination: destinationFor(decision.resource ?? resource, args),
+        environment: this.environment,
+        costUsd: args?.costUsd ?? 0,
+        delegating: Boolean(delegation),
+      },
+      activeMission,
+    );
+
+    const authorityContext = applyAuthority(decision, authorityAssessment);
+
+    /*
+     * An attempt is recorded whether or not authority is what refused it.
+     *
+     * A call policy already denied is still an agent reaching outside its
+     * boundary, and if only authority-attributed refusals were counted an
+     * agent could probe the boundary for free by choosing actions policy
+     * denies anyway. The benchmark scores attempts, not attributions.
+     */
+    if (this.missions && authorityAssessment.applicable && !authorityAssessment.authorized) {
+      this.missions.recordEscape({
+        missionId: activeMission?.id ?? null,
+        agent: caller,
+        kind: authorityAssessment.escape?.kind ?? null,
+        stage: authorityAssessment.stage,
+        code: authorityAssessment.code,
+        action,
+        resource: decision.resource ?? resource,
+        tool,
+        reason: authorityAssessment.reason,
+        blocked: decision.verdict === "deny" || decision.verdict === "hold",
+      });
+    }
+
+    /*
+     * Sequence-aware enforcement (Lethal Trifecta) in Guard.
+     * Prevents untrusted content + sensitive data read + outbound egress.
+     */
+    const trifectaCall = {
+      action,
+      resource: decision.resource ?? resource,
+      tool,
+      server,
+      destination: destinationFor(decision.resource ?? resource, args),
+      environment: this.environment,
+      egress: this.isExternal(decision.resource ?? resource) ? "external" : "none",
+      timestamp: new Date().toISOString(),
+      sql: typeof args?.sql === "string" ? args.sql : typeof args?.query === "string" ? args.query : null,
+      secretsDetected: scanned.length,
+    };
+    const trifecta = assessTrifecta(trifectaCall, this.taint);
+    decision = applyTrifecta(decision, trifecta);
+    decision.trifecta = { complete: trifecta.complete, satisfied: trifecta.satisfied, imminent: trifecta.imminent };
+
     /*
      * THE COMMERCIAL GATE RUNS HERE TOO, NOT ONLY IN THE PIPELINE.
      *
@@ -391,7 +493,12 @@ export class Guard {
       // Who authorized this must be answerable after the fact, on every surface
       // — not only the one that happened to record it.
       ...(delegationContext ? { delegation: delegationContext } : {}),
+      // Authority is part of the record for the same reason delegation is:
+      // "who authorized this" must be answerable after the fact.
+      ...(authorityContext ? { authority: authorityContext } : {}),
+      ...(decision.escape ? { escape: decision.escape } : {}),
       ...(brokered.length ? { secrets: brokered, secrets_brokered: brokered } : {}),
+      ...(decision.trifecta ? { trifecta: decision.trifecta } : {}),
       // Findings never carry the value — see secret-detect.mjs.
       ...(scanned.length
         ? {
@@ -413,6 +520,13 @@ export class Guard {
     else if (decision.verdict === "hold") this.stats.held++;
     else {
       this.stats.permitted++;
+      // Budget and rate are consumed by calls that HAPPEN. See the note above
+      // `assessAuthority`: charging a refused call would let a blocked agent
+      // exhaust its own mission.
+      if (this.missions && activeMission) {
+        this.missions.record(activeMission.id, { costUsd: args?.costUsd ?? 0 });
+      }
+      this.taint.observeCall(trifectaCall, true);
       // Any successful read of secret-shaped material taints the session. A
       // brokered substitution deliberately does not: the agent never held the
       // material, which is the entire point of a handle.

package/src/core/intent.mjs

@@ -0,0 +1,166 @@
+/**
+ * Intent-Aware Agent Firewall.
+ *
+ * Implements: CAPABILITY + AUTHORITY + INTENT + CONTEXT = AUTHORIZED ACTION
+ *
+ * Rather than evaluating tools in isolation (`tool == allowed`), an agent's
+ * declared mission/purpose governs what it may reach for.
+ *
+ * Example:
+ *   Mission: "Fix checkout test failures"
+ *   Allowed: read source, run tests, modify checkout files
+ *   Suspicious: read production credentials, drop database, upload code to external IP
+ */
+
+import { RISK } from "./risk.mjs";
+
+/** Semantic categories of intent. */
+export const INTENT_CATEGORIES = {
+  TESTING: "testing",
+  DEVELOPMENT: "development",
+  MAINTENANCE: "maintenance",
+  REPORTING: "reporting",
+  DATABASE_ADMIN: "database_admin",
+  DEPLOYMENT: "deployment",
+  GENERAL: "general",
+};
+
+/** High-risk actions that require explicit intent alignment. */
+const RESTRICTED_ACTIONS = {
+  "secret:read": ["credential_management", "auth_setup"],
+  "db:drop": ["database_admin", "migration_rollback"],
+  "db:write": ["database_admin", "data_migration", "development"],
+  "shell:destructive": ["system_admin"],
+  "net:external_egress": ["data_sync", "api_integration", "deployment"],
+  "iam:modify": ["cloud_admin", "iam_setup"],
+};
+
+/**
+ * Classifies a declared intent string into dominant categories and allowed scopes.
+ */
+export function classifyIntent(intentText) {
+  if (!intentText || typeof intentText !== "string") {
+    return {
+      category: INTENT_CATEGORIES.GENERAL,
+      keywords: [],
+      sensitivityFloor: RISK.LOW,
+      allowedActions: ["*"],
+    };
+  }
+
+  const text = intentText.toLowerCase();
+  const keywords = text.match(/\b\w{3,}\b/g) ?? [];
+
+  if (/\b(test|spec|assert|coverage|jest|mocha|pytest|unit)\b/.test(text)) {
+    return {
+      category: INTENT_CATEGORIES.TESTING,
+      keywords,
+      sensitivityFloor: RISK.LOW,
+      disallowedActions: ["secret:read", "db:drop", "net:external_egress", "iam:modify"],
+      allowedActions: ["fs:read", "fs:write", "exec:test", "exec:dev"],
+    };
+  }
+
+  if (/\b(fix|bug|refactor|feature|implement|code|frontend|backend)\b/.test(text)) {
+    return {
+      category: INTENT_CATEGORIES.DEVELOPMENT,
+      keywords,
+      sensitivityFloor: RISK.LOW,
+      disallowedActions: ["secret:read", "db:drop", "iam:modify"],
+      allowedActions: ["fs:read", "fs:write", "exec:dev", "net:fetch"],
+    };
+  }
+
+  if (/\b(deploy|release|ship|staging|production|publish)\b/.test(text)) {
+    return {
+      category: INTENT_CATEGORIES.DEPLOYMENT,
+      keywords,
+      sensitivityFloor: RISK.HIGH,
+      disallowedActions: ["db:drop"],
+      allowedActions: ["fs:read", "net:external_egress", "exec:deploy"],
+    };
+  }
+
+  if (/\b(migrate|schema|table|sql|database|query|seed)\b/.test(text)) {
+    return {
+      category: INTENT_CATEGORIES.DATABASE_ADMIN,
+      keywords,
+      sensitivityFloor: RISK.HIGH,
+      disallowedActions: ["iam:modify"],
+      allowedActions: ["db:read", "db:write", "fs:read"],
+    };
+  }
+
+  return {
+    category: INTENT_CATEGORIES.GENERAL,
+    keywords,
+    sensitivityFloor: RISK.LOW,
+    disallowedActions: ["db:drop", "iam:modify"],
+    allowedActions: ["*"],
+  };
+}
+
+/**
+ * Evaluates whether a requested action aligns with the agent's declared intent.
+ *
+ * @param {Object} params
+ * @param {string} params.intent - Declared mission or task description
+ * @param {string} params.action - Canonical action identifier (e.g. "fs:read", "secret:read")
+ * @param {string} params.resource - Resource target (e.g. "/etc/passwd", "src/auth.ts")
+ * @param {string} params.tool - Tool name invoked
+ * @param {Object} params.context - Execution context
+ * @returns {{ aligned: boolean, intentScore: number, reason: string, category: string }}
+ */
+export function evaluateIntent({ intent, action, resource = "", tool = "", context = {} }) {
+  const classification = classifyIntent(intent);
+
+  // If action is explicitly restricted, verify if intent permits it
+  const restrictedFor = RESTRICTED_ACTIONS[action];
+  if (restrictedFor && !restrictedFor.includes(classification.category)) {
+    return {
+      aligned: false,
+      intentScore: 0.1,
+      reason: `Action '${action}' is restricted and outside declared mission '${intent}' (${classification.category})`,
+      category: classification.category,
+    };
+  }
+
+  // Check disallowed actions for this intent category
+  if (classification.disallowedActions?.includes(action)) {
+    return {
+      aligned: false,
+      intentScore: 0.2,
+      reason: `Action '${action}' conflicts with declared mission scope (${classification.category})`,
+      category: classification.category,
+    };
+  }
+
+  // Resource sensitivity check against intent
+  const isCredentialTarget = /(credential|\.env|id_rsa|secret|token|api[_-]?key|password)/i.test(resource);
+  if (isCredentialTarget && classification.category === INTENT_CATEGORIES.TESTING) {
+    return {
+      aligned: false,
+      intentScore: 0.15,
+      reason: `Agent attempted to access credentials ('${resource}') while declared mission is testing only`,
+      category: classification.category,
+    };
+  }
+
+  // Production database deletion check
+  const isDropTarget = /(drop\s+table|delete\s+from|truncate|rm\s+-rf\s+\/)/i.test(resource);
+  if (isDropTarget && classification.category !== INTENT_CATEGORIES.DATABASE_ADMIN) {
+    return {
+      aligned: false,
+      intentScore: 0.05,
+      reason: `Destructive action against '${resource}' requires explicit administrative mission`,
+      category: classification.category,
+    };
+  }
+
+  return {
+    aligned: true,
+    intentScore: 0.95,
+    reason: `Action '${action}' against '${resource || tool}' aligns with mission '${classification.category}'`,
+    category: classification.category,
+  };
+}

package/src/core/journal.mjs

@@ -198,23 +198,55 @@ function clock(ts) {
   return m ? m[1] : s.slice(0, 8).padEnd(8);
 }
 
-/** One record, one line. The shape `cirvix logs` prints. */
+/** One record, compact or expanded per risk/decision (spec: ALLOW compact, DENY expanded). */
 export function renderLine(record) {
   if (record.malformed) {
     return `  ${dim(String(record.line).padStart(4))}  ${red("malformed record")} ${dim(record.raw.slice(0, 60))}`;
   }
   const decision = record.decision ?? toDecision(record.verdict);
   const tone = toneFor(record);
-  const risk = RISK_TONE[record.risk] ?? dim;
+  const riskTone = RISK_TONE[record.risk] ?? dim;
+  const isCritical = String(record.risk ?? "").toLowerCase() === "critical" || String(record.risk ?? "").toLowerCase() === "high";
+  const isDenied = decision === DECISION.DENY;
+  const isHeld = decision === DECISION.REQUIRE_APPROVAL;
+  const clockStr = dim(clock(record.ts ?? record.timestamp));
+  const icon = decision === DECISION.ALLOW ? "✓" : decision === DECISION.SANITIZE ? "◈" : isDenied ? "✕" : isHeld ? "⏸" : "·";
+  const label = String(decision).toUpperCase().replace(/_/g, " ");
+  const tool = String(record.tool ?? record.action ?? "—");
+  const resource = truncate(record.resource ?? record.command ?? "", 44);
+  const policy = String(record.policy ?? record.rule ?? "default-deny");
+  const latency = `${record.latency_ms ?? "—"}ms`;
+
+  // Expanded for DENY/CRITICAL/HOLD/HIGH — high visibility, spec layout:
+  // 22:38:53  ◇ SANITIZE  HIGH      network.request
+  //            https://docs.example.com/deploy
+  //            Policy: sanitize-fetched-content       16.82ms
+  if (isDenied || isHeld || isCritical) {
+    const iconLabel = isHeld ? "APPROVAL" : label; // REQUIRE_APPROVAL displays as APPROVAL per spec
+    const iconChar = isHeld ? "●" : icon;
+    const lines = [];
+    // First line: time + icon/verdict + risk + tool — columns aligned, decision strongest
+    lines.push(
+      `  ${clockStr}  ${tone(`${iconChar} ${iconLabel.padEnd(12)}`)} ${riskTone(String(record.risk ?? "—").toUpperCase().padEnd(9))} ${tool.padEnd(20)} ${dim(latency)}`,
+    );
+    if (resource) lines.push(`           ${dim(resource)}`);
+    // Policy line — indented, secondary
+    lines.push(`           ${dim(`Policy: ${policy}`)}`);
+    if (isHeld) {
+      lines.push(`           ${amber("→ AWAITING APPROVAL")}`);
+    }
+    return lines.join("\n");
+  }
 
+  // Compact for ordinary ALLOW.
   return [
-    `  ${dim(clock(record.ts ?? record.timestamp))}`,
-    tone(String(decision).toUpperCase().padEnd(16)),
-    risk(String(record.risk ?? "—").toUpperCase().padEnd(8)),
-    String(record.tool ?? record.action ?? "—").padEnd(20),
-    dim(truncate(record.resource ?? record.command ?? "", 44).padEnd(44)),
-    dim(String(record.policy ?? record.rule ?? "default-deny").padEnd(24)),
-    dim(`${record.latency_ms ?? "—"}ms`),
+    `  ${clockStr}`,
+    tone(`${icon} ${label.padEnd(12)}`),
+    riskTone(String(record.risk ?? "—").toUpperCase().padEnd(8)),
+    tool.padEnd(20),
+    dim(resource.padEnd(44)),
+    dim(latency.padEnd(8)),
+    dim(policy),
   ].join(" ");
 }
 
@@ -237,44 +269,103 @@ export function renderLine(record) {
 export function renderTree(record, { indent = "  " } = {}) {
   const decision = record.decision ?? toDecision(record.verdict);
   const tone = toneFor(record);
-  const risk = RISK_TONE[record.risk] ?? dim;
-
-  const rows = [
-    ["input", truncate(record.resource || record.command || "(no resource)", 70)],
-    ["risk", risk(String(record.risk ?? "unknown").toUpperCase()) + (record.risk_signals?.length ? dim(`  ${record.risk_signals.join(", ")}`) : "")],
-    ["policy", record.policy ?? record.rule ?? dim("— no rule matched (default deny)")],
-    ["decision", tone(String(decision).toUpperCase()) + (record.enforced === false ? dim("  (not enforced — audit mode)") : "")],
-    ["latency", `${record.latency_ms ?? "—"}ms`],
-  ];
-
-  if (record.would_have) {
-    rows.push(["would have", red(String(record.would_have.decision).toUpperCase()) + dim(` by ${record.would_have.rule ?? "default-deny"}`)]);
+  const riskTone = RISK_TONE[record.risk] ?? dim;
+  const isDeny = decision === DECISION.DENY;
+  const isHold = decision === DECISION.REQUIRE_APPROVAL;
+  const isSanitize = decision === DECISION.SANITIZE;
+
+  // Header — spec: CIRVIX DECISION ANALYSIS
+  const lines = [];
+  lines.push(`${indent}${bold("CIRVIX DECISION ANALYSIS")}`);
+  lines.push("");
+
+  // Top: Decision + Risk — strongest visual
+  const decisionLabel = isDeny ? "✕ BLOCKED" : isHold ? "● AWAITING APPROVAL" : isSanitize ? "◇ SANITIZED" : "✓ " + String(decision).toUpperCase();
+  const decisionTone = isDeny ? red : isHold ? amber : isSanitize ? blue : green;
+  lines.push(`${indent}${dim("Decision".padEnd(12))} ${decisionTone(bold(decisionLabel))}${record.enforced === false ? dim("  (not enforced — audit mode)") : ""}`);
+  lines.push(`${indent}${dim("Risk".padEnd(12))} ${riskTone(bold(String(record.risk ?? "unknown").toUpperCase()))}${record.risk_signals?.length ? dim(`  ${record.risk_signals.join(", ")}`) : ""}`);
+  lines.push("");
+
+  // Tool / Target / Policy / Latency / Request
+  lines.push(`${indent}${dim("Tool".padEnd(12))} ${bold(String(record.tool ?? record.action ?? "—"))}`);
+  if (record.resource || record.command) {
+    lines.push(`${indent}${dim("Target".padEnd(12))} ${truncate(record.resource || record.command || "", 70)}`);
   }
-  if (record.approval_id) rows.push(["approval", blue(record.approval_id)]);
-  if (record.secrets_brokered?.length) rows.push(["secrets", `${record.secrets_brokered.join(", ")} ${dim("(brokered — the agent never held the value)")}`]);
-  if (record.secrets_detected?.length) {
-    rows.push(["detected", record.secrets_detected.map((s) => `${s.detector} ${dim(s.masked)}`).join(", ")]);
+  if (record.destination) {
+    lines.push(`${indent}${dim("Destination".padEnd(12))} ${record.destination}`);
   }
-  if (record.sanitized?.arguments?.length) {
-    rows.push(["sanitized", `${record.sanitized.arguments.length} value(s) stripped from arguments`]);
+  lines.push(`${indent}${dim("Policy".padEnd(12))} ${record.policy ?? record.rule ?? dim("— no rule matched (default deny)")}`);
+  lines.push(`${indent}${dim("Latency".padEnd(12))} ${record.latency_ms ?? "—"}ms`);
+  lines.push(`${indent}${dim("Request".padEnd(12))} ${dim(record.request_id ?? record.decision_id ?? "—")}  ${dim(`agent ${record.agent ?? "—"}`)}`);
+  if (record.approval_id) {
+    lines.push(`${indent}${dim("Approval".padEnd(12))} ${blue(record.approval_id)}`);
   }
-  if (record.observed_by?.length) rows.push(["observed", dim(record.observed_by.join(", "))]);
-  rows.push(["result", decision === DECISION.DENY ? red("not forwarded") : decision === DECISION.REQUIRE_APPROVAL ? amber("held") : green("forwarded")]);
-
-  const width = Math.max(...rows.map(([k]) => k.length));
-  const lines = [
-    `${indent}${bold(record.agent ?? "agent")}  ${dim(record.request_id ?? "")}`,
-    `${indent} └── ${bold(record.tool ?? record.action ?? "tool")}`,
-  ];
-  rows.forEach(([key, value], i) => {
-    const branch = i === rows.length - 1 ? "└──" : "├──";
-    lines.push(`${indent}      ${branch} ${dim(key.padEnd(width))}  ${value}`);
-  });
+  lines.push("");
 
+  // Matched policy + Reason — if present
+  if (record.policy ?? record.rule) {
+    lines.push(`${indent}${dim("Matched policy")}`);
+    lines.push(`${indent}  ${record.policy ?? record.rule}`);
+    lines.push("");
+  }
   if (record.reason) {
+    lines.push(`${indent}${dim("Reason")}`);
+    lines.push(`${indent}  ${wrap(record.reason, 70, `${indent}  `)}`);
+    lines.push("");
+  }
+
+  // Approval panel — for REQUIRE_APPROVAL, spec: HUMAN APPROVAL REQUIRED
+  if (isHold) {
+    const W = 48;
+    const top = `${indent}${dim(`╭─ HUMAN APPROVAL REQUIRED ${"─".repeat(Math.max(0, W - 26))}╮`)}`;
+    const bottom = `${indent}${dim(`╰${"─".repeat(W)}╯`)}`;
+    lines.push(top);
+    lines.push(`${indent}${dim("│")} ${dim("Agent".padEnd(10))} ${record.agent ?? "—"}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Action".padEnd(10))} ${record.action ?? record.tool ?? "—"}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Target".padEnd(10))} ${truncate(record.resource ?? "", 30)}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${"".padEnd(42)} ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Risk".padEnd(10))} ${amber(String(record.risk ?? "").toUpperCase())}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Policy".padEnd(10))} ${record.policy ?? record.rule ?? "—"}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${"".padEnd(42)} ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${dim("Reason")}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${wrap(record.reason ?? "Production database mutation requires human authorization.", 42, `${indent}${dim("│")} `)}  ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${"".padEnd(42)} ${dim("│")}`);
+    lines.push(`${indent}${dim("│")} ${blue("[A] Approve")}  ${dim("  ")} ${red("[R] Reject")}  ${dim("│")}`);
+    lines.push(bottom);
     lines.push("");
-    lines.push(`${indent}      ${dim(wrap(record.reason, 84, `${indent}      `))}`);
   }
+
+  // Decision path — spec: secret detection → risk classification → policy evaluation → BLOCK
+  lines.push(`${indent}${dim("Decision path")}`);
+  lines.push(`${indent}  ${dim("secret detection")}`);
+  lines.push(`${indent}    ${dim("↓")}`);
+  lines.push(`${indent}  ${dim("risk classification")}`);
+  lines.push(`${indent}    ${dim("↓")}`);
+  lines.push(`${indent}  ${dim("policy evaluation")}`);
+  lines.push(`${indent}    ${dim("↓")}`);
+  lines.push(`${indent}  ${decisionTone(isDeny ? "BLOCK" : isHold ? "HOLD" : isSanitize ? "SANITIZE" : "ALLOW")}`);
+
+  // Low-level details — keep for debugging, muted
+  const extra = [];
+  if (record.secrets_brokered?.length) extra.push(`secrets brokered: ${record.secrets_brokered.join(", ")}`);
+  if (record.secrets_detected?.length) extra.push(`detected: ${record.secrets_detected.map((s) => `${s.detector} ${s.masked}`).join(", ")}`);
+  if (record.sanitized?.arguments?.length) extra.push(`sanitized: ${record.sanitized.arguments.length} value(s) stripped`);
+  if (record.would_have) extra.push(`would have: ${String(record.would_have.decision).toUpperCase()} by ${record.would_have.rule ?? "default-deny"}`);
+  if (extra.length) {
+    lines.push("");
+    lines.push(`${indent}${dim(extra.join("  ·  "))}`);
+  }
+
+  // Considered tree — compact, for dead-rule discovery (keep, muted)
+  if (record.considered?.length) {
+    lines.push("");
+    lines.push(`${indent}${dim("considered")}  ${dim(`${record.considered.filter((c) => c.matched).length} of ${record.considered.length} matched`)}`);
+    for (const c of record.considered.slice(0, 12)) {
+      const marker = c.matched ? bold("→") : dim(" ");
+      lines.push(`${indent}  ${marker} ${dim(String(c.effect).padEnd(11))} ${c.matched ? c.rule : dim(c.rule)}`);
+    }
+  }
+
   return lines.join("\n");
 }
 

package/src/core/kill-switch.mjs

@@ -0,0 +1,122 @@
+/**
+ * Unified Multi-Scope Emergency Kill Switch.
+ *
+ * Provides emergency freezing across scopes:
+ * - single agent
+ * - agent family
+ * - organization
+ * - environment
+ * - MCP server
+ * - credential
+ * - session
+ * - model
+ * - tool
+ */
+
+import { DECISION } from "./decisions.mjs";
+
+export const KILL_SCOPES = {
+  AGENT: "agent",
+  FAMILY: "family",
+  ORG: "org",
+  ENVIRONMENT: "environment",
+  MCP: "mcp",
+  CREDENTIAL: "credential",
+  SESSION: "session",
+  MODEL: "model",
+  TOOL: "tool",
+};
+
+export class KillSwitchEngine {
+  constructor() {
+    this.activeRules = new Map(); // id -> rule
+  }
+
+  /**
+   * Arms a kill switch.
+   */
+  arm({ scope, target, reason = "Emergency freeze activated", triggeredBy = "system" }) {
+    if (!Object.values(KILL_SCOPES).includes(scope)) {
+      throw new Error(`Invalid kill switch scope '${scope}'`);
+    }
+    const id = `ks_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const rule = {
+      id,
+      scope,
+      target: String(target).toLowerCase(),
+      reason,
+      triggeredBy,
+      armedAt: new Date().toISOString(),
+      active: true,
+    };
+    this.activeRules.set(id, rule);
+    return rule;
+  }
+
+  /**
+   * Disarms a kill switch.
+   */
+  disarm(id) {
+    return this.activeRules.delete(id);
+  }
+
+  /**
+   * Checks whether a request matches any active kill rule.
+   *
+   * @param {Object} context
+   * @returns {{ killed: boolean, decision: string, reason?: string, matchedRule?: Object }}
+   */
+  evaluate({
+    agentId = null,
+    family = null,
+    orgId = null,
+    environment = null,
+    mcp = null,
+    credential = null,
+    session = null,
+    model = null,
+    tool = null,
+  } = {}) {
+    for (const rule of this.activeRules.values()) {
+      if (!rule.active) continue;
+
+      const target = rule.target;
+
+      if (rule.scope === KILL_SCOPES.ORG && orgId && orgId.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Organization under emergency freeze: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.AGENT && agentId && agentId.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Agent '${agentId}' is frozen: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.FAMILY && family && family.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Agent family '${family}' is frozen: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.ENVIRONMENT && environment && environment.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Environment '${environment}' is frozen: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.MCP && mcp && mcp.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `MCP server '${mcp}' is disabled: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.TOOL && tool && tool.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `Tool '${tool}' is disabled: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.SESSION && session && session.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.QUARANTINE, reason: `Session '${session}' is terminated: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.MODEL && model && model.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `Model '${model}' is suspended: ${rule.reason}`, matchedRule: rule };
+      }
+      if (rule.scope === KILL_SCOPES.CREDENTIAL && credential && credential.toLowerCase() === target) {
+        return { killed: true, decision: DECISION.DENY, reason: `Credential '${credential}' is revoked: ${rule.reason}`, matchedRule: rule };
+      }
+    }
+
+    return { killed: false, decision: DECISION.ALLOW };
+  }
+
+  list() {
+    return Array.from(this.activeRules.values());
+  }
+}
+
+export const globalKillSwitch = new KillSwitchEngine();