@wrongstack/core 0.306.3 → 0.307.0

package/dist/security/index.js

@@ -894,6 +894,24 @@ function validateDirectoryPolicy(value) {
 import { homedir } from "node:os";
 
 // src/security/secret-scrubber.ts
+var JSON_CREDENTIAL_KEY_ANCHORS = [
+  'Key"',
+  'key"',
+  'KEY"',
+  'token"',
+  'Token"',
+  'TOKEN"',
+  'secret"',
+  'Secret"',
+  'SECRET"',
+  'password"',
+  'Password"',
+  'PASSWORD"',
+  'authorization"',
+  'Authorization"',
+  'bearer"',
+  'Bearer"'
+];
 var PATTERNS = [
   // Anchored at the start where possible so partial matches inside larger
   // strings don't trigger false positives.
@@ -996,6 +1014,30 @@ var PATTERNS = [
     regex: /(^|\s)([A-Z_]{4,}(?:KEY|TOKEN|SECRET|PASSWORD|PWD))\s*[:=]\s*['"]?([A-Za-z0-9_/+=-]{20,512})['"]?(?=\s|$)/g,
     anchor: ["KEY", "TOKEN", "SECRET", "PASSWORD", "PWD"]
   },
+  {
+    type: "json_credential_key",
+    // The JSON counterpart to `high_entropy_env`, and the pattern that the
+    // now-deleted `JSON_KEY_ANCHORS` list was written for. Without it those
+    // anchors only widened the cheap pre-scan — `hasCredentialAnchors` said
+    // "this text may hold a secret", every pattern then declined to match, and
+    // the value went out verbatim. `high_entropy_env` cannot cover these: it
+    // requires an UPPERCASE unquoted key (`API_KEY=…`), so `{"apiKey":"…"}`
+    // never matched.
+    //
+    // Tool results are routinely serialised as JSON, and a credential with no
+    // recognisable prefix (Azure, self-hosted gateways, Anthropic/Codex OAuth)
+    // has no other pattern that can catch it — this is the only thing standing
+    // between such a value and the session JSONL, chronicle, HQ broadcast and
+    // the model's own context.
+    //
+    // The key may carry a prefix (`"anthropicApiKey"`), but the credential word
+    // must END the key: `"tokenCount"` and `"maxTokens"` do not match, because
+    // the closing quote has to follow the word immediately.
+    // Value floor of 8 chars keeps enum-ish values (`"authorization":"none"`)
+    // out. Capture groups: 1=key + punctuation, 2=value, 3=closing quote.
+    regex: /("[A-Za-z0-9_]*(?:apiKey|api_key|token|secret|password|authorization|bearer|private_key|access_token|refresh_token|client_secret)"\s*:\s*")([^"\\]{8,512})(")/gi,
+    anchor: JSON_CREDENTIAL_KEY_ANCHORS
+  },
   // ── Ported from packages/plugins credential-patterns.ts (WS-034) ─────────
   // The plugin runtime carried 37 patterns while this scrubber — the one that
   // guards session JSONL, chronicle, HQ broadcast, WebUI events and the auth
@@ -1078,9 +1120,12 @@ var PATTERNS = [
     anchor: "GOCSPX-"
   }
 ];
-var SIMPLE_PATTERNS = PATTERNS.filter((p) => p.type !== "high_entropy_env");
+var SIMPLE_PATTERNS = PATTERNS.filter(
+  (p) => p.type !== "high_entropy_env" && p.type !== "json_credential_key"
+);
 var COMBINED_REGEX = new RegExp(SIMPLE_PATTERNS.map((p) => `(${p.regex.source})`).join("|"), "g");
 var HIGH_ENTROPY_REGEX = PATTERNS.find((p) => p.type === "high_entropy_env").regex;
+var JSON_CREDENTIAL_REGEX = PATTERNS.find((p) => p.type === "json_credential_key").regex;
 var COMBINED_REPLACEMENTS = SIMPLE_PATTERNS.map((p) => `[REDACTED:${p.type}]`);
 var SCRUB_CHUNK_BYTES = 64 * 1024;
 var SCRUB_OVERLAP_BYTES = 1024;
@@ -1091,20 +1136,7 @@ var PATTERN_ANCHORS = [
     )
   )
 ];
-var JSON_KEY_ANCHORS = [
-  '"apiKey"',
-  '"api_key"',
-  '"token"',
-  '"secret"',
-  '"password"',
-  '"authorization"',
-  '"bearer"',
-  '"private_key"',
-  '"access_token"',
-  '"refresh_token"',
-  '"client_secret"'
-];
-var ALL_ANCHORS = [...PATTERN_ANCHORS, ...JSON_KEY_ANCHORS];
+var ALL_ANCHORS = PATTERN_ANCHORS;
 function hasCredentialAnchors(text) {
   for (const anchor of ALL_ANCHORS) {
     if (text.includes(anchor)) return true;
@@ -1153,6 +1185,9 @@ var DefaultSecretScrubber = class {
     out = out.replace(HIGH_ENTROPY_REGEX, (_match, lead, key, _value) => {
       return `${lead}${key}=[REDACTED:high_entropy_env]`;
     });
+    out = out.replace(JSON_CREDENTIAL_REGEX, (_match, keyPrefix, _value, closingQuote) => {
+      return `${keyPrefix}[REDACTED:json_credential_key]${closingQuote}`;
+    });
     return out;
   }
   /**
@@ -1751,175 +1786,23 @@ function subjectForToolInput(toolName, input, subjectKey) {
   return void 0;
 }
 
-// src/security/permission-policy-schema.ts
-var TRUST_POLICY_SCHEMA_VERSION = 1;
-var TRUST_POLICY_LIMITS = Object.freeze({
-  maxTools: 1e3,
-  maxPatternsPerRule: 1e3,
-  maxToolNameChars: 256,
-  maxPatternChars: 4096
-});
-var TRUST_POLICY_JSON_SCHEMA = Object.freeze({
-  $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://wrongstack.dev/schemas/trust-policy-v1.json",
-  title: "WrongStack Trust Policy",
-  type: "object",
-  maxProperties: TRUST_POLICY_LIMITS.maxTools,
-  propertyNames: {
-    minLength: 1,
-    maxLength: TRUST_POLICY_LIMITS.maxToolNameChars,
-    not: { enum: ["__proto__", "prototype", "constructor"] }
-  },
-  additionalProperties: {
-    type: "object",
-    additionalProperties: false,
-    properties: {
-      allow: {
-        type: "array",
-        maxItems: TRUST_POLICY_LIMITS.maxPatternsPerRule,
-        items: { type: "string", minLength: 1, maxLength: TRUST_POLICY_LIMITS.maxPatternChars }
-      },
-      deny: {
-        type: "array",
-        maxItems: TRUST_POLICY_LIMITS.maxPatternsPerRule,
-        items: { type: "string", minLength: 1, maxLength: TRUST_POLICY_LIMITS.maxPatternChars }
-      },
-      auto: { type: "boolean" },
-      trustWorkdir: { type: "boolean" },
-      denyPrivate: { type: "boolean" }
-    }
-  }
-});
-var RULE_FIELDS2 = /* @__PURE__ */ new Set(["allow", "deny", "auto", "trustWorkdir", "denyPrivate"]);
-var UNSAFE_PROPERTY_NAMES2 = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function error2(diagnostics, code, path9, message) {
-  diagnostics.push({ severity: "error", code, path: path9, message });
-}
-function validatePatterns(value, path9, diagnostics) {
-  if (!Array.isArray(value)) {
-    error2(diagnostics, "invalid_pattern_list", path9, "must be an array of strings");
-    return void 0;
-  }
-  if (value.length > TRUST_POLICY_LIMITS.maxPatternsPerRule) {
-    error2(
-      diagnostics,
-      "too_many_patterns",
-      path9,
-      `must contain at most ${TRUST_POLICY_LIMITS.maxPatternsPerRule} patterns`
-    );
-    return void 0;
-  }
-  const patterns = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const [index, pattern] of value.entries()) {
-    const itemPath = `${path9}[${index}]`;
-    if (typeof pattern !== "string" || pattern.length === 0 || pattern.length > TRUST_POLICY_LIMITS.maxPatternChars) {
-      error2(
-        diagnostics,
-        "invalid_pattern",
-        itemPath,
-        `must be a non-empty string up to ${TRUST_POLICY_LIMITS.maxPatternChars} characters`
-      );
-      continue;
-    }
-    if (seen.has(pattern)) {
-      diagnostics.push({
-        severity: "warning",
-        code: "duplicate_pattern",
-        path: itemPath,
-        message: "duplicates an earlier pattern and was normalized away"
-      });
-      continue;
-    }
-    seen.add(pattern);
-    patterns.push(pattern);
-  }
-  return patterns;
-}
-function validateTrustPolicy(value) {
-  const diagnostics = [];
-  if (!isRecord2(value)) {
-    return {
-      ok: false,
-      diagnostics: [
-        {
-          severity: "error",
-          code: "invalid_root",
-          path: "$",
-          message: "trust policy must be an object"
-        }
-      ]
-    };
-  }
-  const entries = Object.entries(value);
-  if (entries.length > TRUST_POLICY_LIMITS.maxTools) {
-    error2(
-      diagnostics,
-      "too_many_tools",
-      "$",
-      `must contain at most ${TRUST_POLICY_LIMITS.maxTools} tool rules`
-    );
-  }
-  const policy = {};
-  for (const [toolName, rawRule] of entries.slice(0, TRUST_POLICY_LIMITS.maxTools)) {
-    const toolPath = `$[${JSON.stringify(toolName)}]`;
-    if (toolName.length === 0 || toolName.length > TRUST_POLICY_LIMITS.maxToolNameChars) {
-      error2(
-        diagnostics,
-        "invalid_tool_name",
-        toolPath,
-        `tool name must be 1-${TRUST_POLICY_LIMITS.maxToolNameChars} characters`
-      );
-      continue;
-    }
-    if (UNSAFE_PROPERTY_NAMES2.has(toolName)) {
-      error2(
-        diagnostics,
-        "unsafe_tool_name",
-        toolPath,
-        "reserved object property names are not valid tool rules"
-      );
-      continue;
-    }
-    if (!isRecord2(rawRule)) {
-      error2(diagnostics, "invalid_rule", toolPath, "tool rule must be an object");
-      continue;
-    }
-    for (const field of Object.keys(rawRule)) {
-      if (!RULE_FIELDS2.has(field)) {
-        error2(
-          diagnostics,
-          "unknown_field",
-          `${toolPath}.${field}`,
-          `unknown policy field "${field}"`
-        );
-      }
-    }
-    const rule = {};
-    for (const field of ["allow", "deny"]) {
-      if (rawRule[field] === void 0) continue;
-      const patterns = validatePatterns(rawRule[field], `${toolPath}.${field}`, diagnostics);
-      if (patterns) rule[field] = patterns;
-    }
-    for (const field of ["auto", "trustWorkdir", "denyPrivate"]) {
-      const setting = rawRule[field];
-      if (setting === void 0) continue;
-      if (typeof setting !== "boolean") {
-        error2(diagnostics, "invalid_boolean", `${toolPath}.${field}`, "must be a boolean");
-      } else {
-        rule[field] = setting;
-      }
-    }
-    policy[toolName] = rule;
-  }
-  return diagnostics.some((diagnostic) => diagnostic.severity === "error") ? { ok: false, diagnostics } : { ok: true, policy, diagnostics };
+// src/security/permission-helpers.ts
+import { realpathSync } from "node:fs";
+import * as path5 from "node:path";
+
+// src/utils/wstack-paths.ts
+import * as os from "node:os";
+import * as path3 from "node:path";
+function wstackGlobalRoot() {
+  const fromEnv = process.env["WRONGSTACK_HOME"];
+  if (fromEnv && fromEnv.trim().length > 0) return path3.resolve(fromEnv);
+  return path3.join(os.homedir(), ".wrongstack");
 }
 
 // src/security/yolo-risk.ts
-import * as path3 from "node:path";
+import * as os2 from "node:os";
+import * as path4 from "node:path";
+var PROTECTED_STATE_BASENAMES = /^(?:config\.json|config\.local\.json|trust\.json|auth\.json|\.key)$/i;
 var CATASTROPHIC_PATTERNS = [
   /\b(?:mkfs(?:\.[a-z0-9]+)?|mke2fs|newfs)\b/i,
   // make a filesystem — wipes a partition
@@ -1979,9 +1862,9 @@ function getInputString(input, key) {
 function pathLooksInsideProject(rawPath, projectRoot) {
   if (!projectRoot) return false;
   if (rawPath === "~" || rawPath.startsWith("~/") || rawPath.startsWith("~\\")) return false;
-  const resolved = path3.resolve(projectRoot, rawPath);
-  const relative4 = path3.relative(projectRoot, resolved);
-  return !!relative4 && !relative4.startsWith("..") && !path3.isAbsolute(relative4);
+  const resolved = path4.resolve(projectRoot, rawPath);
+  const relative4 = path4.relative(projectRoot, resolved);
+  return !!relative4 && !relative4.startsWith("..") && !path4.isAbsolute(relative4);
 }
 function tokenizeShell(command) {
   return command.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, "")) ?? [];
@@ -2155,6 +2038,48 @@ function hasCatastrophicDelete(command) {
   }
   return false;
 }
+function hasWriteToAgentStateRoot(command) {
+  const tokens = tokenizeShell(command);
+  for (let i = 0; i < tokens.length - 1; i++) {
+    const t = tokens[i];
+    if (t === ">" || t === ">>") {
+      const target = tokens[i + 1];
+      if (target && looksLikeAgentStateTarget(target)) return true;
+    }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]?.toLowerCase();
+    if (t === "tee") {
+      for (let j = i + 1; j < tokens.length; j++) {
+        const arg = tokens[j];
+        if (!arg || arg.startsWith("-")) continue;
+        if (SHELL_OPERATORS.has(arg)) break;
+        if (looksLikeAgentStateTarget(arg)) return true;
+        break;
+      }
+    }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]?.toLowerCase();
+    if (t === "cp" || t === "copy" || t === "mv" || t === "move") {
+      const args = commandSegment(tokens, i + 1);
+      const dst = args.filter((a) => !a.startsWith("-") && !SHELL_OPERATORS.has(a)).pop();
+      if (dst && looksLikeAgentStateTarget(dst)) return true;
+    }
+  }
+  return false;
+}
+function looksLikeAgentStateTarget(rawPath) {
+  const expanded = rawPath.replace(/^~([\\/])/, (_, sep2) => `${os2.homedir()}${sep2}`);
+  const resolved = path4.resolve(expanded);
+  const rootStr = wstackGlobalRoot();
+  const resolvedNorm = resolved.replace(/\\/g, "/").toLowerCase();
+  const rootNorm = path4.resolve(rootStr).replace(/\\/g, "/").toLowerCase();
+  if (!resolvedNorm.startsWith(rootNorm) && !resolvedNorm.includes(".wrongstack")) {
+    return false;
+  }
+  return PROTECTED_STATE_BASENAMES.test(path4.basename(resolved));
+}
 function isClearlyDestructiveBashCommand(command, projectRoot) {
   const trimmed = command.trim();
   if (!trimmed) return false;
@@ -2163,85 +2088,12 @@ function isClearlyDestructiveBashCommand(command, projectRoot) {
   if (hasExternalPublish(trimmed)) return true;
   if (hasFindExec(trimmed)) return true;
   if (hasCatastrophicDelete(trimmed)) return true;
+  if (hasWriteToAgentStateRoot(trimmed)) return true;
   if (CATASTROPHIC_PATTERNS.some((pattern) => pattern.test(trimmed))) return true;
   if (HIGH_IMPACT_PATTERNS.some((pattern) => pattern.test(trimmed))) return true;
   return false;
 }
 
-// src/security/auto-approve-policy.ts
-var AutoApprovePermissionPolicy = class _AutoApprovePermissionPolicy {
-  allowedCapabilities;
-  constructor(allowedCapabilities) {
-    this.allowedCapabilities = allowedCapabilities ?? [
-      ToolCapabilities.FS_READ,
-      ToolCapabilities.NET_OUTBOUND
-    ];
-  }
-  static isMcpTool(name) {
-    return name.startsWith("mcp__");
-  }
-  async evaluate(tool) {
-    const caps = tool.capabilities ?? [];
-    const hasAllowedCap = caps.some((c) => this.allowedCapabilities.includes(c));
-    const isMcp = _AutoApprovePermissionPolicy.isMcpTool(tool.name);
-    const mcpProxyAllowed = this.allowedCapabilities.includes(ToolCapabilities.MCP_PROXY);
-    const dangerousNotAllowed = getDangerousCapabilities(tool).filter(
-      (c) => !this.allowedCapabilities.includes(c)
-    );
-    const blocked = tool.permission === "deny" || isMcp && !mcpProxyAllowed || !hasAllowedCap || dangerousNotAllowed.length > 0;
-    if (blocked) {
-      const reason = isMcp && !mcpProxyAllowed ? `MCP tool ${tool.name} is not auto-approved for subagents \u2014 ask the leader to allow mcp.proxy explicitly` : tool.permission === "deny" ? "tool default deny" : dangerousNotAllowed.length > 0 ? `tool requires un-granted dangerous capability (needs: ${dangerousNotAllowed.join(", ")}, allowed: ${this.allowedCapabilities.join(", ")})` : `tool lacks allowed capability (has: ${caps.join(", ") || "none"}, allowed: ${this.allowedCapabilities.join(", ")})`;
-      return {
-        permission: "deny",
-        source: "subagent_guard",
-        reason
-      };
-    }
-    return { permission: "auto", source: "yolo" };
-  }
-  async trust() {
-  }
-  async deny() {
-  }
-  denyOnce() {
-  }
-  allowOnce() {
-  }
-  async explain(tool) {
-    const decision = await this.evaluate(tool);
-    return {
-      toolName: tool.name,
-      subject: null,
-      steps: [
-        {
-          rule: "subagent auto",
-          matched: decision.permission === "auto",
-          decision: decision.permission,
-          source: decision.source,
-          detail: decision.reason ?? `subagent policy: ${decision.permission}`
-        }
-      ],
-      winnerIndex: 0,
-      decision
-    };
-  }
-  async reload() {
-  }
-};
-
-// src/security/permission-helpers.ts
-import { realpathSync } from "node:fs";
-import * as path5 from "node:path";
-
-// src/utils/wstack-paths.ts
-import * as os from "node:os";
-import * as path4 from "node:path";
-function wstackGlobalRoot() {
-  const fromEnv = process.env["WRONGSTACK_HOME"];
-  if (fromEnv && fromEnv.trim().length > 0) return path4.resolve(fromEnv);
-  return path4.join(os.homedir(), ".wrongstack");
-}
-
 // src/security/permission-helpers.ts
 function matchesTrust(patterns, subject) {
   return patterns.includes(subject) || matchAny(patterns, subject);
@@ -2377,8 +2229,558 @@ function shellCommandReadsSensitivePath(command) {
     const rest = tokens.slice(i + 1);
     if (rest.some((arg) => pathLooksSensitive(arg))) return true;
   }
-  return false;
-}
+  return false;
+}
+
+// src/security/permission-explain.ts
+function explainPermissionTrace(state, tool, input, ctx) {
+  const subject = subjectForToolInput(tool.name, input, tool.subjectKey);
+  const steps = [];
+  let winnerIndex = -1;
+  const add = (rule, matched, decision, source, detail) => {
+    steps.push({ rule, matched, decision, source, detail });
+  };
+  if (state.policyInvalid) {
+    add("policy invalid", true, "deny", "deny", "trust policy is invalid; all tools are denied");
+    winnerIndex = 0;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: { permission: "deny", source: "deny", reason: "trust policy is invalid" }
+    };
+  }
+  add("policy valid", false, "auto", "default", "trust policy loaded successfully");
+  let namespaceEntry;
+  for (const { pattern, value } of state.wildcardEntries) {
+    if (matchGlob(pattern, tool.name)) {
+      namespaceEntry = value;
+      break;
+    }
+  }
+  const entry = state.policy[tool.name] ?? namespaceEntry;
+  const namespaceSource = namespaceEntry ? `wildcard entry matched (${Object.keys(state.policy).find((k) => k.includes("*") && matchGlob(k, tool.name))})` : "no namespace match";
+  const cacheKey = `${tool.name}::${subject ?? tool.name}`;
+  if (state.sessionDenied.has(cacheKey)) {
+    add(
+      "session soft deny",
+      true,
+      "deny",
+      "deny",
+      'user pressed "no" earlier in this session \u2014 blocked until reload'
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: {
+        permission: "deny",
+        source: "deny",
+        reason: "session soft deny (user pressed no)"
+      }
+    };
+  }
+  add(
+    "session soft deny",
+    false,
+    "deny",
+    "deny",
+    "no session-level soft deny for this tool+subject"
+  );
+  if (state.sessionAllowed.has(cacheKey)) {
+    add(
+      "session soft allow",
+      true,
+      "auto",
+      "trust",
+      'user pressed "yes" in current session \u2014 one-shot auto-approve (consumed)'
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: {
+        permission: "auto",
+        source: "trust",
+        reason: "session one-shot allow (user pressed yes)"
+      }
+    };
+  }
+  add(
+    "session soft allow",
+    false,
+    "auto",
+    "trust",
+    "no session-level one-shot allow for this tool+subject"
+  );
+  if (entry?.deny && subject && matchesTrust(entry.deny, subject)) {
+    add(
+      "trust deny",
+      true,
+      "deny",
+      "deny",
+      `subject "${subject}" matched a deny pattern in trust file`
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: { permission: "deny", source: "deny", reason: "matched deny pattern" }
+    };
+  }
+  add(
+    "trust deny",
+    false,
+    "deny",
+    "deny",
+    `no deny pattern matched (namespace: ${namespaceSource})`
+  );
+  if (tool.permission === "deny") {
+    add(
+      "tool default deny",
+      true,
+      "deny",
+      "default",
+      `tool "${tool.name}" has permission: deny by default`
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: { permission: "deny", source: "default", reason: "tool default deny" }
+    };
+  }
+  add(
+    "tool default deny",
+    false,
+    "deny",
+    "default",
+    `tool "${tool.name}" has permission: "${tool.permission}"`
+  );
+  if (entry?.allow && subject && matchesTrust(entry.allow, subject)) {
+    add(
+      "trust allow",
+      true,
+      "auto",
+      "trust",
+      `subject "${subject}" matched an allow pattern in trust file`
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: { permission: "auto", source: "trust", reason: "matched allow pattern" }
+    };
+  }
+  add(
+    "trust allow",
+    false,
+    "auto",
+    "trust",
+    `no allow pattern matched (namespace: ${namespaceSource})`
+  );
+  if (entry?.auto) {
+    add("trust auto", true, "auto", "trust", `trust file has auto: true for "${tool.name}"`);
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: { permission: "auto", source: "trust", reason: "trust auto" }
+    };
+  }
+  add("trust auto", false, "auto", "trust", `no auto flag for "${tool.name}" in trust file`);
+  if (!state.yolo && state.isSensitiveReadCall(tool, input)) {
+    const hasDelegate2 = state.promptDelegatePresent;
+    add(
+      "sensitive read",
+      true,
+      "confirm",
+      "default",
+      hasDelegate2 ? "sensitive file read detected \u2014 would prompt user for approval" : "sensitive file read detected \u2014 returns confirm (no prompt delegate)"
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: {
+        permission: "confirm",
+        source: "default",
+        riskTier: "standard",
+        reason: "sensitive file read needs explicit approval"
+      }
+    };
+  }
+  add(
+    "sensitive read",
+    false,
+    "confirm",
+    "default",
+    "not a sensitive read call (or YOLO bypasses this check)"
+  );
+  if (state.yolo) {
+    if (state.yoloBlockedAsDestructive(tool, input, ctx)) {
+      add(
+        "yolo destructive gate",
+        true,
+        "confirm",
+        "yolo_destructive",
+        "YOLO is active but this is a clearly destructive command \u2014 still asking"
+      );
+      winnerIndex = steps.length - 1;
+      return {
+        toolName: tool.name,
+        subject,
+        steps,
+        winnerIndex,
+        decision: {
+          permission: "confirm",
+          source: "yolo_destructive",
+          riskTier: "destructive",
+          reason: "destructive command needs explicit approval even in YOLO mode"
+        }
+      };
+    }
+    add(
+      "yolo",
+      true,
+      "auto",
+      "yolo",
+      "YOLO mode is active \u2014 auto-approving every non-denied call"
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: { permission: "auto", source: "yolo" }
+    };
+  }
+  add("yolo", false, "auto", "yolo", "YOLO mode is not active");
+  if (tool.name === "write" && subject) {
+    const isAgentState = isInsideAgentStateRoot(subject);
+    const hasRead = ctx.hasRead(subject) && !isAgentState;
+    add(
+      "write smart bypass",
+      hasRead,
+      "auto",
+      "context",
+      isAgentState ? `file "${subject}" is WrongStack's own state \u2014 bypass never applies, write always confirms` : hasRead ? `file "${subject}" was already read in this session \u2014 auto-approving write` : `file "${subject}" was not read in this session \u2014 bypass does not apply`
+    );
+    if (hasRead) {
+      winnerIndex = steps.length - 1;
+      return {
+        toolName: tool.name,
+        subject,
+        steps,
+        winnerIndex,
+        decision: {
+          permission: "auto",
+          source: "context",
+          reason: "file already read in this session"
+        }
+      };
+    }
+  } else {
+    add(
+      "write smart bypass",
+      false,
+      "auto",
+      "context",
+      'tool is not "write" or has no subject \u2014 bypass does not apply'
+    );
+  }
+  const hasWriteCap = hasCapability(tool, ToolCapabilities.FS_WRITE);
+  const hasShellCap = hasCapability(tool, [
+    ToolCapabilities.SHELL_ARBITRARY,
+    ToolCapabilities.SHELL_RESTRICTED,
+    ToolCapabilities.SHELL_EXEC
+  ]);
+  const hasInstallCap = hasCapability(tool, ToolCapabilities.PACKAGE_INSTALL);
+  const hasConfigCap = hasCapability(tool, ToolCapabilities.CONFIG_MUTATE);
+  const hasSubagentCap = hasCapability(tool, ToolCapabilities.SUBAGENT_SPAWN);
+  const isMutating = tool.mutating || hasWriteCap || hasShellCap || hasInstallCap || hasConfigCap || hasSubagentCap;
+  if (tool.permission === "auto" && !isMutating) {
+    add(
+      "safe default auto",
+      true,
+      "auto",
+      "default",
+      `tool "${tool.name}" has auto permission and is not mutating \u2014 safe to auto-approve`
+    );
+    winnerIndex = steps.length - 1;
+    return {
+      toolName: tool.name,
+      subject,
+      steps,
+      winnerIndex,
+      decision: { permission: "auto", source: "default" }
+    };
+  }
+  add(
+    "mutating default confirm",
+    true,
+    "confirm",
+    "default",
+    isMutating ? `tool "${tool.name}" is mutating (default auto not enough) \u2014 needs confirmation` : `tool "${tool.name}" has "${tool.permission}" permission \u2014 needs confirmation`
+  );
+  winnerIndex = steps.length - 1;
+  const hasDelegate = state.promptDelegatePresent;
+  return {
+    toolName: tool.name,
+    subject,
+    steps,
+    winnerIndex,
+    decision: {
+      permission: "confirm",
+      source: "default",
+      ...hasDelegate ? { reason: "would prompt user via delegate" } : {}
+    }
+  };
+}
+
+// src/security/permission-policy-schema.ts
+var TRUST_POLICY_SCHEMA_VERSION = 1;
+var TRUST_POLICY_LIMITS = Object.freeze({
+  maxTools: 1e3,
+  maxPatternsPerRule: 1e3,
+  maxToolNameChars: 256,
+  maxPatternChars: 4096
+});
+var TRUST_POLICY_JSON_SCHEMA = Object.freeze({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://wrongstack.dev/schemas/trust-policy-v1.json",
+  title: "WrongStack Trust Policy",
+  type: "object",
+  maxProperties: TRUST_POLICY_LIMITS.maxTools,
+  propertyNames: {
+    minLength: 1,
+    maxLength: TRUST_POLICY_LIMITS.maxToolNameChars,
+    not: { enum: ["__proto__", "prototype", "constructor"] }
+  },
+  additionalProperties: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      allow: {
+        type: "array",
+        maxItems: TRUST_POLICY_LIMITS.maxPatternsPerRule,
+        items: { type: "string", minLength: 1, maxLength: TRUST_POLICY_LIMITS.maxPatternChars }
+      },
+      deny: {
+        type: "array",
+        maxItems: TRUST_POLICY_LIMITS.maxPatternsPerRule,
+        items: { type: "string", minLength: 1, maxLength: TRUST_POLICY_LIMITS.maxPatternChars }
+      },
+      auto: { type: "boolean" },
+      trustWorkdir: { type: "boolean" },
+      denyPrivate: { type: "boolean" }
+    }
+  }
+});
+var RULE_FIELDS2 = /* @__PURE__ */ new Set(["allow", "deny", "auto", "trustWorkdir", "denyPrivate"]);
+var UNSAFE_PROPERTY_NAMES2 = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function error2(diagnostics, code, path9, message) {
+  diagnostics.push({ severity: "error", code, path: path9, message });
+}
+function validatePatterns(value, path9, diagnostics) {
+  if (!Array.isArray(value)) {
+    error2(diagnostics, "invalid_pattern_list", path9, "must be an array of strings");
+    return void 0;
+  }
+  if (value.length > TRUST_POLICY_LIMITS.maxPatternsPerRule) {
+    error2(
+      diagnostics,
+      "too_many_patterns",
+      path9,
+      `must contain at most ${TRUST_POLICY_LIMITS.maxPatternsPerRule} patterns`
+    );
+    return void 0;
+  }
+  const patterns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, pattern] of value.entries()) {
+    const itemPath = `${path9}[${index}]`;
+    if (typeof pattern !== "string" || pattern.length === 0 || pattern.length > TRUST_POLICY_LIMITS.maxPatternChars) {
+      error2(
+        diagnostics,
+        "invalid_pattern",
+        itemPath,
+        `must be a non-empty string up to ${TRUST_POLICY_LIMITS.maxPatternChars} characters`
+      );
+      continue;
+    }
+    if (seen.has(pattern)) {
+      diagnostics.push({
+        severity: "warning",
+        code: "duplicate_pattern",
+        path: itemPath,
+        message: "duplicates an earlier pattern and was normalized away"
+      });
+      continue;
+    }
+    seen.add(pattern);
+    patterns.push(pattern);
+  }
+  return patterns;
+}
+function validateTrustPolicy(value) {
+  const diagnostics = [];
+  if (!isRecord2(value)) {
+    return {
+      ok: false,
+      diagnostics: [
+        {
+          severity: "error",
+          code: "invalid_root",
+          path: "$",
+          message: "trust policy must be an object"
+        }
+      ]
+    };
+  }
+  const entries = Object.entries(value);
+  if (entries.length > TRUST_POLICY_LIMITS.maxTools) {
+    error2(
+      diagnostics,
+      "too_many_tools",
+      "$",
+      `must contain at most ${TRUST_POLICY_LIMITS.maxTools} tool rules`
+    );
+  }
+  const policy = {};
+  for (const [toolName, rawRule] of entries.slice(0, TRUST_POLICY_LIMITS.maxTools)) {
+    const toolPath = `$[${JSON.stringify(toolName)}]`;
+    if (toolName.length === 0 || toolName.length > TRUST_POLICY_LIMITS.maxToolNameChars) {
+      error2(
+        diagnostics,
+        "invalid_tool_name",
+        toolPath,
+        `tool name must be 1-${TRUST_POLICY_LIMITS.maxToolNameChars} characters`
+      );
+      continue;
+    }
+    if (UNSAFE_PROPERTY_NAMES2.has(toolName)) {
+      error2(
+        diagnostics,
+        "unsafe_tool_name",
+        toolPath,
+        "reserved object property names are not valid tool rules"
+      );
+      continue;
+    }
+    if (!isRecord2(rawRule)) {
+      error2(diagnostics, "invalid_rule", toolPath, "tool rule must be an object");
+      continue;
+    }
+    for (const field of Object.keys(rawRule)) {
+      if (!RULE_FIELDS2.has(field)) {
+        error2(
+          diagnostics,
+          "unknown_field",
+          `${toolPath}.${field}`,
+          `unknown policy field "${field}"`
+        );
+      }
+    }
+    const rule = {};
+    for (const field of ["allow", "deny"]) {
+      if (rawRule[field] === void 0) continue;
+      const patterns = validatePatterns(rawRule[field], `${toolPath}.${field}`, diagnostics);
+      if (patterns) rule[field] = patterns;
+    }
+    for (const field of ["auto", "trustWorkdir", "denyPrivate"]) {
+      const setting = rawRule[field];
+      if (setting === void 0) continue;
+      if (typeof setting !== "boolean") {
+        error2(diagnostics, "invalid_boolean", `${toolPath}.${field}`, "must be a boolean");
+      } else {
+        rule[field] = setting;
+      }
+    }
+    policy[toolName] = rule;
+  }
+  return diagnostics.some((diagnostic) => diagnostic.severity === "error") ? { ok: false, diagnostics } : { ok: true, policy, diagnostics };
+}
+
+// src/security/auto-approve-policy.ts
+var AutoApprovePermissionPolicy = class _AutoApprovePermissionPolicy {
+  allowedCapabilities;
+  constructor(allowedCapabilities) {
+    this.allowedCapabilities = allowedCapabilities ?? [
+      ToolCapabilities.FS_READ,
+      ToolCapabilities.NET_OUTBOUND
+    ];
+  }
+  static isMcpTool(name) {
+    return name.startsWith("mcp__");
+  }
+  async evaluate(tool) {
+    const caps = tool.capabilities ?? [];
+    const hasAllowedCap = caps.some((c) => this.allowedCapabilities.includes(c));
+    const isMcp = _AutoApprovePermissionPolicy.isMcpTool(tool.name);
+    const mcpProxyAllowed = this.allowedCapabilities.includes(ToolCapabilities.MCP_PROXY);
+    const dangerousNotAllowed = getDangerousCapabilities(tool).filter(
+      (c) => !this.allowedCapabilities.includes(c)
+    );
+    const blocked = tool.permission === "deny" || isMcp && !mcpProxyAllowed || !hasAllowedCap || dangerousNotAllowed.length > 0;
+    if (blocked) {
+      const reason = isMcp && !mcpProxyAllowed ? `MCP tool ${tool.name} is not auto-approved for subagents \u2014 ask the leader to allow mcp.proxy explicitly` : tool.permission === "deny" ? "tool default deny" : dangerousNotAllowed.length > 0 ? `tool requires un-granted dangerous capability (needs: ${dangerousNotAllowed.join(", ")}, allowed: ${this.allowedCapabilities.join(", ")})` : `tool lacks allowed capability (has: ${caps.join(", ") || "none"}, allowed: ${this.allowedCapabilities.join(", ")})`;
+      return {
+        permission: "deny",
+        source: "subagent_guard",
+        reason
+      };
+    }
+    return { permission: "auto", source: "yolo" };
+  }
+  async trust() {
+  }
+  async deny() {
+  }
+  denyOnce() {
+  }
+  allowOnce() {
+  }
+  async explain(tool) {
+    const decision = await this.evaluate(tool);
+    return {
+      toolName: tool.name,
+      subject: null,
+      steps: [
+        {
+          rule: "subagent auto",
+          matched: decision.permission === "auto",
+          decision: decision.permission,
+          source: decision.source,
+          detail: decision.reason ?? `subagent policy: ${decision.permission}`
+        }
+      ],
+      winnerIndex: 0,
+      decision
+    };
+  }
+  async reload() {
+  }
+};
 
 // src/security/permission-policy.ts
 function fsWriteTargetPaths(input) {
@@ -2414,70 +2816,13 @@ var DefaultPermissionPolicy = class {
   loaded = false;
   trustFile;
   yolo;
-  /**
-   * Session-scoped "soft deny" map. When the user presses 'n' (block once),
-   * the tool+pattern is added here. If the LLM retries in the same session,
-   * we return deny directly without asking again.
-   *
-   * Cleared on reload() since reload = fresh trust file snapshot.
-   */
   sessionDenied = /* @__PURE__ */ new Map();
-  /**
-   * Session-scoped one-shot "soft trust" map. When the user presses 'y', the
-   * tool+pattern is added here so the immediate confirm re-run can proceed.
-   * The entry is consumed on first use; future calls must ask again unless the
-   * user chose persistent trust.
-   *
-   * Cleared on reload().
-   */
   sessionAllowed = /* @__PURE__ */ new Map();
-  /**
-   * Interactive prompt delegate. When set, `evaluate()` calls it to get a
-   * user decision synchronously (CLI REPL path). When cleared (TUI / WebUI),
-   * `evaluate()` returns `confirm` so the caller can emit
-   * `tool.confirm_needed` for the UI layer to handle.
-   *
-   * Mutable so the host can switch from CLI-prompt to event-driven
-   * confirmation at runtime (e.g. when `--goal` forces TUI mode after
-   * the agent was already constructed).
-   */
   promptDelegate;
-  /** Pre-compiled wildcard patterns — rebuilt on reload for O(1) lookup. */
   wildcardEntries = [];
-  /**
-   * Evaluate-result cache. Keyed by `tool.name::subject::permissionFingerprint`
-   * so repeated calls with the same tool+input skip namespace matching,
-   * subject computation, and pattern matching (matchAny). The fingerprint
-   * suffix covers the `Tool` fields `evaluate()` reads (`permission`,
-   * `riskTier`, `mutating`, `capabilities`), so a tool redefined via
-   * `ToolRegistry.wrap()` misses the cache instead of inheriting a stale
-   * verdict.
-   *
-   * Cleared on any state change (reload, trust, deny, yolo toggle) because
-   * the result depends on the full policy state. The write-tool smart-bypass
-   * (step 7 in `evaluate()`) is not cached since `ctx.hasRead()` changes
-   * dynamically within a session.
-   *
-   * P3 #17 (before-release.md): capped at 500 entries via LRU eviction. An
-   * iteration that evaluates thousands of unique tool+subject combinations
-   * (e.g. repeated `tool-help` or `bash` with different commands) can grow
-   * the cache without bound. 500 is far more than any single iteration needs;
-   * the LRU evicts the least-recently-used entries first.
-   */
   _evalCache = new LruCache(500);
   policyDiagnostics = [];
   policyInvalid = false;
-  /**
-   * When true, YOLO also auto-approves clearly destructive shell commands.
-   *
-   * WS-008: `isClearlyDestructiveBashCommand` was exported and heavily tested
-   * but called from zero production modules, so YOLO returned `auto` for
-   * everything — including `rm -rf`, git history rewrites, and external
-   * publishes. The `'yolo_destructive'` decision source, the getter/setter on
-   * PermissionPolicy, and the TUI branch that reads it all existed; only the
-   * gate itself was missing. Defaults to false: destructive commands still ask,
-   * even in YOLO.
-   */
   yoloDestructive;
   constructor(opts) {
     this.trustFile = opts.trustFile;
@@ -2485,30 +2830,13 @@ var DefaultPermissionPolicy = class {
     this.yoloDestructive = opts.yoloDestructive ?? false;
     this.promptDelegate = opts.promptDelegate;
   }
-  /** Allow YOLO to cover destructive shell commands too (off by default). */
   setYoloDestructive(enabled) {
     if (this.yoloDestructive !== enabled) this._evalCache.clear();
     this.yoloDestructive = enabled;
   }
-  /** Whether YOLO currently extends to destructive shell commands. */
   getYoloDestructive() {
     return this.yoloDestructive;
   }
-  /**
-   * True when this call is an FS_WRITE whose target lands inside WrongStack's
-   * own state root.
-   *
-   * FS_WRITE tools disagree on where the target path lives: write/edit use
-   * `path`, replace/format/git `files` (string OR array), patch `directory`,
-   * design `out`, scaffold writes under `cwd`/`template`. Checking only
-   * `path`/`file_path` let a state-root write merely switch tools, so every
-   * path-bearing key is inspected.
-   *
-   * Shared by the YOLO carve-out and the eval-cache guard so the two cannot
-   * drift: the carve-out scans all path keys while the cache key fingerprints
-   * only the subject key, so the cache must consult the same predicate or a
-   * secondary state-root key can be replayed a cached `auto`.
-   */
   hasAgentStateWriteTarget(tool, input, ctx) {
     if (!hasCapability(tool, ToolCapabilities.FS_WRITE)) return false;
     for (const targetPath of fsWriteTargetPaths(input)) {
@@ -2518,11 +2846,6 @@ var DefaultPermissionPolicy = class {
     }
     return false;
   }
-  /**
-   * True when YOLO is on but this specific call is a destructive shell command
-   * the user has not opted to auto-approve. Shared by `evaluate()` and the
-   * explain/trace path so the two cannot drift.
-   */
   yoloBlockedAsDestructive(tool, input, ctx) {
     if (!this.yolo || this.yoloDestructive) return false;
     if (this.hasAgentStateWriteTarget(tool, input, ctx)) return true;
@@ -2532,25 +2855,16 @@ var DefaultPermissionPolicy = class {
     if (!command) return false;
     return isClearlyDestructiveBashCommand(command, ctx.projectRoot);
   }
-  /**
-   * Replace (or clear) the interactive prompt delegate at runtime.
-   * Used by the CLI to switch from inline prompts (REPL) to event-driven
-   * confirmation (TUI) when the run mode is determined after the policy
-   * was constructed (e.g. `--goal` auto-flipping to TUI).
-   */
   setPromptDelegate(delegate) {
     this.promptDelegate = delegate;
   }
-  /** Toggle YOLO (auto-approve) mode at runtime. */
   setYolo(enabled) {
     if (this.yolo !== enabled) this._evalCache.clear();
     this.yolo = enabled;
   }
-  /** Check whether YOLO mode is currently active. */
   getYolo() {
     return this.yolo;
   }
-  /** Read-only diagnostics for policy inspector/editor surfaces. */
   getPolicyDiagnostics() {
     return this.policyDiagnostics.map((diagnostic) => ({ ...diagnostic }));
   }
@@ -2819,7 +3133,6 @@ var DefaultPermissionPolicy = class {
       throw err;
     }
   }
-  /** Persist a deny rule — this tool+pattern pair is permanently blocked. */
   async deny(rule) {
     if (!this.loaded) await this.reload();
     if (this.policyInvalid) {
@@ -2840,335 +3153,32 @@ var DefaultPermissionPolicy = class {
       throw err;
     }
   }
-  /** Block this tool+pattern for the rest of this session (no trust file). */
   denyOnce(rule) {
     this.sessionDenied.set(`${rule.tool}::${rule.pattern}`, true);
     this._evalCache.clear();
   }
-  /** Auto-approve this tool+pattern once (no trust file). */
   allowOnce(rule) {
     this.sessionAllowed.set(`${rule.tool}::${rule.pattern}`, true);
     this._evalCache.clear();
   }
-  /**
-   * Side-effect-free permission evaluation trace. Mirrors `evaluate()`
-   * step-by-step without prompting the user, writing to trust files, or
-   * mutating session state. Returns the full ordered trace and winner.
-   */
   async explain(tool, input, ctx) {
     if (!this.loaded) await this.reload();
-    const subject = subjectForToolInput(tool.name, input, tool.subjectKey);
-    const steps = [];
-    let winnerIndex = -1;
-    const add = (rule, matched, decision, source, detail) => {
-      steps.push({ rule, matched, decision, source, detail });
-    };
-    if (this.policyInvalid) {
-      add("policy invalid", true, "deny", "deny", "trust policy is invalid; all tools are denied");
-      winnerIndex = 0;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: { permission: "deny", source: "deny", reason: "trust policy is invalid" }
-      };
-    }
-    add("policy valid", false, "auto", "default", "trust policy loaded successfully");
-    const namespaceEntry = this.findNamespaceEntry(tool.name);
-    const entry = this.policy[tool.name] ?? namespaceEntry;
-    const namespaceSource = namespaceEntry ? `wildcard entry matched (${Object.keys(this.policy).find((k) => k.includes("*") && matchGlob(k, tool.name))})` : "no namespace match";
-    const cacheKey = `${tool.name}::${subject ?? tool.name}`;
-    if (this.sessionDenied.has(cacheKey)) {
-      add(
-        "session soft deny",
-        true,
-        "deny",
-        "deny",
-        'user pressed "no" earlier in this session \u2014 blocked until reload'
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: {
-          permission: "deny",
-          source: "deny",
-          reason: "session soft deny (user pressed no)"
-        }
-      };
-    }
-    add(
-      "session soft deny",
-      false,
-      "deny",
-      "deny",
-      "no session-level soft deny for this tool+subject"
-    );
-    if (this.sessionAllowed.has(cacheKey)) {
-      add(
-        "session soft allow",
-        true,
-        "auto",
-        "trust",
-        'user pressed "yes" in current session \u2014 one-shot auto-approve (consumed)'
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: {
-          permission: "auto",
-          source: "trust",
-          reason: "session one-shot allow (user pressed yes)"
-        }
-      };
-    }
-    add(
-      "session soft allow",
-      false,
-      "auto",
-      "trust",
-      "no session-level one-shot allow for this tool+subject"
-    );
-    if (entry?.deny && subject && matchesTrust(entry.deny, subject)) {
-      add(
-        "trust deny",
-        true,
-        "deny",
-        "deny",
-        `subject "${subject}" matched a deny pattern in trust file`
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: { permission: "deny", source: "deny", reason: "matched deny pattern" }
-      };
-    }
-    add(
-      "trust deny",
-      false,
-      "deny",
-      "deny",
-      `no deny pattern matched (namespace: ${namespaceSource})`
-    );
-    if (tool.permission === "deny") {
-      add(
-        "tool default deny",
-        true,
-        "deny",
-        "default",
-        `tool "${tool.name}" has permission: deny by default`
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: { permission: "deny", source: "default", reason: "tool default deny" }
-      };
-    }
-    add(
-      "tool default deny",
-      false,
-      "deny",
-      "default",
-      `tool "${tool.name}" has permission: "${tool.permission}"`
-    );
-    if (entry?.allow && subject && matchesTrust(entry.allow, subject)) {
-      add(
-        "trust allow",
-        true,
-        "auto",
-        "trust",
-        `subject "${subject}" matched an allow pattern in trust file`
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: { permission: "auto", source: "trust", reason: "matched allow pattern" }
-      };
-    }
-    add(
-      "trust allow",
-      false,
-      "auto",
-      "trust",
-      `no allow pattern matched (namespace: ${namespaceSource})`
-    );
-    if (entry?.auto) {
-      add("trust auto", true, "auto", "trust", `trust file has auto: true for "${tool.name}"`);
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: { permission: "auto", source: "trust", reason: "trust auto" }
-      };
-    }
-    add("trust auto", false, "auto", "trust", `no auto flag for "${tool.name}" in trust file`);
-    if (!this.yolo && this.isSensitiveReadCall(tool, input)) {
-      const hasDelegate2 = this.promptDelegate !== void 0;
-      add(
-        "sensitive read",
-        true,
-        hasDelegate2 ? "confirm" : "confirm",
-        "default",
-        hasDelegate2 ? "sensitive file read detected \u2014 would prompt user for approval" : "sensitive file read detected \u2014 returns confirm (no prompt delegate)"
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: {
-          permission: "confirm",
-          source: "default",
-          riskTier: "standard",
-          reason: "sensitive file read needs explicit approval"
-        }
-      };
-    }
-    add(
-      "sensitive read",
-      false,
-      "confirm",
-      "default",
-      "not a sensitive read call (or YOLO bypasses this check)"
-    );
-    if (this.yolo) {
-      if (this.yoloBlockedAsDestructive(tool, input, ctx)) {
-        add(
-          "yolo destructive gate",
-          true,
-          "confirm",
-          "yolo_destructive",
-          "YOLO is active but this is a clearly destructive command \u2014 still asking"
-        );
-        winnerIndex = steps.length - 1;
-        return {
-          toolName: tool.name,
-          subject,
-          steps,
-          winnerIndex,
-          decision: {
-            permission: "confirm",
-            source: "yolo_destructive",
-            riskTier: "destructive",
-            reason: "destructive command needs explicit approval even in YOLO mode"
-          }
-        };
-      }
-      add(
-        "yolo",
-        true,
-        "auto",
-        "yolo",
-        "YOLO mode is active \u2014 auto-approving every non-denied call"
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: { permission: "auto", source: "yolo" }
-      };
-    }
-    add("yolo", false, "auto", "yolo", "YOLO mode is not active");
-    if (tool.name === "write" && subject) {
-      const isAgentState = isInsideAgentStateRoot(subject);
-      const hasRead = ctx.hasRead(subject) && !isAgentState;
-      add(
-        "write smart bypass",
-        hasRead,
-        "auto",
-        "context",
-        isAgentState ? `file "${subject}" is WrongStack's own state \u2014 bypass never applies, write always confirms` : hasRead ? `file "${subject}" was already read in this session \u2014 auto-approving write` : `file "${subject}" was not read in this session \u2014 bypass does not apply`
-      );
-      if (hasRead) {
-        winnerIndex = steps.length - 1;
-        return {
-          toolName: tool.name,
-          subject,
-          steps,
-          winnerIndex,
-          decision: {
-            permission: "auto",
-            source: "context",
-            reason: "file already read in this session"
-          }
-        };
-      }
-    } else {
-      add(
-        "write smart bypass",
-        false,
-        "auto",
-        "context",
-        'tool is not "write" or has no subject \u2014 bypass does not apply'
-      );
-    }
-    const hasWriteCap = hasCapability(tool, ToolCapabilities.FS_WRITE);
-    const hasShellCap = hasCapability(tool, [
-      ToolCapabilities.SHELL_ARBITRARY,
-      ToolCapabilities.SHELL_RESTRICTED,
-      ToolCapabilities.SHELL_EXEC
-    ]);
-    const hasInstallCap = hasCapability(tool, ToolCapabilities.PACKAGE_INSTALL);
-    const hasConfigCap = hasCapability(tool, ToolCapabilities.CONFIG_MUTATE);
-    const hasSubagentCap = hasCapability(tool, ToolCapabilities.SUBAGENT_SPAWN);
-    const isMutating = tool.mutating || hasWriteCap || hasShellCap || hasInstallCap || hasConfigCap || hasSubagentCap;
-    if (tool.permission === "auto" && !isMutating) {
-      add(
-        "safe default auto",
-        true,
-        "auto",
-        "default",
-        `tool "${tool.name}" has auto permission and is not mutating \u2014 safe to auto-approve`
-      );
-      winnerIndex = steps.length - 1;
-      return {
-        toolName: tool.name,
-        subject,
-        steps,
-        winnerIndex,
-        decision: { permission: "auto", source: "default" }
-      };
-    }
-    add(
-      "mutating default confirm",
-      true,
-      "confirm",
-      "default",
-      isMutating ? `tool "${tool.name}" is mutating (default auto not enough) \u2014 needs confirmation` : `tool "${tool.name}" has "${tool.permission}" permission \u2014 needs confirmation`
+    return explainPermissionTrace(
+      {
+        policy: this.policy,
+        policyInvalid: this.policyInvalid,
+        wildcardEntries: this.wildcardEntries,
+        sessionDenied: this.sessionDenied,
+        sessionAllowed: this.sessionAllowed,
+        yolo: this.yolo,
+        promptDelegatePresent: this.promptDelegate !== void 0,
+        isSensitiveReadCall: (t, inp) => this.isSensitiveReadCall(t, inp),
+        yoloBlockedAsDestructive: (t, inp, c) => this.yoloBlockedAsDestructive(t, inp, c)
+      },
+      tool,
+      input,
+      ctx
     );
-    winnerIndex = steps.length - 1;
-    const hasDelegate = this.promptDelegate !== void 0;
-    return {
-      toolName: tool.name,
-      subject,
-      steps,
-      winnerIndex,
-      decision: {
-        permission: "confirm",
-        source: "default",
-        ...hasDelegate ? { reason: "would prompt user via delegate" } : {}
-      }
-    };
   }
   findNamespaceEntry(toolName) {
     for (const { pattern, value } of this.wildcardEntries) {