ultimate-pi 0.9.0 → 0.10.0

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

@@ -1,8 +1,8 @@
 {
   "schema_version": "1.0.0",
   "package": "ultimate-pi",
-  "package_version": "0.8.0",
-  "generated_at": "2026-05-17T09:55:45.240Z",
+  "package_version": "0.9.0",
+  "generated_at": "2026-05-17T10:06:28.388Z",
   "agents": {
     "pi-pi/agent-expert": {
       "path": ".pi/agents/pi-pi/agent-expert.md",

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

@@ -126,7 +126,11 @@ const PLAN_CANCEL_OPTION =
 export interface PlanUserApproval {
 	plan_id: string | null;
 	approved_at: string;
-	source: "ask_user" | "harness-plan-approval" | "noninteractive";
+	source:
+		| "ask_user"
+		| "approve_plan"
+		| "harness-plan-approval"
+		| "noninteractive";
 }
 
 /** Persisted on `input` when user invokes a raw `/harness-*` prompt template. */
@@ -291,32 +295,45 @@ export function indexOfLastPlanCommand(entries: unknown[]): number {
 	return -1;
 }
 
-export function parseAskUserApprovalFromMessage(msg: {
+type PlanApprovalToolDetails = {
+	cancelled?: boolean;
+	plan_packet?: PlanPacketLike;
+	response?: {
+		kind?: string;
+		text?: string;
+		selections?: string[];
+	};
+};
+
+function planIdFromApprovalDetails(
+	details: PlanApprovalToolDetails | undefined,
+): string | null {
+	const fromPacket = details?.plan_packet?.plan_id;
+	return typeof fromPacket === "string" && fromPacket.length > 0
+		? fromPacket
+		: null;
+}
+
+export function parsePlanApprovalFromMessage(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;
+	const toolName = msg.toolName;
+	if (toolName !== "ask_user" && toolName !== "approve_plan") return null;
+	const source = toolName === "approve_plan" ? "approve_plan" : "ask_user";
+	const details = msg.details as PlanApprovalToolDetails | undefined;
 	if (details?.cancelled) return null;
 	const response = details?.response;
 	if (!response) return null;
+	const plan_id = planIdFromApprovalDetails(details);
 	if (response.kind === "freeform") {
 		const text = (response.text ?? "").trim();
 		if (/^approve(d)?\b/i.test(text)) {
 			return {
-				plan_id: null,
+				plan_id,
 				approved_at: nowIso(),
-				source: "ask_user",
+				source,
 			};
 		}
 		return null;
@@ -325,14 +342,23 @@ export function parseAskUserApprovalFromMessage(msg: {
 	if (!selection || PLAN_CANCEL_OPTION.test(selection)) return null;
 	if (PLAN_APPROVE_OPTION.test(selection)) {
 		return {
-			plan_id: null,
+			plan_id,
 			approved_at: nowIso(),
-			source: "ask_user",
+			source,
 		};
 	}
 	return null;
 }
 
+/** @deprecated Use parsePlanApprovalFromMessage */
+export function parseAskUserApprovalFromMessage(msg: {
+	toolName?: string;
+	details?: unknown;
+	content?: { type?: string; text?: string }[];
+}): PlanUserApproval | null {
+	return parsePlanApprovalFromMessage(msg);
+}
+
 export function getLatestPlanUserApproval(
 	entries: unknown[],
 	sinceIndex = 0,
@@ -365,8 +391,8 @@ export function getLatestPlanUserApproval(
 		if (entry.type !== "message" || entry.message?.role !== "toolResult") {
 			continue;
 		}
-		const fromAsk = parseAskUserApprovalFromMessage(entry.message);
-		if (fromAsk) return fromAsk;
+		const fromTool = parsePlanApprovalFromMessage(entry.message);
+		if (fromTool) return fromTool;
 	}
 	return null;
 }
@@ -472,7 +498,7 @@ export async function isPlanPhaseAllowedMutation(
 				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).",
+					"policy-gate: plan-packet.json write blocked until the user approves via approve_plan or ask_user (present the full plan, then Approve).",
 			};
 		}
 		if (opts.aborted) {
@@ -569,11 +595,72 @@ export function userVisiblePromptSlice(prompt: string): string {
 
 export function hasApprovedPlanSignalFromUserPrompt(prompt: string): boolean {
 	const p = userVisiblePromptSlice(prompt).toLowerCase();
-	return (
-		p.includes("planpacket") ||
-		p.includes("approved plan") ||
-		/\bplan_id\s*[=:]/i.test(p)
-	);
+	if (p.includes("user approved") || p.includes("already approved")) {
+		return true;
+	}
+	if (/\bapprove(d)?\s+(this\s+)?plan\b/.test(p)) return true;
+	if (p.includes("harness-plan-approval")) return true;
+	return false;
+}
+
+/** Detect parent-session ask_user calls that duplicate planner plan approval. */
+export function isPlanApprovalAskUser(input: {
+	question?: string;
+	options?: unknown[];
+}): boolean {
+	const q = String(input.question ?? "").trim();
+	const opts = Array.isArray(input.options) ? input.options : [];
+	const titles = opts.map((o) => {
+		if (typeof o === "string") return o.trim();
+		if (o && typeof o === "object" && "title" in o) {
+			return String((o as { title?: string }).title ?? "").trim();
+		}
+		return "";
+	});
+	const hasPlanOptions =
+		titles.some(
+			(t) => PLAN_APPROVE_OPTION.test(t) || PLAN_CANCEL_OPTION.test(t),
+		) || PLAN_APPROVE_OPTION.test(q);
+	if (!hasPlanOptions) return false;
+	return /plan|approve/i.test(q);
+}
+
+export function appendPlanApprovalIfNew(
+	appendEntry: (customType: string, data: unknown) => void,
+	parentEntries: unknown[],
+	approval: PlanUserApproval,
+	runCtx: HarnessRunContext | null,
+	opts?: { sincePlanCommand?: boolean },
+): boolean {
+	const since =
+		opts?.sincePlanCommand !== false
+			? Math.max(0, indexOfLastPlanCommand(parentEntries))
+			: 0;
+	if (getLatestPlanUserApproval(parentEntries, since)) {
+		return false;
+	}
+	appendEntry("harness-plan-approval", {
+		plan_id: approval.plan_id ?? runCtx?.plan_id ?? null,
+		approved_at: approval.approved_at,
+		source: approval.source,
+	});
+	return true;
+}
+
+/** Sync planner subagent approvals into the parent session (deduped). */
+export function syncPlannerApprovalsToParent(
+	appendEntry: (customType: string, data: unknown) => void,
+	parentEntries: unknown[],
+	subEntries: unknown[],
+	runCtx: HarnessRunContext | null,
+): number {
+	let synced = 0;
+	for (const approval of extractPlanApprovalsFromEntries(subEntries)) {
+		if (appendPlanApprovalIfNew(appendEntry, parentEntries, approval, runCtx)) {
+			synced++;
+		}
+	}
+	return synced;
 }
 
 export function isDriftReplanPrompt(prompt: string): boolean {
@@ -970,7 +1057,9 @@ export interface HarnessPolicyState {
 	aborted: boolean;
 }
 
-export function inferHarnessPhaseFromTurn(entries: unknown[]): HarnessPhase | null {
+export function inferHarnessPhaseFromTurn(
+	entries: unknown[],
+): HarnessPhase | null {
 	const turn = getLatestHarnessTurn(entries);
 	if (!turn) return null;
 	return HARNESS_COMMAND_PHASE[turn.command] ?? null;
@@ -1266,8 +1355,8 @@ export function extractPlanApprovalsFromEntries(
 		if (entry.type !== "message" || entry.message?.role !== "toolResult") {
 			continue;
 		}
-		const fromAsk = parseAskUserApprovalFromMessage(entry.message);
-		if (fromAsk) out.push(fromAsk);
+		const fromTool = parsePlanApprovalFromMessage(entry.message);
+		if (fromTool) out.push(fromTool);
 	}
 	return out;
 }

package/.pi/prompts/harness-plan.md

@@ -5,7 +5,7 @@ argument-hint: "\"<task>\" [--risk low|med|high] [--budget <amount>] [--quick]"
 
 # harness-plan
 
-Orchestrator only — spawn `harness/planner` once; planner runs clarification and approval via `ask_user` (parent UI). Write `plan-packet.json` only after approval. Do **not** plan inline in this session.
+Orchestrator only — spawn `harness/planner` once. The planner runs clarification (`ask_user`), approval (`approve_plan`), and persists the plan (`create_plan`). Do **not** write `plan-packet.json` in this parent session.
 
 ## Step 0 — Parse arguments
 
@@ -33,7 +33,7 @@ Otherwise use `HarnessSpawnContext` from `[HarnessRunContext]` for greenfield `m
 
 ## Orchestration (required)
 
-1. Copy the `HarnessSpawnContext=…` JSON from `[HarnessRunContext]` into the spawn prompt (adjust `risk_level`, `quick`, `mode` from `$ARGUMENTS` if needed).
+1. Copy the `HarnessSpawnContext=…` JSON from `[HarnessRunContext]` into the spawn prompt (adjust `risk_level`, `quick`, `mode` from `$ARGUMENTS` if needed). Do **not** add “call ask_user for approval” in the `Agent` prompt — the planner agent instructions already define `approve_plan` / `create_plan`.
 2. Spawn **once** with **`inherit_context: false`**:
 
 ```
@@ -41,15 +41,15 @@ Agent({ subagent_type: "harness/planner", prompt: "<task + HarnessSpawnContext J
 ```
 
 3. `get_subagent_result` — parse final JSON (`status`, `plan_packet`, `human_summary`, `clarification`) via fenced `json` block.
-4. If `status === "ready"` and user approved in the subagent (`ask_user` Approve), validate `plan_packet` fields, then **write** `PlanPacket` JSON to canonical `plan_packet_path` from `[HarnessRunContext]`.
+4. If `status === "ready"` and parent `harness-run-context` shows `plan_ready: true` (planner called `create_plan`), confirm `plan_packet_path` exists — do **not** write the file yourself.
 5. If `needs_clarification`, tell the user the planner is waiting — do **not** re-spawn; user should answer in the subagent or re-run `/harness-plan`.
-6. Do **not** call `ask_user` in this parent session for planner clarification or approval.
+6. Do **not** call `ask_user`, `approve_plan`, or `create_plan` in this parent session.
 
 ## Parent rules
 
-- Do not mutate project source files — only `plan-packet.json` after subagent approval is recorded.
+- Do not mutate project source files in the plan phase.
 - Do not embed `plan_id=` in prompts for policy sync.
-- Optional: `/harness-plan-commit` if write was blocked but approval exists.
+- Optional recovery: `/harness-plan-commit` only if the planner approved but `create_plan` failed.
 
 ## Completion
 

package/.pi/scripts/harness-verify.mjs

@@ -5,7 +5,7 @@
 
 import { readFile, access } from "node:fs/promises";
 import { constants } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 
@@ -202,6 +202,33 @@ async function main() {
 	if (!(await fileExists(runCtxLib))) fail("missing lib/harness-run-context.ts");
 	ok("lib/harness-run-context.ts");
 
+	const vendoredIndex = join(
+		ROOT,
+		".pi",
+		"extensions",
+		"lib",
+		"harness-subagents",
+		"vendored",
+		"index.ts",
+	);
+	const vendoredSrc = await readFile(vendoredIndex, "utf-8");
+	const runCtxImport = vendoredSrc.match(
+		/from ["']([^"']*harness-run-context\.js)["']/,
+	);
+	if (!runCtxImport) {
+		fail("vendored/index.ts must import harness-run-context.js");
+	}
+	const runCtxImportPath = resolve(
+		dirname(vendoredIndex),
+		runCtxImport[1].replace(/\.js$/, ".ts"),
+	);
+	if (runCtxImportPath !== runCtxLib) {
+		fail(
+			`vendored/index.ts harness-run-context import resolves to ${runCtxImportPath}, expected ${runCtxLib}`,
+		);
+	}
+	ok("vendored/index.ts harness-run-context import path");
+
 	const policyGateSrc = await readFile(
 		join(ROOT, ".pi", "extensions", "policy-gate.ts"),
 		"utf-8",

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [v0.10.0] — 2026-05-17
+
+### ✨ Features
+
+- **Harness plan UX:** scrollable `approve_plan` overlay with `harness-plan-draft` parent transcript; planner-only `create_plan` persists canonical `plan-packet.json` after approval; blocks planner `write`/`edit` for plan files; syncs subagent approvals and dedupes duplicate plan-approval gates.
+
+## [v0.9.1] — 2026-05-17
+
+### 🐛 Fixes
+
+- **npm package:** fix `harness-subagents` vendored import of `harness-run-context` (`../../../../lib`); broken installs failed with `Cannot find module '../../../lib/harness-run-context.js'`.
+
 ## [v0.9.0] — 2026-05-17
 
 ### ✨ Features

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -73,7 +73,7 @@
 		"@earendil-works/pi-coding-agent": "*"
 	},
 	"scripts": {
-		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/00-ultimate-pi-system-prompt.ts .pi/lib/harness-run-context.ts .pi/lib/harness-ui-state.ts .pi/extensions/harness-run-context.ts .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/policy-gate.ts .pi/extensions/budget-guard.ts .pi/extensions/debate-orchestrator.ts .pi/extensions/harness-live-widget.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/lib/harness-subagents/agent-loader.ts .pi/extensions/lib/harness-subagents/agent-parser.ts .pi/extensions/lib/harness-subagents/agent-manifest.ts .pi/extensions/lib/harness-subagents/blackboard.ts .pi/extensions/lib/harness-subagents/blackboard-tool.ts .pi/extensions/lib/harness-subagents/spawn-policy.ts .pi/extensions/lib/harness-subagents/types-blackboard.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/extensions/lib/harness-web/run-cli.ts",
+		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/00-ultimate-pi-system-prompt.ts .pi/lib/harness-run-context.ts .pi/lib/harness-ui-state.ts .pi/extensions/harness-run-context.ts .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/harness-plan-approval.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/lib/plan-approval/types.ts .pi/extensions/lib/plan-approval/schema.ts .pi/extensions/lib/plan-approval/validate.ts .pi/extensions/lib/plan-approval/format-plan.ts .pi/extensions/lib/plan-approval/dialog.ts .pi/extensions/lib/plan-approval/fallback.ts .pi/extensions/lib/plan-approval/render.ts .pi/extensions/lib/plan-approval/create-plan.ts .pi/extensions/lib/harness-subagents/parent-harness-ui-bridge.ts .pi/extensions/lib/harness-subagents/parent-harness-ui-hooks.ts .pi/extensions/lib/harness-subagents/parent-ask-user-bridge.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/policy-gate.ts .pi/extensions/budget-guard.ts .pi/extensions/debate-orchestrator.ts .pi/extensions/harness-live-widget.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/lib/harness-subagents/agent-loader.ts .pi/extensions/lib/harness-subagents/agent-parser.ts .pi/extensions/lib/harness-subagents/agent-manifest.ts .pi/extensions/lib/harness-subagents/blackboard.ts .pi/extensions/lib/harness-subagents/blackboard-tool.ts .pi/extensions/lib/harness-subagents/spawn-policy.ts .pi/extensions/lib/harness-subagents/types-blackboard.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/extensions/lib/harness-web/run-cli.ts",
 		"vendor:sync-router": "bash .pi/scripts/vendor-sync-pi-model-router.sh",
 		"vendor:sync-vcc": "bash .pi/scripts/vendor-sync-pi-vcc.sh",
 		"release": "bash .pi/scripts/release.sh",
@@ -82,7 +82,7 @@
 		"format": "biome format --write",
 		"format:check": "biome format",
 		"prepare": "lefthook install",
-		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-turn-routing.test.mjs",
+		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagents-import-path.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-turn-routing.test.mjs test/plan-approval-format.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs",
 		"test:vcc": "npx -y tsx --test vendor/pi-vcc/tests/*.test.ts",
 		"harness:sentrux-bootstrap": "node .pi/scripts/harness-sentrux-bootstrap.mjs",
 		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",