ultimate-pi 0.7.0 → 0.9.0

package/.pi/lib/harness-run-context.ts

@@ -6,7 +6,7 @@
  * - `.pi/harness/active-run.json` (cross-session pointer)
  */
 
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
 export type HarnessPhase =
@@ -114,6 +114,412 @@ export function canonicalPlanPath(runId: string, projectRoot: string): string {
 	return join(harnessRunsRoot(projectRoot), runId, "plan-packet.json");
 }
 
+const PLAN_PACKET_BASENAME = "plan-packet.json";
+
+const MUTATING_FILE_TOOLS = new Set(["write", "edit"]);
+
+const PLAN_APPROVE_OPTION =
+	/^(approve(d)?(\s+plan)?|yes,?\s+proceed|looks\s+good)$/i;
+const PLAN_CANCEL_OPTION =
+	/^(cancel(led)?|revise|request\s+changes|needs?\s+clarification)$/i;
+
+export interface PlanUserApproval {
+	plan_id: string | null;
+	approved_at: string;
+	source: "ask_user" | "harness-plan-approval" | "noninteractive";
+}
+
+/** Persisted on `input` when user invokes a raw `/harness-*` prompt template. */
+export interface HarnessTurnEntry {
+	schema_version: "1.0.0";
+	command: string;
+	args: string;
+	source: "slash";
+	invoked_at: string;
+}
+
+export const HARNESS_COMMAND_PHASE: Record<string, HarnessPhase> = {
+	"harness-plan": "plan",
+	"harness-auto": "plan",
+	"harness-run": "execute",
+	"harness-eval": "evaluate",
+	"harness-review": "evaluate",
+	"harness-critic": "adversary",
+	"harness-trace": "evaluate",
+	"harness-incident": "evaluate",
+	"harness-drift-replan": "plan",
+	"harness-drift-proceed": "execute",
+	"harness-abort": "plan",
+	"harness-new-run": "plan",
+	"harness-run-status": "plan",
+	"harness-use-run": "plan",
+	"harness-policy-status": "merge",
+	"harness-router-tune": "plan",
+	"harness-budget-status": "plan",
+	"harness-setup": "execute",
+};
+
+export interface PlanPhaseMutationDecision {
+	allowed: boolean;
+	reason?: string;
+	isScopedPlanWrite?: boolean;
+}
+
+/** Resolve path relative to project root when not absolute. */
+export function normalizeHarnessPath(
+	path: string,
+	projectRoot: string,
+): string {
+	const trimmed = path.trim();
+	if (!trimmed) return resolve(projectRoot);
+	if (isAbsolute(trimmed)) return resolve(trimmed);
+	return resolve(projectRoot, trimmed);
+}
+
+export function isCanonicalPlanPacketPath(
+	absPath: string,
+	projectRoot: string,
+	runId: string,
+): boolean {
+	const expected = resolve(canonicalPlanPath(runId, projectRoot));
+	return resolve(absPath) === expected;
+}
+
+export function extractWritePathFromToolInput(
+	input: Record<string, unknown>,
+): string {
+	const raw =
+		(typeof input.path === "string" && input.path) ||
+		(typeof input.filePath === "string" && input.filePath) ||
+		"";
+	return raw.trim();
+}
+
+/** True when absPath is the canonical plan-packet.json for the active run. */
+export async function isPlanPhaseScopedWrite(
+	absPath: string,
+	runCtx: HarnessRunContext | null,
+	projectRoot: string,
+): Promise<boolean> {
+	if (!runCtx?.run_id) return false;
+	let resolved: string;
+	try {
+		resolved = await realpath(normalizeHarnessPath(absPath, projectRoot));
+	} catch {
+		resolved = normalizeHarnessPath(absPath, projectRoot);
+	}
+	const runsRoot = resolve(harnessRunsRoot(projectRoot));
+	let runsReal: string;
+	try {
+		runsReal = await realpath(runsRoot);
+	} catch {
+		runsReal = runsRoot;
+	}
+	const rel = relative(runsReal, resolved);
+	if (rel.startsWith("..") || isAbsolute(rel)) return false;
+	const parts = rel.split(/[/\\]/);
+	if (parts.length !== 2 || parts[1] !== PLAN_PACKET_BASENAME) return false;
+	if (parts[0] !== runCtx.run_id) return false;
+	return isCanonicalPlanPacketPath(resolved, projectRoot, runCtx.run_id);
+}
+
+export function getLatestHarnessTurn(
+	entries: unknown[],
+): HarnessTurnEntry | null {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i] as SessionEntryLike;
+		if (entry.type !== "custom" || entry.customType !== "harness-turn") {
+			continue;
+		}
+		const data = entry.data as Partial<HarnessTurnEntry> | undefined;
+		if (data?.command && typeof data.command === "string") {
+			return {
+				schema_version: "1.0.0",
+				command: data.command,
+				args: typeof data.args === "string" ? data.args : "",
+				source: "slash",
+				invoked_at:
+					typeof data.invoked_at === "string" ? data.invoked_at : nowIso(),
+			};
+		}
+	}
+	return null;
+}
+
+export function indexOfLastPlanCommand(entries: unknown[]): number {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i] as SessionEntryLike & {
+			message?: { role?: string; content?: string | unknown[] };
+		};
+		if (entry.type === "custom" && entry.customType === "harness-turn") {
+			const cmd = (entry.data as { command?: string })?.command;
+			if (cmd === "harness-plan" || cmd === "harness-auto") {
+				return i;
+			}
+		}
+		if (
+			entry.type === "custom" &&
+			entry.customType === "harness-plan-attempt"
+		) {
+			return i;
+		}
+		if (entry.type !== "message" || entry.message?.role !== "user") continue;
+		const content = entry.message.content;
+		const text =
+			typeof content === "string"
+				? content
+				: Array.isArray(content)
+					? content
+							.filter(
+								(c): c is { type: string; text?: string } =>
+									typeof c === "object" &&
+									c !== null &&
+									(c as { type?: string }).type === "text",
+							)
+							.map((c) => c.text ?? "")
+							.join("\n")
+					: "";
+		const visible = userVisiblePromptSlice(text);
+		const parsed = parseHarnessSlashInput(visible);
+		if (
+			parsed?.command === "harness-plan" ||
+			parsed?.command === "harness-auto"
+		) {
+			return i;
+		}
+	}
+	return -1;
+}
+
+export function parseAskUserApprovalFromMessage(msg: {
+	toolName?: string;
+	details?: unknown;
+	content?: { type?: string; text?: string }[];
+}): PlanUserApproval | null {
+	if (msg.toolName !== "ask_user") return null;
+	const details = msg.details as
+		| {
+				cancelled?: boolean;
+				response?: {
+					kind?: string;
+					text?: string;
+					selections?: string[];
+				};
+		  }
+		| undefined;
+	if (details?.cancelled) return null;
+	const response = details?.response;
+	if (!response) return null;
+	if (response.kind === "freeform") {
+		const text = (response.text ?? "").trim();
+		if (/^approve(d)?\b/i.test(text)) {
+			return {
+				plan_id: null,
+				approved_at: nowIso(),
+				source: "ask_user",
+			};
+		}
+		return null;
+	}
+	const selection = (response.selections?.[0] ?? "").trim();
+	if (!selection || PLAN_CANCEL_OPTION.test(selection)) return null;
+	if (PLAN_APPROVE_OPTION.test(selection)) {
+		return {
+			plan_id: null,
+			approved_at: nowIso(),
+			source: "ask_user",
+		};
+	}
+	return null;
+}
+
+export function getLatestPlanUserApproval(
+	entries: unknown[],
+	sinceIndex = 0,
+): PlanUserApproval | null {
+	for (let i = entries.length - 1; i >= sinceIndex; i--) {
+		const entry = entries[i] as SessionEntryLike & {
+			message?: {
+				role?: string;
+				toolName?: string;
+				details?: unknown;
+				content?: { type?: string; text?: string }[];
+			};
+		};
+		if (
+			entry.type === "custom" &&
+			entry.customType === "harness-plan-approval"
+		) {
+			const data = entry.data as Partial<PlanUserApproval> | undefined;
+			if (data?.approved_at) {
+				return {
+					plan_id: typeof data.plan_id === "string" ? data.plan_id : null,
+					approved_at: data.approved_at,
+					source:
+						data.source === "noninteractive"
+							? "noninteractive"
+							: "harness-plan-approval",
+				};
+			}
+		}
+		if (entry.type !== "message" || entry.message?.role !== "toolResult") {
+			continue;
+		}
+		const fromAsk = parseAskUserApprovalFromMessage(entry.message);
+		if (fromAsk) return fromAsk;
+	}
+	return null;
+}
+
+export function hasPlanUserApproval(
+	entries: unknown[],
+	opts?: { planId?: string | null; sincePlanCommand?: boolean },
+): boolean {
+	if (process.env.HARNESS_PLAN_NONINTERACTIVE === "1") {
+		return true;
+	}
+	const since = opts?.sincePlanCommand
+		? Math.max(0, indexOfLastPlanCommand(entries))
+		: 0;
+	const approval = getLatestPlanUserApproval(entries, since);
+	if (!approval) return false;
+	if (opts?.planId && approval.plan_id && approval.plan_id !== opts.planId) {
+		return false;
+	}
+	return true;
+}
+
+export function isHarnessAutoSession(entries: unknown[]): boolean {
+	const since = indexOfLastPlanCommand(entries);
+	if (since < 0) return false;
+	for (let i = since; i < entries.length; i++) {
+		const entry = entries[i] as SessionEntryLike & {
+			message?: { role?: string; content?: string };
+		};
+		if (entry.type !== "message" || entry.message?.role !== "user") continue;
+		const text =
+			typeof entry.message.content === "string"
+				? userVisiblePromptSlice(entry.message.content)
+				: "";
+		const parsed = parseHarnessSlashInput(text);
+		if (parsed?.command === "harness-auto") return true;
+	}
+	return false;
+}
+
+export async function isPlanPhaseAllowedMutation(
+	toolName: string,
+	input: Record<string, unknown>,
+	phase: HarnessPhase,
+	runCtx: HarnessRunContext | null,
+	projectRoot: string,
+	opts: {
+		aborted: boolean;
+		entries: unknown[];
+		ownerSessionId?: string;
+		currentSessionId?: string;
+	},
+): Promise<PlanPhaseMutationDecision> {
+	if (!MUTATING_FILE_TOOLS.has(toolName)) {
+		if (phase === "execute" || phase === "merge") {
+			return { allowed: true };
+		}
+		return {
+			allowed: false,
+			reason: `policy-gate: ${toolName} blocked in phase '${phase}'.`,
+		};
+	}
+
+	if (
+		runCtx?.owner_pi_session_id &&
+		opts.currentSessionId &&
+		runCtx.owner_pi_session_id !== opts.currentSessionId
+	) {
+		return {
+			allowed: false,
+			reason:
+				"harness-run-context: this session does not own the active run; plan writes are read-only here.",
+		};
+	}
+
+	const target = extractWritePathFromToolInput(input);
+	if (!target) {
+		return {
+			allowed: false,
+			reason: "policy-gate: write/edit requires a path.",
+		};
+	}
+
+	const scoped = runCtx
+		? await isPlanPhaseScopedWrite(target, runCtx, projectRoot)
+		: false;
+
+	if (scoped) {
+		if (!runCtx) {
+			return {
+				allowed: false,
+				reason:
+					'policy-gate: no active harness run. Run /harness-plan "<task>" first.',
+			};
+		}
+		if (
+			!hasPlanUserApproval(opts.entries, {
+				sincePlanCommand: true,
+				planId: runCtx.plan_id,
+			})
+		) {
+			return {
+				allowed: false,
+				isScopedPlanWrite: true,
+				reason:
+					"policy-gate: plan-packet.json write blocked until the user approves via ask_user (present the full plan, then Approve).",
+			};
+		}
+		if (opts.aborted) {
+			return { allowed: true, isScopedPlanWrite: true };
+		}
+		if (phase === "plan") {
+			return { allowed: true, isScopedPlanWrite: true };
+		}
+		if (phase === "execute" || phase === "merge") {
+			return { allowed: true, isScopedPlanWrite: true };
+		}
+		return {
+			allowed: false,
+			isScopedPlanWrite: true,
+			reason: `harness-run-context: plan-packet.json is read-only in phase '${phase}'.`,
+		};
+	}
+
+	if (opts.aborted) {
+		return {
+			allowed: false,
+			reason:
+				"policy-gate: mutating tool blocked because harness-abort lock is active. Attach a new approved plan via plan-packet.json first.",
+		};
+	}
+
+	if (phase === "execute" || phase === "merge") {
+		return { allowed: true };
+	}
+
+	if (phase === "plan" && !runCtx) {
+		return {
+			allowed: false,
+			reason:
+				'policy-gate: no active harness run. Run /harness-plan "<task>" first.',
+		};
+	}
+
+	const allowedPath = runCtx?.run_id
+		? canonicalPlanPath(runCtx.run_id, projectRoot)
+		: ".pi/harness/runs/<run_id>/plan-packet.json";
+	return {
+		allowed: false,
+		reason: `policy-gate: ${toolName} blocked in phase '${phase}'. In plan phase only ${allowedPath} is writable after ask_user approval.`,
+	};
+}
+
 export function allocateRunId(sessionId: string): string {
 	return `${sessionId}-${Date.now()}`;
 }
@@ -122,18 +528,16 @@ export function nowIso(): string {
 	return new Date().toISOString();
 }
 
+/** @deprecated Use parseHarnessSlashInput on raw `input` event text only. */
 export function isHarnessSlashCommand(prompt: string): boolean {
-	const trimmed = prompt.trim();
-	if (!trimmed.startsWith("/harness-")) return false;
-	const match = trimmed.match(/^\/(harness-[a-z0-9-]+)/);
-	if (!match) return false;
-	return HARNESS_COMMANDS.has(match[1]);
+	return parseHarnessSlashInput(prompt) !== null;
 }
 
-export function parseHarnessSlashCommand(
-	prompt: string,
+/** Parse raw user input before prompt-template expansion (`input` hook only). */
+export function parseHarnessSlashInput(
+	text: string,
 ): { command: string; args: string } | null {
-	const trimmed = prompt.trim();
+	const trimmed = text.trim();
 	const match = trimmed.match(/^\/(harness-[a-z0-9-]+)(?:\s+([\s\S]*))?$/);
 	if (!match) return null;
 	const command = match[1];
@@ -141,6 +545,13 @@ export function parseHarnessSlashCommand(
 	return { command, args: (match[2] ?? "").trim() };
 }
 
+/** @deprecated Prefer parseHarnessSlashInput on raw input; kept for expanded-prompt fallbacks. */
+export function parseHarnessSlashCommand(
+	prompt: string,
+): { command: string; args: string } | null {
+	return parseHarnessSlashInput(userVisiblePromptSlice(prompt));
+}
+
 /** User-visible prompt slice for policy signals (exclude injected blocks). */
 export function userVisiblePromptSlice(prompt: string): string {
 	const markers = [
@@ -373,7 +784,32 @@ export function planPacketSummary(
 	};
 }
 
-export function formatPlanContextBlock(ctx: HarnessRunContext): string {
+export function buildHarnessSpawnContextSnippet(
+	ctx: HarnessRunContext,
+	opts?: { mode?: "create" | "revise"; risk_level?: string; quick?: boolean },
+): string {
+	const mode =
+		opts?.mode ??
+		(ctx.plan_ready || ctx.status === "aborted" ? "revise" : "create");
+	return JSON.stringify(
+		{
+			schema_version: "1.0.0",
+			run_id: ctx.run_id,
+			plan_packet_path: ctx.plan_packet_path,
+			task_summary: ctx.task_summary,
+			mode,
+			risk_level: opts?.risk_level ?? "med",
+			quick: opts?.quick ?? false,
+		},
+		null,
+		2,
+	);
+}
+
+export function formatPlanContextBlock(
+	ctx: HarnessRunContext,
+	opts?: { mode?: "create" | "revise"; risk_level?: string; quick?: boolean },
+): string {
 	const lines = [
 		"[HarnessRunContext]",
 		`run_id=${ctx.run_id}`,
@@ -388,6 +824,12 @@ export function formatPlanContextBlock(ctx: HarnessRunContext): string {
 	if (ctx.plan_packet_path) {
 		lines.push(`plan_packet_path=${ctx.plan_packet_path}`);
 	}
+	if (ctx.task_summary) {
+		lines.push(`task_summary=${ctx.task_summary}`);
+	}
+	lines.push(
+		`HarnessSpawnContext=${buildHarnessSpawnContextSnippet(ctx, opts)}`,
+	);
 	return lines.join("\n");
 }
 
@@ -471,13 +913,11 @@ export function validatePlanOverridePath(
 	runId: string,
 	projectRoot: string,
 ): { ok: boolean; reason?: string } {
-	const absPlan = resolve(planPath);
-	const runsDir = resolve(harnessRunsRoot(projectRoot), runId);
-	const rel = relative(runsDir, absPlan);
-	if (rel.startsWith("..") || isAbsolute(rel)) {
+	const absPlan = normalizeHarnessPath(planPath, projectRoot);
+	if (!isCanonicalPlanPacketPath(absPlan, projectRoot, runId)) {
 		return {
 			ok: false,
-			reason: `--plan must be under runs/${runId}/ or use /harness-use-run to switch runs`,
+			reason: `--plan must be runs/${runId}/plan-packet.json (canonical plan packet only)`,
 		};
 	}
 	return { ok: true };
@@ -505,7 +945,7 @@ export function shouldReuseHarnessRunId(
 	ctx: HarnessRunContext | null,
 	command: string | null,
 ): boolean {
-	if (!command || !isHarnessSlashCommand(prompt)) return false;
+	if (!command) return false;
 	if (command === "harness-new-run") return false;
 	if (!ctx) return false;
 	if (command === "harness-plan" || command === "harness-auto") {
@@ -530,27 +970,43 @@ export interface HarnessPolicyState {
 	aborted: boolean;
 }
 
+export function inferHarnessPhaseFromTurn(entries: unknown[]): HarnessPhase | null {
+	const turn = getLatestHarnessTurn(entries);
+	if (!turn) return null;
+	return HARNESS_COMMAND_PHASE[turn.command] ?? null;
+}
+
+/** Prefer session `harness-turn`; fall back to raw slash in visible prompt only. */
+export function inferHarnessPhase(
+	entries: unknown[],
+	userPrompt?: string,
+): HarnessPhase {
+	const fromTurn = inferHarnessPhaseFromTurn(entries);
+	if (fromTurn) return fromTurn;
+	if (userPrompt) {
+		const parsed = parseHarnessSlashInput(userVisiblePromptSlice(userPrompt));
+		if (parsed && HARNESS_COMMAND_PHASE[parsed.command]) {
+			return HARNESS_COMMAND_PHASE[parsed.command];
+		}
+	}
+	return "execute";
+}
+
+/** @deprecated Use inferHarnessPhase(entries, prompt) — substring matching causes false plan phase. */
 export function inferHarnessPhaseFromPrompt(prompt: string): HarnessPhase {
-	const p = prompt.toLowerCase();
-	if (
-		p.includes("/harness-plan") ||
-		p.includes("harness-plan") ||
-		p.includes("/harness-auto") ||
-		p.includes("harness-auto")
-	) {
-		return "plan";
+	const p = userVisiblePromptSlice(prompt).toLowerCase();
+	const parsed = parseHarnessSlashInput(userVisiblePromptSlice(prompt));
+	if (parsed && HARNESS_COMMAND_PHASE[parsed.command]) {
+		return HARNESS_COMMAND_PHASE[parsed.command];
 	}
-	if (p.includes("/harness-run") || p.includes("harness-run")) return "execute";
-	if (p.includes("/harness-eval") || p.includes("harness-eval")) {
-		return "evaluate";
+	if (p.startsWith("/harness-plan") || p.startsWith("/harness-auto")) {
+		return "plan";
 	}
-	if (p.includes("/harness-review") || p.includes("harness-review")) {
+	if (p.startsWith("/harness-run")) return "execute";
+	if (p.startsWith("/harness-eval") || p.startsWith("/harness-review")) {
 		return "evaluate";
 	}
-	if (p.includes("/harness-critic") || p.includes("harness-critic")) {
-		return "adversary";
-	}
-	if (p.includes("adversary")) return "adversary";
+	if (p.startsWith("/harness-critic")) return "adversary";
 	if (p.includes("merge gate") || p.includes("policy decision")) return "merge";
 	return "execute";
 }
@@ -569,8 +1025,8 @@ export function isValidHarnessPhaseTransition(
 
 export function getLatestPolicyState(entries: unknown[]): HarnessPolicyState {
 	const fallback: HarnessPolicyState = {
-		phase: "execute",
-		approvedPlan: true,
+		phase: "plan",
+		approvedPlan: false,
 		planId: null,
 		aborted: false,
 	};
@@ -625,7 +1081,7 @@ export function getPolicyTransitionBlock(
 		return { blocked: false };
 	}
 	const state = getLatestPolicyState(entries);
-	const nextPhase = inferHarnessPhaseFromPrompt(userPrompt);
+	const nextPhase = inferHarnessPhase(entries, userPrompt);
 	if (!isValidHarnessPhaseTransition(state.phase, nextPhase)) {
 		return {
 			blocked: true,
@@ -669,7 +1125,7 @@ export function isNewTaskPlanBlocked(
 ): boolean {
 	if (ctx.status !== "active") return false;
 	if (isAmendPlanAllowed(ctx, prompt, false)) return false;
-	const cmd = parseHarnessSlashCommand(prompt);
+	const cmd = parseHarnessSlashInput(userVisiblePromptSlice(prompt));
 	if (cmd?.command !== "harness-plan") return false;
 	const taskMatch = prompt.match(/"([^"]+)"/);
 	if (!taskMatch || !ctx.task_summary) return true;
@@ -701,7 +1157,7 @@ export function nextStepAfterOutcome(input: {
 			return "/harness-plan or /harness-abort";
 		}
 		if (exec === "completed") {
-			return "New Pi session → /harness-eval";
+			return "/harness-eval";
 		}
 	}
 	if (input.phase === "evaluate") {
@@ -792,3 +1248,26 @@ export function driftGateActive(entries: unknown[]): boolean {
 export function phaseTraceFileName(phase: HarnessPhase): string {
 	return `trace-${phase}.json`;
 }
+
+/** Collect plan approvals from a session entry list (e.g. subagent in-memory session). */
+export function extractPlanApprovalsFromEntries(
+	entries: unknown[],
+): PlanUserApproval[] {
+	const out: PlanUserApproval[] = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i] as SessionEntryLike & {
+			message?: {
+				role?: string;
+				toolName?: string;
+				details?: unknown;
+				content?: { type?: string; text?: string }[];
+			};
+		};
+		if (entry.type !== "message" || entry.message?.role !== "toolResult") {
+			continue;
+		}
+		const fromAsk = parseAskUserApprovalFromMessage(entry.message);
+		if (fromAsk) out.push(fromAsk);
+	}
+	return out;
+}

package/.pi/lib/harness-ui-state.ts

@@ -1,4 +1,4 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 export type HarnessPhase =
 	| "plan"