immune-brain 4.5.0 → 5.0.0

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

@@ -74,6 +74,7 @@ export interface McpRuntimeOptions {
 	cwd?: string;
 	env?: Record<string, string | undefined>;
 	ports?: AssuranceCoordinatorPorts;
+	authorityOverrides?: Partial<import("../assurance/verdict_authority").VerdictAuthority>;
 	host?: ClaudeReviewHost;
 	interactive?: boolean;
 	requestConfirmation?: NativeConfirmationPort;
@@ -89,6 +90,7 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 		env: options.env ?? process.env,
 		host,
 		ports: options.ports,
+		authorityOverrides: options.authorityOverrides,
 		interactive: options.interactive,
 		requestConfirmation: options.requestConfirmation,
 		batchKernel: options.batchKernel,
@@ -160,10 +162,10 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				signal: meta.signal,
 			};
 			if (name === "enroll") return runtime.enroll(taskId, toolMeta);
-			if (name === "advance_assurance") return runtime.advance(taskId, toolMeta.signal);
+			if (name === "advance_assurance") return runtime.advance(taskId, toolMeta.signal, toolMeta);
 			if (name === "submit_review") {
 				if (!Object.hasOwn(args, "verdict")) throw new Error("verdict is required");
-				return runtime.submitReview(taskId, args.verdict);
+				return runtime.submitReview(taskId, args.verdict, toolMeta);
 			}
 			if (name === "revise_intent") {
 				if (!Object.hasOwn(args, "next_intent")) throw new Error("next_intent is required");
@@ -369,8 +371,7 @@ export function elicitationParams(input: NativeConfirmationInput) {
 			input.planDigest ? `Plan digest: ${input.planDigest}` : null,
 			b?.children ? `Ordered children (${b.children.length}):\n${b.children.map((c) => `  - ${c.task_id} (${c.slice_id}) [risk: ${c.risk ?? "unknown"}]`).join("\n")}` : null,
 			b?.excluded && b.excluded.length > 0 ? `Excluded children (${b.excluded.length}):\n${b.excluded.map((e) => `  - ${e.task_id} (${e.slice_id}): ${e.reason}`).join("\n")}` : null,
-			b?.budget ? `Budget: max_children=${b.budget.max_children}, deadline_at=${b.budget.deadline_at}, qa_failure_limit=${b.budget.qa_failure_limit}` : null,
-			b?.expires_at ? `Expires at: ${b.expires_at}` : null,
+			b?.budget ? `Budget: max_children=${b.budget.max_children}, qa_failure_limit=${b.budget.qa_failure_limit}` : null,
 		].filter(Boolean);
 		return {
 			mode: "form",

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

@@ -149,9 +149,9 @@ export type AsyncAgentLaunch = { agentId: string; outputFile: string };
 /**
  * Recognise the launch receipt this Claude Code build returns for `Agent`.
  *
- * Every `Agent` call here runs asynchronously — `run_in_background: false` in
- * the dispatch envelope is not honoured, and there is no synchronous mode. The
- * tool result is therefore
+ * Every `Agent` call here runs asynchronously: this Host has no synchronous
+ * mode and no background switch, so the dispatch envelope carries nothing that
+ * would ask for one. The tool result is therefore
  * `{"isAsync":true,"status":"async_launched","agentId":…,"outputFile":…}`:
  * proof that a subagent started, never its answer. Treating it as the verdict
  * would settle Review on a receipt for starting the reviewer, so the launch
@@ -169,12 +169,21 @@ export function parseAsyncAgentLaunch(result: string): AsyncAgentLaunch | null {
 	return { agentId, outputFile };
 }
 
+const HANDBACK_TOOL = "SubagentHandback";
+
 /**
  * Extract the reviewer's terminal message from its own transcript.
  *
  * Each record carries the `agentId` that wrote it, so the caller's independently
  * observed id is matched per record rather than trusted for the file as a whole;
  * a transcript that interleaves another agent cannot contribute its text.
+ *
+ * A subagent ends its run either with an assistant text message or, on Hosts
+ * that hand the report back through a tool, with a `SubagentHandback` call whose
+ * `input.message` is that same report and which leaves no text block behind.
+ * Both are the reviewer's own record in its own transcript, so whichever the
+ * observed agent wrote last is its result — across records and across the
+ * ordered content blocks of a single record.
  */
 export function readAgentTranscriptResult(transcript: string, agentId: string): string | null {
 	let last: string | null = null;
@@ -192,6 +201,12 @@ export function readAgentTranscriptResult(transcript: string, agentId: string):
 			if (!block || typeof block !== "object") continue;
 			const part = block as Record<string, unknown>;
 			if (part.type === "text" && typeof part.text === "string") text += part.text;
+			if (part.type === "tool_use" && part.name === HANDBACK_TOOL && part.input && typeof part.input === "object") {
+				const report = (part.input as Record<string, unknown>).message;
+				// Blocks are ordered, so text before the report is a preamble and
+				// only text written after it can supersede it.
+				if (typeof report === "string" && report.trim()) { last = report; text = ""; }
+			}
 		}
 		if (text.trim()) last = text;
 	}
@@ -262,6 +277,12 @@ export class FileHookEventLog implements HookEventLog {
 
 interface PendingReview {
 	request: ReviewRequest;
+	/**
+	 * The prompt the Host asked the Parent to dispatch, marker line included.
+	 * Hook evidence carries Parent-authored text, so this is the only string a
+	 * dispatched prompt is ever compared against.
+	 */
+	dispatchPrompt: string;
 	initialCursors: Map<string, number>;
 	sessionCursors: Map<string, number>;
 	startEvent?: Extract<ClaudeHookEvent, { type: "SubagentStart" }>;
@@ -271,18 +292,39 @@ interface PendingReview {
 	error?: string;
 }
 
+/**
+ * The reserved dispatch prompt: the reservation marker line followed by the
+ * per-dispatch snapshot facts, byte for byte.
+ *
+ * One place builds it and one place compares against it, so the marker format
+ * cannot drift from what the binding rule accepts. The static instructions are
+ * deliberately absent: the dispatched reviewer definition carries them, and they
+ * are generated from one source by the plugin build.
+ */
+function reservedDispatchPrompt(
+	request: Pick<ReviewRequest, "operationId" | "taskId" | "snapshotPrompt">,
+): string {
+	return `<!-- immune-brain:operation_id=${request.operationId} task_id=${request.taskId} -->\n${request.snapshotPrompt}`;
+}
+
+/**
+ * Whether hook evidence carrying a prompt belongs to this reservation.
+ *
+ * The prompt is Parent-authored text, so the marker is not an acceptance path:
+ * a dispatch that keeps the matching `operation_id` and `task_id` marker but
+ * appends, truncates or rewrites the body does not bind and cannot settle. Only
+ * the exact reserved dispatch prompt does. Evidence with no prompt at all is
+ * judged by the identifiers the hook itself supplies.
+ */
+function bindsPrompt(prompt: string | undefined, pending: PendingReview): boolean {
+	return prompt === undefined || prompt === pending.dispatchPrompt;
+}
+
 function bindsStart(event: Extract<ClaudeHookEvent, { type: "SubagentStart" }>, pending: PendingReview): boolean {
 	if (event.taskId && event.taskId !== pending.request.taskId) return false;
-	if (event.prompt !== undefined) {
-		const match = /<!-- immune-brain:operation_id=([^\s]+)\s+task_id=([^\s]+)\s+-->/.exec(event.prompt);
-		if (match) {
-			if (match[1] !== pending.request.operationId || match[2] !== pending.request.taskId) return false;
-		} else if (event.prompt !== pending.request.prompt) {
-			return false;
-		}
-	}
+	if (!bindsPrompt(event.prompt, pending)) return false;
 	if (event.operationId) return event.operationId === pending.request.operationId;
-	return event.prompt !== undefined && event.prompt === pending.request.prompt;
+	return event.prompt !== undefined;
 }
 
 export class ClaudeReviewHost implements AssuranceHostPort {
@@ -306,17 +348,19 @@ export class ClaudeReviewHost implements AssuranceHostPort {
 		}
 		this.pending.set(request.operationId, {
 			request,
+			dispatchPrompt: reservedDispatchPrompt(request),
 			initialCursors,
 			sessionCursors,
 			consumed: false,
 		});
 		return {
 			id: request.operationId,
+			// Only parameters the Claude `Agent` tool accepts. The Host has no turn
+			// cap and no background switch, so `request.maxTurns` (which the Pi port
+			// forwards natively) has no receiver here and is not projected.
 			dispatch: {
 				name: CLAUDE_REVIEWER_AGENT,
-				prompt: `<!-- immune-brain:operation_id=${request.operationId} task_id=${request.taskId} -->\n${request.prompt}`,
-				max_turns: request.maxTurns,
-				run_in_background: false,
+				prompt: reservedDispatchPrompt(request),
 			},
 		};
 	}
@@ -419,6 +463,9 @@ export class ClaudeReviewHost implements AssuranceHostPort {
 			if (event.toolName !== AGENT_TOOL) return;
 			if (!event.agentId || !event.operationId || event.operationId !== state.request.operationId) return;
 			if ("taskId" in event && event.taskId && event.taskId !== state.request.taskId) return;
+			// The `Agent` tool input is where this Host actually reports the
+			// dispatched prompt, so it is bound by the same exactness rule.
+			if (!bindsPrompt(event.prompt, state)) return;
 			if (state.startEvent && event.sessionId !== state.startEvent.sessionId) return;
 			if (state.startEvent && event.agentId !== state.startEvent.agentId) return;
 			if (state.stopEvent && event.sessionId !== state.stopEvent.sessionId) return;
@@ -443,7 +490,7 @@ export class ClaudeReviewHost implements AssuranceHostPort {
 			}
 			if (state.stopEvent) {
 				if (state.stopEvent === event) return;
-				state.error = "duplicate SubagentStop observed for review reservation";
+				state.error = "duplicate SubagentStop observed for review reservation: a reviewer was continued after it finished; a reviewer cannot be continued and a fresh reviewer must be dispatched";
 				return;
 			}
 			state.stopEvent = event;

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

@@ -0,0 +1,83 @@
+import type { InternalRole } from "../role_prompt_bridge";
+
+/**
+ * Claude plugin agent definitions for the read-only internal roles.
+ *
+ * A native definition is the strictest boundary the Host can express for these
+ * roles: `Read, Grep, Glob` grants no write, shell or dispatch tool, while the
+ * Pi mapping leaves the same boundary as prompt text. `INTERNAL_ROLE_PROMPTS`
+ * declares `no tools` or `read-only tools` for every role here; a native
+ * definition cannot express an empty allowlist without inheriting every tool,
+ * so read-only-without-shell is what ships.
+ *
+ * The bodies are generated from the matching `runtime/prompts/` source by
+ * `scripts/build-claude-plugin.ts`, never maintained by hand.
+ */
+export interface ClaudeReadonlyRoleAgent {
+	/** The plugin-qualified agent type the Claude `Agent` tool accepts. */
+	readonly agent: string;
+	/** Repository-relative definition the plugin build generates. */
+	readonly definition: string;
+	/** The role prompt source the definition body is generated from. */
+	readonly prompt: string;
+	/** Frontmatter `description`: when the Host may select this agent. */
+	readonly description: string;
+}
+
+export const CLAUDE_READONLY_ROLE_AGENTS = {
+	qa: {
+		agent: "immune-brain:immune-brain-qa",
+		definition: "plugins/immune-brain/agents/immune-brain-qa.md",
+		prompt: "plugins/immune-brain/runtime/prompts/qa.md",
+		description:
+			"Immune-Brain QA authority. Judges recorded execution evidence against one active target and returns one decision.",
+	},
+	"ui-review": {
+		agent: "immune-brain:immune-brain-ui-review",
+		definition: "plugins/immune-brain/agents/immune-brain-ui-review.md",
+		prompt: "plugins/immune-brain/runtime/prompts/ui-review.md",
+		description:
+			"Immune-Brain UI Review authority. Read-only review of a bounded UI change surface and its evidence.",
+	},
+	"advisory-reviewer": {
+		agent: "immune-brain:immune-brain-advisory-reviewer",
+		definition: "plugins/immune-brain/agents/immune-brain-advisory-reviewer.md",
+		prompt: "plugins/immune-brain/runtime/prompts/advisory-reviewer.md",
+		description:
+			"Immune-Brain advisory reviewer for one explicit lens. Read-only advice; synthesis stays with the coordinating Parent.",
+	},
+} as const satisfies Record<string, ClaudeReadonlyRoleAgent>;
+
+/** The read-only roles that ship a generated native definition. */
+export type ClaudeReadonlyRole = keyof typeof CLAUDE_READONLY_ROLE_AGENTS;
+
+export const CLAUDE_READONLY_ROLES = Object.keys(
+	CLAUDE_READONLY_ROLE_AGENTS,
+) as ClaudeReadonlyRole[];
+
+/** The tool allowlist every generated read-only definition declares. */
+export const CLAUDE_READONLY_TOOLS = ["Read", "Grep", "Glob"] as const;
+
+/**
+ * The read-only internal roles that ship no definition because the Host already
+ * provides the agent. `arch-explorer` is architecture discovery: Claude's own
+ * `Explore` agent is the read-only research agent, and shipping a second
+ * definition would fork a boundary the Host owns.
+ */
+export const CLAUDE_HOST_PROVIDED_ROLE_AGENTS = {
+	"arch-explorer": { agent: "Explore" },
+} as const satisfies Record<string, { agent: string }>;
+
+/**
+ * Roles that are not dispatched as native Claude agents.
+ *
+ * `code-review` ships its own definition with a wider allowlist (it must run
+ * read-only Git commands), so it is not part of this table. The remaining roles
+ * write: `executor`, `test-fixer` and `pr-fix` mutate the workspace, and
+ * `compounder` writes learning storage. A write-capable role stays bounded by
+ * its dispatch envelope and the Parent, not by an agent definition.
+ */
+export const CLAUDE_NATIVE_AGENT_ROLES = new Set<InternalRole>([
+	...CLAUDE_READONLY_ROLES,
+	...(Object.keys(CLAUDE_HOST_PROVIDED_ROLE_AGENTS) as InternalRole[]),
+]);

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

@@ -29,7 +29,7 @@ import {
 import { inspectSpecBinding } from "../kernel/spec_binding";
 import { projectTask, resolveProjectedRisk } from "../kernel/completion";
 import { deriveAssuranceAuthorization } from "../kernel/assurance_projection";
-import { taskDiffIdentity, taskRevisionIdentity } from "../workspace_scope";
+import { taskDeliveryIdentity } from "../workspace_scope";
 import type { TaskIntentV1, TaskRisk } from "../kernel/types";
 import {
 	canonicalDescriptorBytes,
@@ -273,10 +273,7 @@ function runInspect(root: string): KernelExecution {
 		const workspaceState = readWorkspaceStateRaw(root);
 		let identity;
 		try {
-			identity =
-				record.contract === "assurance_kernel/task_record/v4"
-					? taskRevisionIdentity(root, intent.scope_hint, record.git_base_head, intent.task_id)
-					: taskDiffIdentity(root, intent.scope_hint, intent.task_id);
+			identity = taskDeliveryIdentity(root, record);
 		} catch (error) {
 			return sourceFailure("inspect", error);
 		}
@@ -571,7 +568,7 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
 				"rejected",
 				"kernel_owner_active",
 				null,
-				"Route to imm-loop instead of authoring a new draft.",
+				"Route to imm-run instead of authoring a new draft.",
 			),
 		};
 	if (owner.v3)