auto-permission-system 3.6.0 → 3.7.8

package/README.md

@@ -89,6 +89,14 @@ A higher layer only states what it changes; absent keys keep the layer below. A
   "subagent": {
     "network": "allow"                  // "allow" | "deny" | "research-only"
   },
+  "mcp": {                              // Advanced Secure MCP gate tuning (ADR-032)
+    "allowTools": ["mcp__diffusion_studio__context"],  // exact names that never ask
+    "allowPrefixes": ["mcp__ticktick__get_"],          // name prefixes that never ask
+    "askTools": [],                    // exact names that always ask
+    "trustAnnotations": false,         // true = a server's readOnlyHint allows without asking
+    "allowSimpleUpdates": true,        // narrow field updates skip the ask
+    "askThreshold": 30                 // risk score at which a call asks (lower = stricter)
+  },
   "commands": {
     "ask": ["printenv", "env", "/proc/*/environ"]  // bash: ask before these (they can print env tokens)
   }
@@ -124,7 +132,7 @@ Never asked about: the project itself, your `allowWrite` roots, pi's own package
 
 ### Ask-tier prompt
 
-`no — block` is pre-selected, so Enter alone blocks. **Network (domain) asks are the exception** (ADR-024): the countdown default is `Allow once` — the footer reads `Default: Yes, just this once (15s)` — so an unanswered countdown counts as allow-once for that bash command, while Enter and Esc still block/deny. Once you press ↑/↓ the `Default:` line disappears and the 15s activity timer restarts (ADR-031). Besides `yes — this once` and the persistent `always` options there is `yes — for this session` (this file, its folder, or this domain), kept in memory until the session ends and never saved (ADR-010). A bash command that reaches a domain outside `allowedDomains` gets the same prompt (ADR-023); because the sandbox proxy asks per connection, `yes — this once` covers that command's connections to the host, and a remembered host is written to `overrides.allowDomains` and applies immediately. Hosts in `deniedDomains`, or with `strictAllowlist: true`, are blocked without a prompt. Prompts are shown one at a time: the extension serializes them, because pi's selector is a singleton and two overlapping prompts can orphan each other and hang the waiting connection. For a bash write that the sandbox refused after the command already ran, `yes — this once` re-runs the command once with that folder allowed for the one invocation only (never saved), and `denyWrite` still wins. The refusal is read from the command's own error text — `EPERM` / `Operation not permitted` on macOS, `EROFS` / `Read-only file system` on Linux (ADR-022) — so a Linux EROFS gets the same prompt instead of a silent read-only failure; a refused write is never mistaken for an outside-project read.
+`no — block` is pre-selected, so Enter alone blocks. **Network (domain) asks are the exception** (ADR-024): the countdown default is `Allow once` — the footer reads `Default: Yes, just this once (15s)` — so an unanswered countdown counts as allow-once for that bash command, while Enter and Esc still block/deny. Once you press ↑/↓ the `Default:` line disappears and the 15s activity timer restarts (ADR-031). The prompt is keyboard-only (ADR-036): ↑/↓ move the highlight, Enter selects, Esc cancels — a mouse click or wheel over the prompt does nothing. Besides `yes — this once` and the persistent `always` options there is `yes — for this session` (this file, its folder, or this domain), kept in memory until the session ends and never saved (ADR-010). A bash command that reaches a domain outside `allowedDomains` gets the same prompt (ADR-023); because the sandbox proxy asks per connection, `yes — this once` covers that command's connections to the host, and a remembered host is written to `overrides.allowDomains` and applies immediately. Hosts in `deniedDomains`, or with `strictAllowlist: true`, are blocked without a prompt. Prompts are shown one at a time: the extension serializes them, because pi's selector is a singleton and two overlapping prompts can orphan each other and hang the waiting connection. For a bash write that the sandbox refused after the command already ran, `yes — this once` re-runs the command once with that folder allowed for the one invocation only (never saved), and `denyWrite` still wins. The refusal is read from the command's own error text — `EPERM` / `Operation not permitted` on macOS, `EROFS` / `Read-only file system` on Linux (ADR-022) — so a Linux EROFS gets the same prompt instead of a silent read-only failure; a refused write is never mistaken for an outside-project read.
 
 Every prompt waits **10 seconds** by default. For file reads and writes, no answer resolves to the safe default: **block / deny**. For a network ask, no answer resolves to **allow once** (ADR-024); Esc still denies.
 
@@ -139,7 +147,7 @@ An entry without `/` or `~` (`.env`, `*.key`) is a file name. pi's own tools (La
 - **`default`** (shipped) — rules only: sandbox.json paths, domains, and commands. Nothing inspects file contents.
 - **`advanced-secure`** (recommended) — adds secret/credential detection:
   - **File reads:** a filename that looks like a credential store asks before the read.
-  - **MCP calls:** `mcp__<server>__<tool>` calls are classified; a risky (mutating/destructive) call asks before it runs.
+  - **MCP calls:** `mcp__<server>__<tool>` calls are classified; a risky call asks before it runs. The gate ignores the server namespace, reads the operation from the head verb of the tool name (or the first verb of the description), and asks for destructive names, mutating names (`update_*`, `create_*`, `run_*`, `evaluate_*`), and destructive arguments (SQL `DELETE`, `rm -rf`, `*` targets, HTTP `DELETE`, production targets). A documented tool with an unclassified name (`context`, `capture`, `logs`) does not ask; a tool with no description counts as opaque and does. Tune it under `mcp` in `sandbox.json` — `allowTools` / `allowPrefixes` skip asks, `askTools` forces them, `trustAnnotations` trusts a server's `readOnlyHint`, `askThreshold` moves the score line (ADR-032).
   - **Tool/command/file output:** before any output reaches the model, a secret-like hit shows `⚠ Sensitive information detected`, the file, and each detected line as `lineNo: text`, and the question **Should the AI be allowed to see it?** with two choices — **No, keep private** or **Yes, allow**. A bare `key` counts only when the value looks machine-generated: `key=<random>` asks, while `key=value`, `key=subagent.network`, and code such as `const key = x` stay clean. No, keep private withholds the output and tells the model plainly that the output was withheld because it may contain sensitive information, so the model does not mistake it for a failure or an empty result. Esc or timeout keeps it private.
 
 Detection can only **add** asks or blocks; it never loosens a rule. The mode is layered like every other key: an untrusted project may opt *in* to `advanced-secure`, but only a trusted project (or the global file) may turn it off.

package/extensions/guard.ts

@@ -11,7 +11,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isToolCallEventType, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { filterGrepOutput, policyFileError, forgetProjectTrust, isProjectFileDeclined, recordProjectDeclined, recordProjectTrust } from "../src/core/index";
-import { classifyFilename, evaluateMcpCall, type JsonSchemaLike, type McpToolAnnotations } from "../src/detect/index";
+import { classifyFilename, evaluateMcpCall, type JsonSchemaLike, type McpPolicy, type McpToolAnnotations } from "../src/detect/index";
 import { collectExposure } from "../src/l2-guard/exposure";
 import { askExposure, askMain, withheldNotice } from "../src/ui/ask-flow";
 import { loadPolicy, projectPolicyPath, projectTrusted, setPiDeclinedTrust, untrustedProjectChanges, bullets, TRUST_STORE } from "../src/l2-guard/policy";
@@ -77,6 +77,7 @@ async function detectMcpAsk(
 	toolName: string,
 	input: Record<string, unknown>,
 	ctx: UICtx,
+	mcpPolicy?: McpPolicy,
 ): Promise<{ block: true; reason: string } | null> {
 	const info = pi.getAllTools().find((t) => t.name === toolName);
 	const result = evaluateMcpCall({
@@ -87,6 +88,7 @@ async function detectMcpAsk(
 			annotations: /* SAFETY: pi's ToolAnnotations mirrors the MCP hints McpToolAnnotations names. */ info?.annotations as McpToolAnnotations | undefined,
 		},
 		call: { name: toolName, arguments: input },
+		policy: mcpPolicy,
 	});
 	if (result.decision !== "ask") return null;
 	return askDetection(ctx, "tool", toolName, result.summary);
@@ -101,10 +103,6 @@ export default function (pi: ExtensionAPI) {
 		active = policyEnabled && !runtimeYolo;
 	};
 
-	// `--yolo` and the `/permission-mode` toggle both arrive on pi's process-wide
-	// bus; `sandbox.ts` is the only extension that registers the CLI flags and
-	// broadcasts the state (ADR-020). The entrypoints share no memory, so this is
-	// the only channel that reaches Layer 2.
 	onYolo(pi.events, (enabled) => {
 		runtimeYolo = enabled;
 		applyActive();
@@ -112,8 +110,6 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", (_event, ctx) => {
-		// A policy file that does not parse is skipped and the defaults apply.
-		// Say so loudly: otherwise one trailing comma silently disables the whole file.
 		for (const p of [`${getAgentDir()}/extensions/sandbox.json`, `${ctx.cwd}/.pi/sandbox.json`]) {
 			const err = policyFileError(p);
 			if (!err) continue;
@@ -151,14 +147,9 @@ export default function (pi: ExtensionAPI) {
 		if (!active) return;
 		const policy = loadPolicy(ctx.cwd);
 
-		// Capture the program id (binary for bash, MCP server for mcp__ tools) so the
-		// Advanced Secure output gate can label the prompt and honor a session grant
-		// keyed by that program. Falls back to the tool name when nothing else fits.
 		const programId = programIdForToolCall(event.toolName, event.input);
 		if (event.toolCallId && programId) programIdByCallId.set(event.toolCallId, programId);
 
-		// --- Path-based gates (with ask-tier prompt) ---
-		// One gate for every read: the read policy first, then the project boundary.
 		const gateRead = async (rawPath: string, tool: string) => {
 			const abs = canonicalize(rawPath, ctx.cwd);
 			let reason = isDeniedRead(rawPath, ctx.cwd, policy);
@@ -190,10 +181,6 @@ export default function (pi: ExtensionAPI) {
 				}
 			}
 		}
-		// Read-only search tools. grep returns file contents and runs ripgrep in
-		// process, so neither the bash sandbox nor the read gate saw it before.
-		// Gate the search root here; tool_result below drops output lines from
-		// denied files beneath the root.
 		const searchRoot = isToolCallEventType("grep", event) || isToolCallEventType("find", event) || isToolCallEventType("ls", event)
 			? (event.input.path ?? ".")
 			: null;
@@ -218,7 +205,6 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 
-		// --- URL/domain gates (best-effort by tool name; tools are extension-defined) ---
 		const input = event.input as Record<string, unknown> | undefined;
 		const collectUrls = (): string[] => {
 			if (!input) return [];
@@ -234,8 +220,6 @@ export default function (pi: ExtensionAPI) {
 			const saReason = subagentNetworkBlock(ctx as { hasUI?: boolean; sessionManager?: unknown }, policy);
 			if (saReason) return { block: true, reason: saReason };
 			for (const u of collectUrls()) {
-				// deniedDomains is the hard-deny tier: the bash proxy refuses it before
-				// any ask, so Layer 2 must not offer to override it either.
 				const denied = deniedUrlReason(u, policy);
 				if (denied) {
 					audit({ layer: 2, tool: event.toolName, subject: u, reason: denied, decision: "no", note: "denied-domain", cwd: ctx.cwd });
@@ -245,7 +229,6 @@ export default function (pi: ExtensionAPI) {
 				if (!reason) continue;
 				const host = hostnameOf(u) ?? u;
 				const result = await askOrBlock(/* SAFETY: pi's ctx carries cwd/UI at runtime. */ ctx as unknown as UICtx, { layer: 2, tool: event.toolName, subject: u, reason, overrideKind: "allowDomains", overrideValue: host }, null, (kind, value) => {
-					// Layer 1's proxy does not re-read the file: apply the remembered host live (ADR-023).
 					if (kind === "allowDomains") emitDomainGrant(pi.events, value);
 				});
 				if (result) return result;
@@ -255,22 +238,14 @@ export default function (pi: ExtensionAPI) {
 		if (event.toolName === "web_search") {
 			const saReason = subagentNetworkBlock(ctx as { hasUI?: boolean; sessionManager?: unknown }, policy);
 			if (saReason) return { block: true, reason: saReason };
-			// web_search itself goes to the search provider (out of scope for v1
-			// allowlist). The follow-on fetch_content for individual results is
-			// the catchable surface.
 		}
 
-		// Advanced Secure (ADR-018): classify MCP tool calls before they run.
 		if (policy.mode === "advanced-secure" && event.toolName.startsWith("mcp__")) {
-			const det = await detectMcpAsk(pi, event.toolName, (event.input ?? {}) as Record<string, unknown>, /* SAFETY: pi's ctx carries cwd/UI at runtime. */ ctx as unknown as UICtx);
+			const det = await detectMcpAsk(pi, event.toolName, (event.input ?? {}) as Record<string, unknown>, /* SAFETY: pi's ctx carries cwd/UI at runtime. */ ctx as unknown as UICtx, policy.mcp);
 			if (det) return det;
 		}
 	});
 
-	// grep output filter. A root that passed the gate can still contain denied
-	// files (`.env`, `*.pem`, `~/.ssh` under a search of `~`). Approving the
-	// root does not approve the denied files beneath it. Runs before the
-	// result reaches the model.
 	pi.on("tool_result", (event, ctx) => {
 		if (!active || event.toolName !== "grep" || event.isError) return;
 		const input = event.input as { path?: string } | undefined;
@@ -282,7 +257,6 @@ export default function (pi: ExtensionAPI) {
 		} catch {
 			return;
 		}
-		// A single-file search prints only the basename; its root gate already decided.
 		if (!rootIsDir) return;
 		let removedLines = 0;
 		const removedFiles = new Set<string>();
@@ -299,10 +273,6 @@ export default function (pi: ExtensionAPI) {
 		return { content };
 	});
 
-	// Advanced Secure (ADR-018): before any tool output reaches the model, ask
-	// the user when it looks like it carries a secret. Block withholds it and
-	// tells the model plainly, so the model does not read it as a failure or an
-	// empty result; Allow send passes the real values through.
 	pi.on("tool_result", async (event, ctx) => {
 		if (!active || event.isError) return;
 		const policy = loadPolicy(ctx.cwd);
@@ -415,6 +385,19 @@ export default function (pi: ExtensionAPI) {
 				`  allowWrite:   ${(overrides.allowWrite ?? []).join(", ") || "(none)"}`,
 				`  allowDomains: ${(overrides.allowDomains ?? []).join(", ") || "(none)"}`,
 			];
+			if (policy.mode === "advanced-secure") {
+				const mcp = policy.mcp ?? {};
+				lines.push(
+					"",
+					"Advanced Secure (MCP gate, ADR-032):",
+					`  allowTools:       ${(mcp.allowTools ?? []).join(", ") || "(none)"}`,
+					`  allowPrefixes:    ${(mcp.allowPrefixes ?? []).join(", ") || "(none)"}`,
+					`  askTools:         ${(mcp.askTools ?? []).join(", ") || "(none)"}`,
+					`  trustAnnotations: ${mcp.trustAnnotations === true}`,
+					`  allowSimpleUpdates: ${mcp.allowSimpleUpdates !== false}`,
+					`  askThreshold:     ${mcp.askThreshold ?? 30}`,
+				);
+			}
 			try {
 				const tail = readFileSync(AUDIT_PATH, "utf-8").trim().split("\n").slice(-10);
 				if (tail.length && tail[0]) {
@@ -422,7 +405,6 @@ export default function (pi: ExtensionAPI) {
 					for (const l of tail) lines.push(`  ${l}`);
 				}
 			} catch {
-				/* no audit log yet */
 			}
 			ctx.ui.notify(lines.join("\n"), "info");
 		},

package/extensions/permission-mode.ts

@@ -84,9 +84,17 @@ async function pickMode(pi: ExtensionAPI, ctx: ExtensionContext, yolo: { active:
 		MODES.map((m) => m.label),
 		{ timeout: 120_000 },
 	);
-	if (picked === undefined) return; // Esc / timeout → keep the current mode
+	if (picked === undefined) return;
 	const next = MODES.find((m) => m.label === picked)?.value ?? current;
 	if (next === current) {
+		if (next === "yolo" && !yolo.active) {
+			yolo.active = true;
+			emitYolo(pi.events, true);
+			audit({ layer: 0, event: "permission-mode", mode: "yolo", cwd: ctx.cwd, note: "runtime-sync" });
+			renderSandboxChip(ctx);
+			ctx.ui.notify("⚠️  YOLO — all security layers disabled for this session.", "warning");
+			return;
+		}
 		ctx.ui.notify(`Permission mode is already ${modeLabel(next)}.`, "info");
 		return;
 	}
@@ -98,8 +106,6 @@ async function pickMode(pi: ExtensionAPI, ctx: ExtensionContext, yolo: { active:
 		return;
 	}
 	yolo.active = next === "yolo";
-	// Layers off/on in place, without a restart. `--yolo` keeps its own flag
-	// value; this only flips the runtime state.
 	emitYolo(pi.events, yolo.active);
 	audit({ layer: 0, event: "permission-mode", mode: next, cwd: ctx.cwd });
 	renderSandboxChip(ctx);
@@ -109,8 +115,6 @@ async function pickMode(pi: ExtensionAPI, ctx: ExtensionContext, yolo: { active:
 
 export default function (pi: ExtensionAPI) {
 	const yolo = { active: false };
-	// `sandbox.ts` owns the CLI flags and broadcasts the startup state, so the
-	// menu shows the truth even when `--yolo` was passed for this run only.
 	onYolo(pi.events, (enabled) => {
 		yolo.active = enabled;
 	});

package/extensions/sandbox.ts

@@ -30,21 +30,17 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createBashTool } from "@earendil-works/pi-coding-agent";
-import { createSandboxedBashOps } from "../src/l1-sandbox/bash-ops";
+import { clearFilesystemSessionGrants, createSandboxedBashOps, filesystemSessionGrantSummary } from "../src/l1-sandbox/bash-ops";
 import { applyNetworkGrant, initSandbox, persistLayer1Override, reloadSandbox, resetSandbox, writeNetworkOverride } from "../src/l1-sandbox/manager";
 import { clearNetworkSessionGrants, type NetworkAskCtx, type NetworkAskDeps } from "../src/l1-sandbox/network-ask";
-import { loadConfig, setPiDeclinedTrust } from "../src/l1-sandbox/config";
+import { loadConfig, projectTrusted, setPiDeclinedTrust } from "../src/l1-sandbox/config";
 import { audit } from "../src/shared/audit";
 import { onDomainGrant } from "../src/shared/network-grants";
 import { emitYolo, onYolo, registerYoloFlags, yoloFromFlags, YOLO_STATUS } from "../src/shared/yolo";
 
 export default function (pi: ExtensionAPI) {
-	// pi scopes flags per extension (ADR-020); registering here makes
-	// `yoloFromFlags(pi)` below read the real CLI value.
 	registerYoloFlags(pi);
 
-	// A domain remembered from the Layer 2 guard prompt is written to
-	// sandbox.json by the guard; apply it to the running proxy here (ADR-023).
 	onDomainGrant(pi.events, applyNetworkGrant);
 
 	const localCwd = process.cwd();
@@ -68,10 +64,7 @@ export default function (pi: ExtensionAPI) {
 		persist: (host, scope) => writeNetworkOverride(cwd, host, scope),
 		applyLive: applyNetworkGrant,
 		audit,
-		// Lazy getters so each proxy ask reads the live trust state and the most
-		// recent bash command. Without these, the values captured at initSandbox()
-		// would be stale.
-		get projectTrusted() { return latestCtx?.isProjectTrusted?.(); },
+		get projectTrusted() { return projectTrusted(cwd); },
 		get command() { return latestBashCommand; },
 	});
 
@@ -119,17 +112,12 @@ export default function (pi: ExtensionAPI) {
 		}
 	};
 
-	// Runtime YOLO from `/permission-mode` (ADR-020): stop or restart the
-	// sandbox in place, without a session restart.
 	onYolo(pi.events, (enabled) => {
-		// The startup broadcast originates here; ignore our own echo.
 		if (enabled === runtimeYolo) return;
 		runtimeYolo = enabled;
 		const ctx = latestCtx;
 		if (!ctx) return;
 		if (!enabled) {
-			// Gate bash until the sandbox is back up, so turning YOLO off cannot
-			// leave a window where a command runs unfenced (ADR-020 follow-up).
 			sandboxStarting = startSandbox(ctx).finally(() => {
 				sandboxStarting = null;
 			});
@@ -162,7 +150,6 @@ export default function (pi: ExtensionAPI) {
 		return { operations: createSandboxedBashOps({ ctx: activeCtx, onAlways: persistAndReload, onAlwaysRead: persistAndReloadRead }) };
 	});
 
-	// Capture the latest bash command so the network ask body can show it.
 	pi.on("tool_call", (event, _ctx) => {
 		if (event.toolName === "bash") {
 			const input = event.input as { command?: string };
@@ -174,10 +161,9 @@ export default function (pi: ExtensionAPI) {
 		latestCtx = ctx;
 		activeCtx = /* SAFETY: pi's runtime ctx carries cwd/hasUI/ui; the local type only names the fields we use. */ ctx as unknown as typeof activeCtx;
 		clearNetworkSessionGrants();
+		clearFilesystemSessionGrants();
 		setPiDeclinedTrust((ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted?.() === false);
 		runtimeYolo = yoloFromFlags(pi) || loadConfig(ctx.cwd).mode === "yolo";
-		// Broadcast before any await: guard.ts consumes this on the same bus to
-		// learn YOLO is on (ADR-020).
 		emitYolo(pi.events, runtimeYolo);
 
 		if (runtimeYolo) {
@@ -232,6 +218,7 @@ export default function (pi: ExtensionAPI) {
 				`  Allow Write: ${config.filesystem?.allowWrite?.join(", ") || "(none)"}`,
 				`  Deny Write: ${config.filesystem?.denyWrite?.join(", ") || "(none)"}`,
 				`  Outside project reads: ${config.filesystem?.outsideProject?.read ?? "allow"}`,
+				`  Session grants: ${filesystemSessionGrantSummary() || "(none)"}`,
 			];
 			ctx.ui.notify(lines.join("\n"), "info");
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-permission-system",
-  "version": "3.6.0",
+  "version": "3.7.8",
   "description": "Security sandbox, permission system and tool guard for the Pi coding agent (pi): enforce filesystem allow/deny lists and network domain allowlists on read, write, edit, bash, grep, find, ls, fetch_content and web_search, with interactive ask prompts, secret detection and an audit log.",
   "type": "module",
   "author": "Navin Kumar",

package/sandbox.example.json

@@ -119,6 +119,16 @@
     "network": "allow"
   },
 
+  "_comment_mcp": "Advanced Secure only. Tune the MCP tool-call gate (ADR-032). allowTools = exact tool names that never ask; allowPrefixes = name prefixes that never ask (e.g. 'mcp__ticktick__get_'); askTools = tool names that always ask; trustAnnotations = a server's readOnlyHint allows the call without asking; allowSimpleUpdates = narrow field updates skip the ask (default true); askThreshold = risk score at which calls ask (default 30, lower = stricter). Detected destructive calls always ask, unless an allowTools/allowPrefixes entry covers them (an explicit override). Unclassified names with a real description start at 25; a tool with no description counts as opaque and still asks. An untrusted project file may only tighten: it may add askTools, lower askThreshold, and turn allowSimpleUpdates/trustAnnotations off; allow lists need /security trust.",
+  "mcp": {
+    "allowTools": [],
+    "allowPrefixes": [],
+    "askTools": [],
+    "trustAnnotations": false,
+    "allowSimpleUpdates": true,
+    "askThreshold": 30
+  },
+
   "_comment_overrides": "Additive overrides written by ask-tier prompts. You can also edit by hand. These are merged on top of the main policy.",
   "overrides": {
     "allowRead": [],

package/skills/auto-permission-system/SKILL.md

@@ -50,6 +50,14 @@ A higher layer only states what it changes; absent keys keep the layer below. A
     "denyWrite": [".env", "*.pem"]   // Layer 1 + 2: always blocked
   },
   "subagent": { "network": "allow" },
+  "mcp": {                           // Advanced Secure MCP gate tuning (ADR-032)
+    "allowTools": ["mcp__diffusion_studio__context"],  // exact names that never ask
+    "allowPrefixes": ["mcp__ticktick__get_"],          // name prefixes that never ask
+    "askTools": [],                   // exact names that always ask
+    "trustAnnotations": false,        // true = a server's readOnlyHint allows without asking
+    "allowSimpleUpdates": true,       // narrow field updates skip the ask
+    "askThreshold": 30                // risk score at which a call asks (lower = stricter)
+  },
   "commands": {
     "ask": ["printenv", "env", "/proc/*/environ"]  // bash: ask before these (they can print env tokens)
   },
@@ -88,7 +96,7 @@ A **network** (domain) ask keeps the same rows, but the *unanswered* default fli
 
 For a Layer 1 bash **write** blocked after the command already ran, `yes — this once` re-runs the command once with the offending path's parent folder allowed for that invocation only (never saved); the same folder is not offered again within that invocation, and `denyWrite` still wins over the grant. The block is recognized from the error output either way it is reported — `EPERM`/`Operation not permitted` on macOS, `EROFS`/`Read-only file system` on Linux (ADR-022) — and a refused write is never offered as a read grant. If the output never names the operand, there is nothing to attribute and no prompt, so the command is simply refused.
 
-Every prompt waits **15 seconds** by default and shows it live as `Default: … (Ns)` under the body. For file reads/writes no answer means the safe default: **block / deny**, and Esc blocks. For a network ask, an unanswered countdown means **allow once** (Esc still denies) — ADR-024. In the TUI the `Default:` line disappears as soon as you press ↑/↓ and the timer restarts, so the hint never competes with an active choice (ADR-031).
+Every prompt waits **15 seconds** by default and shows it live as `Default: … (Ns)` under the body. For file reads/writes no answer means the safe default: **block / deny**, and Esc blocks. For a network ask, an unanswered countdown means **allow once** (Esc still denies) — ADR-024. In the TUI the `Default:` line disappears as soon as you press ↑/↓ and the timer restarts, so the hint never competes with an active choice (ADR-031). The prompt is keyboard-only (ADR-036): ↑/↓ move the highlight, Enter selects, Esc cancels — a mouse click or wheel over the prompt does nothing.
 
 The same options apply to a bash command whose network request reaches a host outside `allowedDomains` (ADR-023), with the countdown default and live footer from ADR-024/ADR-031: `No` / `Yes, just this once` / `Yes, all in group for this session` / `Yes, always…`, and an untouched countdown counts as allow-once. Because the sandbox proxy asks per connection, `Allow (default)` covers that bash command rather than one connection — redirects and parallel connections to the same host do not re-prompt. A host in `deniedDomains`, or `network.strictAllowlist: true`, is blocked outright: the prompt never appears. A remembered host is written to `overrides.allowDomains` and takes effect immediately, so the waiting request completes without a retry. Prompts from both layers are serialized through one queue (`src/ui/ask-flow.ts`), so two unknown hosts cannot replace each other's selector and hang the waiting connection.
 
@@ -103,7 +111,7 @@ The same options apply to a bash command whose network request reaches a host ou
 - **`default`** (shipped) — rules only. No content inspection.
 - **`advanced-secure`** (recommended) — adds secret/credential detection, and **only adds asks or blocks** (never loosens):
   - file reads whose name looks like a credential store ask before the read;
-  - risky `mcp__<server>__<tool>` calls ask before they run;
+  - risky `mcp__<server>__<tool>` calls ask before they run. The gate ignores the `mcp__<server>__` namespace, takes the operation from the head verb of the name (or the first verb of the description), and asks for destructive names, mutating names (`update_*`, `create_*`, `run_*`, `evaluate_*`), and destructive arguments (SQL `DELETE`/`UPDATE` without `WHERE`, `rm -rf`, `*` targets, HTTP `DELETE`, production targets). A documented tool with an unclassified name (`context`, `capture`, `logs`) does not ask; a tool with **no description** counts as opaque and does. Tune it under `mcp` in `sandbox.json` (ADR-032): `allowTools` / `allowPrefixes` skip asks, `askTools` forces them, `trustAnnotations` lets a server's `readOnlyHint` allow the call, `askThreshold` moves the score line (default 30). An untrusted project file may only tighten it (add `askTools`, lower `askThreshold`, turn `allowSimpleUpdates`/`trustAnnotations` off).
   - before any tool/command/file output reaches the model, a secret-like hit shows the file and each detected line as `lineNo: text`, with two choices — **No, keep private** or **Yes, allow**. No, keep private withholds the output and tells the model it was withheld because it may contain sensitive information (not a failure, not an empty result).
 
 Switch with `/permission-mode`; all three modes are saved to the global `sandbox.json` and reflected in the footer's sandbox chip (`Sandbox: 🧠 N domains, M paths` for advanced-secure, `Sandbox: 🔒 …` for default). An untrusted project may move the mode **up** (toward stricter), never down: it cannot turn on YOLO or turn off Advanced Secure. The third choice, **YOLO**, disables every layer; the chip reads `⚠️ YOLO — all security layers disabled` until you pick another mode (ADR-020).
@@ -143,6 +151,13 @@ Without restarting, `/permission-mode` → **YOLO** turns every layer off in one
 
 **Allow writes to a new path** — same pattern with `allowWrite`.
 
+**Allow an MCP tool** — in Advanced Secure mode, a `mcp__<server>__<tool>` call that keeps asking can be allowed without weakening anything else:
+```json
+// ~/.pi/agent/extensions/sandbox.json  (global)
+{ "mcp": { "allowPrefixes": ["mcp__ticktick__get_"], "allowTools": ["mcp__diffusion_studio__export"] } }
+```
+`allowTools` matches exact names, `allowPrefixes` matches the start (case-insensitive). Detected destructive calls still ask unless an exact `allowTools` entry names them. `"trustAnnotations": true` lets servers that mark a tool `readOnlyHint` skip the ask, and a project's `mcp` file may only tighten (add `askTools`, lower `askThreshold`, turn `allowSimpleUpdates`/`trustAnnotations` off) until you trust it.
+
 **View recent blocks** — run `/security` and read the audit section, or:
 ```bash
 tail -20 ~/.pi/agent/audit.log | python3 -m json.tool

package/src/core/grep-filter.ts

@@ -3,7 +3,7 @@
  * `path-N- text` for a context line. The separator is the same on both sides
  * of the line number, which keeps paths containing `-` or `:` parseable.
  */
-const GREP_LINE = /^(.+?)([:-])(\d+)\2 /;
+const GREP_LINE_RE = /^(.+?)([:-])(\d+)\2 /;
 
 export interface GrepFilterResult {
 	text: string;
@@ -20,26 +20,26 @@ export interface GrepFilterResult {
  * per path.
  */
 export function filterGrepOutput(text: string, isDenied: (printedPath: string) => boolean): GrepFilterResult {
-	const cache = new Map<string, boolean>();
+	const deniedByPath = new Map<string, boolean>();
 	const removedFiles = new Set<string>();
 	let removedLines = 0;
-	const kept: string[] = [];
+	const keptLines: string[] = [];
 	for (const line of text.split("\n")) {
-		const m = GREP_LINE.exec(line);
-		if (m) {
-			const file = m[1];
-			let denied = cache.get(file);
+		const match = GREP_LINE_RE.exec(line);
+		if (match) {
+			const printedPath = match[1];
+			let denied = deniedByPath.get(printedPath);
 			if (denied === undefined) {
-				denied = isDenied(file);
-				cache.set(file, denied);
+				denied = isDenied(printedPath);
+				deniedByPath.set(printedPath, denied);
 			}
 			if (denied) {
 				removedLines++;
-				removedFiles.add(file);
+				removedFiles.add(printedPath);
 				continue;
 			}
 		}
-		kept.push(line);
+		keptLines.push(line);
 	}
-	return { text: kept.join("\n"), removedLines, removedFiles: [...removedFiles] };
+	return { text: keptLines.join("\n"), removedLines, removedFiles: [...removedFiles] };
 }

package/src/core/index.ts

@@ -5,13 +5,16 @@
 export * from "./policy/defaults";
 export * from "./policy/domains";
 export * from "./policy/default-file";
-export * from "./policy/files";
+export * from "./policy/policy-file";
 export * from "./policy/merge";
 export * from "./policy/mode";
+export * from "./policy/overrides";
+export * from "./policy/paths";
 export * from "./policy/patterns";
 export * from "./policy/classify";
 export * from "./policy/commands";
 export * from "./policy/fence";
+export * from "./policy/subagent";
 export * from "./grep-filter";
 export * from "./trust";
 export * from "./user-named";

package/src/core/policy/classify.ts

@@ -1,6 +1,18 @@
+/**
+ * The filesystem slice both layers read, plus the outside-project boundary
+ * (ADR-012) it is enforced through. Pure: no pi, no OS side effects.
+ */
+
 import { matchesPolicyPattern } from "./patterns";
 
-/** The filesystem slice both layers read, with the Layer-2-only fields. */
+/** Erasable enum for `filesystem.outsideProject.read`. */
+export const ReadPosture = {
+	Allow: "allow",
+	Ask: "ask",
+	Deny: "deny",
+} as const;
+export type ReadPosture = (typeof ReadPosture)[keyof typeof ReadPosture];
+
 export interface FilesystemPolicy {
 	denyRead: readonly string[];
 	allowWrite: readonly string[];
@@ -8,23 +20,23 @@ export interface FilesystemPolicy {
 	allowRead?: readonly string[];
 	/** Paths that prompt on read instead of being hard-denied (ADR-019). */
 	askRead?: readonly string[];
-	/** Reads outside the project: "allow" (default), "ask" or "deny" (ADR-012). */
-	outsideProject?: { read?: "allow" | "ask" | "deny"; allowRead?: string[] };
+	/** Reads outside the project: `allow` (default), `ask` or `deny` (ADR-012). */
+	outsideProject?: { read?: ReadPosture; allowRead?: string[] };
 }
 
-export function outsideProjectMode(fs: FilesystemPolicy): "allow" | "ask" | "deny" {
-	return fs.outsideProject?.read ?? "allow";
+export function outsideProjectMode(filesystem: FilesystemPolicy): ReadPosture {
+	return filesystem.outsideProject?.read ?? ReadPosture.Allow;
 }
 
 /**
  * Whether `absPath` is an outside-the-project read the policy wants to gate:
  * outside cwd, not under an allowWrite / allowRead / outsideProject.allowRead
- * root, and mode !== "allow". Pure; mirrors Layer 2's outsideProjectReason for
+ * root, and mode !== `allow`. Pure; mirrors Layer 2's outsideProjectReason for
  * callers (and tests) that cannot import security-guard.ts.
  */
-export function outsideProjectReadDenied(absPath: string, cwd: string, home: string, fs: FilesystemPolicy): boolean {
-	if (outsideProjectMode(fs) === "allow") return false;
+export function outsideProjectReadDenied(absPath: string, cwd: string, home: string, filesystem: FilesystemPolicy): boolean {
+	if (outsideProjectMode(filesystem) === ReadPosture.Allow) return false;
 	if (absPath === cwd || absPath.startsWith(`${cwd}/`)) return false;
-	const allowed = [...fs.allowWrite, ...(fs.allowRead ?? []), ...(fs.outsideProject?.allowRead ?? [])];
-	return !allowed.some((pat) => matchesPolicyPattern(absPath, pat, cwd, home));
+	const allowed = [...filesystem.allowWrite, ...(filesystem.allowRead ?? []), ...(filesystem.outsideProject?.allowRead ?? [])];
+	return !allowed.some((pattern) => matchesPolicyPattern(absPath, pattern, cwd, home));
 }

package/src/core/policy/commands.ts

@@ -1,19 +1,21 @@
-/** Commands/paths that can print secrets and must ask first (ADR-017). Pure. */
+/**
+ * Commands/paths that can print secrets and must ask first (ADR-017). Pure.
+ */
 
 import { resolve } from "node:path";
 import { shellSegments, shellTokens } from "./fence";
 import { matchesPolicyPattern, normalizeAbs } from "./patterns";
 
 /** Expand a leading `~`, then resolve relative to cwd. Returns null for non-paths. */
-function asAbsolute(token: string, cwd: string, home: string): string | null {
-	const t = token.trim();
-	if (!t || t.startsWith("-")) return null;
-	let p = t;
-	if (p === "~") p = home;
-	else if (p.startsWith("~/")) p = `${home}/${p.slice(2)}`;
-	else if (!p.startsWith("/") && !p.startsWith("./") && !p.startsWith("../") && !p.includes("/")) return null;
-	const abs = p.startsWith("/") ? p : resolve(cwd, p);
-	return normalizeAbs(abs);
+function asAbsolutePath(rawToken: string, cwd: string, home: string): string | null {
+	const token = rawToken.trim();
+	if (!token || token.startsWith("-")) return null;
+	let path = token;
+	if (path === "~") path = home;
+	else if (path.startsWith("~/")) path = `${home}/${path.slice(2)}`;
+	else if (!path.startsWith("/") && !path.startsWith("./") && !path.startsWith("../") && !path.includes("/")) return null;
+	const absolute = path.startsWith("/") ? path : resolve(cwd, path);
+	return normalizeAbs(absolute);
 }
 
 /**
@@ -22,18 +24,18 @@ function asAbsolute(token: string, cwd: string, home: string): string | null {
  * path token in the command, so a read of the per-process environ file is
  * caught whatever command performs it.
  */
-export function matchedAskCommands(command: string, ask: readonly string[], cwd: string, home: string): string[] {
+export function matchedAskCommands(command: string, askEntries: readonly string[], cwd: string, home: string): string[] {
 	const found = new Set<string>();
-	if (!ask.length) return [];
+	if (!askEntries.length) return [];
 	for (const segment of shellSegments(command)) {
 		const tokens = shellTokens(segment);
 		const head = (tokens[0] ?? "").split("/").pop() ?? "";
-		for (const entry of ask) {
+		for (const entry of askEntries) {
 			if (!entry) continue;
 			if (entry.includes("/") || entry.startsWith("~")) {
 				for (const raw of tokens.slice(1)) {
-					const abs = asAbsolute(raw, cwd, home);
-					if (abs && matchesPolicyPattern(abs, entry, cwd, home)) found.add(`${head} ${raw}`.trim());
+					const absolute = asAbsolutePath(raw, cwd, home);
+					if (absolute && matchesPolicyPattern(absolute, entry, cwd, home)) found.add(`${head} ${raw}`.trim());
 				}
 			} else if (head === entry) {
 				found.add(entry);

package/src/core/policy/default-file.ts

@@ -4,8 +4,8 @@
  * global/project files tune it on top.
  *
  * Robust by design: if the file is missing or unparseable the caller falls back
- * to the constants in `defaults.ts`, so a broken package layout never leaves the
- * sandbox wide open.
+ * to the constants in `defaults.ts`, so a broken package layout never leaves
+ * the sandbox wide open.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -14,13 +14,13 @@ import { fileURLToPath } from "node:url";
 
 /** Walk up from this module looking for the file the package ships. */
 function findDefaultFile(): string | null {
-	let dir = dirname(fileURLToPath(import.meta.url));
-	for (let i = 0; i < 6; i++) {
-		const candidate = join(dir, "sandbox.default.json");
+	let directory = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 6; depth++) {
+		const candidate = join(directory, "sandbox.default.json");
 		if (existsSync(candidate)) return candidate;
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
+		const parent = dirname(directory);
+		if (parent === directory) break;
+		directory = parent;
 	}
 	return null;
 }
@@ -37,7 +37,6 @@ export function loadDefaultPolicy(): Record<string, unknown> | null {
 			const parsed = JSON.parse(readFileSync(path, "utf-8"));
 			if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) resolved = parsed;
 		} catch {
-			/* fall back to the caller's constants */
 		}
 	}
 	cached = resolved;

package/src/core/policy/defaults.ts

@@ -8,3 +8,12 @@
 export const DEFAULT_DENY_READ = ["~/.ssh", "~/.aws", "~/.gnupg", "~/.pi/agent"];
 export const DEFAULT_ALLOW_WRITE = [".", "/tmp"];
 export const DEFAULT_DENY_WRITE = [".env", ".env.*", "*.pem", "*.key"];
+
+/** Domains every install may reach without a prompt; the shipped baseline adds more. */
+export const BUILTIN_NETWORK_ALLOWED = [
+	"npmjs.org", "*.npmjs.org",
+	"registry.npmjs.org", "registry.yarnpkg.com",
+	"pypi.org", "*.pypi.org",
+	"github.com", "*.github.com",
+	"api.github.com", "raw.githubusercontent.com",
+];