auto-permission-system 3.0.1 → 3.6.0

package/README.md

@@ -11,7 +11,7 @@ It puts allow/deny rules, interactive ask prompts, secret detection and an audit
 
 Enforcement happens in three layers:
 
-- **Layer 1** — OS-level bash sandbox (`sandbox-exec` on macOS, `bubblewrap` on Linux) that blocks filesystem writes outside an allow-list, reads of sensitive paths, reads outside the project when `outsideProject.read` gates them, and network egress to unlisted domains.
+- **Layer 1** — OS-level bash sandbox (`sandbox-exec` on macOS, `bubblewrap` on Linux) that blocks filesystem writes outside an allow-list, reads of sensitive paths, reads outside the project when `outsideProject.read` gates them, and network egress to unlisted domains — an unknown host asks first (a host in `deniedDomains` never does), with the same once/session/remember options as Layer 2.
 - **Layer 2** — In-process tool guard applying the same policy to the tools the OS sandbox can't reach: `read`, `grep`, `find`, `ls`, `write`, `edit`, `fetch_content`, `web_search`, `get_search_content`. `grep` output lines from denied files beneath an allowed search root are removed before the model sees them.
 - **Layer 3** — Subagent posture: optionally drop or restrict network access when running headless (`-p`, JSON mode, subagents).
 
@@ -72,11 +72,12 @@ A higher layer only states what it changes; absent keys keep the layer below. A
   "enabled": true,                      // set false to disable Layer 2 without --yolo
   "mode": "default",                   // "default" (rules) | "advanced-secure" (secret detection, ADR-018)
   "network": {
-    "allowedDomains": [                 // domains fetch_content / get_search_content may reach
+    "allowedDomains": [                 // domains the URL tools and bash may reach
       "github.com", "*.github.com",
       "registry.npmjs.org"
     ],
-    "deniedDomains": []                 // explicit block-list (checked before allowedDomains)
+    "deniedDomains": [],                // hard deny, checked first, never ask-able
+    "strictAllowlist": false            // true = deny unknown hosts instead of asking
   },
   "filesystem": {
     "denyRead": ["~/.ssh", "~/.aws", "~/.pi/agent"],  // Layer 1 + Layer 2: no read at all
@@ -123,9 +124,9 @@ 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. 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). 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). 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. If you do not answer, it resolves to the safe default: **block / deny**.
+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.
 
 ### File-name patterns
 
@@ -200,7 +201,7 @@ Every block/allow/always decision is appended to `~/.pi/agent/audit.log` as a JS
 ## FAQ
 
 ### How do I allow the agent to reach a new domain?
-Add it to `network.allowedDomains` in a policy file (global `~/.pi/agent/extensions/sandbox.json` or project `<cwd>/.pi/sandbox.json`), or just run the tool once and pick an **always** option in the ask prompt — that writes the domain to the project file for you.
+Add it to `network.allowedDomains` in a policy file (global `~/.pi/agent/extensions/sandbox.json` or project `<cwd>/.pi/sandbox.json`), or just run the tool (or a bash `curl`) once and pick an **always** option in the ask prompt — that writes the domain to the project file for you.
 
 ### How do I allow writes to another folder?
 Add the folder to `filesystem.allowWrite`. Relative paths (`.`, `/tmp`) resolve from the project root.

package/extensions/guard.ts

@@ -16,10 +16,13 @@ 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";
 import { canonicalize, expandHome, isAbsoluteDeny, isAskRead, isDeniedRead, isDeniedWrite, outsideProjectReason } from "../src/l2-guard/matching";
-import { hostnameOf, isAllowedUrl } from "../src/l2-guard/url";
+import { deniedUrlReason, hostnameOf, isAllowedUrl } from "../src/l2-guard/url";
 import { audit, AUDIT_PATH } from "../src/shared/audit";
 import { askOrBlock, clearSessionGrants, sessionGrantSummary, type UICtx } from "../src/l2-guard/prompts";
-import { denyMessage } from "../src/l2-guard/ask";
+import { grantProgramOutputSession, isProgramOutputGranted, clearProgramOutputSessionGrants, programOutputSessionGrantSummary } from "../src/l2-guard/program-grants";
+import { programIdForToolCall } from "../src/l2-guard/program-id";
+import { denyMessage } from "../src/ui/ask";
+import { emitDomainGrant } from "../src/shared/network-grants";
 import { subagentNetworkBlock } from "../src/l2-guard/subagent";
 import { onYolo } from "../src/shared/yolo";
 
@@ -35,6 +38,11 @@ function detectionBlock(action: "read" | "tool", why: string): string {
 	return `Tool call blocked by policy: ${why}. Nothing was run — ask the user.`;
 }
 
+/** Maps each in-flight tool call to the program id we'll show in the
+ *  Advanced Secure output gate. Populated at `tool_call`, consumed at
+ *  `tool_result`, cleared at `session_start`. */
+const programIdByCallId = new Map<string, string>();
+
 async function askDetection(
 	ctx: UICtx,
 	kind: "read" | "tool",
@@ -135,12 +143,20 @@ export default function (pi: ExtensionAPI) {
 		applyActive();
 		clearSessionGrants();
 		detectionGrants.clear();
+		clearProgramOutputSessionGrants();
+		programIdByCallId.clear();
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
 		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) => {
@@ -218,10 +234,20 @@ 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 });
+					return { block: true, reason: denyMessage("allowDomains", denied) };
+				}
 				const reason = isAllowedUrl(u, policy);
 				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);
+				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;
 			}
 		}
@@ -281,17 +307,35 @@ export default function (pi: ExtensionAPI) {
 		if (!active || event.isError) return;
 		const policy = loadPolicy(ctx.cwd);
 		if (policy.mode !== "advanced-secure") return;
+		const programId = event.toolCallId ? programIdByCallId.get(event.toolCallId) : undefined;
+		if (programId && isProgramOutputGranted(programId)) {
+			audit({ layer: 2, tool: event.toolName, decision: "session-grant", grant: programId, note: "advanced-secure-output", cwd: ctx.cwd });
+			return;
+		}
 		const rawInput = event.input ?? {};
 		const rawPath = rawInput.path ?? rawInput.file_path;
-		const subject = typeof rawPath === "string" && rawPath ? rawPath : event.toolName;
+		const subject = (() => {
+			if (typeof rawPath === "string" && rawPath) return rawPath;
+			if (event.toolName === "bash") {
+				const cmd = (event.input as { command?: string } | undefined)?.command;
+				return cmd ? `bash: ${cmd}` : "bash";
+			}
+			return event.toolName;
+		})();
 		const { types, hits } = collectExposure(event.content, subject);
 		if (!types.length) return;
 		const findings = types;
 		const ui = /* SAFETY: pi's ctx carries cwd/UI at runtime; the local type only names the members used. */ ctx as unknown as UICtx;
-		const allow = ui.hasUI !== false && (await askExposure(ui, hits)) === "allow";
-		if (allow) {
-			audit({ layer: 2, tool: event.toolName, decision: "yes", note: "advanced-secure-output", findings, cwd: ctx.cwd });
-			ctx.ui.notify(`🛡 Advanced Secure: you allowed ${event.toolName} output to be sent.`, "warning");
+		const choice = ui.hasUI !== false ? await askExposure(ui, hits, programId) : "block";
+		if (choice === "allow" || choice === "program-session") {
+			if (choice === "program-session" && programId) {
+				grantProgramOutputSession(programId);
+				audit({ layer: 2, tool: event.toolName, decision: "session", grant: programId, note: "advanced-secure-output", findings, cwd: ctx.cwd });
+				ctx.ui.notify(`🛡 Advanced Secure: you allowed all ${programId} output for the rest of this session.`, "info");
+			} else {
+				audit({ layer: 2, tool: event.toolName, decision: "yes", note: "advanced-secure-output", findings, cwd: ctx.cwd });
+				ctx.ui.notify(`🛡 Advanced Secure: you allowed ${event.toolName} output to be sent.`, "warning");
+			}
 			return;
 		}
 		audit({ layer: 2, tool: event.toolName, decision: "no", note: "advanced-secure-output", findings, cwd: ctx.cwd });

package/extensions/sandbox.ts

@@ -31,8 +31,11 @@
 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 { initSandbox, persistLayer1Override, reloadSandbox, resetSandbox } from "../src/l1-sandbox/manager";
+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 { 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) {
@@ -40,6 +43,10 @@ export default function (pi: ExtensionAPI) {
 	// `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();
 	const localBash = createBashTool(localCwd);
 
@@ -48,10 +55,25 @@ export default function (pi: ExtensionAPI) {
 	let runtimeYolo = false;
 	let sandboxStarting: Promise<void> | null = null;
 	let latestCtx: ExtensionContext | undefined;
+	let latestBashCommand: string | undefined;
 	let activeCtx: { cwd: string; hasUI?: boolean; ui?: { select?: (t: string, o: string[], op?: { timeout?: number }) => Promise<string | undefined>; notify?: (m: string, l?: string) => void } } | undefined;
 
-	const persistAndReload = (absPath: string, scope: "cwd" | "global") => persistLayer1Override(localCwd, "allowWrite", absPath, scope);
-	const persistAndReloadRead = (absPath: string, scope: "cwd" | "global") => persistLayer1Override(localCwd, "allowRead", absPath, scope);
+	const persistAndReload = (absPath: string, scope: "cwd" | "global") => persistLayer1Override(localCwd, "allowWrite", absPath, scope, networkDeps(localCwd));
+	const persistAndReloadRead = (absPath: string, scope: "cwd" | "global") => persistLayer1Override(localCwd, "allowRead", absPath, scope, networkDeps(localCwd));
+
+	/** Layer 1 network ask wiring (ADR-023): the proxy asks for unknown hosts and applies grants live. */
+	const networkDeps = (cwd: string): NetworkAskDeps => ({
+		cwd,
+		getCtx: () => /* SAFETY: pi's runtime ctx carries ui.select/ui.notify; the local type names only the members used. */ activeCtx as unknown as NetworkAskCtx | undefined,
+		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 command() { return latestBashCommand; },
+	});
 
 	/** Bring the bash sandbox down; safe when it was never up. */
 	const stopSandbox = async (): Promise<void> => {
@@ -77,7 +99,7 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 		try {
-			await initSandbox(ctx.cwd, config);
+			await initSandbox(ctx.cwd, config, networkDeps(ctx.cwd));
 			sandboxEnabled = true;
 			sandboxInitialized = true;
 			const networkCount = config.network?.allowedDomains?.length ?? 0;
@@ -140,9 +162,18 @@ 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 };
+			if (typeof input.command === "string") latestBashCommand = input.command;
+		}
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		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();
 		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
@@ -175,7 +206,7 @@ export default function (pi: ExtensionAPI) {
 					return;
 				}
 				try {
-					await reloadSandbox(localCwd);
+					await reloadSandbox(localCwd, networkDeps(localCwd));
 					ctx.ui.notify("🔄 Sandbox reloaded from disk (global + project sandbox.json)", "info");
 				} catch (e) {
 					ctx.ui.notify(`Sandbox reload failed: ${e instanceof Error ? e.message : e}`, "error");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-permission-system",
-  "version": "3.0.1",
+  "version": "3.6.0",
   "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",
@@ -39,7 +39,8 @@
     "@anthropic-ai/sandbox-runtime": "^0.0.78"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.2.3",

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

@@ -14,7 +14,7 @@ Wraps the `bash` tool with `sandbox-exec` (macOS) or `bubblewrap` (Linux). Block
 - Filesystem writes outside `allowWrite`
 - Filesystem reads of `denyRead` paths (defaults include `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.pi/agent`)
 - Filesystem reads outside the project when `outsideProject.read` is `"ask"` or `"deny"` — when set, the home dir (and the project's parent) is fenced with `denyRead` and the project plus `allowWrite`/`outsideProject.allowRead` are re-exposed (ADR-014). With `"ask"`, a bash command that *plainly* names an outside path is confirmed with you **before it runs** (ADR-015): allow (`yes — this once`, or a persistent `always` grant) → the real, complete output; deny → the command is not run at all (no silently trimmed output). `install`/`npm` under `~/.pi/agent` are pre-allowed via `outsideProject.allowRead`, so they never prompt. Obfuscated reads still hit the fence and stay masked.
-- Network egress to domains not in `allowedDomains`
+- Network egress to domains not in `allowedDomains`: a host in neither list asks before the proxy decides (ADR-023) — `yes — this once` covers that bash command's connections to the host, `yes — for this session` lasts until the session ends, and `always` writes `overrides.allowDomains` and applies live. A host in `deniedDomains`, or `network.strictAllowlist: true`, is a hard deny that is never ask-able; headless blocks.
 
 **Layer 2 — In-process tool guard**
 Hooks `tool_call` for `read`, `grep`, `find`, `ls`, `write`, `edit`, `fetch_content`, `web_search`, `get_search_content`. Applies the same policy file as Layer 1. For `grep`, `find` and `ls` the search root is checked like a `read` path. A `tool_result` hook also removes `grep` output lines from denied files beneath an allowed root (for example a `.env` deep in the tree); approving the root does not approve those files. When a call is blocked, shows an interactive prompt with persistence options.
@@ -39,7 +39,8 @@ A higher layer only states what it changes; absent keys keep the layer below. A
   "mode": "default",                     // "default" (rules) | "advanced-secure" (secret detection, ADR-018)
   "network": {
     "allowedDomains": ["github.com", "*.github.com"],  // empty = allow all
-    "deniedDomains": []
+    "deniedDomains": [],                   // hard deny, never ask-able
+    "strictAllowlist": false               // true = deny unknown hosts instead of asking
   },
   "filesystem": {
     "denyRead": ["~/.ssh", "~/.pi/agent"],  // Layer 1 + 2: hard block (defaults add ~/.aws, ~/.gnupg)
@@ -83,9 +84,13 @@ When a normal (non-absolute-deny) call is blocked:
 - **always for ALL projects** — whitelist in `~/.pi/agent/extensions/sandbox.json`
 - **always for ALL projects (folder)** — whitelist parent directory globally
 
+A **network** (domain) ask keeps the same rows, but the *unanswered* default flips (ADR-024): the footer reads `Default: Yes, just this once (15s)`, and a countdown that runs out counts as **allow once for this bash command**. `No` is still preselected (Enter blocks) and Esc still denies. A domain in `deniedDomains` (or `network.strictAllowlist: true`) never prompts.
+
 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 **10 seconds** by default; no answer means the safe default: **block / deny**. Esc on any screen also blocks.
+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 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.
 
 ## Sensitive reads ask
 
@@ -129,7 +134,7 @@ Without restarting, `/permission-mode` → **YOLO** turns every layer off in one
 
 ## Common tasks
 
-**Allow a new domain** — either answer "always" in the prompt when the block fires, or add it manually:
+**Allow a new domain** — either answer "always" in the prompt when the block fires (from a bash command or a URL tool), or add it manually:
 ```json
 // ~/.pi/agent/extensions/sandbox.json  (global)
 // or <cwd>/.pi/sandbox.json  (project-local)

package/src/core/index.ts

@@ -3,6 +3,7 @@
  * Both layer adapters and the unit tests import from here.
  */
 export * from "./policy/defaults";
+export * from "./policy/domains";
 export * from "./policy/default-file";
 export * from "./policy/files";
 export * from "./policy/merge";

package/src/core/policy/domains.ts

@@ -0,0 +1,26 @@
+/**
+ * Domain pattern matching shared by both layers. Pure: no pi, no OS.
+ *
+ * `hostnameOf` parses a URL to its lowercase host; `domainMatches` implements
+ * the allow-list syntax used by `allowedDomains` / `deniedDomains` / grants:
+ * an exact host, or `*.domain` which also matches the apex. Port suffixes
+ * (`host:443`) are a sandbox-runtime config feature only; this matcher is
+ * hostname-only, which is what both layers store in policy.
+ */
+
+export function hostnameOf(url: string): string | null {
+	try {
+		return new URL(url).hostname.toLowerCase();
+	} catch {
+		return null;
+	}
+}
+
+export function domainMatches(host: string, pattern: string): boolean {
+	const p = pattern.toLowerCase();
+	if (p.startsWith("*.")) {
+		const suffix = p.slice(1); // ".npmjs.org"
+		return host === p.slice(2) || host.endsWith(suffix);
+	}
+	return host === p;
+}

package/src/l1-sandbox/bash-ops.ts

@@ -12,7 +12,13 @@ import { type BashOperations } from "@earendil-works/pi-coding-agent";
 import { askReadCandidates, extractBlockedPath, isBlockedAccessError, isSafeFolderGrant, isWriteBlockError, matchedAskCommands, matchesPolicyPattern, outsideProjectMode, outsideProjectReadCandidates, outsideProjectReadDenied, sandboxFilesystem } from "../core/index";
 import { audit } from "../shared/audit";
 import { askMain, askRememberFile, type AskCtx } from "../ui/ask-flow";
-import { loadConfig } from "./config";
+import { loadConfig, projectTrusted } from "./config";
+
+/** First whitespace-separated token of a bash command — used to name the binary in prompt titles. */
+function firstWord(command: string): string {
+	return command.trim().split(/\s+/)[0] ?? command;
+}
+import { beginNetworkCommand, endNetworkCommand } from "./network-ask";
 
 export interface SandboxedBashOpts {
 	ctx?: { cwd: string; hasUI?: boolean; ui?: { select?: (t: string, o: string[], op?: { timeout?: number }) => Promise<string | undefined>; notify?: (m: string, l?: string) => void } };
@@ -42,8 +48,12 @@ async function preflightSensitiveCommands(
 	const matched = matchedAskCommands(command, ask, cwd, homedir());
 	if (!matched.length) return undefined;
 	const ui = opts.ctx as AskCtx;
-	const body = `  command: ${matched.join(", ")}\n  why:     it can print environment values (API tokens)`;
-	const choice = await askMain(ui, "Command may print secrets", body, { once: true, remember: false });
+	const body = [
+		`Command  ${matched.join(", ")}`,
+		`Risk     environment variables often hold API keys and tokens`,
+		`Note     can only be allowed one run at a time`,
+	].join("\n");
+	const choice = await askMain(ui, `Let ${matched[0]} print your environment variables?`, body, { once: true, remember: false, icon: "cred" });
 	const subject = matched.join(", ");
 	if (choice === "once") {
 		auditL1({ subject, decision: "once", note: "sensitive-command", cwd });
@@ -75,7 +85,7 @@ async function preflightAskReads(
 			onData(Buffer.from(`\n❌ pi-sandbox: sensitive file read blocked: ${absPath}. Nothing was run — ask the user.\n`));
 			return { exitCode: 1 };
 		}
-		const choice = await askMain(ui, "Sensitive file read", `  file:   ${absPath}\n  why:    it may hold secrets`, { remember: false });
+		const choice = await askMain(ui, "Let this command read your .env file?", [`File     ${absPath}`, `Why      .env files usually hold passwords and API keys`, `Risk     the AI will see any keys in it`, `Note     can't be saved as a permanent rule (it holds secrets)`].join("\n"), { remember: false, icon: "cred" });
 		if (choice === "once" || choice === "session") {
 			auditL1({ subject: absPath, decision: choice, note: "ask-read", cwd });
 			continue;
@@ -100,7 +110,7 @@ async function preflightOutsideReads(
 	const once: string[] = [];
 	for (const absPath of outsideProjectReadCandidates(command, cwd, homedir(), cfg)) {
 		const ui = opts.ctx as AskCtx;
-		const main = await askMain(ui, "Read outside the project", `  path:   ${absPath}\n  source: this bash command`);
+		const main = await askMain(ui, "Let this command read a file outside your project?", [`File     ${absPath}`, `Command  ${command}`, `Why      files outside your project need your OK`].join("\n"), { session: true });
 		if (main === "once") {
 			auditL1({ subject: absPath, decision: "once", reason: "outside-project-read", note: "preflight", cwd });
 			once.push(absPath);
@@ -111,7 +121,7 @@ async function preflightOutsideReads(
 		if (main === "remember") {
 			const parent = dirname(absPath);
 			const folder = isSafeFolderGrant(parent, homedir()) ? parent : null;
-			const picked = await askRememberFile(ui, "Remember this read?", `  file:   ${absPath}\n  folder: ${parent}`, absPath, folder);
+			const picked = await askRememberFile(ui, "Always allow reading \u2014 what, and where?", [`File     ${absPath}`, `Folder   ${parent}/`, `Note     the rule works for any command, not just ${firstWord(command)}`].join("\n"), absPath, folder, { icon: "save", untrusted: !projectTrusted(cwd) });
 			if (picked) {
 				subject = picked.folder ? parent : absPath;
 				scope = picked.scope;
@@ -302,11 +312,11 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 							const absPath = offending;
 							try {
 								const ui = opts.ctx as AskCtx;
-								const main = await askMain(ui, "Read blocked by policy", `  path:   ${absPath}\n  why:    outside the project\n  layer:  bash sandbox`, { once: false });
+								const main = await askMain(ui, "Let this command read a file outside your project?", [`File     ${absPath}`, `Command  ${command}`, `Why      outside your project, not on your allowed list`].join("\n"), { session: true });
 								if (main === "remember") {
 									const parent = dirname(absPath);
 									const folder = isSafeFolderGrant(parent, homedir()) ? parent : null;
-									const picked = await askRememberFile(ui, "Remember this read?", `  file:   ${absPath}\n  folder: ${parent}`, absPath, folder);
+									const picked = await askRememberFile(ui, "Always allow reading \u2014 what, and where?", [`File     ${absPath}`, `Folder   ${parent}/`, `Note     the rule works for any command, not just ${firstWord(command)}`].join("\n"), absPath, folder, { icon: "save", untrusted: !projectTrusted(cwd) });
 									if (picked) {
 										const subject = picked.folder ? parent : absPath;
 										try {
@@ -342,7 +352,7 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 							const alreadyGranted = writeOnce.includes(parentDir);
 							try {
 								const ui = opts.ctx as AskCtx;
-								const main = await askMain(ui, "Write blocked by policy", `  path:   ${absPath}\n  why:    not under any allowWrite root\n  layer:  bash sandbox`, { once: !alreadyGranted });
+								const main = await askMain(ui, `Let ${firstWord(command)} save files in ${parentDir}/?`, [`File     ${absPath}`, `Command  ${command}`, `Why      outside your project, not on your allowed list`].join("\n"), { session: true, once: !alreadyGranted });
 								if (main === "once") {
 									auditL1({ subject: absPath, granularity: "folder", original: absPath, decision: "once", scope: "invocation", cwd: opts.ctx.cwd, note: "write-once" });
 									opts.ctx.ui?.notify?.(`pi-sandbox: allowed ${absPath} once — re-running the command`, "warning");
@@ -352,7 +362,7 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 								}
 								if (main === "remember") {
 									const folder = isSafeFolderGrant(parentDir, homedir()) ? parentDir : null;
-									const picked = await askRememberFile(ui, "Remember this write?", `  file:   ${absPath}\n  folder: ${parentDir}`, absPath, folder);
+									const picked = await askRememberFile(ui, "Always allow saving \u2014 what, and where?", [`File     ${absPath}`, `Folder   ${parentDir}/`, `Note     the rule works for any command, not just ${firstWord(command)}`].join("\n"), absPath, folder, { icon: "save", untrusted: !projectTrusted(cwd) });
 									if (picked) {
 										const subject = picked.folder ? parentDir : absPath;
 										try {
@@ -393,7 +403,14 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 				});
 			};
 
-			return attempt([]);
+			// "Allow once" network grants cover this command's connections to a host;
+			// the finally releases them however the command ends (abort/timeout too).
+			beginNetworkCommand();
+			try {
+				return await attempt([]);
+			} finally {
+				endNetworkCommand();
+			}
 		},
 	};
 }

package/src/l1-sandbox/manager.ts

@@ -1,6 +1,6 @@
 /**
- * Layer 1 sandbox-runtime lifecycle: initialize, reset/reload, and persist an
- * ask-tier "always" grant into sandbox.json.
+ * Layer 1 sandbox-runtime lifecycle: initialize, reset/reload, persist an
+ * ask-tier "always" grant into sandbox.json, and apply network grants live.
  *
  * Adapter module: owns the SandboxManager singleton and the on-disk policy.
  */
@@ -8,13 +8,15 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { SandboxManager } from "@anthropic-ai/sandbox-runtime";
+import { SandboxManager, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { readPolicyForUpdate, recordProjectTrust, sandboxFilesystem } from "../core/index";
 import { loadConfig, projectTrusted, TRUST_STORE, type SandboxConfig } from "./config";
+import { createNetworkAsk, type NetworkAskDeps } from "./network-ask";
 
-export async function initSandbox(cwd: string, config: SandboxConfig): Promise<void> {
-	await SandboxManager.initialize({
+/** The sandbox-runtime view of a SandboxConfig (pi-only fields stripped). */
+function runtimeConfig(cwd: string, config: SandboxConfig): SandboxRuntimeConfig {
+	return {
 		network: config.network,
 		// Strip pi-only fields (modelDenyRead, _comment_*) so SandboxManager
 		// doesn't see keys it doesn't understand; modelDenyRead is enforced by
@@ -25,7 +27,16 @@ export async function initSandbox(cwd: string, config: SandboxConfig): Promise<v
 			: { denyRead: [], allowRead: [], allowWrite: [], denyWrite: [], disabled: true },
 		ignoreViolations: config.ignoreViolations,
 		enableWeakerNestedSandbox: config.enableWeakerNestedSandbox,
-	});
+	};
+}
+
+/**
+ * `deps` registers the unknown-domain ask callback (ADR-023). Without it the
+ * proxy hard-denies hosts outside `allowedDomains` (sandbox-runtime's own
+ * behavior when no callback is registered).
+ */
+export async function initSandbox(cwd: string, config: SandboxConfig, deps?: NetworkAskDeps): Promise<void> {
+	await SandboxManager.initialize(runtimeConfig(cwd, config), deps ? createNetworkAsk(deps) : undefined);
 }
 
 export async function resetSandbox(): Promise<void> {
@@ -36,17 +47,35 @@ export async function resetSandbox(): Promise<void> {
 	}
 }
 
-export async function reloadSandbox(cwd: string): Promise<void> {
+export async function reloadSandbox(cwd: string, deps?: NetworkAskDeps): Promise<void> {
 	const config = loadConfig(cwd);
 	await resetSandbox();
-	await initSandbox(cwd, config);
+	await initSandbox(cwd, config, deps);
 }
 
-/** Persist an "always" Layer 1 override (scope: cwd or global) and live-reload SandboxManager. */
-export async function persistLayer1Override(
+/**
+ * Add a host to the running proxy's allowlist in place. `updateConfig` swaps
+ * the config the proxy reads per request; a `reset()`/`initialize()` here
+ * would tear down the proxy that is serving the request being approved.
+ */
+export function applyNetworkGrant(host: string): void {
+	const current = SandboxManager.getConfig();
+	if (!current) return;
+	const pattern = host.toLowerCase();
+	if (current.network.allowedDomains.some((p) => p.toLowerCase() === pattern)) return;
+	SandboxManager.updateConfig({
+		...current,
+		network: { ...current.network, allowedDomains: [...current.network.allowedDomains, pattern] },
+	});
+}
+
+type Layer1OverrideKind = "allowWrite" | "allowRead" | "allowDomains";
+
+/** File write only — the caller decides whether (and how) to apply it live. */
+async function writeLayer1Override(
 	cwd: string,
-	kind: "allowWrite" | "allowRead",
-	absPath: string,
+	kind: Layer1OverrideKind,
+	value: string,
 	scope: "cwd" | "global",
 ): Promise<string> {
 	const { dir, path } =
@@ -59,15 +88,35 @@ export async function persistLayer1Override(
 		throw new Error(`${path} is not trusted; run /security trust first, or choose an "ALL projects" option`);
 	}
 	// Throws on an unparseable file: never overwrite a hand-written policy we could not read.
-	const existing = readPolicyForUpdate(path) as { overrides?: { allowWrite?: string[]; allowRead?: string[] } };
+	const existing = readPolicyForUpdate(path) as { overrides?: Partial<Record<Layer1OverrideKind, string[]>> };
 	const overrides = existing.overrides ?? {};
 	const list = overrides[kind] ?? [];
-	if (!list.includes(absPath)) list.push(absPath);
+	if (!list.includes(value)) list.push(value);
 	overrides[kind] = list;
 	existing.overrides = overrides;
 	mkdirSync(dir, { recursive: true });
 	writeFileSync(path, `${JSON.stringify(existing, null, 2)}\n`);
 	if (scope === "cwd") recordProjectTrust(path, TRUST_STORE);
-	await reloadSandbox(cwd);
+	return path;
+}
+
+/**
+ * Write an "always" domain grant (file only). The network ask applies it live
+ * with `applyNetworkGrant` right after, so the in-flight request survives.
+ */
+export async function writeNetworkOverride(cwd: string, host: string, scope: "cwd" | "global"): Promise<string> {
+	return writeLayer1Override(cwd, "allowDomains", host, scope);
+}
+
+/** Persist an "always" Layer 1 override (scope: cwd or global) and live-reload SandboxManager. */
+export async function persistLayer1Override(
+	cwd: string,
+	kind: "allowWrite" | "allowRead",
+	absPath: string,
+	scope: "cwd" | "global",
+	deps?: NetworkAskDeps,
+): Promise<string> {
+	const path = await writeLayer1Override(cwd, kind, absPath, scope);
+	await reloadSandbox(cwd, deps);
 	return path;
 }