@andares/pi-toolkits 0.8.0 → 0.9.0

package/src/features/permission/index.test.ts

@@ -0,0 +1,340 @@
+/**
+ * `/ask-perm` integration over a captured gate and a mocked pi surface.
+ *
+ * The UI components are not rendered here (that needs a terminal); the
+ * dialog contract is exercised through `AskRequest.present` with a host
+ * selector, and the rest through the gate's verdicts and the command handler.
+ */
+import { mkdtempSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { AskDecision, GateHub, ToolGate } from "../../lib/gates.js";
+import { registerPermission } from "./index.js";
+
+function bashEvent(command: string): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName: "bash",
+		input: { command },
+	} as unknown as ToolCallEvent;
+}
+
+function pathEvent(toolName: string, path: string): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName,
+		input: { path },
+	} as unknown as ToolCallEvent;
+}
+
+function customEvent(toolName: string): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName,
+		input: {},
+	} as unknown as ToolCallEvent;
+}
+
+interface Harness {
+	readonly cwd: string;
+	readonly ctx: ExtensionContext;
+	readonly gate: ToolGate;
+	readonly statuses: Array<[string, string | undefined]>;
+	readonly notes: Array<{ message: string; kind?: string }>;
+	readonly branch: Array<Record<string, unknown>>;
+	evaluate(event: ToolCallEvent): Promise<unknown>;
+	command(args: string): Promise<void>;
+	sessionStart(): Promise<void>;
+	banner(): { systemPrompt: string } | undefined;
+}
+
+function makeHarness(): Harness {
+	const cwd = realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-test-")));
+	const statuses: Harness["statuses"] = [];
+	const notes: Harness["notes"] = [];
+	const branch: Harness["branch"] = [];
+	const ctx = {
+		cwd,
+		hasUI: true,
+		mode: "tui",
+		ui: {
+			notify: (message: string, kind?: string) => notes.push({ message, kind }),
+			setStatus: (key: string, value: string | undefined) => statuses.push([key, value]),
+			theme: { fg: (_color: string, text: string) => text },
+			custom: async () => undefined,
+			select: async () => undefined,
+		},
+		sessionManager: { getBranch: () => branch },
+	} as unknown as ExtensionContext;
+
+	const captured: ToolGate[] = [];
+	const hub = {
+		register(gate: ToolGate) {
+			captured.push(gate);
+		},
+		handle: async () => undefined,
+		install: () => {},
+	} as unknown as GateHub;
+
+	const handlers = new Map<string, (...args: unknown[]) => unknown>();
+	let commandHandler: ((args: string, ctx: ExtensionContext) => unknown) | undefined;
+	const pi = {
+		on(event: string, handler: (...args: unknown[]) => unknown) {
+			handlers.set(event, handler);
+		},
+		registerCommand(
+			name: string,
+			options: { handler: (args: string, ctx: ExtensionContext) => unknown },
+		) {
+			if (name === "ask-perm") commandHandler = options.handler;
+		},
+	} as unknown as ExtensionAPI;
+
+	registerPermission(pi, hub);
+	const gate = captured[0];
+	if (!gate || !commandHandler) throw new Error("permission did not register");
+
+	return {
+		cwd,
+		ctx,
+		gate,
+		statuses,
+		notes,
+		branch,
+		async evaluate(event) {
+			return gate.evaluate(event, ctx);
+		},
+		async command(args) {
+			await commandHandler?.(args, ctx);
+		},
+		async sessionStart() {
+			await handlers.get("session_start")?.( { reason: "new" }, ctx);
+		},
+		banner() {
+			return handlers.get("before_agent_start")?.(
+				{ systemPrompt: "base", type: "before_agent_start" },
+				ctx,
+			) as { systemPrompt: string } | undefined;
+		},
+	};
+}
+
+interface AskVerdict {
+	kind: "ask";
+	request: {
+		details: readonly string[];
+		root: string;
+		present(ctx: ExtensionContext): Promise<AskDecision | undefined>;
+		apply(decision: AskDecision): void;
+	};
+}
+
+function asAsk(verdict: unknown): AskVerdict {
+	expect(verdict).toMatchObject({ kind: "ask" });
+	return verdict as AskVerdict;
+}
+
+describe("/ask-perm", () => {
+	it("is off by default", async () => {
+		const h = makeHarness();
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("enables from arguments, reports status, and asks for an outside write", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(h.statuses.at(-1)?.[0]).toBe("perm-mode");
+		expect(h.statuses.at(-1)?.[1]).toContain("perm");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside")));
+		expect(verdict.request.details.join("\n")).toContain("/tmp/outside");
+		expect(verdict.request.root).toBe("/tmp");
+	});
+
+	it("blocks immediately when outside writes are denied", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow deny");
+		const verdict = (await h.evaluate(bashEvent("rm -rf /tmp/outside"))) as {
+			kind: "block";
+			reason: string;
+		};
+		expect(verdict.kind).toBe("block");
+		expect(verdict.reason).toContain("Permission denied");
+		expect(verdict.reason).toContain("outside-project write");
+	});
+
+	it("records a session grant and applies it to later calls", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const first = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x")));
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))).toBeUndefined();
+	});
+
+	it("records a session deny and blocks later calls", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const first = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x")));
+		first.request.apply("deny-session");
+		const later = (await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))) as {
+			kind: "block";
+			reason: string;
+		};
+		expect(later.kind).toBe("block");
+		expect(later.reason).toContain("denied for this session");
+	});
+
+	it("toggles off with no arguments and clears the status", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		await h.command("");
+		expect(h.statuses.at(-1)?.[1]).toBeUndefined();
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("keeps the mode off when the panel is cancelled", async () => {
+		const h = makeHarness();
+		await h.command("");
+		expect(h.notes.at(-1)?.message).toContain("cancelled");
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("rejects invalid arguments without enabling", async () => {
+		const h = makeHarness();
+		await h.command("deny");
+		expect(h.notes.at(-1)?.kind).toBe("error");
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+	});
+
+	it("resets on session_start", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		await h.sessionStart();
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside"))).toBeUndefined();
+		expect(h.statuses.at(-1)?.[1]).toBeUndefined();
+	});
+
+	it("treats add-dir directories as inside the project", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(asAsk(await h.evaluate(bashEvent("rm -rf /tmp/added/x"))).kind).toBe("ask");
+
+		h.branch.push({
+			type: "custom",
+			customType: "add-dir:state",
+			data: { dirs: [{ absolutePath: "/tmp/added" }] },
+		});
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/added/x"))).toBeUndefined();
+	});
+
+	it("treats a redirect write to a credential path as a fixed deny, not a write ask", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const verdict = (await h.evaluate(
+			bashEvent("echo a > ~/.ssh/authorized_keys"),
+		)) as { kind: "block"; reason: string };
+		expect(verdict.kind).toBe("block");
+		expect(verdict.reason).toContain("fixed safety table");
+	});
+
+	it("judges git -C by the -C directory, not the working directory", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(await h.evaluate(bashEvent("git -C ../outside log"))).toBeUndefined();
+		expect(asAsk(await h.evaluate(bashEvent("git -C ../outside push"))).kind).toBe("ask");
+	});
+
+	it("answers path-bearing tools by their own path", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(await h.evaluate(pathEvent("write", "notes.txt"))).toBeUndefined();
+		expect(asAsk(await h.evaluate(pathEvent("write", "/tmp/outside.txt"))).kind).toBe("ask");
+		const denied = (await h.evaluate(pathEvent("read", "~/.ssh/id_rsa"))) as {
+			kind: "block";
+		};
+		expect(denied.kind).toBe("block");
+	});
+
+	it("judges a pathless tool by the working directory", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		expect(await h.evaluate(customEvent("mcp"))).toBeUndefined();
+	});
+
+	it("clears session grants when the mode is reconfigured", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x"))).request.apply(
+			"allow-session",
+		);
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))).toBeUndefined();
+
+		await h.command("allow allow allow ask");
+		expect(asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))).kind).toBe("ask");
+	});
+});
+
+describe("dialog contract", () => {
+	it("fails closed without a UI", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside")));
+		const noUi = { ...h.ctx, hasUI: false } as ExtensionContext;
+		await expect(verdict.request.present(noUi)).resolves.toBeUndefined();
+	});
+
+	it("falls back to the host selector in non-TUI modes", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside")));
+		const rpc = {
+			cwd: h.cwd,
+			hasUI: true,
+			mode: "rpc",
+			ui: {
+				select: async () => "Allow once (a)",
+				theme: { fg: (_color: string, text: string) => text },
+			},
+		} as unknown as ExtensionContext;
+		await expect(verdict.request.present(rpc)).resolves.toBe("allow");
+	});
+});
+
+describe("model-facing banner", () => {
+	it("appends the policy only while enabled", async () => {
+		const h = makeHarness();
+		expect(h.banner()).toBeUndefined();
+		await h.command("allow allow allow ask");
+		expect(h.banner()?.systemPrompt).toContain("Permission mode");
+		expect(h.banner()?.systemPrompt).toContain("in allow/allow, out allow/ask");
+	});
+});
+
+describe("session grants cover repeat asks", () => {
+	it("stops asking for a destructive in-project command once allowed", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const first = asAsk(await h.evaluate(bashEvent("rm -rf .")));
+		expect(first.request.details.join("\n")).toContain("recursive delete");
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent("rm -rf ."))).toBeUndefined();
+	});
+
+	it("stops asking for the same opaque command once allowed", async () => {
+		const h = makeHarness();
+		await h.command("allow allow allow ask");
+		const command = 'cd "$DIR" && rm x';
+		const first = asAsk(await h.evaluate(bashEvent(command)));
+		expect(first.request.details.join("\n")).toContain("this exact command");
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent(command))).toBeUndefined();
+	});
+});

package/src/features/permission/index.ts

@@ -0,0 +1,333 @@
+/**
+ * permission feature — `/ask-perm`: session-scoped boundary permission.
+ *
+ * Design notes:
+ *  - Off by default and never persisted. The mode, the modes, and every session
+ *    grant live in this closure; `session_start` resets them and
+ *    `session_shutdown` clears them. A forgotten toggle cannot follow the
+ *    operator into the next session.
+ *  - Toggling: no arguments flips on→off, off→panel. Arguments configure and
+ *    enable in one step (`/ask-perm allow allow allow ask`), which is also the
+ *    autostart path and never opens a dialog.
+ *  - Enforcement is a gate on the shared bus, so it composes with `/ask`
+ *    instead of replacing it: ask answers "does this mutate?", permission
+ *    answers "does this cross the project boundary?", and either can block.
+ *  - The boundary is the working directory plus directories added through
+ *    pi-add-dir (read from its session entry).
+ */
+import { isAbsolute, join } from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { AskRequest, GateHub } from "../../lib/gates.js";
+import {
+	DEFAULT_MODES,
+	type PermissionModes,
+	PERMISSION_STATUS_KEY,
+	type Effect,
+} from "./constants.js";
+import {
+	formatModes,
+	parsePermissionArgs,
+	shortMode,
+} from "./modes.js";
+import { openPermissionPanel } from "./panel.js";
+import {
+	canonicalize,
+	expandHome,
+	readAddedDirectories,
+	sessionRoots,
+} from "./paths.js";
+import {
+	decideProgram,
+	decisionEffect,
+	decisionGrantRoot,
+	formatDenial,
+	type PolicyDecision,
+	programKey,
+} from "./policy.js";
+import { askPermission } from "./prompt.js";
+import { SessionRules } from "./session-rules.js";
+import { parseCommandUnits, type CommandUnit } from "./units.js";
+
+/** Tools that read one path. */
+const READ_PATH_TOOLS = new Set(["read", "grep", "find", "ls"]);
+/** Tools that write one path. */
+const WRITE_PATH_TOOLS = new Set(["write", "edit"]);
+
+function inputPath(input: unknown): string | undefined {
+	if (typeof input !== "object" || input === null) return undefined;
+	const value = (input as { path?: unknown }).path;
+	return typeof value === "string" ? value : undefined;
+}
+
+/** One synthetic unit for a non-bash tool call. */
+function toolUnit(
+	command: string,
+	effect: Effect,
+	pathValue: string | undefined,
+	cwd: string,
+): CommandUnit {
+	const base = canonicalize(cwd);
+	return {
+		raw: command,
+		headWord: command,
+		command,
+		args: [],
+		effect,
+		opaque: WRITE_PATH_TOOLS.has(command) && pathValue === undefined,
+		base,
+		targets:
+			pathValue === undefined
+				? []
+				: [
+						{
+							path: isAbsolute(expandHome(pathValue))
+								? expandHome(pathValue)
+								: join(base, pathValue),
+							effect,
+							source: "operand",
+						},
+					],
+		note: pathValue === undefined ? "the tool call names no path" : undefined,
+	};
+}
+
+export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
+	let enabled = false;
+	let modes: PermissionModes = { ...DEFAULT_MODES };
+	const rules = new SessionRules();
+	let rootsCache:
+		| { cwd: string; branchLength: number; roots: string[] }
+		| undefined;
+
+	function reset(): void {
+		enabled = false;
+		modes = { ...DEFAULT_MODES };
+		rules.clear();
+		rootsCache = undefined;
+	}
+
+	function syncStatus(ctx: ExtensionContext): void {
+		if (!enabled) {
+			ctx.ui.setStatus(PERMISSION_STATUS_KEY, undefined);
+			return;
+		}
+		const color = (mode: string, label: string): string => {
+			if (mode === "allow") return ctx.ui.theme.fg("success", label);
+			if (mode === "ask") return ctx.ui.theme.fg("warning", label);
+			return ctx.ui.theme.fg("error", label);
+		};
+		const part = (inProject: string, outside: string): string =>
+			`${color(inProject, shortMode(inProject as "allow"))}/${color(outside, shortMode(outside as "allow"))}`;
+		ctx.ui.setStatus(
+			PERMISSION_STATUS_KEY,
+			`${ctx.ui.theme.fg("muted", "perm")} i:${part(modes.inRead, modes.inWrite)} o:${part(modes.outRead, modes.outWrite)}`,
+		);
+	}
+
+	/** Session roots, refreshed only when the branch grew. */
+	function rootsFor(ctx: ExtensionContext): string[] {
+		try {
+			const branch = ctx.sessionManager.getBranch();
+			if (
+				!rootsCache ||
+				rootsCache.cwd !== ctx.cwd ||
+				rootsCache.branchLength !== branch.length
+			) {
+				rootsCache = {
+					cwd: ctx.cwd,
+					branchLength: branch.length,
+					roots: sessionRoots(ctx.cwd, readAddedDirectories(branch)),
+				};
+			}
+			return rootsCache.roots;
+		} catch {
+			// No session manager (unexpected context): fail closed on the cwd only.
+			return [canonicalize(ctx.cwd)];
+		}
+	}
+
+	function unitsFor(event: ToolCallEvent, cwd: string): CommandUnit[] {
+		if (event.toolName === "bash") {
+			const command = (event.input as { command?: unknown }).command;
+			return parseCommandUnits(typeof command === "string" ? command : "", cwd);
+		}
+		if (event.toolName === "powershell") {
+			// PowerShell is not decomposed: a script's writes and exec targets stay
+			// invisible, so the call is asked about instead of judged by its cwd.
+			return [
+				{
+					raw: "powershell",
+					headWord: "powershell",
+					command: "powershell",
+					args: [],
+					effect: "write",
+					opaque: true,
+					base: canonicalize(cwd),
+					targets: [],
+					note: "PowerShell commands are not analysed",
+				},
+			];
+		}
+		if (READ_PATH_TOOLS.has(event.toolName)) {
+			return [toolUnit(event.toolName, "read", inputPath(event.input), cwd)];
+		}
+		if (WRITE_PATH_TOOLS.has(event.toolName)) {
+			return [toolUnit(event.toolName, "write", inputPath(event.input), cwd)];
+		}
+		// Every other tool (MCP, subagent, …) has no path to judge: it is
+		// treated as an exec and answered by the working directory's scope.
+		return [toolUnit(event.toolName, "write", undefined, cwd)];
+	}
+
+	function askRequest(
+		decision: PolicyDecision,
+		fallbackCwd: string,
+		units: readonly CommandUnit[],
+	): AskRequest {
+		const root = decisionGrantRoot(decision, () => fallbackCwd);
+		const effect = decisionEffect(decision);
+		const scope =
+			decision.target?.scope === "out" ? "outside project" : "inside project";
+		const details = [
+			`Command: ${decision.unit.raw || decision.unit.command}`,
+			...(decision.target
+				? [`Target: ${decision.target.path} (${scope}, ${effect})`]
+				: []),
+			...(decision.reason ? [`Reason: ${decision.reason}`] : []),
+			decision.unit.opaque
+				? "Session grant would cover: this exact command"
+				: `Session grant would cover: ${root}`,
+		];
+		return {
+			title: "Permission required",
+			details,
+			root,
+			present: (ctx) =>
+				askPermission(ctx, { title: "Permission required", details }),
+			apply: (choice) => {
+				if (choice === "allow-session") {
+					if (decision.unit.opaque) rules.allowCommand(programKey(units));
+					else rules.allow({ effect, root });
+				}
+				if (choice === "deny-session") {
+					if (decision.unit.opaque) rules.denyCommand(programKey(units));
+					else rules.deny({ effect, root });
+				}
+			},
+			denyReason: (choice) =>
+				formatDenial({
+					...decision,
+					reason:
+						choice === "deny-session"
+							? `${decision.reason ?? "operation"} — denied for this session`
+							: (decision.reason ?? "denied by the operator"),
+				}),
+		};
+	}
+
+	// ── Lifecycle ──────────────────────────────────────────────────────────
+
+	pi.on("session_start", (_event, ctx) => {
+		reset();
+		syncStatus(ctx);
+	});
+	pi.on("session_shutdown", () => {
+		reset();
+	});
+
+	// ── Command ────────────────────────────────────────────────────────────
+
+	pi.registerCommand("ask-perm", {
+		description:
+			"Toggle permission checks; with arguments: /ask-perm [in-read] [in-write] [out-read] [out-write]",
+		handler: async (args, ctx) => {
+			const raw = args.trim();
+
+			if (raw !== "") {
+				const parsed = parsePermissionArgs(raw);
+				if ("error" in parsed) {
+					ctx.ui.notify(`ask-perm: ${parsed.error}`, "error");
+					return;
+				}
+				modes = parsed.modes;
+				// A new policy invalidates grants made under the old one.
+				rules.clear();
+				enabled = true;
+				syncStatus(ctx);
+				ctx.ui.notify(
+					`Permission ON — ${formatModes(modes)}. /ask-perm to turn off.`,
+					"info",
+				);
+				return;
+			}
+
+			if (enabled) {
+				enabled = false;
+				rules.clear();
+				syncStatus(ctx);
+				ctx.ui.notify(
+					"Permission OFF — no boundary checks in this session.",
+					"info",
+				);
+				return;
+			}
+
+			const chosen = await openPermissionPanel(ctx, modes);
+			if (!chosen) {
+				ctx.ui.notify(
+					"ask-perm: cancelled. Use /ask-perm allow allow allow ask to enable from the argument form.",
+					"info",
+				);
+				return;
+			}
+			modes = chosen;
+			enabled = true;
+			syncStatus(ctx);
+			ctx.ui.notify(
+				`Permission ON — ${formatModes(modes)}. /ask-perm to turn off.`,
+				"info",
+			);
+		},
+	});
+
+	// ── Gate ───────────────────────────────────────────────────────────────
+
+	gates.register({
+		name: "permission",
+		order: 20,
+		evaluate(event, ctx) {
+			if (!enabled) return undefined;
+			const units = unitsFor(event, ctx.cwd);
+			if (units.length === 0) return undefined;
+			const decision = decideProgram(units, {
+				modes,
+				roots: rootsFor(ctx),
+				rules,
+			});
+			if (decision.action === "allow") return undefined;
+			if (decision.action === "deny") {
+				return { kind: "block", reason: formatDenial(decision) };
+			}
+			return { kind: "ask", request: askRequest(decision, ctx.cwd, units) };
+		},
+	});
+
+	// ── Model-facing banner ────────────────────────────────────────────────
+
+	pi.on("before_agent_start", (event) => {
+		if (!enabled) return;
+		const banner = [
+			"",
+			"## Permission mode",
+			`Boundary checks are ON: ${formatModes(modes)}.`,
+			"Operations outside the project, destructive commands, and credential paths may require operator confirmation.",
+			"A denial is a policy decision — do not retry the same operation through an equivalent command.",
+			"",
+		].join("\n");
+		return { systemPrompt: `${event.systemPrompt}${banner}` };
+	});
+}