pi-pr-review 1.8.0 → 1.9.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.8.0"
+  ".": "1.9.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.9.0](https://github.com/10ego/pi-pr-review/compare/v1.8.0...v1.9.0) (2026-07-14)
+
+
+### Features
+
+* **review:** add constrained one-shot self-review ([#18](https://github.com/10ego/pi-pr-review/issues/18)) ([ab267c4](https://github.com/10ego/pi-pr-review/commit/ab267c40415731b2fbbea91c5b345153fa7b6132))
+
 ## [1.8.0](https://github.com/10ego/pi-pr-review/compare/v1.7.1...v1.8.0) (2026-07-14)
 
 

package/README.md

@@ -14,7 +14,7 @@ The default review prioritizes P0–P2 defects and allows up to three minor find
 
 ## Requirements
 
-- Pi `0.77.0` or newer.
+- Pi `0.80.5` or newer (the first release with the terminal `agent_settled` lifecycle event).
 - [`gh`](https://cli.github.com/) installed and authenticated with `gh auth login`.
 - Pi running inside the repository that owns the PR.
 
@@ -158,6 +158,20 @@ Example:
 
 Tier subprocesses retry configured fallbacks only for retryable quota, rate-limit, or capacity failures. If a tier is unset, it uses the nearest configured tier and then Pi's default model.
 
+## One-shot self-review for top-level tasks
+
+For an eligible long-running coding task started by direct interactive or RPC input, Pi exposes `self_review_subagent` near the end of the task. The tool takes no arguments. Its empty schema is closed with `additionalProperties: false`; the extension—not the caller—fixes the objective, heavy tier, P0–P2-only severity policy, no-minor-hygiene policy, and no-tools isolation.
+
+The permit is bound to one top-level task generation, the Pi session instance, cwd, and canonical Git worktree. Dispatch is additionally bound to the tool-call ID from an assistant `message_end` containing exactly one tool call, `self_review_subagent`; mixed, multiple, or direct unbound dispatches are denied without consuming the reusable task permit. A bound permit is consumed atomically before delta capture, so concurrent or replayed calls are rejected and the tool is hidden immediately. It is never available during `/pr-review`. Low-level `agent_end` events do not revoke it because Pi may still retry, compact, or run queued continuations; unused authority is cleared only at terminal `agent_settled` (or earlier cancellation/session/input boundaries).
+
+The child uses Pi RPC mode with a bounded ten-minute total runtime. Before startup, the host creates a mode-`0700` temporary `PI_CODING_AGENT_DIR`, copies and normalizes the trusted user settings there with retry and compaction disabled, and exposes only validated regular `auth.json`/`models.json` files through controlled symlinks. The same private directory—not the mutable worktree—is the child process cwd, and inherited runtime preload flags (`NODE_OPTIONS` and `BUN_OPTIONS`) are removed. RPC control acknowledgements can therefore persist only to temporary settings. The host attempts synchronous recursive removal after every supervised outcome; unsafe source configuration or cleanup failure fails the call closed. Environment-based authentication otherwise remains inherited, and no credentials are placed in arguments or prompts. The host waits for acknowledgements that automatic compaction and automatic retry are disabled before it submits the sole prompt, and it also aborts on timeout, bounded stdout/stderr overflow, any retry/compaction lifecycle event, or a second `agent_start`. There is no fallback, sharding, extension discovery, tools, publication, or verification behavior.
+
+Self-review is deliberately fail-closed. At extension startup, the host resolves one canonical executable Git from that startup `PATH`; the same absolute executable is bound through clean-baseline capture, permit validation, and delta capture, so later `PATH` changes cannot select repository-controlled Git. The worktree must be clean when the top-level task starts and HEAD must remain unchanged. Baseline capture receives its abort signal immediately, so new input, cancellation, or session/tree navigation can stop even the initial Git inspection. At execution, the host builds a complete bounded diff of Git-visible tracked, staged, and non-ignored untracked changes relative to that starting HEAD. It rejects an empty delta, any changed or dirty submodule, more than 200 status records, more than 4 MiB of diff, a changed session/cwd/worktree/HEAD, or a status change during capture.
+
+The child must return strict JSON containing only a `findings` array. Every finding must pass an exact host-owned schema: P0/P1/P2 severity and matching title/blocking state, concrete impact/trigger/evidence strings, normalized repo-relative changed-line coordinates, side, task/diff relationship flags, and bounded confidence. The host derives changed-line anchors from the captured unified diff and requires each claimed range to lie completely within one changed-line run in one hunk on the exact claimed path and side; binary and no-hunk paths have no valid anchors. Markdown, malformed JSON, extra or missing fields, P3/nits, inconsistent metadata, out-of-delta anchors, and unsafe paths are rejected rather than shown as review results. No findings is `{"findings":[]}`.
+
+This is a practical Git-derived boundary, not a filesystem snapshot or sandbox. Ignored files are not included, and an external process that rewrites ordinary file contents without changing status shape could race capture. Requiring a clean start, rejecting submodule deltas, checking HEAD and status before/after capture, incrementally bounding all output, and failing closed avoids silently presenting a partial oversized delta. The RPC leader starts in a detached POSIX process group; on failure, abort, timeout, or retained descendants, the host sends group TERM then KILL, destroys inherited pipes, and stops waiting after a bounded drain deadline. A descendant that deliberately creates a different process group/session can escape those signals, although it cannot force the host to retain the supervised pipes indefinitely. Use a separate sandbox or snapshot system when stronger filesystem, process, or network isolation is required.
+
 ## Publish to GitHub
 
 Publishing is off by default.
@@ -237,6 +251,8 @@ The verdict is `request_changes` only when a validated P0 or P1 finding exists.
 - Every review tool also checks an in-memory, session- and cwd-bound loop lease before reading review context, running verification, or spawning a reviewer. Hiding the tools is not the only enforcement boundary.
 - Unrelated input, terminal completion, cancellation, session navigation, or tree navigation revokes the lease and aborts in-flight review work. Tools are suspended while a non-open PR waits for confirmation.
 - Reviewer subprocesses start with extension discovery disabled, so they cannot recursively invoke this package's agents or verification tool.
+- `self_review_subagent` has separate one-shot authority for an eligible direct top-level task; it cannot authorize `review_subagent`, `review_subagents`, or `pr_review_verify`, and those permissive schemas remain exclusively behind `ReviewLoopCoordinator`.
+- Self-review execute-time checks are authoritative: visibility alone never grants a permit, and consumption hides the tool before any asynchronous delta or child work.
 - Reviewers receive the captured diff and are instructed not to modify files.
 - The orchestrator does not check out, commit, or push PR code.
 - GitHub writes require `--comment`, an effective `autoPostReviews: true` setting, the model-free `/pr-review-publish` command, or a narrowly matched direct interactive/RPC publish request handled by the extension before an agent turn. `allowStalePublish` controls whether an invocation/config-authorized write may be stale; it does not independently authorize a write.

package/extensions/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { ReviewLoopCoordinator } from "../lib/pr-review-loop.ts";
+import { SelfReviewPermitCoordinator } from "../lib/pr-self-review.ts";
 import registerPrReviewSubagents from "./pr-review-subagent.ts";
 import registerReviewFocus from "./pr-review-focus.ts";
 import registerReviewTable from "./review-table.ts";
@@ -7,7 +8,8 @@ import registerReviewTable from "./review-table.ts";
 /** Register the package behind one shared, session-scoped review-loop authority. */
 export default function registerPrReview(pi: ExtensionAPI) {
 	const loopCoordinator = new ReviewLoopCoordinator(pi);
-	registerPrReviewSubagents(pi, loopCoordinator);
+	const selfReviewCoordinator = new SelfReviewPermitCoordinator(pi, () => !!loopCoordinator.peek());
+	registerPrReviewSubagents(pi, loopCoordinator, selfReviewCoordinator);
 	registerReviewFocus(pi, loopCoordinator);
-	registerReviewTable(pi, loopCoordinator);
+	registerReviewTable(pi, loopCoordinator, selfReviewCoordinator);
 }

package/extensions/pr-review-subagent.ts

@@ -56,6 +56,13 @@ import {
 	reviewLoopDeniedResult,
 	type ReviewFocusPublisher,
 } from "../lib/pr-review-loop.ts";
+import { runSelfReviewRpcSubprocess } from "../lib/pr-self-review-rpc.ts";
+import {
+	buildSelfReviewDelta,
+	parseSelfReviewOutput,
+	SelfReviewPermitCoordinator,
+	selfReviewDeniedResult,
+} from "../lib/pr-self-review.ts";
 import {
 	normalizeReviewFocusJsonEvent,
 	ReviewJsonLineDecoder,
@@ -705,6 +712,69 @@ async function runSubagentAttempt(
 	}
 }
 
+const SELF_REVIEW_SYSTEM_PROMPT = [
+	"You are an isolated self-review subagent invoked once by the host for a completed top-level coding task.",
+	"Review only the complete host-derived Git working-tree delta supplied below. Do not infer or request caller context.",
+	"Find only substantiated defects introduced by this delta in correctness, security, performance, state/lifecycle, concurrency, or integration behavior.",
+	"Report only P0, P1, or P2 findings. Do not report P3/nits, style, naming, documentation, tests-only hygiene, or subjective maintainability preferences, and never inflate severity.",
+	"You have no tools. Do not attempt to inspect paths, modify files, run verification, publish comments, or delegate work.",
+	"Return only strict JSON with this exact shape and no Markdown fence: {\"findings\":[{\"title\":\"[P2] Imperative summary\",\"severity\":\"P2\",\"blocking\":false,\"impact\":\"concrete user/system impact\",\"trigger\":\"exact input or environment\",\"evidence\":\"specific causal evidence visible in the delta\",\"path\":\"repo/relative/path.ts\",\"startLine\":1,\"endLine\":1,\"side\":\"RIGHT\",\"inDiff\":true,\"prRelated\":true,\"confidence\":0.9}]}",
+	"Every listed field is required and no additional fields are allowed. blocking is true only for P0/P1. Use exact changed-line coordinates and LEFT only for removed lines. Emit {\"findings\":[]} when no substantiated P0-P2 finding survives validation.",
+].join("\n");
+
+async function runSelfReviewAttempt(
+	config: PrReviewConfig,
+	worktree: string,
+	delta: string,
+	signal: AbortSignal | undefined,
+	onText?: (text: string) => void,
+): Promise<{ result: RunResult; modelSpec?: string; elapsedMs: number }> {
+	let tmp: { dir: string; filePath: string } | undefined;
+	const startedAt = monotonicNow();
+	const modelSpec = config.tiers.heavy;
+	try {
+		const args = buildReviewBaseArgs();
+		args[args.indexOf("json")] = "rpc";
+		args.splice(args.indexOf("-p"), 1);
+		if (modelSpec) args.push("--model", modelSpec);
+		appendTierThinkingArgs(args, modelSpec, config.thinkingLevels.heavy);
+		args.push("--no-tools", "--no-approve");
+		tmp = await writeTempPrompt("heavy", SELF_REVIEW_SYSTEM_PROMPT);
+		args.push("--append-system-prompt", tmp.filePath);
+		const task = [
+			"Objective: Perform the host-defined one-shot major-only self-review of this complete task delta.",
+			"",
+			"--- Complete host-derived task delta ---",
+			delta,
+		].join("\n");
+		const invocation = getPiInvocation(args);
+		const result = await runSelfReviewRpcSubprocess(
+			invocation.command,
+			invocation.args,
+			worktree,
+			task,
+			signal,
+			getAgentDir(),
+		);
+		if (result.text) onText?.(result.text);
+		return { result, modelSpec, elapsedMs: monotonicNow() - startedAt };
+	} catch (error) {
+		return {
+			result: { text: "", exitCode: 1, stderr: "", errorMessage: errMessage(error), toolElapsedMs: 0 },
+			modelSpec,
+			elapsedMs: monotonicNow() - startedAt,
+		};
+	} finally {
+		if (tmp) {
+			try {
+				fs.rmSync(tmp.dir, { recursive: true, force: true });
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+}
+
 async function runSubagentPass(
 	config: PrReviewConfig,
 	ctx: Pick<ExtensionContext, "cwd">,
@@ -862,6 +932,8 @@ function combineContexts(shared: string | undefined, specific: string | undefine
 // Extension
 // ---------------------------------------------------------------------------
 
+const SelfReviewSubagentParams = Type.Object({}, { additionalProperties: false });
+
 const PrReviewVerifyParams = Type.Union([
 	Type.Object(
 		{
@@ -1006,11 +1078,97 @@ const ReviewSubagentsParams = Type.Object({
 export default function registerPrReviewSubagents(
 	pi: ExtensionAPI,
 	loopCoordinator = new ReviewLoopCoordinator(pi),
+	selfReviewCoordinator = new SelfReviewPermitCoordinator(pi, () => !!loopCoordinator.peek()),
 ) {
 	// Resolve security-sensitive executables only from the PATH trusted when this
 	// extension starts, never from a later mutable process environment.
 	const trustedStartupPath = process.env.PATH ?? "";
 
+	pi.registerTool({
+		name: "self_review_subagent",
+		label: "Self Review Subagent",
+		description: [
+			"Perform the host-defined, one-shot P0-P2 self-review for the current eligible top-level user task.",
+			"The host supplies the complete bounded Git-visible task delta, heavy-tier model, objective, isolation, and no-tools policy; this tool accepts no arguments.",
+		].join(" "),
+		promptSnippet: "Run the one-shot host-bounded major-only self-review near the end of an eligible coding task",
+		promptGuidelines: [
+			"Call at most once, near the end of a long-running top-level coding task after implementation and focused tests.",
+			"The permit is consumed before delta capture. A denied or failed call cannot be replayed, and the tool is unavailable during /pr-review.",
+		],
+		parameters: SelfReviewSubagentParams,
+
+		async execute(toolCallId, _params, signal, onUpdate, ctx) {
+			const permit = await selfReviewCoordinator.consume(toolCallId, ctx);
+			if (!permit) return selfReviewDeniedResult();
+			const executionSignal = combineAbortSignals(signal, permit.signal);
+			try {
+				if (executionSignal?.aborted) throw new Error("Self-review was aborted before delta capture.");
+				const captured = await buildSelfReviewDelta({ ...permit, signal: executionSignal ?? permit.signal });
+				if (executionSignal?.aborted) throw new Error("Self-review was aborted before the reviewer could start.");
+				const config = loadConfig(ctx);
+				const attempt = await runSelfReviewAttempt(
+					config,
+					permit.worktree,
+					captured.delta,
+					executionSignal,
+				);
+				const failed = attempt.result.exitCode !== 0 ||
+					attempt.result.stopReason === "error" ||
+					attempt.result.stopReason === "aborted";
+				const details = {
+					authorized: true,
+					generation: permit.generation,
+					tier: "heavy",
+					model: attempt.result.model ?? attempt.modelSpec,
+					exitCode: attempt.result.exitCode,
+					status: failed ? "failed" : "completed",
+					attempts: 1,
+					fallbackUsed: false,
+					toolPolicy: "none",
+					majorOnly: true,
+					minorHygiene: false,
+					deltaBytes: captured.bytes,
+					fileCount: captured.fileCount,
+					elapsedMs: attempt.elapsedMs,
+				};
+				if (failed) {
+					const error = attempt.result.errorMessage || attempt.result.stderr || attempt.result.text || "(no output)";
+					return {
+						content: [{ type: "text", text: `Self-review subagent failed: ${error}` }],
+						isError: true,
+						details,
+					};
+				}
+				let report;
+				try {
+					report = parseSelfReviewOutput(attempt.result.text, captured.anchors);
+				} catch (error) {
+					return {
+						content: [{ type: "text", text: `Self-review rejected malformed or out-of-policy output: ${errMessage(error)}` }],
+						isError: true,
+						details: { ...details, status: "failed", outputRejected: true },
+					};
+				}
+				const text = JSON.stringify(report, null, 2);
+				onUpdate?.({ content: [{ type: "text", text }] });
+				return {
+					content: [{ type: "text", text }],
+					details: { ...details, findingCount: report.findings.length },
+				};
+			} catch (error) {
+				return {
+					content: [{ type: "text", text: `Self-review failed closed: ${errMessage(error)}` }],
+					isError: true,
+					details: { authorized: true, generation: permit.generation, attempts: 0 },
+				};
+			} finally {
+				selfReviewCoordinator.finish(permit);
+			}
+		},
+	});
+	selfReviewCoordinator.hideTool();
+
 	pi.registerTool({
 		name: "pr_review_verify",
 		label: "PR Review Verify",
@@ -1361,6 +1519,7 @@ export default function registerPrReviewSubagents(
 		handler: async (args, ctx) => {
 			// Extension commands execute before input events, so revoke explicitly.
 			loopCoordinator.clear();
+			selfReviewCoordinator.clear();
 			const raw = (args ?? "").trim();
 			const parsed = parseConfigArgs(raw);
 			if (parsed.errors.length) {

package/extensions/review-table.ts

@@ -47,6 +47,7 @@ import {
 	ReviewLoopCoordinator,
 	type ReviewLoopInputSource,
 } from "../lib/pr-review-loop.ts";
+import { SelfReviewPermitCoordinator } from "../lib/pr-self-review.ts";
 import {
 	ReviewTelemetryTracker,
 	type ReviewPerformanceTelemetry,
@@ -428,6 +429,7 @@ async function maybePublishReview(
 export default function registerReviewTable(
 	pi: ExtensionAPI,
 	loopCoordinator = new ReviewLoopCoordinator(pi),
+	selfReviewCoordinator = new SelfReviewPermitCoordinator(pi, () => !!loopCoordinator.peek()),
 ) {
 	const completedReviews = new CompletedReviewCache();
 	const sessionIdentity = (ctx: ExtensionContext): CompletedReviewSessionIdentity | undefined => {
@@ -510,6 +512,7 @@ export default function registerReviewTable(
 		handler: async (args, ctx) => {
 			// Extension commands execute before input hooks, so every invocation —
 			// including malformed arguments — must revoke active review authority.
+			selfReviewCoordinator.clear();
 			const active = loopCoordinator.peek();
 			if (active) {
 				loopCoordinator.clear();
@@ -549,6 +552,7 @@ export default function registerReviewTable(
 
 	const revokeActiveLoop = () => {
 		loopCoordinator.clear();
+		selfReviewCoordinator.clear();
 		pendingCompletion = undefined;
 		telemetryTracker.clear();
 	};
@@ -563,8 +567,17 @@ export default function registerReviewTable(
 		restoreCompletedReviews(ctx);
 	});
 
+	pi.on("before_agent_start", async (_event, ctx) => {
+		await selfReviewCoordinator.beginTask(ctx);
+	});
+
+	pi.on("agent_settled", () => {
+		selfReviewCoordinator.clear();
+	});
+
 	pi.on("session_tree", (event, ctx) => {
 		loopCoordinator.clear();
+		selfReviewCoordinator.clear();
 		pendingCompletion = undefined;
 		restoreCompletedReviews(ctx);
 		telemetryTracker.clear();
@@ -579,6 +592,9 @@ export default function registerReviewTable(
 	});
 
 	pi.on("input", async (event, ctx) => {
+		// Any new input revokes the prior top-level task generation before it can
+		// authorize a replay or a queued/steering continuation.
+		selfReviewCoordinator.clear();
 		const source = event.source as ReviewLoopInputSource;
 		const directPublish = parseDirectPublishRequest(event.text);
 		if (
@@ -620,7 +636,10 @@ export default function registerReviewTable(
 			persistTelemetry(parsed.matched && event.streamingBehavior === undefined ? "replaced" : "cleared");
 			if (!parsed.matched) return;
 		}
-		if (!parsed.matched) return;
+		if (!parsed.matched) {
+			selfReviewCoordinator.noteTopLevelInput(source, event.streamingBehavior, ctx);
+			return;
+		}
 		if (event.streamingBehavior !== undefined) {
 			// Returning handled prevents queueing but does not stop the current parent
 			// operation. Abort it so revoked review work cannot continue with built-ins.
@@ -696,7 +715,18 @@ export default function registerReviewTable(
 	pi.on("message_end", async (event, ctx) => {
 		if (event.message.role !== "assistant") return;
 		const completion = classifyAssistantCompletion(event.message.stopReason, hasToolCall(event.message));
-		if (completion === "continue_tools") return;
+		if (completion === "continue_tools") {
+			const toolCalls = Array.isArray(event.message.content)
+				? event.message.content.filter((part) => part.type === "toolCall")
+				: [];
+			if (toolCalls.length === 1) {
+				const call = toolCalls[0] as { id?: unknown; name?: unknown };
+				if (call.name === "self_review_subagent" && typeof call.id === "string") {
+					selfReviewCoordinator.bindToolCall(call.id, ctx);
+				}
+			}
+			return;
+		}
 		if (completion === "clear_invocation") {
 			loopCoordinator.clear();
 			persistTelemetry("cleared");

package/lib/pr-review-policy.ts

@@ -4,6 +4,7 @@ const RECURSIVE_REVIEW_TOOLS = new Set([
 	"review_subagent",
 	"review_subagents",
 	"pr_review_verify",
+	"self_review_subagent",
 ]);
 
 /** Isolated review subprocesses receive all review context explicitly. */

package/lib/pr-review-verify.ts

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { monotonicNow, type MonotonicNow } from "./pr-review-telemetry.ts";
+import { resolveTrustedExecutableFromStartupPath } from "./trusted-executable.ts";
 
 export const VERIFY_TIMEOUT_MIN_MS = 2_000;
 export const VERIFY_TIMEOUT_MAX_MS = 10 * 60_000;
@@ -617,33 +618,6 @@ function validateCanonicalExecutable(profile: VerificationBaselineProfile): stri
 	return errors;
 }
 
-function canonicalExecutable(candidate: string, label: string): string {
-	if (!path.isAbsolute(candidate)) throw new Error(`${label} executable path must be absolute`);
-	const canonical = fs.realpathSync(candidate);
-	const stat = fs.statSync(canonical);
-	if (!stat.isFile()) throw new Error(`${label} executable must resolve to a regular file`);
-	fs.accessSync(canonical, fs.constants.X_OK);
-	return canonical;
-}
-
-function resolveTrustedExecutableFromStartupPath(
-	name: "gh" | "git",
-	injected: string | undefined,
-	startupPath: string,
-): string {
-	if (injected) return canonicalExecutable(injected, name);
-	for (const directory of startupPath.split(path.delimiter)) {
-		if (!path.isAbsolute(directory)) continue;
-		const candidate = path.join(directory, name);
-		try {
-			return canonicalExecutable(candidate, name);
-		} catch {
-			/* continue through the trusted extension startup PATH */
-		}
-	}
-	throw new Error(`Unable to resolve an accessible ${name} executable from the trusted extension startup PATH.`);
-}
-
 function trustedStartupPath(options: VerifyOptions): string {
 	return options.startupPath ?? (options.ghEnvironment ?? process.env).PATH ?? "";
 }