ultimate-pi 0.11.0 → 0.12.0

package/.pi/lib/debate-orchestrator-types.ts

@@ -0,0 +1,38 @@
+/** Shared debate bus participant types (plan + post-execute). */
+
+export type PostExecuteDebateParticipant =
+	| "EvaluatorAgent"
+	| "AdversaryAgent"
+	| "TieBreakerAgent";
+
+export type PlanDebateParticipant =
+	| "PlanEvaluatorAgent"
+	| "PlanAdversaryAgent"
+	| "HypothesisValidatorAgent"
+	| "SprintContractAuditorAgent"
+	| "ReviewIntegratorAgent"
+	| "StackResearchAgent";
+
+export type DebateParticipant =
+	| PostExecuteDebateParticipant
+	| PlanDebateParticipant;
+
+export const PLAN_DEBATE_PARTICIPANTS: PlanDebateParticipant[] = [
+	"PlanEvaluatorAgent",
+	"PlanAdversaryAgent",
+	"HypothesisValidatorAgent",
+	"SprintContractAuditorAgent",
+	"ReviewIntegratorAgent",
+	"StackResearchAgent",
+];
+
+export const POST_EXECUTE_DEBATE_PARTICIPANTS: PostExecuteDebateParticipant[] =
+	["EvaluatorAgent", "AdversaryAgent", "TieBreakerAgent"];
+
+export function isPlanDebateId(debateId: string): boolean {
+	return debateId.startsWith("plan-");
+}
+
+export function debatePhaseFromId(debateId: string): "plan" | "post_execute" {
+	return isPlanDebateId(debateId) ? "plan" : "post_execute";
+}

package/.pi/lib/harness-agent-discovery.mjs

@@ -0,0 +1,81 @@
+/**
+ * Shared agent discovery helpers (manifest + tests).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export function isSafeAgentId(id) {
+	if (!id || id.includes("..") || id.startsWith("/") || id.includes("\\")) {
+		return false;
+	}
+	return /^[a-zA-Z0-9][a-zA-Z0-9/_-]*$/.test(id);
+}
+
+export function sha256Content(content) {
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+export function walkAgentsDir(rootDir, source, out) {
+	if (!existsSync(rootDir)) return;
+	const stack = [rootDir];
+	while (stack.length > 0) {
+		const dir = stack.pop();
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+				continue;
+			}
+			if (!entry.name.endsWith(".md")) continue;
+			const rel = relative(rootDir, full).replace(/\\/g, "/");
+			const id = rel.replace(/\.md$/i, "");
+			if (!isSafeAgentId(id)) continue;
+			let content;
+			try {
+				content = readFileSync(full, "utf-8");
+			} catch {
+				continue;
+			}
+			out.set(id, { id, path: full, source, content });
+		}
+	}
+}
+
+export function discoverFromRoots(packageAgentsDir, projectAgentsDir, globalAgentsDir) {
+	const files = new Map();
+	walkAgentsDir(packageAgentsDir, "package", files);
+	if (globalAgentsDir) walkAgentsDir(globalAgentsDir, "global", files);
+	walkAgentsDir(projectAgentsDir, "project", files);
+	return files;
+}
+
+export function getDriftReport(manifest, onDiskHashes) {
+	const items = [];
+	if (!manifest) {
+		return { ok: false, items: [{ id: "*", kind: "missing_on_disk" }] };
+	}
+	for (const [id, entry] of onDiskHashes) {
+		const expected = manifest.agents[id];
+		if (!expected) {
+			items.push({ id, kind: "missing_in_manifest" });
+			continue;
+		}
+		if (expected.sha256 !== entry.sha256) {
+			items.push({ id, kind: "hash_mismatch" });
+		}
+	}
+	for (const id of Object.keys(manifest.agents)) {
+		if (!onDiskHashes.has(id)) {
+			items.push({ id, kind: "missing_on_disk" });
+		}
+	}
+	return { ok: items.length === 0, items };
+}

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

@@ -2,12 +2,13 @@
  * harness-run-context — shared types and helpers for active harness runs.
  *
  * Session entry `harness-run-context` is the live source of truth; disk mirrors:
- * - `.pi/harness/runs/<run_id>/run-context.json`
+ * - `.pi/harness/runs/<run_id>/run-context.yaml`
  * - `.pi/harness/active-run.json` (cross-session pointer)
  */
 
 import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { readYamlFile, writeYamlFile } from "./harness-yaml.js";
 
 export type HarnessPhase =
 	| "plan"
@@ -67,6 +68,7 @@ export interface PlanPacketLike {
 	risk_level?: string;
 	assumptions?: unknown[];
 	rollback_plan?: unknown;
+	execution_plan?: unknown;
 }
 
 interface SessionEntryLike {
@@ -107,11 +109,22 @@ export function activeRunPointerPath(projectRoot: string): string {
 }
 
 export function runContextDiskPath(runId: string, projectRoot: string): string {
-	return join(harnessRunsRoot(projectRoot), runId, "run-context.json");
+	return join(harnessRunsRoot(projectRoot), runId, RUN_CONTEXT_BASENAME);
 }
 
 export function canonicalPlanPath(runId: string, projectRoot: string): string {
-	return join(harnessRunsRoot(projectRoot), runId, "plan-packet.json");
+	return join(harnessRunsRoot(projectRoot), runId, PLAN_PACKET_BASENAME);
+}
+
+export function canonicalResearchBriefPath(
+	runId: string,
+	projectRoot: string,
+): string {
+	return join(harnessRunsRoot(projectRoot), runId, RESEARCH_BRIEF_BASENAME);
+}
+
+export function runArtifactsDir(runId: string, projectRoot: string): string {
+	return join(harnessRunsRoot(projectRoot), runId, "artifacts");
 }
 
 export const PLAN_REVIEW_BASENAME = "plan-review.md";
@@ -123,7 +136,16 @@ export function canonicalPlanReviewPath(
 	return join(harnessRunsRoot(projectRoot), runId, PLAN_REVIEW_BASENAME);
 }
 
-const PLAN_PACKET_BASENAME = "plan-packet.json";
+export const PLAN_PACKET_BASENAME = "plan-packet.yaml";
+export const RUN_CONTEXT_BASENAME = "run-context.yaml";
+export const RESEARCH_BRIEF_BASENAME = "research-brief.yaml";
+
+const PLAN_RUN_SCOPED_ROOT_FILES = new Set([
+	PLAN_PACKET_BASENAME,
+	RESEARCH_BRIEF_BASENAME,
+	"plan-dag-validation.yaml",
+	PLAN_REVIEW_BASENAME,
+]);
 
 const MUTATING_FILE_TOOLS = new Set(["write", "edit"]);
 
@@ -208,7 +230,21 @@ export function extractWritePathFromToolInput(
 	return raw.trim();
 }
 
-/** True when absPath is the canonical plan-packet.json for the active run. */
+/** True when absPath is a plan-phase artifact under the active run directory. */
+export function isPlanRunScopedRelativePath(rel: string): boolean {
+	if (rel.startsWith("..") || isAbsolute(rel)) return false;
+	const parts = rel.split(/[/\\]/);
+	if (parts.length === 2 && PLAN_RUN_SCOPED_ROOT_FILES.has(parts[1])) {
+		return true;
+	}
+	if (parts.length === 3 && parts[1] === "artifacts") {
+		const file = parts[2];
+		return file.endsWith(".yaml") || file.endsWith(".yml");
+	}
+	return false;
+}
+
+/** True when absPath is a writable plan-run artifact for the active run. */
 export async function isPlanPhaseScopedWrite(
 	absPath: string,
 	runCtx: HarnessRunContext | null,
@@ -229,11 +265,9 @@ export async function isPlanPhaseScopedWrite(
 		runsReal = runsRoot;
 	}
 	const rel = relative(runsReal, resolved);
-	if (rel.startsWith("..") || isAbsolute(rel)) return false;
+	if (!isPlanRunScopedRelativePath(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);
+	return parts[0] === runCtx.run_id;
 }
 
 export function getLatestHarnessTurn(
@@ -497,19 +531,6 @@ export async function isPlanPhaseAllowedMutation(
 					'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 approve_plan or ask_user (present the full plan, then Approve).",
-			};
-		}
 		if (opts.aborted) {
 			return { allowed: true, isScopedPlanWrite: true };
 		}
@@ -522,7 +543,7 @@ export async function isPlanPhaseAllowedMutation(
 		return {
 			allowed: false,
 			isScopedPlanWrite: true,
-			reason: `harness-run-context: plan-packet.json is read-only in phase '${phase}'.`,
+			reason: `harness-run-context: plan-packet.yaml is read-only in phase '${phase}'.`,
 		};
 	}
 
@@ -530,7 +551,7 @@ export async function isPlanPhaseAllowedMutation(
 		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.",
+				"policy-gate: mutating tool blocked because harness-abort lock is active. Attach a new approved plan via plan-packet.yaml first.",
 		};
 	}
 
@@ -548,7 +569,7 @@ export async function isPlanPhaseAllowedMutation(
 
 	const allowedPath = runCtx?.run_id
 		? canonicalPlanPath(runCtx.run_id, projectRoot)
-		: ".pi/harness/runs/<run_id>/plan-packet.json";
+		: `.pi/harness/runs/<run_id>/${PLAN_PACKET_BASENAME}`;
 	return {
 		allowed: false,
 		reason: `policy-gate: ${toolName} blocked in phase '${phase}'. In plan phase only ${allowedPath} is writable after ask_user approval.`,
@@ -754,8 +775,11 @@ export async function loadRunContextFromDisk(
 	projectRoot: string,
 ): Promise<HarnessRunContext | null> {
 	try {
-		const raw = await readFile(runContextDiskPath(runId, projectRoot), "utf-8");
-		return normalizeRunContext(JSON.parse(raw) as Partial<HarnessRunContext>);
+		const doc = await readYamlFile(
+			runContextDiskPath(runId, projectRoot),
+			"run-context",
+		);
+		return normalizeRunContext(doc as Partial<HarnessRunContext>);
 	} catch {
 		return null;
 	}
@@ -766,11 +790,7 @@ export async function saveRunContextToDisk(
 ): Promise<void> {
 	const dir = join(harnessRunsRoot(ctx.project_root), ctx.run_id);
 	await mkdir(dir, { recursive: true });
-	await writeFile(
-		runContextDiskPath(ctx.run_id, ctx.project_root),
-		`${JSON.stringify(ctx, null, 2)}\n`,
-		"utf-8",
-	);
+	await writeYamlFile(runContextDiskPath(ctx.run_id, ctx.project_root), ctx);
 }
 
 export async function loadProjectActiveRun(
@@ -828,8 +848,8 @@ export async function readPlanPacketFromPath(
 	planPath: string,
 ): Promise<PlanPacketLike | null> {
 	try {
-		const raw = await readFile(planPath, "utf-8");
-		return JSON.parse(raw) as PlanPacketLike;
+		const doc = await readYamlFile(planPath, planPath);
+		return doc as PlanPacketLike;
 	} catch {
 		return null;
 	}
@@ -844,8 +864,11 @@ export function validatePlanPacket(packet: PlanPacketLike | null): {
 	const errors: string[] = [];
 	if (packet.schema_version !== "1.0.0")
 		errors.push("schema_version must be 1.0.0");
-	if (packet.contract_version !== "1.0.0")
-		errors.push("contract_version must be 1.0.0");
+	if (
+		packet.contract_version !== "1.0.0" &&
+		packet.contract_version !== "1.1.0"
+	)
+		errors.push("contract_version must be 1.0.0 or 1.1.0");
 	if (!packet.plan_id || typeof packet.plan_id !== "string")
 		errors.push("plan_id required");
 	if (!packet.task_id || typeof packet.task_id !== "string")
@@ -859,6 +882,9 @@ export function validatePlanPacket(packet: PlanPacketLike | null): {
 		errors.push("acceptance_checks required");
 	if (!packet.risk_level) errors.push("risk_level required");
 	if (!packet.rollback_plan) errors.push("rollback_plan required");
+	if (packet.contract_version === "1.1.0" && !packet.execution_plan) {
+		errors.push("execution_plan required for contract_version 1.1.0");
+	}
 	return { valid: errors.length === 0, errors };
 }
 
@@ -957,7 +983,7 @@ export function formatActivePlanBlock(
 		);
 	} else {
 		lines.push(
-			"Plan is read-only in this phase. Do not edit plan-packet.json.",
+			"Plan is read-only in this phase. Do not edit plan-packet.yaml.",
 		);
 	}
 	if (ctx.plan_packet_path) {
@@ -1016,7 +1042,7 @@ export function validatePlanOverridePath(
 	if (!isCanonicalPlanPacketPath(absPlan, projectRoot, runId)) {
 		return {
 			ok: false,
-			reason: `--plan must be runs/${runId}/plan-packet.json (canonical plan packet only)`,
+			reason: `--plan must be runs/${runId}/${PLAN_PACKET_BASENAME} (canonical plan packet only)`,
 		};
 	}
 	return { ok: true };

package/.pi/lib/harness-yaml.mjs

@@ -0,0 +1,73 @@
+/**
+ * YAML read/write for harness plan artifacts (no JSON plan fallbacks).
+ */
+
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { parse, stringify } from "yaml";
+
+const CODE_FENCE_RE = /^```(?:ya?ml|json)?\s*\n?([\s\S]*?)```\s*$/im;
+
+export function stripYamlFences(text) {
+	return stripCodeFences(text);
+}
+
+export function stripCodeFences(text) {
+	const trimmed = text.trim();
+	const m = CODE_FENCE_RE.exec(trimmed);
+	return m ? m[1].trim() : trimmed;
+}
+
+export function parseStructuredDocument(text, label = "document") {
+	const body = stripCodeFences(text);
+	if (!body.trim()) {
+		throw new Error(`${label}: empty document`);
+	}
+
+	try {
+		const yamlDoc = parse(body, { uniqueKeys: true });
+		if (yamlDoc !== null && yamlDoc !== undefined) {
+			return yamlDoc;
+		}
+	} catch {
+		/* try JSON below */
+	}
+
+	const trimmed = body.trim();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		try {
+			return JSON.parse(trimmed);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`${label}: JSON parse failed — ${msg}`);
+		}
+	}
+
+	throw new Error(
+		`${label}: not valid YAML or JSON (use write_harness_yaml with a schema-shaped object)`,
+	);
+}
+
+export function parseYaml(text, label = "yaml") {
+	return parseStructuredDocument(text, label);
+}
+
+export async function readYamlFile(path, label) {
+	const raw = await readFile(path, "utf-8");
+	return parseStructuredDocument(raw, label ?? path);
+}
+
+export async function writeYamlFile(path, data) {
+	const tmp = `${path}.tmp`;
+	const content = `${stringify(data, { indent: 2 })}\n`;
+	await writeFile(tmp, content, "utf-8");
+	await rename(tmp, path);
+}
+
+export function stringifyYaml(data) {
+	return `${stringify(data, { indent: 2 })}\n`;
+}
+
+export function normalizeHarnessYamlContent(text, label = "yaml") {
+	const doc = parseStructuredDocument(text, label);
+	return stringifyYaml(doc);
+}

package/.pi/lib/harness-yaml.ts

@@ -0,0 +1,90 @@
+/**
+ * YAML read/write for harness plan artifacts (no JSON plan fallbacks).
+ */
+
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { parse, stringify } from "yaml";
+
+const CODE_FENCE_RE = /^```(?:ya?ml|json)?\s*\n?([\s\S]*?)```\s*$/im;
+
+/** @deprecated Use stripCodeFences */
+export function stripYamlFences(text: string): string {
+	return stripCodeFences(text);
+}
+
+export function stripCodeFences(text: string): string {
+	const trimmed = text.trim();
+	const m = CODE_FENCE_RE.exec(trimmed);
+	return m ? m[1].trim() : trimmed;
+}
+
+/**
+ * Parse agent output or file body: fenced YAML/JSON, raw YAML, or raw JSON object/array.
+ */
+export function parseStructuredDocument(
+	text: string,
+	label = "document",
+): unknown {
+	const body = stripCodeFences(text);
+	if (!body.trim()) {
+		throw new Error(`${label}: empty document`);
+	}
+
+	try {
+		const yamlDoc = parse(body, { uniqueKeys: true });
+		if (yamlDoc !== null && yamlDoc !== undefined) {
+			return yamlDoc;
+		}
+	} catch {
+		/* try JSON below */
+	}
+
+	const trimmed = body.trim();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		try {
+			return JSON.parse(trimmed) as unknown;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`${label}: JSON parse failed — ${msg}`);
+		}
+	}
+
+	throw new Error(
+		`${label}: not valid YAML or JSON (use write_harness_yaml with a schema-shaped object)`,
+	);
+}
+
+export function parseYaml(text: string, label = "yaml"): unknown {
+	return parseStructuredDocument(text, label);
+}
+
+export async function readYamlFile(
+	path: string,
+	label?: string,
+): Promise<unknown> {
+	const raw = await readFile(path, "utf-8");
+	return parseStructuredDocument(raw, label ?? path);
+}
+
+export async function writeYamlFile(
+	path: string,
+	data: unknown,
+): Promise<void> {
+	const tmp = `${path}.tmp`;
+	const content = `${stringify(data, { indent: 2 })}\n`;
+	await writeFile(tmp, content, "utf-8");
+	await rename(tmp, path);
+}
+
+export function stringifyYaml(data: unknown): string {
+	return `${stringify(data, { indent: 2 })}\n`;
+}
+
+/** Normalize arbitrary agent text to canonical YAML file bytes. */
+export function normalizeHarnessYamlContent(
+	text: string,
+	label = "yaml",
+): string {
+	const doc = parseStructuredDocument(text, label);
+	return stringifyYaml(doc);
+}

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

@@ -5,7 +5,7 @@ argument-hint: "\"<task>\" [--quick] [--risk low|med|high] [--budget <amount>]"
 
 # harness-auto
 
-Pipeline orchestrator — one session, sequential `Agent` spawns. Invoke **harness-orchestration** skill for agent IDs. Do **not** implement or review inline.
+Pipeline orchestrator — one session, sequential phase handoffs. Invoke **harness-orchestration** skill for agent IDs. Do **not** implement or review inline.
 
 ## Step 0 — Parse arguments
 
@@ -18,20 +18,22 @@ If task missing:
 
 ## Orchestration (required) — same session
 
-1. **Plan** — follow `/harness-plan` parent orchestration (parallel `harness/planning/scout-*`, `decompose`, `hypothesis`, draft PlanPacket, `ask_user` on fork, parallel `plan-adversary` + `hypothesis-eval`, parent `approve_plan` + `create_plan`). Do not spawn `harness/planner`. No second approval pass.
-2. **Execute** — spawn `harness/executor` with `HarnessSpawnContext` (`mode: execute`). Summarize handoff bullets for next spawn (do not paste full subagent log).
-3. **Eval** — spawn `harness/evaluator` (`mode: benchmark`) after parent scripts if needed.
-4. **Review** — spawn `harness/evaluator` (`mode: verdict`) OR rely on eval verdict if policy allows — prefer both when strict gates require.
-5. **Adversary** — spawn `harness/adversary` with artifact paths.
-6. **Tie-breaker** — spawn `harness/tie-breaker` only if debate unresolved.
+Follow **harness-plan** performance rules (`subagent` with parallel `tasks`, `agentScope: "both"`).
+
+1. **Plan** — follow `/harness-plan` (parallel scouts → parallel decompose/hypothesis → draft PlanPacket → debate rounds → parent `approve_plan` + `create_plan`). No second approval pass.
+2. **Execute** — `subagent({ agent: "harness/executor", task: "<HarnessSpawnContext mode execute>" })`; summarize handoff bullets only (do not paste full subprocess log).
+3. **Eval** — `subagent({ agent: "harness/evaluator", task: "<mode benchmark>" })` after parent scripts if needed.
+4. **Review** — `subagent({ agent: "harness/evaluator", task: "<mode verdict>" })` when strict gates require.
+5. **Adversary** — `subagent({ agent: "harness/adversary", ... })`. **Skip when `--quick`**.
+6. **Tie-breaker** — `subagent({ agent: "harness/tie-breaker", ... })` only if debate unresolved and **not** `--quick`.
 7. **Parent** — apply locked strict gates below; commit/PR only if all pass.
 
-No new Pi session for review — subagents use isolated context (`inherit_context: false`).
+Review agents run in isolated subprocesses via `subagent` (same parent session).
 
 ## Locked decisions (do not change)
 
 - Always produce and approve plan before mutation.
-- Adversarial review always required.
+- Adversarial review always required **except** `--quick` (evaluator-only gate).
 - Severity-policy-engine blocks merge.
 - Router tuning propose-and-approve only.
 - Plan ambiguity → parent `ask_user` (harness-decisions).
@@ -41,11 +43,11 @@ No new Pi session for review — subagents use isolated context (`inherit_contex
 
 ## Strict gates
 
-Block commit/PR if any fails: plan gate, execution in scope, evaluator pass, adversary complete, severity-policy pass/conditional_pass, benchmark deltas, rollback artifacts.
+Block commit/PR if any fails: plan gate, execution in scope, evaluator pass, adversary complete (unless `--quick`), severity-policy pass/conditional_pass, benchmark deltas, rollback artifacts.
 
 ## Notes
 
-- `--quick` reduces breadth, never safety gates.
+- `--quick` reduces breadth (skips semantic scout, post-run adversary, tie-breaker), never core safety gates on plan approval or evaluator.
 - High risk/ambiguity → stop and recommend manual `/harness-plan` with `ask_user`.
 - Interrupt: `/harness-abort [reason]` then `/harness-plan`.
 - Artifact refs under active run dir; `/harness-run-status` or `/harness-trace-last` for handoff.

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

@@ -20,10 +20,10 @@ Happy path: omit `--run`.
 2. Spawn:
 
 ```
-Agent({ subagent_type: "harness/adversary", prompt: "…" })
+subagent({ agentScope: "both", agent: "harness/adversary", task: "…" })
 ```
 
-3. `get_subagent_result` — parse `AdversaryReport` JSON; parent persists for severity policy.
+3. Parse `AdversaryReport` JSON from tool result; parent persists for severity policy.
 
 ## Parent rules
 

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

@@ -26,11 +26,11 @@ If no active run:
 4. Spawn:
 
 ```
-Agent({ subagent_type: "harness/evaluator", prompt: "…" })
+subagent({ agentScope: "both", agent: "harness/evaluator", task: "<HarnessSpawnContext + eval brief>" })
 ```
 
-5. `get_subagent_result` — parse eval JSON; parent writes structured artifacts under run dir.
-6. Do not edit `plan-packet.json`.
+5. Parse eval JSON from tool result; parent writes structured artifacts under run dir.
+6. Do not edit `plan-packet.yaml`.
 
 ## Parent rules
 

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

@@ -22,10 +22,10 @@ If `--trigger` missing:
 2. Spawn:
 
 ```
-Agent({ subagent_type: "harness/incident-recorder", prompt: "…" })
+subagent({ agentScope: "both", agent: "harness/incident-recorder", task: "…" })
 ```
 
-3. `get_subagent_result` — validate `IncidentRecord` draft; parent writes under `.pi/harness/incidents/`.
+3. Parse `IncidentRecord` JSON from tool result; parent writes under `.pi/harness/incidents/`.
 
 ## Completion