pi-subagents 0.40.0 → 0.42.0

package/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -38,6 +38,7 @@ interface ServerEntry {
 	exposeResources?: boolean;
 	includeTools?: string[];
 	excludeTools?: string[];
+	protocolVersion?: string;
 	directTools?: boolean | string[];
 }
 
@@ -284,6 +285,7 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 		exposeResources: definition.exposeResources,
 		includeTools: definition.includeTools,
 		excludeTools: definition.excludeTools,
+		protocolVersion: definition.protocolVersion,
 	};
 	return createHash("sha256").update(stableStringify(identity)).digest("hex");
 }

package/src/runs/shared/nested-events.ts

@@ -2,8 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import {
-	ASYNC_DIR,
-	RESULTS_DIR,
+	DIRS,
 	TEMP_ROOT_DIR,
 	type AsyncJobState,
 	type AsyncStatus,
@@ -30,6 +29,7 @@ import {
 } from "./pi-args.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { sanitizeProcessTerminal } from "../background/process-terminal.ts";
+import { THINKING_LEVELS } from "../../shared/model-info.ts";
 
 export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
 const ROUTE_FILE = "route.json";
@@ -281,9 +281,13 @@ function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefi
 	const status = raw.status === "pending" || raw.status === "running" || raw.status === "complete" || raw.status === "completed" || raw.status === "failed" || raw.status === "paused" || raw.status === "stopped"
 		? raw.status
 		: "pending";
+	const model = stringValue(raw.model);
+	const thinking = THINKING_LEVELS.find((level) => level === raw.thinking);
 	return {
 		agent,
 		status,
+		...(model ? { model } : {}),
+		...(thinking ? { thinking } : {}),
 		...(stringValue(raw.sessionFile, 2048) ? { sessionFile: stringValue(raw.sessionFile, 2048) } : {}),
 		...(raw.activityState === "active_long_running" || raw.activityState === "needs_attention" ? { activityState: raw.activityState } : {}),
 		...(clampNumber(raw.lastActivityAt) !== undefined ? { lastActivityAt: clampNumber(raw.lastActivityAt) } : {}),
@@ -324,6 +328,8 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 		depth: Math.min(Math.max(0, clampNumber(raw.depth) ?? 0), MAX_DEPTH),
 		path: pathParts,
 		state: sanitizeState(raw.state, "running"),
+		...(stringValue(raw.model) ? { model: stringValue(raw.model) } : {}),
+		...(THINKING_LEVELS.find((level) => level === raw.thinking) ? { thinking: THINKING_LEVELS.find((level) => level === raw.thinking) } : {}),
 		...(stringValue(raw.asyncDir, 2048) ? { asyncDir: stringValue(raw.asyncDir, 2048) } : {}),
 		...(clampNumber(raw.pid) !== undefined && clampNumber(raw.pid)! > 0 && Number.isInteger(clampNumber(raw.pid)) ? { pid: clampNumber(raw.pid) } : {}),
 		...(stringValue(raw.sessionId, 256) ? { sessionId: stringValue(raw.sessionId, 256) } : {}),
@@ -415,6 +421,36 @@ function terminal(state: NestedRunState): boolean {
 	return state === "complete" || state === "failed" || state === "paused" || state === "stopped";
 }
 
+function mergeBoundedChildren(existing: NestedRunSummary[] | undefined, incoming: NestedRunSummary[] | undefined): NestedRunSummary[] | undefined {
+	if (incoming === undefined) return existing?.slice(0, MAX_CHILDREN);
+	const incomingById = new Map(incoming.map((child) => [child.id, child]));
+	const merged = (existing ?? []).map((child) => incomingById.get(child.id) ?? child);
+	for (const child of incoming) {
+		if (!existing?.some((prior) => prior.id === child.id)) merged.push(child);
+	}
+	return merged.slice(0, MAX_CHILDREN);
+}
+
+function mergeStepSummary(existing: NestedStepSummary | undefined, incoming: NestedStepSummary): NestedStepSummary {
+	if (!existing || existing.agent !== incoming.agent) return { ...incoming, ...(incoming.children ? { children: incoming.children.slice(0, MAX_CHILDREN) } : {}) };
+	const metadata = { ...existing } as Partial<NestedStepSummary>;
+	delete metadata.status;
+	delete metadata.activityState;
+	delete metadata.lastActivityAt;
+	delete metadata.currentTool;
+	delete metadata.currentToolStartedAt;
+	delete metadata.currentPath;
+	delete metadata.turnCount;
+	delete metadata.toolCount;
+	delete metadata.children;
+	const children = mergeBoundedChildren(existing.children, incoming.children);
+	return {
+		...metadata,
+		...incoming,
+		...(children ? { children } : {}),
+	};
+}
+
 function mergeSummary(existing: NestedRunSummary | undefined, event: NestedEventRecord): NestedRunSummary {
 	const incomingState = event.type === "subagent.nested.completed" && event.child.state === "running" ? "complete" : event.child.state;
 	const incoming = { ...event.child, state: incomingState, lastUpdate: event.child.lastUpdate ?? event.ts };
@@ -424,7 +460,21 @@ function mergeSummary(existing: NestedRunSummary | undefined, event: NestedEvent
 	if (incomingUpdate < existingUpdate) return existing;
 	if (terminal(existing.state) && !terminal(incoming.state)) return existing;
 	if (terminal(existing.state) && terminal(incoming.state) && incomingUpdate === existingUpdate) return existing;
-	return { ...existing, ...incoming, state: incoming.state, lastUpdate: Math.max(existingUpdate, incomingUpdate) };
+	const existingSteps = existing.steps ?? [];
+	const incomingSteps = incoming.steps;
+	const steps = incomingSteps === undefined
+		? existing.steps
+		: Array.from({ length: Math.min(MAX_STEPS, Math.max(existingSteps.length, incomingSteps.length)) }, (_, index) =>
+			incomingSteps[index] ? mergeStepSummary(existingSteps[index], incomingSteps[index]!) : existingSteps[index]!).filter((step): step is NestedStepSummary => Boolean(step));
+	const children = mergeBoundedChildren(existing.children, incoming.children);
+	return {
+		...existing,
+		...incoming,
+		...(steps ? { steps } : {}),
+		...(children ? { children } : {}),
+		state: incoming.state,
+		lastUpdate: Math.max(existingUpdate, incomingUpdate),
+	};
 }
 
 function attachChild(children: NestedRunSummary[], event: NestedEventRecord): NestedRunSummary[] {
@@ -947,6 +997,8 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.pid ? { pid: status.pid } : {}),
 		...(status.sessionId ? { sessionId: status.sessionId } : {}),
 		mode: status.mode ?? fallback.mode,
+		...(status.steps?.length === 1 && status.steps[0]?.model ? { model: status.steps[0].model } : {}),
+		...(status.steps?.length === 1 && status.steps[0]?.thinking ? { thinking: status.steps[0].thinking } : {}),
 		...(status.processTerminal ? { processTerminal: sanitizeProcessTerminal(status.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: status.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json`) } : {}),
 		...(status.launchResolvedExtensions ? { launchResolvedExtensions: status.launchResolvedExtensions } : {}),
 		...runtimeAcknowledgedEntry(status.runtimeAcknowledgedExtensions),
@@ -978,6 +1030,8 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.steps?.length ? { steps: status.steps.map((step, index) => ({
 			agent: step.agent,
 			status: step.status,
+			...(step.model ? { model: step.model } : {}),
+			...(step.thinking ? { thinking: step.thinking } : {}),
 			...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
 			...(step.activityState ? { activityState: step.activityState } : {}),
 			...(step.lastActivityAt !== undefined ? { lastActivityAt: step.lastActivityAt } : {}),
@@ -1012,11 +1066,11 @@ export function nestedArtifactEnv(rootRunId: string, parentRunId: string): Recor
 
 export function isTopLevelAsyncDir(asyncDir: string): boolean {
 	const resolved = path.resolve(asyncDir);
-	return containedPath(ASYNC_DIR, resolved) && !containedPath(path.join(TEMP_ROOT_DIR, "nested-subagent-runs"), resolved);
+	return containedPath(DIRS.async, resolved) && !containedPath(path.join(TEMP_ROOT_DIR, "nested-subagent-runs"), resolved);
 }
 
 export function nestedResultsPath(rootRunId: string, id: string): string {
 	assertSafeId("rootRunId", rootRunId);
 	assertSafeId("id", id);
-	return path.join(RESULTS_DIR, "nested", rootRunId, `${id}.json`);
+	return path.join(DIRS.results, "nested", rootRunId, `${id}.json`);
 }

package/src/runs/shared/nested-render.ts

@@ -1,4 +1,4 @@
-import { formatDuration, formatTokens, shortenPath } from "../../shared/formatters.ts";
+import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
 import { formatActivityLabel } from "../../shared/status-format.ts";
 import type { ActivityState, NestedRunSummary, NestedStepSummary } from "../../shared/types.ts";
 
@@ -8,12 +8,13 @@ export interface NestedRunCounts {
 	paused: number;
 	complete: number;
 	failed: number;
+	rejected: number;
 	stopped: number;
 	queued: number;
 }
 
 export function countNestedRuns(children: NestedRunSummary[] | undefined): NestedRunCounts {
-	const counts: NestedRunCounts = { total: 0, running: 0, paused: 0, complete: 0, failed: 0, stopped: 0, queued: 0 };
+	const counts: NestedRunCounts = { total: 0, running: 0, paused: 0, complete: 0, failed: 0, rejected: 0, stopped: 0, queued: 0 };
 	for (const child of children ?? []) {
 		counts.total++;
 		counts[child.state]++;
@@ -23,6 +24,7 @@ export function countNestedRuns(children: NestedRunSummary[] | undefined): Neste
 		counts.paused += nested.paused;
 		counts.complete += nested.complete;
 		counts.failed += nested.failed;
+		counts.rejected += nested.rejected;
 		counts.stopped += nested.stopped;
 		counts.queued += nested.queued;
 	}
@@ -36,6 +38,7 @@ export function formatNestedAggregate(children: NestedRunSummary[] | undefined):
 		counts.running > 0 ? `${counts.running} running` : "",
 		counts.paused > 0 ? `${counts.paused} paused` : "",
 		counts.failed > 0 ? `${counts.failed} failed` : "",
+		counts.rejected > 0 ? `${counts.rejected} rejected` : "",
 		counts.stopped > 0 ? `${counts.stopped} stopped` : "",
 		counts.complete > 0 ? `${counts.complete} complete` : "",
 		counts.queued > 0 ? `${counts.queued} queued` : "",
@@ -88,7 +91,8 @@ function formatNestedRunLines(children: NestedRunSummary[] | undefined, options:
 			}
 			const activity = child.state === "running" ? formatNestedActivity(child) : undefined;
 			const error = child.error ? ` | error: ${child.error}` : "";
-			lines.push(`${indent}↳ ${nestedRunLabel(child)} [${child.id}] ${child.state}${activity ? ` | ${activity}` : ""}${error}`);
+			const modelThinking = formatModelThinking(child.model, child.thinking);
+			lines.push(`${indent}↳ ${nestedRunLabel(child)} [${child.id}] ${child.state}${modelThinking ? ` | ${modelThinking}` : ""}${activity ? ` | ${activity}` : ""}${error}`);
 			if (options.commandHints && lines.length < options.maxLines) lines.push(`${indent}  Status: subagent({ action: "status", id: "${child.id}" })`);
 			if (depth === options.maxDepth) {
 				const aggregate = formatNestedAggregate([...(child.steps?.flatMap((step) => step.children ?? []) ?? []), ...(child.children ?? [])]);
@@ -98,7 +102,8 @@ function formatNestedRunLines(children: NestedRunSummary[] | undefined, options:
 			for (const [stepIndex, step] of (child.steps ?? []).entries()) {
 				if (lines.length >= options.maxLines) return;
 				const stepActivity = step.status === "running" ? formatNestedActivity(step) : undefined;
-				lines.push(`${indent}  ${stepIndex + 1}. ${step.agent} ${step.status}${stepActivity ? ` | ${stepActivity}` : ""}${step.error ? ` | error: ${step.error}` : ""}`);
+				const stepModelThinking = formatModelThinking(step.model, step.thinking);
+				lines.push(`${indent}  ${stepIndex + 1}. ${step.agent} ${step.status}${stepModelThinking ? ` | ${stepModelThinking}` : ""}${stepActivity ? ` | ${stepActivity}` : ""}${step.error ? ` | error: ${step.error}` : ""}`);
 				append(step.children, depth + 1, `${indent}    `);
 			}
 			append(child.children, depth + 1, `${indent}  `);

package/src/runs/shared/parallel-handoff.ts

@@ -11,7 +11,9 @@ import type {
 	WorktreeCleanupReport,
 	WorktreeDiff,
 	WorktreeSetup,
+	WorktreeCleanupIntent,
 } from "./worktree.ts";
+import { cleanupWorktrees } from "./worktree.ts";
 
 export interface ParallelHandoffResult {
 	agent: string;
@@ -79,7 +81,7 @@ export function writeParallelHandoffGroup(input: {
 	flatStartIndex: number;
 	setup: WorktreeSetup;
 	diffs: WorktreeDiff[];
-	cleanup: WorktreeCleanupReport;
+	cleanup?: WorktreeCleanupReport;
 	results: ParallelHandoffResult[];
 	now?: number;
 }): ParallelHandoffReference {
@@ -122,7 +124,19 @@ export function writeParallelHandoffGroup(input: {
 				},
 			};
 		}),
-		cleanup: input.cleanup,
+		cleanup: input.cleanup ?? {
+			state: "partial",
+			pruned: false,
+			tasks: input.setup.worktrees.map((worktree) => ({
+				index: worktree.index,
+				path: worktree.path,
+				branch: worktree.branch,
+				worktreeRemoved: false,
+				branchRemoved: false,
+				preserved: true,
+				reason: "cleanup pending durable handoff capture",
+			})),
+		},
 	};
 	const groups = existing?.groups.filter((candidate) => candidate.stepIndex !== input.stepIndex) ?? [];
 	groups.push(group);
@@ -145,6 +159,19 @@ export function parallelHandoffPath(baseDir: string, runId?: string): string {
 	return runId ? path.join(baseDir, "handoffs", `${runId}.json`) : path.join(baseDir, "handoff.json");
 }
 
+export function writePendingParallelHandoff(input: {
+	manifestPath: string;
+	runId: string;
+	mode: "parallel" | "chain";
+	source: "foreground" | "async";
+	cwd: string;
+	stepIndex: number;
+	flatStartIndex: number;
+	setup: WorktreeSetup;
+}): ParallelHandoffReference {
+	return writeParallelHandoffGroup({ ...input, diffs: [], results: [] });
+}
+
 export function formatParallelHandoffReference(reference: ParallelHandoffReference): string {
 	return `Parallel handoff: ${reference.path} (${reference.childCount} children, ${reference.changedPatches} changed patches, cleanup ${reference.cleanupState})`;
 }
@@ -152,3 +179,60 @@ export function formatParallelHandoffReference(reference: ParallelHandoffReferen
 export function formatParallelHandoffError(error: unknown): string {
 	return `Parallel handoff unavailable: ${error instanceof Error ? error.message : String(error)}`;
 }
+
+export function discardPreservedWorktrees(
+	manifestPath: string,
+	authorization: Extract<WorktreeCleanupIntent, { kind: "discard" }>["authorization"],
+): { manifest: ParallelHandoffManifest; text: string } {
+	const resolvedPath = path.resolve(manifestPath);
+	const manifest = readManifest(resolvedPath);
+	if (!manifest) throw new Error(`Parallel handoff manifest not found: ${resolvedPath}`);
+	let attempted = 0;
+	for (const group of manifest.groups) {
+		const pending = group.cleanup.tasks.filter((task) => task.preserved && (!task.worktreeRemoved || !task.branchRemoved));
+		if (pending.length === 0) continue;
+		attempted += pending.length;
+		const report = cleanupWorktrees({
+			cwd: group.repoRoot,
+			baseCommit: group.baseCommit,
+			worktrees: pending.map((task) => ({
+				path: task.path,
+				agentCwd: task.path,
+				branch: task.branch,
+				index: task.index,
+				nodeModulesLinked: false,
+				syntheticPaths: [],
+			})),
+		}, { kind: "discard", authorization });
+		const updates = new Map(report.tasks.map((task) => [task.index, task.worktreeRemoved && task.branchRemoved
+			? task
+			: { ...task, preserved: true, reason: task.reason ?? "discard cleanup remains incomplete" }]));
+		group.cleanup = {
+			state: group.cleanup.tasks.every((task) => {
+				const next = updates.get(task.index) ?? task;
+				return next.worktreeRemoved && next.branchRemoved;
+			}) && report.pruned ? "complete" : "partial",
+			tasks: group.cleanup.tasks.map((task) => updates.get(task.index) ?? task),
+			pruned: report.pruned,
+			...(report.errors ? { errors: report.errors } : {}),
+		};
+	}
+	manifest.updatedAt = Date.now();
+	writeAtomicJson(resolvedPath, manifest);
+	const remaining = manifest.groups.flatMap((group) => group.cleanup.tasks.map((task) => ({ group, task })))
+		.filter(({ task }) => task.preserved && (!task.worktreeRemoved || !task.branchRemoved));
+	const lines = attempted === 0
+		? [`No preserved worktrees remain in ${resolvedPath}.`]
+		: [`Discard processed ${attempted} preserved worktree${attempted === 1 ? "" : "s"}.`, `Manifest: ${resolvedPath}`];
+	if (remaining.length > 0) {
+		lines.push("", "Some worktrees remain. Inspect and remove them manually if appropriate:");
+		for (const { group, task } of remaining) {
+			lines.push(
+				`  git -C ${JSON.stringify(group.repoRoot)} status --short`,
+				`  git -C ${JSON.stringify(group.repoRoot)} worktree remove --force ${JSON.stringify(task.path)}`,
+				`  git -C ${JSON.stringify(group.repoRoot)} branch -D ${JSON.stringify(task.branch)}`,
+			);
+		}
+	}
+	return { manifest, text: lines.join("\n") };
+}

package/src/runs/shared/parallel-utils.ts

@@ -1,8 +1,13 @@
+export type ResolvedRunnerConfig = import("../../shared/types.ts").AgentRunnerConfig;
+
 export interface RunnerSubagentStep {
 	/** Session id of the direct parent session for permission-system ask forwarding. */
 	parentSessionId?: string;
+	/** Resolved opt-in rules for native Pi child tool calls. */
+	permissionRules?: import("./permissions.ts").PermissionRules;
 	agent: string;
 	task: string;
+	runner?: ResolvedRunnerConfig;
 	/** Resolved launch context for this child. */
 	context?: "fresh" | "fork";
 	importAsyncRoot?: {
@@ -86,6 +91,8 @@ export interface DynamicRunnerGroup {
 	acceptanceRole?: import("../../shared/types.ts").AcceptanceRole;
 	agentContract?: import("../../shared/types.ts").AgentContract;
 	gateOn?: import("../../shared/types.ts").ChainGateLayer;
+	capabilityCeiling?: import("./capability-ceiling.ts").ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: import("./capability-ceiling.ts").SubagentCapabilityAudit;
 }
 
 export type RunnerStep = RunnerSubagentStep | ParallelStepGroup | DynamicRunnerGroup | RunnerCheckpointStep;
@@ -178,15 +185,17 @@ export async function mapConcurrent<T, R>(
 		try {
 			while (next < items.length) {
 				const i = next++;
+				if (!(i in items)) throw new Error(`Missing parallel item at index ${i}`);
+				const item = items[i] as T;
 				if (globalSemaphore) {
 					await globalSemaphore.acquire();
 					try {
-						results[i] = await fn(items[i], i);
+						results[i] = await fn(item, i);
 					} finally {
 						globalSemaphore.release();
 					}
 				} else {
-					results[i] = await fn(items[i], i);
+					results[i] = await fn(item, i);
 				}
 			}
 		} finally {

package/src/runs/shared/permissions.ts

@@ -0,0 +1,95 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type PermissionDecision = "allow" | "ask" | "deny";
+export type PermissionRules = Record<string, PermissionDecision>;
+export interface PermissionConfig { rules?: PermissionRules }
+
+export const PERMISSION_POLICY_ENV = "PI_SUBAGENT_PERMISSION_POLICY";
+export const PERMISSION_AUDIT_PATH_ENV = "PI_SUBAGENT_PERMISSION_AUDIT_PATH";
+const INTERNAL_TOOLS = new Set(["contact_supervisor", "intercom", "subagent_wait", "structured_output"]);
+const DECISIONS = new Set<PermissionDecision>(["allow", "ask", "deny"]);
+const MAX_POLICY_BYTES = 16 * 1024;
+const MAX_PREVIEW_BYTES = 2048;
+const SECRET_KEY = /(?:authorization|cookie|credential|password|secret|token|api[-_]?key)/i;
+const SECRET_VALUE = /\b(?:Bearer\s+\S+|(?:sk|ghp|github_pat|xox[baprs])[-_A-Za-z0-9]{8,})\b/gi;
+
+export function validatePermissionRules(value: unknown, label: string): PermissionRules | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object mapping tool names to allow, ask, or deny.`);
+	const result: PermissionRules = {};
+	for (const [tool, decision] of Object.entries(value)) {
+		if (!tool.trim()) throw new Error(`${label} contains an empty tool name.`);
+		if (tool === "bash") throw new Error(`${label}.bash is unsupported; pi-subagents leaves bash policy to pi-guard.`);
+		if (INTERNAL_TOOLS.has(tool)) throw new Error(`${label}.${tool} is reserved for child coordination and cannot be gated.`);
+		if (!DECISIONS.has(decision as PermissionDecision)) throw new Error(`${label}.${tool} must be allow, ask, or deny.`);
+		result[tool] = decision as PermissionDecision;
+	}
+	return Object.keys(result).length ? result : undefined;
+}
+
+export function validatePermissionConfig(value: unknown, label = "config.permissions"): PermissionConfig | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	const object = value as Record<string, unknown>;
+	const unknown = Object.keys(object).filter((key) => key !== "rules");
+	if (unknown.length) throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
+	return { rules: validatePermissionRules(object.rules, `${label}.rules`) };
+}
+
+export function resolvePermissionRules(globalConfig?: PermissionConfig, agentRules?: PermissionRules): PermissionRules | undefined {
+	const merged = { ...(globalConfig?.rules ?? {}), ...(agentRules ?? {}) };
+	for (const [tool, decision] of Object.entries(merged)) if (decision === "allow") delete merged[tool];
+	return Object.keys(merged).length ? merged : undefined;
+}
+
+export function permissionDecision(rules: PermissionRules | undefined, toolName: string): PermissionDecision {
+	if (toolName === "bash" || INTERNAL_TOOLS.has(toolName)) return "allow";
+	return rules?.[toolName] ?? "allow";
+}
+
+export function encodePermissionRules(rules: PermissionRules | undefined): string | undefined {
+	if (!rules || Object.keys(rules).length === 0) return undefined;
+	const encoded = JSON.stringify(rules);
+	if (Buffer.byteLength(encoded, "utf-8") > MAX_POLICY_BYTES) throw new Error("Resolved permission policy is too large.");
+	return encoded;
+}
+
+export function decodePermissionRules(encoded: string | undefined): PermissionRules | undefined {
+	if (!encoded?.trim()) return undefined;
+	return validatePermissionRules(JSON.parse(encoded), PERMISSION_POLICY_ENV);
+}
+
+function redact(value: unknown, key = "", depth = 0): unknown {
+	if (SECRET_KEY.test(key)) return "[redacted]";
+	if (depth >= 3) return "[truncated]";
+	if (Array.isArray(value)) return value.slice(0, 10).map((item) => redact(item, "", depth + 1));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value as Record<string, unknown>).slice(0, 20).map(([entryKey, entryValue]) => [entryKey, redact(entryValue, entryKey, depth + 1)]));
+	if (typeof value === "string") {
+		const redacted = value.replace(SECRET_VALUE, "[redacted]");
+		return redacted.length > 500 ? `${redacted.slice(0, 500)}…` : redacted;
+	}
+	return value;
+}
+
+export function permissionArgsPreview(input: unknown): string {
+	const serialized = JSON.stringify(redact(input));
+	if (!serialized) return "{}";
+	if (Buffer.byteLength(serialized, "utf-8") <= MAX_PREVIEW_BYTES) return serialized;
+	const maxContentBytes = MAX_PREVIEW_BYTES - Buffer.byteLength("…", "utf-8");
+	let preview = "";
+	let previewBytes = 0;
+	for (const character of serialized) {
+		const characterBytes = Buffer.byteLength(character, "utf-8");
+		if (previewBytes + characterBytes > maxContentBytes) break;
+		preview += character;
+		previewBytes += characterBytes;
+	}
+	return `${preview}…`;
+}
+
+export function appendPermissionAudit(filePath: string | undefined, record: Record<string, unknown>): void {
+	if (!filePath) return;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+	fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, { encoding: "utf-8", mode: 0o600 });
+}