auto-permission-system 3.12.0 → 3.17.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
@@ -65,7 +65,7 @@ async function askDetection(
 	if (choice === "session") {
 		detectionGrants.add(key);
 		audit({ layer: 2, tool: kind, subject, reason, decision: "session", note: "advanced-secure", cwd: ctx.cwd });
-		ctx.ui.notify(`security-guard: allowed for this conversation (not saved) → ${subject}`, "info");
+		ctx.ui.notify(`Allowed for this conversation: ${subject}`, "info");
 		return null;
 	}
 	audit({ layer: 2, tool: kind, subject, reason, decision: "no", note: "advanced-secure", cwd: ctx.cwd });
@@ -130,24 +130,23 @@ export default function (pi: ExtensionAPI) {
 			if (!err) continue;
 			audit({ layer: 2, event: "policy-parse-error", file: p, error: err, cwd: ctx.cwd });
 			console.error(`security-guard: ${p} does not parse (${err}); its rules are NOT applied`);
-			ctx.ui.notify(`⚠️  security-guard: ${p} does not parse, so neither layer applies its rules (built-in defaults instead).\n${err}`, "error");
+			const isProject = p === `${ctx.cwd}/.pi/sandbox.json`;
+			const msg = isProject
+				? "⚠️  Syntax error in settings file — project configuration not loaded."
+				: "⚠️  Syntax error in settings file — global configuration not loaded.";
+			ctx.ui.notify(msg, "error");
 		}
 		setPiDeclinedTrust((ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted?.() === false);
 		const changes = untrustedProjectChanges(ctx.cwd);
 		if (changes.length && !isProjectFileDeclined(projectPolicyPath(ctx.cwd), TRUST_STORE)) {
 			audit({ layer: 2, event: "untrusted-project-policy", file: projectPolicyPath(ctx.cwd), changes, cwd: ctx.cwd });
-			ctx.ui.notify(
-				`⚠️  This folder has a .pi/sandbox.json that tries to make your security weaker:\n${bullets(changes)}\n` +
-					"auto-permission-system ignores these changes. Its block rules still apply.\n" +
-					"Did you write this file? Then type /security trust.",
-				"warning",
-			);
+			ctx.ui.notify("🛡️  Project-level configuration detected: run /security trust to approve.", "warning");
 		}
 		const policy = loadPolicy(ctx.cwd);
 		if (!policy.enabled) {
 			policyEnabled = false;
 			applyActive();
-			ctx.ui.notify("security-guard (Layer 2) disabled: enabled=false in sandbox.json", "info");
+			ctx.ui.notify("Tool guard is disabled in your sandbox.json settings.", "info");
 			return;
 		}
 		policyEnabled = true;
@@ -316,15 +315,15 @@ export default function (pi: ExtensionAPI) {
 			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 conversation.`, "info");
+				ctx.ui.notify(`Output permitted: allowed all ${programId} output for this conversation.`, "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");
+				ctx.ui.notify(`Output permitted: allowed ${event.toolName} output for this call.`, "info");
 			}
 			return;
 		}
 		audit({ layer: 2, tool: event.toolName, decision: "no", note: "advanced-secure-output", findings, cwd: ctx.cwd });
-		ctx.ui.notify(`🧠 Advanced Secure: blocked ${event.toolName} output — it may contain sensitive information. Nothing was sent to the model.`, "warning");
+		ctx.ui.notify(`Sensitive data protected: withheld ${event.toolName} output from the AI (potential secrets detected).`, "warning");
 		return { content: [{ type: "text", text: withheldNotice(subject) }] };
 	});
 

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.
@@ -72,27 +67,37 @@ function renderSandboxChip(ctx: ExtensionContext): void {
 }
 
 function modeNotice(mode: PermissionMode): { text: string; level: "info" | "warning" } {
-	if (mode === "yolo") return { text: "⚠️  YOLO — all security layers disabled. Saved; new conversations start this way too.", level: "warning" };
+	if (mode === "yolo") return { text: "🚨  YOLO — all security layers disabled. Saved; new conversations start this way too.", level: "warning" };
 	if (mode === "advanced-secure") return { text: "🧠 Advanced Secure on. File reads, MCP calls, and tool output are checked for secrets.", level: "info" };
 	return { text: "🛡 Default mode. Rule-based policy only.", level: "info" };
 }
 
 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;
 			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 conversation.", "warning");
+			ctx.ui.notify("🚨  YOLO — all security layers disabled for this conversation.", "warning");
 			return;
 		}
 		ctx.ui.notify(`Permission mode is already ${modeLabel(next)}.`, "info");

package/extensions/sandbox.ts

@@ -169,7 +169,7 @@ export default function (pi: ExtensionAPI) {
 		if (runtimeYolo) {
 			await stopSandbox();
 			ctx.ui.setStatus("sandbox", ctx.ui.theme.fg("error", YOLO_STATUS));
-			ctx.ui.notify(ctx.ui.theme.fg("error", "⚠️  YOLO mode — all pi security layers disabled."), "info");
+			ctx.ui.notify(ctx.ui.theme.fg("error", "🚨  YOLO mode — all pi security layers disabled."), "info");
 			return;
 		}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-permission-system",
-  "version": "3.12.0",
+  "version": "3.17.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.default.json

@@ -3,6 +3,7 @@
   "mode": "advanced-secure",
   "network": {
     "allowLocalhost": true,
+    "allowAllUnixSockets": true,
     "allowedDomains": [
       "registry.npmjs.org",
       "registry.yarnpkg.com",

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)**

package/src/core/policy/patterns.ts

@@ -57,13 +57,11 @@ export interface LoopbackEndpointInfo {
 export function extractLoopbackEndpoint(output: string, command?: string): LoopbackEndpointInfo | undefined {
 	if (!isLoopbackConnectionRefused(output)) return undefined;
 
-	// Check for Diffusion Studio specific error or command
 	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" };
 	}
 
-	// Match "Failed to connect to 127.0.0.1 port 3274" or "localhost port 8080"
 	const curlMatch = output.match(/Failed to connect to (127\.0\.0\.1|localhost|::1) port (\d+)/i);
 	if (curlMatch) {
 		return {
@@ -73,7 +71,6 @@ export function extractLoopbackEndpoint(output: string, command?: string): Loopb
 		};
 	}
 
-	// Match "connect ECONNREFUSED 127.0.0.1:3274"
 	const nodeMatch = output.match(/(?:ECONNREFUSED|connect to)\s+(127\.0\.0\.1|localhost|::1)(?::| port )(\d+)/i);
 	if (nodeMatch) {
 		return {
@@ -83,15 +80,16 @@ export function extractLoopbackEndpoint(output: string, command?: string): Loopb
 		};
 	}
 
-	// Generic host match
 	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(/[.,;]+$/, "");
-	if (!token || /^(bash|sh|zsh)$/.test(token)) return undefined;
+	let token = rawToken.trim().replace(/[.,;:]+$/, "");
+	if (!token || /^(bash|sh|zsh|EROFS)$/i.test(token)) return undefined;
+	token = token.replace(/\/EROFS$/i, "");
+	if (!token) return undefined;
 	if (token === "~" || token.startsWith("~/")) token = home + token.slice(1);
 	const absolute = token.startsWith("/") ? token : `${cwd.replace(/\/+$/, "")}/${token}`;
 	return normalizeAbs(absolute);

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

@@ -30,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 `[Security Policy Notice] ${action} blocked by policy: ${why}. Nothing was ${outcome}. Inform the user; do not attempt workarounds.`;
 }
 
 /** `Link` body row for a symlinked block path; empty when the spellings agree (ADR-035). */
@@ -93,7 +93,7 @@ async function preflightSensitiveCommands(
 		return undefined;
 	}
 	auditL1({ subject, decision: "no", note: "sensitive-command", cwd });
-	onData(Buffer.from(`\n❌ pi-sandbox: command blocked — it can print secrets: ${subject}. Nothing was run — ask the user.\n`));
+	onData(Buffer.from(`\n[Security Block] pi-sandbox: command blocked — it can print secrets: ${subject}. Nothing was run — ask the user.\n`));
 	return { exitCode: 1 };
 }
 
@@ -116,7 +116,7 @@ async function preflightAskReads(
 		if (sessionAskReadGrants.includes(absPath)) continue;
 		if (!ui?.hasUI || !ui.ui?.select) {
 			auditL1({ subject: absPath, decision: "no", note: "ask-read-headless", cwd });
-			onData(Buffer.from(`\n❌ pi-sandbox: sensitive file read blocked: ${absPath}. Nothing was run — ask the user.\n`));
+			onData(Buffer.from(`\n[Security Block] pi-sandbox: sensitive file read blocked: ${absPath}. Nothing was run — ask the user.\n`));
 			return { exitCode: 1 };
 		}
 		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"), { session: true, remember: false, icon: "cred" });
@@ -126,7 +126,7 @@ async function preflightAskReads(
 			continue;
 		}
 		auditL1({ subject: absPath, decision: "no", note: "ask-read", cwd });
-		onData(Buffer.from(`\n❌ pi-sandbox: sensitive file read blocked: ${absPath}. Nothing was run — ask the user.\n`));
+		onData(Buffer.from(`\n[Security Block] pi-sandbox: sensitive file read blocked: ${absPath}. Nothing was run — ask the user.\n`));
 		return { exitCode: 1 };
 	}
 	return undefined;
@@ -327,32 +327,10 @@ 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`;
-							if (offending) {
-								let why = "";
-								if (writeDenied && !hardDenied) why = " (not under an allowWrite root: writes outside it 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`;
-							}
-							blockedHint += `   Policy: ~/.pi/agent/extensions/sandbox.json (+ <cwd>/.pi/sandbox.json overrides).\n`;
+							let reason = "writes outside allowWrite are read-only";
+							if (hardDenied) reason = hardWhy;
+							else if (outsideDenied) reason = "target is outside the project directory";
+							blockedHint = `\n[Security Policy Notice] filesystem access blocked by sandbox policy: ${writeDenied ? "Write" : "Read"} access to ${offending ?? "target"} is restricted.\nReason: ${reason}. Inform the user; do not attempt workarounds.\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");
@@ -361,42 +339,17 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 							auditL1({
 								subject: endpointStr,
 								decision: "loopback-refused",
-								reason: "Linux sandbox network namespace (--unshare-net) isolates host loopback",
+								reason: "Network namespace isolates host loopback under current policy",
 								cwd: opts?.ctx?.cwd,
 								note: serviceName ? `service:${serviceName}` : undefined,
 							});
 
-							const notifyMsg = serviceName === "Diffusion Studio"
-								? "pi-sandbox: Diffusion Studio is running on host port 3274, but sandboxed bash cannot reach host localhost. Connect it via MCP in ~/.pi/agent/mcp.json."
-								: `pi-sandbox: connection to host ${endpointStr} refused. Sandboxed bash cannot reach host localhost.`;
+							const notifyMsg = serviceName
+								? `Local network notice: connection to ${serviceName} (${endpointStr}) was blocked by security policy.`
+								: `Local network notice: connection to host ${endpointStr} was blocked by security policy.`;
 							opts?.ctx?.ui?.notify?.(notifyMsg, "warning");
 
-							blockedHint = `\n💡 pi-sandbox: localhost / loopback connection refused.\n` +
-								`   Target: ${endpointStr}${serviceName ? ` (${serviceName})` : ""}\n` +
-								`   Why: The Linux sandbox runs inside an isolated network namespace (--unshare-net).\n` +
-								`        Services running on your HOST's 127.0.0.1/localhost are isolated and cannot\n` +
-								`        be reached directly from sandboxed bash commands.\n`;
-
-							if (serviceName === "Diffusion Studio" || /dapi|diffusion|3274/i.test(command)) {
-								blockedHint +=
-									`   Resolution for Diffusion Studio:\n` +
-									`   • Diffusion Studio exposes an MCP server on http://127.0.0.1:3274/mcp\n` +
-									`   • Add it to ~/.pi/agent/mcp.json so Pi connects directly on the host:\n` +
-									`       {\n` +
-									`         "mcpServers": {\n` +
-									`           "diffusion-studio": { "url": "http://127.0.0.1:3274/mcp" }\n` +
-									`         }\n` +
-									`       }\n` +
-									`   • Once added, restart or reload Pi: the agent gets native MCP tools\n` +
-									`     (context, check, capture, probe) with Layer 2 security, no bash needed.\n` +
-									`   • Or run pi with --yolo for one-off host access.\n`;
-							} else {
-								blockedHint +=
-									`   Resolution:\n` +
-									`   • If this is an MCP service, configure it in ~/.pi/agent/mcp.json.\n` +
-									`   • Pi runs on the host and can communicate with local MCP servers directly.\n` +
-									`   • Or run pi with --yolo if this task requires interacting with host network services.\n`;
-							}
+							blockedHint = `\n[Security Policy Notice] Connection to ${endpointStr}${serviceName ? ` (${serviceName})` : ""} blocked by sandbox policy.\nReason: Local network connections are restricted. Inform the user; do not attempt workarounds.\n`;
 						}
 						/**
 						 * Emit the block explanation only when the command is not re-run with a
@@ -416,8 +369,8 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 						if (sandboxSetupError && !hardDenied && !outsideDenied && (!offending || offending === cwd || offending.startsWith(`${cwd}/`))) {
 							blockedHint = "";
 							auditL1({ subject: offending ?? spelledOffending, decision: "write-denied", reason: "the OS sandbox could not start (bwrap mount setup)", cwd: opts?.ctx?.cwd, note: "sandbox-setup-error" });
-							opts?.ctx?.ui?.notify?.(`pi-sandbox: the OS sandbox could not start (bwrap could not create ${offending ?? spelledOffending ?? "a protected mount point"}). This is a sandbox setup problem, not a policy denial.`, "warning");
-							decisionHint = `\n❌ pi-sandbox: the OS sandbox could not start (bwrap could not create a protected mount point), so nothing was permission-prompted. This is a sandbox setup problem, not a policy denial.\n`;
+							opts?.ctx?.ui?.notify?.(`Sandbox setup notice: could not prepare folder isolation for ${offending ?? spelledOffending ?? "the sandbox"}. System defaults will be used.`, "warning");
+							decisionHint = `\n[System Error] pi-sandbox: the OS sandbox could not start (bwrap could not create a protected mount point), so nothing was permission-prompted. This is a sandbox setup problem, not a policy denial.\n`;
 							onData(Buffer.from(decisionHint));
 						} else if (offending && outsideDenied && !hardDenied && outsideMode === "ask" && opts?.ctx?.hasUI && opts.ctx.ui?.select && opts.onAlwaysRead) {
 							const absPath = offending;
@@ -437,8 +390,8 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 									if (choice === MainChoice.Once) readOnce.push(absPath);
 									else sessionReadGrants.push(absPath);
 									auditL1({ subject: absPath, decision: choice, scope: choice === MainChoice.Once ? "invocation" : "session", cwd: opts.ctx.cwd, note: "outside-project-read" });
-									opts.ctx.ui?.notify?.(`pi-sandbox: allowed read of ${absPath} ${choice === MainChoice.Once ? "once" : "for this conversation"} — re-running the command`, "warning");
-									onData(Buffer.from(`\n✅ pi-sandbox: read of ${absPath} allowed ${choice === MainChoice.Once ? "once" : "for this conversation"}. Command output with the new permission follows.\n`));
+									opts.ctx.ui?.notify?.(`pi-sandbox: allowed read of ${absPath} ${choice === MainChoice.Once ? "once" : "for this conversation"}`, "info");
+									onData(Buffer.from(`\n[Permission Granted] pi-sandbox: read of ${absPath} allowed ${choice === MainChoice.Once ? "once" : "for this conversation"}. Command output with the new permission follows.\n`));
 									resolve(attempt([]));
 									return;
 								}
@@ -447,13 +400,13 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 									try {
 										const persistedTo = await opts.onAlwaysRead(subject, grant.scope);
 										auditL1({ subject, granularity: grant.folder ? "folder" : "file", original: absPath, decision: grant.scope === "cwd" ? "always-cwd" : "always-global", scope: grant.scope, cwd: opts.ctx.cwd, persisted_to: persistedTo, note: "outside-project-read" });
-										opts.ctx.ui?.notify?.(`pi-sandbox: allowed read of ${subject} (${grant.scope}${grant.folder ? ", folder" : ""}) — re-running the command`, "warning");
-										onData(Buffer.from(`\n✅ pi-sandbox: read of ${subject} allowed (${grant.scope}${grant.folder ? ", folder" : ""}). Command output with the new permission follows.\n`));
+										opts.ctx.ui?.notify?.(`pi-sandbox: allowed read of ${subject} (${grant.scope}${grant.folder ? ", folder" : ""})`, "info");
+										onData(Buffer.from(`\n[Permission Granted] pi-sandbox: read of ${subject} allowed (${grant.scope}${grant.folder ? ", folder" : ""}). Command output with the new permission follows.\n`));
 										resolve(attempt([]));
 										return;
 									} catch (e) {
 										auditL1({ subject, scope: grant.scope, cwd: opts.ctx.cwd, error: String(e), note: "outside-project-read" });
-										decisionHint = `\n❌ pi-sandbox: could not save the permission (${e}). ${subject} remains blocked.\n`;
+										decisionHint = `\n[Security Notice] pi-sandbox: could not save the permission (${e}). ${subject} remains blocked.\n`;
 									}
 								}
 							} catch (e) {
@@ -475,12 +428,13 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 							const action: "Read" | "Write" = writeDenied ? "Write" : "Read";
 							const outcome = action === "Write" ? "written" : "read";
 							auditL1({ subject: offending, decision: readDenied && !writeDenied ? "read-denied" : "write-denied", reason: why, cwd });
-							opts?.ctx?.ui?.notify?.(`pi-sandbox: bash was refused a ${action.toLowerCase()} of ${offending} (${why}). Edit sandbox.json if that is wrong.`, "warning");
+							opts?.ctx?.ui?.notify?.(`Folder protected: unable to ${action.toLowerCase()} ${offending}. Location is restricted under current policy.`, "warning");
 							decisionHint = `\n${blockedLine(action, why, outcome)}\n`;
 							onData(Buffer.from(decisionHint));
 						} else if (offending && writeGrantRepeated && writeGrantParent) {
 							auditL1({ subject: offending, decision: "write-denied", reason: `grant for ${writeGrantParent} did not take effect`, cwd: opts?.ctx?.cwd, note: "grant-ineffective" });
-							opts?.ctx?.ui?.notify?.(`pi-sandbox: the write grant for ${writeGrantParent} did not take effect — the sandbox still refuses ${offending}.`, "warning");
+							const targetFolder = (writeGrantParent || offending || "").replace(/\/EROFS$/i, "");
+							opts?.ctx?.ui?.notify?.(`🚧  Folder protected: unable to write to ${targetFolder} under sandbox policy. Review sandbox.json or /permission-mode.`, "warning");
 							decisionHint = `\n${blockedLine("Write", `the grant for ${writeGrantParent} did not take effect`, "written")}\n`;
 							onData(Buffer.from(decisionHint));
 						} else if (offending && opts?.ctx?.hasUI && opts.ctx.ui?.select && opts.onAlways) {
@@ -502,8 +456,8 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 								if (choice === MainChoice.Once) {
 									grantedWriteFolders.add(parentDir);
 									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");
-									onData(Buffer.from(`\n✅ pi-sandbox: write to ${absPath} allowed once. Command output with the new permission follows.\n`));
+									opts.ctx.ui?.notify?.(`pi-sandbox: allowed write to ${absPath} once`, "info");
+									onData(Buffer.from(`\n[Permission Granted] pi-sandbox: write to ${absPath} allowed once. Command output with the new permission follows.\n`));
 									resolve(attempt([...writeOnce, parentDir]));
 									return;
 								}
@@ -512,8 +466,8 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 									sessionWriteGrants.push(value);
 									(value === parentDir ? grantedWriteFolders : grantedWriteFiles).add(value);
 									auditL1({ subject: value, granularity: value === parentDir ? "folder" : "file", original: absPath, decision: "session", scope: "session", cwd: opts.ctx.cwd, note: "write-session" });
-									opts.ctx.ui?.notify?.(`pi-sandbox: allowed ${value} for this conversation (not saved) — re-running the command`, "info");
-									onData(Buffer.from(`\n✅ pi-sandbox: write to ${value} allowed for this conversation. Command output with the new permission follows.\n`));
+									opts.ctx.ui?.notify?.(`pi-sandbox: allowed write to ${value} for this conversation`, "info");
+									onData(Buffer.from(`\n[Permission Granted] pi-sandbox: write to ${value} allowed for this conversation. Command output with the new permission follows.\n`));
 									resolve(attempt([]));
 									return;
 								}
@@ -523,14 +477,14 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 										const persistedTo = await opts.onAlways(subject, grant.scope);
 										(grant.folder ? grantedWriteFolders : grantedWriteFiles).add(subject);
 										auditL1({ subject, granularity: grant.folder ? "folder" : "file", original: absPath, decision: grant.scope === "cwd" ? "always-cwd" : "always-global", scope: grant.scope, cwd: opts.ctx.cwd, persisted_to: persistedTo });
-										opts.ctx.ui?.notify?.(`pi-sandbox: allowed ${subject} (${grant.scope}${grant.folder ? ", folder" : ""}) — re-running the command`, "warning");
-										onData(Buffer.from(`\n✅ pi-sandbox: write to ${subject} allowed (${grant.scope}${grant.folder ? ", folder" : ""}). Command output with the new permission follows.\n`));
+										opts.ctx.ui?.notify?.(`pi-sandbox: allowed write to ${subject} (${grant.scope}${grant.folder ? ", folder" : ""})`, "info");
+										onData(Buffer.from(`\n[Permission Granted] pi-sandbox: write to ${subject} allowed (${grant.scope}${grant.folder ? ", folder" : ""}). Command output with the new permission follows.\n`));
 										resolve(attempt([]));
 										return;
 									} catch (e) {
 										auditL1({ subject, granularity: grant.folder ? "folder" : "file", original: absPath, scope: grant.scope, cwd: opts.ctx.cwd, error: String(e) });
 										opts.ctx.ui?.notify?.(`pi-sandbox: could not save the permission (${e})`, "error");
-										decisionHint = `\n❌ pi-sandbox: could not save the permission (${e}). ${subject} remains blocked.\n`;
+										decisionHint = `\n[Security Notice] pi-sandbox: could not save the permission (${e}). ${subject} remains blocked.\n`;
 									}
 								}
 							} catch (e) {
@@ -549,7 +503,7 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 							onData(Buffer.from(decisionHint));
 						} else if (offending && writeDenied) {
 							auditL1({ subject: offending, decision: "write-denied", reason: "not under any allowWrite root", cwd });
-							opts?.ctx?.ui?.notify?.(`pi-sandbox: bash was refused a write of ${offending} (not under any allowWrite root).`, "warning");
+							opts?.ctx?.ui?.notify?.(`Folder protected: unable to write to ${offending}. Location is outside allowed project folders.`, "warning");
 							onData(Buffer.from(`\n${blockedLine("Write", "not under any allowWrite root", "written")}\n`));
 						}
 

package/src/l1-sandbox/config.ts

@@ -65,6 +65,7 @@ const BUILTIN_CONFIG: SandboxConfig = {
 		allowedDomains: [...BUILTIN_NETWORK_ALLOWED],
 		deniedDomains: [],
 		allowLocalhost: true,
+		allowAllUnixSockets: true,
 	},
 	filesystem: {
 		denyRead: [...DEFAULT_DENY_READ],

package/src/l1-sandbox/manager.ts

@@ -67,10 +67,11 @@ type Layer1FilesystemKind = typeof OverrideKind.AllowWrite | typeof OverrideKind
  */
 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: config.allowAllUnixSockets ?? config.network.allowAllUnixSockets,
+				allowAllUnixSockets,
 				allowLocalBinding: config.allowLocalBinding ?? config.network.allowLocalBinding ?? allowLocalhost,
 			}
 		: undefined;

package/src/l1-sandbox/network-ask.ts

@@ -161,7 +161,7 @@ async function decide(deps: NetworkAskDeps, host: string, port: number | undefin
 	if (mainChoice === MainChoice.Session) {
 		sessionGrants.push(wildcard);
 		deps.audit({ ...base, decision: "session", grant: wildcard, requested: host });
-		ctx.ui.notify?.(`pi-sandbox: allowed for this conversation (not saved) → ${wildcard}`, "info");
+		ctx.ui.notify?.(`Allowed for this conversation: ${wildcard}`, "info");
 		return true;
 	}
 
@@ -176,11 +176,12 @@ async function decide(deps: NetworkAskDeps, host: string, port: number | undefin
 		const path = await deps.persist(pattern, scope);
 		deps.applyLive(pattern);
 		deps.audit({ ...base, decision: scope === GrantScope.Cwd ? "always-cwd" : "always-global", scope, persisted_to: path, pattern, requested: host });
-		ctx.ui.notify?.(`pi-sandbox: persisted ${scope} override → ${path}`, "warning");
+		const scopeLabel = scope === GrantScope.Cwd ? "this project (stored in project settings)" : "all projects (stored in global settings)";
+		ctx.ui.notify?.(`Rule saved for ${scopeLabel}.`, "info");
 	} catch (error) {
 		commandGrants?.add(host);
 		deps.audit({ ...base, decision: "yes", note: `always-persist-failed: ${error}`, scope });
-		ctx.ui.notify?.(`pi-sandbox: could not persist ${scope} override (${error}); allowing this command only`, "warning");
+		ctx.ui.notify?.(`Could not save rule for ${scope === GrantScope.Cwd ? "this project" : "all projects"} (${error}); allowing this command only.`, "warning");
 	}
 	return true;
 }

package/src/l2-guard/prompts.ts

@@ -87,7 +87,7 @@ export async function askOrBlock(
 			const named = userNamedOutside(ctx as SessionCtx, ask);
 			if (named) {
 				audit({ layer: 2, tool: ask.tool, subject: ask.subject, reason: ask.reason, decision: "user-named", named, cwd: ctx.cwd });
-				ctx.ui.notify(`security-guard: read outside the project allowed once → ${ask.subject} (you named "${named}")`, "info");
+				ctx.ui.notify(`Allowed reading ${ask.subject} once (mentioned in your prompt).`, "info");
 				return null;
 			}
 		}
@@ -102,7 +102,7 @@ export async function askOrBlock(
 		const value = ask.overrideKind === OverrideKind.AllowDomains || isSafeFolderGrant(parent, homedir()) ? parent : ask.overrideValue;
 		sessionGrants.push({ kind: ask.overrideKind, value });
 		audit({ layer: 2, tool: ask.tool, subject: ask.subject, reason: ask.reason, decision, grant: value, cwd: ctx.cwd });
-		ctx.ui.notify(`security-guard: allowed for this conversation (not saved) → ${value}`, "info");
+		ctx.ui.notify(`Allowed for this conversation: ${value}`, "info");
 		return null;
 	}
 	if (decision === Decision.AlwaysCwd || decision === Decision.AlwaysGlobal || decision === Decision.AlwaysCwdFolder || decision === Decision.AlwaysGlobalFolder) {
@@ -117,10 +117,11 @@ export async function askOrBlock(
 			const path = persistOverride(scope, ctx.cwd, ask.overrideKind, value);
 			onPersist?.(ask.overrideKind, value, scope);
 			audit({ layer: 2, tool: ask.tool, subject: ask.subject, reason: ask.reason, decision, scope, granularity: useFolder ? "folder" : "file", cwd: ctx.cwd, persisted_to: path, override: { [ask.overrideKind]: value } });
-			ctx.ui.notify(`security-guard: persisted ${scope}${useFolder ? " (folder)" : ""} override → ${path}`, "warning");
+			const scopeLabel = scope === GrantScope.Cwd ? "this project (stored in project settings)" : "all projects (stored in global settings)";
+			ctx.ui.notify(`Rule saved for ${scopeLabel}.`, "info");
 		} catch (error) {
 			audit({ layer: 2, tool: ask.tool, subject: ask.subject, reason: ask.reason, decision: "yes", note: `always-persist-failed: ${error}`, scope, cwd: ctx.cwd });
-			ctx.ui.notify(`security-guard: could not persist ${scope} override (${error}); allowing this call only`, "warning");
+			ctx.ui.notify(`Could not save rule for ${scope === GrantScope.Cwd ? "this project" : "all projects"} (${error}); allowing this call only.`, "warning");
 		}
 		return null;
 	}

package/src/l2-guard/subagent.ts

@@ -21,7 +21,7 @@ export function subagentNetworkBlock(ctx: { hasUI?: boolean; sessionManager?: un
 	if (ctx.hasUI !== false) return null;
 	const mode = policy.subagent?.network ?? SubagentNetwork.Allow;
 	if (mode === SubagentNetwork.Allow) return null;
-	if (mode === SubagentNetwork.Deny) return "Network blocked by policy: subagent.network=deny. Nothing was fetched — ask the user.";
+	if (mode === SubagentNetwork.Deny) return "[Security Policy Notice] Network access blocked: automated subagent network connections are restricted. Nothing was fetched. Inform the user; do not attempt workarounds.";
 	if (mode === SubagentNetwork.ResearchOnly) {
 		const sessionManager = ctx.sessionManager as { getBranch?: () => Array<{ type: string; text?: string }> } | undefined;
 		const branch = sessionManager?.getBranch?.() ?? [];
@@ -31,7 +31,7 @@ export function subagentNetworkBlock(ctx: { hasUI?: boolean; sessionManager?: un
 			.join(" ")
 			.toLowerCase();
 		for (const agent of RESEARCH_AGENTS) if (recentText.includes(agent)) return null;
-		return "Network blocked by policy: subagent.network=research-only. Nothing was fetched — ask the user.";
+		return "[Security Policy Notice] Network access restricted: subagents may only connect to approved research domains. Nothing was fetched. Inform the user; do not attempt workarounds.";
 	}
 	return null;
 }

package/src/shared/yolo.ts

@@ -26,7 +26,7 @@
 export const YOLO_CHANNEL = "auto-permission-system:yolo";
 
 /** Footer text shown while every layer is disabled. */
-export const YOLO_STATUS = "⚠️  YOLO — all security layers disabled";
+export const YOLO_STATUS = "🚨  YOLO — all security layers disabled";
 
 /** The pi APIs this module needs; kept structural so tests can fake them. */
 export interface YoloFlagPI {

package/src/ui/ask-flow.ts

@@ -482,7 +482,7 @@ export async function askExposure(ctx: AskCtx, hits: string[], programId?: strin
  */
 export function withheldNotice(subject: string): string {
 	return [
-		`\u26a0 Output from \`${subject}\` was withheld because it may contain sensitive information.`,
+		`[Security Policy Notice] Output from \`${subject}\` was withheld because it contains sensitive credentials.`,
 		"",
 		"The tool completed successfully, but the output is unavailable.",
 		"Continue with the available information, or ask the user to allow access if the output is needed.",

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.`;
 }
 
 /**