pi-pr-review 1.1.2 → 1.3.1

package/README.md

@@ -63,15 +63,19 @@ The `/pr-review-config` command maps three labels to models:
 ```
 /pr-review-config                                   # open the settings menu (like /settings & /nervous:config)
 /pr-review-config show                              # print the current mapping
-/pr-review-config light=<spec> medium=<spec> heavy=<spec>   # set non-interactively
+/pr-review-config light=<spec> medium=<spec> heavy=<spec>   # set primary tier models
+/pr-review-config heavy_fallbacks=<spec>,<spec>     # retry chain for quota/rate-limit failures
+/pr-review-config light_tool_policy=none            # tier default when a pass omits tool_policy
 /pr-review-config medium=unset                      # clear a tier (back to pi default)
-/pr-review-config tools=read,bash,grep,find,ls      # tools granted to each subagent
+/pr-review-config heavy_fallbacks=unset             # clear a fallback chain
+/pr-review-config light_tool_policy=unset           # restore legacy configured-tool behavior
+/pr-review-config tools=read,bash,grep,find,ls      # allowlist used by configured policy
 ```
 
 Running `/pr-review-config` with no arguments in the TUI opens an interactive settings menu that mirrors pi's `/settings` and the NERVous `/nervous:config`:
 
-- One row per tier (`light` / `medium` / `heavy` model) plus a `subagent tools` row.
-- Press Enter on a tier to pick a model from a searchable list (or `(unset — pi default)`); Enter/Space on `subagent tools` cycles presets.
+- One primary-model, fallback-model, and tool-policy row per tier (`light` / `medium` / `heavy`) plus a configured-tool allowlist row.
+- Press Enter on a primary or fallback row to pick a model from a searchable list (or unset it); Enter/Space cycles tool policies and allowlist presets. The menu sets one fallback model at a time; use the `key=value` form for longer fallback chains.
 - Selections apply and persist **immediately**; Esc closes the menu.
 - Type to search, and tab-completion is available for the `key=value` form.
 
@@ -91,15 +95,27 @@ Example `pr-review.json`:
     "medium": "<balanced-model-spec>",
     "heavy": "<strong-model-spec:high>"
   },
+  "fallbacks": {
+    "light": ["<backup-fast-model>"],
+    "medium": ["<backup-balanced-model>"],
+    "heavy": ["<backup-strong-model:high>", "<balanced-model-spec>"]
+  },
+  "toolPolicies": {
+    "light": "none",
+    "medium": "configured",
+    "heavy": "configured"
+  },
   "tools": ["read", "bash", "grep", "find", "ls"]
 }
 ```
 
-Each tier runs in an **isolated `pi` subprocess** on its configured model. The `review_subagents` batch tool runs independent passes concurrently (default `max_parallel: 4`, capped at 6) and returns ordered per-pass results; the older single-pass `review_subagent` tool remains available as a compatibility fallback. If a tier is unset, that subagent falls back to the nearest configured tier, then to your pi default model.
+Each tier runs in an **isolated `pi` subprocess** on its configured model. The `review_subagents` batch tool runs independent passes concurrently (default `max_parallel: 4`, capped at 6) and returns ordered per-pass results; the older single-pass `review_subagent` tool remains available as a compatibility fallback. If a tier model fails with a retryable quota/rate-limit/capacity error, the subprocess retries that tier's configured `fallbacks` in order. Non-quota failures do not blindly cycle through fallbacks. If a tier is unset, that subagent falls back to the nearest configured tier, then to your pi default model.
+
+Tool policy is additive and backward compatible: `none` emits Pi's explicit `--no-tools`; `configured` uses the existing `tools` allowlist. A tool call's optional `tool_policy` overrides `toolPolicies[tier]`, which in turn falls back to legacy `configured` behavior. The shipped `/pr-review` prompt explicitly uses `none` only for overview because its complete evidence is supplied in context. Conventions/maintainability and both heavy specialist passes use `configured` repository-context tools so they can inspect surrounding files when needed. Fallback model attempts keep the original pass policy.
 
-### 2. The orchestrator / fallback model
+### 2. The orchestrator / inline-fallback model
 
-The orchestrator (which fetches the PR, merges findings, and emits the JSON) and the inline-fallback path both run on your pi session model:
+The orchestrator (which fetches the PR, merges findings, and emits the JSON) and the inline fallback path both run on your pi session model:
 
 - **Per run:** `pi --model <model-id> "/pr-review 123"`
 - **Persistent default (user):** `~/.pi/agent/settings.json` → `{ "defaultModel": "<model-id>", "defaultThinkingLevel": "high" }`
@@ -174,15 +190,19 @@ Severity tags: `[P0]` blocking/drop-everything · `[P1]` blocking/urgent · `[P2
 pi-pr-review/
 ├─ package.json                      # pi manifest: prompts + extensions
 ├─ prompts/pr-review.md              # the /pr-review orchestrator prompt
+├─ lib/pr-review-policy.ts           # pure tool-policy resolution/argv helpers
 ├─ extensions/pr-review-subagent.ts  # review_subagents/review_subagent tools + /pr-review-config command
-└─ extensions/review-table.ts        # renders the final JSON as a table (TUI only)
+├─ extensions/review-table.ts        # renders the final JSON as a table (TUI only)
+└─ tests/pr-review-policy.test.ts     # focused policy compatibility tests
 ```
 
-## Security & cost notes
+## Speed, security & cost notes
 
-- The `review_subagents` batch tool and `review_subagent` fallback spawn isolated `pi` subprocesses (`--mode json -p --no-session`) on your configured tier models. Subagents are read-only reviewers (`read,bash,grep,find,ls` by default) and never post comments or edit files.
+- The four independent review lenses remain intact. Only overview runs context-only with `--no-tools`; medium and both heavy specialists retain configured tools for surrounding-file validation. All subprocesses use `--no-context-files` because the orchestrator supplies the base review context explicitly, and convention excerpts are sent only to the medium pass instead of every model.
+- Tool results include effective `toolPolicy` and `elapsedMs` telemetry (plus per-attempt timing) so repeated representative runs can be compared at p50/p95 without guessing. Restore tools for a custom pass by sending `tool_policy: "configured"`; callers that omit policy retain legacy behavior unless `toolPolicies` config says otherwise.
+- The `review_subagents` batch tool and `review_subagent` fallback spawn isolated `pi` subprocesses (`--mode json -p --no-session`) on your configured tier models. Reviewer prompts prohibit modifications, but a configured allowlist containing `bash` is not technically read-only; use a narrower allowlist if stronger enforcement is required.
 - Project-local `pr-review.json` is only read when the project is trusted.
-- Tiered review calls multiple models per PR, now concurrently for independent passes. Point `light` at a cheap model for overview/risk scan; reserve `heavy` for the deep passes.
+- Tiered review calls multiple models per PR, concurrently for independent passes. Point `light` at a cheap model for overview/risk scan; reserve `heavy` for deep passes, and configure per-tier `fallbacks` only for acceptable backup models because retries can increase cost.
 
 ## Design notes
 

package/extensions/pr-review-subagent.ts

@@ -4,7 +4,8 @@
  * Adds configurable, tiered review subagents to the /pr-review workflow.
  *
  * - Config surface: `pr-review.json` (user: ~/.pi/agent, project: <repo>/.pi) maps
- *   the labels `light` / `medium` / `heavy` to whatever models you choose.
+ *   the labels `light` / `medium` / `heavy` to whatever models you choose,
+ *   plus optional per-tier fallback chains for quota/capacity failures.
  *   No model names are hardcoded here — you configure them.
  * - Tool: `review_subagent` spawns one isolated `pi` subprocess on the model
  *   bound to the requested tier and returns its review report.
@@ -45,6 +46,13 @@ import {
 	Text,
 } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import {
+	appendToolPolicyArgs,
+	buildReviewBaseArgs,
+	normalizeToolPolicy,
+	resolveToolPolicy,
+	type ToolPolicy,
+} from "../lib/pr-review-policy.ts";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -54,6 +62,8 @@ type Tier = "light" | "medium" | "heavy";
 const TIERS: Tier[] = ["light", "medium", "heavy"];
 
 const UNSET = "(unset — pi default)";
+const INHERIT_TOOL_POLICY = "(inherit — configured tools)";
+const TOOL_POLICIES: ToolPolicy[] = ["configured", "none"];
 const TOOLS_PRESETS = ["read,bash,grep,find,ls", "read,grep,find,ls", "read"];
 const DEFAULT_BATCH_PARALLEL = 4;
 const MAX_BATCH_PARALLEL = 6;
@@ -66,7 +76,11 @@ const TIER_PURPOSE: Record<Tier, string> = {
 interface PrReviewConfig {
 	/** Tier label -> model spec (e.g. "anthropic/model", "openai/model:high"). */
 	tiers: Partial<Record<Tier, string>>;
-	/** Tools granted to each review subagent process. */
+	/** Tier label -> ordered fallback model specs used for quota/capacity failures. */
+	fallbacks: Partial<Record<Tier, string[]>>;
+	/** Optional tier-level policy used when a tool call does not override it. */
+	toolPolicies: Partial<Record<Tier, ToolPolicy>>;
+	/** Tools granted to review subagents whose effective policy is configured. */
 	tools: string[];
 }
 
@@ -91,6 +105,37 @@ function readConfigFile(filePath: string): Partial<PrReviewConfig> {
 	}
 }
 
+function normalizeFallbacks(
+	raw: Partial<Record<Tier, unknown>> | undefined,
+	preserveEmpty = false,
+): Partial<Record<Tier, string[]>> {
+	const out: Partial<Record<Tier, string[]>> = {};
+	if (!raw || typeof raw !== "object") return out;
+	for (const tier of TIERS) {
+		const value = raw[tier];
+		if (value === undefined) continue;
+		const list = Array.isArray(value)
+			? value.map((v) => String(v).trim()).filter(Boolean)
+			: typeof value === "string"
+				? value.split(",").map((v) => v.trim()).filter(Boolean)
+				: [];
+		if (list.length > 0 || preserveEmpty) out[tier] = [...new Set(list)];
+	}
+	return out;
+}
+
+function normalizeToolPolicies(
+	raw: Partial<Record<Tier, unknown>> | undefined,
+): Partial<Record<Tier, ToolPolicy>> {
+	const out: Partial<Record<Tier, ToolPolicy>> = {};
+	if (!raw || typeof raw !== "object") return out;
+	for (const tier of TIERS) {
+		const policy = normalizeToolPolicy(raw[tier]);
+		if (policy) out[tier] = policy;
+	}
+	return out;
+}
+
 /** User config, overlaid by project config when the project is trusted. */
 function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): PrReviewConfig {
 	const user = readConfigFile(userConfigPath());
@@ -102,6 +147,11 @@ function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Pr
 	}
 	return {
 		tiers: { ...(user.tiers ?? {}), ...(project.tiers ?? {}) },
+		fallbacks: { ...normalizeFallbacks(user.fallbacks, true), ...normalizeFallbacks(project.fallbacks, true) },
+		toolPolicies: {
+			...normalizeToolPolicies(user.toolPolicies),
+			...normalizeToolPolicies(project.toolPolicies),
+		},
 		tools: project.tools ?? user.tools ?? DEFAULT_TOOLS,
 	};
 }
@@ -109,7 +159,12 @@ function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Pr
 /** User-level config only (the scope the config command edits), with defaults. */
 function readUserConfig(): PrReviewConfig {
 	const raw = readConfigFile(userConfigPath());
-	return { tiers: { ...(raw.tiers ?? {}) }, tools: raw.tools ?? [...DEFAULT_TOOLS] };
+	return {
+		tiers: { ...(raw.tiers ?? {}) },
+		fallbacks: normalizeFallbacks(raw.fallbacks),
+		toolPolicies: normalizeToolPolicies(raw.toolPolicies),
+		tools: raw.tools ?? [...DEFAULT_TOOLS],
+	};
 }
 
 function writeUserConfig(next: PrReviewConfig): string {
@@ -119,19 +174,50 @@ function writeUserConfig(next: PrReviewConfig): string {
 	return filePath;
 }
 
-/** Resolve the model spec for a tier, falling back to the nearest configured tier. */
-function resolveModelSpec(config: PrReviewConfig, tier: Tier): { spec?: string; usedTier?: Tier } {
-	if (config.tiers[tier]) return { spec: config.tiers[tier], usedTier: tier };
-	// Preference order: search outward from the requested tier.
-	const order: Record<Tier, Tier[]> = {
-		light: ["light", "medium", "heavy"],
-		medium: ["medium", "heavy", "light"],
-		heavy: ["heavy", "medium", "light"],
+interface ModelAttempt {
+	spec?: string;
+	usedTier?: Tier;
+	kind: "primary" | "fallback" | "nearest" | "default";
+	fallbackIndex?: number;
+}
+
+const NEAREST_TIER_ORDER: Record<Tier, Tier[]> = {
+	light: ["light", "medium", "heavy"],
+	medium: ["medium", "heavy", "light"],
+	heavy: ["heavy", "medium", "light"],
+};
+
+/** Resolve the ordered model attempts for a tier, preserving nearest-tier/default behavior when the tier is unset. */
+function resolveModelAttempts(config: PrReviewConfig, tier: Tier): ModelAttempt[] {
+	const attempts: ModelAttempt[] = [];
+	const seen = new Set<string>();
+	const add = (attempt: ModelAttempt) => {
+		const key = attempt.spec ?? "__pi_default__";
+		if (seen.has(key)) return;
+		seen.add(key);
+		attempts.push(attempt);
 	};
-	for (const candidate of order[tier]) {
-		if (config.tiers[candidate]) return { spec: config.tiers[candidate], usedTier: candidate };
+
+	const primary = config.tiers[tier];
+	if (primary) {
+		add({ spec: primary, usedTier: tier, kind: "primary" });
+	} else {
+		let foundNearest = false;
+		for (const candidate of NEAREST_TIER_ORDER[tier]) {
+			const spec = config.tiers[candidate];
+			if (!spec) continue;
+			add({ spec, usedTier: candidate, kind: "nearest" });
+			foundNearest = true;
+			break;
+		}
+		if (!foundNearest) add({ kind: "default" });
 	}
-	return {};
+
+	for (const [index, spec] of (config.fallbacks[tier] ?? []).entries()) {
+		add({ spec, usedTier: tier, kind: "fallback", fallbackIndex: index });
+	}
+
+	return attempts;
 }
 
 // ---------------------------------------------------------------------------
@@ -295,6 +381,20 @@ interface SubagentPassRequest {
 	tier: Tier;
 	objective: string;
 	context?: string;
+	toolPolicy?: ToolPolicy;
+}
+
+interface ModelAttemptReport {
+	kind: ModelAttempt["kind"];
+	spec?: string;
+	usedTier?: Tier;
+	model?: string;
+	exitCode: number;
+	status: "completed" | "failed";
+	retryable: boolean;
+	elapsedMs: number;
+	stopReason?: string;
+	errorMessage?: string;
 }
 
 interface SubagentPassResult {
@@ -309,39 +409,67 @@ interface SubagentPassResult {
 	stderr?: string;
 	stopReason?: string;
 	errorMessage?: string;
+	attempts: ModelAttemptReport[];
+	fallbackUsed: boolean;
+	retryableFailure: boolean;
+	toolPolicy: ToolPolicy;
+	elapsedMs: number;
 }
 
-function noticeForTier(tier: Tier, spec: string | undefined, usedTier: Tier | undefined): string {
-	if (spec) {
-		return usedTier === tier
-			? `tier=${tier} model=${spec}`
-			: `tier=${tier} (not configured; using ${usedTier} model=${spec})`;
+function noticeForAttempt(tier: Tier, attempt: ModelAttempt): string {
+	if (!attempt.spec) {
+		return `tier=${tier} (no tier configured; using pi default model — run /pr-review-config to set tiers)`;
 	}
-	return `tier=${tier} (no tier configured; using pi default model — run /pr-review-config to set tiers)`;
+	if (attempt.kind === "fallback") {
+		return `tier=${tier} fallback #${(attempt.fallbackIndex ?? 0) + 1} model=${attempt.spec}`;
+	}
+	if (attempt.usedTier && attempt.usedTier !== tier) {
+		return `tier=${tier} (not configured; using ${attempt.usedTier} model=${attempt.spec})`;
+	}
+	return `tier=${tier} model=${attempt.spec}`;
+}
+
+function noticeForResult(tier: Tier, attempts: ModelAttemptReport[], finalNotice: string): string {
+	const failedBeforeSuccess = attempts.filter((a) => a.status === "failed").length;
+	if (failedBeforeSuccess > 0 && attempts.some((a) => a.status === "completed")) {
+		return `${finalNotice} (after ${failedBeforeSuccess} retry${failedBeforeSuccess === 1 ? "" : "ies"})`;
+	}
+	return finalNotice;
 }
 
 function buildPassTask(objective: string, context: string | undefined): string {
 	return context ? `Objective: ${objective}\n\n--- PR context / diff ---\n${context}` : `Objective: ${objective}`;
 }
 
-async function runSubagentPass(
+function isRetryableModelFailure(result: RunResult): boolean {
+	if (result.stopReason === "aborted") return false;
+	const haystack = [result.errorMessage, result.stderr, result.text, result.stopReason]
+		.filter(Boolean)
+		.join("\n")
+		.toLowerCase();
+	if (!haystack) return false;
+	return /(?:\b429\b|rate[\s_-]*limit(?:ed)?|too many requests|quota|usage[\s_-]*limit|insufficient[\s_-]*quota|resource[\s_-]*exhausted|out of credits|insufficient credits|credit limit|billing quota|billing hard limit|at capacity|overloaded|temporarily unavailable|model (?:is )?(?:temporarily|currently) unavailable|service unavailable|try again later)/i.test(
+		haystack,
+	);
+}
+
+async function runSubagentAttempt(
 	config: PrReviewConfig,
 	ctx: Pick<ExtensionContext, "cwd">,
 	pass: SubagentPassRequest,
+	attempt: ModelAttempt,
+	toolPolicy: ToolPolicy,
 	signal: AbortSignal | undefined,
 	onText?: (text: string) => void,
-): Promise<SubagentPassResult> {
-	const tier = pass.tier;
-	const { spec, usedTier } = resolveModelSpec(config, tier);
-	const notice = noticeForTier(tier, spec, usedTier);
+): Promise<{ result: RunResult; notice: string; elapsedMs: number }> {
 	let tmp: { dir: string; filePath: string } | undefined;
-
+	const startedAt = Date.now();
 	try {
-		const args = ["--mode", "json", "-p", "--no-session"];
-		if (spec) args.push("--model", spec);
-		if (config.tools.length > 0) args.push("--tools", config.tools.join(","));
+		const args = buildReviewBaseArgs();
+		if (attempt.spec) args.push("--model", attempt.spec);
+		appendToolPolicyArgs(args, toolPolicy, config.tools);
 
-		tmp = await writeTempPrompt(tier, buildSubagentSystemPrompt(tier));
+		tmp = await writeTempPrompt(pass.tier, buildSubagentSystemPrompt(pass.tier));
 		args.push("--append-system-prompt", tmp.filePath);
 		args.push(buildPassTask(pass.objective, pass.context));
 
@@ -349,32 +477,12 @@ async function runSubagentPass(
 		const result = await runReviewSubprocess(invocation.command, invocation.args, ctx.cwd, signal, (text) => {
 			onText?.(text);
 		});
-
-		const failed = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-		return {
-			id: pass.id ?? tier,
-			tier,
-			usedTier,
-			model: result.model ?? spec,
-			exitCode: result.exitCode,
-			status: failed ? "failed" : "completed",
-			notice,
-			text: result.text || (failed ? "" : "NO FINDINGS."),
-			stderr: result.stderr || undefined,
-			stopReason: result.stopReason,
-			errorMessage: result.errorMessage,
-		};
+		return { result, notice: noticeForAttempt(pass.tier, attempt), elapsedMs: Date.now() - startedAt };
 	} catch (e) {
 		return {
-			id: pass.id ?? tier,
-			tier,
-			usedTier,
-			model: spec,
-			exitCode: 1,
-			status: "failed",
-			notice,
-			text: "",
-			errorMessage: errMessage(e),
+			result: { text: "", exitCode: 1, stderr: "", errorMessage: errMessage(e) },
+			notice: noticeForAttempt(pass.tier, attempt),
+			elapsedMs: Date.now() - startedAt,
 		};
 	} finally {
 		if (tmp) {
@@ -387,6 +495,93 @@ async function runSubagentPass(
 	}
 }
 
+async function runSubagentPass(
+	config: PrReviewConfig,
+	ctx: Pick<ExtensionContext, "cwd">,
+	pass: SubagentPassRequest,
+	signal: AbortSignal | undefined,
+	onText?: (text: string) => void,
+): Promise<SubagentPassResult> {
+	const startedAt = Date.now();
+	const tier = pass.tier;
+	const toolPolicy = resolveToolPolicy(pass.toolPolicy, config.toolPolicies[tier]);
+	const attempts = resolveModelAttempts(config, tier);
+	const reports: ModelAttemptReport[] = [];
+	let lastResult: RunResult | undefined;
+	let lastNotice = noticeForAttempt(tier, attempts[0]!);
+
+	for (const attempt of attempts) {
+		const { result, notice, elapsedMs } = await runSubagentAttempt(
+			config,
+			ctx,
+			pass,
+			attempt,
+			toolPolicy,
+			signal,
+			onText,
+		);
+		const failed = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+		const retryable = failed && isRetryableModelFailure(result);
+		lastResult = result;
+		lastNotice = notice;
+		reports.push({
+			kind: attempt.kind,
+			spec: attempt.spec,
+			usedTier: attempt.usedTier,
+			model: result.model ?? attempt.spec,
+			exitCode: result.exitCode,
+			status: failed ? "failed" : "completed",
+			retryable,
+			elapsedMs,
+			stopReason: result.stopReason,
+			errorMessage: result.errorMessage,
+		});
+
+		if (!failed) {
+			return {
+				id: pass.id ?? tier,
+				tier,
+				usedTier: attempt.usedTier,
+				model: result.model ?? attempt.spec,
+				exitCode: result.exitCode,
+				status: "completed",
+				notice: noticeForResult(tier, reports, notice),
+				text: result.text || "NO FINDINGS.",
+				stderr: result.stderr || undefined,
+				stopReason: result.stopReason,
+				errorMessage: result.errorMessage,
+				attempts: reports,
+				fallbackUsed: attempt.kind === "fallback" || reports.length > 1,
+				retryableFailure: false,
+				toolPolicy,
+				elapsedMs: Date.now() - startedAt,
+			};
+		}
+
+		if (!retryable || signal?.aborted) break;
+	}
+
+	const final = lastResult ?? { text: "", exitCode: 1, stderr: "", errorMessage: "No model attempts were available." };
+	return {
+		id: pass.id ?? tier,
+		tier,
+		usedTier: reports.at(-1)?.usedTier,
+		model: reports.at(-1)?.model,
+		exitCode: final.exitCode,
+		status: "failed",
+		notice: noticeForResult(tier, reports, lastNotice),
+		text: final.text || "",
+		stderr: final.stderr || undefined,
+		stopReason: final.stopReason,
+		errorMessage: final.errorMessage,
+		attempts: reports,
+		fallbackUsed: reports.length > 1,
+		retryableFailure: reports.at(-1)?.retryable ?? false,
+		toolPolicy,
+		elapsedMs: Date.now() - startedAt,
+	};
+}
+
 function normalizeMaxParallel(raw: unknown, count: number): number {
 	if (count <= 0) return 0;
 	const requested = typeof raw === "number" && Number.isFinite(raw) ? Math.floor(raw) : DEFAULT_BATCH_PARALLEL;
@@ -410,6 +605,13 @@ async function runWithConcurrency<T, R>(
 	return results;
 }
 
+function formatAttemptSummary(result: SubagentPassResult): string {
+	if (result.attempts.length <= 1) return "";
+	return `attempts: ${result.attempts
+		.map((a) => `${a.status === "completed" ? "✓" : a.retryable ? "↻" : "✗"} ${a.spec ?? "pi default"}`)
+		.join(" → ")}`;
+}
+
 function formatBatchResults(results: SubagentPassResult[], maxParallel: number): string {
 	const failed = results.filter((r) => r.status === "failed");
 	const lines = [
@@ -421,7 +623,16 @@ function formatBatchResults(results: SubagentPassResult[], maxParallel: number):
 		);
 	}
 	for (const result of results) {
-		lines.push("", `## Pass: ${result.id}`, `status: ${result.status}`, result.notice);
+		lines.push(
+			"",
+			`## Pass: ${result.id}`,
+			`status: ${result.status}`,
+			`tool_policy: ${result.toolPolicy}`,
+			`elapsed_ms: ${result.elapsedMs}`,
+			result.notice,
+		);
+		const attemptSummary = formatAttemptSummary(result);
+		if (attemptSummary) lines.push(attemptSummary);
 		if (result.status === "failed") {
 			const detail = result.errorMessage || result.stderr || result.text || "(no output)";
 			lines.push(`error: ${detail}`);
@@ -457,13 +668,19 @@ const ReviewSubagentParams = Type.Object({
 				"Shared context for the subagent, typically the PR title/description plus the unified diff to review.",
 		}),
 	),
+	tool_policy: Type.Optional(
+		StringEnum(["none", "configured"] as const, {
+			description:
+				"Tool access for this pass. none emits --no-tools; configured uses the configured allowlist. Request override wins over tier config; omission preserves configured legacy behavior unless tier policy is set.",
+		}),
+	),
 });
 
 const ReviewSubagentsParams = Type.Object({
 	context: Type.Optional(
 		Type.String({
 			description:
-				"Shared PR context for every pass, typically PR title/body/metadata, in-scope convention-file summaries, and the unified diff.",
+				"Shared PR context for every pass, typically PR title/body/metadata, cross-cutting requirements, and the unified diff. Put specialist-only convention excerpts in the medium pass context.",
 		}),
 	),
 	max_parallel: Type.Optional(
@@ -490,6 +707,12 @@ const ReviewSubagentsParams = Type.Object({
 					description: "Optional pass-specific context appended after the shared context.",
 				}),
 			),
+			tool_policy: Type.Optional(
+				StringEnum(["none", "configured"] as const, {
+					description:
+					"Tool access for this pass. none emits --no-tools; configured uses the configured allowlist. The resolved policy remains fixed across fallback model attempts.",
+				}),
+			),
 		}),
 		{
 			description: "Independent review passes to run concurrently. Results are returned in this same order.",
@@ -520,7 +743,12 @@ export default function (pi: ExtensionAPI) {
 			const result = await runSubagentPass(
 				loadConfig(ctx),
 				ctx,
-				{ tier, objective: params.objective, context: params.context },
+				{
+					tier,
+					objective: params.objective,
+					context: params.context,
+					toolPolicy: normalizeToolPolicy(params.tool_policy),
+				},
 				signal,
 				(text) => onUpdate?.({ content: [{ type: "text", text }] }),
 			);
@@ -535,6 +763,11 @@ export default function (pi: ExtensionAPI) {
 						usedTier: result.usedTier,
 						model: result.model,
 						exitCode: result.exitCode,
+						fallbackUsed: result.fallbackUsed,
+						retryableFailure: result.retryableFailure,
+						toolPolicy: result.toolPolicy,
+						elapsedMs: result.elapsedMs,
+						attempts: result.attempts,
 					},
 				};
 			}
@@ -546,6 +779,10 @@ export default function (pi: ExtensionAPI) {
 					usedTier: result.usedTier,
 					model: result.model,
 					exitCode: result.exitCode,
+					fallbackUsed: result.fallbackUsed,
+					toolPolicy: result.toolPolicy,
+					elapsedMs: result.elapsedMs,
+					attempts: result.attempts,
 				},
 			};
 		},
@@ -587,6 +824,7 @@ export default function (pi: ExtensionAPI) {
 					tier,
 					objective: pass.objective,
 					context: combineContexts(sharedContext, typeof pass.context === "string" ? pass.context : undefined),
+					toolPolicy: normalizeToolPolicy(pass.tool_policy),
 				};
 			});
 			const maxParallel = normalizeMaxParallel(params.max_parallel, passes.length);
@@ -622,6 +860,11 @@ export default function (pi: ExtensionAPI) {
 						status: r.status,
 						stopReason: r.stopReason,
 						errorMessage: r.errorMessage,
+						fallbackUsed: r.fallbackUsed,
+						retryableFailure: r.retryableFailure,
+						toolPolicy: r.toolPolicy,
+						elapsedMs: r.elapsedMs,
+						attempts: r.attempts,
 						outputChars: r.text.length,
 					})),
 				},
@@ -630,7 +873,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("pr-review-config", {
-		description: "Open the review-tier settings menu, or show/set light/medium/heavy models for /pr-review",
+		description: "Open the review-tier settings menu, or show/set light/medium/heavy models and fallbacks for /pr-review",
 		handler: async (args, ctx) => {
 			const raw = (args ?? "").trim();
 			const parsed = parseConfigArgs(raw);
@@ -640,7 +883,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			try {
-				// Direct set: `/pr-review-config light=... heavy=...`
+				// Direct set: `/pr-review-config light=... heavy=... heavy_fallbacks=...`
 				if (parsed.hasChanges) {
 					const next = applyConfigPatch(readUserConfig(), parsed.patch);
 					writeUserConfig(next);
@@ -701,7 +944,15 @@ function shouldOpenConfigMenu(args: string, ctx: ExtensionContext): boolean {
 
 const CONFIG_COMPLETIONS: Array<{ value: string; label: string }> = [
 	...TIERS.map((t) => ({ value: `${t}=`, label: `${t}=<model> — ${TIER_PURPOSE[t]}` })),
-	{ value: "tools=", label: "tools=read,bash,grep,find,ls — tools granted to review subagents" },
+	...TIERS.map((t) => ({
+		value: `${t}_fallbacks=`,
+		label: `${t}_fallbacks=<model1,model2> — retry chain for quota/rate-limit failures`,
+	})),
+	...TIERS.map((t) => ({
+		value: `${t}_tool_policy=`,
+		label: `${t}_tool_policy=<none|configured|unset> — default tool access when a pass does not override it`,
+	})),
+	{ value: "tools=", label: "tools=read,bash,grep,find,ls — allowlist used by configured policy" },
 	{ value: "show", label: "show — print the current tier config" },
 ];
 
@@ -734,13 +985,45 @@ function splitConfigArgs(input: string): string[] {
 	return tokens;
 }
 
+function splitCommaList(value: string): string[] {
+	return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function isFallbackKey(key: string): boolean {
+	for (const tier of TIERS) {
+		if (key === `${tier}_fallbacks` || key === `${tier}-fallbacks` || key === `${tier}.fallbacks`) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function isToolPolicyKey(key: string): boolean {
+	for (const tier of TIERS) {
+		if (
+			key === `${tier}_tool_policy` ||
+			key === `${tier}-tool-policy` ||
+			key === `${tier}.toolpolicy`
+		) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function tierFromCompoundKey(key: string): Tier {
+	return key.split(/[_\-.]/)[0] as Tier;
+}
+
 interface ConfigPatch {
 	tiers: Partial<Record<Tier, string | null>>;
+	fallbacks: Partial<Record<Tier, string[] | null>>;
+	toolPolicies: Partial<Record<Tier, ToolPolicy | null>>;
 	tools?: string[];
 }
 
 function parseConfigArgs(args: string): { patch: ConfigPatch; hasChanges: boolean; errors: string[] } {
-	const patch: ConfigPatch = { tiers: {} };
+	const patch: ConfigPatch = { tiers: {}, fallbacks: {}, toolPolicies: {} };
 	const errors: string[] = [];
 	const tokens = splitConfigArgs(args).filter((t) => !["show", "get", "current"].includes(t.toLowerCase()));
 	for (const token of tokens) {
@@ -753,28 +1036,65 @@ function parseConfigArgs(args: string): { patch: ConfigPatch; hasChanges: boolea
 		const value = token.slice(eq + 1);
 		if ((TIERS as string[]).includes(key)) {
 			patch.tiers[key as Tier] = value === "" || value === "unset" ? null : value;
+		} else if (isFallbackKey(key)) {
+			const tier = tierFromCompoundKey(key);
+			patch.fallbacks[tier] = value === "" || value === "unset" || value === "none" ? null : splitCommaList(value);
+		} else if (isToolPolicyKey(key)) {
+			const tier = tierFromCompoundKey(key);
+			if (value === "" || value === "unset" || value === "inherit") patch.toolPolicies[tier] = null;
+			else {
+				const policy = normalizeToolPolicy(value);
+				if (policy) patch.toolPolicies[tier] = policy;
+				else errors.push(`invalid ${key} "${value}" (expected none|configured|unset)`);
+			}
 		} else if (key === "tools") {
-			patch.tools = value.split(",").map((s) => s.trim()).filter(Boolean);
+			patch.tools = splitCommaList(value);
 		} else {
-			errors.push(`unknown key "${key}" (expected light|medium|heavy|tools)`);
+			errors.push(
+				`unknown key "${key}" (expected light|medium|heavy|<tier>_fallbacks|<tier>_tool_policy|tools)`,
+			);
 		}
 	}
-	const hasChanges = Object.keys(patch.tiers).length > 0 || patch.tools !== undefined;
+	const hasChanges =
+		Object.keys(patch.tiers).length > 0 ||
+		Object.keys(patch.fallbacks).length > 0 ||
+		Object.keys(patch.toolPolicies).length > 0 ||
+		patch.tools !== undefined;
 	return { patch, hasChanges, errors };
 }
 
 function applyConfigPatch(base: PrReviewConfig, patch: ConfigPatch): PrReviewConfig {
-	const next: PrReviewConfig = { tiers: { ...base.tiers }, tools: [...base.tools] };
+	const next: PrReviewConfig = {
+		tiers: { ...base.tiers },
+		fallbacks: normalizeFallbacks(base.fallbacks),
+		toolPolicies: normalizeToolPolicies(base.toolPolicies),
+		tools: [...base.tools],
+	};
 	for (const tier of TIERS) {
-		if (!(tier in patch.tiers)) continue;
-		const value = patch.tiers[tier];
-		if (value === null || value === undefined) delete next.tiers[tier];
-		else next.tiers[tier] = value;
+		if (tier in patch.tiers) {
+			const value = patch.tiers[tier];
+			if (value === null || value === undefined) delete next.tiers[tier];
+			else next.tiers[tier] = value;
+		}
+		if (tier in patch.fallbacks) {
+			const value = patch.fallbacks[tier];
+			if (value === null || value === undefined || value.length === 0) delete next.fallbacks[tier];
+			else next.fallbacks[tier] = [...new Set(value)];
+		}
+		if (tier in patch.toolPolicies) {
+			const value = patch.toolPolicies[tier];
+			if (value === null || value === undefined) delete next.toolPolicies[tier];
+			else next.toolPolicies[tier] = value;
+		}
 	}
 	if (patch.tools) next.tools = patch.tools;
 	return next;
 }
 
+function formatModelList(models: string[] | undefined): string {
+	return models && models.length > 0 ? `\`${models.join(",")}\`` : "_none_";
+}
+
 function summarizeConfig(
 	user: PrReviewConfig,
 	effective: PrReviewConfig,
@@ -799,7 +1119,14 @@ function summarizeConfig(
 			(t) =>
 				`| \`${t}\` | ${user.tiers[t] ? `\`${user.tiers[t]}\`` : "_unset_"} | ${effective.tiers[t] ? `\`${effective.tiers[t]}\`` : "_pi default_"} | ${TIER_PURPOSE[t]} |`,
 		),
-		`| \`tools\` | \`${user.tools.join(",")}\` | \`${effective.tools.join(",")}\` | tools granted to each review subagent |`,
+		`| \`tools\` | \`${user.tools.join(",")}\` | \`${effective.tools.join(",")}\` | allowlist used when policy is \`configured\` |`,
+		"",
+		"| Tier | Your fallbacks | Effective fallbacks | Tool policy |",
+		"|---|---|---|---|",
+		...TIERS.map(
+			(t) =>
+				`| \`${t}\` | ${formatModelList(user.fallbacks[t])} | ${formatModelList(effective.fallbacks[t])} | ${user.toolPolicies[t] ? `\`${user.toolPolicies[t]}\`` : "_inherit configured_"} → \`${effective.toolPolicies[t] ?? "configured"}\` |`,
+		),
 		"",
 		`User config: \`${userConfigPath()}\``,
 	];
@@ -810,7 +1137,11 @@ function summarizeConfig(
 		"- Open the settings menu: `/pr-review-config`",
 		"- Print this summary: `/pr-review-config show`",
 		"- Set directly: `/pr-review-config light=provider/model heavy=provider/model:high`",
+		"- Set fallback chain: `/pr-review-config heavy_fallbacks=provider/backup:high,provider/backup2`",
+		"- Set tier tool policy: `/pr-review-config light_tool_policy=none`",
 		"- Clear a tier: `/pr-review-config medium=unset`",
+		"- Clear fallback chain: `/pr-review-config heavy_fallbacks=unset`",
+		"- Restore legacy tier tool behavior: `/pr-review-config light_tool_policy=unset`",
 		"- A `<model>` is any pi model pattern (`provider/model` or `provider/model:thinking`).",
 	);
 	return lines.join("\n");
@@ -828,10 +1159,14 @@ const MODEL_LIST_ROWS = 10;
  * search UX and fuzzyFilter's slash-token matching, so typing a model name substring
  * finds `provider/model`). The SelectList is rebuilt as the query changes.
  */
-function buildModelSubmenu(available: string[], currentSpec: string | undefined) {
+function buildModelSubmenu(
+	available: string[],
+	currentSpec: string | undefined,
+	unsetDescription = "Fall back to the nearest configured tier, then the pi default.",
+) {
 	return (_currentValue: string, done: (selectedValue?: string) => void) => {
 		const allItems: SelectItem[] = [
-			{ value: "__unset__", label: UNSET, description: "Fall back to the nearest configured tier, then the pi default." },
+			{ value: "__unset__", label: UNSET, description: unsetDescription },
 			...available.map((spec) => ({ value: spec, label: spec })),
 		];
 		const theme = getSelectListTheme();
@@ -890,14 +1225,35 @@ function configMenuItems(cfg: PrReviewConfig, available: string[]): SettingItem[
 		currentValue: cfg.tiers[tier] ?? UNSET,
 		submenu: buildModelSubmenu(available, cfg.tiers[tier]),
 	}));
+	const fallbackItems: SettingItem[] = TIERS.map((tier) => ({
+		id: `${tier}_fallbacks`,
+		label: `${tier} fallback model`,
+		description:
+			"Retry model for quota/rate-limit/capacity failures. Press Enter to set one fallback; use key=value for chains.",
+		currentValue: cfg.fallbacks[tier]?.join(",") || "(none)",
+		submenu: buildModelSubmenu(
+			available,
+			cfg.fallbacks[tier]?.[0],
+			"Clear this tier's fallback chain. Use key=value form to set multiple fallbacks.",
+		),
+	}));
+	const policyItems: SettingItem[] = TIERS.map((tier) => ({
+		id: `${tier}_tool_policy`,
+		label: `${tier} tool policy`,
+		description: "Default when a pass does not explicitly set tool_policy. Enter/Space cycles values.",
+		currentValue: cfg.toolPolicies[tier] ?? INHERIT_TOOL_POLICY,
+		values: [INHERIT_TOOL_POLICY, ...TOOL_POLICIES],
+	}));
 	const current = cfg.tools.join(",");
 	const toolValues = [current, ...TOOLS_PRESETS.filter((p) => p !== current)];
 	return [
 		...tierItems,
+		...fallbackItems,
+		...policyItems,
 		{
 			id: "tools",
-			label: "subagent tools",
-			description: "Tools granted to each review subagent. Enter/Space cycles presets.",
+			label: "configured tool allowlist",
+			description: "Tools available when effective policy is configured. Enter/Space cycles presets.",
 			currentValue: current,
 			values: toolValues,
 		},
@@ -920,7 +1276,11 @@ async function showConfigMenu(
 
 			let settingsList: SettingsList;
 			const refresh = () => {
-				for (const tier of TIERS) settingsList.updateValue(tier, draft.tiers[tier] ?? UNSET);
+				for (const tier of TIERS) {
+					settingsList.updateValue(tier, draft.tiers[tier] ?? UNSET);
+					settingsList.updateValue(`${tier}_fallbacks`, draft.fallbacks[tier]?.join(",") || "(none)");
+					settingsList.updateValue(`${tier}_tool_policy`, draft.toolPolicies[tier] ?? INHERIT_TOOL_POLICY);
+				}
 				settingsList.updateValue("tools", draft.tools.join(","));
 			};
 
@@ -928,15 +1288,32 @@ async function showConfigMenu(
 				if ((TIERS as string[]).includes(id)) {
 					if (newValue === "__unset__") delete draft.tiers[id as Tier];
 					else draft.tiers[id as Tier] = newValue;
+				} else if (isFallbackKey(id)) {
+					const tier = tierFromCompoundKey(id);
+					if (newValue === "__unset__") delete draft.fallbacks[tier];
+					else draft.fallbacks[tier] = [newValue];
+				} else if (isToolPolicyKey(id)) {
+					const tier = tierFromCompoundKey(id);
+					if (newValue === INHERIT_TOOL_POLICY) delete draft.toolPolicies[tier];
+					else {
+						const policy = normalizeToolPolicy(newValue);
+						if (policy) draft.toolPolicies[tier] = policy;
+					}
 				} else if (id === "tools") {
-					draft.tools = newValue.split(",").map((s) => s.trim()).filter(Boolean);
+					draft.tools = splitCommaList(newValue);
 				} else {
 					return;
 				}
 				try {
 					writeUserConfig(draft);
 					refresh();
-					const shown = id === "tools" ? draft.tools.join(",") : (draft.tiers[id as Tier] ?? UNSET);
+					const shown = id === "tools"
+						? draft.tools.join(",")
+						: isFallbackKey(id)
+							? (draft.fallbacks[tierFromCompoundKey(id)]?.join(",") ?? "(none)")
+							: isToolPolicyKey(id)
+								? (draft.toolPolicies[tierFromCompoundKey(id)] ?? INHERIT_TOOL_POLICY)
+								: (draft.tiers[id as Tier] ?? UNSET);
 					ctx.ui.notify(`PR review config: ${id} = ${shown}`, "info");
 				} catch (e) {
 					ctx.ui.notify(`pr-review-config failed: ${errMessage(e)}`, "error");
@@ -946,7 +1323,7 @@ async function showConfigMenu(
 
 			settingsList = new SettingsList(
 				configMenuItems(draft, available),
-				6,
+				12,
 				getSettingsListTheme(),
 				(id, newValue) => persist(id, newValue),
 				() => done(undefined),

package/lib/pr-review-policy.ts

@@ -0,0 +1,32 @@
+export type ToolPolicy = "none" | "configured";
+
+/** Isolated review subprocesses receive all review context explicitly. */
+export function buildReviewBaseArgs(): string[] {
+	return ["--mode", "json", "-p", "--no-session", "--no-context-files"];
+}
+
+export function normalizeToolPolicy(value: unknown): ToolPolicy | undefined {
+	return value === "none" || value === "configured" ? value : undefined;
+}
+
+/** Request override wins, then explicit tier config, then legacy configured behavior. */
+export function resolveToolPolicy(
+	requested: ToolPolicy | undefined,
+	configured: ToolPolicy | undefined,
+): ToolPolicy {
+	return requested ?? configured ?? "configured";
+}
+
+/** Preserve legacy configured behavior; only `none` explicitly disables every tool. */
+export function appendToolPolicyArgs(
+	args: string[],
+	policy: ToolPolicy,
+	configuredTools: string[],
+): string[] {
+	if (policy === "none") {
+		args.push("--no-tools");
+	} else if (configuredTools.length > 0) {
+		args.push("--tools", configuredTools.join(","));
+	}
+	return args;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pr-review",
-  "version": "1.1.2",
+  "version": "1.3.1",
   "description": "Model-agnostic GitHub PR code review prompt for pi. Pass a PR number; it derives the base and head branches from the PR in the current repo, reviews the diff, and returns structured JSON findings.",
   "keywords": [
     "pi-package",
@@ -14,6 +14,9 @@
     "type": "git",
     "url": "git+https://github.com/10ego/pi-pr-review.git"
   },
+  "scripts": {
+    "test": "bun test"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
@@ -21,11 +24,11 @@
     "typebox": "*"
   },
   "pi": {
-    "prompts": [
-      "./prompts"
-    ],
     "extensions": [
       "./extensions"
+    ],
+    "prompts": [
+      "./prompts"
     ]
   }
 }

package/prompts/pr-review.md

@@ -20,14 +20,16 @@ You are the **orchestrator**. You own all GitHub access, skip decisions, convent
 
 If the `review_subagents` batch tool is available, prefer it over multiple single-pass calls. Fetch PR metadata and the unified diff once, gather any relevant convention-file excerpts, then call `review_subagents` with shared `context`, `max_parallel`, and ordered `passes`. This guarantees bounded parallel fan-out instead of depending on whether the tool interface runs separate calls concurrently. Use these pass assignments:
 
-| Pass id | Tier label | Scope |
-|---------|------------|-------|
-| `overview` | `light` | Step 3 overview, strengths, and high-level risk areas |
-| `conventions-maintainability` | `medium` | Step 5 convention compliance, readability, maintainability, test gaps, and nits |
-| `correctness` | `heavy` | Step 5 compile/parse, logic, error handling, lifecycle, concurrency, and edge-case defects |
-| `security-performance` | `heavy` | Step 5 security vulnerabilities and performance regressions |
+| Pass id | Tier label | Tool policy | Scope |
+|---------|------------|-------------|-------|
+| `overview` | `light` | `none` | Step 3 overview, strengths, and high-level risk areas |
+| `conventions-maintainability` | `medium` | `configured` | Step 5 convention compliance, readability, maintainability, test gaps, and nits |
+| `correctness` | `heavy` | `configured` | Step 5 compile/parse, logic, error handling, lifecycle, concurrency, and edge-case defects |
+| `security-performance` | `heavy` | `configured` | Step 5 security vulnerabilities and performance regressions |
 
-Call `review_subagents` with `{ context, max_parallel: 4, passes: [...] }`. If any pass returns `status: failed`, treat the review evidence as incomplete: rerun the failed pass with `review_subagent` or perform that pass inline before finalizing. Always put the PR title/description, relevant metadata, convention-file excerpts, and unified diff in shared `context` so subagents do not refetch anything.
+Call `review_subagents` with `{ context, max_parallel: 4, passes: [...] }`, setting each pass's `tool_policy` exactly as shown. Shared `context` contains the PR title/description, relevant metadata, complete unified diff, and strictly cross-cutting review requirements. Put convention-file paths and excerpts only in the `conventions-maintainability` pass's own `context`; they are appended to shared context by the tool. This avoids sending specialist-only material to every model while still allowing the medium reviewer to inspect surrounding files when maintainability or test-gap analysis requires it.
+
+If deterministic context assembly reports that required input is missing or truncated before dispatch (for example, an incomplete diff or unreadable applicable convention file), set `tool_policy: configured` for that affected pass instead of `none`. Do not ask the model to self-diagnose and rerun. If any pass returns `status: failed`, treat the review evidence as incomplete: rerun the failed pass with `review_subagent` using the same tool policy, or perform that pass inline before finalizing.
 
 If `review_subagents` is unavailable but `review_subagent` is available, run the same pass assignments as individual `review_subagent` calls; emit independent calls in the same turn when the interface supports parallel tool calls. If neither subagent tool is available, perform every pass yourself inline on the current session model.
 
@@ -78,25 +80,25 @@ List (do not dump contents yet) the repository convention files that could gover
 - The root convention file (`CLAUDE.md`, and/or `AGENTS.md` if present).
 - Any convention file living in a directory that contains a file modified by this PR.
 
-When you evaluate compliance for a given changed file, only apply convention files that share that file's path or a parent path. Read a convention file's contents when a changed file falls under its scope, and include the relevant rule excerpts (with file paths) in the shared context for the medium pass.
+When you evaluate compliance for a given changed file, only apply convention files that share that file's path or a parent path. Read a convention file's contents when a changed file falls under its scope, and include the relevant rule excerpts (with file paths) only in the `conventions-maintainability` pass-specific `context`, not the batch's shared context.
 
 ## Step 3 — Overview & strengths (`light` reviewer)
 
 Write a short **overview** (1–3 short paragraphs) of what the PR does and how, grounded in the diff and PR title/description — enough to understand author intent. Also collect a list of genuine **strengths** (good tests, nice consolidation, correct reuse of helpers, etc.) and any high-level risk areas for the specialist passes. Strengths are part of the output, and understanding intent is what lets you tell an intentional change from a bug.
 
-When `review_subagents` is available, include this as the `overview` pass in the same batch as the Step 5 review passes instead of waiting for a separate sequential call.
+When `review_subagents` is available, include this as the `overview` pass in the same batch as the Step 5 review passes instead of waiting for a separate sequential call. Set `tool_policy: none`; the complete PR metadata and diff are already supplied.
 
 ## Step 4 — (reserved)
 
 ## Step 5 — Review passes (dispatch by tier, then merge results)
 
-Run these independent passes over the diff, each on its tier reviewer (or inline if subagent tools are unavailable). Give every pass the shared PR context from Step 1 plus the relevant convention-file excerpts from Step 2, and instruct each pass to report issues **at every severity, including nits**, within its own scope. Do **not** ask every pass to audit everything; the objective boundaries below reduce duplicate work while preserving coverage.
+Run these independent passes over the diff, each on its tier reviewer (or inline if subagent tools are unavailable). Give every pass the shared PR metadata and complete diff from Step 1; give only the medium pass the relevant convention-file excerpts from Step 2. Instruct each pass to report issues **at every severity, including nits**, within its own scope. Do **not** ask every pass to audit everything; the objective and tool-policy boundaries below reduce duplicate work while preserving coverage.
 
 When `review_subagents` is available, dispatch the Step 3 `overview` pass and these Step 5 passes in one batch with `max_parallel: 4`, then combine the ordered outputs:
 
-1. **Convention, readability & maintainability pass — `medium` reviewer.** Audit changed lines against the in-scope convention files from Step 2. Flag violations (quote the rule), softer deviations from documented style as nits, naming/dead-code/comment/typo issues, minor duplication, test gaps, and "worth confirming" observations (e.g. "no current callers — confirm intended", "confirm this generated file came from codegen not a hand-edit"). Do not duplicate deep correctness or security analysis unless needed to explain a convention/maintainability issue.
-2. **Bug & correctness pass — `heavy` reviewer.** Hunt for defects in the introduced code: compile/parse failures, logic errors, wrong results, off-by-one, error handling, resource/lifecycle, concurrency, and edge cases. Include lower-severity correctness smells and missing edge cases as P2/P3. Do not duplicate pure style nits covered by the medium pass.
-3. **Security & performance pass — `heavy` reviewer.** Look for security issues (injection, authz, secrets, unsafe deserialization) and performance regressions in the changed code. Note minor ones too. Do not duplicate ordinary correctness/readability findings unless they are security/performance relevant.
+1. **Convention, readability & maintainability pass — `medium` reviewer, `tool_policy: configured`.** Audit changed lines against the in-scope convention excerpts supplied in this pass's context. Flag violations (quote the rule), softer deviations from documented style as nits, naming/dead-code/comment/typo issues, minor duplication, test gaps, and "worth confirming" observations (e.g. "no current callers — confirm intended", "confirm this generated file came from codegen not a hand-edit"). Use configured tools to inspect surrounding files, tests, callers, or generated-file context when needed; do not modify files or duplicate deep correctness/security analysis unless needed to explain a convention/maintainability issue.
+2. **Bug & correctness pass — `heavy` reviewer, `tool_policy: configured`.** Hunt for defects in the introduced code: compile/parse failures, logic errors, wrong results, off-by-one, error handling, resource/lifecycle, concurrency, and edge cases. Include lower-severity correctness smells and missing edge cases as P2/P3. Do not duplicate pure style nits covered by the medium pass. Use configured repository-context tools when surrounding files or callers are needed to confirm impact; reviewing remains non-modifying even if the allowlist includes `bash`.
+3. **Security & performance pass — `heavy` reviewer, `tool_policy: configured`.** Look for security issues (injection, authz, secrets, unsafe deserialization) and performance regressions in the changed code. Note minor ones too. Do not duplicate ordinary correctness/readability findings unless they are security/performance relevant. Use configured tools when repository context is needed to validate a candidate; do not modify files.
 
 ## Step 6 — Verification (best-effort, orchestrator-owned, non-destructive)
 

package/tests/pr-review-policy.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import {
+	appendToolPolicyArgs,
+	buildReviewBaseArgs,
+	normalizeToolPolicy,
+	resolveToolPolicy,
+} from "../lib/pr-review-policy.ts";
+
+describe("tool policy resolution", () => {
+	test("request override wins over tier config", () => {
+		expect(resolveToolPolicy("none", "configured")).toBe("none");
+		expect(resolveToolPolicy("configured", "none")).toBe("configured");
+	});
+
+	test("tier config applies when request omits policy", () => {
+		expect(resolveToolPolicy(undefined, "none")).toBe("none");
+	});
+
+	test("omission preserves legacy configured behavior", () => {
+		expect(resolveToolPolicy(undefined, undefined)).toBe("configured");
+	});
+
+	test("normalization rejects unknown values", () => {
+		expect(normalizeToolPolicy("none")).toBe("none");
+		expect(normalizeToolPolicy("configured")).toBe("configured");
+		expect(normalizeToolPolicy("auto")).toBeUndefined();
+	});
+});
+
+describe("tool policy argv", () => {
+	test("base args isolate explicit review context", () => {
+		expect(buildReviewBaseArgs()).toEqual([
+			"--mode",
+			"json",
+			"-p",
+			"--no-session",
+			"--no-context-files",
+		]);
+	});
+
+	test("none emits explicit --no-tools", () => {
+		const args = ["--mode", "json"];
+		expect(appendToolPolicyArgs(args, "none", ["read", "bash"])).toEqual([
+			"--mode",
+			"json",
+			"--no-tools",
+		]);
+	});
+
+	test("configured emits the configured allowlist", () => {
+		const args = ["--mode", "json"];
+		expect(appendToolPolicyArgs(args, "configured", ["read", "grep"])).toEqual([
+			"--mode",
+			"json",
+			"--tools",
+			"read,grep",
+		]);
+	});
+
+	test("configured with an empty list preserves legacy omitted-flag behavior", () => {
+		const args = ["--mode", "json"];
+		expect(appendToolPolicyArgs(args, "configured", [])).toEqual(["--mode", "json"]);
+	});
+
+	test("one resolved policy can be reused across fallback attempts", () => {
+		const policy = resolveToolPolicy("none", "configured");
+		const first = appendToolPolicyArgs([], policy, ["read"]);
+		const fallback = appendToolPolicyArgs([], policy, ["read"]);
+		expect(first).toEqual(["--no-tools"]);
+		expect(fallback).toEqual(["--no-tools"]);
+	});
+});