ultimate-pi 0.7.0 → 0.9.0

package/.pi/extensions/policy-gate.ts

@@ -8,17 +8,24 @@
  * - command surface via pi.registerCommand()
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
+	extractWritePathFromToolInput,
 	getLatestRunContext,
 	getPolicyTransitionBlock,
 	hasApprovedPlanSignalFromUserPrompt,
 	hasHarnessAbortSignal,
-	inferHarnessPhaseFromPrompt,
+	inferHarnessPhase,
+	isHarnessAutoSession,
 	isHarnessBootstrapPrompt,
+	isPlanPhaseAllowedMutation,
+	isPlanPhaseScopedWrite,
+	normalizeHarnessPath,
+	readPlanPacketFromPath,
 	saveProjectActiveRun,
 	saveRunContextToDisk,
 	userVisiblePromptSlice,
+	validatePlanPacket,
 } from "../lib/harness-run-context.js";
 
 type HarnessPhase = "plan" | "execute" | "evaluate" | "adversary" | "merge";
@@ -70,8 +77,8 @@ function nowIso(): string {
 
 function defaultState(): PolicyState {
 	return {
-		phase: "execute",
-		approvedPlan: true,
+		phase: "plan",
+		approvedPlan: false,
 		planId: null,
 		budgetBypass: false,
 		aborted: false,
@@ -134,6 +141,11 @@ function getLatestPolicyStateFull(ctx: {
 export default function policyGate(pi: ExtensionAPI) {
 	let state = defaultState();
 
+	const appendPolicyState = (next: PolicyState): void => {
+		state = next;
+		pi.appendEntry("harness-policy-state", state);
+	};
+
 	pi.on("session_start", async (_event, ctx) => {
 		state = getLatestPolicyStateFull(ctx);
 	});
@@ -141,6 +153,7 @@ export default function policyGate(pi: ExtensionAPI) {
 	pi.on("before_agent_start", async (event, ctx) => {
 		const userPrompt = userVisiblePromptSlice(event.prompt);
 		const entries = ctx.sessionManager.getEntries();
+		state = getLatestPolicyStateFull(ctx);
 		const bootstrapPrompt = isHarnessBootstrapPrompt(userPrompt);
 		const abortSignal = hasHarnessAbortSignal(userPrompt);
 
@@ -185,7 +198,7 @@ export default function policyGate(pi: ExtensionAPI) {
 			};
 		}
 
-		const nextPhase = inferHarnessPhaseFromPrompt(userPrompt);
+		const nextPhase = inferHarnessPhase(entries, userPrompt);
 		const planSignal = hasApprovedPlanSignal(userPrompt, entries);
 
 		const transitionBlock = getPolicyTransitionBlock(userPrompt, entries);
@@ -228,26 +241,41 @@ export default function policyGate(pi: ExtensionAPI) {
 		state.updatedAt = nowIso();
 		pi.appendEntry("harness-policy-state", state);
 
+		const planPhaseHint =
+			state.phase === "plan"
+				? "\nPlan phase: present the full PlanPacket in chat, call ask_user (Approve / Request changes / Cancel), then write only the canonical plan-packet.json after Approve."
+				: "";
+
 		return {
-			systemPrompt: `${event.systemPrompt}\n\n[PolicyGate]\nPhase=${state.phase}; ApprovedPlan=${state.approvedPlan}; PlanId=${state.planId ?? "none"}; Aborted=${state.aborted}.`,
+			systemPrompt: `${event.systemPrompt}\n\n[PolicyGate]\nPhase=${state.phase}; ApprovedPlan=${state.approvedPlan}; PlanId=${state.planId ?? "none"}; Aborted=${state.aborted}.${planPhaseHint}`,
 		};
 	});
 
-	pi.on("tool_call", async (event) => {
-		if (state.aborted && MUTATING_TOOLS.has(event.toolName)) {
-			return {
-				block: true,
-				reason:
-					"policy-gate: mutating tool blocked because harness-abort lock is active. Attach a new approved plan first.",
-			};
-		}
+	pi.on("tool_call", async (event, ctx) => {
+		state = getLatestPolicyStateFull(ctx);
+		const entries = ctx.sessionManager.getEntries();
+		const projectRoot = process.cwd();
+		const sessionId = ctx.sessionManager.getSessionId();
+		const runCtx = getLatestRunContext(entries);
+
 		if (MUTATING_TOOLS.has(event.toolName)) {
-			if (state.phase !== "execute") {
-				return {
-					block: true,
-					reason: `policy-gate: ${event.toolName} blocked in phase '${state.phase}'. Allowed only in execute phase.`,
-				};
+			const decision = await isPlanPhaseAllowedMutation(
+				event.toolName,
+				event.input as Record<string, unknown>,
+				state.phase,
+				runCtx,
+				projectRoot,
+				{
+					aborted: state.aborted,
+					entries,
+					ownerSessionId: runCtx?.owner_pi_session_id,
+					currentSessionId: sessionId,
+				},
+			);
+			if (!decision.allowed) {
+				return { block: true, reason: decision.reason };
 			}
+			return undefined;
 		}
 
 		if (event.toolName === "bash") {
@@ -260,7 +288,7 @@ export default function policyGate(pi: ExtensionAPI) {
 						"policy-gate: mutating bash command blocked because harness-abort lock is active. Attach a new approved plan first.",
 				};
 			}
-			if (state.phase !== "execute") {
+			if (state.phase !== "execute" && state.phase !== "merge") {
 				return {
 					block: true,
 					reason: `policy-gate: mutating bash command blocked in phase '${state.phase}'.`,
@@ -271,6 +299,48 @@ export default function policyGate(pi: ExtensionAPI) {
 		return undefined;
 	});
 
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.isError) return;
+		if (event.toolName !== "write" && event.toolName !== "edit") return;
+
+		const entries = ctx.sessionManager.getEntries();
+		state = getLatestPolicyStateFull(ctx);
+		const projectRoot = process.cwd();
+		const runCtx = getLatestRunContext(entries);
+		if (!runCtx) return;
+
+		const target = extractWritePathFromToolInput(
+			event.input as Record<string, unknown>,
+		);
+		if (!target) return;
+		const scoped = await isPlanPhaseScopedWrite(target, runCtx, projectRoot);
+		if (!scoped) return;
+
+		const planPath = normalizeHarnessPath(target, projectRoot);
+		const packet = await readPlanPacketFromPath(planPath);
+		const validation = validatePlanPacket(packet);
+		if (!validation.valid || !packet?.plan_id) return;
+
+		if (isHarnessAutoSession(entries)) {
+			state.phase = "execute";
+			state.approvedPlan = true;
+			state.planId = packet.plan_id;
+			state.aborted = false;
+			state.abortReason = null;
+			state.abortedAt = null;
+			state.updatedAt = nowIso();
+			appendPolicyState(state);
+
+			runCtx.plan_ready = true;
+			runCtx.plan_id = packet.plan_id;
+			runCtx.phase = "execute";
+			runCtx.updated_at = nowIso();
+			pi.appendEntry("harness-run-context", runCtx);
+			void saveRunContextToDisk(runCtx);
+			void saveProjectActiveRun(runCtx);
+		}
+	});
+
 	pi.registerCommand("harness-abort", {
 		description: "Safely abort current harness run and reset to plan phase",
 		handler: async (args, ctx) => {

package/.pi/extensions/provider-payload-sanitize.ts

@@ -9,7 +9,7 @@
 import type {
 	BeforeProviderRequestEvent,
 	ExtensionAPI,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 
 const CHAT_MESSAGE_EXTRA_KEYS = [
 	"reasoning",

package/.pi/extensions/review-integrity.ts

@@ -1,19 +1,34 @@
 /**
  * review-integrity — enforce evaluator/adversary isolation from executor session.
  *
- * If review phases (`evaluate`/`adversary`) run in the same session as execution,
- * tool calls are blocked until the review is isolated (fork/switch session).
+ * Parent orchestrators spawn review agents in isolated subagent sessions.
+ * Direct review tools in the executor session are blocked; Agent/get_subagent_result
+ * for harness review agents remain allowed.
  */
 
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 type HarnessPhase = "plan" | "execute" | "evaluate" | "adversary" | "merge";
 
 const INCIDENTS_DIR = join(process.cwd(), ".pi", "harness", "incidents");
 const INCIDENT_FILE = join(INCIDENTS_DIR, "review-integrity.jsonl");
 
+const ORCHESTRATION_TOOLS = new Set([
+	"Agent",
+	"get_subagent_result",
+	"steer_subagent",
+]);
+
+const REVIEW_SUBAGENT_TYPES = new Set([
+	"harness/evaluator",
+	"harness/adversary",
+	"harness/tie-breaker",
+]);
+
+const EXECUTOR_SUBAGENT_TYPE = "harness/executor";
+
 interface IsolationState {
 	executorSessionId: string | null;
 	violationActive: boolean;
@@ -89,6 +104,17 @@ function restoreState(ctx: {
 	};
 }
 
+function subagentTypeFromInput(
+	input: Record<string, unknown> | undefined,
+): string {
+	if (!input) return "";
+	const direct = input.subagent_type;
+	if (typeof direct === "string") return direct;
+	const nested = input as { subagentType?: string };
+	if (typeof nested.subagentType === "string") return nested.subagentType;
+	return "";
+}
+
 async function appendIncident(payload: Record<string, unknown>): Promise<void> {
 	await mkdir(INCIDENTS_DIR, { recursive: true });
 	await appendFile(
@@ -105,6 +131,10 @@ export default function reviewIntegrity(pi: ExtensionAPI) {
 		updatedAt: nowIso(),
 	};
 
+	const persist = (): void => {
+		pi.appendEntry("harness-review-integrity", state);
+	};
+
 	pi.on("session_start", async (_event, ctx) => {
 		state = restoreState(ctx);
 	});
@@ -115,7 +145,7 @@ export default function reviewIntegrity(pi: ExtensionAPI) {
 		state.executorSessionId = ctx.sessionManager.getSessionId();
 		state.violationActive = false;
 		state.updatedAt = nowIso();
-		pi.appendEntry("harness-review-integrity", state);
+		persist();
 	});
 
 	pi.on("before_agent_start", async (_event, ctx) => {
@@ -125,7 +155,7 @@ export default function reviewIntegrity(pi: ExtensionAPI) {
 		if (!inReview) {
 			state.violationActive = false;
 			state.updatedAt = nowIso();
-			pi.appendEntry("harness-review-integrity", state);
+			persist();
 			return undefined;
 		}
 
@@ -135,42 +165,66 @@ export default function reviewIntegrity(pi: ExtensionAPI) {
 		) {
 			state.violationActive = false;
 			state.updatedAt = nowIso();
-			pi.appendEntry("harness-review-integrity", state);
+			persist();
 			return undefined;
 		}
 
 		state.violationActive = true;
 		state.updatedAt = nowIso();
-		pi.appendEntry("harness-review-integrity", state);
-
-		await appendIncident({
-			type: "review_integrity_violation",
-			session_id: currentSessionId,
-			phase,
-			reason:
-				"evaluator/adversary session is not isolated from executor session",
-			mitigation:
-				"fork or switch to a clean review session before running review tools",
-		});
+		persist();
 
 		return {
 			message: {
-				customType: "harness-review-integrity-block",
+				customType: "harness-review-integrity-hint",
 				display: true,
 				content: [
-					"Review integrity violation: evaluator/adversary is sharing executor session context.",
-					"Fork/switch session, then rerun review to maintain independent evaluation guarantees.",
+					"Review phase in executor session: spawn harness/evaluator or harness/adversary via Agent (isolated subagent context).",
+					"Do not run review checks directly in this session — use get_subagent_result after spawn.",
 				].join("\n"),
 			},
 		};
 	});
 
-	pi.on("tool_call", async (_event) => {
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName === "Agent") {
+			const subagentType = subagentTypeFromInput(
+				event.input as Record<string, unknown> | undefined,
+			);
+			if (subagentType === EXECUTOR_SUBAGENT_TYPE) {
+				state.executorSessionId = ctx.sessionManager.getSessionId();
+				state.violationActive = false;
+				state.updatedAt = nowIso();
+				persist();
+				return undefined;
+			}
+			if (REVIEW_SUBAGENT_TYPES.has(subagentType)) {
+				state.violationActive = false;
+				state.updatedAt = nowIso();
+				persist();
+				return undefined;
+			}
+		}
+
 		if (!state.violationActive) return undefined;
+
+		if (ORCHESTRATION_TOOLS.has(event.toolName)) {
+			return undefined;
+		}
+
+		await appendIncident({
+			type: "review_integrity_violation",
+			session_id: ctx.sessionManager.getSessionId(),
+			tool: event.toolName,
+			reason:
+				"direct tool use in review phase while sharing executor session context",
+			mitigation:
+				"spawn harness/evaluator or harness/adversary via Agent instead",
+		});
+
 		return {
 			block: true,
 			reason:
-				"review-integrity: tool call blocked because review session is not isolated from executor context.",
+				"review-integrity: tool blocked in review phase — spawn an isolated review subagent via Agent.",
 		};
 	});
 

package/.pi/extensions/sentrux-rules-sync.ts

@@ -3,7 +3,7 @@
  */
 
 import { spawn } from "node:child_process";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolveHarnessScript } from "./lib/harness-paths.js";
 
 function resolveSyncScript(): string {

package/.pi/extensions/soundboard.ts

@@ -31,7 +31,7 @@ import {
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 
 // ── Constants ──────────────────────────────────────────────────────
 

package/.pi/extensions/test-diff-integrity.ts

@@ -12,7 +12,7 @@
 
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const INCIDENTS_DIR = join(process.cwd(), ".pi", "harness", "incidents");
 const INCIDENT_FILE = join(INCIDENTS_DIR, "test-diff-integrity.jsonl");

package/.pi/extensions/trace-recorder.ts

@@ -9,7 +9,7 @@
 
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	getLatestRunContext,
 	getRunIdFromSession,

package/.pi/extensions/ultimate-pi-vcc.ts

@@ -9,7 +9,7 @@
  * - `HARNESS_VCC_DEBUG` — set `true` to write `/tmp/pi-vcc-debug.json` on compaction
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import registerVcc from "../../vendor/pi-vcc/index.js";
 
 export default function ultimatePiVcc(pi: ExtensionAPI): void {

package/.pi/harness/agents.manifest.json

@@ -1,80 +1,84 @@
 {
-	"schema_version": "1.0.0",
-	"package": "ultimate-pi",
-	"package_version": "0.6.1",
-	"generated_at": "2026-05-17T06:10:49.269Z",
-	"agents": {
-		"pi-pi/agent-expert": {
-			"path": ".pi/agents/pi-pi/agent-expert.md",
-			"sha256": "86561eb092b92fa43f221bfc6305de8d5afe10d43c5f577b9bf15a71bda051c6"
-		},
-		"pi-pi/cli-expert": {
-			"path": ".pi/agents/pi-pi/cli-expert.md",
-			"sha256": "6ecdbc37c60f1da7c68d504187454c95197dd19bd7091d97d136c6fb9e866838"
-		},
-		"pi-pi/config-expert": {
-			"path": ".pi/agents/pi-pi/config-expert.md",
-			"sha256": "c23b9b70a4c326cca2d139f18de48f8db2e0e28fa5ceb8205600f25430822a40"
-		},
-		"pi-pi/ext-expert": {
-			"path": ".pi/agents/pi-pi/ext-expert.md",
-			"sha256": "ae71ccf598217c830ac99e3150365a075bde931778d8bc6305d0270ac959a8a9"
-		},
-		"pi-pi/keybinding-expert": {
-			"path": ".pi/agents/pi-pi/keybinding-expert.md",
-			"sha256": "d8c3d645a507b453d9b338f7a5435232a23e4a00cb7981e3b81a4ce2a0df6bba"
-		},
-		"pi-pi/pi-orchestrator": {
-			"path": ".pi/agents/pi-pi/pi-orchestrator.md",
-			"sha256": "1323fc262112030320bdd7d7866fd69e1b861377bb30fd3553a5e3a4398f9090"
-		},
-		"pi-pi/prompt-expert": {
-			"path": ".pi/agents/pi-pi/prompt-expert.md",
-			"sha256": "0d9f5e3e8ab162149cac8f08e159a7b2150a11f53ebe7021e72f8277fa004d0c"
-		},
-		"pi-pi/skill-expert": {
-			"path": ".pi/agents/pi-pi/skill-expert.md",
-			"sha256": "91732a2479097a2645b6af56171d5cdc1ed67a0896ca54bc4badba250341698f"
-		},
-		"pi-pi/theme-expert": {
-			"path": ".pi/agents/pi-pi/theme-expert.md",
-			"sha256": "3d256049203356d87c36eac2232c0ad6261fec8af02eb15d3144b18a400ed64d"
-		},
-		"pi-pi/tui-expert": {
-			"path": ".pi/agents/pi-pi/tui-expert.md",
-			"sha256": "cd6aaf6ca28e6e65a72ef1dc3c96e3315669ec0f859c148f0f15d0ee74a263d7"
-		},
-		"harness/adversary": {
-			"path": ".pi/agents/harness/adversary.md",
-			"sha256": "17c29621d99dd46cf6ea6566845b502c5e825338b61f073a28cb53f297b2f208"
-		},
-		"harness/evaluator": {
-			"path": ".pi/agents/harness/evaluator.md",
-			"sha256": "71cfb070ec3bbec9d764052ba03fee8692f2db385ad19f15c2f3a157422c1c2b"
-		},
-		"harness/executor": {
-			"path": ".pi/agents/harness/executor.md",
-			"sha256": "02cd2f438d97abb9f35ca6cdab51b3733fc6a9076427cf9c2c93fd4593052539"
-		},
-		"harness/meta-optimizer": {
-			"path": ".pi/agents/harness/meta-optimizer.md",
-			"sha256": "faf81af85d273796f059395287058d2f16fe70903c70b8c6ac9b3c5f12fca69c"
-		},
-		"harness/planner": {
-			"path": ".pi/agents/harness/planner.md",
-			"sha256": "58d9c983bddddd37070f33742409f16474bf7c54bdccb8808fca4926f4adfdad"
-		},
-		"harness/sentrux-bootstrap": {
-			"path": ".pi/agents/harness/sentrux-bootstrap.md",
-			"sha256": "3a0b43b94386a7c541b8a806a37524a5e53f1c8049270db7a420680df5799eeb"
-		},
-		"harness/tie-breaker": {
-			"path": ".pi/agents/harness/tie-breaker.md",
-			"sha256": "c8fd02b3423760d9503e20ea27d3a90aa11326fc38c98f1e7253e67676b15e42"
-		},
-		"harness/trace-librarian": {
-			"path": ".pi/agents/harness/trace-librarian.md",
-			"sha256": "f44439758317b5fbae66b760bb6a1b6df19787d344bf7038712368e8fe0594ee"
-		}
-	}
+  "schema_version": "1.0.0",
+  "package": "ultimate-pi",
+  "package_version": "0.8.0",
+  "generated_at": "2026-05-17T09:55:45.240Z",
+  "agents": {
+    "pi-pi/agent-expert": {
+      "path": ".pi/agents/pi-pi/agent-expert.md",
+      "sha256": "86561eb092b92fa43f221bfc6305de8d5afe10d43c5f577b9bf15a71bda051c6"
+    },
+    "pi-pi/cli-expert": {
+      "path": ".pi/agents/pi-pi/cli-expert.md",
+      "sha256": "6ecdbc37c60f1da7c68d504187454c95197dd19bd7091d97d136c6fb9e866838"
+    },
+    "pi-pi/config-expert": {
+      "path": ".pi/agents/pi-pi/config-expert.md",
+      "sha256": "c23b9b70a4c326cca2d139f18de48f8db2e0e28fa5ceb8205600f25430822a40"
+    },
+    "pi-pi/ext-expert": {
+      "path": ".pi/agents/pi-pi/ext-expert.md",
+      "sha256": "47c64a9e2cffe00a50cac5541b0edc89fe8bcbd66ec3bb302eecc10d405a977f"
+    },
+    "pi-pi/keybinding-expert": {
+      "path": ".pi/agents/pi-pi/keybinding-expert.md",
+      "sha256": "bb83f5fd2178075c8374ef28c360339f7de9faeedf811670b43a536c5f65c58e"
+    },
+    "pi-pi/pi-orchestrator": {
+      "path": ".pi/agents/pi-pi/pi-orchestrator.md",
+      "sha256": "1323fc262112030320bdd7d7866fd69e1b861377bb30fd3553a5e3a4398f9090"
+    },
+    "pi-pi/prompt-expert": {
+      "path": ".pi/agents/pi-pi/prompt-expert.md",
+      "sha256": "0d9f5e3e8ab162149cac8f08e159a7b2150a11f53ebe7021e72f8277fa004d0c"
+    },
+    "pi-pi/skill-expert": {
+      "path": ".pi/agents/pi-pi/skill-expert.md",
+      "sha256": "91732a2479097a2645b6af56171d5cdc1ed67a0896ca54bc4badba250341698f"
+    },
+    "pi-pi/theme-expert": {
+      "path": ".pi/agents/pi-pi/theme-expert.md",
+      "sha256": "3d256049203356d87c36eac2232c0ad6261fec8af02eb15d3144b18a400ed64d"
+    },
+    "pi-pi/tui-expert": {
+      "path": ".pi/agents/pi-pi/tui-expert.md",
+      "sha256": "a619b2ee3d3d94fe599abb61db0904f90d30335ec426851c3f1efdf2e5ce5390"
+    },
+    "harness/adversary": {
+      "path": ".pi/agents/harness/adversary.md",
+      "sha256": "b965f90610ca942d08b656f1aee839266d08a92beb174b8761dd5e840694a899"
+    },
+    "harness/evaluator": {
+      "path": ".pi/agents/harness/evaluator.md",
+      "sha256": "6c0de777a10de26dba4a6feb5641495fa5c2d31072a8b0e597a5ecc9921f129f"
+    },
+    "harness/executor": {
+      "path": ".pi/agents/harness/executor.md",
+      "sha256": "5af3ec2be4d64a738834e36d480a36c2bee4359e8cd5a2e1aac49be4cff79589"
+    },
+    "harness/incident-recorder": {
+      "path": ".pi/agents/harness/incident-recorder.md",
+      "sha256": "2de405f77b62dde38f331665bff220a3ef131c3c1cd42eebee364000fc83352b"
+    },
+    "harness/meta-optimizer": {
+      "path": ".pi/agents/harness/meta-optimizer.md",
+      "sha256": "ef2fb950e18e3a6439e91a68f764fc7ec922cd2d6b35de8f656f376854974d04"
+    },
+    "harness/planner": {
+      "path": ".pi/agents/harness/planner.md",
+      "sha256": "eb0459a1fcb018e4ca8d4339141e294828fa7014879d9a64258ae01abc13d3ad"
+    },
+    "harness/sentrux-bootstrap": {
+      "path": ".pi/agents/harness/sentrux-bootstrap.md",
+      "sha256": "3a0b43b94386a7c541b8a806a37524a5e53f1c8049270db7a420680df5799eeb"
+    },
+    "harness/tie-breaker": {
+      "path": ".pi/agents/harness/tie-breaker.md",
+      "sha256": "651f50b9e2c7903c542700e94908b1fcd026ebed12aa1f1d6ec481df3567e34f"
+    },
+    "harness/trace-librarian": {
+      "path": ".pi/agents/harness/trace-librarian.md",
+      "sha256": "d63fe08a2ea0466c0fd89fff4da03ac1d9d3580c306381cee251c89d4e8fdb97"
+    }
+  }
 }

package/.pi/harness/docs/adrs/0031-harness-run-context.md

@@ -9,7 +9,7 @@ Manual harness steps required copying `run_id` and `plan-packet.json` paths betw
 
 ## Decision
 
-1. Add `.pi/lib/harness-run-context.ts` and `harness-run-context.ts` extension as the single source of truth for active runs.
+1. Add `.pi/lib/harness-run-context.ts` and `harness-run-context.ts` extension as the single source of truth for active runs. **Harness command routing:** `pi.on("input")` appends `harness-turn` for raw `/harness-*` (before template expansion); `before_agent_start` bootstraps from that entry, not expanded prompt headers.
 2. Persist mirrors:
    - `.pi/harness/runs/<run_id>/run-context.json`
    - `.pi/harness/active-run.json` (cross-session pointer for forked eval)
@@ -17,8 +17,11 @@ Manual harness steps required copying `run_id` and `plan-packet.json` paths betw
 4. **Hook order:** `harness-run-context` `before_agent_start` allocates/reuses `run_id` before `trace-recorder` `agent_start`. Trace writes phase files `trace-<phase>.json` plus rollup `trace.json`.
 5. PostHog `harness_run_started` at most once per logical `run_id`.
 6. Short commands: `/harness-run`, `/harness-eval`, etc. without args; recovery via `/harness-run-status`, `/harness-use-run`.
-7. Review isolation unchanged: after execute, handoff says **new Pi session → `/harness-eval`**; project `active-run.json` binds forked sessions.
-8. `hasApprovedPlanSignal` uses user-visible prompt only; execute requires `plan_ready` from disk validation.
+7. After execute, handoff recommends **`/harness-eval`** in the same session; review commands spawn isolated subagents (see ADR 0032). `active-run.json` still supports cross-session recovery when Pi was closed mid-run.
+8. `hasApprovedPlanSignal` uses user-visible prompt only; execute requires `plan_ready` from disk validation **and** recorded `ask_user` approval (or `harness-plan-approval` entry).
+9. **Plan-phase writes:** policy-gate allows `write`/`edit` only on canonical `.pi/harness/runs/<run_id>/plan-packet.json` after approval; all other paths stay blocked until execute phase.
+10. **Approval-before-persist:** agents present the full plan, call `ask_user` (Approve / Request changes / Cancel), then write the packet. `--quick` narrows planning only — it does not skip approval.
+11. **`/harness-auto`:** after an approved plan-packet write, policy phase promotes to `execute` in the same agent turn so implementation can proceed without a separate `/harness-run` message.
 
 ## Consequences
 

package/.pi/harness/docs/adrs/0032-harness-command-orchestration.md

@@ -0,0 +1,37 @@
+# ADR 0032: Harness slash commands as agent orchestrators
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+
+## Context
+
+Harness slash prompts duplicated logic already defined in `harness/*` agents. Commands did not invoke the `Agent` tool. Review docs told users to fork a new Pi session even though subagents already provide isolated context.
+
+## Decision
+
+1. **Slash commands** (prompt templates) are orchestrators: spawn `harness/*` agents once, perform policy-gated writes, emit handoff blocks. Command identity is captured on Pi **`input`** as `harness-turn` (raw `/harness-*`), not from expanded prompt markdown.
+2. **Agents** perform multi-turn reads and emit structured JSON drafts. **Planner** runs clarification and plan approval via `ask_user` (parent UI bridge); planner does not write `plan-packet.json`.
+3. **HarnessSpawnContext** is injected in `[HarnessRunContext]`; orchestrator copies it into spawn prompts. Subagents do not receive `[HarnessActivePlan]` injection.
+4. **Review isolation** uses `Agent` spawn with `inherit_context: false`. `review-integrity` allows `Agent` / `get_subagent_result` for evaluator/adversary/tie-breaker.
+5. **Subagent policy** blocks mutating tools for read-only phase agents; `ask_user` allowed for planner/evaluator/adversary/tie-breaker only.
+6. **Parent** does not duplicate planner `ask_user` or re-spawn for clarification. `get_subagent_result` syncs `harness-plan-approval` from subagent sessions.
+
+## Consequences
+
+### Positive
+
+- Single source of truth for phase logic in agent files; prompts stay thin.
+- L4 review isolation without manual session management.
+
+### Negative
+
+- Orchestrator must parse subagent JSON reliably and pass complete spawn context.
+- Scope enforcement remains prompt-driven for executor until optional path allowlist.
+
+## References
+
+- `.pi/prompts/harness-*.md`
+- `.pi/agents/harness/*.md`
+- `.pi/extensions/lib/harness-subagents/harness-subagent-policy.ts`
+- `.pi/extensions/review-integrity.ts`
+- `.pi/lib/harness-agent-output.ts`

package/.pi/harness/docs/adrs/README.md

@@ -17,6 +17,7 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0009](0009-sentrux-rules-lifecycle.md) | Sentrux rules.toml lifecycle | Accepted |
 | [0030](0030-inhouse-vcc-compaction.md) | In-house VCC compaction (vendored pi-vcc) | Accepted |
 | [0031](0031-harness-run-context.md) | Harness active run context | Accepted |
+| [0032](0032-harness-command-orchestration.md) | Harness commands as agent orchestrators | Accepted |
 
 ## Template
 

package/.pi/harness/specs/budget-exhausted-event.schema.json

@@ -54,7 +54,9 @@
 			"enum": [
 				"max_rounds_reached",
 				"round_token_cap_exceeded",
-				"debate_global_cap_exceeded"
+				"debate_global_cap_exceeded",
+				"phase_cap_exceeded",
+				"global_cap_exceeded"
 			]
 		},
 		"caps": {