ultimate-pi 0.9.1 → 0.10.0

package/.agents/skills/harness-decisions/SKILL.md

@@ -36,18 +36,22 @@ description: Structured user decisions via ask_user for harness setup, planning,
 
 ## Example (plan — approval gate)
 
-After presenting the full PlanPacket in chat:
+`harness/planner` calls **`approve_plan`** with the full `plan_packet` (parent TUI: scrollable plan + Approve / Request changes / Cancel), then **`create_plan`** with the same packet after Approve. Do not use `ask_user` for final approval or `write`/`edit` for the plan file.
 
 ```json
 {
-  "question": "Approve this plan for execution?",
-  "context": "Scope, acceptance checks, and rollback are listed above. The plan file is written only after you approve.",
-  "options": [
-    { "title": "Approve", "description": "Write plan-packet.json and mark plan ready" },
-    { "title": "Request changes", "description": "Revise scope or acceptance before writing" },
-    { "title": "Cancel", "description": "Stop with needs_clarification" }
-  ],
-  "allowFreeform": false
+  "plan_packet": {
+    "schema_version": "1.0.0",
+    "contract_version": "1.0.0",
+    "plan_id": "…",
+    "task_id": "…",
+    "scope": "…",
+    "assumptions": [],
+    "risk_level": "med",
+    "acceptance_checks": ["…"],
+    "rollback_plan": { "revert_commit_ready": true, "rollback_artifacts": { "revert_command": "…", "revert_branch": "…", "patch_bundle": "…" } }
+  },
+  "human_summary": "One-line summary for the overlay header"
 }
 ```
 
@@ -64,8 +68,8 @@ After presenting the full PlanPacket in chat:
 }
 ```
 
-## Who must NOT call ask_user
+## Who calls what
 
-- `harness/planner` — returns `clarification.options` in JSON; parent runs `ask_user`.
-- `harness/evaluator`, `harness/adversary`, and `harness/tie-breaker` — emit `human_required` in structured verdicts; the **parent orchestrator** calls `ask_user`.
-- `harness/executor` — parent handles plan-level and governance forks.
+- `harness/planner` — `ask_user` for clarification; **`approve_plan`** then **`create_plan`** for the plan file (`write`/`edit` blocked).
+- `harness/evaluator`, `harness/adversary`, and `harness/tie-breaker` — emit `human_required`; the **parent orchestrator** calls `ask_user`.
+- Parent orchestrator during `/harness-plan` — must **not** call `ask_user`, `approve_plan`, or `create_plan` (planner owns the full plan lifecycle).

package/.agents/skills/harness-plan/SKILL.md

@@ -17,12 +17,12 @@ description: Produce PlanPacket-aligned harness plans before execute phase. Use
 1. Use `HarnessSpawnContext` from injected `[HarnessRunContext]` — do not read spec files from disk.
 2. Spawn `harness/planner` **once** with that JSON in the prompt (`inherit_context: false`).
 3. Parse planner JSON from `get_subagent_result` (`status`, `plan_packet`, `clarification`).
-4. Do **not** parent `ask_user` or re-spawn for clarification — planner uses `ask_user` in the subagent.
-5. **Only after** subagent approval is synced — write canonical `plan_packet_path`.
+4. Do **not** parent `ask_user` / `approve_plan` / `create_plan` or re-spawn — planner uses those tools in the subagent (bridged UI + `create_plan` write).
+5. Parent checks `plan_ready` on `harness-run-context` after planner returns — **does not** write `plan-packet.json`.
 
 ## Rules
 
-- `harness/planner` owns clarification and approval `ask_user` (bridged to parent UI).
+- `harness/planner` owns clarification (`ask_user`), approval (`approve_plan`), and persistence (`create_plan` — only path to `plan-packet.json`; `write`/`edit` blocked).
 - Never plan or mutate source inline in the slash-command session.
 - context-mode only on harness paths; never lean-ctx.
 

package/.pi/agents/harness/planner.md

@@ -1,6 +1,7 @@
 ---
 description: Harness planner that compiles strict PlanPacket contracts before execution.
-tools: read, grep, find, ls, ask_user
+tools: read, grep, find, ls, ask_user, approve_plan, create_plan
+disallowed_tools: write, edit, bash
 extensions: false
 thinking: medium
 max_turns: 20
@@ -11,7 +12,7 @@ You are the Harness Planner.
 
 ## Mission
 
-Compile a strict, machine-readable `PlanPacket` draft. Run clarification and final approval via `ask_user` in this session (parent UI). You do **not** write `plan-packet.json` — the orchestrator writes the canonical file after you return `status: ready` and the user has approved.
+Compile a strict, machine-readable `PlanPacket`, get user approval, and persist it with **`create_plan`**. You do **not** use `write` or `edit` — those are blocked. The parent orchestrator does not write `plan-packet.json`.
 
 ## Spawn context
 
@@ -26,11 +27,12 @@ Read the `HarnessSpawnContext` JSON in the spawn prompt (`schema_version`, `mode
 5. Build a complete `PlanPacket`: `plan_id`, `task_id`, `scope`, `assumptions`, `risk_level`, `acceptance_checks`, `rollback_plan` with `revert_command`, `revert_branch`, `patch_bundle`, `revert_commit_ready: true`.
 6. Escalate `risk_level` to `high` for blast radius, uncertainty, or policy-sensitive surfaces.
 7. If scope is ambiguous, call `ask_user` with structured options — do not return `needs_clarification` without trying `ask_user` first when options are clear.
-8. Before returning `ready`, present the full plan in chat and call `ask_user` with **Approve** / **Request changes** / **Cancel**. On Request changes, revise and ask again in this session.
+8. Call **`approve_plan`** with the full `plan_packet` (and optional `human_summary`). The parent TUI shows a scrollable plan plus **Approve** / **Request changes** / **Cancel**. On Request changes, revise and call `approve_plan` again.
+9. After the user selects **Approve**, call **`create_plan`** with the same `plan_packet` to write canonical `plan-packet.json` for this run.
 
 ## Guardrails
 
-- Do not mutate project files (read-only tools except `ask_user`).
+- Never call `write`, `edit`, or mutating `bash` — use **`create_plan`** only for the plan file.
 - Never speculate about code you have not read.
 - Do not execute or widen implementation scope.
 
@@ -48,3 +50,5 @@ End with a single fenced `json` block the parent can parse:
 ```
 
 Use `"status": "needs_clarification"` only when blocked after `ask_user` or user cancelled; include `clarification` when the parent must intervene without a live subagent.
+
+When `create_plan` succeeds, set `status` to `"ready"` and confirm `plan_packet_path` was written.

package/.pi/extensions/harness-plan-approval.ts

@@ -0,0 +1,140 @@
+/**
+ * harness-plan-approval — PlanPacket approval UI and transcript renderer for parent sessions.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+	appendPlanApprovalIfNew,
+	getLatestRunContext,
+	parsePlanApprovalFromMessage,
+} from "../lib/harness-run-context.js";
+import { runPlanApprovalDialog } from "./lib/plan-approval/dialog.js";
+import { runPlanApprovalFallback } from "./lib/plan-approval/fallback.js";
+import {
+	renderApprovePlanCall,
+	renderApprovePlanResult,
+	renderHarnessPlanDraft,
+} from "./lib/plan-approval/render.js";
+import {
+	ApprovePlanParamsSchema,
+	PROMPT_GUIDELINES,
+	PROMPT_SNIPPET,
+} from "./lib/plan-approval/schema.js";
+import type {
+	ApprovePlanParams,
+	PlanApprovalDialogResult,
+} from "./lib/plan-approval/types.js";
+import {
+	formatApprovePlanResultText,
+	toApprovePlanToolDetails,
+	validateApprovePlanParams,
+} from "./lib/plan-approval/validate.js";
+
+export default function harnessPlanApproval(pi: ExtensionAPI) {
+	pi.registerMessageRenderer("harness-plan-draft", (message, _options, theme) => {
+		const data = message.details as
+			| {
+					plan_packet?: unknown;
+					human_summary?: string | null;
+			  }
+			| undefined;
+		if (!data?.plan_packet) return undefined;
+		const lines = renderHarnessPlanDraft(
+			{
+				plan_packet: data.plan_packet as Parameters<
+					typeof renderHarnessPlanDraft
+				>[0]["plan_packet"],
+				human_summary: data.human_summary,
+			},
+			80,
+			theme,
+		);
+		return new Text(lines.join("\n"), 0, 0);
+	});
+
+	pi.registerTool({
+		name: "approve_plan",
+		label: "Approve Plan",
+		description:
+			"Present a PlanPacket for user approval with a scrollable plan view. Planners should prefer the subagent bridge; this registers the tool on parent sessions for non-interactive fallback.",
+		promptSnippet: PROMPT_SNIPPET,
+		promptGuidelines: PROMPT_GUIDELINES,
+		parameters: ApprovePlanParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const validated = validateApprovePlanParams(params as ApprovePlanParams);
+			if (typeof validated === "string") {
+				return {
+					content: [{ type: "text", text: validated }],
+					details: {
+						plan_packet: (params as ApprovePlanParams).plan_packet ?? {},
+						options: [],
+						response: null,
+						cancelled: true,
+					},
+				};
+			}
+
+			const planId = String(validated.plan_packet.plan_id ?? "plan");
+			const summary =
+				validated.human_summary?.trim() ||
+				`Plan ${planId} — pending your approval`;
+			pi.sendMessage({
+				customType: "harness-plan-draft",
+				content: summary,
+				display: true,
+				details: {
+					schema_version: "1.0.0",
+					plan_packet: validated.plan_packet,
+					human_summary: validated.human_summary ?? null,
+					shown_at: new Date().toISOString(),
+				},
+			});
+
+			let outcome: PlanApprovalDialogResult;
+			if (ctx.hasUI) {
+				outcome = await runPlanApprovalDialog(ctx.ui, validated);
+			} else {
+				outcome = await runPlanApprovalFallback(ctx.ui, validated);
+			}
+
+			const details = toApprovePlanToolDetails(
+				validated,
+				outcome.response,
+				outcome.cancelled,
+			);
+			const approval = parsePlanApprovalFromMessage({
+				toolName: "approve_plan",
+				details,
+			});
+			if (approval) {
+				const entries = ctx.sessionManager.getEntries();
+				const runCtx = getLatestRunContext(entries);
+				appendPlanApprovalIfNew(
+					(type, data) => pi.appendEntry(type, data),
+					entries,
+					approval,
+					runCtx,
+				);
+			}
+
+			const text = formatApprovePlanResultText(
+				outcome.response,
+				outcome.cancelled,
+			);
+			return {
+				content: [{ type: "text", text }],
+				details,
+			};
+		},
+
+		renderCall(args, theme) {
+			return renderApprovePlanCall(args, theme);
+		},
+
+		renderResult(result, options, theme) {
+			return renderApprovePlanResult(result, options, theme);
+		},
+	});
+}

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

@@ -26,14 +26,15 @@ import {
 	isAmendPlanAllowed,
 	isHarnessBootstrapPrompt,
 	isNewTaskPlanBlocked,
+	isPlanApprovalAskUser,
 	isStaleActiveRunPointer,
 	loadProjectActiveRun,
 	loadRunContextFromDisk,
 	nextStepAfterOutcome,
 	nowIso,
 	type PlanPacketSummary,
-	parseAskUserApprovalFromMessage,
 	parseHarnessSlashInput,
+	parsePlanApprovalFromMessage,
 	planPacketSummary,
 	readPlanPacketFromPath,
 	resolveArgsForCommand,
@@ -582,7 +583,7 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 				activeCtx.last_outcome = "needs_clarification";
 				activeCtx.last_completed_step = "plan";
 				const msg =
-					"Plan file exists but user approval was not recorded. Present the full plan and call ask_user (Approve) before writing plan-packet.json.";
+					"Plan file exists but user approval was not recorded. Planner must call approve_plan (or bridged ask_user Approve) before writing plan-packet.json.";
 				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
 				else
 					pi.sendMessage({
@@ -649,9 +650,12 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_result", async (event, ctx) => {
-		if (event.toolName !== "ask_user" || event.isError) return;
-		const approval = parseAskUserApprovalFromMessage({
-			toolName: "ask_user",
+		if (event.isError) return;
+		if (event.toolName !== "ask_user" && event.toolName !== "approve_plan") {
+			return;
+		}
+		const approval = parsePlanApprovalFromMessage({
+			toolName: event.toolName,
 			details: event.details,
 			content: event.content,
 		});
@@ -662,11 +666,27 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 		pi.appendEntry("harness-plan-approval", {
 			plan_id: approval.plan_id ?? runCtx.plan_id,
 			approved_at: approval.approved_at,
-			source: "ask_user",
+			source: approval.source,
 		});
 	});
 
-	pi.on("tool_call", async (event) => {
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName === "ask_user" && activeCtx?.plan_packet_path) {
+			const input = event.input as {
+				question?: string;
+				options?: unknown[];
+			};
+			if (
+				isPlanApprovalAskUser(input) &&
+				hasPlanUserApproval(getEntries(ctx), { sincePlanCommand: true })
+			) {
+				return {
+					block: true,
+					reason:
+						"harness-run-context: plan already approved via planner subagent; do not call ask_user for plan approval in the parent session.",
+				};
+			}
+		}
 		if (!activeCtx?.plan_packet_path) return undefined;
 		const phase = activeCtx.phase;
 		if (phase !== "evaluate" && phase !== "adversary") return undefined;
@@ -807,7 +827,8 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 			}
 			const target = runCtx.plan_packet_path;
 			if (!target) {
-				if (ctx.hasUI) ctx.ui.notify("No plan_packet_path on active run.", "error");
+				if (ctx.hasUI)
+					ctx.ui.notify("No plan_packet_path on active run.", "error");
 				return;
 			}
 			if (pathArg && pathArg !== target) {

package/.pi/extensions/lib/harness-subagents/harness-subagent-policy.ts

@@ -96,10 +96,20 @@ export function evaluateHarnessSubagentToolCall(
 		return { action: "allow" };
 	}
 
+	if (toolName === "create_plan") {
+		if (kind === "planner") {
+			return { action: "allow" };
+		}
+		return {
+			action: "block",
+			reason: `harness-subagent-policy: create_plan is only for harness/planner.`,
+		};
+	}
+
 	if (MUTATING_TOOLS.has(toolName)) {
 		return {
 			action: "block",
-			reason: `harness-subagent-policy: ${toolName} blocked for harness/${kind} (read-only phase agent).`,
+			reason: `harness-subagent-policy: ${toolName} blocked for harness/${kind} (read-only phase agent). Use create_plan after approve_plan instead of write/edit.`,
 		};
 	}
 

package/.pi/extensions/lib/harness-subagents/parent-ask-user-bridge.ts

@@ -1,89 +1,10 @@
 /**
- * Registers ask_user in subagent sessions, delegating UI to the parent harness session.
+ * @deprecated Import from parent-harness-ui-bridge.js — kept for stable import paths.
  */
-
-import type {
-	ExtensionAPI,
-	ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
-import { runAskDialog } from "../ask-user/dialog.js";
-import { runAskFallback } from "../ask-user/fallback.js";
-import { renderAskCall, renderAskResult } from "../ask-user/render.js";
-import {
-	AskUserParamsSchema,
-	PROMPT_GUIDELINES,
-	PROMPT_SNIPPET,
-} from "../ask-user/schema.js";
-import type { AskUserParams, DialogResult } from "../ask-user/types.js";
-import {
-	formatResultText,
-	toToolDetails,
-	validateAskParams,
-} from "../ask-user/validate.js";
-
-const ASK_USER_AGENT_TYPES = new Set([
-	"harness/planner",
-	"harness/evaluator",
-	"harness/adversary",
-	"harness/tie-breaker",
-]);
-
-export function agentTypeAllowsParentAskUser(agentType: string): boolean {
-	return ASK_USER_AGENT_TYPES.has(agentType);
-}
-
-export function createParentAskUserBridgeFactory(
-	parentCtx: ExtensionContext,
-	agentType: string,
-): ((pi: ExtensionAPI) => void) | null {
-	if (!agentTypeAllowsParentAskUser(agentType)) {
-		return null;
-	}
-	return (pi: ExtensionAPI) => {
-		pi.registerTool({
-			name: "ask_user",
-			label: "Ask User",
-			description:
-				"Ask the user a structured question (parent session UI). Use for clarification and plan approval.",
-			promptSnippet: PROMPT_SNIPPET,
-			promptGuidelines: PROMPT_GUIDELINES,
-			parameters: AskUserParamsSchema,
-			async execute(_toolCallId, params, _signal, _onUpdate) {
-				const validated = validateAskParams(params as AskUserParams);
-				if (typeof validated === "string") {
-					return {
-						content: [{ type: "text", text: validated }],
-						details: {
-							question: params.question ?? "",
-							options: [],
-							response: null,
-							cancelled: true,
-						},
-					};
-				}
-				let outcome: DialogResult;
-				if (parentCtx.hasUI) {
-					outcome = await runAskDialog(parentCtx.ui, validated);
-				} else {
-					outcome = await runAskFallback(parentCtx.ui, validated);
-				}
-				const details = toToolDetails(
-					validated,
-					outcome.response,
-					outcome.cancelled,
-				);
-				const text = formatResultText(outcome.response, outcome.cancelled);
-				return {
-					content: [{ type: "text", text }],
-					details,
-				};
-			},
-			renderCall(args, theme) {
-				return renderAskCall(args, theme);
-			},
-			renderResult(result, options, theme) {
-				return renderAskResult(result, options, theme);
-			},
-		});
-	};
-}
+export {
+	agentTypeAllowsParentAskUser,
+	agentTypeAllowsParentHarnessUi,
+	createParentAskUserBridgeFactory,
+	createParentHarnessUiBridgeFactory,
+	type ParentHarnessUiHooks,
+} from "./parent-harness-ui-bridge.js";