@andares/pi-toolkits 0.9.8 → 0.11.0

package/src/features/permission/audit.ts

@@ -0,0 +1,145 @@
+/**
+ * permission feature — the audit payload.
+ *
+ * The gate bus owns the record envelope (session, tool call, answer, outcome);
+ * this module contributes the part only the permission layer knows: the four
+ * modes and session roots in force, the bash decomposition, and which rule
+ * produced the verdict.
+ *
+ * The payload is deliberately lossless for *policy analysis* — every unit and
+ * every target survives, including the parser's `opaque` note — while being
+ * bounded: units, targets, args and long strings are capped, and the final
+ * serializer drops detail with a visible `truncated` marker rather than
+ * silently cutting a field. File contents never enter this payload.
+ */
+import { createHash } from "node:crypto";
+import type { ApprovalRecord } from "../../lib/approval-log.js";
+import { clipText } from "../../lib/approval-log.js";
+import type { PermissionModes } from "./constants.js";
+import { canonicalize, insideAnyRoot } from "./paths.js";
+import {
+	decisionGrantRoot,
+	type PolicyDecision,
+} from "./policy.js";
+import type { CommandUnit } from "./units.js";
+
+const MAX_UNITS = 32;
+const MAX_TARGETS = 32;
+const MAX_ARGS = 64;
+const ARG_CHARS = 512;
+const RAW_CHARS = 8192;
+const PATH_CHARS = 1024;
+const NOTE_CHARS = 512;
+const REASON_CHARS = 2048;
+
+export interface PermissionAuditInput {
+	readonly cwd: string;
+	readonly modes: PermissionModes;
+	/** Canonical session roots (working directory plus added directories). */
+	readonly roots: readonly string[];
+	readonly units: readonly CommandUnit[];
+	/** Verdict for each unit, in the same order as {@link units}. */
+	readonly unitDecisions: readonly PolicyDecision[];
+	/** Aggregate verdict (the strictest unit wins). */
+	readonly decision: PolicyDecision;
+	/** Exact dialog lines, when this payload belongs to an ask. */
+	readonly prompt?: readonly string[];
+}
+
+/** Short digest of the command text, for grouping opaque grants. */
+export function commandDigest(units: readonly CommandUnit[]): string {
+	return createHash("sha256")
+		.update(units.map((unit) => unit.raw).join(" ; "))
+		.digest("hex")
+		.slice(0, 16);
+}
+
+function serializeUnit(
+	unit: CommandUnit,
+	decision: PolicyDecision | undefined,
+	roots: readonly string[],
+): ApprovalRecord {
+	const targets = unit.targets.slice(0, MAX_TARGETS).map((target) => {
+		const canonical = canonicalize(target.path);
+		return {
+			path: clipText(target.path, PATH_CHARS),
+			canonical: clipText(canonical, PATH_CHARS),
+			effect: target.effect,
+			source: target.source,
+			scope: insideAnyRoot(roots, canonical) ? "in" : "out",
+		};
+	});
+	return {
+		raw: clipText(unit.raw, RAW_CHARS),
+		head: unit.headWord,
+		command: unit.command,
+		args: unit.args.slice(0, MAX_ARGS).map((arg) => clipText(arg, ARG_CHARS)),
+		base: unit.base === null ? null : clipText(canonicalize(unit.base), PATH_CHARS),
+		effect: unit.effect,
+		opaque: unit.opaque,
+		...(unit.note === undefined ? {} : { note: clipText(unit.note, NOTE_CHARS) }),
+		...(decision === undefined
+			? {}
+			: { action: decision.action, layer: decision.layer }),
+		targets,
+	};
+}
+
+function serializeVerdict(
+	input: PermissionAuditInput,
+): ApprovalRecord {
+	const decision = input.decision;
+	const unitIndex = input.units.indexOf(decision.unit);
+	const target = decision.target;
+	const grantScope = decision.unit.opaque ? "command" : "root";
+	return {
+		action: decision.action,
+		layer: decision.layer,
+		...(unitIndex < 0 ? {} : { unit: unitIndex }),
+		...(target === undefined
+			? {}
+			: {
+					target: clipText(target.path, PATH_CHARS),
+					effect: target.effect,
+					scope: target.scope,
+				}),
+		grantScope,
+		...(grantScope === "root"
+			? {
+					grantRoot: clipText(
+						decisionGrantRoot(decision, () => input.cwd),
+						PATH_CHARS,
+					),
+				}
+			: { grantDigest: commandDigest(input.units) }),
+		...(decision.reason === undefined
+			? {}
+			: { reason: clipText(decision.reason, REASON_CHARS) }),
+	};
+}
+
+/** Structured audit fields for one permission decision. */
+export function buildPermissionAudit(
+	input: PermissionAuditInput,
+): ApprovalRecord {
+	const unitDecisions = input.unitDecisions;
+	return {
+		modes: {
+			inRead: input.modes.inRead,
+			inWrite: input.modes.inWrite,
+			outRead: input.modes.outRead,
+			outWrite: input.modes.outWrite,
+		},
+		roots: input.roots
+			.slice(0, 16)
+			.map((root) => clipText(root, PATH_CHARS)),
+		units: input.units
+			.slice(0, MAX_UNITS)
+			.map((unit, index) => serializeUnit(unit, unitDecisions[index], input.roots)),
+		...(input.units.length > MAX_UNITS
+			? { unitsOmitted: input.units.length - MAX_UNITS }
+			: {}),
+		verdict: serializeVerdict(input),
+		...(input.prompt === undefined ? {} : { prompt: [...input.prompt] }),
+	};
+}

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

@@ -6,7 +6,7 @@
  * 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 { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeEach, describe, expect, it } from "vitest";
 import type {
@@ -14,6 +14,7 @@ import type {
 	ExtensionContext,
 	ToolCallEvent,
 } from "@earendil-works/pi-coding-agent";
+import type { ApprovalLog, ApprovalRecord } from "../../lib/approval-log.js";
 import type { AskDecision, GateHub, ToolGate } from "../../lib/gates.js";
 import {
 	clearJailedTool,
@@ -65,7 +66,7 @@ interface Harness {
 	banner(): { systemPrompt: string } | undefined;
 }
 
-function makeHarness(): Harness {
+function makeHarness(audit?: ApprovalLog): Harness {
 	const cwd = realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-test-")));
 	const statuses: Harness["statuses"] = [];
 	const notes: Harness["notes"] = [];
@@ -116,7 +117,7 @@ function makeHarness(): Harness {
 		registerEntryRenderer() {},
 	} as unknown as ExtensionAPI;
 
-	registerPermission(pi, hub);
+	registerPermission(pi, hub, { audit });
 	const gate = captured[0];
 	if (!gate || !commandHandler) throw new Error("permission did not register");
 
@@ -154,6 +155,7 @@ interface AskVerdict {
 	request: {
 		details: readonly string[];
 		root: string;
+		audit?: ApprovalRecord;
 		present(ctx: ExtensionContext): Promise<AskDecision | undefined>;
 		apply(decision: AskDecision): void;
 	};
@@ -435,3 +437,136 @@ describe("self-jailed tools", () => {
 		expect(asAsk(await h.evaluate(customEvent("scratchpad"))).kind).toBe("ask");
 	});
 });
+
+describe("audit log", () => {
+	function makeAudit(): { audit: ApprovalLog; records: ApprovalRecord[] } {
+		const records: ApprovalRecord[] = [];
+		return {
+			records,
+			audit: {
+				dir: "/tmp/pi-perm-audit",
+				mode: "interesting",
+				active: true,
+				append: (record) => records.push(record),
+			},
+		};
+	}
+
+	it("attaches the decomposition to an ask verdict", async () => {
+		const { audit } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x")));
+		expect(verdict.request.audit).toMatchObject({
+			modes: { outWrite: "ask" },
+			verdict: {
+				action: "ask",
+				layer: "mode",
+				target: "/tmp/outside/x",
+				scope: "out",
+			},
+		});
+		expect(
+			(verdict.request.audit?.units as Array<Record<string, unknown>>)[0],
+		).toMatchObject({
+			command: "rm",
+			opaque: false,
+			action: "ask",
+			layer: "mode",
+		});
+	});
+
+	it("attaches the deciding layer to a deny verdict", async () => {
+		const { audit } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		const verdict = (await h.evaluate(
+			bashEvent(`cat ${homedir()}/.ssh/id_rsa`),
+		)) as {
+			kind: "block";
+			reason: string;
+			audit?: ApprovalRecord;
+		};
+		expect(verdict.kind).toBe("block");
+		expect(verdict.audit?.verdict).toMatchObject({
+			action: "deny",
+			layer: "secret",
+		});
+	});
+
+	it("records mode changes with their source", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		expect(records.at(-1)).toMatchObject({
+			event: "mode",
+			enabled: true,
+			source: "args",
+			via: "manual",
+			modes: { inRead: "allow", outWrite: "ask" },
+		});
+		await h.command("");
+		expect(records.at(-1)).toMatchObject({
+			event: "mode",
+			enabled: false,
+			source: "toggle",
+		});
+	});
+
+	it("marks an autostart-dispatched mode change", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		markStartupCommand("ask-perm");
+		await h.command("allow allow allow ask");
+		expect(records.at(-1)).toMatchObject({
+			event: "mode",
+			via: "autostart",
+		});
+	});
+});
+
+describe("audit log — session-grant allows", () => {
+	function makeAudit(): { audit: ApprovalLog; records: ApprovalRecord[] } {
+		const records: ApprovalRecord[] = [];
+		return {
+			records,
+			audit: {
+				dir: "/tmp/pi-perm-audit",
+				mode: "interesting",
+				active: true,
+				append: (record) => records.push(record),
+			},
+		};
+	}
+
+	it("records the repeat call a directory grant made free", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		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();
+
+		const allow = records.find((record) => record.event === "allow");
+		expect(allow).toMatchObject({
+			event: "allow",
+			verdict: { action: "allow", layer: "session-allow", scope: "out" },
+		});
+	});
+
+	it("records a program-level grant on an opaque command too", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		const command = 'cd "$DIR" && rm x';
+		const first = asAsk(await h.evaluate(bashEvent(command)));
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent(command))).toBeUndefined();
+
+		const allow = records.find((record) => record.event === "allow");
+		expect(allow).toMatchObject({
+			event: "allow",
+			verdict: { action: "allow", layer: "session-command", grantScope: "command" },
+		});
+	});
+});

package/src/features/permission/index.ts

@@ -22,6 +22,8 @@ import type {
 	ToolCallEvent,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import type { ApprovalLog, ApprovalRecord } from "../../lib/approval-log.js";
+import { auditBase, auditTool } from "../../lib/approval-log.js";
 import type { AskRequest, GateHub } from "../../lib/gates.js";
 import { isJailedTool } from "../../lib/tools.js";
 import { consumeStartupCommand } from "../../lib/startup.js";
@@ -46,6 +48,7 @@ import {
 } from "./paths.js";
 import {
 	decideProgram,
+	decideUnit,
 	decisionEffect,
 	decisionGrantRoot,
 	formatDenial,
@@ -55,6 +58,7 @@ import {
 import { askPermission } from "./prompt.js";
 import { SessionRules } from "./session-rules.js";
 import { parseCommandUnits, type CommandUnit } from "./units.js";
+import { buildPermissionAudit, commandDigest } from "./audit.js";
 
 /** Tools that read one path. */
 const READ_PATH_TOOLS = new Set(["read", "grep", "find", "ls"]);
@@ -123,7 +127,17 @@ interface NoticeData {
 	text: string;
 }
 
-export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
+export interface PermissionOptions {
+	/** Write-only audit sink; kept optional so tests need no filesystem. */
+	readonly audit?: ApprovalLog;
+}
+
+export function registerPermission(
+	pi: ExtensionAPI,
+	gates: GateHub,
+	options: PermissionOptions = {},
+): void {
+	const audit = options.audit;
 	pi.registerEntryRenderer?.(NOTICE_ENTRY, (entry, _options, theme) => {
 		const text = (entry.data as NoticeData | undefined)?.text;
 		return text === undefined
@@ -148,6 +162,22 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 		rootsCache = undefined;
 	}
 
+	/** Record an on/off or mode change; never affects the state machine. */
+	function recordMode(
+		ctx: ExtensionContext,
+		state: { enabled: boolean; source: string; via: string },
+	): void {
+		if (!audit || audit.mode === "off") return;
+		audit.append({
+			...auditBase(ctx),
+			event: "mode",
+			enabled: state.enabled,
+			modes: { ...modes },
+			source: state.source,
+			via: state.via,
+		});
+	}
+
 	/** Session id, or `undefined` when the host exposes none. */
 	function sessionIdOf(ctx: ExtensionContext): string | undefined {
 		try {
@@ -234,11 +264,13 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 		decision: PolicyDecision,
 		fallbackCwd: string,
 		units: readonly CommandUnit[],
+		payload: ApprovalRecord | undefined,
 	): AskRequest {
 		const root = decisionGrantRoot(decision, () => fallbackCwd);
 		const effect = decisionEffect(decision);
 		const scope =
 			decision.target?.scope === "out" ? "outside project" : "inside project";
+		const title = "Permission required";
 		const details = [
 			`Command: ${decision.unit.raw || decision.unit.command}`,
 			...(decision.target
@@ -249,12 +281,16 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 				? "Session grant would cover: this exact command"
 				: `Session grant would cover: ${root}`,
 		];
+		const auditPayload =
+			payload === undefined
+				? undefined
+				: { ...payload, prompt: [title, ...details] };
 		return {
-			title: "Permission required",
+			title,
 			details,
 			root,
-			present: (ctx) =>
-				askPermission(ctx, { title: "Permission required", details }),
+			audit: auditPayload,
+			present: (ctx) => askPermission(ctx, { title, details }),
 			apply: (choice) => {
 				if (choice === "allow-session") {
 					if (decision.unit.opaque) rules.allowCommand(programKey(units));
@@ -273,6 +309,20 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 							? `${decision.reason ?? "operation"} — denied for this session`
 							: (decision.reason ?? "denied by the operator"),
 				}),
+			settle: (choice) => {
+				if (choice !== "allow-session" && choice !== "deny-session") {
+					return undefined;
+				}
+				const commandScope = decision.unit.opaque;
+				return {
+					grant: {
+						kind: choice === "allow-session" ? "allow" : "deny",
+						scope: commandScope ? "command" : "root",
+						effect,
+						...(commandScope ? { digest: commandDigest(units) } : { root }),
+					},
+				};
+			},
 		};
 	}
 
@@ -298,6 +348,7 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 		handler: async (args, ctx) => {
 			// Startup notices are entries; interactive ones stay in-place toasts.
 			const startup = consumeStartupCommand("ask-perm");
+			const via = startup ? "autostart" : "manual";
 			const notice = (text: string): void => {
 				if (startup) pi.appendEntry<NoticeData>(NOTICE_ENTRY, { text });
 				else ctx.ui.notify(text, "info");
@@ -322,6 +373,7 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 				if (changed) rules.clear();
 				enabled = true;
 				syncStatus(ctx);
+				recordMode(ctx, { enabled: true, source: "args", via });
 				notice(`Permission ON — ${formatModes(modes)}. /ask-perm to turn off.`);
 				return;
 			}
@@ -330,6 +382,7 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 				enabled = false;
 				rules.clear();
 				syncStatus(ctx);
+				recordMode(ctx, { enabled: false, source: "toggle", via });
 				notice("Permission OFF — no boundary checks in this session.");
 				return;
 			}
@@ -346,6 +399,7 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 			rules.clear();
 			enabled = true;
 			syncStatus(ctx);
+			recordMode(ctx, { enabled: true, source: "panel", via });
 			notice(`Permission ON — ${formatModes(modes)}. /ask-perm to turn off.`);
 		},
 	});
@@ -364,16 +418,58 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 			if (isJailedTool(event.toolName)) 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;
+			const roots = rootsFor(ctx);
+			const policyCtx = { modes, roots, rules };
+			const decision = decideProgram(units, policyCtx);
+			const logOn = audit !== undefined && audit.mode !== "off";
+
+			if (decision.action === "allow") {
+				// Session-grant allows show how much friction a grant removed; plain
+				// mode allows are logged only under `PI_APPROVAL_LOG=all`, otherwise
+				// their volume would bury the interesting records. A grant on an
+				// opaque program is keyed by its text (`session-command`), so both
+				// grant layers must be recorded — otherwise "allow for this session"
+				// on a command the parser cannot resolve would leave no trace.
+				const granted =
+					decision.layer === "session-allow" ||
+					decision.layer === "session-command";
+				if (logOn && (granted || audit?.mode === "all")) {
+					const payload = buildPermissionAudit({
+						cwd: ctx.cwd,
+						modes,
+						roots,
+						units,
+						unitDecisions: units.map((unit) => decideUnit(unit, policyCtx)),
+						decision,
+					});
+					audit?.append({
+						...auditBase(ctx),
+						...auditTool(event),
+						...payload,
+						event: "allow",
+					});
+				}
+				return undefined;
+			}
+
+			let payload: ApprovalRecord | undefined;
+			if (logOn) {
+				payload = buildPermissionAudit({
+					cwd: ctx.cwd,
+					modes,
+					roots,
+					units,
+					unitDecisions: units.map((unit) => decideUnit(unit, policyCtx)),
+					decision,
+				});
+			}
 			if (decision.action === "deny") {
-				return { kind: "block", reason: formatDenial(decision) };
+				return { kind: "block", reason: formatDenial(decision), audit: payload };
 			}
-			return { kind: "ask", request: askRequest(decision, ctx.cwd, units) };
+			return {
+				kind: "ask",
+				request: askRequest(decision, ctx.cwd, units, payload),
+			};
 		},
 	});
 

package/src/features/permission/policy.ts

@@ -30,12 +30,31 @@ export interface PolicyTarget {
 
 export interface PolicyDecision {
 	readonly action: PolicyAction;
+	/** Machine-readable reason class, for the audit log and tests. */
+	readonly layer: PolicyLayer;
 	readonly unit: CommandUnit;
 	readonly target?: PolicyTarget;
 	/** Human/model-facing explanation for ask and deny. */
 	readonly reason?: string;
 }
 
+/**
+ * Which rule decided a unit: the four modes, one of the fixed tables, a session
+ * grant, or a parser fallback. Kept separate from the human-facing reason so
+ * the audit log can group decisions without parsing English.
+ */
+export type PolicyLayer =
+	| "mode"
+	| "secret"
+	| "session-allow"
+	| "session-deny"
+	| "session-command"
+	| "danger"
+	| "privileged"
+	| "opaque"
+	| "unresolved"
+	| "empty";
+
 export interface PolicyContext {
 	readonly modes: PermissionModes;
 	/** Canonical session roots (working directory plus added directories). */
@@ -81,6 +100,7 @@ function decidePath(
 	if (secret !== undefined) {
 		return {
 			action: "deny",
+			layer: "secret",
 			unit,
 			target: { path: pathValue, effect, scope },
 			reason: `${secret} — denied by the fixed safety table`,
@@ -90,19 +110,23 @@ function decidePath(
 	if (ctx.rules.denies(effect, pathValue)) {
 		return {
 			action: "deny",
+			layer: "session-deny",
 			unit,
 			target,
 			reason: `${effect} under ${pathValue} was denied for this session`,
 		};
 	}
 	if (ctx.rules.allows(effect, pathValue)) {
-		return { action: "allow", unit, target };
+		return { action: "allow", layer: "session-allow", unit, target };
 	}
 	const mode = modeFor(ctx.modes, effect, scope);
-	if (mode === "allow") return { action: "allow", unit, target };
+	if (mode === "allow") {
+		return { action: "allow", layer: "mode", unit, target };
+	}
 	if (mode === "deny") {
 		return {
 			action: "deny",
+			layer: "mode",
 			unit,
 			target,
 			reason: `${scope === "out" ? "outside-project" : "in-project"} ${effect} is set to deny`,
@@ -110,6 +134,7 @@ function decidePath(
 	}
 	return {
 		action: "ask",
+		layer: "mode",
 		unit,
 		target,
 		reason:
@@ -130,6 +155,7 @@ export function decideUnit(
 		// to grant.
 		return {
 			action: "ask",
+			layer: "opaque",
 			unit,
 			reason: unit.note ?? "this command could not be analysed",
 		};
@@ -149,6 +175,7 @@ export function decideUnit(
 	if (secret?.reason !== undefined) {
 		return {
 			action: "deny",
+			layer: "secret",
 			unit,
 			target: {
 				path: secret.target.path,
@@ -163,6 +190,7 @@ export function decideUnit(
 		if (baseSecret !== undefined) {
 			return {
 				action: "deny",
+				layer: "secret",
 				unit,
 				target: {
 					path: canonicalBase,
@@ -221,6 +249,7 @@ export function decideUnit(
 		}
 		return {
 			action: "ask",
+			layer: danger !== undefined ? "danger" : "privileged",
 			unit,
 			target,
 			reason: danger ?? "privileged command",
@@ -231,6 +260,7 @@ export function decideUnit(
 		if (canonicalBase === null) {
 			return {
 				action: "ask",
+				layer: "unresolved",
 				unit,
 				reason: "the working directory could not be resolved",
 			};
@@ -263,6 +293,7 @@ export function decideProgram(
 	if (units.length === 0) {
 		return {
 			action: "allow",
+			layer: "empty",
 			unit: {
 				raw: "",
 				headWord: "",
@@ -284,12 +315,17 @@ export function decideProgram(
 		if (ctx.rules.deniesCommand(key)) {
 			return {
 				action: "deny",
+				layer: "session-command",
 				unit: opaqueUnit,
 				reason: "this command was denied for this session",
 			};
 		}
 		if (ctx.rules.allowsCommand(key)) {
-			return { action: "allow", unit: opaqueUnit };
+			return {
+				action: "allow",
+				layer: "session-command",
+				unit: opaqueUnit,
+			};
 		}
 	}