pi-sentry 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# pi-sentry
+
+A permission/impact gate extension for pi.
+
+It classifies every tool call (including `bash`) as **low / medium / high** impact, then allows, prompts, or blocks based on the active permission level.
+
+## Permission levels (enforcement behavior)
+
+- **low**
+  - auto-allows only known **low-impact** operations
+- **medium**
+  - auto-allows known **low + medium-impact** operations
+- **YOLO**
+  - bypasses classification and authorization checks
+
+## Tool classification summary
+
+From current implementation:
+
+- `read`, `grep`, `find`, `ls` → **low**
+- `edit` → **low**
+- `write` → **medium**
+- other non-bash tools → **medium + unknown** (requires prompt/block path)
+- `bash`:
+  - classify via rules in `rules.ts` (including compound command splitting and highest-impact selection)
+  - AI fallback is used **only** for unknown bash commands
+  - if AI is unavailable, unknown bash defaults to **high**
+
+## Usage
+
+- Keyboard shortcut: cycles levels (`low → medium → YOLO`) and persists the selected level.
+- Set shortcut from pi: `/pi-sentry <key>` (example: `/pi-sentry ctrl+shift+p`)
+  - takes effect after `/reload` (or restarting pi)
+  - use `/pi-sentry <key> --reload` to apply immediately
+- CLI flag: `--permission-level <low|medium|YOLO>` (applies to current run)
+
+## Configuration
+
+`pi-sentry` merges config in this order (later wins):
+
+1. Built-in defaults
+2. `config.default.json` (packaged with extension)
+3. Global user config: `~/.pi/agent/pi-sentry/config.json`
+4. Project override: `.pi/pi-sentry/config.json`
+
+### Config fields
+
+```json
+{
+  "cycle_shortcut": "shift+tab",
+  "level": "medium"
+}
+```
+
+- `cycle_shortcut`: keybinding used for cycling permission levels
+- `level`: initial level (`low`, `medium`, or `YOLO`)
+
+> Backward compatibility: legacy key `cycle_shorcut` is still accepted.
+
+## Testing
+
+From `pi-sentry/`:
+
+```bash
+npm run test:tool-assessment
+```

package/config.default.json

@@ -0,0 +1,4 @@
+{
+	"cycle_shortcut": "shift+tab",
+	"level": "medium"
+}

package/index.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { registerPermissionSystem } from "./src/permissions.js";
+
+export default function (pi: ExtensionAPI) {
+	registerPermissionSystem(pi);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pi-sentry",
+  "version": "1.0.0",
+  "description": "Permission/impact gate extension for pi coding agent",
+  "main": "index.ts",
+  "scripts": {
+    "test:tool-assessment": "npx --yes tsx --test test/tool-assessment.test.ts"
+  },
+  "keywords": [
+    "pi-coding-agent",
+    "extension",
+    "security",
+    "permissions"
+  ],
+  "author": "ElwinLiu",
+  "license": "MIT",
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-ai": "*"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config.default.json",
+    "rules.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/rules.ts

@@ -0,0 +1,154 @@
+import type { Rule } from "./types.js";
+
+// Rule coverage is based on common command behavior documented by upstream/manual sources:
+// GNU coreutils (ls/rm), Git docs (push/reset), Docker docs (publish ports),
+// Kubernetes docs (kubectl apply), systemctl man page, npm lifecycle scripts, and Terraform command refs.
+const LOW_IMPACT_RULES: Rule[] = [
+	// Display / introspection
+	{ pattern: /^\s*(echo|printf)\b/i, reason: "display" },
+	{ pattern: /^\s*(pwd|whoami|id|groups|date|uname|hostname|uptime)\b/i, reason: "system info" },
+	{ pattern: /^\s*(env|printenv|which|type)\b/i, reason: "environment info" },
+	{ pattern: /^\s*(ls|tree)\b/i, reason: "read-only listing" },
+	{ pattern: /^\s*(cat|less|more|head|tail|wc|stat|file)\b/i, reason: "read-only file" },
+	{ pattern: /^\s*cd\b/i, reason: "directory navigation" },
+	{ pattern: /^\s*sed\b(?![^\n]*\s-i\b)/i, reason: "text processing" },
+	{ pattern: /^\s*(grep|egrep|fgrep|awk|cut|sort|uniq|tr|column|nl)\b/i, reason: "text processing" },
+	{ pattern: /^\s*find\b(?![^\n]*\s-(delete|exec|execdir|ok|okdir)\b)/i, reason: "file discovery" },
+
+	// Process, network, resource inspection
+	{ pattern: /^\s*(ps|top|htop|pgrep|pstree|lsof|ss|netstat|df|du|free|vmstat|iostat|dmesg)\b/i, reason: "runtime inspection" },
+	{ pattern: /^\s*(md5sum|sha1sum|sha256sum|sha512sum|cksum|b2sum)\b/i, reason: "checksums" },
+
+	// Git read-only operations
+	{ pattern: /^\s*git\s+(status|log|show|diff|blame|grep|rev-parse|rev-list|ls-files|ls-tree|cat-file)\b/i, reason: "read-only git" },
+	{ pattern: /^\s*git\s+branch\b(?!([^\n]*\s-[dDmM]))/i, reason: "read-only git branch view" },
+	{ pattern: /^\s*git\s+tag\b(?!([^\n]*\s-d\b))/i, reason: "read-only git tag view" },
+	{ pattern: /^\s*git\s+remote\s+-v\b/i, reason: "read-only git remote view" },
+	{ pattern: /^\s*git\s+stash\s+list\b/i, reason: "read-only git stash view" },
+
+	// Package manager read-only queries
+	{ pattern: /^\s*(npm|pnpm|yarn)\s+(ls|list|outdated|info|view)\b/i, reason: "package query" },
+	{ pattern: /^\s*(pip|pip3)\s+(list|show|freeze)\b/i, reason: "package query" },
+	{ pattern: /^\s*(brew)\s+(list|info|search)\b/i, reason: "package query" },
+	{ pattern: /^\s*(apt|apt-cache)\s+(list|search|show|policy)\b/i, reason: "package query" },
+
+	// GitHub CLI read-only queries
+	{ pattern: /^\s*gh\s+(--version|version|help|auth\s+status|repo\s+view|issue\s+view|pr\s+view|run\s+view|run\s+list|api\s+\/repos\/[^\s]+\/[^\s]+\/actions\/runs)\b/i, reason: "github query" },
+
+	// Infra/container read-only queries
+	{ pattern: /^\s*docker\s+(ps|images|inspect|logs|stats|top|events|version|info)\b/i, reason: "container query" },
+	{ pattern: /^\s*kubectl\s+(get|describe|logs|api-resources|api-versions|version|config\s+view)\b/i, reason: "cluster query" },
+	{ pattern: /^\s*helm\s+(list|status|history|get)\b/i, reason: "release query" },
+	{ pattern: /^\s*terraform\s+(validate|show|plan)\b/i, reason: "infra plan/query" },
+];
+
+const MEDIUM_IMPACT_RULES: Rule[] = [
+	// Local file mutations (usually recoverable)
+	{ pattern: /\b(touch|mkdir|rmdir|cp|mv|ln|install)\b/i, reason: "file mutation" },
+	{ pattern: /^\s*sed\b[^\n]*\s-i\b/i, reason: "in-place file edit" },
+	{ pattern: /(^|[^\u003c])\u003e(?!\u003e)/, reason: "redirect write" },
+	{ pattern: /\u003e\u003e/, reason: "redirect append" },
+	{ pattern: /\btee\b/i, reason: "write via tee" },
+
+	// Git local history/index mutations (recoverable with effort)
+	{ pattern: /^\s*git\s+(add|restore|checkout|switch|commit|merge|rebase|cherry-pick|revert|pull|fetch|stash(?!\s+list\b))\b/i, reason: "git mutation" },
+
+	// Language/package ecosystem mutations
+	{ pattern: /^\s*(npm|pnpm|yarn)\s+(install|add|update|upgrade|remove|rm|uninstall|ci)\b/i, reason: "package mutation" },
+	{ pattern: /^\s*npx\b/i, reason: "one-off package/script execution" },
+	{ pattern: /^\s*(pip|pip3)\s+(install|uninstall)\b/i, reason: "package mutation" },
+	{ pattern: /^\s*(cargo|go|gem|bundle|poetry|uv)\s+(install|add|get|update|remove|sync)\b/i, reason: "package/toolchain mutation" },
+	{ pattern: /^\s*terraform\s+fmt\b/i, reason: "source formatting mutation" },
+
+	// Build/test execution (side effects typically local)
+	{ pattern: /^\s*(make|cmake|ninja|meson|mvn|gradle|\.\/gradlew)\b/i, reason: "build pipeline" },
+	{ pattern: /^\s*(pytest|jest|vitest)\b/i, reason: "test run" },
+	{ pattern: /^\s*(go\s+test|cargo\s+test)\b/i, reason: "test run" },
+	{ pattern: /^\s*(npm|pnpm|yarn)\s+run\s+\S+/i, reason: "script run" },
+
+	// Service/container operations with local side effects
+	{ pattern: /^\s*(systemctl|service|launchctl)\s+(start|stop|restart|reload|enable|disable)\b/i, reason: "service state mutation" },
+	{ pattern: /^\s*docker\s+(build|pull|compose\s+(up|down|build|pull)|start|stop|restart|rm|rmi|run)\b/i, reason: "container mutation" },
+];
+
+const HIGH_IMPACT_RULES: Rule[] = [
+	// Privilege escalation / identity changes
+	{ pattern: /\b(sudo|doas|su|pkexec)\b/i, reason: "elevated privileges" },
+	{ pattern: /\b(useradd|userdel|usermod|groupadd|groupdel|passwd)\b/i, reason: "identity/security mutation" },
+
+	// Irreversible/destructive filesystem & disk actions
+	{ pattern: /(^\s*rm\b|\bxargs\b[^\n]*\brm\b)/i, reason: "destructive delete" },
+	{ pattern: /\b(shred|wipefs|mkfs(?:\.\w+)?|fdisk|parted|sgdisk)\b/i, reason: "disk/filesystem destructive action" },
+	{ pattern: /\bdd\b[^\n]*\bof=\/dev\//i, reason: "raw disk write" },
+	{ pattern: /\btruncate\b/i, reason: "destructive truncate" },
+	{ pattern: /^\s*diskutil\s+erase/i, reason: "disk erase" },
+
+	// Security-sensitive permission/firewall/system tuning actions
+	{ pattern: /\b(chown|chgrp|chmod|setfacl|setcap|visudo|chattr)\b/i, reason: "permission/security mutation" },
+	{ pattern: /\b(ufw|iptables|nft|firewall-cmd|pfctl|sysctl)\b/i, reason: "network/system security mutation" },
+	{ pattern: /\b(reboot|shutdown|halt|poweroff|init\s+[06])\b/i, reason: "system availability impact" },
+
+	// Remote code execution patterns
+	{ pattern: /\bcurl\b[^|\n]*\|\s*(bash|sh|zsh|fish)\b/i, reason: "remote execution" },
+	{ pattern: /\bwget\b[^|\n]*\|\s*(bash|sh|zsh|fish)\b/i, reason: "remote execution" },
+	{ pattern: /\biwr\b[^|\n]*\|\s*iex\b/i, reason: "remote execution" },
+	{ pattern: /\binvoke-webrequest\b[^|\n]*\|\s*invoke-expression\b/i, reason: "remote execution" },
+	{ pattern: /\beval\b/i, reason: "dynamic execution" },
+
+	// Remote mutation / exposure
+	{ pattern: /\bgit\s+push\b/i, reason: "remote mutation" },
+	{ pattern: /^\s*gh\s+(issue\s+(create|edit|close|reopen|delete)|pr\s+(create|merge|close|reopen|ready|review)|repo\s+(create|delete|rename|edit)|release\s+create|secret\s+set|variable\s+set|workflow\s+run|run\s+rerun|api\s+.*\b(POST|PUT|PATCH|DELETE)\b)/i, reason: "github remote mutation" },
+	{ pattern: /\bgit\s+reset\b[^\n]*--hard\b/i, reason: "destructive history rewrite" },
+	{ pattern: /\bgit\s+clean\b[^\n]*\s-f\b/i, reason: "destructive workspace clean" },
+	{ pattern: /\bgit\s+branch\b[^\n]*\s-[dD]\b/i, reason: "branch deletion" },
+	{ pattern: /\bgit\s+tag\b[^\n]*\s-d\b/i, reason: "tag deletion" },
+	{ pattern: /\b(docker\s+run\b[^\n]*(\s-p\s|\s--publish\s|\s--network\s+host\b|\s--privileged\b)|kubectl\s+port-forward\b|ssh\s+-R\b|nc\b[^\n]*\s-l\b|socat\b[^\n]*\bLISTEN\b|ngrok\b|cloudflared\b|localtunnel\b)/i, reason: "port exposure" },
+
+	// Infra orchestration / destructive remote control
+	{ pattern: /\bterraform\s+(apply|destroy|state\s+rm|taint|import)\b/i, reason: "infra mutation" },
+	{ pattern: /\bkubectl\s+(apply|create|delete|replace|patch|edit|scale|set|drain|cordon|uncordon|rollout\s+(restart|undo))\b/i, reason: "cluster mutation" },
+	{ pattern: /\bhelm\s+(install|upgrade|rollback|uninstall|delete)\b/i, reason: "release mutation" },
+	{ pattern: /\bansible-playbook\b/i, reason: "remote orchestration mutation" },
+
+	// System package manager changes (broad machine impact)
+	{ pattern: /\b(apt(?:-get)?|dnf|yum|pacman|zypper)\s+(install|upgrade|dist-upgrade|remove|purge|autoremove)\b/i, reason: "system package mutation" },
+	{ pattern: /\bbrew\s+(install|upgrade|uninstall|tap|untap|services\s+(start|stop|restart))\b/i, reason: "system package/service mutation" },
+
+	// Database destructive intent
+	{ pattern: /\b(drop|truncate|delete|destroy|wipe)\b[^\n]*\b(table|database|schema|collection|index|prod|production|db|sensitive)\b/i, reason: "database/data destructive action" },
+];
+
+const PRIORITIZED_RULESETS = [
+	{ level: "high", rules: HIGH_IMPACT_RULES },
+	{ level: "medium", rules: MEDIUM_IMPACT_RULES },
+	{ level: "low", rules: LOW_IMPACT_RULES },
+] as const;
+
+/**
+ * Classify a single command using the rule-based system.
+ * Assumes command is already normalized (trimmed, single spaces).
+ * Returns the assessment with unknown: true if no rules match.
+ */
+export function classifyCommandByRules(normalized: string): {
+	level: "low" | "medium" | "high";
+	reason: string;
+	unknown: boolean;
+} {
+	if (!normalized) {
+		return { level: "low", unknown: false, reason: "empty" };
+	}
+
+	for (const ruleset of PRIORITIZED_RULESETS) {
+		for (const rule of ruleset.rules) {
+			if (rule.pattern.test(normalized)) {
+				return { level: ruleset.level, unknown: false, reason: rule.reason };
+			}
+		}
+	}
+
+	return {
+		level: "medium",
+		unknown: true,
+		reason: "unmapped command",
+	};
+}

package/src/ai-assessment.ts

@@ -0,0 +1,154 @@
+import { complete, type Message } from "@mariozechner/pi-ai";
+import { buildSessionContext, convertToLlm } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { isImpactLevel } from "./types.js";
+import type { AiImpactClassification, ImpactAssessment } from "./types.js";
+
+const BASH_SOURCE = "agent:bash";
+
+const AI_IMPACT_ASSESSOR_USER_INSTRUCTIONS = [
+	"Permission impact assessment task.",
+	"Classify the single bash command described below as low, medium, or high impact.",
+	"Use prior conversation messages as context for escalation (prod, secrets, destructive intent, remote impact, privilege/security impact).",
+	"Definitions:",
+	"- low: read-only inspection/query operations with no meaningful mutation.",
+	"- medium: mostly local or recoverable mutations.",
+	"- high: security-sensitive, destructive, privileged, remote-mutating, or hard-to-reverse actions.",
+	"Rules:",
+	"- If uncertain, pick the HIGHER impact.",
+	"- Return JSON only: {\"level\":\"low|medium|high\"}",
+].join("\n");
+
+function truncateForPrompt(value: string, maxLength = 1200): string {
+	if (value.length <= maxLength) return value;
+	return `${value.slice(0, maxLength)}...`;
+}
+
+function coerceAiImpactClassification(value: unknown): AiImpactClassification | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as { level?: unknown };
+	const level = typeof record.level === "string" ? record.level.toLowerCase() : "";
+	if (!isImpactLevel(level)) {
+		return undefined;
+	}
+	return { level };
+}
+
+function parseAiImpactClassification(raw: string): AiImpactClassification | undefined {
+	const trimmed = raw.trim();
+	if (!trimmed) return undefined;
+
+	try {
+		const parsed = JSON.parse(trimmed);
+		const normalized = coerceAiImpactClassification(parsed);
+		if (normalized) return normalized;
+	} catch {
+		// fall through
+	}
+
+	const jsonBlockMatch = trimmed.match(/\{[\s\S]*\}/);
+	if (!jsonBlockMatch) return undefined;
+
+	try {
+		return coerceAiImpactClassification(JSON.parse(jsonBlockMatch[0]));
+	} catch {
+		return undefined;
+	}
+}
+
+function buildConversationMessages(ctx: ExtensionContext): Message[] {
+	const entries = ctx.sessionManager.getEntries();
+	const leafId = ctx.sessionManager.getLeafId();
+	const sessionContext = buildSessionContext(entries, leafId);
+	return convertToLlm(sessionContext.messages);
+}
+
+function buildAssessmentMessage(assessment: ImpactAssessment): Message {
+	const text = [
+		AI_IMPACT_ASSESSOR_USER_INSTRUCTIONS,
+		"",
+		"<bash_command>",
+		`base_level_from_rules: ${assessment.level}`,
+		`unknown_from_rules: ${assessment.unknown}`,
+		`source: ${assessment.source}`,
+		`command: ${truncateForPrompt(assessment.operation)}`,
+		`previous_rule_reason: ${truncateForPrompt(assessment.reason, 600)}`,
+		"</bash_command>",
+	].join("\n");
+
+	return {
+		role: "user",
+		content: [{ type: "text", text }],
+		timestamp: Date.now(),
+	};
+}
+
+async function getApiAccess(ctx: ExtensionContext): Promise<{ model: NonNullable<ExtensionContext["model"]>; apiKey: string } | undefined> {
+	const model = ctx.model;
+	if (!model) return undefined;
+
+	const apiKey = await ctx.modelRegistry.getApiKey(model);
+	if (!apiKey) return undefined;
+
+	return { model, apiKey };
+}
+
+async function getClassificationFromModel(
+	ctx: ExtensionContext,
+	assessment: ImpactAssessment,
+): Promise<AiImpactClassification | undefined> {
+	const access = await getApiAccess(ctx);
+	if (!access) return undefined;
+
+	const conversationMessages = buildConversationMessages(ctx);
+	const requestMessage = buildAssessmentMessage(assessment);
+
+	try {
+		const response = await complete(
+			access.model,
+			{
+				systemPrompt: ctx.getSystemPrompt(),
+				messages: [...conversationMessages, requestMessage],
+			},
+			{
+				apiKey: access.apiKey,
+				sessionId: ctx.sessionManager.getSessionId(),
+			},
+		);
+
+		const output = response.content
+			.filter((part): part is { type: "text"; text: string } => part.type === "text" && typeof part.text === "string")
+			.map((part) => part.text)
+			.join("\n");
+
+		return parseAiImpactClassification(output);
+	} catch {
+		return undefined;
+	}
+}
+
+export class AiAssessor {
+	async assessBashImpact(assessment: ImpactAssessment, ctx: ExtensionContext): Promise<ImpactAssessment> {
+		if (assessment.source !== BASH_SOURCE || !assessment.unknown) {
+			return assessment;
+		}
+
+		const classified = await getClassificationFromModel(ctx, assessment);
+		if (!classified) {
+			return {
+				...assessment,
+				level: "high",
+				unknown: false,
+				reason: "ai-unavailable-default-high-bash",
+			};
+		}
+
+		return {
+			...assessment,
+			level: classified.level,
+			unknown: false,
+			reason: "ai-classified-bash",
+		};
+	}
+}

package/src/config-loader.ts

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { DEFAULT_LEVEL, isPermissionLevel } from "./types.js";
+import type { PermissionLevel } from "./types.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const packageDefaultConfigPath = join(__dirname, "..", "config.default.json");
+const legacyPackageUserConfigPath = join(__dirname, "..", "config.json");
+
+const globalConfigPath = join(homedir(), ".pi", "agent", "pi-sentry", "config.json");
+
+function getProjectConfigPath(cwd = process.cwd()): string {
+	return resolve(cwd, ".pi", "pi-sentry", "config.json");
+}
+
+export interface Config {
+	cycle_shortcut: string;
+	level: PermissionLevel;
+}
+
+type RawConfig = {
+	cycle_shortcut?: unknown;
+	// Backward compatibility for older typo in released config files.
+	cycle_shorcut?: unknown;
+	level?: unknown;
+};
+
+const DEFAULT_CONFIG: Config = {
+	cycle_shortcut: "shift+tab",
+	level: DEFAULT_LEVEL,
+};
+
+function readJsonFile(path: string): Record<string, unknown> {
+	try {
+		const content = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(content) as unknown;
+		return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+	} catch {
+		return {};
+	}
+}
+
+function getShortcut(raw: RawConfig): string | undefined {
+	if (typeof raw.cycle_shortcut === "string") return raw.cycle_shortcut;
+	if (typeof raw.cycle_shorcut === "string") return raw.cycle_shorcut;
+	return undefined;
+}
+
+function normalizeConfig(raw: RawConfig): Config {
+	const level = isPermissionLevel(raw.level) ? raw.level : DEFAULT_LEVEL;
+	const cycle_shortcut = getShortcut(raw) ?? DEFAULT_CONFIG.cycle_shortcut;
+	return {
+		cycle_shortcut,
+		level,
+	};
+}
+
+function loadUserOverrides(cwd = process.cwd()): RawConfig {
+	const legacyOverrides = readJsonFile(legacyPackageUserConfigPath) as RawConfig;
+	const globalOverrides = readJsonFile(globalConfigPath) as RawConfig;
+	const projectOverrides = readJsonFile(getProjectConfigPath(cwd)) as RawConfig;
+	return { ...legacyOverrides, ...globalOverrides, ...projectOverrides };
+}
+
+export function loadConfig(options?: { cwd?: string }): Config {
+	const cwd = options?.cwd ?? process.cwd();
+	const defaults = readJsonFile(packageDefaultConfigPath) as RawConfig;
+	const userOverrides = loadUserOverrides(cwd);
+	return normalizeConfig({ ...DEFAULT_CONFIG, ...defaults, ...userOverrides });
+}
+
+function ensureParentDir(path: string): void {
+	const parent = dirname(path);
+	if (existsSync(parent)) return;
+	mkdirSync(parent, { recursive: true });
+}
+
+function writeGlobalOverrides(patch: RawConfig): boolean {
+	try {
+		const globalOverrides = readJsonFile(globalConfigPath) as RawConfig;
+		const next: RawConfig = { ...globalOverrides, ...patch };
+		ensureParentDir(globalConfigPath);
+		writeFileSync(globalConfigPath, `${JSON.stringify(next, null, "\t")}\n`, "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function savePermissionLevel(level: PermissionLevel): boolean {
+	if (!isPermissionLevel(level)) return false;
+	return writeGlobalOverrides({ level });
+}
+
+export function saveCycleShortcut(shortcut: string): boolean {
+	if (typeof shortcut !== "string" || shortcut.trim().length === 0) return false;
+	return writeGlobalOverrides({ cycle_shortcut: shortcut.trim() });
+}
+
+export function getGlobalConfigPath(): string {
+	return globalConfigPath;
+}
+
+export function getProjectConfigPathForDisplay(cwd = process.cwd()): string {
+	return getProjectConfigPath(cwd);
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const PERMISSION_LEVEL_FLAG = "permission-level" as const;

package/src/index.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { registerPermissionSystem } from "./permissions.js";
+
+export default function (pi: ExtensionAPI) {
+	registerPermissionSystem(pi);
+}

package/src/level-store.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { PERMISSION_LEVEL_FLAG } from "./constants.js";
+import { getGlobalConfigPath, loadConfig, savePermissionLevel } from "./config-loader.js";
+import { cycleLevel, DEFAULT_LEVEL, isPermissionLevel } from "./types.js";
+import type { PermissionLevel } from "./types.js";
+import { renderPermissionWidget } from "./ui.js";
+
+export type SetPermissionLevelOptions = {
+	persist?: boolean;
+	notify?: boolean;
+};
+
+function normalizePermissionLevel(value: unknown): PermissionLevel | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim().toLowerCase();
+	return isPermissionLevel(normalized) ? normalized : undefined;
+}
+
+function parsePermissionLevelFlag(pi: ExtensionAPI): PermissionLevel | undefined {
+	return (
+		normalizePermissionLevel(pi.getFlag(PERMISSION_LEVEL_FLAG)) ??
+		normalizePermissionLevel(pi.getFlag(`--${PERMISSION_LEVEL_FLAG}`))
+	);
+}
+
+export class PermissionLevelStore {
+	private level: PermissionLevel = DEFAULT_LEVEL;
+	private latestContext: ExtensionContext | undefined;
+
+	constructor(private readonly pi: ExtensionAPI) {}
+
+	get current(): PermissionLevel {
+		return this.level;
+	}
+
+	setLatestContext(ctx: ExtensionContext): void {
+		this.latestContext = ctx;
+	}
+
+	/**
+	 * Initializes the store from config and CLI flags.
+	 *
+	 * Does not persist/notify (session start should be quiet).
+	 */
+	init(ctx: ExtensionContext): void {
+		this.latestContext = ctx;
+
+		const config = loadConfig({ cwd: ctx.cwd });
+		this.level = config.level;
+
+		const fromFlag = parsePermissionLevelFlag(this.pi);
+		if (fromFlag) {
+			this.level = fromFlag;
+		}
+
+		renderPermissionWidget(ctx, this.level);
+	}
+
+	set(nextLevel: PermissionLevel, ctx: ExtensionContext, options?: SetPermissionLevelOptions): void {
+		const changed = this.level !== nextLevel;
+
+		this.level = nextLevel;
+		this.latestContext = ctx;
+
+		if (changed && options?.persist !== false) {
+			const persisted = savePermissionLevel(nextLevel);
+			if (!persisted) {
+				ctx.ui.notify(`Failed to persist permission level to ${getGlobalConfigPath()}`, "error");
+			}
+		}
+
+		renderPermissionWidget(ctx, nextLevel);
+
+		if (options?.notify !== false) {
+			ctx.ui.notify(`Permission level: ${nextLevel.toUpperCase()}`, "info");
+		}
+	}
+
+	cycle(options?: SetPermissionLevelOptions): void {
+		if (!this.latestContext) return;
+		this.set(cycleLevel(this.level), this.latestContext, { notify: false, ...options });
+	}
+}

package/src/permissions.ts

@@ -0,0 +1,111 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { PERMISSION_LEVEL_FLAG } from "./constants.js";
+import { AiAssessor } from "./ai-assessment.js";
+import { PermissionLevelStore } from "./level-store.js";
+import { authorize, classifyToolCall } from "./tool-assessment.js";
+import { setPermissionBadgeRenderer } from "./ui.js";
+import { getGlobalConfigPath, loadConfig, saveCycleShortcut } from "./config-loader.js";
+
+const PERMISSION_BADGE_RENDERER_SET_EVENT = "permission:ui:badge-renderer:set" as const;
+const PERMISSION_BADGE_RENDERER_REQUEST_EVENT = "permission:ui:badge-renderer:request" as const;
+
+type PermissionBadgeRendererPayload = {
+	renderBadge: (theme: unknown, label: string) => string | undefined;
+};
+
+function isPermissionBadgeRendererPayload(value: unknown): value is PermissionBadgeRendererPayload {
+	if (!value || typeof value !== "object") return false;
+	const record = value as Partial<PermissionBadgeRendererPayload>;
+	return typeof record.renderBadge === "function";
+}
+
+export function registerPermissionSystem(pi: ExtensionAPI): void {
+	const levelStore = new PermissionLevelStore(pi);
+	const aiAssessor = new AiAssessor();
+	const config = loadConfig();
+
+	setPermissionBadgeRenderer(undefined);
+
+	pi.events.on(PERMISSION_BADGE_RENDERER_SET_EVENT, (payload) => {
+		if (!isPermissionBadgeRendererPayload(payload)) return;
+		setPermissionBadgeRenderer((theme, label) => payload.renderBadge(theme, label));
+	});
+
+	// Ask UI extensions to (re)register renderers, regardless of load order.
+	pi.events.emit(PERMISSION_BADGE_RENDERER_REQUEST_EVENT, {});
+
+	pi.registerFlag(PERMISSION_LEVEL_FLAG, {
+		description: "Permission level: low | medium | YOLO",
+		type: "string",
+	});
+
+	pi.registerShortcut(config.cycle_shortcut, {
+		description: "Cycle through permission levels (low → medium → YOLO)",
+		handler: () => {
+			levelStore.cycle();
+		},
+	});
+
+	pi.registerCommand("pi-sentry", {
+		description: "Set pi-sentry cycle shortcut (example: /pi-sentry ctrl+shift+p)",
+		handler: async (args, ctx) => {
+			const rawArgs = (args ?? "").trim();
+			if (!rawArgs) {
+				const current = loadConfig({ cwd: ctx.cwd }).cycle_shortcut;
+				ctx.ui.notify(`Current shortcut: ${current}`, "info");
+				ctx.ui.notify("Usage: /pi-sentry <key> [--reload]", "info");
+				return;
+			}
+
+			const parts = rawArgs.split(/\s+/).filter(Boolean);
+			const reloadNow = parts.includes("--reload");
+			const shortcutParts = parts.filter((part) => part !== "--reload");
+			const nextShortcut = shortcutParts.join(" ").trim();
+
+			if (!nextShortcut) {
+				ctx.ui.notify("Usage: /pi-sentry <key> [--reload]", "info");
+				return;
+			}
+
+			if (!saveCycleShortcut(nextShortcut)) {
+				ctx.ui.notify(`Failed to persist shortcut to ${getGlobalConfigPath()}`, "error");
+				return;
+			}
+
+			if (reloadNow) {
+				ctx.ui.notify(`Saved shortcut: ${nextShortcut}. Reloading...`, "info");
+				await ctx.reload();
+				return;
+			}
+
+			ctx.ui.notify(`Saved shortcut: ${nextShortcut}`, "info");
+			ctx.ui.notify("It will take effect after /reload (or restart pi).", "info");
+			return;
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		levelStore.init(ctx);
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		return {
+			systemPrompt: `${event.systemPrompt}\n\nPermission policy active. Current level: ${levelStore.current.toUpperCase()}. Unknown bash command impacts are AI-classified from operation semantics and conversation intent. Other tools use fixed mappings/rules. YOLO level bypasses all checks.`,
+		};
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		levelStore.setLatestContext(ctx);
+
+		// YOLO mode: bypass all classification and authorization
+		if (levelStore.current === "YOLO") {
+			return undefined;
+		}
+
+		const assessment = await classifyToolCall(event, ctx, aiAssessor);
+		const decision = await authorize(assessment, levelStore.current, ctx);
+		if (decision.allowed) return undefined;
+		return { block: true, reason: decision.reason ?? "Blocked by permission policy" };
+	});
+}

package/src/tool-assessment.ts

@@ -0,0 +1,199 @@
+import type { ToolCallEvent, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { AiAssessor } from "./ai-assessment.js";
+import { classifyCommandByRules } from "../rules.js";
+import { askUserPermission } from "./ui.js";
+import { isImpactAtMost, maxImpactLevel } from "./types.js";
+import type { ImpactAssessment, ImpactLevel, PermissionLevel } from "./types.js";
+
+const READ_ONLY_TOOLS = new Set(["read", "grep", "find", "ls"]);
+const WRITE_TOOLS = new Set(["write"]);
+const EDIT_TOOLS = new Set(["edit"]);
+const BASH_SOURCE = "agent:bash";
+
+function truncateForPrompt(value: string, maxLength = 300): string {
+	if (value.length <= maxLength) return value;
+	return `${value.slice(0, maxLength)}...`;
+}
+
+function getStringProp(input: unknown, key: string): string | undefined {
+	if (!input || typeof input !== "object") return undefined;
+	const record = input as Record<string, unknown>;
+	const value = record[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+function serializeForOperation(input: unknown): string {
+	try {
+		const serialized = JSON.stringify(input);
+		if (!serialized) return "";
+		return truncateForPrompt(serialized);
+	} catch {
+		return "";
+	}
+}
+
+function normalizeCommand(command: string): string {
+	return command.trim().replace(/\s+/g, " ");
+}
+
+/**
+ * Split a compound command into individual commands based on common shell separators.
+ * Assumes command is already normalized.
+ */
+function splitCompoundCommands(normalized: string): string[] {
+	if (!normalized) return [];
+	return normalized
+		.split(/\s*(?:&&|\|\||;|\|&|\||&|\n)\s*/)
+		.map((part) => part.trim())
+		.filter(Boolean);
+}
+
+function toImpactAssessment(normalized: string, result: ReturnType<typeof classifyCommandByRules>): ImpactAssessment {
+	return {
+		level: result.level,
+		source: BASH_SOURCE,
+		operation: normalized,
+		unknown: result.unknown,
+		reason: result.reason,
+	};
+}
+
+function pickMoreImpactful(current: ImpactAssessment, candidate: ImpactAssessment): ImpactAssessment {
+	const higherLevel = maxImpactLevel(current.level, candidate.level);
+	if (higherLevel !== current.level) return candidate;
+	if (higherLevel !== candidate.level) return current;
+	if (current.unknown && !candidate.unknown) return candidate;
+	return current;
+}
+
+function summarizeAssessment(assessment: ImpactAssessment): string {
+	const operation = truncateForPrompt(assessment.operation, 30);
+	return `${operation}(${assessment.level})`;
+}
+
+/**
+ * Rule-only bash classification.
+ * Classifies the full command and each sub-command, then returns the highest impact.
+ */
+function classifyBashByRules(command: string): ImpactAssessment {
+	const normalized = normalizeCommand(command);
+	if (!normalized) {
+		return { level: "low", source: BASH_SOURCE, operation: "", unknown: false, reason: "empty" };
+	}
+
+	const overallAssessment = toImpactAssessment(normalized, classifyCommandByRules(normalized));
+	const subCommands = splitCompoundCommands(normalized);
+
+	if (subCommands.length <= 1) {
+		return overallAssessment;
+	}
+
+	let highestAssessment = overallAssessment;
+	const reasonParts: string[] = [`whole:${summarizeAssessment(overallAssessment)}`];
+
+	for (const subCommand of subCommands) {
+		const assessment = toImpactAssessment(subCommand, classifyCommandByRules(subCommand));
+		highestAssessment = pickMoreImpactful(highestAssessment, assessment);
+		reasonParts.push(`part:${summarizeAssessment(assessment)}`);
+	}
+
+	return {
+		...highestAssessment,
+		operation: normalized,
+		unknown: highestAssessment.unknown,
+		reason: `compound: ${reasonParts.join("; ")}`,
+	};
+}
+
+/**
+ * Classify a bash command with rule-based analysis + AI fallback for unknown commands.
+ */
+async function classifyBash(command: string, ctx: ExtensionContext, aiAssessor: AiAssessor): Promise<ImpactAssessment> {
+	const ruleAssessment = classifyBashByRules(command);
+	if (!ruleAssessment.unknown) {
+		return ruleAssessment;
+	}
+	return aiAssessor.assessBashImpact(ruleAssessment, ctx);
+}
+
+/**
+ * Unified function to classify any tool call.
+ */
+export async function classifyToolCall(
+	event: ToolCallEvent,
+	ctx: ExtensionContext,
+	aiAssessor: AiAssessor,
+): Promise<ImpactAssessment> {
+	let assessment: ImpactAssessment;
+
+	if (event.toolName === "bash") {
+		const command = getStringProp(event.input, "command") ?? "";
+		return classifyBash(command, ctx, aiAssessor);
+	} else if (READ_ONLY_TOOLS.has(event.toolName)) {
+		assessment = {
+			level: "low",
+			source: `agent:${event.toolName}`,
+			operation: event.toolName,
+			unknown: false,
+			reason: "read-only tool",
+		};
+	} else if (EDIT_TOOLS.has(event.toolName)) {
+		const path = getStringProp(event.input, "path") ?? "(unknown path)";
+		assessment = {
+			level: "low",
+			source: `agent:${event.toolName}`,
+			operation: `${event.toolName} ${path}`,
+			unknown: false,
+			reason: "edit tool",
+		};
+	} else if (WRITE_TOOLS.has(event.toolName)) {
+		const path = getStringProp(event.input, "path") ?? "(unknown path)";
+		assessment = {
+			level: "medium",
+			source: `agent:${event.toolName}`,
+			operation: `${event.toolName} ${path}`,
+			unknown: false,
+			reason: "write tool",
+		};
+	} else {
+		const serializedInput = serializeForOperation(event.input);
+		const operation = serializedInput ? `${event.toolName} ${serializedInput}` : event.toolName;
+		assessment = {
+			level: "medium",
+			source: `agent:${event.toolName}`,
+			operation,
+			unknown: true,
+			reason: "unmapped tool",
+		};
+	}
+
+	return assessment;
+}
+
+export async function authorize(
+	assessment: ImpactAssessment,
+	level: PermissionLevel,
+	ctx: ExtensionContext,
+): Promise<{ allowed: boolean; reason?: string }> {
+	// Map permission level to max allowed impact level
+	const maxAllowedImpact: ImpactLevel = level === "medium" ? "medium" : "low";
+	const thresholdAllows = !assessment.unknown && isImpactAtMost(assessment.level, maxAllowedImpact);
+	if (thresholdAllows) {
+		return { allowed: true };
+	}
+
+	const baseReason = assessment.unknown
+		? "Blocked unknown-impact operation"
+		: `Blocked ${assessment.level}-impact operation`;
+
+	if (!ctx.hasUI) {
+		return {
+			allowed: false,
+			reason: `${baseReason}: ${assessment.operation}`,
+		};
+	}
+
+	const ok = await askUserPermission(ctx, assessment);
+	return ok ? { allowed: true } : { allowed: false, reason: baseReason };
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+export const LEVELS = ["low", "medium", "YOLO"] as const;
+export type PermissionLevel = (typeof LEVELS)[number];
+
+// Impact levels for command classification (separate from permission levels)
+export const IMPACT_LEVELS = ["low", "medium", "high"] as const;
+export type ImpactLevel = (typeof IMPACT_LEVELS)[number];
+
+export type Rule = {
+	pattern: RegExp;
+	reason: string;
+};
+
+export type ImpactAssessment = {
+	level: ImpactLevel;
+	source: string;
+	operation: string;
+	unknown: boolean;
+	reason: string;
+};
+
+export type AiImpactClassification = {
+	level: ImpactLevel;
+};
+
+// Impact level ordering for comparison
+export const IMPACT_LEVEL_ORDER = {
+	low: 0,
+	medium: 1,
+	high: 2,
+} satisfies Record<ImpactLevel, number>;
+
+export const DEFAULT_LEVEL: PermissionLevel = "medium";
+
+export function isImpactAtMost(level: ImpactLevel, threshold: ImpactLevel): boolean {
+	return IMPACT_LEVEL_ORDER[level] <= IMPACT_LEVEL_ORDER[threshold];
+}
+
+export function maxImpactLevel(base: ImpactLevel, candidate: ImpactLevel): ImpactLevel {
+	return IMPACT_LEVEL_ORDER[candidate] > IMPACT_LEVEL_ORDER[base] ? candidate : base;
+}
+
+export function isImpactLevel(value: unknown): value is ImpactLevel {
+	return typeof value === "string" && (IMPACT_LEVELS as readonly string[]).includes(value);
+}
+
+export function isPermissionLevel(value: unknown): value is PermissionLevel {
+	return typeof value === "string" && (LEVELS as readonly string[]).includes(value);
+}
+
+export function cycleLevel(level: PermissionLevel): PermissionLevel {
+	const index = LEVELS.indexOf(level);
+	return LEVELS[(index + 1) % LEVELS.length];
+}

package/src/ui.ts

@@ -0,0 +1,100 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import type { ImpactAssessment, PermissionLevel } from "./types.js";
+import { loadConfig } from "./config-loader.js";
+
+type ThemeLike = {
+	inverse: (text: string) => string;
+	bold: (text: string) => string;
+	fg: (token: string, text: string) => string;
+};
+
+type PermissionBadgeRenderer = (theme: ThemeLike, label: string) => string | undefined;
+
+let badgeRenderer: PermissionBadgeRenderer | undefined;
+
+function truncatePlain(text: string, maxWidth: number): string {
+	if (maxWidth <= 0) return "";
+	if (text.length <= maxWidth) return text;
+	if (maxWidth <= 3) return ".".repeat(maxWidth);
+	return `${text.slice(0, maxWidth - 3)}...`;
+}
+
+export function setPermissionBadgeRenderer(renderer: PermissionBadgeRenderer | undefined): void {
+	badgeRenderer = renderer;
+}
+
+export const PERMISSION_LABELS = {
+	low: "Perm (Low) - allow edits + read-only commands",
+	medium: "Perm (Med) - allow reversible commands",
+	YOLO: "Perm (YOLO) - bypass all commands",
+} satisfies Record<PermissionLevel, string>;
+
+const PERMISSION_TONES = {
+	low: "text",
+	medium: "warning",
+	YOLO: "error",
+} satisfies Record<PermissionLevel, "text" | "warning" | "error">;
+
+function defaultBadge(theme: ThemeLike, label: string): string {
+	return theme.inverse(theme.bold(` ${label} `));
+}
+
+function renderBadge(theme: ThemeLike, label: string): string {
+	return badgeRenderer?.(theme, label) ?? defaultBadge(theme, label);
+}
+
+export function renderPermissionWidget(ctx: ExtensionContext, level: PermissionLevel): void {
+	if (!ctx.hasUI) return;
+	const config = loadConfig({ cwd: ctx.cwd });
+	const text = PERMISSION_LABELS[level];
+	const tone = PERMISSION_TONES[level];
+
+	ctx.ui.setWidget(
+		"permission-level",
+		() => ({
+			render: (width: number) => {
+				const prefix = " ";
+				const available = Math.max(0, width - prefix.length);
+				const hintPlain = ` (${config.cycle_shortcut} to cycle)`;
+
+				let basePlain = text;
+				let hintShown = hintPlain;
+
+				if (basePlain.length + hintShown.length > available) {
+					if (basePlain.length >= available) {
+						basePlain = truncatePlain(basePlain, available);
+						hintShown = "";
+					} else {
+						const remaining = available - basePlain.length;
+						hintShown = truncatePlain(hintShown, remaining);
+					}
+				}
+
+				const rendered = prefix + ctx.ui.theme.fg(tone, basePlain) + ctx.ui.theme.fg("dim", hintShown);
+				return [rendered];
+			},
+			invalidate: () => {},
+		}),
+		{ placement: "aboveEditor" },
+	);
+}
+
+function renderExecuteLine(ctx: ExtensionContext, assessment: ImpactAssessment): string {
+	const impact = assessment.unknown ? "unknown" : assessment.level;
+	const executeTag = renderBadge(ctx.ui.theme as ThemeLike, "EXECUTE");
+	const detailParts = [
+		assessment.operation,
+		`impact: ${impact}`,
+		assessment.reason ? `reason: ${assessment.reason}` : undefined,
+	]
+		.filter(Boolean)
+		.join(", ");
+	const detail = ctx.ui.theme.fg("toolOutput", `(${detailParts})`);
+	return `${executeTag} ${detail}`;
+}
+
+export async function askUserPermission(ctx: ExtensionContext, assessment: ImpactAssessment): Promise<boolean> {
+	const choice = await ctx.ui.select(renderExecuteLine(ctx, assessment), ["Yes, allow", "No, Cancel"]);
+	return choice === "Yes, allow";
+}