immune-brain 5.1.1 → 5.2.0

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

@@ -55,9 +55,11 @@ import {
 	startBatch,
 	type BatchRunnerKernelPort,
 	type BatchRunReport,
+	type BatchTrackerPort,
 } from "../unattended/batch_runner";
 import { createBatchKernelPort } from "../unattended/batch_kernel_port";
-import type { LaneOffer } from "../unattended/batch_lanes";
+import type { LaneRevisionRequest } from "../unattended/batch_delegation";
+import { createBatchTrackerPort, laneRuntimeContractRefusal, type LaneInstructionRequest, type LaneOffer } from "../unattended/batch_lanes";
 import { retireStaleBatch } from "../unattended/batch_disposition";
 import type { BatchLaneRunReport } from "../unattended/batch_state";
 import {
@@ -231,6 +233,7 @@ export interface ClaudeRuntimeOptions {
 	requestConfirmation?: NativeConfirmationPort;
 	batchKernel?: Partial<BatchRunnerKernelPort>;
 	batchGit?: BatchRunnerGitPort;
+	batchTracker?: BatchTrackerPort;
 	readInitiative?: InitiativeObservationReader;
 }
 
@@ -268,6 +271,7 @@ export class ClaudeRuntime {
 	private app: ReturnType<typeof createCanaryApplication> | null = null;
 	private readonly batchKernel?: Partial<BatchRunnerKernelPort>;
 	private readonly batchGit?: BatchRunnerGitPort;
+	private readonly batchTracker?: BatchTrackerPort;
 	private readonly readInitiative?: InitiativeObservationReader;
 
 	constructor(options: ClaudeRuntimeOptions) {
@@ -277,6 +281,7 @@ export class ClaudeRuntime {
 		this.requestConfirmation = options.requestConfirmation;
 		this.batchKernel = options.batchKernel;
 		this.batchGit = options.batchGit;
+		this.batchTracker = options.batchTracker;
 		this.readInitiative = options.readInitiative;
 		this.host = options.host ?? new ClaudeReviewHost(new FileHookEventLog());
 		this.coordinator = new AssuranceCoordinator({
@@ -741,7 +746,7 @@ export class ClaudeRuntime {
 	async startUnattendedBatch(
 		initiativeSlug: string,
 		meta: ToolMeta,
-		options: { reuseOnly?: boolean; max_parallel?: number; lane_offers?: LaneOffer[] } = {},
+		options: { reuseOnly?: boolean; max_parallel?: number; lane_offers?: LaneOffer[]; final_verification?: string[]; lane_instruction?: LaneInstructionRequest; lane_revision?: LaneRevisionRequest } = {},
 	): Promise<ClaudeBatchStartResult> {
 		throwIfCancelled(meta.signal);
 		const reuseOnly = options.reuseOnly === true;
@@ -779,6 +784,12 @@ export class ClaudeRuntime {
 		const budget = preflight.projection.budget;
 		const planDigest = preflight.projection.plan_digest;
 		const recoveryChildren = preflight.projection.recovery_children;
+		// A new lane batch whose Lane runtime cannot read the coordinator's Kernel
+		// contracts is refused before the gate opens; a match adds nothing.
+		if (options.max_parallel !== undefined && !isResuming) {
+			const contractRefusal = laneRuntimeContractRefusal(this.cwd);
+			if (contractRefusal) return batchReason("batch_run_rejected", contractRefusal);
+		}
 		// 5. Literal-user gate plus the shared reuse decision, the post-gate
 		// claim/drift cascade, and the Batch Authorization binding. The Host supplies
 		// only its gate, its confirmation reference, and its binding nonce.
@@ -803,7 +814,7 @@ export class ClaudeRuntime {
 					};
 				// The gate settles only on the literal user's answer or the caller's
 				// cancellation signal.
-				let confirmationResult: { decision: NativeDecision; requestId: string };
+				let confirmationResult: { decision: NativeDecision; requestId: string; delegateRevisions?: boolean };
 				try {
 					confirmationResult = await this.requestConfirmation!({
 						operation: "start_unattended_batch",
@@ -830,6 +841,8 @@ export class ClaudeRuntime {
 											max_parallel: options.max_parallel,
 											parallel_groups: facts.parallel_groups,
 											serialized: facts.scope_conflicts,
+											...(options.final_verification ? { final_verification: options.final_verification } : {}),
+											offer_revision_delegation: true,
 										},
 									}
 								: {}),
@@ -874,7 +887,11 @@ export class ClaudeRuntime {
 					return { kind: "host_rejection", value: batchReason("confirmation_cancelled") };
 				if (confirmationResult.decision !== "accept")
 					return { kind: "host_rejection", value: batchReason("confirmation_no_decision") };
-				return { kind: "confirmed", request_id: confirmationResult.requestId };
+				return {
+					kind: "confirmed",
+					request_id: confirmationResult.requestId,
+					...(options.max_parallel !== undefined && confirmationResult.delegateRevisions ? { delegate_revisions: true } : {}),
+				};
 			},
 			// A reused authorization keeps this invocation's Kernel binding without a new
 			// literal-user act, so its confirmation reference names the resumed batch
@@ -937,7 +954,16 @@ export class ClaudeRuntime {
 			now,
 			kernel: kernelPort,
 			git: this.batchGit,
-			...(options.max_parallel !== undefined ? { max_parallel: options.max_parallel } : {}),
+			...(options.max_parallel !== undefined
+				? {
+						max_parallel: options.max_parallel,
+						tracker: this.batchTracker ?? createBatchTrackerPort(this.cwd, initiativeSlug),
+						...(options.final_verification ? { final_verification: options.final_verification } : {}),
+						...(options.lane_instruction ? { lane_instruction: options.lane_instruction } : {}),
+						...(options.lane_revision ? { lane_revision: options.lane_revision } : {}),
+						...(authorization.revision_delegation !== undefined ? { revision_delegation: authorization.revision_delegation } : {}),
+					}
+				: {}),
 			...(options.lane_offers !== undefined ? { lane_offers: options.lane_offers } : {}),
 		});
 
@@ -969,7 +995,7 @@ export class ClaudeRuntime {
 			initiative_slug: initiativeSlug,
 			now: new Date().toISOString(),
 			gate: async (facts) => {
-				let confirmationResult: { decision: NativeDecision; requestId: string };
+				let confirmationResult: { decision: NativeDecision; requestId: string; delegateRevisions?: boolean };
 				try {
 					confirmationResult = await this.requestConfirmation!({
 						operation: "retire_stale_batch",

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

@@ -0,0 +1,210 @@
+// Claude Code hook decisions that are not Review observation. PreToolUse guard for batch Lanes: an Edit, Write, MultiEdit or
+// NotebookEdit whose target resolves outside the Lane is denied before it
+// runs, the same rule the Pi extension applies to `edit`/`write`. Bash is not
+// intercepted. Outside a Lane the hook answers nothing and the tool runs as
+// configured.
+//
+// Phase entry gate: UserPromptSubmit records which literal prompt entered
+// planning or execution; PreToolUse denies `enroll`, `start_unattended_batch`
+// and the three phase Skills without a matching entry, and otherwise leaves an
+// admission the tool handler consumes by tool-use id.
+import { lstatSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { laneWriteRefusal } from "../unattended/lane_workspace";
+import { activeTaskNotice } from "../assurance/active_task_notice";
+import { readAliasFile } from "../assurance/alias_file";
+import {
+	admitPhaseOperation,
+	NO_PHASE_ENTRY,
+	packagedPhaseSkill,
+	phaseEntryLogLine,
+	phaseRefusalMessage,
+	PHASE_ENTRY_RECOVERY,
+	recognizePhaseEntry,
+	reducePhaseEntryLog,
+	RUN_ENTRY_REQUIRED,
+	type AliasReader,
+	type PhaseEntryState,
+	type PhaseOperation,
+} from "../assurance/phase_entry";
+import { readActiveClaimTaskId } from "../unattended/batch_preflight";
+import { appendPrivate, cacheDir, ensurePrivateDir, ownedByUs, readPrivate, sessionHash } from "./review_host";
+
+const FILE_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+const GATED_MCP_TOOL = /^mcp__.*immune-brain.*__(enroll|start_unattended_batch)$/;
+
+export type GatedTool = "enroll" | "start_unattended_batch";
+
+/** Where the phase entry gate keeps its private files and finds user aliases. */
+export interface PhaseEntryLocations {
+	/** Parent of the private cache directory. Defaults to the OS temp directory. */
+	root?: string;
+	/** The user's home, for `~/.claude/commands`. */
+	home?: string;
+	/** The private store's append and read. Default to the real file operations. */
+	append?: typeof appendPrivate;
+	read?: typeof readPrivate;
+}
+
+function denyPreToolUse(reason: string): string {
+	return JSON.stringify({
+		hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason },
+	});
+}
+
+/** The hook's stdout for one PreToolUse payload, or null to stay silent. */
+export function laneGuardHookOutput(payload: Record<string, unknown>): string | null {
+	if (payload.hook_event_name !== "PreToolUse" || !FILE_TOOLS.has(String(payload.tool_name))) return null;
+	const input = (payload.tool_input ?? {}) as { file_path?: unknown; notebook_path?: unknown };
+	const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+	const refusal = laneWriteRefusal(cwd, input.file_path ?? input.notebook_path);
+	if (!refusal) return null;
+	return denyPreToolUse(refusal);
+}
+
+/**
+ * UserPromptSubmit: when the workspace has an active Managed task, add the
+ * advisory notice as context. It never resumes the task.
+ */
+export async function activeTaskHookOutput(payload: Record<string, unknown>): Promise<string | null> {
+	if (payload.hook_event_name !== "UserPromptSubmit") return null;
+	const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+	const notice = await activeTaskNotice(cwd);
+	if (!notice) return null;
+	return JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: notice } });
+}
+
+function entryLogPath(sessionId: string, root: string): string {
+	return join(cacheDir(root), `${sessionHash(sessionId)}.entry`);
+}
+
+function admissionPath(toolUseId: string, root: string): string {
+	return join(cacheDir(root), `${sessionHash(toolUseId)}.admit`);
+}
+
+function sessionIdOf(payload: Record<string, unknown>): string {
+	return typeof payload.session_id === "string" ? payload.session_id : "";
+}
+
+function cwdOf(payload: Record<string, unknown>): string {
+	return typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+}
+
+/** Project aliases first, then the user's, as Claude Code resolves commands. */
+function claudeAliasReader(cwd: string, home: string): AliasReader {
+	return (name) => {
+		for (const dir of [join(cwd, ".claude", "commands"), join(home, ".claude", "commands")]) {
+			const body = readAliasFile(join(dir, `${name}.md`));
+			if (body !== null) return body;
+		}
+		return null;
+	};
+}
+
+/** The session's entry state: none recorded yet, or null when the store is unreadable. */
+export function readPhaseEntryState(sessionId: string, root = tmpdir(), read: typeof readPrivate = readPrivate): PhaseEntryState | null {
+	if (!sessionId) return null;
+	const path = entryLogPath(sessionId, root);
+	try {
+		lstatSync(path);
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ENOENT" ? NO_PHASE_ENTRY : null;
+	}
+	if (!ensurePrivateDir(cacheDir(root))) return null;
+	let text: string | undefined;
+	try { text = read(path); } catch { return null; }
+	return text === undefined ? null : reducePhaseEntryLog(text);
+}
+
+/** Removes one of our private files. Never follows a link or touches another owner's file. */
+function dropPrivate(path: string): void {
+	try {
+		const stat = lstatSync(path);
+		if (ownedByUs(stat) && stat.isFile()) rmSync(path, { force: true });
+	} catch { /* already gone, or not ours to remove */ }
+}
+
+/**
+ * UserPromptSubmit: record whether this literal prompt entered a phase. Every
+ * prompt is recorded so "the latest prompt" is decidable later. A prompt that
+ * could not be recorded drops the log: an earlier entry must not outlive a
+ * prompt the store never saw, so the session is back to no entry.
+ */
+export function recordPhaseEntryPrompt(payload: Record<string, unknown>, locations: PhaseEntryLocations = {}): boolean {
+	if (payload.hook_event_name !== "UserPromptSubmit") return false;
+	const sessionId = sessionIdOf(payload);
+	if (!sessionId) return false;
+	const root = locations.root ?? tmpdir();
+	const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+	const entry = recognizePhaseEntry(prompt, claudeAliasReader(cwdOf(payload), locations.home ?? homedir()));
+	const path = entryLogPath(sessionId, root);
+	const recorded = (locations.append ?? appendPrivate)(path, cacheDir(root), phaseEntryLogLine(entry));
+	if (!recorded) dropPrivate(path);
+	return recorded;
+}
+
+function gatedOperation(payload: Record<string, unknown>): PhaseOperation | null {
+	const toolName = String(payload.tool_name ?? "");
+	if (toolName === "Skill") {
+		const input = (payload.tool_input ?? {}) as { skill?: unknown };
+		const skill = typeof input.skill === "string" ? packagedPhaseSkill(input.skill) : null;
+		return skill ? { kind: "skill", skill } : null;
+	}
+	const mcp = GATED_MCP_TOOL.exec(toolName);
+	return mcp ? { kind: "tool", name: mcp[1] as GatedTool } : null;
+}
+
+/**
+ * PreToolUse for a gated tool: deny without a matching entry; for the two MCP
+ * tools, otherwise write the admission the handler consumes. Any other tool
+ * answers null and runs as configured.
+ */
+export function phaseEntryGateHookOutput(payload: Record<string, unknown>, locations: PhaseEntryLocations = {}): string | null {
+	if (payload.hook_event_name !== "PreToolUse") return null;
+	const operation = gatedOperation(payload);
+	if (!operation) return null;
+	const root = locations.root ?? tmpdir();
+	let state: PhaseEntryState | null = null;
+	try { state = readPhaseEntryState(sessionIdOf(payload), root, locations.read); } catch { /* an unreadable store refuses */ }
+	let activeClaim = false;
+	try { activeClaim = readActiveClaimTaskId(cwdOf(payload)) !== null; } catch { /* unreadable authority is no claim */ }
+	const admission = admitPhaseOperation(operation, state, { activeClaim });
+	if (!admission.ok) return denyPreToolUse(phaseRefusalMessage(admission));
+	if (operation.kind === "skill") return null;
+	const toolUseId = typeof payload.tool_use_id === "string" ? payload.tool_use_id : "";
+	let recorded = false;
+	try {
+		recorded = toolUseId !== ""
+			&& (locations.append ?? appendPrivate)(admissionPath(toolUseId, root), cacheDir(root), `${JSON.stringify({ v: 1, operation: operation.name })}\n`);
+	} catch { /* an admission that could not be written refuses */ }
+	if (recorded) return null;
+	return denyPreToolUse(
+		`${RUN_ENTRY_REQUIRED}: the admission for this ${operation.name} call could not be recorded; recovery: ${PHASE_ENTRY_RECOVERY[RUN_ENTRY_REQUIRED]}`,
+	);
+}
+
+/**
+ * Tool side: take the admission the hook wrote for this exact call. One use;
+ * absent, unreadable or written for another operation all refuse. The hook may
+ * run more than once for one call (two enabled copies of the plugin), so
+ * repeated identical admissions count as one.
+ */
+export function consumePhaseAdmission(toolUseId: string, operation: GatedTool, root = tmpdir()): boolean {
+	if (!toolUseId || !ensurePrivateDir(cacheDir(root))) return false;
+	const path = admissionPath(toolUseId, root);
+	let text: string | undefined;
+	try { text = readPrivate(path); } catch { return false; }
+	if (text === undefined) return false;
+	dropPrivate(path);
+	const lines = text.split("\n").filter(Boolean);
+	if (lines.length === 0) return false;
+	return lines.every((line) => {
+		try {
+			const record = JSON.parse(line) as { v?: unknown; operation?: unknown } | null;
+			return record?.v === 1 && record.operation === operation;
+		} catch {
+			return false;
+		}
+	});
+}

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

@@ -12,8 +12,11 @@ import {
 	type NativeConfirmationPort,
 } from "./interaction";
 import { ClaudeReviewHost, FileHookEventLog, parseHookStdin } from "./review_host";
+import { activeTaskHookOutput, consumePhaseAdmission, laneGuardHookOutput, phaseEntryGateHookOutput, recordPhaseEntryPrompt, type GatedTool } from "./lane_guard";
 import { ClaudeRuntime, type ToolMeta } from "./kernel_ports";
-import { parseLaneOffers, parseMaxParallel, resolveLaneParallel } from "../unattended/batch_lanes";
+import { parseLaneInstruction, parseLaneOffers, parseMaxParallel, resolveLaneParallel } from "../unattended/batch_lanes";
+import { parseFinalVerification } from "../unattended/batch_final_verification";
+import { parseLaneRevision, REVISION_DELEGATION_TEXT } from "../unattended/batch_delegation";
 import type { AssuranceCoordinatorPorts } from "../assurance/coordinator";
 
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
@@ -56,6 +59,24 @@ export function listMcpTools() {
 											additionalProperties: false,
 										},
 									},
+									final_verification: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
+									lane_instruction: {
+										type: "object",
+										properties: {
+											task_id: { type: "string" },
+											kind: { type: "string", enum: ["instruction", "correction"] },
+											text: { type: "string" },
+											session_state: { type: "string", enum: ["idle", "working", "blocked", "done"] },
+										},
+										required: ["task_id", "text", "session_state"],
+										additionalProperties: false,
+									},
+									lane_revision: {
+										type: "object",
+										properties: { task_id: { type: "string" }, next_intent: { type: "object" } },
+										required: ["task_id", "next_intent"],
+										additionalProperties: false,
+									},
 								}
 							: {}),
 						}
@@ -97,6 +118,11 @@ export interface McpRuntimeOptions {
 	batchKernel?: Partial<import("../unattended/batch_runner").BatchRunnerKernelPort>;
 	batchGit?: import("../unattended/batch_git").BatchRunnerGitPort;
 	readInitiative?: import("../unattended/types").InitiativeObservationReader;
+	/**
+	 * Takes the admission the PreToolUse hook wrote for one `enroll` or
+	 * `start_unattended_batch` call. Defaults to the private file store.
+	 */
+	consumePhaseAdmission?: (toolCallId: string, operation: GatedTool) => boolean;
 }
 
 export function createMcpRuntime(options: McpRuntimeOptions = {}) {
@@ -118,6 +144,14 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 	let negotiatedVersion: string | undefined;
 	let negotiatedInteractive = false;
 	const connectionId = randomUUID();
+	const consumeAdmission = options.consumePhaseAdmission ?? ((toolCallId: string, operation: GatedTool) => consumePhaseAdmission(toolCallId, operation));
+	// 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.
+	const requireRunEntry = (operation: GatedTool, toolCallId: string) => {
+		if (consumeAdmission(toolCallId, operation)) return;
+		throw new NativeAuthorityError("run_entry_required", `${operation} needs a literal-user imm-run entry in this session`);
+	};
 	return {
 		runtime,
 		host,
@@ -143,6 +177,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);
+				requireRunEntry(name, meta.toolCallId ?? `call-${name}`);
 				const toolMeta: ToolMeta = {
 					sessionId: meta.sessionId ?? connectionId,
 					toolCallId: meta.toolCallId ?? `call-${name}`,
@@ -153,10 +188,16 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				};
 				const laneOffers = parseLaneOffers(args.lane_offers);
 				// A lane_offers-only call resumes the recorded lane batch; refused before any gate otherwise.
-				const maxParallel = resolveLaneParallel(options.cwd ?? process.cwd(), initiativeSlug, parseMaxParallel(args.max_parallel), laneOffers);
+				const laneInstruction = parseLaneInstruction(args.lane_instruction);
+				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);
 				return runtime.startUnattendedBatch(initiativeSlug, toolMeta, {
 					...(maxParallel !== undefined ? { max_parallel: maxParallel } : {}),
 					...(laneOffers !== undefined ? { lane_offers: laneOffers } : {}),
+					...(finalVerification !== undefined ? { final_verification: finalVerification } : {}),
+					...(laneInstruction !== undefined ? { lane_instruction: laneInstruction } : {}),
+					...(laneRevision !== undefined ? { lane_revision: laneRevision } : {}),
 				});
 			}
 			if (name === "retire_stale_batch") {
@@ -203,7 +244,10 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				interactive: meta.interactive ?? options.interactive ?? negotiatedInteractive,
 				signal: meta.signal,
 			};
-			if (name === "enroll") return runtime.enroll(taskId, toolMeta);
+			if (name === "enroll") {
+				requireRunEntry(name, meta.toolCallId ?? `call-${name}`);
+				return runtime.enroll(taskId, toolMeta);
+			}
 			if (name === "advance_assurance") return runtime.advance(taskId, toolMeta.signal, toolMeta);
 			if (name === "submit_review") {
 				// ADR 0017: an absent verdict is the receipt-bound submission.
@@ -445,11 +489,25 @@ 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?.lane_mode?.offer_revision_delegation ? REVISION_DELEGATION_TEXT : null,
 		].filter(Boolean);
 		return {
 			mode: "form",
 			message: `Authorize this unattended batch run for ${input.initiativeSlug}?\n\n${details.join("\n")}`,
-			requestedSchema: { type: "object", properties: {} },
+			requestedSchema: b?.lane_mode?.offer_revision_delegation
+				? {
+						type: "object",
+						properties: {
+							delegate_in_lane_revisions: {
+								type: "boolean",
+								title: "Delegate in-envelope Lane Intent revisions to the batch coordinator",
+								description: REVISION_DELEGATION_TEXT,
+								default: false,
+							},
+						},
+					}
+				: { type: "object", properties: {} },
 		};
 	}
 	const details = [
@@ -527,13 +585,19 @@ export async function serveStdio(options: {
 			if (action !== "accept" && action !== "decline" && action !== "cancel") {
 				throw new NativeAuthorityError("correlation_missing", "MCP elicitation returned an invalid action");
 			}
+			let delegateRevisions = false;
 			if (action === "accept") {
 				const content = (result as { content?: unknown }).content;
-				if (typeof content !== "object" || content === null || Array.isArray(content) || Object.keys(content).length !== 0) {
+				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;
+				const valid = keys !== null && (keys.length === 0 ||
+					(offered && keys.length === 1 && keys[0] === "delegate_in_lane_revisions" && typeof (content as Record<string, unknown>).delegate_in_lane_revisions === "boolean"));
+				if (!valid) {
 					throw new NativeAuthorityError("correlation_missing", "MCP elicitation accept content did not match the requested schema");
 				}
+				delegateRevisions = offered && (content as Record<string, unknown>).delegate_in_lane_revisions === true;
 			}
-			return { decision: action, requestId };
+			return { decision: action, requestId, ...(delegateRevisions ? { delegateRevisions: true } : {}) };
 		} finally {
 			pending.delete(requestId);
 			if (abortListener) input.signal?.removeEventListener("abort", abortListener);
@@ -686,7 +750,21 @@ async function runHook(): Promise<void> {
 	const lines: string[] = [];
 	const rl = createInterface({ input: stdin });
 	for await (const line of rl) lines.push(line);
-	const event = parseHookStdin(lines.join("\n"));
+	const raw = lines.join("\n");
+	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);
+		if (decision) process.stdout.write(`${decision}\n`);
+		return;
+	}
+	if (payload?.hook_event_name === "UserPromptSubmit") {
+		recordPhaseEntryPrompt(payload);
+		const notice = await activeTaskHookOutput(payload);
+		if (notice) process.stdout.write(`${notice}\n`);
+		return;
+	}
+	const event = parseHookStdin(raw);
 	if (!event) return;
 	new FileHookEventLog().append(event);
 }

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

@@ -76,21 +76,21 @@ export class MemoryHookEventLog implements HookEventLog {
 
 const CACHE_DIR = "immune-brain-claude";
 
-function sessionHash(sessionId: string): string {
+export function sessionHash(sessionId: string): string {
 	return createHash("sha256").update(sessionId).digest("hex");
 }
 
-function cacheDir(root: string): string {
+export function cacheDir(root: string): string {
 	return join(root, CACHE_DIR);
 }
 
-function ownedByUs(stat: { uid: number; isSymbolicLink(): boolean }): boolean {
+export function ownedByUs(stat: { uid: number; isSymbolicLink(): boolean }): boolean {
 	if (stat.isSymbolicLink()) return false;
 	const uid = process.getuid?.();
 	return uid === undefined || stat.uid === uid;
 }
 
-function ensurePrivateDir(dir: string): boolean {
+export function ensurePrivateDir(dir: string): boolean {
 	try {
 		const existing = lstatSync(dir);
 		return existing.isDirectory() && ownedByUs(existing) && (existing.mode & 0o777) === 0o700;
@@ -106,7 +106,7 @@ function ensurePrivateDir(dir: string): boolean {
 	}
 }
 
-function appendPrivate(path: string, dir: string, line: string): boolean {
+export function appendPrivate(path: string, dir: string, line: string): boolean {
 	if (!ensurePrivateDir(dir)) return false;
 	const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK;
 	let fd: number;
@@ -122,7 +122,7 @@ function appendPrivate(path: string, dir: string, line: string): boolean {
 	}
 }
 
-function readPrivate(path: string, maxBytes = Number.POSITIVE_INFINITY): string | undefined {
+export function readPrivate(path: string, maxBytes = Number.POSITIVE_INFINITY): string | undefined {
 	let fd: number;
 	try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); } catch { return; }
 	try {

package/plugins/immune-brain/runtime/commands/kernel.ts

@@ -8,6 +8,7 @@ import {
 } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
+import { projectScopeOverlap } from "../unattended/batch_schedule";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import {
@@ -858,6 +859,57 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
  * TaskRecord, claim, Ledger, Git index, or session write. Returns a stable
  * bounded projection.
  */
+/**
+ * Read-only: compare the `scope_hint` of two or more TaskIntents of one
+ * Initiative and report every overlapping entry pair plus the start waves the
+ * Batch Plan would use. Optional `--blocked-by a=b,c` edges order the waves the
+ * way the Initiative's dependencies do. Writes nothing.
+ */
+function runIntentOverlap(args: string[], root: string): KernelExecution {
+	const usage = "Run imm-kernel intent overlap <path> <path>... [--blocked-by <task-id>=<task-id>,...] --json.";
+	const reject = (message: string): KernelExecution => ({
+		result: errorResult("invalid_command", message, 2),
+		journal: journalFor("intent", null, "rejected", "invalid_command", null, usage),
+	});
+	const paths: string[] = [];
+	const blockedBy = new Map<string, string[]>();
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index]!;
+		if (arg === "--json") continue;
+		if (arg === "--blocked-by") {
+			const edge = args[++index] ?? "";
+			const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)=([A-Za-z0-9._,-]+)$/.exec(edge);
+			if (!match) return reject(`invalid --blocked-by edge: ${edge}`);
+			blockedBy.set(match[1]!, match[2]!.split(",").filter(Boolean));
+			continue;
+		}
+		if (arg.startsWith("-")) return reject(`unsupported intent overlap option: ${arg}`);
+		paths.push(arg);
+	}
+	if (paths.length < 2) return reject("imm-kernel intent overlap requires at least two paths");
+	const children: Array<{ task_id: string; blocked_by: string[]; scope_hint: string[] }> = [];
+	for (const path of paths) {
+		let intent: { task_id?: unknown; scope_hint?: unknown };
+		try {
+			intent = JSON.parse(readFileSync(resolve(root, path), "utf8"));
+		} catch (error) {
+			return { result: errorResult("source_invalid", `cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`, 1), journal: journalFor("intent", null, "rejected", "source_read_failed", null, usage) };
+		}
+		if (typeof intent.task_id !== "string" || !Array.isArray(intent.scope_hint) || intent.scope_hint.some((entry) => typeof entry !== "string"))
+			return { result: errorResult("source_invalid", `${path} has no task_id and string scope_hint`, 1), journal: journalFor("intent", null, "rejected", "source_invalid", null, usage) };
+		children.push({ task_id: intent.task_id, blocked_by: [], scope_hint: intent.scope_hint as string[] });
+	}
+	const known = new Set(children.map((child) => child.task_id));
+	for (const child of children) child.blocked_by = (blockedBy.get(child.task_id) ?? []).filter((id) => known.has(id));
+	let report: ReturnType<typeof projectScopeOverlap>;
+	try {
+		report = projectScopeOverlap(children);
+	} catch (error) {
+		return reject(error instanceof Error ? error.message : String(error));
+	}
+	return { result: jsonResult(report, 0), journal: journalFor("intent", null, "ok", "command_ok", null, null) };
+}
+
 function runIntentValidate(args: string[], root: string): KernelExecution {
 	const nonFlags = args.filter((arg) => !arg.startsWith("-"));
 	if (nonFlags.length !== 1)
@@ -1173,10 +1225,11 @@ function executeKernelCommand(args: string[], root: string): KernelExecution {
 		const sub = args[1] ?? "";
 		if (sub === "author") return runIntentAuthor(args.slice(2), root);
 		if (sub === "validate") return runIntentValidate(args.slice(2), root);
+		if (sub === "overlap") return runIntentOverlap(args.slice(2), root);
 		return {
 			result: errorResult(
 				"invalid_command",
-				"usage: imm-kernel intent author <path> --stdin --json | validate <path> --json",
+				"usage: imm-kernel intent author <path> --stdin --json | validate <path> --json | overlap <path> <path>... [--blocked-by <task-id>=<task-id>,...] --json",
 				2,
 			),
 			journal: journalFor(