@ferris1225/pi-subagents 4.1.3 → 4.1.5

package/src/models.ts

@@ -1,189 +1,189 @@
-/*
- * Model routing, capability-aware thinking, and setup-picker helpers.
- *
- * Runtime has one explicit fallback only: a configured agent model hands
- * off directly to the current main-window model. Setup lists only currently
- * available models and derives thinking choices from Pi's model metadata.
- */
-
-import {
-	clampThinkingLevel,
-	getSupportedThinkingLevels,
-	type Api,
-	type Model,
-} from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
-
-export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
-	Partial<Pick<ExtensionContext, "scopedModels">>;
-
-export const CURRENT_MAIN_MODEL = "__current_main_model__";
-
-export interface ModelPickerItem {
-	value: string;
-	label: string;
-	description?: string;
-}
-
-export type ModelListEntry = Pick<
-	Model<Api>,
-	"provider" | "id" | "name" | "input" | "reasoning" | "thinkingLevelMap"
->;
-
-export interface ResolvedAgentModelRoute {
-	/** Effective first candidate. Undefined means let Pi use its normal default. */
-	primaryRef?: string;
-	/** Current main-window model when it differs from the selection. */
-	mainFallbackRef?: string;
-	/** Runtime order, useful for status/tests. */
-	candidateRefs: string[];
-	/** Configured ref skipped because Pi does not currently report it available. */
-	unavailableSelectedRef?: string;
-}
-
-export interface AgentModelRouteInput {
-	selectedRef?: string;
-	mainRef?: string;
-	declaredDefaultRef?: string;
-	/** When supplied, a configured selection outside this live set is skipped. */
-	availableRefs?: readonly string[];
-}
-
-function cleanModelRef(ref: string | undefined): string | undefined {
-	const trimmed = ref?.trim();
-	return trimmed || undefined;
-}
-
-export function modelRef(model: { provider: string; id: string }): string {
-	return `${model.provider}/${model.id}`;
-}
-
-export function currentModelRef(ctx: Pick<ModelContext, "model">): string | undefined {
-	return ctx.model ? modelRef(ctx.model) : undefined;
-}
-
-/**
- * Current authenticated registry models narrowed by the session scope. Scope
- * entries are a session snapshot, so they act only as a whitelist; the live
- * registry remains the source of truth for availability and model metadata.
- */
-export function availableModelsInScope(ctx: ModelContext): readonly Model<Api>[] {
-	const models = ctx.modelRegistry.getAvailable();
-	// scopedModels was added after the original Pi minimum. Treat a missing field
-	// exactly like an empty scope and use the full live registry.
-	const scopedModels = ctx.scopedModels ?? [];
-	if (scopedModels.length === 0) return models;
-	const scopedRefs = new Set(scopedModels.map((entry) => modelRef(entry.model)));
-	return models.filter((model) => scopedRefs.has(modelRef(model)));
-}
-
-export function findModelByRef(
-	models: readonly Model<Api>[],
-	ref: string | undefined,
-): Model<Api> | undefined {
-	const normalized = cleanModelRef(ref);
-	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
-}
-
-/**
- * Resolve one agent's runtime route:
- *
- * configured selection -> current main-window model
- *
- * Without an override, current main is primary; the agent-declared default is
- * used only when no main model exists. A configured selection that Pi no longer
- * reports as available is skipped immediately instead of spawning a doomed child.
- */
-export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
-	const selectedRef = cleanModelRef(input.selectedRef);
-	const mainRef = cleanModelRef(input.mainRef);
-	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
-	const available = input.availableRefs
-		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
-		: undefined;
-	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
-	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
-	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
-	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
-	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
-	return {
-		primaryRef,
-		...(candidateRefs[1] ? { mainFallbackRef: candidateRefs[1] } : {}),
-		candidateRefs,
-		...(!selectedAvailable && selectedRef ? { unavailableSelectedRef: selectedRef } : {}),
-	};
-}
-
-/** The exact levels Pi exposes for this model, including `off` when supported. */
-export function supportedThinkingLevels(model: Model<Api> | undefined): ThinkingLevel[] {
-	return model ? (getSupportedThinkingLevels(model) as ThinkingLevel[]) : [];
-}
-
-/** Clamp an agent preference to the effective model's actual capability map. */
-export function resolveThinkingLevel(
-	model: Model<Api> | undefined,
-	preferred: ThinkingLevel = DEFAULT_THINKING_LEVEL,
-): ThinkingLevel {
-	return model ? (clampThinkingLevel(model, preferred) as ThinkingLevel) : preferred;
-}
-
-function modelCapabilities(model: ModelListEntry): string {
-	const input = model.input.includes("image") ? "vision" : "text-only";
-	const thinking = getSupportedThinkingLevels(model as Model<Api>).join("/");
-	return `${input} · thinking: ${thinking}`;
-}
-
-/** Build one searchable list for agent model selection. Only models Pi
- * currently reports as available are supplied by setup. */
-export function buildModelPickerItems(options: {
-	models: readonly ModelListEntry[];
-	configuredRef?: string;
-	mainRef?: string;
-}): ModelPickerItem[] {
-	const configuredRef = cleanModelRef(options.configuredRef);
-	const mainRef = cleanModelRef(options.mainRef);
-	const byRef = new Map<string, ModelListEntry>();
-	for (const model of options.models) {
-		const ref = modelRef(model);
-		if (!byRef.has(ref)) byRef.set(ref, model);
-	}
-
-	const refs = [...byRef.keys()]
-		.sort((left, right) => {
-			const leftRank = left === configuredRef ? 0 : left === mainRef ? 1 : 2;
-			const rightRank = right === configuredRef ? 0 : right === mainRef ? 1 : 2;
-			return leftRank - rightRank || left.localeCompare(right);
-		});
-
-	const dynamic: ModelPickerItem = {
-		value: CURRENT_MAIN_MODEL,
-		label: "Current main model (dynamic)",
-		description: "Clear agent override; use the current main model dynamically",
-	};
-	const items: ModelPickerItem[] = [dynamic];
-	for (const ref of refs) {
-		const model = byRef.get(ref)!;
-		const tags = [ref === configuredRef ? "configured" : "", ref === mainRef ? "current main" : ""]
-			.filter(Boolean);
-		const name = model.name.trim() && model.name !== model.id ? model.name.trim() : undefined;
-		items.push({
-			value: ref,
-			label: ref,
-			description: [name, modelCapabilities(model), ...tags].filter(Boolean).join(" · "),
-		});
-	}
-	return items;
-}
-
-/** The dynamic choice removes the persisted per-agent override. */
-export function applyAgentModelChoice(
-	current: Record<string, string>,
-	agentName: string,
-	choice: string,
-): Record<string, string> {
-	const next = { ...current };
-	if (choice === CURRENT_MAIN_MODEL) delete next[agentName];
-	else next[agentName] = choice.trim();
-	return next;
-}
+/*
+ * Model routing, capability-aware thinking, and setup-picker helpers.
+ *
+ * Runtime has one explicit fallback only: a configured agent model hands
+ * off directly to the current main-window model. Setup lists only currently
+ * available models and derives thinking choices from Pi's model metadata.
+ */
+
+import {
+	clampThinkingLevel,
+	getSupportedThinkingLevels,
+	type Api,
+	type Model,
+} from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
+
+export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
+	Partial<Pick<ExtensionContext, "scopedModels">>;
+
+export const CURRENT_MAIN_MODEL = "__current_main_model__";
+
+export interface ModelPickerItem {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+export type ModelListEntry = Pick<
+	Model<Api>,
+	"provider" | "id" | "name" | "input" | "reasoning" | "thinkingLevelMap"
+>;
+
+export interface ResolvedAgentModelRoute {
+	/** Effective first candidate. Undefined means let Pi use its normal default. */
+	primaryRef?: string;
+	/** Current main-window model when it differs from the selection. */
+	mainFallbackRef?: string;
+	/** Runtime order, useful for status/tests. */
+	candidateRefs: string[];
+	/** Configured ref skipped because Pi does not currently report it available. */
+	unavailableSelectedRef?: string;
+}
+
+export interface AgentModelRouteInput {
+	selectedRef?: string;
+	mainRef?: string;
+	declaredDefaultRef?: string;
+	/** When supplied, a configured selection outside this live set is skipped. */
+	availableRefs?: readonly string[];
+}
+
+function cleanModelRef(ref: string | undefined): string | undefined {
+	const trimmed = ref?.trim();
+	return trimmed || undefined;
+}
+
+export function modelRef(model: { provider: string; id: string }): string {
+	return `${model.provider}/${model.id}`;
+}
+
+export function currentModelRef(ctx: Pick<ModelContext, "model">): string | undefined {
+	return ctx.model ? modelRef(ctx.model) : undefined;
+}
+
+/**
+ * Current authenticated registry models narrowed by the session scope. Scope
+ * entries are a session snapshot, so they act only as a whitelist; the live
+ * registry remains the source of truth for availability and model metadata.
+ */
+export function availableModelsInScope(ctx: ModelContext): readonly Model<Api>[] {
+	const models = ctx.modelRegistry.getAvailable();
+	// scopedModels was added after the original Pi minimum. Treat a missing field
+	// exactly like an empty scope and use the full live registry.
+	const scopedModels = ctx.scopedModels ?? [];
+	if (scopedModels.length === 0) return models;
+	const scopedRefs = new Set(scopedModels.map((entry) => modelRef(entry.model)));
+	return models.filter((model) => scopedRefs.has(modelRef(model)));
+}
+
+export function findModelByRef(
+	models: readonly Model<Api>[],
+	ref: string | undefined,
+): Model<Api> | undefined {
+	const normalized = cleanModelRef(ref);
+	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
+}
+
+/**
+ * Resolve one agent's runtime route:
+ *
+ * configured selection -> current main-window model
+ *
+ * Without an override, current main is primary; the agent-declared default is
+ * used only when no main model exists. A configured selection that Pi no longer
+ * reports as available is skipped immediately instead of spawning a doomed child.
+ */
+export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
+	const selectedRef = cleanModelRef(input.selectedRef);
+	const mainRef = cleanModelRef(input.mainRef);
+	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
+	const available = input.availableRefs
+		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
+		: undefined;
+	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
+	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
+	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
+	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
+	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
+	return {
+		primaryRef,
+		...(candidateRefs[1] ? { mainFallbackRef: candidateRefs[1] } : {}),
+		candidateRefs,
+		...(!selectedAvailable && selectedRef ? { unavailableSelectedRef: selectedRef } : {}),
+	};
+}
+
+/** The exact levels Pi exposes for this model, including `off` when supported. */
+export function supportedThinkingLevels(model: Model<Api> | undefined): ThinkingLevel[] {
+	return model ? (getSupportedThinkingLevels(model) as ThinkingLevel[]) : [];
+}
+
+/** Clamp an agent preference to the effective model's actual capability map. */
+export function resolveThinkingLevel(
+	model: Model<Api> | undefined,
+	preferred: ThinkingLevel = DEFAULT_THINKING_LEVEL,
+): ThinkingLevel {
+	return model ? (clampThinkingLevel(model, preferred) as ThinkingLevel) : preferred;
+}
+
+function modelCapabilities(model: ModelListEntry): string {
+	const input = model.input.includes("image") ? "vision" : "text-only";
+	const thinking = getSupportedThinkingLevels(model as Model<Api>).join("/");
+	return `${input} · thinking: ${thinking}`;
+}
+
+/** Build one searchable list for agent model selection. Only models Pi
+ * currently reports as available are supplied by setup. */
+export function buildModelPickerItems(options: {
+	models: readonly ModelListEntry[];
+	configuredRef?: string;
+	mainRef?: string;
+}): ModelPickerItem[] {
+	const configuredRef = cleanModelRef(options.configuredRef);
+	const mainRef = cleanModelRef(options.mainRef);
+	const byRef = new Map<string, ModelListEntry>();
+	for (const model of options.models) {
+		const ref = modelRef(model);
+		if (!byRef.has(ref)) byRef.set(ref, model);
+	}
+
+	const refs = [...byRef.keys()]
+		.sort((left, right) => {
+			const leftRank = left === configuredRef ? 0 : left === mainRef ? 1 : 2;
+			const rightRank = right === configuredRef ? 0 : right === mainRef ? 1 : 2;
+			return leftRank - rightRank || left.localeCompare(right);
+		});
+
+	const dynamic: ModelPickerItem = {
+		value: CURRENT_MAIN_MODEL,
+		label: "Current main model (dynamic)",
+		description: "Clear agent override; use the current main model dynamically",
+	};
+	const items: ModelPickerItem[] = [dynamic];
+	for (const ref of refs) {
+		const model = byRef.get(ref)!;
+		const tags = [ref === configuredRef ? "configured" : "", ref === mainRef ? "current main" : ""]
+			.filter(Boolean);
+		const name = model.name.trim() && model.name !== model.id ? model.name.trim() : undefined;
+		items.push({
+			value: ref,
+			label: ref,
+			description: [name, modelCapabilities(model), ...tags].filter(Boolean).join(" · "),
+		});
+	}
+	return items;
+}
+
+/** The dynamic choice removes the persisted per-agent override. */
+export function applyAgentModelChoice(
+	current: Record<string, string>,
+	agentName: string,
+	choice: string,
+): Record<string, string> {
+	const next = { ...current };
+	if (choice === CURRENT_MAIN_MODEL) delete next[agentName];
+	else next[agentName] = choice.trim();
+	return next;
+}

package/src/monitor.ts

@@ -20,6 +20,15 @@ import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 
 export type RunStatus = "queued" | "running" | "steering" | "interrupting" | "parked" | "done" | "failed";
 export type ContinuationKind = "resume-retained" | "resume-appended" | "fork-retained" | "fork-appended" | "retarget";
+export type WorkflowStageStatus = "done" | "active" | "pending" | "changes" | "failed";
+
+/** Ephemeral projection of one real or currently planned managed stage. It is
+ * live monitor state only; durable results remain the per-run chain records. */
+export interface WorkflowStage {
+	agent: string;
+	relation: string;
+	status: WorkflowStageStatus;
+}
 
 export function isRunActiveStatus(status: RunStatus): boolean {
 	return status === "queued" || status === "running" || status === "steering" || status === "interrupting";
@@ -65,6 +74,9 @@ export interface RunView {
 	/** This stable top-level row currently owns a multi-stage managed workflow.
 	 * Its elapsed time is workflow-wide; active child rows own stage telemetry. */
 	managedWorkflow?: boolean;
+	/** Live-only stage timeline retained on the parent while completed internal
+	 * child rows leave the monitor. */
+	workflowStages?: WorkflowStage[];
 }
 
 /** Optional metadata for documenter/reviewer/fix children of a stable parent run. */
@@ -481,6 +493,18 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		run.managedWorkflow = active || undefined;
+		if (!active) run.workflowStages = undefined;
+		this.notify();
+	}
+
+	/** Replace the live workflow projection atomically so renderers never observe
+	 * a half-updated fix/re-review plan. */
+	setWorkflowStages(id: number, stages: readonly WorkflowStage[]): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.workflowStages = stages.length > 0
+			? stages.map((stage) => ({ ...stage }))
+			: undefined;
 		this.notify();
 	}
 
@@ -615,6 +639,7 @@ export class MonitorStore {
 		run.usage = emptyUsage();
 		run.activity = undefined;
 		run.managedWorkflow = undefined;
+		run.workflowStages = undefined;
 		run.activeSince = undefined;
 		run.endedAt = undefined;
 		run.elapsedMs = Math.max(run.elapsedMs, meta?.elapsedMs ?? 0);

package/src/prompt.ts

@@ -29,14 +29,7 @@ export function buildDelegationDirective(
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
 	];
-	const reviewedWriterNames = [
-		...codeWriterNames,
-		...(hasDocumenter ? ["documenter"] : []),
-	];
-	const automaticWriterRoute = [
-		...(hasDocumenter ? ["documenter"] : []),
-		...(hasReviewer ? ["reviewer"] : []),
-	].join(" → ");
+	const reviewedWriterNames = [...codeWriterNames];
 	const namedWorktreeTargets = [
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
@@ -47,34 +40,43 @@ export function buildDelegationDirective(
 		: namedWorktreeTargets.length === 1
 			? `${namedWorktreeTargets[0]} or another`
 			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
+	const managedWriterWorkflowRule = reviewedWriterNames.length === 0
+		? undefined
+		: hasReviewer && hasDocumenter
+			? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate. Only REVIEW_PASS can authorize documenter, which runs for DOCUMENTATION: NEEDED or a missing marker; the workflow delivers once. Never duplicate stages.`
+			: hasReviewer
+				? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate and then deliver once; never duplicate the gate.`
+				: hasDocumenter
+					? `With reviewer disabled, successful top-level ${reviewedWriterNames.join("/")} runs use documenter as the conservative final fallback and then deliver once; never duplicate the fallback.`
+					: undefined;
 
 	const dispatchRules = [
-		"Handle simple work inline with direct tools: one-line lookups, known-target reads/edits, and quick questions do not justify a child process.",
+		"Keep small, known-target work in the main thread with direct tools: lookups and focused reads/edits do not justify a child context.",
 		...(hasExplorer
 			? [
-				"Use `explorer` proactively when reconnaissance becomes broad or crosses files: mapping unfamiliar code, tracing symbols/dependencies, or answering multi-file location/reference questions. Treat its output only as a retrieval index; re-read load-bearing files before edits or decisions about deletion, security, compatibility, persistence, or dynamic reachability. Use a stronger model/specialist for complex dynamic, concurrent, migration, or security-sensitive analysis.",
+				"Use `explorer` proactively only for broad or cross-file reconnaissance: mapping unfamiliar code, tracing symbols/dependencies, or finding multi-file references. It is a lightweight retrieval index, never an automatic gate. Re-read load-bearing files before edits or high-risk decisions. Use a stronger model/specialist for dynamic, concurrent, migration, or security analysis.",
 			]
 			: []),
 		...(hasWorker
-			? ["Use `worker` for a self-contained implementation, fix, refactor, or test task whose separate context pays for itself."]
+			? ["Use `worker` for a self-contained implementation, fix, refactor, or test whose separate context pays for itself—not a small known-target edit."]
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance. Once dispatched, it applies every safe proven in-scope cut without item-by-item approval; zero edits is valid only if none is proved. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only as the separate evidence-first entry for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance; never substitute it for \`worker\`. It applies every safe proven in-scope cut without item-by-item approval. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
 			]
 			: []),
 		...(hasDocumenter
 			? [
-				`Use \`documenter\` directly for explicit whole-codebase maintenance or standalone documentation work.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already auto-sync the actual diff; never dispatch a duplicate.` : ""} Zero edits is valid and broad mode is never inferred. It changes docs/comments only and never runtime behavior, versions, release state, or ${hasReviewer ? "the final reviewer gate" : "direct final verification"}.`,
+				`Use \`documenter\` directly only for explicit whole-codebase maintenance or standalone documentation/comment work; a top-level documenter delivers directly without an automatic reviewer.${codeWriterNames.length > 0 ? ` ${codeWriterNames.join("/")} must sync existing docs they directly affect; runtime runs documenter only after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback—never dispatch a duplicate.` : ""} It never changes runtime behavior, versions, or release state.`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for read-only assessments or an explicit gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get a fresh read-only reviewer gate.` : ""} Advisory output has no VERDICT: it stays read-only and does not authorize follow-up edits.`,
+				`Use \`reviewer\` for read-only assessments or a gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get one fresh read-only reviewer gate, independent of the writer.` : ""} Advisory output has no VERDICT and cannot authorize follow-up edits${hasDocumenter ? "; gates classify docs separately for the enabled documenter." : "."}`,
 			]
 			: []),
-		"Brief every child with the complete goal, exact paths, constraints, and expected output. It has no memory of this conversation.",
-		"Children are leaf processes without delegation tools. Do not ask them to spawn sub-agents; use `subagent_control fork` on a parked/settled retained thread for an independent continuation.",
+		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory.",
+		"Children are leaf processes without delegation tools; use `subagent_control fork` on a parked/settled thread for an independent continuation.",
 		...(hasMultiple
 			? [
 				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
@@ -86,24 +88,20 @@ export function buildDelegationDirective(
 	];
 
 	const handoffRules = [
-		"Dispatch returns immediately and ends this turn. Never sleep, poll, or call `subagent_wait` to hold the turn; results arrive as messages that automatically resume the main agent, even mid-turn.",
-		"Use `subagent_wait` with explicit `timeoutMs` only when the user specifically asks you to remain in-turn and wait. Its default lookup is non-blocking.",
-		"A result is already shown to the user. Do not restate, paraphrase, or re-summarize it; add only your conclusion or next action, often one line.",
+		"Dispatch ends this turn; results resume the main agent, even mid-turn. Never sleep, poll, or call `subagent_wait` to hold the turn.",
+		"Use `subagent_wait` with explicit `timeoutMs` only when the user asks to wait in-turn; its default lookup is non-blocking.",
+		"Results are already shown. Do not restate, paraphrase, or re-summarize them; add only your conclusion or next action.",
 		"A delivered result does not mean siblings are finished. Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
 	];
 
 	const verificationRules = [
 		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
-		...(automaticWriterRoute && reviewedWriterNames.length > 0
-			? [
-				`Successful top-level write roles automatically continue through enabled downstream roles (${automaticWriterRoute}) to one final delivery; never duplicate stages.`,
-			]
-			: []),
+		...(managedWriterWorkflowRule ? [managedWriterWorkflowRule] : []),
 		...(hasReviewer
 			? [
 				...(hasDocumenter
 					? [
-						`A direct REVIEW_PASS is preliminary: runtime runs documenter on the pending diff, then a fresh reviewer. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps auto-fix; maxFixRounds limits worker fixes only, not initial docs/review." : "cannot start fixes while worker/fix rounds are disabled."}`,
+						`A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps bounded worker/reviewer auto-fix, with docs considered only after its terminal REVIEW_PASS." : "cannot start fixes while worker/fix rounds are disabled."}`,
 					]
 					: []),
 				"Resolve every gate finding; do not bypass the configured auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
@@ -116,7 +114,7 @@ export function buildDelegationDirective(
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-The \`subagent\` tool starts specialized leaf agents in isolated Pi child processes and context windows. It returns immediately; completion messages automatically resume the main agent.
+The \`subagent\` tool starts isolated Pi child processes and context windows. Completions automatically resume the main agent.
 
 Available agents:
 ${catalog}