pi-subagents 0.53.0 → 0.55.0

package/src/runs/foreground/workflow-detach-reconcile.ts

@@ -119,6 +119,7 @@ function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result
 		timestamp: Date.now(),
 		results: workflowResultChildren(status, childRunId, result, existing?.results),
 		workflow: status.workflow,
+		reconciledFromDetachedChild: childRunId,
 		...(receipt ? { workflowReceipt: { path: path.join(asyncDir, "workflow-receipt.json"), receipt } } : {}),
 		asyncDir,
 		cwd: status.cwd,
@@ -252,6 +253,8 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 			success: next.state === "complete",
 			state: next.state,
 			summary: typeof published.summary === "string" ? published.summary : (next.state === "complete" ? "Workflow completed." : next.error),
+			reconciledFromDetachedChild: input.childRunId,
+			...(Array.isArray(published.results) ? { results: published.results } : {}),
 			sessionId: next.sessionId,
 			completionOwnerId: next.completionOwnerId,
 			timestamp: Date.now(),

package/src/runs/shared/acceptance.ts

@@ -959,6 +959,7 @@ function checkNoStagedFiles(cwd: string): AcceptanceRuntimeCheck {
 function runStructuralChecks(acceptance: ResolvedAcceptanceConfig, report: AcceptanceReport, cwd: string): AcceptanceRuntimeCheck[] {
 	const checks: AcceptanceRuntimeCheck[] = [];
 	for (const kind of acceptance.evidence) {
+		if (kind === "no-staged-files" && report.noStagedFiles === undefined) continue;
 		const status = reportEvidenceStatus(report, kind);
 		checks.push({
 			id: `evidence:${kind}`,

package/src/runs/shared/child-identity.ts

@@ -0,0 +1,36 @@
+import type { AsyncStatus } from "../../shared/types.ts";
+
+export type AsyncStatusStep = NonNullable<AsyncStatus["steps"]>[number];
+
+export interface ResolvedAsyncStatusChild {
+	index: number;
+	step: AsyncStatusStep;
+	id: string;
+}
+
+export type AsyncStatusChildResolution =
+	| { ok: true; child: ResolvedAsyncStatusChild }
+	| { ok: false; code: "not_found" | "ambiguous"; message: string };
+
+export function asyncStatusChildIdentity(step: AsyncStatusStep, index: number): string {
+	return step.workflowKey ?? step.runId ?? `step:${index}`;
+}
+
+export function asyncStatusChildIdentityCandidates(step: AsyncStatusStep, index: number): string[] {
+	return [...new Set([step.workflowKey, step.runId, `step:${index}`].filter((value): value is string => typeof value === "string" && value.length > 0))];
+}
+
+export function resolveAsyncStatusChild(status: Pick<AsyncStatus, "runId" | "steps">, childId: string): AsyncStatusChildResolution {
+	const matches: ResolvedAsyncStatusChild[] = [];
+	for (const [index, step] of (status.steps ?? []).entries()) {
+		if (!asyncStatusChildIdentityCandidates(step, index).includes(childId)) continue;
+		matches.push({ index, step, id: asyncStatusChildIdentity(step, index) });
+	}
+	if (matches.length === 1) return { ok: true, child: matches[0]! };
+	if (matches.length > 1) return { ok: false, code: "ambiguous", message: `Child '${childId}' is ambiguous under async run '${status.runId}'.` };
+	return { ok: false, code: "not_found", message: `Child '${childId}' was not found under async run '${status.runId}'.` };
+}
+
+export function isStoppableAsyncStatusStep(step: AsyncStatusStep): boolean {
+	return step.status === "pending" || step.status === "running";
+}

package/src/runs/shared/completion-guard.ts

@@ -1,6 +1,7 @@
 import type { Message } from "@earendil-works/pi-ai";
+import type { AcceptanceRole } from "../../shared/types.ts";
 import { isMutatingTool } from "./long-running-guard.ts";
-import { expectsImplementationMutation } from "./task-intent.ts";
+import { classifyTaskMutationIntent, expectsImplementationMutation, taskMayMutate } from "./task-intent.ts";
 
 export { expectsImplementationMutation };
 
@@ -14,6 +15,7 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 	"get_search_content",
 	"intercom",
 	"contact_supervisor",
+	"structured_output",
 ]);
 
 // Cursor native edit/write often land as thinking traces (inactive_trace /
@@ -45,12 +47,15 @@ interface CompletionMutationGuardInput {
 	messages: Message[];
 	tools?: string[];
 	mcpDirectTools?: string[];
+	toolAvailabilityError?: string;
 }
 
 interface CompletionMutationGuardResult {
 	expectedMutation: boolean;
 	attemptedMutation: boolean;
 	triggered: boolean;
+	blocked: boolean;
+	message?: string;
 }
 
 interface ReportSentence {
@@ -64,6 +69,40 @@ export function hasMutationToolCapability(tools: string[] | undefined, mcpDirect
 	return !tools.every((tool) => READ_ONLY_BUILTIN_TOOLS.has(tool));
 }
 
+function hasBuiltinMutationTool(tools: string[] | undefined): boolean {
+	return tools === undefined || tools.some((tool) => !READ_ONLY_BUILTIN_TOOLS.has(tool));
+}
+
+function isWriterRole(agent: string, acceptanceRole: AcceptanceRole | undefined): boolean {
+	return acceptanceRole === "writer"
+		|| (acceptanceRole === undefined && /\bworker\b/i.test(agent));
+}
+
+const WRITER_DELIVERY_PATTERN = /\b(?:address|resolve|work)\s+(?:backlog\s+)?(?:item|issue)\b|\b(?:land|ship)\s+(?:the\s+)?(?:change|changes|fix|feature|implementation)\b/i;
+
+export function validateImplementationToolContract(input: {
+	agent: string;
+	task: string;
+	tools?: string[];
+	mcpDirectTools?: string[];
+	configuredExtensions?: string[];
+	requestedTools?: string[];
+	acceptanceRole?: AcceptanceRole;
+	completionGuard?: boolean;
+}): string | undefined {
+	if (input.completionGuard === false) return undefined;
+	const requestedMutationTools = input.requestedTools?.filter((tool) => !READ_ONLY_BUILTIN_TOOLS.has(tool)) ?? [];
+	const declaredMutationToolsWereRemoved = requestedMutationTools.length > 0 && !hasBuiltinMutationTool(input.tools);
+	const configuredExtensionCapability = (input.configuredExtensions?.length ?? 0) > 0 && !declaredMutationToolsWereRemoved;
+	if (hasMutationToolCapability(input.tools, input.mcpDirectTools) || configuredExtensionCapability) return undefined;
+	const intent = classifyTaskMutationIntent(input.agent, input.task);
+	if (intent.kind === "read-only") return undefined;
+	const writerTaskMayMutate = isWriterRole(input.agent, input.acceptanceRole)
+		&& (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
+	if (intent.kind !== "implementation" && !writerTaskMayMutate && !declaredMutationToolsWereRemoved) return undefined;
+	return `Agent '${input.agent}' was given an implementation task, but its tool allowlist has no mutation-capable tools. Add bash, edit, write, or another mutation-capable tool to the agent, or use a read-only task/agent.`;
+}
+
 function hasCheckpointMutationEvidence(message: Message): boolean {
 	const record = message as unknown as {
 		role?: string;
@@ -187,6 +226,15 @@ function reportsNoBetterChallengeChange(messages: Message[]): boolean {
 }
 
 export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
+	if (input.toolAvailabilityError && expectsImplementationMutation(input.agent, input.task)) {
+		return {
+			expectedMutation: true,
+			attemptedMutation: false,
+			triggered: false,
+			blocked: true,
+			message: input.toolAvailabilityError,
+		};
+	}
 	const expectedMutation = hasMutationToolCapability(input.tools, input.mcpDirectTools)
 		? expectsImplementationMutation(input.agent, input.task)
 		: false;
@@ -197,5 +245,6 @@ export function evaluateCompletionMutationGuard(input: CompletionMutationGuardIn
 		expectedMutation,
 		attemptedMutation,
 		triggered: expectedMutation && !attemptedMutation && !noEditChallengeComplete,
+		blocked: false,
 	};
 }

package/src/runs/shared/external-job-bridge.ts

@@ -11,6 +11,7 @@ import {
 	type ExternalJobHandle,
 	type ExternalJobOperation,
 	type ExternalJobResult,
+	type ExternalJobFollowUpInput,
 	type ExternalJobStartInput,
 } from "../../api/external-job-provider.ts";
 
@@ -26,6 +27,7 @@ interface ExternalJobBridgeRequest {
 	provider: string;
 	providerJobId?: string;
 	start?: ExternalJobStartInput;
+	followUp?: ExternalJobFollowUpInput;
 	createdAt: number;
 	claimedAt?: number;
 }
@@ -72,32 +74,36 @@ function requestPath(asyncDir: string, id: string): string {
 	return path.join(requestDir(asyncDir), `${id}.json`);
 }
 
-function startClaimDir(asyncDir: string, id: string): string {
+function isDispatchOperation(operation: ExternalJobOperation): boolean {
+	return operation === "start" || operation === "follow-up";
+}
+
+function dispatchClaimDir(asyncDir: string, id: string): string {
 	return path.join(requestDir(asyncDir), `${id}.claim`);
 }
 
-function startClaimTempDir(asyncDir: string, id: string): string {
+function dispatchClaimTempDir(asyncDir: string, id: string): string {
 	return path.join(requestDir(asyncDir), `${id}.claim.tmp-${randomUUID()}`);
 }
 
-function startClaimCompletedPath(claimDir: string): string {
+function dispatchClaimCompletedPath(claimDir: string): string {
 	return path.join(claimDir, "completed.json");
 }
 
-function startClaimHandlePath(claimDir: string): string {
+function dispatchClaimHandlePath(claimDir: string): string {
 	return path.join(claimDir, "handle.json");
 }
 
-function completedStartClaimExists(asyncDir: string, id: string): boolean {
-	return fs.existsSync(startClaimCompletedPath(startClaimDir(asyncDir, id)));
+function completedDispatchClaimExists(asyncDir: string, id: string): boolean {
+	return fs.existsSync(dispatchClaimCompletedPath(dispatchClaimDir(asyncDir, id)));
 }
 
-function cancelStartRequest(asyncDir: string, request: ExternalJobBridgeRequest): boolean {
-	const claimDir = startClaimDir(asyncDir, request.id);
-	const tempClaimDir = startClaimTempDir(asyncDir, request.id);
+function cancelDispatchRequest(asyncDir: string, request: ExternalJobBridgeRequest): boolean {
+	const claimDir = dispatchClaimDir(asyncDir, request.id);
+	const tempClaimDir = dispatchClaimTempDir(asyncDir, request.id);
 	try {
 		fs.mkdirSync(tempClaimDir);
-		writeAtomicJson(startClaimCompletedPath(tempClaimDir), { completedAt: Date.now() });
+		writeAtomicJson(dispatchClaimCompletedPath(tempClaimDir), { completedAt: Date.now() });
 		fs.renameSync(tempClaimDir, claimDir);
 	} catch (error) {
 		fs.rmSync(tempClaimDir, { recursive: true, force: true });
@@ -190,12 +196,14 @@ function assertRequest(value: unknown, filePath: string): ExternalJobBridgeReque
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`External-job bridge request '${filePath}' must be an object.`);
 	const request = value as ExternalJobBridgeRequest;
 	if (typeof request.id !== "string" || !request.id) throw new Error(`External-job bridge request '${filePath}' has invalid id.`);
-	if (request.operation !== "start" && request.operation !== "status" && request.operation !== "result" && request.operation !== "reattach") throw new Error(`External-job bridge request '${filePath}' has invalid operation.`);
+	if (request.operation !== "start" && request.operation !== "follow-up" && request.operation !== "status" && request.operation !== "result" && request.operation !== "reattach") throw new Error(`External-job bridge request '${filePath}' has invalid operation.`);
 	if (typeof request.provider !== "string" || !request.provider.trim()) throw new Error(`External-job bridge request '${filePath}' has invalid provider.`);
 	if (typeof request.createdAt !== "number") throw new Error(`External-job bridge request '${filePath}' has invalid createdAt.`);
 	if (request.claimedAt !== undefined && typeof request.claimedAt !== "number") throw new Error(`External-job bridge request '${filePath}' has invalid claimedAt.`);
 	if (request.operation === "start") {
 		if (!request.start || typeof request.start !== "object" || Array.isArray(request.start)) throw new Error(`External-job bridge start request '${filePath}' is missing start input.`);
+	} else if (request.operation === "follow-up") {
+		if (!request.followUp || typeof request.followUp !== "object" || Array.isArray(request.followUp)) throw new Error(`External-job bridge follow-up request '${filePath}' is missing follow-up input.`);
 	} else if (typeof request.providerJobId !== "string" || !request.providerJobId.trim()) {
 		throw new Error(`External-job bridge ${request.operation} request '${filePath}' is missing providerJobId.`);
 	}
@@ -216,17 +224,25 @@ async function executeBridgeRequest(request: ExternalJobBridgeRequest, claimDir?
 		};
 	}
 	try {
-		const raw = request.operation === "start"
-			? await provider.start(request.start!)
-			: request.operation === "status"
+		let raw: ExternalJobHandle | ExternalJobResult;
+		if (request.operation === "start") {
+			raw = await provider.start(request.start!);
+		} else if (request.operation === "follow-up") {
+			if (typeof provider.followUp !== "function") {
+				throw new ExternalJobProviderError(`External-job provider '${request.provider}' does not support follow-up. Update or reload the provider package, then retry action='resume'.`, { code: "follow-up-unsupported" });
+			}
+			raw = await provider.followUp(request.followUp!);
+		} else {
+			raw = request.operation === "status"
 				? await provider.status(request.providerJobId!)
 				: request.operation === "reattach"
 					? await provider.reattach(request.providerJobId!)
 					: await provider.result(request.providerJobId!);
+		}
 		const result = request.operation === "result"
 			? validateExternalJobResult(provider.name, raw, "External-job bridge result")
 			: validateExternalJobHandle(provider.name, raw, "External-job bridge handle");
-		if (request.operation === "start" && claimDir) writeAtomicJson(startClaimHandlePath(claimDir), result);
+		if (isDispatchOperation(request.operation) && claimDir) writeAtomicJson(dispatchClaimHandlePath(claimDir), result);
 		return { id: request.id, ok: true, operation: request.operation, provider: request.provider, result, completedAt: Date.now() };
 	} catch (error) {
 		const details = bridgeError(error);
@@ -241,11 +257,11 @@ async function executeBridgeRequest(request: ExternalJobBridgeRequest, claimDir?
 	}
 }
 
-function claimStartRequest(asyncDir: string, filePath: string, request: ExternalJobBridgeRequest): { request: ExternalJobBridgeRequest; filePath: string } | undefined {
+function claimDispatchRequest(asyncDir: string, filePath: string, request: ExternalJobBridgeRequest): { request: ExternalJobBridgeRequest; filePath: string } | undefined {
 	const owner = currentClaimOwner();
 	const claimed: ExternalJobBridgeRequest = { ...request, claimedAt: owner.claimedAt };
-	const claimDir = startClaimDir(asyncDir, request.id);
-	const tempClaimDir = startClaimTempDir(asyncDir, request.id);
+	const claimDir = dispatchClaimDir(asyncDir, request.id);
+	const tempClaimDir = dispatchClaimTempDir(asyncDir, request.id);
 	try {
 		fs.mkdirSync(tempClaimDir);
 		writeAtomicJson(path.join(tempClaimDir, "owner.json"), owner);
@@ -287,7 +303,7 @@ function readClaimOwner(claimDir: string): ExternalJobClaimOwner | undefined {
 
 function readClaimHandle(provider: string, claimDir: string): ExternalJobHandle | undefined {
 	try {
-		return validateExternalJobHandle(provider, readJson(startClaimHandlePath(claimDir)), "External-job bridge recovered start handle");
+		return validateExternalJobHandle(provider, readJson(dispatchClaimHandlePath(claimDir)), "External-job bridge recovered dispatch handle");
 	} catch {
 		return undefined;
 	}
@@ -297,7 +313,7 @@ export function serviceExternalJobBridgeRequests(asyncDir: string): void {
 	let files: string[];
 	try {
 		files = fs.readdirSync(requestDir(asyncDir), { withFileTypes: true })
-			.filter((entry) => (entry.isFile() && entry.name.endsWith(".json") && !completedStartClaimExists(asyncDir, entry.name.replace(/\.json$/, ""))) || (entry.isDirectory() && entry.name.endsWith(".claim") && !fs.existsSync(startClaimCompletedPath(path.join(requestDir(asyncDir), entry.name)))))
+			.filter((entry) => (entry.isFile() && entry.name.endsWith(".json") && !completedDispatchClaimExists(asyncDir, entry.name.replace(/\.json$/, ""))) || (entry.isDirectory() && entry.name.endsWith(".claim") && !fs.existsSync(dispatchClaimCompletedPath(path.join(requestDir(asyncDir), entry.name)))))
 			.map((entry) => entry.name)
 			.slice(0, MAX_REQUESTS_PER_SWEEP);
 	} catch (error) {
@@ -313,7 +329,7 @@ export function serviceExternalJobBridgeRequests(asyncDir: string): void {
 export function serviceExternalJobBridgeRequestFile(asyncDir: string, file: string): void {
 	fs.mkdirSync(responseDir(asyncDir), { recursive: true });
 	if (file.endsWith(".claim")) {
-		serviceExternalJobStartClaim(asyncDir, file);
+		serviceExternalJobDispatchClaim(asyncDir, file);
 		return;
 	}
 	const filePath = path.join(requestDir(asyncDir), file);
@@ -335,20 +351,20 @@ export function serviceExternalJobBridgeRequestFile(asyncDir: string, file: stri
 		fs.rmSync(filePath, { force: true });
 		return;
 	}
-	if (request.operation === "start" && completedStartClaimExists(asyncDir, request.id)) {
+	if (isDispatchOperation(request.operation) && completedDispatchClaimExists(asyncDir, request.id)) {
 		fs.rmSync(filePath, { force: true });
 		return;
 	}
 	if (inFlight.has(request.id) || fs.existsSync(responsePath(asyncDir, request.id))) return;
-	if (request.operation === "start" && request.claimedAt !== undefined) return;
-	const claimed = request.operation === "start" ? claimStartRequest(asyncDir, filePath, request) : { request, filePath };
+	if (isDispatchOperation(request.operation) && request.claimedAt !== undefined) return;
+	const claimed = isDispatchOperation(request.operation) ? claimDispatchRequest(asyncDir, filePath, request) : { request, filePath };
 	if (!claimed) return;
 	const claimedRequest = claimed.request;
 	inFlight.add(claimedRequest.id);
-	void executeBridgeRequest(claimedRequest, claimedRequest.operation === "start" ? claimed.filePath : undefined).then((response) => {
+	void executeBridgeRequest(claimedRequest, isDispatchOperation(claimedRequest.operation) ? claimed.filePath : undefined).then((response) => {
 		writeAtomicJson(responsePath(asyncDir, claimedRequest.id), response);
-		if (claimedRequest.operation === "start") {
-			writeAtomicJson(startClaimCompletedPath(claimed.filePath), { completedAt: Date.now() });
+		if (isDispatchOperation(claimedRequest.operation)) {
+			writeAtomicJson(dispatchClaimCompletedPath(claimed.filePath), { completedAt: Date.now() });
 		} else {
 			fs.rmSync(claimed.filePath, { recursive: true, force: true });
 		}
@@ -362,15 +378,15 @@ export function serviceExternalJobBridgeRequestFile(asyncDir: string, file: stri
 			message: error instanceof Error ? error.message : String(error),
 			completedAt: Date.now(),
 		} satisfies ExternalJobBridgeResponse);
-		if (claimedRequest.operation === "start") writeAtomicJson(startClaimCompletedPath(claimed.filePath), { completedAt: Date.now() });
+		if (isDispatchOperation(claimedRequest.operation)) writeAtomicJson(dispatchClaimCompletedPath(claimed.filePath), { completedAt: Date.now() });
 	}).finally(() => {
 		inFlight.delete(claimedRequest.id);
 	});
 }
 
-function serviceExternalJobStartClaim(asyncDir: string, file: string): void {
+function serviceExternalJobDispatchClaim(asyncDir: string, file: string): void {
 	const claimDir = path.join(requestDir(asyncDir), file);
-	if (fs.existsSync(startClaimCompletedPath(claimDir))) return;
+	if (fs.existsSync(dispatchClaimCompletedPath(claimDir))) return;
 	const owner = readClaimOwner(claimDir);
 	if (!owner && fs.existsSync(requestPath(asyncDir, file.replace(/\.claim$/, ""))) && !fs.existsSync(responsePath(asyncDir, file.replace(/\.claim$/, "")))) {
 		fs.rmSync(claimDir, { recursive: true, force: true });
@@ -383,7 +399,7 @@ function serviceExternalJobStartClaim(asyncDir: string, file: string): void {
 	} catch {
 		return;
 	}
-	if (request.operation !== "start" || fs.existsSync(responsePath(asyncDir, request.id))) return;
+	if (!isDispatchOperation(request.operation) || fs.existsSync(responsePath(asyncDir, request.id))) return;
 	const handle = readClaimHandle(request.provider, claimDir);
 	if (handle) {
 		writeAtomicJson(responsePath(asyncDir, request.id), {
@@ -394,7 +410,7 @@ function serviceExternalJobStartClaim(asyncDir: string, file: string): void {
 			result: handle,
 			completedAt: Date.now(),
 		} satisfies ExternalJobBridgeResponse);
-		writeAtomicJson(startClaimCompletedPath(claimDir), { completedAt: Date.now() });
+		writeAtomicJson(dispatchClaimCompletedPath(claimDir), { completedAt: Date.now() });
 		fs.rmSync(requestPath(asyncDir, request.id), { force: true });
 		return;
 	}
@@ -403,8 +419,8 @@ function serviceExternalJobStartClaim(asyncDir: string, file: string): void {
 		ok: false,
 		operation: request.operation,
 		provider: request.provider,
-		code: "start-dispatch-abandoned",
-		message: `External-job start for provider '${request.provider}' was claimed by a host process that is no longer alive before a provider job id was committed. Refusing to redispatch the prompt automatically.`,
+		code: `${request.operation}-dispatch-abandoned`,
+		message: `External-job ${request.operation} for provider '${request.provider}' was claimed by a host process that is no longer alive before a provider job id was committed. Refusing to redispatch the prompt automatically.`,
 		completedAt: Date.now(),
 	} satisfies ExternalJobBridgeResponse);
 	fs.rmSync(claimDir, { recursive: true, force: true });
@@ -417,16 +433,16 @@ export async function requestExternalJobOperation<T extends ExternalJobHandle |
 	fs.mkdirSync(responseDir(asyncDir), { recursive: true });
 	const bridgeRequest = { ...request, id, createdAt: Date.now() } satisfies ExternalJobBridgeRequest;
 	writeAtomicJson(requestPath(asyncDir, id), bridgeRequest);
-	const deadline = request.operation === "start" ? undefined : Date.now() + timeoutMs;
+	const deadline = isDispatchOperation(request.operation) ? undefined : Date.now() + timeoutMs;
 	const outPath = responsePath(asyncDir, id);
 	while (!fs.existsSync(outPath)) {
 		const canceled = cancel?.();
 		if (canceled) {
-			if (request.operation === "start" && !cancelStartRequest(asyncDir, bridgeRequest)) {
+			if (isDispatchOperation(request.operation) && !cancelDispatchRequest(asyncDir, bridgeRequest)) {
 				await sleep(POLL_INTERVAL_MS);
 				continue;
 			}
-			if (request.operation !== "start") fs.rmSync(requestPath(asyncDir, id), { force: true });
+			if (!isDispatchOperation(request.operation)) fs.rmSync(requestPath(asyncDir, id), { force: true });
 			throw canceled;
 		}
 		if (deadline !== undefined && Date.now() >= deadline) {

package/src/runs/shared/external-job-runner.ts

@@ -20,6 +20,31 @@ export function externalJobPromptDigest(prompt: string): string {
 	return createHash("sha256").update(prompt).digest("hex");
 }
 
+export function externalJobStableJson(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(externalJobStableJson).join(",")}]`;
+	const record = value as Record<string, unknown>;
+	return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${externalJobStableJson(record[key])}`).join(",")}}`;
+}
+
+export function externalJobFollowUpRequestDigest(input: { provider: string; parentProviderJobId: string; promptDigest: string; options: Record<string, unknown> }): string {
+	return createHash("sha256")
+		.update(externalJobStableJson({ provider: input.provider, parentProviderJobId: input.parentProviderJobId, promptDigest: input.promptDigest, options: input.options }))
+		.digest("hex");
+}
+
+export function externalJobFollowUpRequestId(requestDigest: string): string {
+	return `follow-up-${requestDigest.slice(0, 48)}`;
+}
+
+export function externalJobFollowUpRunId(requestDigest: string): string {
+	const hex = requestDigest.padEnd(32, "0").slice(0, 32).split("");
+	hex[12] = "4";
+	hex[16] = ((Number.parseInt(hex[16]!, 16) & 0x3) | 0x8).toString(16);
+	const value = hex.join("");
+	return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20, 32)}`;
+}
+
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -70,11 +95,29 @@ function parseExternalJobStatus(value: unknown, statusPath: string): ExternalJob
 	if (failureCode !== undefined && typeof failureCode !== "string") throw malformedStatus(statusPath);
 	if (failureMessage !== undefined && typeof failureMessage !== "string") throw malformedStatus(statusPath);
 	if (blockingJobId !== undefined && typeof blockingJobId !== "string") throw malformedStatus(statusPath);
+	const operation = value.operation;
+	const sourceRunId = value.sourceRunId;
+	const sourceStepIndex = value.sourceStepIndex;
+	const parentProviderJobId = value.parentProviderJobId;
+	const requestId = value.requestId;
+	const requestDigest = value.requestDigest;
+	if (operation !== undefined && operation !== "start" && operation !== "follow-up") throw malformedStatus(statusPath);
+	if (sourceRunId !== undefined && (typeof sourceRunId !== "string" || sourceRunId.length === 0)) throw malformedStatus(statusPath);
+	if (sourceStepIndex !== undefined && (typeof sourceStepIndex !== "number" || !Number.isInteger(sourceStepIndex) || sourceStepIndex < 0)) throw malformedStatus(statusPath);
+	if (parentProviderJobId !== undefined && (typeof parentProviderJobId !== "string" || parentProviderJobId.length === 0)) throw malformedStatus(statusPath);
+	if (requestId !== undefined && (typeof requestId !== "string" || requestId.length === 0)) throw malformedStatus(statusPath);
+	if (requestDigest !== undefined && (typeof requestDigest !== "string" || requestDigest.length === 0)) throw malformedStatus(statusPath);
 	if (startedAt !== undefined && typeof startedAt !== "number") throw malformedStatus(statusPath);
 	if (updatedAt !== undefined && typeof updatedAt !== "number") throw malformedStatus(statusPath);
 	return {
 		provider,
 		promptDigest,
+		...(operation ? { operation } : {}),
+		...(sourceRunId ? { sourceRunId } : {}),
+		...(sourceStepIndex !== undefined ? { sourceStepIndex } : {}),
+		...(parentProviderJobId ? { parentProviderJobId } : {}),
+		...(requestId ? { requestId } : {}),
+		...(requestDigest ? { requestDigest } : {}),
 		options: value.options ?? {},
 		state,
 		...(providerJobId ? { providerJobId } : {}),
@@ -111,10 +154,30 @@ function readExistingExternalJob(asyncDir: string, stepIndex: number): ExternalJ
 	return parseExternalJobStatus(step.externalJob, statusPath);
 }
 
+function externalJobLineage(followUp: ExternalJobFollowUpDescriptor | undefined, previous: ExternalJobStatus | undefined) {
+	return {
+		operation: followUp ? "follow-up" as const : previous?.operation,
+		...(followUp ? {
+			sourceRunId: followUp.sourceRunId,
+			sourceStepIndex: followUp.sourceStepIndex,
+			parentProviderJobId: followUp.parentProviderJobId,
+			requestId: followUp.requestId,
+			requestDigest: followUp.requestDigest,
+		} : {
+			...(previous?.sourceRunId ? { sourceRunId: previous.sourceRunId } : {}),
+			...(previous?.sourceStepIndex !== undefined ? { sourceStepIndex: previous.sourceStepIndex } : {}),
+			...(previous?.parentProviderJobId ? { parentProviderJobId: previous.parentProviderJobId } : {}),
+			...(previous?.requestId ? { requestId: previous.requestId } : {}),
+			...(previous?.requestDigest ? { requestDigest: previous.requestDigest } : {}),
+		}),
+	};
+}
+
 function statusFromHandle(input: {
 	provider: string;
 	promptDigest: string;
 	options: Record<string, unknown>;
+	followUp?: ExternalJobFollowUpDescriptor;
 	startedAt?: number;
 	previous?: ExternalJobStatus;
 	handle: ExternalJobHandle;
@@ -124,6 +187,7 @@ function statusFromHandle(input: {
 		provider: input.provider,
 		providerJobId: input.handle.providerJobId,
 		promptDigest: input.promptDigest,
+		...externalJobLineage(input.followUp, input.previous),
 		options: input.options,
 		handleUrl: input.handle.handleUrl ?? input.previous?.handleUrl,
 		conversationUrl: input.handle.conversationUrl ?? input.previous?.conversationUrl,
@@ -141,6 +205,7 @@ function failureStatus(input: {
 	provider: string;
 	promptDigest: string;
 	options: Record<string, unknown>;
+	followUp?: ExternalJobFollowUpDescriptor;
 	previous?: ExternalJobStatus;
 	code: string;
 	message: string;
@@ -150,6 +215,7 @@ function failureStatus(input: {
 		provider: input.provider,
 		providerJobId: input.previous?.providerJobId,
 		promptDigest: input.promptDigest,
+		...externalJobLineage(input.followUp, input.previous),
 		options: input.options,
 		handleUrl: input.previous?.handleUrl,
 		conversationUrl: input.previous?.conversationUrl,
@@ -176,6 +242,24 @@ function blocksStartRedispatch(status: ExternalJobStatus, provider: string, prom
 		&& status.failureCode !== "provider-unavailable";
 }
 
+interface ExternalJobFollowUpDescriptor {
+	sourceRunId: string;
+	sourceStepIndex: number;
+	parentProviderJobId: string;
+	requestId: string;
+	requestDigest: string;
+}
+
+function sameFollowUpLineage(status: ExternalJobStatus, followUp: ExternalJobFollowUpDescriptor | undefined): boolean {
+	if (!followUp) return status.operation !== "follow-up";
+	return status.operation === "follow-up"
+		&& status.sourceRunId === followUp.sourceRunId
+		&& status.sourceStepIndex === followUp.sourceStepIndex
+		&& status.parentProviderJobId === followUp.parentProviderJobId
+		&& status.requestId === followUp.requestId
+		&& status.requestDigest === followUp.requestDigest;
+}
+
 export async function runExternalJob(input: {
 	provider: string;
 	options?: Record<string, unknown>;
@@ -191,6 +275,7 @@ export async function runExternalJob(input: {
 	timeoutMessage?: string;
 	stopMessage?: string;
 	onExternalJob?: (status: ExternalJobStatus) => void;
+	followUp?: ExternalJobFollowUpDescriptor;
 }): Promise<ExternalJobRunResult> {
 	const provider = input.provider;
 	const options = input.options ?? {};
@@ -218,37 +303,55 @@ export async function runExternalJob(input: {
 		current = readExistingExternalJob(input.asyncDir, input.stepIndex);
 		let handle: ExternalJobHandle;
 		if (current?.providerJobId) {
-			if (current.provider !== provider || current.promptDigest !== promptDigest) {
-				const message = `Existing external job '${current.providerJobId}' does not match provider or prompt digest. Refusing to redispatch prompt.`;
-				const status = failureStatus({ provider, promptDigest, options, previous: current, code: "recovery-mismatch", message });
+			if (current.provider !== provider || current.promptDigest !== promptDigest || !sameFollowUpLineage(current, input.followUp)) {
+				const message = `Existing external job '${current.providerJobId}' does not match provider, prompt digest, or follow-up lineage. Refusing to redispatch prompt.`;
+				const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: "recovery-mismatch", message });
 				publish(status);
 				return { output: message, exitCode: 1, error: message, externalJob: status };
 			}
 			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "reattach", provider, providerJobId: current.providerJobId });
 		} else {
 			if (current && blocksStartRedispatch(current, provider, promptDigest)) {
-				const message = `External-job start for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
-				const status = failureStatus({ provider, promptDigest, options, previous: current, code: "start-redispatch-blocked", message });
+				const message = `External-job ${input.followUp ? "follow-up" : "start"} for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
+				const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: input.followUp ? "dispatch-redispatch-blocked" : "start-redispatch-blocked", message });
 				publish(status);
 				return { output: message, exitCode: 1, error: message, externalJob: status };
 			}
-			publish({ provider, promptDigest, options, state: "queued", startedAt, updatedAt: Date.now() });
+			publish({ provider, promptDigest, ...(input.followUp ? { operation: "follow-up" as const, ...input.followUp } : {}), options, state: "queued", startedAt, updatedAt: Date.now() });
+			if (input.followUp) {
 				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
-				operation: "start",
-				provider,
-				start: {
-					prompt: input.prompt,
-					promptDigest,
-					cwd: input.cwd,
-					runId: input.runId,
-					stepIndex: input.stepIndex,
-					agent: input.agent,
-					options,
-					...(input.sessionId ? { sessionId: input.sessionId } : {}),
-				},
-			}, undefined, localCancellation);
+					operation: "follow-up",
+					provider,
+					followUp: {
+						prompt: input.prompt,
+						promptDigest,
+						cwd: input.cwd,
+						runId: input.runId,
+						stepIndex: input.stepIndex,
+						agent: input.agent,
+						options,
+						...(input.sessionId ? { sessionId: input.sessionId } : {}),
+						...input.followUp,
+					},
+				}, undefined, localCancellation);
+			} else {
+				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
+					operation: "start",
+					provider,
+					start: {
+						prompt: input.prompt,
+						promptDigest,
+						cwd: input.cwd,
+						runId: input.runId,
+						stepIndex: input.stepIndex,
+						agent: input.agent,
+						options,
+						...(input.sessionId ? { sessionId: input.sessionId } : {}),
+					},
+				}, undefined, localCancellation);
+			}
 		}
-		publish(statusFromHandle({ provider, promptDigest, options, startedAt, previous: current, handle }));
+		publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, startedAt, previous: current, handle }));
 		while (!terminal(handle.state)) {
 			if (timedOut || stopped) {
 				const message = stopped
@@ -258,7 +361,7 @@ export async function runExternalJob(input: {
 			}
 			await sleep(STATUS_POLL_INTERVAL_MS);
 			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "status", provider, providerJobId: handle.providerJobId });
-			publish(statusFromHandle({ provider, promptDigest, options, previous: current, handle }));
+			publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle }));
 		}
 		const result = await requestExternalJobOperation<ExternalJobResult>(input.asyncDir, { operation: "result", provider, providerJobId: handle.providerJobId });
 		let artifactPath = result.artifactPath;
@@ -266,7 +369,7 @@ export async function runExternalJob(input: {
 			artifactPath = path.join(input.asyncDir, `external-job-${input.stepIndex}.result.md`);
 			fs.writeFileSync(artifactPath, result.output, "utf-8");
 		}
-		const finalStatus = statusFromHandle({ provider, promptDigest, options, previous: current, handle: result, resultArtifactPath: artifactPath });
+		const finalStatus = statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle: result, resultArtifactPath: artifactPath });
 		publish(finalStatus);
 		const output = resultOutput(result, artifactPath);
 		const error = result.state === "completed" ? undefined : result.failureMessage ?? `External job ${result.state}.`;
@@ -276,7 +379,7 @@ export async function runExternalJob(input: {
 			? error
 			: new ExternalJobProviderError(error instanceof Error ? error.message : String(error), { code: "provider-error", cause: error });
 		const message = formatError(providerError, provider);
-		const status = failureStatus({ provider, promptDigest, options, previous: current, code: providerError.code, message, ...(providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {}) });
+		const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: providerError.code, message, ...(providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {}) });
 		publish(status);
 		return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: status };
 	} finally {