ultimate-pi 0.7.0 → 0.8.0

package/.pi/extensions/lib/harness-subagents/vendored/ui/agent-widget.ts

@@ -5,7 +5,7 @@
  * Uses the callback form of setWidget for themed rendering.
  */
 
-import { truncateToWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
 import { getConfig } from "../agent-types.js";
 import type { AgentInvocation, SubagentType } from "../types.js";

package/.pi/extensions/lib/harness-subagents/vendored/ui/conversation-viewer.ts

@@ -5,7 +5,7 @@
  * Subscribes to session events for real-time streaming updates.
  */
 
-import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import {
 	type Component,
 	matchesKey,
@@ -13,7 +13,7 @@ import {
 	truncateToWidth,
 	visibleWidth,
 	wrapTextWithAnsi,
-} from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-tui";
 import { extractText } from "../context.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";

package/.pi/extensions/lib/harness-subagents/vendored/ui/schedule-menu.ts

@@ -8,7 +8,7 @@
  * if real demand emerges.
  */
 
-import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { SubagentScheduler } from "../schedule.js";
 import type { ScheduledSubagent } from "../types.js";
 

package/.pi/extensions/observation-bus.ts

@@ -6,7 +6,7 @@
  */
 
 import { randomUUID } from "node:crypto";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getRunIdFromSession } from "../lib/harness-run-context.js";
 
 type HarnessPhase = "plan" | "execute" | "evaluate" | "adversary" | "merge";

package/.pi/extensions/pi-model-router-harness.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import vendorModelRouter from "../../vendor/pi-model-router/extensions/index.js";
 
 function isHarnessRouterReady(cwd: string): boolean {

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,
+	isHarnessAutoSession,
 	isHarnessBootstrapPrompt,
+	isPlanPhaseAllowedMutation,
+	isPlanPhaseScopedWrite,
+	normalizeHarnessPath,
+	readPlanPacketFromPath,
 	saveProjectActiveRun,
 	saveRunContextToDisk,
 	userVisiblePromptSlice,
+	validatePlanPacket,
 } from "../lib/harness-run-context.js";
 
 type HarnessPhase = "plan" | "execute" | "evaluate" | "adversary" | "merge";
@@ -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);
 
@@ -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,8 +1,8 @@
 {
 	"schema_version": "1.0.0",
 	"package": "ultimate-pi",
-	"package_version": "0.6.1",
-	"generated_at": "2026-05-17T06:10:49.269Z",
+	"package_version": "0.7.0",
+	"generated_at": "2026-05-17T08:24:57.263Z",
 	"agents": {
 		"pi-pi/agent-expert": {
 			"path": ".pi/agents/pi-pi/agent-expert.md",
@@ -18,11 +18,11 @@
 		},
 		"pi-pi/ext-expert": {
 			"path": ".pi/agents/pi-pi/ext-expert.md",
-			"sha256": "ae71ccf598217c830ac99e3150365a075bde931778d8bc6305d0270ac959a8a9"
+			"sha256": "47c64a9e2cffe00a50cac5541b0edc89fe8bcbd66ec3bb302eecc10d405a977f"
 		},
 		"pi-pi/keybinding-expert": {
 			"path": ".pi/agents/pi-pi/keybinding-expert.md",
-			"sha256": "d8c3d645a507b453d9b338f7a5435232a23e4a00cb7981e3b81a4ce2a0df6bba"
+			"sha256": "bb83f5fd2178075c8374ef28c360339f7de9faeedf811670b43a536c5f65c58e"
 		},
 		"pi-pi/pi-orchestrator": {
 			"path": ".pi/agents/pi-pi/pi-orchestrator.md",
@@ -42,27 +42,31 @@
 		},
 		"pi-pi/tui-expert": {
 			"path": ".pi/agents/pi-pi/tui-expert.md",
-			"sha256": "cd6aaf6ca28e6e65a72ef1dc3c96e3315669ec0f859c148f0f15d0ee74a263d7"
+			"sha256": "a619b2ee3d3d94fe599abb61db0904f90d30335ec426851c3f1efdf2e5ce5390"
 		},
 		"harness/adversary": {
 			"path": ".pi/agents/harness/adversary.md",
-			"sha256": "17c29621d99dd46cf6ea6566845b502c5e825338b61f073a28cb53f297b2f208"
+			"sha256": "b965f90610ca942d08b656f1aee839266d08a92beb174b8761dd5e840694a899"
 		},
 		"harness/evaluator": {
 			"path": ".pi/agents/harness/evaluator.md",
-			"sha256": "71cfb070ec3bbec9d764052ba03fee8692f2db385ad19f15c2f3a157422c1c2b"
+			"sha256": "6c0de777a10de26dba4a6feb5641495fa5c2d31072a8b0e597a5ecc9921f129f"
 		},
 		"harness/executor": {
 			"path": ".pi/agents/harness/executor.md",
-			"sha256": "02cd2f438d97abb9f35ca6cdab51b3733fc6a9076427cf9c2c93fd4593052539"
+			"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": "faf81af85d273796f059395287058d2f16fe70903c70b8c6ac9b3c5f12fca69c"
+			"sha256": "ef2fb950e18e3a6439e91a68f764fc7ec922cd2d6b35de8f656f376854974d04"
 		},
 		"harness/planner": {
 			"path": ".pi/agents/harness/planner.md",
-			"sha256": "58d9c983bddddd37070f33742409f16474bf7c54bdccb8808fca4926f4adfdad"
+			"sha256": "3052e0b4ca504c7aa025b1926228e34adfe7f1c42d66a24db43fc6a1abb9968d"
 		},
 		"harness/sentrux-bootstrap": {
 			"path": ".pi/agents/harness/sentrux-bootstrap.md",
@@ -70,11 +74,11 @@
 		},
 		"harness/tie-breaker": {
 			"path": ".pi/agents/harness/tie-breaker.md",
-			"sha256": "c8fd02b3423760d9503e20ea27d3a90aa11326fc38c98f1e7253e67676b15e42"
+			"sha256": "651f50b9e2c7903c542700e94908b1fcd026ebed12aa1f1d6ec481df3567e34f"
 		},
 		"harness/trace-librarian": {
 			"path": ".pi/agents/harness/trace-librarian.md",
-			"sha256": "f44439758317b5fbae66b760bb6a1b6df19787d344bf7038712368e8fe0594ee"
+			"sha256": "d63fe08a2ea0466c0fd89fff4da03ac1d9d3580c306381cee251c89d4e8fdb97"
 		}
 	}
 }

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

@@ -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** parse args, spawn the matching `harness/*` agent, run all `ask_user` gates, perform policy-gated writes, and emit handoff blocks.
+2. **Agents** perform multi-turn reads and emit structured JSON drafts; they do not approve plans or write canonical run artifacts (except executor mutations in scope).
+3. **HarnessSpawnContext** JSON (`.pi/harness/specs/harness-spawn-context.schema.json`) is required in every spawn prompt because subagents do not receive `[HarnessActivePlan]` injection.
+4. **Review isolation** uses `Agent` spawn with `inherit_context: false`, not session fork. `review-integrity` allows `Agent` / `get_subagent_result` for `harness/evaluator`, `harness/adversary`, and `harness/tie-breaker`.
+5. **Subagent policy** (`harness-subagent-policy.ts`) blocks mutating tools for planner/evaluator/adversary and related read-only agents; executor keeps write tools and `extensions: true`.
+6. **Planner** has `disallowed_tools: ask_user`; clarification options return in JSON for the parent orchestrator.
+
+## 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/harness-spawn-context.schema.json

@@ -0,0 +1,65 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/harness-spawn-context.schema.json",
+	"title": "HarnessSpawnContext",
+	"description": "Structured context passed from harness slash-command orchestrators to harness/* subagents.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "agent", "mode"],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"agent": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Target subagent id, e.g. harness/planner"
+		},
+		"mode": {
+			"type": "string",
+			"enum": [
+				"create",
+				"revise",
+				"execute",
+				"benchmark",
+				"verdict",
+				"adversary",
+				"trace",
+				"incident",
+				"tune"
+			]
+		},
+		"run_id": {
+			"type": "string"
+		},
+		"plan_packet_path": {
+			"type": "string"
+		},
+		"run_dir": {
+			"type": "string"
+		},
+		"task_summary": {
+			"type": "string"
+		},
+		"risk_level": {
+			"type": "string",
+			"enum": ["low", "med", "high"]
+		},
+		"quick": {
+			"type": "boolean"
+		},
+		"acceptance_checks": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"artifact_paths": {
+			"type": "object",
+			"additionalProperties": { "type": "string" }
+		},
+		"handoff_summary": {
+			"type": "string",
+			"description": "Prior phase bullet summary for chained spawns (harness-auto)"
+		}
+	}
+}