@henryqw/pi-subagent 18.0.0 → 22.0.0

package/extensions/admission.ts

@@ -0,0 +1,66 @@
+import { realpath } from "node:fs/promises";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Role } from "../src/index.ts";
+
+const READ_ONLY_TOOLS = new Set([
+	"read", "grep", "find", "ffgrep", "fffind", "ls", "codegraph_explore", "subagent_status",
+]);
+
+export function roleCanWrite(role: Role): boolean {
+	return Boolean(role.extensions.length || role.mcps?.length || role.tools.some((tool) => !READ_ONLY_TOOLS.has(tool)));
+}
+
+export interface CheckoutAdmission {
+	register(pi: ExtensionAPI, directCanWrite: (input: unknown) => boolean): void;
+}
+
+async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<string> {
+	const cwd = await realpath(ctx.cwd);
+	const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd, timeout: 5_000 });
+	if (result.code !== 0 || result.killed) return cwd;
+	const root = result.stdout.replace(/\r?\n$/, "");
+	if (!root || /[\r\n\0]/.test(root)) throw new Error("Git returned a malformed checkout root during delegation admission.");
+	return await realpath(root);
+}
+
+/**
+ * Coordinate Pi-owned calls that can mutate one checkout. This is admission,
+ * not an OS sandbox: external processes and trusted extension lifecycle code
+ * remain outside interception.
+ */
+export function createCheckoutAdmission(): CheckoutAdmission {
+	const ownerByCheckout = new Map<string, string>();
+	const checkoutByCall = new Map<string, string>();
+	const release = (toolCallId: string) => {
+		const key = checkoutByCall.get(toolCallId);
+		if (!key) return;
+		checkoutByCall.delete(toolCallId);
+		if (ownerByCheckout.get(key) === toolCallId) ownerByCheckout.delete(key);
+	};
+	return {
+		register(pi, directCanWrite) {
+			pi.on("tool_call", async (event, ctx) => {
+				const potentiallyWriting = event.toolName === "delegate_task"
+					? directCanWrite(event.input)
+					: !READ_ONLY_TOOLS.has(event.toolName);
+				if (!potentiallyWriting) return;
+				const key = await checkoutKey(pi, ctx);
+				const owner = ownerByCheckout.get(key);
+				if (owner && owner !== event.toolCallId) {
+					return {
+						block: true,
+						reason: `Checkout ${key} already has an admitted Pi writer (${owner}); retry after it settles.`,
+					};
+				}
+				ownerByCheckout.set(key, event.toolCallId);
+				checkoutByCall.set(event.toolCallId, key);
+			});
+			pi.on("tool_result", (event) => release(event.toolCallId));
+			pi.on("tool_execution_end", (event) => release(event.toolCallId));
+			pi.on("session_shutdown", () => {
+				ownerByCheckout.clear();
+				checkoutByCall.clear();
+			});
+		},
+	};
+}

package/extensions/config.ts

@@ -12,56 +12,68 @@ export interface SubagentConfig {
 	maxSubagents?: number;
 	maxTurns?: number;
 	maxTokens?: number;
+	maxCorrections?: number;
 	timeout?: SubagentTimeoutConfig;
 }
 
 export interface LoadedSubagentConfig {
 	source: "file" | "missing";
 	config: SubagentConfig;
-	/** Human-readable problems when the file exists but is partly unusable; the file is never rewritten. */
+	/** Human-readable problems; malformed files are preserved and delegation fails closed. */
 	error?: string;
 }
 
+export interface EffectiveExecutionPolicy {
+	maxSubagents: number;
+	maxTurns: number;
+	maxTokens?: number;
+	childIdleMs: number;
+	childMaxMs: number;
+	maxCorrections: number;
+}
+
 type ParsedSubagentConfig = Omit<LoadedSubagentConfig, "source">;
 
 const EXTENSION_ID = "pi-subagent";
 const positive = (value: unknown): value is number =>
 	typeof value === "number" && Number.isFinite(value) && value > 0;
-
-// Node clamps setTimeout delays above 2^31 - 1 ms to 1 ms, which would kill
-// every child immediately instead of applying the configured deadline.
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export const DEFAULT_TIMEOUT_CONFIG = { idleMinutes: 10, maxMinutes: 30 } as const;
+export const DEFAULT_EXECUTION_POLICY = {
+	maxSubagents: 5,
+	maxTurns: 50,
+	maxCorrections: 1,
+} as const;
 const INTEGER_FIELDS = ["maxSubagents", "maxTurns", "maxTokens"] as const;
+const POLICY_FIELDS = ["maxCorrections"] as const;
 const TIMEOUT_FIELDS = ["idleMinutes", "maxMinutes"] as const;
 
-/** Return the canonical default JSON path for pi-subagent's config home. */
 export const configPath = (agentDir = getAgentDir()): string =>
 	extensionConfigPath(EXTENSION_ID, agentDir);
 
 function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfig {
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-		return { config: {}, error: `${path} must contain a JSON object; using defaults.` };
+		return { config: {}, error: `${path} must contain a JSON object; delegation is blocked until this file is corrected.` };
 	}
 	const record = parsed as Record<string, unknown>;
 	const problems: string[] = [];
 	const config: SubagentConfig = {};
 	for (const key of Object.keys(record)) {
-		if (![...INTEGER_FIELDS, "timeout"].includes(key as typeof INTEGER_FIELDS[number] | "timeout")) {
-			problems.push(`unknown config key ${JSON.stringify(key)}; expected ${INTEGER_FIELDS.join(", ")}, timeout`);
+		if (![...INTEGER_FIELDS, ...POLICY_FIELDS, "timeout"].includes(key as never)) {
+			problems.push(`unknown config key ${JSON.stringify(key)}; expected ${[...INTEGER_FIELDS, ...POLICY_FIELDS].join(", ")}, timeout`);
 		}
 	}
-
 	for (const key of INTEGER_FIELDS) {
 		const value = record[key];
 		if (value === undefined) continue;
-		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) {
-			config[key] = value;
-		} else {
-			problems.push(`${key} must be a safe integer >= 1, got ${JSON.stringify(value)}`);
-		}
+		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) config[key] = value;
+		else problems.push(`${key} must be a safe integer >= 1, got ${JSON.stringify(value)}`);
+	}
+	if (record.maxCorrections !== undefined) {
+		if (!Number.isSafeInteger(record.maxCorrections) || (record.maxCorrections as number) < 0) {
+			problems.push(`maxCorrections must be a safe integer >= 0, got ${JSON.stringify(record.maxCorrections)}`);
+		} else config.maxCorrections = record.maxCorrections as number;
 	}
-
 	if (record.timeout !== undefined) {
 		if (!record.timeout || typeof record.timeout !== "object" || Array.isArray(record.timeout)) {
 			problems.push(`timeout must be a JSON object, got ${JSON.stringify(record.timeout)}`);
@@ -71,26 +83,16 @@ function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfi
 			for (const key of TIMEOUT_FIELDS) {
 				const value = timeoutRecord[key];
 				if (value === undefined) continue;
-				if (!positive(value)) {
-					problems.push(`timeout.${key} must be a positive number of minutes, got ${JSON.stringify(value)}`);
-				} else if (value * 60_000 > MAX_TIMER_DELAY_MS) {
-					problems.push(`timeout.${key} exceeds the maximum supported delay of ${MAX_TIMER_DELAY_MS} ms, got ${JSON.stringify(value)} minutes`);
-				} else {
-					timeout[key] = value;
-				}
+				if (!positive(value)) problems.push(`timeout.${key} must be a positive number of minutes, got ${JSON.stringify(value)}`);
+				else if (value * 60_000 > MAX_TIMER_DELAY_MS) problems.push(`timeout.${key} exceeds ${MAX_TIMER_DELAY_MS} ms, got ${JSON.stringify(value)} minutes`);
+				else timeout[key] = value;
 			}
 			for (const key of Object.keys(timeoutRecord)) {
-				if (!TIMEOUT_FIELDS.includes(key as keyof SubagentTimeoutConfig)) {
-					problems.push(`unknown timeout.${key}; expected ${TIMEOUT_FIELDS.join(", ")}`);
-				}
+				if (!TIMEOUT_FIELDS.includes(key as keyof SubagentTimeoutConfig)) problems.push(`unknown timeout.${key}; expected ${TIMEOUT_FIELDS.join(", ")}`);
 			}
 			if (Object.keys(timeout).length) config.timeout = timeout;
 		}
 	}
-
-	// The hard cap must exceed the idle deadline or every idle kill is
-	// unreachable. Falling back to defaults drops the whole timeout object,
-	// matching other invalid values.
 	if (config.timeout) {
 		const idleMinutes = config.timeout.idleMinutes ?? DEFAULT_TIMEOUT_CONFIG.idleMinutes;
 		const maxMinutes = config.timeout.maxMinutes ?? DEFAULT_TIMEOUT_CONFIG.maxMinutes;
@@ -99,15 +101,27 @@ function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfi
 			delete config.timeout;
 		}
 	}
+	return {
+		config,
+		error: problems.length ? `${path}: ${problems.join("; ")}; delegation is blocked until this file is corrected.` : undefined,
+	};
+}
 
-	return { config, error: problems.length ? `${path}: ${problems.join("; ")}; invalid settings use defaults while valid settings still apply.` : undefined };
+/** Resolve one immutable policy. Malformed explicit safety settings fail closed. */
+export function resolveExecutionPolicy(loaded: LoadedSubagentConfig): EffectiveExecutionPolicy {
+	if (loaded.error) throw new Error(loaded.error);
+	const timeout = loaded.config.timeout;
+	return Object.freeze({
+		maxSubagents: loaded.config.maxSubagents ?? DEFAULT_EXECUTION_POLICY.maxSubagents,
+		maxTurns: loaded.config.maxTurns ?? DEFAULT_EXECUTION_POLICY.maxTurns,
+		...(loaded.config.maxTokens === undefined ? {} : { maxTokens: loaded.config.maxTokens }),
+		childIdleMs: (timeout?.idleMinutes ?? DEFAULT_TIMEOUT_CONFIG.idleMinutes) * 60_000,
+		childMaxMs: (timeout?.maxMinutes ?? DEFAULT_TIMEOUT_CONFIG.maxMinutes) * 60_000,
+		maxCorrections: loaded.config.maxCorrections ?? DEFAULT_EXECUTION_POLICY.maxCorrections,
+	});
 }
 
-/**
- * Read the optional user config at `<agentDir>/config/pi-subagent/config.json`.
- * Treated as untrusted user data: malformed files are preserved untouched and
- * reported instead of crashing the session; callers fall back to defaults.
- */
+/** Read untrusted optional config without rewriting it. */
 export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConfig {
 	const path = configPath(agentDir);
 	let validationError: string | undefined;
@@ -136,8 +150,8 @@ export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConf
 			source: "file",
 			config: {},
 			error: error instanceof SyntaxError
-				? `${path} is not valid JSON (${reason}); using defaults.`
-				: `${path} couldn't be read (${reason}); using defaults.`,
+				? `${path} is not valid JSON (${reason}); delegation is blocked until this file is corrected.`
+				: `${path} couldn't be read (${reason}); delegation is blocked until this file is corrected.`,
 		};
 	}
 }