immune-brain 5.2.0 → 5.5.1

package/plugins/immune-brain/runtime/claude/mcp_server.ts

@@ -1,4 +1,8 @@
 import { randomUUID } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readActiveClaimTaskId } from "../unattended/batch_preflight";
+import { isTerminalBatchState, readAnyBatchRunState } from "../unattended/batch_state";
 import { createInterface } from "node:readline";
 import { stdin, stdout } from "node:process";
 import type { Readable, Writable } from "node:stream";
@@ -13,11 +17,14 @@ import {
 } from "./interaction";
 import { ClaudeReviewHost, FileHookEventLog, parseHookStdin } from "./review_host";
 import { activeTaskHookOutput, consumePhaseAdmission, laneGuardHookOutput, phaseEntryGateHookOutput, recordPhaseEntryPrompt, type GatedTool } from "./lane_guard";
+import { readRunToolSession, runContinuationHookOutput } from "./run_continuation";
 import { ClaudeRuntime, type ToolMeta } from "./kernel_ports";
 import { parseLaneInstruction, parseLaneOffers, parseMaxParallel, resolveLaneParallel } from "../unattended/batch_lanes";
 import { parseFinalVerification } from "../unattended/batch_final_verification";
+import { consolidationSchema, parseDeliveryConsolidation } from "../unattended/parent_delivery_consolidation";
 import { parseLaneRevision, REVISION_DELEGATION_TEXT } from "../unattended/batch_delegation";
 import type { AssuranceCoordinatorPorts } from "../assurance/coordinator";
+import { parseReworkChoice, reworkExitLines, type ReworkChoice } from "../kernel/assurance_projection";
 
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
 
@@ -59,6 +66,7 @@ export function listMcpTools() {
 											additionalProperties: false,
 										},
 									},
+									delivery_consolidation: consolidationSchema,
 									final_verification: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
 									lane_instruction: {
 										type: "object",
@@ -148,8 +156,12 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 	// The phase entry gate, before any preparation or native dialog. The hook
 	// decided on the session's literal entry; no admission for this exact call
 	// means no hook saw it, which refuses.
+	let hookSessionId: string | null = null;
 	const requireRunEntry = (operation: GatedTool, toolCallId: string) => {
-		if (consumeAdmission(toolCallId, operation)) return;
+		const correlated = readRunToolSession(toolCallId, operation, options.cwd ?? process.cwd());
+		if (!options.consumePhaseAdmission && !correlated)
+			throw new NativeAuthorityError("run_entry_required", "Enrollment needs exact Hook session and workspace correlation");
+		if (consumeAdmission(toolCallId, operation)) { hookSessionId = correlated ?? hookSessionId; return; }
 		throw new NativeAuthorityError("run_entry_required", `${operation} needs a literal-user imm-run entry in this session`);
 	};
 	return {
@@ -167,6 +179,8 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 		},
 		sessionInteractive: () => negotiatedInteractive,
 		async callTool(name: string, args: Record<string, unknown>, meta: Partial<ToolMeta> = {}) {
+			const observedSession = readRunToolSession(meta.toolCallId ?? `call-${name}`, name, options.cwd ?? process.cwd());
+			if (observedSession) hookSessionId = observedSession;
 			if (name === "start_unattended_batch") {
 				const initiativeSlug = String(args.initiative_slug ?? "");
 				if (!initiativeSlug) throw new Error("initiative_slug is required");
@@ -179,7 +193,7 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				if (!probe.ok) throw new NativeAuthorityError("unsupported_host", probe.reason);
 				requireRunEntry(name, meta.toolCallId ?? `call-${name}`);
 				const toolMeta: ToolMeta = {
-					sessionId: meta.sessionId ?? connectionId,
+					sessionId: hookSessionId ?? meta.sessionId ?? connectionId,
 					toolCallId: meta.toolCallId ?? `call-${name}`,
 					taskId: initiativeSlug,
 					initiativeSlug,
@@ -192,10 +206,12 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				const laneRevision = parseLaneRevision(args.lane_revision);
 				const maxParallel = resolveLaneParallel(options.cwd ?? process.cwd(), initiativeSlug, parseMaxParallel(args.max_parallel), laneOffers, laneInstruction ?? laneRevision);
 				const finalVerification = parseFinalVerification(args.final_verification);
+				const deliveryConsolidation = parseDeliveryConsolidation(args.delivery_consolidation);
 				return runtime.startUnattendedBatch(initiativeSlug, toolMeta, {
 					...(maxParallel !== undefined ? { max_parallel: maxParallel } : {}),
 					...(laneOffers !== undefined ? { lane_offers: laneOffers } : {}),
 					...(finalVerification !== undefined ? { final_verification: finalVerification } : {}),
+					...(deliveryConsolidation !== undefined ? { delivery_consolidation: deliveryConsolidation } : {}),
 					...(laneInstruction !== undefined ? { lane_instruction: laneInstruction } : {}),
 					...(laneRevision !== undefined ? { lane_revision: laneRevision } : {}),
 				});
@@ -211,7 +227,7 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				const probe = probeHost(options.env ?? process.env, process.platform, negotiatedVersion);
 				if (!probe.ok) throw new NativeAuthorityError("unsupported_host", probe.reason);
 				const toolMeta: ToolMeta = {
-					sessionId: meta.sessionId ?? connectionId,
+					sessionId: hookSessionId ?? meta.sessionId ?? connectionId,
 					toolCallId: meta.toolCallId ?? `call-${name}`,
 					taskId: initiativeSlug,
 					initiativeSlug,
@@ -238,7 +254,7 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 			const probe = probeHost(options.env ?? process.env, process.platform, negotiatedVersion);
 			if (!probe.ok) throw new NativeAuthorityError("unsupported_host", probe.reason);
 			const toolMeta: ToolMeta = {
-				sessionId: meta.sessionId ?? connectionId,
+				sessionId: hookSessionId ?? meta.sessionId ?? connectionId,
 				toolCallId: meta.toolCallId ?? `call-${name}`,
 				taskId,
 				interactive: meta.interactive ?? options.interactive ?? negotiatedInteractive,
@@ -462,7 +478,7 @@ export function elicitationParams(input: NativeConfirmationInput) {
 				? `Children (${d.children.length}):\n${d.children
 						.map(
 							(child) =>
-								`  - ${child.task_id} (${child.slice_id}) [state: ${child.state}]${child.commit ? ` [commit: ${child.commit}]` : " [no commit]"}${child.lane_branch ? ` [lane: ${child.lane_branch}]` : ""}`,
+								`  - ${child.task_id} (${child.slice_id}) [state: ${child.state}]${child.commit ? ` [commit: ${child.commit}]` : " [no commit]"}${child.lane_branch ? ` [lane: ${child.lane_branch}]` : ""}${child.kernel_lifecycle ? ` [Kernel run: ${child.kernel_lifecycle}]` : ""}`,
 						)
 						.join("\n")}`
 				: null,
@@ -478,6 +494,24 @@ export function elicitationParams(input: NativeConfirmationInput) {
 	}
 	if (input.operation === "start_unattended_batch") {
 		const b = input.batchDetails;
+		if (b?.parent_final_verification) {
+			const lines = [
+				`Operation: start_unattended_batch (native Parent final verification; no batch run is started)`,
+				`Initiative: ${input.initiativeSlug ?? b.initiative_slug}`,
+				input.planDigest ? `Plan digest: ${input.planDigest}` : null,
+				`Parent Tasks (${b.children.length}):\n${b.children.map((c) => `  - ${c.task_id} (${c.slice_id})`).join("\n")}`,
+				b.parent_final_verification.integrate_task_ids.length > 0
+					? `Settled deliveries committed first (${b.parent_final_verification.integrate_task_ids.length}):\n${b.parent_final_verification.integrate_task_ids.map((id) => `  - ${id}`).join("\n")}`
+					: null,
+				b.parent_final_verification.delivery_consolidation ? `Explicit reviewed delivery consolidation:\n${JSON.stringify(b.parent_final_verification.delivery_consolidation, null, 2)}` : null,
+				`Final verification commands run in this workspace outside Host permission:\n${(b.final_verification ?? []).map((command) => `  - ${command}`).join("\n")}`,
+			].filter(Boolean);
+			return {
+				mode: "form",
+				message: `Authorize this Parent final verification for ${input.initiativeSlug}?\n\n${lines.join("\n")}`,
+				requestedSchema: { type: "object", properties: {} },
+			};
+		}
 		const details = [
 			`Operation: start_unattended_batch`,
 			`Initiative: ${input.initiativeSlug ?? b?.initiative_slug}`,
@@ -489,7 +523,7 @@ export function elicitationParams(input: NativeConfirmationInput) {
 			b?.lane_mode ? `Lane mode: max_parallel=${b.lane_mode.max_parallel}` : null,
 			b?.lane_mode ? `Parallel groups (${b.lane_mode.parallel_groups.length}):\n${b.lane_mode.parallel_groups.map((group) => `  - ${group.join(", ")}`).join("\n")}` : null,
 			b?.lane_mode && b.lane_mode.serialized.length > 0 ? `Serialized by overlapping scope (${b.lane_mode.serialized.length}):\n${b.lane_mode.serialized.map((c) => `  - ${c.task_id} after ${c.overlaps_with.join(", ")}`).join("\n")}` : null,
-			b?.lane_mode?.final_verification ? `Final verification: ${b.lane_mode.final_verification.join("; ")}` : null,
+			b?.final_verification ? `Final verification: ${b.final_verification.join("; ")}` : null,
 			b?.lane_mode?.offer_revision_delegation ? REVISION_DELEGATION_TEXT : null,
 		].filter(Boolean);
 		return {
@@ -510,6 +544,41 @@ export function elicitationParams(input: NativeConfirmationInput) {
 				: { type: "object", properties: {} },
 		};
 	}
+	if (input.reworkExits) {
+		const exits = input.reworkExits;
+		const exitValues = [
+			"grant_rounds",
+			...(exits.accept_residual_risk ? ["accept_residual_risk"] : []),
+			"replan",
+		];
+		return {
+			mode: "form",
+			message: `Choose how to resolve this replan boundary for ${input.taskId}.\n\n${[
+				`Operation: ${input.operation}`,
+				`Task: ${input.taskId}`,
+				input.risk ? `Risk: ${input.risk}` : null,
+				input.bindingDigest ? `Binding digest: ${input.bindingDigest}` : null,
+				...reworkExitLines(exits),
+			].filter(Boolean).join("\n")}`,
+			requestedSchema: {
+				type: "object",
+				properties: {
+					exit: { type: "string", title: "Exit", enum: exitValues, default: "grant_rounds" },
+					rounds: {
+						type: "integer",
+						title: "Further Review rounds (grant_rounds)",
+						minimum: exits.grant_rounds.min,
+						maximum: exits.grant_rounds.max,
+						default: exits.grant_rounds.min,
+					},
+					...(exits.accept_residual_risk
+						? { reason: { type: "string", title: "Reason for accepting residual risk (accept_residual_risk)" } }
+						: {}),
+				},
+				required: ["exit"],
+			},
+		};
+	}
 	const details = [
 		`Operation: ${input.operation}`,
 		`Task: ${input.taskId}`,
@@ -586,7 +655,14 @@ export async function serveStdio(options: {
 				throw new NativeAuthorityError("correlation_missing", "MCP elicitation returned an invalid action");
 			}
 			let delegateRevisions = false;
-			if (action === "accept") {
+			let reworkChoice: ReworkChoice | undefined;
+			if (action === "accept" && input.reworkExits) {
+				const parsed = parseReworkChoice(input.reworkExits, (result as { content?: unknown }).content);
+				if (!parsed) {
+					throw new NativeAuthorityError("correlation_missing", "MCP elicitation accept content did not match the requested exit schema");
+				}
+				reworkChoice = parsed;
+			} else if (action === "accept") {
 				const content = (result as { content?: unknown }).content;
 				const offered = input.operation === "start_unattended_batch" && input.batchDetails?.lane_mode?.offer_revision_delegation === true;
 				const keys = typeof content === "object" && content !== null && !Array.isArray(content) ? Object.keys(content) : null;
@@ -597,7 +673,12 @@ export async function serveStdio(options: {
 				}
 				delegateRevisions = offered && (content as Record<string, unknown>).delegate_in_lane_revisions === true;
 			}
-			return { decision: action, requestId, ...(delegateRevisions ? { delegateRevisions: true } : {}) };
+			return {
+				decision: action,
+				requestId,
+				...(delegateRevisions ? { delegateRevisions: true } : {}),
+				...(reworkChoice ? { reworkChoice } : {}),
+			};
 		} finally {
 			pending.delete(requestId);
 			if (abortListener) input.signal?.removeEventListener("abort", abortListener);
@@ -754,18 +835,33 @@ async function runHook(): Promise<void> {
 	let payload: Record<string, unknown> | null = null;
 	try { payload = JSON.parse(raw) as Record<string, unknown>; } catch { payload = null; }
 	if (payload?.hook_event_name === "PreToolUse") {
-		const decision = laneGuardHookOutput(payload) ?? phaseEntryGateHookOutput(payload);
+		const decision = laneGuardHookOutput(payload) ?? phaseEntryGateHookOutput(payload) ?? await runContinuationHookOutput(payload);
 		if (decision) process.stdout.write(`${decision}\n`);
 		return;
 	}
 	if (payload?.hook_event_name === "UserPromptSubmit") {
 		recordPhaseEntryPrompt(payload);
+		await runContinuationHookOutput(payload);
 		const notice = await activeTaskHookOutput(payload);
 		if (notice) process.stdout.write(`${notice}\n`);
 		return;
 	}
+	if (payload) {
+		const continuation = await runContinuationHookOutput(payload);
+		if (continuation) process.stdout.write(`${continuation}\n`);
+	}
 	const event = parseHookStdin(raw);
 	if (!event) return;
+	const cwd = typeof payload?.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+	if (!readActiveClaimTaskId(cwd)) {
+		const batchesDir = join(cwd, ".imm", "state", "batches");
+		const activeBatch = existsSync(batchesDir) && readdirSync(batchesDir).some((file) => {
+			if (!file.endsWith(".json") || file.endsWith(".report.json")) return false;
+			const batch = readAnyBatchRunState(cwd, file.slice(0, -5));
+			return batch !== null && !isTerminalBatchState(batch.batch_state);
+		});
+		if (!activeBatch) return;
+	}
 	new FileHookEventLog().append(event);
 }
 

package/plugins/immune-brain/runtime/claude/run_continuation.ts

@@ -0,0 +1,274 @@
+import { existsSync, realpathSync, lstatSync, rmSync, renameSync, openSync, fstatSync, readSync, closeSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { projectTaskStatus } from "../assurance/coordinator";
+import { readTaskRecordRaw } from "../kernel/storage";
+import { recordParentRepair } from "../unattended/batch_git";
+import { readAnyBatchRunState } from "../unattended/batch_state";
+import { bindRun, decideRunContinuation, observeParentRun, parkFailedCriticalGate, releasesRunBinding, scopedSourceDigest,
+	type RunContinuationState, type ReviewContinuationState } from "../assurance/run_continuation";
+import { digestOfReviewerBytes } from "../assurance/review_mediation";
+import { recognizePhaseEntry } from "../assurance/phase_entry";
+import { homedir } from "node:os";
+import { readPhaseEntryState, claudeAliasReader } from "./lane_guard";
+import { appendPrivate, cacheDir, ensurePrivateDir, ownedByUs, readPrivate, sessionHash } from "./review_host";
+
+const MCP_TOOL = /^mcp__.*immune-brain.*__(\w+)$/;
+const NATIVE_OPERATIONS = new Set(["enroll", "start_unattended_batch", "request_authorization", "approve_breaking_intent_revision", "stop"]);
+const MAX_METADATA_BYTES = 256 * 1024;
+interface Correlation { session_id: string; workspace: string; tool_use_id: string; operation: string; task_id: string | null }
+interface ContinuationMetadata {
+	state: RunContinuationState | null;
+	sequence: number;
+	review: ReviewContinuationState;
+	reviewer_prompt: string | null;
+	reviewer_call_id: string | null;
+	reviewer_agent_id: string | null;
+	recovery_action: string | null;
+	paused: string | null;
+	stop_blocks: number;
+}
+const blank = (): ContinuationMetadata => ({ state: null, sequence: 0, review: "unobserved", reviewer_prompt: null,
+	reviewer_call_id: null, reviewer_agent_id: null, recovery_action: null, paused: null, stop_blocks: 0 });
+const statePath = (sessionId: string, root: string) => join(cacheDir(root), `${sessionHash(sessionId)}.continuation`);
+const callPath = (toolId: string, root: string) => join(cacheDir(root), `${sessionHash(toolId)}.continuation-call`);
+function drop(path: string, root: string): void {
+	// Nothing to drop means no cache directory either: an idle session must leave the store untouched.
+	if (!existsSync(path)) return;
+	if (!ensurePrivateDir(cacheDir(root))) return;
+	try { const stat = lstatSync(path); if (stat.isFile() && ownedByUs(stat)) rmSync(path); } catch { /* absent */ }
+}
+function readLast(path: string): unknown {
+	let stat;
+	try { stat = lstatSync(path); } catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+	if (!stat.isFile() || !ownedByUs(stat)) throw new Error("unsafe continuation metadata");
+	const text = readPrivate(path, MAX_METADATA_BYTES);
+	if (text === undefined) throw new Error("continuation metadata could not be read");
+	const lines = text.trim().split("\n");
+	return JSON.parse(lines.at(-1) ?? "null");
+}
+function readMetadata(sessionId: string, root: string): ContinuationMetadata {
+	const value = readLast(statePath(sessionId, root)) as ContinuationMetadata | null;
+	if (!value) return blank();
+	if (typeof value !== "object" || !Number.isInteger(value.sequence) || value.sequence < 0 ||
+		!Number.isInteger(value.stop_blocks) || value.stop_blocks < 0 ||
+		!["unobserved", "ready", "running", "returned", "rejected"].includes(value.review) ||
+		![value.reviewer_prompt, value.reviewer_call_id, value.reviewer_agent_id, value.recovery_action, value.paused].every(v => v === null || typeof v === "string"))
+		throw new Error("invalid continuation metadata");
+	if (value.state) {
+		const { binding } = value.state;
+		if (!binding || binding.session_id !== sessionId || !Number.isInteger(value.state.unchanged_observations) || value.state.unchanged_observations < 0 ||
+			!(value.state.progress_digest === null || typeof value.state.progress_digest === "string") ||
+			!(value.state.boundary_id === null || typeof value.state.boundary_id === "string")) throw new Error("invalid bound run metadata");
+		bindRun(binding);
+	}
+	return value;
+}
+function save(sessionId: string, root: string, value: ContinuationMetadata): void {
+	const path = statePath(sessionId, root);
+	const temporary = `${path}.${randomUUID()}`;
+	if (!appendPrivate(temporary, cacheDir(root), JSON.stringify(value) + "\n")) throw new Error("continuation metadata could not be written");
+	try { renameSync(temporary, path); } finally { drop(temporary, root); }
+}
+
+async function observeNativeFailure(metadata: ContinuationMetadata, correlation: Correlation, root: string, reason: string): Promise<void> {
+	metadata.paused = reason;
+	save(correlation.session_id, root, metadata);
+	if (correlation.operation === "enroll" && metadata.state && await parkFailedCriticalGate(metadata.state.binding, correlation.task_id ?? undefined)) {
+		metadata.paused = null;
+		save(correlation.session_id, root, metadata);
+	}
+}
+
+/** Exact PreToolUse correlation; the transport connection ID is never a Hook session. */
+export function readRunToolSession(toolId: string, operation: string, workspace: string, root = tmpdir()): string | null {
+	const record = readLast(callPath(toolId, root)) as Correlation | null;
+	if (!record || record.operation !== operation || record.tool_use_id !== toolId || record.workspace !== realpathSync(workspace) ||
+		typeof record.session_id !== "string" || !record.session_id || !readPhaseEntryState(record.session_id, root)?.run_live) return null;
+	return record.session_id;
+}
+export function selectedClaudeParent(toolId: string, workspace: string, slug: string, root = tmpdir()): boolean {
+	const call = readLast(callPath(toolId, root)) as Correlation | null;
+	if (!call || call.workspace !== realpathSync(workspace) || !["advance_assurance", "submit_review"].includes(call.operation) ||
+		!readPhaseEntryState(call.session_id, root)?.run_live) return false;
+	const state = readMetadata(call.session_id, root).state;
+	return state?.binding.kind === "parent" && state.binding.workspace === call.workspace && state.binding.initiative_slug === slug;
+}
+
+/** A transcript assistant UUID identifies a Host turn; local callback counters do not. */
+function stopBoundary(payload: Record<string, unknown>): string | null {
+	if (typeof payload.transcript_path !== "string" || !payload.transcript_path) return null;
+	const fd = openSync(payload.transcript_path, "r");
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile()) throw new Error("Stop transcript must be a regular file");
+		const bytes = Buffer.alloc(Math.min(stat.size, 256 * 1024));
+		readSync(fd, bytes, 0, bytes.length, stat.size - bytes.length);
+		for (const line of bytes.toString("utf8").trim().split("\n").reverse()) {
+			let value; try { value = JSON.parse(line); } catch { continue; }
+			if (value.type === "assistant" && !value.isSidechain && typeof value.uuid === "string" && value.uuid)
+				return digestOfReviewerBytes(`${payload.transcript_path}\n${value.uuid}`);
+		}
+		return null;
+	} finally { closeSync(fd); }
+}
+
+function toolResponse(payload: Record<string, unknown>): Record<string, unknown> | null {
+	const response = payload.tool_response;
+	if (Array.isArray(response)) {
+		const text = response.filter(item => item?.type === "text" && typeof item.text === "string").map(item => item.text).join("");
+		try { return JSON.parse(text); } catch { return null; }
+	}
+	if (response && typeof response === "object" && !Array.isArray(response)) {
+		const object = response as Record<string, unknown>;
+		if (typeof object.state === "string") return object;
+		if (Array.isArray(object.content)) {
+			const text = object.content.filter(item => item?.type === "text" && typeof item.text === "string").map(item => item.text).join("");
+			try { return JSON.parse(text); } catch { return null; }
+		}
+		return object;
+	}
+	if (typeof response === "string") { try { return JSON.parse(response); } catch { return null; } }
+	return null;
+}
+function warning(reason: string): string { return JSON.stringify({ systemMessage: `Immune-Brain run paused: ${reason}` }); }
+
+/** Hook metadata only. Every continuation decision re-reads the actual Kernel. */
+export async function runContinuationHookOutput(payload: Record<string, unknown>, root = tmpdir()): Promise<string | null> {
+	const sessionId = typeof payload.session_id === "string" ? payload.session_id : "";
+	if (!sessionId) return null;
+	const workspace = realpathSync(typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd());
+	const event = String(payload.hook_event_name ?? "");
+	if (event === "SessionEnd") { drop(statePath(sessionId, root), root); return null; }
+	if (event === "UserPromptSubmit") {
+		const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+		const entry = recognizePhaseEntry(prompt, claudeAliasReader(workspace, homedir()));
+		if (releasesRunBinding(prompt, entry === "plan" ? "planner" : null) || entry === "run")
+			drop(statePath(sessionId, root), root);
+		return null;
+	}
+	try {
+		const operation = MCP_TOOL.exec(String(payload.tool_name ?? ""))?.[1];
+		const toolId = typeof payload.tool_use_id === "string" ? payload.tool_use_id : "";
+		if (event === "PreToolUse" && operation && toolId && readPhaseEntryState(sessionId, root)?.run_live) {
+			const metadata = readMetadata(sessionId, root);
+			if (metadata.paused && NATIVE_OPERATIONS.has(operation)) return JSON.stringify({ hookSpecificOutput: {
+				hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `Run paused: ${metadata.paused}; enter imm-run explicitly before another native gate` } });
+			const input = (payload.tool_input ?? {}) as Record<string, unknown>;
+			if (operation === "enroll" && metadata.state?.binding.kind === "parent" &&
+				metadata.state.binding.blocked_native_tasks?.includes(String(input.task_id))) return JSON.stringify({ hookSpecificOutput: {
+					hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "This critical gate is parked; continue independent work or resolve its same-Host recovery and enter imm-run explicitly" } });
+			const correlation: Correlation = { session_id: sessionId, workspace, tool_use_id: toolId, operation,
+				task_id: typeof input.task_id === "string" ? input.task_id : null };
+			if (!appendPrivate(callPath(toolId, root), cacheDir(root), JSON.stringify(correlation) + "\n")) throw new Error("tool correlation could not be recorded");
+			return null;
+		}
+		const metadata = readMetadata(sessionId, root);
+		if (metadata.paused) return event === "Stop" ? warning(metadata.paused) : null;
+		if ((event === "PostToolUse" || event === "PostToolUseFailure") && operation && toolId) {
+			const correlated = readLast(callPath(toolId, root)) as Correlation | null;
+			if (!correlated || correlated.session_id !== sessionId || correlated.workspace !== workspace || correlated.operation !== operation ||
+				readRunToolSession(toolId, operation, workspace, root) !== sessionId) return null;
+			drop(callPath(toolId, root), root);
+			if (event === "PostToolUseFailure") {
+				if (NATIVE_OPERATIONS.has(operation)) await observeNativeFailure(metadata, correlated, root, `${operation} failed or was cancelled; no automatic native retry`);
+				else if (operation === "submit_review") { metadata.review = "rejected"; save(sessionId, root, metadata); }
+				return null;
+			}
+			const response = toolResponse(payload);
+			if (operation === "start_unattended_batch" && response?.state === "native_parent" && typeof response.plan_digest === "string" && typeof response.initiative_slug === "string") {
+				if (metadata.state?.binding.kind !== "parent") metadata.state = bindRun({ kind: "parent", workspace, session_id: sessionId,
+					batch_id: null, initiative_slug: response.initiative_slug, plan_digest: response.plan_digest,
+					final_verification: response.final_verification_commands as string[] | undefined });
+			}
+			if (operation === "start_unattended_batch" && response?.state === "started" && typeof response.batch_id === "string") {
+				const batch = readAnyBatchRunState(workspace, response.batch_id);
+				if (!batch) throw new Error("batch receipt has no persisted identity");
+				if (metadata.state?.binding.kind !== "parent") metadata.state = bindRun({ kind: "parent", workspace,
+					session_id: sessionId, batch_id: batch.batch_id, initiative_slug: batch.initiative_slug, plan_digest: batch.plan_digest });
+			}
+			if (!metadata.state && correlated.task_id && ["enroll", "status"].includes(operation)) {
+				const status = await projectTaskStatus(workspace, correlated.task_id);
+				if (!status.error && status.claim?.task_id === correlated.task_id && status.projection.lifecycle === "active" && status.projection.run_id)
+					metadata.state = bindRun({ kind: "task", workspace, session_id: sessionId, task_id: correlated.task_id, run_id: status.projection.run_id });
+			}
+			if (operation === "enroll" && correlated.task_id && metadata.state?.binding.kind === "parent" && !["blocked", "cancelled", "failed", "rejected"].includes(String(response?.state)))
+				await recordParentRepair(workspace, metadata.state.binding.batch_id, correlated.task_id, metadata.state.binding.initiative_slug);
+			if (metadata.state?.binding.kind === "task" && correlated.task_id !== metadata.state.binding.task_id) return null;
+			if (operation === "advance_assurance" && response?.state === "review_ready") {
+				const params = response.agent_params as { prompt?: unknown } | undefined;
+				if (typeof params?.prompt === "string" && digestOfReviewerBytes(params.prompt) !== metadata.reviewer_prompt) {
+					metadata.reviewer_prompt = digestOfReviewerBytes(params.prompt); metadata.reviewer_call_id = null; metadata.reviewer_agent_id = null; metadata.review = "ready";
+				}
+			}
+			if (operation === "submit_review") {
+				if (["blocked", "rejected", "failed"].includes(String(response?.state))) {
+					metadata.review = "rejected";
+					const recovery = response?.recovery_action ?? response?.next_action;
+					metadata.recovery_action = typeof recovery === "string" ? recovery : null;
+				} else { metadata.review = "unobserved"; metadata.reviewer_prompt = null; metadata.reviewer_call_id = null; metadata.recovery_action = null; }
+			}
+			if (NATIVE_OPERATIONS.has(operation) && ["blocked", "cancelled", "rejected", "failed"].includes(String(response?.state)))
+				await observeNativeFailure(metadata, correlated, root, `${operation} did not apply; inspect the same-Host recovery before retrying`);
+			if (metadata.state) save(sessionId, root, metadata);
+			return null;
+		}
+		if (payload.tool_name === "Agent" && metadata.state && metadata.reviewer_prompt) {
+			const input = payload.tool_input as { prompt?: unknown; subagent_type?: unknown } | undefined;
+			if (event === "PreToolUse" && typeof input?.prompt === "string" && digestOfReviewerBytes(input.prompt) === metadata.reviewer_prompt && toolId) {
+				if (metadata.reviewer_call_id) { metadata.review = "rejected"; }
+				else { metadata.reviewer_call_id = toolId; metadata.review = "running"; }
+				save(sessionId, root, metadata);
+			}
+			if ((event === "PostToolUse" || event === "PostToolUseFailure") && toolId === metadata.reviewer_call_id) {
+				const response = toolResponse(payload);
+				if (response?.isAsync === true || response?.status === "async_launched") {
+					metadata.reviewer_agent_id = typeof response.agentId === "string" ? response.agentId : null;
+				} else metadata.review = "returned";
+				save(sessionId, root, metadata);
+			}
+		}
+		if (event === "SubagentStop" && metadata.reviewer_agent_id && payload.agent_id === metadata.reviewer_agent_id) {
+			metadata.review = "returned"; save(sessionId, root, metadata); return null;
+		}
+		if (event !== "Stop" || !metadata.state) return null;
+		if (!readPhaseEntryState(sessionId, root)?.run_live) { drop(statePath(sessionId, root), root); return null; }
+		if (metadata.state.binding.workspace !== workspace) {
+			drop(statePath(sessionId, root), root);
+			return warning("workspace changed; enter imm-run explicitly in this workspace");
+		}
+		const boundary = stopBoundary(payload);
+		if (!boundary) return null;
+		metadata.sequence++;
+		const taskId = metadata.state.binding.kind === "task" ? metadata.state.binding.task_id : metadata.state.binding.initiative_slug;
+		let observation: Parameters<typeof decideRunContinuation>[1];
+		if (metadata.state.binding.kind === "parent") observation = await observeParentRun(metadata.state.binding,
+			boundary, metadata.review, metadata.recovery_action ?? undefined);
+		else {
+			const status = await projectTaskStatus(workspace, taskId);
+			const record = readTaskRecordRaw(workspace, taskId);
+			observation = { kind: "task", workspace, session_id: sessionId,
+				boundary_id: boundary, status,
+				source_digest: record.record ? scopedSourceDigest(workspace, record.record.intent_snapshot.scope_hint) : "terminal",
+				review: metadata.review, recovery_action: metadata.recovery_action ?? undefined };
+		}
+		const decision = decideRunContinuation(metadata.state, observation);
+		if (decision.action === "unbound" || decision.action === "settled") { drop(statePath(sessionId, root), root); return null; }
+		if (decision.action === "wait") { metadata.state = decision.state; save(sessionId, root, metadata); return null; }
+		if (decision.state.progress_digest !== metadata.state.progress_digest || payload.stop_hook_active !== true) metadata.stop_blocks = 0;
+		metadata.state = decision.state;
+		if (decision.action === "pause" || metadata.stop_blocks >= 7) {
+			metadata.paused = metadata.stop_blocks >= 7 ? "Claude consecutive Stop boundary reached; resume explicitly in the same Host" : decision.reason;
+			save(sessionId, root, metadata); return warning(metadata.paused);
+		}
+		metadata.stop_blocks++;
+		save(sessionId, root, metadata);
+		return JSON.stringify({ decision: "block", reason: `Explicit imm-run is bound to ${taskId}; Kernel settlement is incomplete. ${decision.next_action}. Continue the authorized Loop.` });
+	} catch (error) {
+		return warning(`continuation facts could not be verified: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}