@gajae-code/coding-agent 0.3.0 → 0.3.1

package/src/task/receipt.ts

@@ -0,0 +1,297 @@
+import type { SingleResult, TaskToolDetails } from "./types";
+
+export interface TaskRoi {
+	tokens: number;
+	contextTokens?: number;
+	clonedTokens?: number;
+	costTotal?: number;
+	outputBytes?: number;
+	outputLines?: number;
+	producedChanges: boolean;
+	materialContribution: boolean;
+	lowRoi: boolean;
+}
+export interface TaskResultReceipt {
+	index: number;
+	id: string;
+	agent: string;
+	agentSource: SingleResult["agentSource"];
+	task: string;
+	assignment?: string;
+	description?: string;
+	status: "completed" | "failed" | "aborted" | "merge_failed" | "paused";
+	exitCode: number;
+	aborted?: boolean;
+	paused?: boolean;
+	truncated: boolean;
+	durationMs: number;
+	tokens: number;
+	contextTokens?: number;
+	contextWindow?: number;
+	modelOverride?: string | string[];
+	usage?: SingleResult["usage"];
+	cost?: number;
+	branchName?: string;
+	retryFailure?: { attempt: number; errorSummary: string };
+	errorSummary?: string;
+	abortSummary?: string;
+	preview: string;
+	previewTruncated: boolean;
+	outputRef?: { uri: string; sizeBytes: number; lineCount: number; sha256?: string };
+	outputUnavailable?: boolean;
+	review?: {
+		overallCorrectness?: string;
+		findingCount: number;
+		findings?: Array<{ severity?: string; summary: string }>;
+	};
+	extractedToolCounts?: Record<string, number>;
+	forkContext?: SingleResult["forkContext"];
+	roi?: TaskRoi;
+}
+
+const BANNED_RAW_TASK_KEYS = new Set([
+	"output",
+	"stderr",
+	"extractedToolData",
+	"resultText",
+	"errorText",
+	"artifactPayload",
+	"rawResult",
+	"rawResults",
+	"rawNestedResults",
+	"fullOutput",
+	"full_result",
+	"toolOutput",
+	"toolResultRaw",
+	"stdout",
+	"rawOutput",
+	"recentOutput",
+	"currentToolArgs",
+	"inflightTaskDetails",
+]);
+
+function truncateText(value: string | undefined, maxChars: number): string | undefined {
+	if (!value) return undefined;
+	return value.length > maxChars ? value.slice(0, maxChars) : value;
+}
+
+function buildSafeSynopsis(raw: SingleResult, outputRef: TaskResultReceipt["outputRef"]): string {
+	const status = getStatus(raw);
+	if (raw.retryFailure) {
+		return `Task ${status}; retry stopped after attempt ${raw.retryFailure.attempt}.`;
+	}
+	if (raw.abortReason) {
+		return `Task ${status}; abort reason recorded.`;
+	}
+	if (raw.error) {
+		return `Task ${status}; error recorded.`;
+	}
+	if (outputRef) {
+		return `Task ${status}; output stored in ${outputRef.uri} (${outputRef.lineCount} lines, ${outputRef.sizeBytes} bytes).`;
+	}
+	return `Task ${status}; output artifact unavailable.`;
+}
+
+function getStatus(raw: SingleResult): TaskResultReceipt["status"] {
+	if (raw.paused) return "paused";
+	if (raw.aborted) return "aborted";
+	if (raw.exitCode === 0 && raw.error) return "merge_failed";
+	if (raw.exitCode !== 0 || raw.error) return "failed";
+	return "completed";
+}
+
+function buildReview(raw: SingleResult): TaskResultReceipt["review"] | undefined {
+	const data = raw.extractedToolData;
+	if (!data) return undefined;
+	const yields = Array.isArray(data.yield) ? data.yield : [];
+	const reviewYield = yields
+		.map(item => (item && typeof item === "object" ? (item as { data?: unknown }).data : undefined))
+		.findLast(item => item && typeof item === "object" && "overall_correctness" in item) as
+		| { overall_correctness?: unknown }
+		| undefined;
+	const rawFindings = Array.isArray(data.report_finding) ? data.report_finding : [];
+	const findings = rawFindings.slice(0, 20).map(item => {
+		const value = item && typeof item === "object" ? (item as Record<string, unknown>) : {};
+		const severity =
+			typeof value.severity === "string"
+				? value.severity
+				: typeof value.priority === "string"
+					? value.priority
+					: undefined;
+		const summaryValue = value.summary ?? value.title ?? value.message ?? value.body ?? "finding";
+		return { severity, summary: truncateText(String(summaryValue), 200) ?? "finding" };
+	});
+	if (!reviewYield && findings.length === 0) return undefined;
+	return {
+		overallCorrectness:
+			typeof reviewYield?.overall_correctness === "string" ? reviewYield.overall_correctness : undefined,
+		findingCount: rawFindings.length,
+		findings: findings.length > 0 ? findings : undefined,
+	};
+}
+
+function hasReviewFindings(raw: SingleResult): boolean {
+	const findings = raw.extractedToolData?.report_finding;
+	return Array.isArray(findings) && findings.length > 0;
+}
+
+function hasNonEmptyPreview(raw: SingleResult): boolean {
+	return Boolean((raw.output.trim() || raw.stderr.trim()).trim());
+}
+
+/**
+ * Heuristic task ROI signal built only from receipt-safe accounting fields.
+ * Advisory only: these flags never change task success/failure semantics.
+ */
+export function buildTaskRoi(raw: SingleResult): TaskRoi {
+	const outputBytes = raw.outputMeta?.byteSize ?? (raw.outputMeta ? Buffer.byteLength(raw.output, "utf8") : undefined);
+	const outputLines = raw.outputMeta?.lineCount;
+	const producedChanges =
+		raw.producedChanges ??
+		Boolean(raw.branchName || (Array.isArray(raw.nestedPatches) && raw.nestedPatches.length > 0));
+	const status = getStatus(raw);
+	const terminal = status !== "paused" && !raw.aborted;
+	const materialContribution = Boolean(
+		producedChanges ||
+			(outputBytes !== undefined && outputBytes > 0) ||
+			hasReviewFindings(raw) ||
+			(status === "completed" && raw.tokens > 0 && hasNonEmptyPreview(raw)),
+	);
+	const lowRoi = terminal && raw.tokens > 0 && !materialContribution;
+	return {
+		tokens: raw.tokens,
+		contextTokens: raw.contextTokens,
+		clonedTokens: raw.forkContext?.clonedTokens,
+		costTotal: raw.usage?.cost.total,
+		outputBytes,
+		outputLines,
+		producedChanges,
+		materialContribution,
+		lowRoi,
+	};
+}
+
+export function buildTaskRoiSummary(receipts: readonly TaskResultReceipt[]): TaskToolDetails["roiSummary"] {
+	const totalCostTotal = receipts.reduce((total, receipt) => total + (receipt.roi?.costTotal ?? 0), 0);
+	const totalClonedTokens = receipts.reduce((total, receipt) => total + (receipt.roi?.clonedTokens ?? 0), 0);
+	return {
+		childCount: receipts.length,
+		totalTokens: receipts.reduce((total, receipt) => total + (receipt.roi?.tokens ?? receipt.tokens), 0),
+		totalCostTotal: totalCostTotal > 0 ? totalCostTotal : undefined,
+		totalClonedTokens: totalClonedTokens > 0 ? totalClonedTokens : undefined,
+		lowRoiChildIds: receipts.filter(receipt => receipt.roi?.lowRoi).map(receipt => receipt.id),
+	};
+}
+
+export function buildTaskReceipt(raw: SingleResult): TaskResultReceipt {
+	const outputRef = raw.outputMeta
+		? {
+				uri: `agent://${raw.id}`,
+				sizeBytes: raw.outputMeta.byteSize ?? Buffer.byteLength(raw.output, "utf8"),
+				lineCount: raw.outputMeta.lineCount,
+				sha256: raw.outputMeta.sha256,
+			}
+		: undefined;
+	const preview = buildSafeSynopsis(raw, outputRef);
+	const extractedToolCounts = raw.extractedToolData
+		? Object.fromEntries(
+				Object.entries(raw.extractedToolData).map(([tool, values]) => [
+					tool,
+					Array.isArray(values) ? values.length : 0,
+				]),
+			)
+		: undefined;
+	return {
+		index: raw.index,
+		id: raw.id,
+		agent: raw.agent,
+		agentSource: raw.agentSource,
+		task: raw.task,
+		assignment: raw.assignment,
+		description: raw.description,
+		status: getStatus(raw),
+		exitCode: raw.exitCode,
+		aborted: raw.aborted,
+		paused: raw.paused,
+		truncated: raw.truncated,
+		durationMs: raw.durationMs,
+		tokens: raw.tokens,
+		contextTokens: raw.contextTokens,
+		contextWindow: raw.contextWindow,
+		modelOverride: raw.modelOverride,
+		usage: raw.usage,
+		cost: raw.usage?.cost.total,
+		branchName: raw.branchName,
+		retryFailure: raw.retryFailure
+			? { attempt: raw.retryFailure.attempt, errorSummary: "Retry failure recorded." }
+			: undefined,
+		errorSummary: raw.error ? "Error recorded." : undefined,
+		abortSummary: raw.abortReason ? "Abort reason recorded." : undefined,
+		preview,
+		previewTruncated: false,
+		outputRef,
+		outputUnavailable: outputRef ? undefined : true,
+		review: buildReview(raw),
+		extractedToolCounts,
+		forkContext: raw.forkContext,
+		roi: buildTaskRoi(raw),
+	};
+}
+
+/**
+ * Raw, pre-sanitization task details: the internal shape produced during task
+ * execution, where `results` are full `SingleResult` objects. The public
+ * `TaskToolDetails` exposes only receipts.
+ */
+export interface RawTaskToolDetails {
+	projectAgentsDir: string | null;
+	results: SingleResult[];
+	totalDurationMs: number;
+	usage?: TaskToolDetails["usage"];
+	async?: TaskToolDetails["async"];
+	forkContextClonedTokens?: number;
+	roiSummary?: TaskToolDetails["roiSummary"];
+}
+
+/** Central converter from raw task details to receipt-only public details. */
+export function sanitizeTaskToolDetails(raw: RawTaskToolDetails): TaskToolDetails {
+	return {
+		projectAgentsDir: raw.projectAgentsDir,
+		results: raw.results.map(buildTaskReceipt),
+		totalDurationMs: raw.totalDurationMs,
+		usage: raw.usage,
+		forkContextClonedTokens: raw.forkContextClonedTokens,
+		roiSummary: raw.roiSummary ?? buildTaskRoiSummary(raw.results.map(buildTaskReceipt)),
+		async: raw.async,
+	};
+}
+
+export function findRawTaskLeakKeys(value: unknown): string[] {
+	const found = new Set<string>();
+	const seen = new WeakSet<object>();
+	const visit = (current: unknown) => {
+		if (!current || typeof current !== "object") return;
+		if (seen.has(current)) return;
+		seen.add(current);
+		if (Array.isArray(current)) {
+			for (const item of current) visit(item);
+			return;
+		}
+		for (const [key, child] of Object.entries(current)) {
+			// Banned keys only leak when they carry text or structure. A numeric
+			// value (e.g. the `output` token count on a canonical `Usage` record,
+			// whose shape is `input/output/cacheRead/cacheWrite/totalTokens`) is safe.
+			if (BANNED_RAW_TASK_KEYS.has(key) && typeof child !== "number") found.add(key);
+			visit(child);
+		}
+	};
+	visit(value);
+	return [...found].sort();
+}
+
+export function assertNoRawTaskFields(value: unknown, surface: string): void {
+	const keys = findRawTaskLeakKeys(value);
+	if (keys.length > 0) {
+		throw new Error(`${surface} contains raw task fields: ${keys.join(", ")}`);
+	}
+}

package/src/task/render.ts

@@ -6,12 +6,13 @@
  */
 import path from "node:path";
 import type { Component } from "@gajae-code/tui";
-import { Container, Text } from "@gajae-code/tui";
+import { Text } from "@gajae-code/tui";
 import { formatNumber } from "@gajae-code/utils";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import {
 	formatBadge,
+	formatBytes,
 	formatDuration,
 	formatMoreItems,
 	formatStatusIcon,
@@ -27,8 +28,9 @@ import {
 	type SubmitReviewDetails,
 } from "../tools/review";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine } from "../tui";
+import type { TaskResultReceipt } from "./receipt";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
-import type { AgentProgress, SingleResult, TaskParams, TaskToolDetails } from "./types";
+import type { AgentProgress, TaskParams, TaskToolDetails } from "./types";
 
 /**
  * Get status icon for agent state.
@@ -139,21 +141,6 @@ function formatTaskId(id: string): string {
 	return `${indices} ${labels}`;
 }
 
-const MISSING_YIELD_WARNING_PREFIX = "SYSTEM WARNING: Subagent exited without calling yield tool";
-
-function extractMissingYieldWarning(output: string): { warning?: string; rest: string } {
-	const lines = output.split("\n");
-	const firstLine = lines[0]?.trim() ?? "";
-	if (!firstLine.startsWith(MISSING_YIELD_WARNING_PREFIX)) {
-		return { rest: output };
-	}
-	const rest = lines
-		.slice(1)
-		.join("\n")
-		.replace(/^\s*\n+/, "");
-	return { warning: firstLine, rest };
-}
-
 function buildTreePrefix(ancestors: boolean[], theme: Theme): string {
 	return ancestors.map(hasNext => (hasNext ? `${theme.tree.vertical}  ` : "   ")).join("");
 }
@@ -804,35 +791,24 @@ function renderFindings(
 /**
  * Render final result for a single agent.
  */
-function renderAgentResult(result: SingleResult, isLast: boolean, expanded: boolean, theme: Theme): string[] {
+function renderAgentResult(result: TaskResultReceipt, isLast: boolean, expanded: boolean, theme: Theme): string[] {
 	const lines: string[] = [];
 	const prefix = isLast ? theme.fg("dim", theme.tree.last) : theme.fg("dim", theme.tree.branch);
 	const continuePrefix = isLast ? "   " : `${theme.fg("dim", theme.tree.vertical)}  `;
 
-	const { warning: missingCompleteWarning, rest: outputWithoutWarning } = extractMissingYieldWarning(result.output);
-	const aborted = result.aborted ?? false;
-	const mergeFailed = !aborted && result.exitCode === 0 && !!result.error;
-	const success = !aborted && result.exitCode === 0 && !result.error;
-	const needsWarning = Boolean(missingCompleteWarning) && success;
-	const icon = aborted
-		? theme.status.aborted
-		: needsWarning
-			? theme.status.warning
-			: success
-				? theme.status.success
+	const success = result.status === "completed";
+	const mergeFailed = result.status === "merge_failed";
+	const aborted = result.status === "aborted";
+	const icon = success
+		? theme.status.success
+		: aborted
+			? theme.status.aborted
+			: mergeFailed
+				? theme.status.warning
 				: theme.status.error;
-	const iconColor = needsWarning ? "warning" : success ? "success" : mergeFailed ? "warning" : "error";
-	const statusText = aborted
-		? "aborted"
-		: needsWarning
-			? "warning"
-			: success
-				? "done"
-				: mergeFailed
-					? "merge failed"
-					: "failed";
+	const iconColor = success ? "success" : mergeFailed ? "warning" : "error";
+	const statusText = mergeFailed ? "merge failed" : success ? "done" : result.status;
 
-	// Main status line: id: description [status] · stats · ⟨agent⟩
 	const description = result.description?.trim();
 	const displayId = formatTaskId(result.id);
 	const titlePart = description ? `${theme.bold(displayId)}: ${description}` : displayId;
@@ -847,121 +823,62 @@ function renderAgentResult(result: SingleResult, isLast: boolean, expanded: bool
 			tokens: result.tokens,
 			contextTokens: result.contextTokens,
 			contextWindow: result.contextWindow,
-			cost: result.usage?.cost.total ?? 0,
+			cost: result.cost ?? result.usage?.cost.total ?? 0,
 		},
 		theme,
 	);
 	statusLine += `${theme.sep.dot}${theme.fg("dim", formatDuration(result.durationMs))}`;
-
-	if (result.truncated) {
+	if (result.truncated || result.previewTruncated) {
 		statusLine += ` ${theme.fg("warning", "[truncated]")}`;
 	}
-
 	lines.push(statusLine);
 
 	lines.push(...renderTaskSection(result.assignment ?? result.task, continuePrefix, expanded, theme));
 
-	if (aborted && result.abortReason) {
-		lines.push(
-			`${continuePrefix}${theme.fg("error", theme.status.aborted)} ${theme.fg("dim", truncateToWidth(replaceTabs(result.abortReason), 80))}`,
-		);
-	}
-	// Check for review result (yield with review schema + report_finding)
-	const completeData = result.extractedToolData?.yield as Array<{ data: unknown }> | undefined;
-	const reportFindingData = normalizeReportFindings(result.extractedToolData?.report_finding);
-
-	// Extract review verdict from yield tool's data field if it matches SubmitReviewDetails
-	const reviewData = completeData
-		?.map(c => c.data as SubmitReviewDetails)
-		.filter(d => d && typeof d === "object" && "overall_correctness" in d);
-	const submitReviewData = reviewData && reviewData.length > 0 ? reviewData : undefined;
-
-	if (submitReviewData && submitReviewData.length > 0) {
-		// Use combined review renderer
-		const summary = submitReviewData[submitReviewData.length - 1];
-		const findings = reportFindingData;
-		lines.push(...renderReviewResult(summary, findings, continuePrefix, expanded, theme));
-		return lines;
-	}
-	if (reportFindingData.length > 0) {
-		const hasCompleteData = completeData && completeData.length > 0;
-		const message = hasCompleteData
-			? "Review verdict missing expected fields"
-			: "Review incomplete (yield not called)";
-		lines.push(`${continuePrefix}${theme.fg("warning", theme.status.warning)} ${theme.fg("dim", message)}`);
-		lines.push(`${continuePrefix}${formatFindingSummary(reportFindingData, theme)}`);
-		lines.push(...renderFindings(reportFindingData, continuePrefix, expanded, theme));
-		return lines;
-	}
-
-	// Check for extracted tool data with custom renderers (skip review tools)
-	let hasCustomRendering = false;
-	const deferredToolLines: string[] = [];
-	if (result.extractedToolData) {
-		for (const [toolName, dataArray] of Object.entries(result.extractedToolData)) {
-			// Skip review tools - handled above
-			if (toolName === "yield" || toolName === "report_finding") continue;
-
-			const handler = subprocessToolRegistry.getHandler(toolName);
-			if (handler?.renderFinal && (dataArray as unknown[]).length > 0) {
-				const isTaskTool = toolName === "task";
-				const component = handler.renderFinal(dataArray as unknown[], theme, expanded);
-				const target = isTaskTool ? deferredToolLines : lines;
-				if (!isTaskTool) {
-					hasCustomRendering = true;
-					target.push(`${continuePrefix}${theme.fg("dim", `Tool: ${toolName}`)}`);
-				}
-				if (component instanceof Text) {
-					// Prefix each line with continuePrefix
-					const text = component.getText();
-					for (const line of text.split("\n")) {
-						target.push(`${continuePrefix}${line}`);
-					}
-				} else if (component instanceof Container) {
-					// For containers, render each child
-					for (const child of (component as Container).children) {
-						if (child instanceof Text) {
-							target.push(`${continuePrefix}${child.getText()}`);
-						}
-					}
+	if (result.review) {
+		if (result.review.overallCorrectness) {
+			lines.push(`${continuePrefix}${theme.fg("dim", `Review: ${result.review.overallCorrectness}`)}`);
+		}
+		if (result.review.findingCount > 0) {
+			lines.push(`${continuePrefix}${theme.fg("dim", `${result.review.findingCount} findings`)}`);
+			if (expanded && result.review.findings) {
+				for (const finding of result.review.findings) {
+					const severity = finding.severity ? `${finding.severity}: ` : "";
+					lines.push(`${continuePrefix}${theme.fg("dim", `- ${severity}${finding.summary}`)}`);
 				}
 			}
 		}
+	} else {
+		lines.push(...renderOutputSection(result.preview, continuePrefix, expanded, theme, 3, 12));
+	}
+	if (result.roi?.lowRoi) {
+		lines.push(`${continuePrefix}${theme.fg("warning", "low ROI: produced no material contribution")}`);
 	}
 
-	if (hasCustomRendering && missingCompleteWarning) {
+	if (result.outputRef) {
 		lines.push(
-			`${continuePrefix}${theme.fg("warning", theme.status.warning)} ${theme.fg(
+			`${continuePrefix}${theme.fg(
 				"dim",
-				truncateToWidth(missingCompleteWarning, 80),
+				`Output: ${result.outputRef.uri} (${formatBytes(result.outputRef.sizeBytes)}, ${result.outputRef.lineCount} lines)`,
 			)}`,
 		);
+	} else if (result.outputUnavailable) {
+		lines.push(`${continuePrefix}${theme.fg("dim", "Output artifact unavailable")}`);
 	}
 
-	// Fallback to output preview if no custom rendering
-	if (!hasCustomRendering) {
+	if (result.branchName && success) {
+		lines.push(`${continuePrefix}${theme.fg("dim", `Branch: ${result.branchName}`)}`);
+	}
+	if (result.abortSummary) {
 		lines.push(
-			...renderOutputSection(outputWithoutWarning, continuePrefix, expanded, theme, 3, 12, missingCompleteWarning),
+			`${continuePrefix}${theme.fg("error", theme.status.aborted)} ${theme.fg("dim", truncateToWidth(replaceTabs(result.abortSummary), 80))}`,
 		);
 	}
-
-	if (deferredToolLines.length > 0) {
-		lines.push(...deferredToolLines);
-	}
-
-	if (result.patchPath && !aborted && result.exitCode === 0) {
-		lines.push(`${continuePrefix}${theme.fg("dim", `Patch: ${result.patchPath}`)}`);
-	} else if (result.branchName && !aborted && result.exitCode === 0) {
-		lines.push(`${continuePrefix}${theme.fg("dim", `Branch: ${result.branchName}`)}`);
-	}
-
-	// Error message
-	if (result.error && (!success || mergeFailed) && (!aborted || result.error !== result.abortReason)) {
+	if (result.errorSummary && (!success || mergeFailed)) {
 		lines.push(
-			`${continuePrefix}${theme.fg(mergeFailed ? "warning" : "error", truncateToWidth(replaceTabs(result.error), 70))}`,
+			`${continuePrefix}${theme.fg(mergeFailed ? "warning" : "error", truncateToWidth(replaceTabs(result.errorSummary), 70))}`,
 		);
 	}
-
 	return lines;
 }
 
@@ -1009,9 +926,9 @@ export function renderResult(
 					lines.push(...renderAgentResult(res, isLast, expanded, theme));
 				});
 
-				const abortedCount = details.results.filter(r => r.aborted).length;
-				const mergeFailedCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && r.error).length;
-				const successCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && !r.error).length;
+				const abortedCount = details.results.filter(r => r.status === "aborted").length;
+				const mergeFailedCount = details.results.filter(r => r.status === "merge_failed").length;
+				const successCount = details.results.filter(r => r.status === "completed").length;
 				const failCount = details.results.length - successCount - mergeFailedCount - abortedCount;
 				let summary = `${theme.fg("dim", "Total:")} `;
 				if (abortedCount > 0) {

package/src/task/spawn-gate.ts

@@ -0,0 +1,132 @@
+/** The hard, locked batch threshold enforced by the runtime gate. */
+export const DEFAULT_SPAWN_THRESHOLD = 4;
+
+/** The justification a large batch or reviewer-spawned explorer must supply to pass the hard gate. */
+export interface SpawnPlanReceipt {
+	whyParallel: string;
+	whyNotLocal: string;
+	independence: string;
+	expectedReceiptShape: string;
+	maxInlineTokens: number;
+}
+
+export interface SpawnGateRequest {
+	/** Number of children the batch wants to spawn. */
+	childCount: number;
+	/** The spawn-plan receipt, when provided. */
+	plan?: SpawnPlanReceipt;
+}
+
+export interface ReviewerExploreGateRequest {
+	/** Agent type/name doing the spawning, when known. */
+	spawningAgentType?: string | null;
+	/** Target agent type/name requested by the task call. */
+	targetAgent: string;
+	/** The spawn-plan receipt, when provided. */
+	plan?: SpawnPlanReceipt;
+}
+
+export type SpawnGateOutcome = "allowed" | "rejected";
+
+export interface SpawnGateDecision {
+	outcome: SpawnGateOutcome;
+	/** Human-readable reason, suitable for a blocked-result message. */
+	reason: string;
+	/** Whether a plan was required for this request. */
+	planRequired: boolean;
+	/** Missing plan field names when rejected for an incomplete plan. */
+	missingFields: readonly string[];
+}
+
+const REQUIRED_STRING_FIELDS = ["whyParallel", "whyNotLocal", "independence", "expectedReceiptShape"] as const;
+
+export function findMissingPlanFields(plan: SpawnPlanReceipt | undefined): string[] {
+	if (plan === undefined) {
+		return [...REQUIRED_STRING_FIELDS, "maxInlineTokens"];
+	}
+	const missing: string[] = [];
+	for (const field of REQUIRED_STRING_FIELDS) {
+		const value = plan[field];
+		if (typeof value !== "string" || value.trim().length === 0) {
+			missing.push(field);
+		}
+	}
+	if (
+		typeof plan.maxInlineTokens !== "number" ||
+		!Number.isFinite(plan.maxInlineTokens) ||
+		plan.maxInlineTokens <= 0
+	) {
+		missing.push("maxInlineTokens");
+	}
+	return missing;
+}
+
+export function decide(childCount: number, threshold: number, plan: SpawnPlanReceipt | undefined): SpawnGateDecision {
+	if (!Number.isInteger(childCount) || childCount < 0) {
+		throw new RangeError("childCount must be a non-negative integer");
+	}
+	if (!Number.isInteger(threshold) || threshold < 1) {
+		throw new RangeError("threshold must be a positive integer");
+	}
+
+	const planRequired = childCount > threshold;
+	if (!planRequired) {
+		return {
+			outcome: "allowed",
+			reason: `batch of ${childCount} is at or below threshold ${threshold}`,
+			planRequired: false,
+			missingFields: [],
+		};
+	}
+
+	const missingFields = findMissingPlanFields(plan);
+	if (missingFields.length > 0) {
+		return {
+			outcome: "rejected",
+			reason: `batch of ${childCount} exceeds threshold ${threshold} and the spawn-plan receipt is ${
+				plan === undefined ? "missing" : `incomplete (${missingFields.join(", ")})`
+			}`,
+			planRequired: true,
+			missingFields,
+		};
+	}
+
+	return {
+		outcome: "allowed",
+		reason: `batch of ${childCount} exceeds threshold ${threshold} and a complete spawn-plan receipt was provided`,
+		planRequired: true,
+		missingFields: [],
+	};
+}
+
+export function evaluateSpawnGate(request: SpawnGateRequest): SpawnGateDecision {
+	return decide(request.childCount, DEFAULT_SPAWN_THRESHOLD, request.plan);
+}
+
+export function evaluateReviewerExploreGate(request: ReviewerExploreGateRequest): SpawnGateDecision {
+	if (request.spawningAgentType !== "reviewer" || request.targetAgent !== "explore") {
+		return {
+			outcome: "allowed",
+			reason: "reviewer->explore gate does not apply",
+			planRequired: false,
+			missingFields: [],
+		};
+	}
+
+	const missingFields = findMissingPlanFields(request.plan);
+	if (missingFields.length > 0) {
+		return {
+			outcome: "rejected",
+			reason: `reviewer->explore spawn requires a complete spawn-plan receipt (${missingFields.join(", ")})`,
+			planRequired: true,
+			missingFields,
+		};
+	}
+
+	return {
+		outcome: "allowed",
+		reason: "reviewer->explore spawn has a complete spawn-plan receipt",
+		planRequired: true,
+		missingFields: [],
+	};
+}