auto-permission-system 3.9.1 → 3.15.0

package/extensions/guard.ts

@@ -34,8 +34,8 @@ import { onYolo } from "../src/shared/yolo";
 const detectionGrants = new Set<string>();
 
 function detectionBlock(action: "read" | "tool", why: string): string {
-	if (action === "read") return `Read blocked by policy: ${why}. Nothing was read — ask the user.`;
-	return `Tool call blocked by policy: ${why}. Nothing was run — ask the user.`;
+	if (action === "read") return `Read blocked by policy: ${why}. Nothing was read — ask the user to adjust the permission mode (/permission-mode) if needed. Do not attempt workarounds or inspect plugin files.`;
+	return `Tool call blocked by policy: ${why}. Nothing was run — ask the user to adjust the permission mode (/permission-mode) if needed. Do not attempt workarounds or inspect plugin files.`;
 }
 
 /** Maps each in-flight tool call to the program id we'll show in the
@@ -91,7 +91,22 @@ async function detectMcpAsk(
 		policy: mcpPolicy,
 	});
 	if (result.decision !== "ask") return null;
-	return askDetection(ctx, "tool", toolName, result.summary);
+
+	// Include detailed call parameters or script preview if present
+	let detailedSummary = result.summary;
+	if (input && Object.keys(input).length > 0) {
+		const rawScript = input.code ?? input.script ?? input.command ?? input.query;
+		if (typeof rawScript === "string" && rawScript.includes("\n")) {
+			detailedSummary += `\n\n${rawScript}`;
+		} else {
+			const formattedArgs = JSON.stringify(input, null, 2);
+			if (formattedArgs.includes("\n")) {
+				detailedSummary += `\n\nArguments:\n${formattedArgs}`;
+			}
+		}
+	}
+
+	return askDetection(ctx, "tool", toolName, detailedSummary);
 }
 
 export default function (pi: ExtensionAPI) {

package/extensions/permission-mode.ts

@@ -19,37 +19,32 @@ import { emitYolo, onYolo, YOLO_STATUS } from "../src/shared/yolo";
 
 const GLOBAL_POLICY = `${getAgentDir()}/extensions/sandbox.json`;
 
-const MODES: Array<{ label: string; value: PermissionMode }> = [
+const MODE_DEFS: Array<{
+	value: PermissionMode;
+	icon: string;
+	name: string;
+	desc: string;
+}> = [
 	{
-		label: "Advanced Secure (recommended) — detect secrets in reads, MCP calls, and output",
 		value: "advanced-secure",
+		icon: "🧠",
+		name: "Advanced Secure",
+		desc: "Blocks sensitive data leaks from file reads, MCP tools & command outputs",
 	},
 	{
-		label: "Default — rules only",
 		value: "default",
+		icon: "🔒",
+		name: "Default",
+		desc: "Restricts file paths & network access at the sandbox level",
 	},
 	{
-		label: "YOLO — disable ALL security layers",
 		value: "yolo",
+		icon: "⚠️",
+		name: "YOLO",
+		desc: "Turns off all file sandboxing and leak protections",
 	},
 ];
 
-const EXPLANATION = [
-	"Advanced Secure (recommended)",
-	"  Adds secret/credential detection on top of the rules:",
-	"   • File reads — scans contents for keys, tokens, and passwords",
-	"   • MCP calls — flags risky tool calls before they run",
-	"   • Tool/command/file output — redacts secrets before they reach the model",
-	"",
-	"Default",
-	"  Rule-based only: sandbox.json paths, domains, and commands.",
-	"  No file contents are inspected.",
-	"",
-	"YOLO",
-	"  Turns every layer off. Saved like the other modes, so new conversations",
-	"  start with it too until you pick Default or Advanced Secure again.",
-].join("\n");
-
 /**
  * The single sandbox footer chip: `Sandbox: <icon> N domains, M paths`.
  * `🧠` marks advanced-secure, `🔒` default; YOLO replaces it with the warning.
@@ -79,13 +74,23 @@ function modeNotice(mode: PermissionMode): { text: string; level: "info" | "warn
 
 async function pickMode(pi: ExtensionAPI, ctx: ExtensionContext, yolo: { active: boolean }): Promise<void> {
 	const current: PermissionMode = yolo.active ? "yolo" : normalizeMode(loadPolicy(ctx.cwd).mode);
+
+	const options = MODE_DEFS.map((m) => {
+		const isActive = m.value === current;
+		const nameWithStatus = isActive ? `${m.name} (active)` : m.name;
+		const labelCol = nameWithStatus.padEnd(26);
+		return `${m.icon}  ${labelCol} —  ${m.desc}`;
+	});
+
 	const picked = await ctx.ui.select(
-		`Permission mode — current: ${modeLabel(current)}\n\n${EXPLANATION}\n\nEsc keeps the current mode.`,
-		MODES.map((m) => m.label),
+		"Select permission mode:",
+		options,
 		{ timeout: 120_000 },
 	);
 	if (picked === undefined) return;
-	const next = MODES.find((m) => m.label === picked)?.value ?? current;
+
+	const pickedIndex = options.indexOf(picked);
+	const next = pickedIndex >= 0 ? MODE_DEFS[pickedIndex].value : current;
 	if (next === current) {
 		if (next === "yolo" && !yolo.active) {
 			yolo.active = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-permission-system",
-  "version": "3.9.1",
+  "version": "3.15.0",
   "description": "Claude auto mode for Pi & security for Pi. A zero-trust permission system for Pi coding agent powered by Advanced Secure mode to scan files, content, and tools to prevent data breaches.",
   "type": "module",
   "author": "Navin Kumar",

package/sandbox.claude.json

@@ -2,6 +2,7 @@
   "enabled": true,
   "mode": "advanced-secure",
   "network": {
+    "allowLocalhost": false,
     "strictAllowlist": true,
     "allowedDomains": [
       "registry.npmjs.org",

package/sandbox.default.json

@@ -2,6 +2,8 @@
   "enabled": true,
   "mode": "advanced-secure",
   "network": {
+    "allowLocalhost": true,
+    "allowAllUnixSockets": true,
     "allowedDomains": [
       "registry.npmjs.org",
       "registry.yarnpkg.com",
@@ -24,13 +26,22 @@
       "rubygems.org",
       "api.nuget.org",
       "deno.land",
-      "jsr.io"
+      "jsr.io",
+      "api.openai.com",
+      "huggingface.co",
+      "*.huggingface.co",
+      "cdn-lfs.huggingface.co",
+      "*.diffusion.studio",
+      "diffusion.studio"
     ]
   },
   "filesystem": {
     "outsideProject": {
       "read": "allow",
-      "allowRead": []
+      "allowRead": [
+        "~/Downloads",
+        "~/.cache"
+      ]
     },
     "denyRead": [],
     "askRead": [

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

@@ -1,12 +1,21 @@
 ---
 name: auto-permission-system
-description: Use this skill when the user asks about auto-permission-system, security for Pi, permission system for Pi, how to secure Pi, Claude auto mode for Pi, security policy configuration, why a tool call was blocked, how to add an allow-list entry, or how to configure sandbox behavior. Covers the two-layer sandbox (OS-level bash sandbox and in-process tool guard), policy file locations and fields, Claude auto mode preset (sandbox.claude.json), ask-tier prompt options, absolute-deny paths, escape hatches (--yolo, --no-sandbox, /permission-mode → YOLO), the audit log, and common tasks like allowing a new domain or write path.
+description: Use this skill ONLY when the user explicitly asks about auto-permission-system, security for Pi, configuring security policies, or permission modes. Do NOT invoke this skill automatically when an action or tool is blocked during regular coding tasks.
 ---
 
 # Security for Pi (Pi Permission System) — Skill
 
 Use this skill when the user asks about the auto-permission-system extension, security for Pi, permission system for Pi, how to secure Pi, or configuring Claude auto mode for Pi.
 
+## Handling Blocked Operations (Agent Behavior Guideline)
+
+When a command, file operation, or tool call is blocked by the security policy:
+- **Do not inspect plugin internals**: Do NOT read files inside `auto-permission-system`, do NOT inspect sandbox runtime code, and do NOT attempt to find bypasses or workarounds.
+- **Explain clearly**: Calmly and concisely inform the user what specific action was restricted and why.
+- **Ask to change permission mode**: Ask the user if they wish to adjust the permission mode using `/permission-mode` to allow the action.
+- **Wait for user input**: Do not proceed with speculative workarounds or retry loops until the user responds or updates the mode.
+
+
 ## What this extension does
 
 **Layer 1 — Bash sandbox (OS-level)**
@@ -39,6 +48,7 @@ A higher layer only states what it changes; absent keys keep the layer below. A
   "enabled": true,
   "mode": "default",                     // "default" (rules) | "advanced-secure" (secret detection, ADR-018)
   "network": {
+    "allowLocalhost": true,                // true (default): localhost on all ports allowed; false: strict network isolation
     "allowedDomains": ["github.com", "*.github.com"],  // empty = allow all
     "deniedDomains": [],                   // hard deny, never ask-able
     "strictAllowlist": false               // true = deny unknown hosts instead of asking

package/src/core/policy/patterns.ts

@@ -31,6 +31,59 @@ export function isWriteBlockError(output: string): boolean {
 	return WRITE_BLOCK_RE.test(output);
 }
 
+/**
+ * Loopback / localhost connection refusal evidence in a sandboxed command's output.
+ * On Linux, bubblewrap runs with --unshare-net which isolates network namespaces.
+ * Host services listening on 127.0.0.1/localhost (like Diffusion Studio on port 3274,
+ * or local dev servers) are not reachable from inside the container namespace.
+ */
+const LOOPBACK_REFUSAL_RE =
+	/(?:Failed to connect to (?:127\.0\.0\.1|localhost|::1)|(?:connect|connection refused).*?(?:127\.0\.0\.1|localhost|::1)|(?:127\.0\.0\.1|localhost|::1).*?(?:connection refused|ECONNREFUSED)|ECONNREFUSED.*?(?:127\.0\.0\.1|localhost|::1)|Diffusion Studio is not running)/i;
+
+/** True when the command failed due to connecting to a loopback/localhost address in the sandbox. */
+export function isLoopbackConnectionRefused(output: string): boolean {
+	return LOOPBACK_REFUSAL_RE.test(output);
+}
+
+export interface LoopbackEndpointInfo {
+	host: string;
+	port?: string;
+	service?: string;
+}
+
+/**
+ * Extract endpoint metadata (host, port, service name) from a loopback connection failure.
+ */
+export function extractLoopbackEndpoint(output: string, command?: string): LoopbackEndpointInfo | undefined {
+	if (!isLoopbackConnectionRefused(output)) return undefined;
+
+	const isDiffusion = /diffusion studio is not running/i.test(output) || (command && /\b(?:dapi|diffusion)\b/i.test(command));
+	if (isDiffusion) {
+		return { host: "127.0.0.1", port: "3274", service: "Diffusion Studio" };
+	}
+
+	const curlMatch = output.match(/Failed to connect to (127\.0\.0\.1|localhost|::1) port (\d+)/i);
+	if (curlMatch) {
+		return {
+			host: curlMatch[1],
+			port: curlMatch[2],
+			service: curlMatch[2] === "3274" ? "Diffusion Studio" : undefined,
+		};
+	}
+
+	const nodeMatch = output.match(/(?:ECONNREFUSED|connect to)\s+(127\.0\.0\.1|localhost|::1)(?::| port )(\d+)/i);
+	if (nodeMatch) {
+		return {
+			host: nodeMatch[1],
+			port: nodeMatch[2],
+			service: nodeMatch[2] === "3274" ? "Diffusion Studio" : undefined,
+		};
+	}
+
+	const hostMatch = output.match(/(127\.0\.0\.1|localhost|::1)/i);
+	return { host: hostMatch ? hostMatch[1] : "127.0.0.1" };
+}
+
 /** A shell-name/empty token is not a path; everything else resolves against cwd unless absolute. */
 function toAbsolutePath(rawToken: string, cwd: string, home: string): string | undefined {
 	let token = rawToken.trim().replace(/[.,;]+$/, "");

package/src/detect/sensitive-file-scanner/patterns.ts

@@ -181,6 +181,33 @@ export const COMMON_NON_SECRET_VALUES = new Set([
   "secretvalue",
   "somevalue",
   "myvalue",
+  // Common keyboard keys / UI events (e.g. `Successfully pressed key: Backspace`)
+  "backspace",
+  "tab",
+  "enter",
+  "return",
+  "escape",
+  "esc",
+  "space",
+  "pageup",
+  "pagedown",
+  "end",
+  "home",
+  "arrowleft",
+  "arrowup",
+  "arrowright",
+  "arrowdown",
+  "left",
+  "up",
+  "right",
+  "down",
+  "delete",
+  "insert",
+  "capslock",
+  "numlock",
+  "scrolllock",
+  "printscreen",
+  "pause",
 ]);
 
 /**

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

@@ -9,11 +9,12 @@ import { homedir } from "node:os";
 import { dirname } from "node:path";
 import { SandboxManager, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
 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 { askReadCandidates, extractBlockedPath, extractLoopbackEndpoint, isBlockedAccessError, isLoopbackConnectionRefused, isSafeFolderGrant, isWriteBlockError, matchedAskCommands, matchesPolicyPattern, outsideProjectMode, outsideProjectReadCandidates, outsideProjectReadDenied, sandboxFilesystem } from "../core/index";
 import { audit } from "../shared/audit";
 import { canonicalize } from "../shared/canonicalize";
 import { askMain, askMainWithRemember, askRememberFile, MainChoice, type AskCtx } from "../ui/ask-flow";
 import { loadConfig, projectTrusted } from "./config";
+import { injectBridgesIntoBwrap, startHostPortBridges, type HostPortBridge } from "./host-bridge";
 
 /** First whitespace-separated token of a bash command — used to name the binary in prompt titles. */
 function firstWord(command: string): string {
@@ -29,7 +30,7 @@ export interface SandboxedBashOpts {
 
 /** One denial shape for Layer 1, mirroring denyMessage() in Layer 2. */
 function blockedLine(action: "Read" | "Write", why: string, outcome: "read" | "written" | "run"): string {
-	return `❌ pi-sandbox: ${action} blocked by policy: ${why}. Nothing was ${outcome} — ask the user.`;
+	return `🛡️  pi-sandbox: ${action} blocked by policy: ${why}. Nothing was ${outcome}. Assistant guideline: Inform the user and ask if they wish to adjust the permission mode (/permission-mode); do not attempt workarounds or inspect plugin internals.`;
 }
 
 /** `Link` body row for a symlinked block path; empty when the spellings agree (ADR-035). */
@@ -76,11 +77,15 @@ async function preflightSensitiveCommands(
 	const matched = matchedAskCommands(command, ask, cwd, homedir());
 	if (!matched.length) return undefined;
 	const ui = opts.ctx as AskCtx;
-	const body = [
+	const bodyLines: string[] = [
 		`Command  ${matched.join(", ")}`,
 		`Risk     environment variables often hold API keys and tokens`,
 		`Note     can only be allowed one run at a time`,
-	].join("\n");
+	];
+	if (command.includes("\n")) {
+		bodyLines.push(`\nScript:\n${command}`);
+	}
+	const body = bodyLines.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") {
@@ -215,7 +220,26 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 			const grantedWriteFolders = new Set<string>();
 			const grantedWriteFiles = new Set<string>();
 			const attempt = async (writeOnce: string[]): Promise<{ exitCode: number | null }> => {
-				const wrappedCommand = await SandboxManager.wrapWithSandbox(command, undefined, buildCustom(writeOnce));
+				const cfg = loadConfig(cwd);
+				const allowLocalhost = cfg.allowLocalhost ?? cfg.network?.allowLocalhost ?? true;
+				let bridges: HostPortBridge[] = [];
+				if (!allowLocalhost && process.platform === "linux") {
+					const hostPorts = cfg.bridgeHostPorts ?? [3274];
+					bridges = await startHostPortBridges(hostPorts);
+				}
+				const rawWrapped = await SandboxManager.wrapWithSandbox(command, undefined, buildCustom(writeOnce));
+				let wrappedCommand = rawWrapped;
+				if (process.platform === "linux") {
+					if (allowLocalhost) {
+						wrappedCommand = wrappedCommand.replace(" --unshare-net ", " ");
+					} else if (bridges.length > 0) {
+						wrappedCommand = injectBridgesIntoBwrap(wrappedCommand, bridges);
+					}
+				}
+
+				const cleanupBridges = () => {
+					bridges.forEach((b) => b.close());
+				};
 
 				return new Promise((resolve, reject) => {
 					const child = spawn("bash", ["-c", wrappedCommand], {
@@ -251,11 +275,13 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 
 					child.on("error", (err) => {
 						if (timeoutHandle) clearTimeout(timeoutHandle);
+						cleanupBridges();
 						SandboxManager.cleanupAfterCommand();
 						reject(err);
 					});
 
 					const onAbort = () => {
+						cleanupBridges();
 						if (child.pid) {
 							try {
 								process.kill(-child.pid, "SIGKILL");
@@ -270,6 +296,7 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 					child.on("close", async (code) => {
 						if (timeoutHandle) clearTimeout(timeoutHandle);
 						signal?.removeEventListener("abort", onAbort);
+						cleanupBridges();
 
 						SandboxManager.cleanupAfterCommand();
 
@@ -300,32 +327,46 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 								}
 								readDenied = hardDenied || outsideDenied;
 							}
-							const configDirHint = offending && /\.config\/|\.kube\/|\.docker\/|\.netrc|\.aws\/|\.npmrc|\.gitconfig/.test(offending);
-
-							blockedHint = `\n💡 pi-sandbox: filesystem access blocked.\n`;
+							blockedHint = `\n🛡️  Security Policy Notice: filesystem access blocked by sandbox policy.\n`;
 							if (offending) {
 								let why = "";
-								if (writeDenied && !hardDenied) why = " (not under an allowWrite root: writes outside it are read-only)";
+								if (writeDenied && !hardDenied) why = " (writes outside allowWrite are read-only)";
 								else if (hardDenied) why = ` (${hardWhy})`;
-								else if (outsideDenied) why = " (outside the project: reading it is gated by policy)";
-								blockedHint += `   Path: ${offending}${why}\n`;
-								if (spelledOffending && spelledOffending !== offending) blockedHint += `   Link: ${spelledOffending} (symlink target shown as Path)\n`;
-							}
-							blockedHint += `   This is the pi sandbox (Layer 1), NOT macOS Full Disk Access / TCC.\n`;
-							if (configDirHint) {
-								blockedHint +=
-									`   Looks like a tool's own config dir. To allow this tool in the\n` +
-									`   current project, add a project-local policy:\n` +
-									`     mkdir -p ${cwd}/.pi && cat > ${cwd}/.pi/sandbox.json <<'JSON'\n` +
-									`     { "filesystem": { "allowWrite": [".", "${offending?.replace(/^~/, "$HOME") ?? "~/.config/<tool>"}"] } }\n` +
-									`     JSON\n` +
-									`   Or run pi with --yolo for one-off elevated access (disables ALL layers).\n`;
-							} else {
-								blockedHint +=
-									`   Use $TMPDIR (= ${piTmp}/) for scratch files,\n` +
-									`   or write inside the project directory (${cwd}).\n`;
+								else if (outsideDenied) why = " (outside the project directory)";
+								blockedHint += `   Target: ${offending}${why}\n`;
+								if (spelledOffending && spelledOffending !== offending) blockedHint += `   Link:   ${spelledOffending}\n`;
 							}
-							blockedHint += `   Policy: ~/.pi/agent/extensions/sandbox.json (+ <cwd>/.pi/sandbox.json overrides).\n`;
+							blockedHint +=
+								`   Explanation: The current sandbox policy restricts this operation to protect your system.\n` +
+								`   Guideline for Assistant:\n` +
+								`   • Stop and inform the user clearly about what was blocked.\n` +
+								`   • Ask the user if they wish to adjust the permission mode (/permission-mode) to allow this action.\n` +
+								`   • Do not inspect security plugin internals or attempt unauthorized bypasses.\n`;
+						} else if (code !== 0 && isLoopbackConnectionRefused(outputTail)) {
+							const endpointInfo = extractLoopbackEndpoint(outputTail, command);
+							const endpointStr = endpointInfo?.port ? `${endpointInfo.host}:${endpointInfo.port}` : (endpointInfo?.host ?? "127.0.0.1");
+							const serviceName = endpointInfo?.service;
+
+							auditL1({
+								subject: endpointStr,
+								decision: "loopback-refused",
+								reason: "Network namespace isolates host loopback under current policy",
+								cwd: opts?.ctx?.cwd,
+								note: serviceName ? `service:${serviceName}` : undefined,
+							});
+
+							const notifyMsg = serviceName
+								? `pi-sandbox: connection to ${serviceName} on ${endpointStr} was restricted by the sandbox.`
+								: `pi-sandbox: connection to host ${endpointStr} was restricted by the sandbox.`;
+							opts?.ctx?.ui?.notify?.(notifyMsg, "warning");
+
+							blockedHint = `\n🛡️  Security Policy Notice: Local network connection restricted.\n` +
+								`   Target: ${endpointStr}${serviceName ? ` (${serviceName})` : ""}\n` +
+								`   Explanation: The sandbox policy restricted access to this local host address.\n` +
+								`   Guideline for Assistant:\n` +
+								`   • Stop and inform the user clearly about what connection was restricted.\n` +
+								`   • Ask the user if they wish to adjust the permission mode (/permission-mode) to allow this action.\n` +
+								`   • Do not inspect security plugin internals or attempt unauthorized bypasses.\n`;
 						}
 						/**
 						 * Emit the block explanation only when the command is not re-run with a

package/src/l1-sandbox/config.ts

@@ -22,10 +22,18 @@ export interface SandboxFilesystem extends NonNullable<SandboxRuntimeConfig["fil
 	outsideProject?: { read?: ReadPosture; allowRead?: string[] };
 }
 
-export interface SandboxConfig extends Omit<SandboxRuntimeConfig, "filesystem"> {
+export interface SandboxNetwork extends Partial<NonNullable<SandboxRuntimeConfig["network"]>> {
+	/** Whether to allow localhost / loopback on all ports (default: true). Set false to strictly isolate network. */
+	allowLocalhost?: boolean;
+	/** Host TCP ports to bridge into the Linux sandbox namespace when allowLocalhost is false. */
+	bridgeHostPorts?: number[];
+}
+
+export interface SandboxConfig extends Omit<SandboxRuntimeConfig, "filesystem" | "network"> {
 	enabled?: boolean;
 	/** `default` = rules only; `advanced-secure` adds secret/credential detection (ADR-018). */
 	mode?: PermissionMode;
+	network?: SandboxNetwork;
 	filesystem?: SandboxFilesystem;
 	/**
 	 * Additive project-local overrides written by the ask-tier prompts (Layer 1
@@ -40,6 +48,14 @@ export interface SandboxConfig extends Omit<SandboxRuntimeConfig, "filesystem">
 	};
 	/** Commands/paths that can print secrets (env, proc environ) and must ask first. */
 	commands?: { ask?: string[] };
+	/** Allow all Unix domain sockets on Linux (disables seccomp socket blocking). */
+	allowAllUnixSockets?: boolean;
+	/** Allow local port binding. */
+	allowLocalBinding?: boolean;
+	/** Whether to allow localhost / loopback on all ports (default: true). Set false to strictly isolate network. */
+	allowLocalhost?: boolean;
+	/** Host TCP ports to bridge into the Linux sandbox namespace when allowLocalhost is false. */
+	bridgeHostPorts?: number[];
 }
 
 const BUILTIN_CONFIG: SandboxConfig = {
@@ -48,6 +64,8 @@ const BUILTIN_CONFIG: SandboxConfig = {
 	network: {
 		allowedDomains: [...BUILTIN_NETWORK_ALLOWED],
 		deniedDomains: [],
+		allowLocalhost: true,
+		allowAllUnixSockets: true,
 	},
 	filesystem: {
 		denyRead: [...DEFAULT_DENY_READ],

package/src/l1-sandbox/host-bridge.ts

@@ -0,0 +1,99 @@
+/**
+ * Host loopback port bridge for Linux sandbox.
+ *
+ * Bubblewrap on Linux isolates the network namespace via `--unshare-net`.
+ * In that isolated namespace, loopback `127.0.0.1` is disconnected from the host,
+ * preventing tools (like Diffusion Studio CLI `dapi` or local dev servers) from
+ * reaching services running on the host's localhost (e.g. port 3274).
+ *
+ * This module creates a lightweight Unix domain socket bridge on the host
+ * (using Node's built-in `node:net`), bind-mounts the socket into bwrap,
+ * and starts a `socat` listener inside the container forwarding container
+ * `127.0.0.1:${port}` to the host service.
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, unlinkSync } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface HostPortBridge {
+	port: number;
+	sockPath: string;
+	close: () => void;
+}
+
+/**
+ * Start a Unix domain socket bridge on the host forwarding to host 127.0.0.1:port.
+ */
+export async function startHostPortBridge(port: number): Promise<HostPortBridge> {
+	const id = randomBytes(6).toString("hex");
+	const sockPath = join(tmpdir(), `pi-host-bridge-${port}-${id}.sock`);
+
+	const server = net.createServer((client) => {
+		const target = net.connect(port, "127.0.0.1");
+		client.pipe(target).pipe(client);
+		client.on("error", () => target.destroy());
+		target.on("error", () => client.destroy());
+	});
+
+	await new Promise<void>((resolve, reject) => {
+		server.listen(sockPath, () => resolve());
+		server.on("error", reject);
+	});
+
+	return {
+		port,
+		sockPath,
+		close: () => {
+			try {
+				server.close();
+			} catch (err) {
+				void err;
+			}
+			try {
+				if (existsSync(sockPath)) unlinkSync(sockPath);
+			} catch (err) {
+				void err;
+			}
+		},
+	};
+}
+
+/**
+ * Start bridges for multiple ports concurrently.
+ */
+export async function startHostPortBridges(ports: number[]): Promise<HostPortBridge[]> {
+	if (process.platform !== "linux" || !ports.length) return [];
+	return Promise.all(ports.map((p) => startHostPortBridge(p)));
+}
+
+/**
+ * Inject the bridges into the bwrap command invocation on Linux.
+ */
+export function injectBridgesIntoBwrap(wrappedCommand: string, bridges: HostPortBridge[]): string {
+	if (process.platform !== "linux" || !bridges.length) return wrappedCommand;
+
+	const dashIndex = wrappedCommand.indexOf(" -- ");
+	if (dashIndex === -1) return wrappedCommand;
+
+	// 1. Add --bind for each socket before " -- "
+	const binds = bridges.map((b) => `--bind ${b.sockPath} ${b.sockPath}`).join(" ");
+	const bwrapPart = `${wrappedCommand.slice(0, dashIndex)} ${binds}`;
+	let shellPart = wrappedCommand.slice(dashIndex + 4);
+
+	// 2. Start socat listeners inside the container
+	const socatStarters = bridges
+		.map((b) => `socat TCP-LISTEN:${b.port},fork,reuseaddr UNIX-CONNECT:${b.sockPath} >/dev/null 2>&1 &\n_pi_bridge_pids="$_pi_bridge_pids $!"`)
+		.join("\n");
+
+	if (shellPart.includes("socat TCP-LISTEN:3128")) {
+		shellPart = shellPart.replace("socat TCP-LISTEN:3128", `${socatStarters}\nsocat TCP-LISTEN:3128`);
+		// Include our bridge pids in the script EXIT trap cleanup
+		shellPart = shellPart.replace("kill %1 %2 2>/dev/null;", "kill %1 %2 $_pi_bridge_pids 2>/dev/null;");
+		return `${bwrapPart} -- ${shellPart}`;
+	}
+
+	return wrappedCommand;
+}

package/src/l1-sandbox/manager.ts

@@ -36,11 +36,13 @@ const SUPPRESSED_PROJECT_FILES = new Set([
  */
 export function suppressGhostDotfiles(): void {
 	try {
+		/* SAFETY: DANGEROUS_FILES is an array of strings in sandbox-runtime. */
 		const files = DANGEROUS_FILES as unknown as string[];
 		const filteredFiles = files.filter((f) => !SUPPRESSED_PROJECT_FILES.has(f));
 		files.length = 0;
 		files.push(...filteredFiles);
 
+		/* SAFETY: DANGEROUS_DIRECTORIES is an array of strings in sandbox-runtime. */
 		const dirs = DANGEROUS_DIRECTORIES as unknown as string[];
 		const filteredDirs = dirs.filter((d) => d === ".git");
 		dirs.length = 0;
@@ -64,8 +66,18 @@ type Layer1FilesystemKind = typeof OverrideKind.AllowWrite | typeof OverrideKind
  * filesystem.outsideProject.read gates reads.
  */
 function runtimeConfig(cwd: string, config: SandboxConfig): SandboxRuntimeConfig {
+	const allowLocalhost = config.allowLocalhost ?? config.network?.allowLocalhost ?? true;
+	const allowAllUnixSockets = config.allowAllUnixSockets ?? config.network?.allowAllUnixSockets ?? true;
+	const network = config.network
+		? {
+				...config.network,
+				allowAllUnixSockets,
+				allowLocalBinding: config.allowLocalBinding ?? config.network.allowLocalBinding ?? allowLocalhost,
+			}
+		: undefined;
+
 	return {
-		network: config.network,
+		network: network as NonNullable<SandboxRuntimeConfig["network"]>,
 		filesystem: config.filesystem
 			? sandboxFilesystem(config.filesystem, { cwd, home: homedir() })
 			: { denyRead: [], allowRead: [], allowWrite: [], denyWrite: [], disabled: true },
@@ -87,7 +99,8 @@ export async function initSandbox(cwd: string, config: SandboxConfig, deps?: Net
 export async function resetSandbox(): Promise<void> {
 	try {
 		await SandboxManager.reset();
-	} catch {
+	} catch (err) {
+		void err;
 	}
 }
 

package/src/ui/ask-flow.ts

@@ -214,7 +214,17 @@ async function askWithSelect(
 	timeoutMs: number,
 	footer: string | null,
 ): Promise<{ picked: string | undefined; expired: boolean }> {
-	const selectTitle = footer ? `${title}\n\n${footer}` : title;
+	// Guard against terminal overflow in non-custom/RPC mode for long scripts
+	let boundedTitle = title;
+	const lines = title.split("\n");
+	const MAX_FALLBACK_LINES = 16;
+	if (lines.length > MAX_FALLBACK_LINES) {
+		const header = lines[0];
+		const preview = lines.slice(1, MAX_FALLBACK_LINES).join("\n");
+		boundedTitle = `${header}\n${preview}\n\n[... ${lines.length - MAX_FALLBACK_LINES} more lines truncated]`;
+	}
+
+	const selectTitle = footer ? `${boundedTitle}\n\n${footer}` : boundedTitle;
 	if (timeoutMs === 0) {
 		const picked = await ctx.ui.select(selectTitle, options);
 		return { picked, expired: false };

package/src/ui/ask-selector.ts

@@ -54,6 +54,8 @@ export type AskSelectorOptions = {
 	onExpire: () => void;
 	/** Countdown tick, default 1000 ms. Test seam. */
 	tickMs?: number;
+	/** Maximum body lines shown in viewport before scrolling engages. Default 12. */
+	maxBodyLines?: number;
 };
 
 /** A one-line horizontal rule, like pi's DynamicBorder but without the
@@ -70,6 +72,9 @@ class Border implements Component {
 	}
 }
 
+const SCROLL_UP_KEYS = new Set(["\x1b[5~", "[", "\x1b[1;2A"]);
+const SCROLL_DOWN_KEYS = new Set(["\x1b[6~", "]", "\x1b[1;2B"]);
+
 export class AskSelector extends Container {
 	private readonly theme: AskTheme;
 	private readonly tui: { requestRender(): void };
@@ -90,6 +95,14 @@ export class AskSelector extends Container {
 	private finished = false;
 	private engaged = false;
 
+	private readonly isMultiLine: boolean;
+	private readonly headerText: string;
+	private readonly bodyLines: string[];
+	private readonly maxBodyLines: number;
+	private readonly bodyComponent: Text | null = null;
+	private readonly indicatorComponent: Text | null = null;
+	private bodyScrollOffset = 0;
+
 	constructor(o: AskSelectorOptions) {
 		super();
 		this.theme = o.theme;
@@ -103,10 +116,35 @@ export class AskSelector extends Container {
 		this.labels = o.options;
 		this.footerVisible = o.footer !== null && o.footer !== "";
 		this.remaining = Math.ceil(o.timeoutMs / 1000);
+		this.maxBodyLines = o.maxBodyLines ?? 12;
+
+		const allLines = o.title.split("\n");
+		this.isMultiLine = allLines.length > 1;
+
+		if (this.isMultiLine) {
+			this.headerText = allLines[0] ?? "";
+			this.bodyLines = allLines.slice(1);
+		} else {
+			this.headerText = o.title;
+			this.bodyLines = [];
+		}
 
 		this.addChild(new Border((t) => this.theme.fg("border", t)));
 		this.addChild(new Spacer(1));
-		this.addChild(new Text(this.theme.fg("accent", this.theme.bold(o.title)), 0, 0));
+
+		if (!this.isMultiLine) {
+			this.addChild(new Text(this.theme.fg("accent", this.theme.bold(o.title)), 0, 0));
+		} else if (this.bodyLines.length <= this.maxBodyLines) {
+			this.addChild(new Text(this.theme.fg("accent", this.theme.bold(o.title)), 0, 0));
+		} else {
+			this.addChild(new Text(this.theme.fg("accent", this.theme.bold(this.headerText)), 0, 0));
+			this.addChild(new Spacer(1));
+			this.bodyComponent = new Text(this.renderBodySlice(), 0, 0);
+			this.addChild(this.bodyComponent);
+			this.indicatorComponent = new Text(this.renderScrollIndicator(), 0, 0);
+			this.addChild(this.indicatorComponent);
+		}
+
 		this.addChild(new Spacer(1));
 		if (this.footerVisible) {
 			this.footerText = new Text(this.footerValue(), 0, 0);
@@ -146,6 +184,17 @@ export class AskSelector extends Container {
 	}
 
 	handleInput(data: string): void {
+		if (this.bodyLines.length > this.maxBodyLines) {
+			const pageSize = Math.max(1, this.maxBodyLines - 2);
+			if (this.keybindings.matches(data, "tui.select.pageUp") || SCROLL_UP_KEYS.has(data)) {
+				this.scrollBody(-pageSize);
+				return;
+			}
+			if (this.keybindings.matches(data, "tui.select.pageDown") || SCROLL_DOWN_KEYS.has(data)) {
+				this.scrollBody(pageSize);
+				return;
+			}
+		}
 		if (this.keybindings.matches(data, "tui.select.up")) {
 			this.move(-1);
 			return;
@@ -157,15 +206,39 @@ export class AskSelector extends Container {
 		this.list.handleInput(data);
 	}
 
-	/**
-	 * Keyboard-only prompt (ADR-036). Deliberately does not call the inherited
-	 * Container dispatch: that would forward the event to the SelectList, which
-	 * picks the row a left click lands on and moves the highlight on wheel — a
-	 * stray click on the terminal could allow a call the user never chose.
-	 * Returning `undefined` means "not handled here"; the renderer may still use
-	 * the gesture for its own text selection, which cannot pick an answer.
-	 */
-	handleMouse(): undefined {
+	private renderBodySlice(): string {
+		const slice = this.bodyLines.slice(this.bodyScrollOffset, this.bodyScrollOffset + this.maxBodyLines);
+		return this.theme.fg("accent", this.theme.bold(slice.join("\n")));
+	}
+
+	private renderScrollIndicator(): string {
+		const total = this.bodyLines.length;
+		const start = this.bodyScrollOffset + 1;
+		const end = Math.min(total, this.bodyScrollOffset + this.maxBodyLines);
+		return this.theme.fg("muted", `[${start}–${end} of ${total} lines | [/] or Shift+↑/↓ or Scroll Wheel]`);
+	}
+
+	private scrollBody(delta: number): void {
+		if (this.bodyLines.length <= this.maxBodyLines) return;
+		const maxOffset = this.bodyLines.length - this.maxBodyLines;
+		const next = Math.max(0, Math.min(maxOffset, this.bodyScrollOffset + delta));
+		if (next === this.bodyScrollOffset) return;
+		this.bodyScrollOffset = next;
+		this.bodyComponent?.setText(this.renderBodySlice());
+		this.indicatorComponent?.setText(this.renderScrollIndicator());
+		this.onActivity();
+		this.tui.requestRender();
+	}
+
+	handleMouse(event: { type?: string; wheelDelta?: number }): undefined {
+		if (event?.type === "wheel" && Number.isFinite(event.wheelDelta)) {
+			if (this.bodyLines.length > this.maxBodyLines) {
+				const delta = event.wheelDelta;
+				if (delta !== undefined) {
+					this.scrollBody(delta > 0 ? 2 : -2);
+				}
+			}
+		}
 		return undefined;
 	}
 

package/src/ui/ask.ts

@@ -67,9 +67,59 @@ function actionOf(ask: AskKind): AskAction {
 	return AskAction.Read;
 }
 
-/** The reason without the trailing `→ /abs/path` (the body already shows the path). */
+/** Format the reason into plain, user-friendly language for non-technical users. */
 export function displayWhy(reason: string): string {
-	return reason.replace(/\s*→\s*.*$/, "");
+	const raw = reason.replace(/\s*→\s*.*$/, "").trim();
+
+	if (raw.startsWith("absolute-deny matched")) {
+		const pat = raw.match(/"([^"]+)"/)?.[1] ?? "";
+		if (pat.includes("ssh")) return `contains private SSH keys (${pat})`;
+		if (pat.includes("aws")) return `contains AWS credentials (${pat})`;
+		if (pat.includes("gnupg")) return `contains private encryption keys (${pat})`;
+		if (pat.includes("pem") || pat.includes("key")) return `contains private security keys (${pat})`;
+		if (pat.includes("auth.json")) return "holds login credentials";
+		return `contains sensitive credentials (${pat || "credentials"})`;
+	}
+
+	if (raw.startsWith("askRead matched")) {
+		const pat = raw.match(/"([^"]+)"/)?.[1] ?? "";
+		if (pat.includes(".env")) return ".env files usually hold passwords and API keys";
+		return `this file usually holds private passwords or API keys (${pat})`;
+	}
+
+	if (raw.startsWith("denyRead matched")) {
+		const pat = raw.match(/"([^"]+)"/)?.[1] ?? "";
+		if (pat.includes(".env")) return ".env files usually hold passwords and API keys";
+		return `protected by security rules from being read (${pat})`;
+	}
+
+	if (raw.startsWith("modelDenyRead matched")) {
+		const pat = raw.match(/"([^"]+)"/)?.[1] ?? "";
+		return `contains private data hidden from the AI (${pat})`;
+	}
+
+	if (raw.startsWith("denyWrite matched")) {
+		const pat = raw.match(/"([^"]+)"/)?.[1] ?? "";
+		return `protected file that cannot be modified (${pat})`;
+	}
+
+	if (raw.includes("not under any allowWrite root") || raw.includes("not under an allowWrite root")) {
+		return "saving files outside your project workspace requires permission";
+	}
+
+	if (raw.startsWith("outside the project")) {
+		return "reading files outside your project folder requires permission";
+	}
+
+	if (raw.startsWith("domain not in allowlist")) {
+		return "this site isn't on your allowed list yet";
+	}
+
+	if (raw === "blocked by the sandbox filesystem policy") {
+		return "restricted by your project's security policy";
+	}
+
+	return raw;
 }
 
 /** A domain reason without its `: host` suffix, so it can sit next to `Site:` without repeating it. */
@@ -79,9 +129,9 @@ export function networkWhy(reason: string): string {
 
 /** The model-facing denial text: one pattern for every block. */
 export function denyMessage(overrideKind: OverrideKind, reason: string): string {
-	if (overrideKind === "allowDomains") return `Network blocked by policy: ${networkWhy(reason)}. Nothing was fetched \u2014 ask the user.`;
-	if (overrideKind === "allowWrite") return `Write blocked by policy: ${displayWhy(reason)}. Nothing was written \u2014 ask the user.`;
-	return `Read blocked by policy: ${displayWhy(reason)}. Nothing was read \u2014 ask the user.`;
+	if (overrideKind === "allowDomains") return `Network blocked by policy: ${networkWhy(reason)}. Nothing was fetched \u2014 ask the user to adjust the permission mode (/permission-mode) if needed. Do not attempt workarounds or inspect plugin files.`;
+	if (overrideKind === "allowWrite") return `Write blocked by policy: ${displayWhy(reason)}. Nothing was written \u2014 ask the user to adjust the permission mode (/permission-mode) if needed. Do not attempt workarounds or inspect plugin files.`;
+	return `Read blocked by policy: ${displayWhy(reason)}. Nothing was read \u2014 ask the user to adjust the permission mode (/permission-mode) if needed. Do not attempt workarounds or inspect plugin files.`;
 }
 
 /**