auto-permission-system 3.12.0 → 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

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.12.0",
+  "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.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,7 +80,6 @@ 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" };
 }

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 `🛡️  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). */
@@ -327,32 +327,21 @@ 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");
@@ -361,42 +350,23 @@ 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
+								? `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💡 pi-sandbox: localhost / loopback connection refused.\n` +
+							blockedHint = `\n🛡️  Security Policy Notice: Local network connection restricted.\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`;
-							}
+								`   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

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