brl-subagent 2.3.7 → 2.3.9

package/src/index.ts

@@ -65,6 +65,7 @@ import {
 	mergeWorkBranch,
 } from "./git";
 import { preflightCheck } from "./preflight";
+import { gateSessionCost, rejectApprovalAlwaysInBackground, runPreTaskValidation, validateDelegationTargets, formatValidationWarnings } from "./prelude";
 import { loadBuiltinPresets, loadCustomPresets, getAllPresets, writePresetFile, formatPresetRestriction, formatToolRestriction } from "./presets";
 import { modelIsAvailable } from "./model-availability";
 import { validatePreTask, diagnoseFailure } from "./validate";
@@ -399,6 +400,14 @@ export default function (pi: ExtensionAPI) {
 		};
 	}
 
+	// Per-unit display name for validation prefixes: the label when present,
+	// else the task truncated to 60 chars. Shared by the foreground parallel
+	// pre-pass and the background fan-out pre-pass (issue #220) so a unit
+	// renders identically in either shape.
+	const displayTaskName = (merged: ReturnType<typeof mergeSubTaskParams>): string =>
+		merged.label ??
+		(merged.task.length > 60 ? `${merged.task.slice(0, 57)}...` : merged.task);
+
 	// -------------------------------------------------------------------
 	// P1: runChainMode
 	// -------------------------------------------------------------------
@@ -416,32 +425,14 @@ export default function (pi: ExtensionAPI) {
 		const chainModeStartedAt = new Date().toISOString();
 
 		// R5: Check session cost limit before spawning
-		const perTaskEstimate =
-			state.config.perTaskCostEstimate > 0
-				? state.config.perTaskCostEstimate
-				: 0.05;
-		if (state.checkCostLimit(perTaskEstimate * chainSteps.length, ctx)) {
-			const currentTotal = state.getSessionTotalCost(ctx);
-			const limit = state.config.sessionCostLimit;
-			log.warn("Chain delegation rejected: session cost limit reached", {
-				currentTotal,
-				estimatedCost: perTaskEstimate * chainSteps.length,
-				limit,
-			});
-			return {
-				content: [
-					{
-						type: "text" as const,
-						text:
-							`Cannot delegate: session cost limit reached ` +
-							`($${currentTotal.toFixed(4)} spent of $${limit.toFixed(2)} limit). ` +
-							`Increase the limit via /brl-subagent costlimit or set to 0 for unlimited.`,
-					},
-				],
-				details: undefined,
-				isError: true,
-			};
-		}
+		const costError = gateSessionCost({
+			state,
+			ctx,
+			log,
+			units: chainSteps.length,
+			label: "Chain delegation",
+		});
+		if (costError) return costError;
 
 		// Reject delegation if recursion depth exceeds configured max
 		const currentDepth = getCurrentDepth();
@@ -521,7 +512,8 @@ export default function (pi: ExtensionAPI) {
 		// #32). Chain top-level tasks are empty (modeCount forbids task+chain), so
 		// keyword warnings skip on empty text and only the hard outputFile-vs-write
 		// conflict applies (issue #34). The mode-level outputFile on globalParams is
-		// the one validated; per-step outputFiles are future work (issue #3).
+		// the one validated here; every step's own cwd/outputFile/tools are
+		// validated by the per-step pre-pass below (issue #222).
 		const validation = validatePreTask({
 			task: globalParams.task,
 			toolOptions: globalParams.toolOptions,
@@ -542,6 +534,47 @@ export default function (pi: ExtensionAPI) {
 			};
 		}
 
+		// Per-step pre-pass (issue #222): resolve + validate EVERY step before
+		// any spawn, so a single bad step rejects the chain with nothing
+		// started — the same all-before-any-spawn semantics the background
+		// fan-out and the parallel `tasks` shape use. Chain steps are fully
+		// known up front and a step's cwd/outputFile never depend on a previous
+		// step's output (only its TASK text consumes {previous}), so the pass
+		// can run up front — and must, because discovering step 5's bad cwd
+		// after four steps already ran would waste their whole budget.
+		const stepCwds: string[] = [];
+		const stepWarnings: string[] = [];
+		for (let i = 0; i < chainSteps.length; i++) {
+			const merged = mergeSubTaskParams(globalParams, chainSteps[i]);
+			const stepPrefix = `Step ${i + 1} ("${displayTaskName(merged)}")`;
+
+			const stepTargets = validateDelegationTargets({
+				ctx,
+				effectiveCwd: merged.effectiveCwd,
+				outputFile: merged.outputFile,
+				prefix: stepPrefix,
+			});
+			if (!stepTargets.ok) return stepTargets.error;
+			stepCwds.push(stepTargets.cwd);
+
+			const stepValidation = runPreTaskValidation({
+				log,
+				label: "Chain",
+				prefix: stepPrefix,
+				logContext: { step: i + 1 },
+				preTask: {
+					task: merged.task,
+					toolOptions: merged.toolOptions,
+					thinkingLevel: merged.thinkingLevel,
+					gitMode: globalParams.resolvedGitMode,
+					outputFile: merged.outputFile,
+					force: params.force as boolean | undefined,
+				},
+			});
+			if (stepValidation.error) return stepValidation.error;
+			for (const w of stepValidation.warnings) stepWarnings.push(`${stepPrefix}: ${w}`);
+		}
+
 		// Resolve model once (per-call top-level model override beats preset)
 		const modelResult = resolveSubagentModel(ctx, globalParams.resolvedPreset, params.model as string | undefined);
 		if (!modelResult.ok) return modelResult.error;
@@ -706,7 +739,10 @@ export default function (pi: ExtensionAPI) {
 				let result: SubagentResult;
 				try {
 					result = await runSubagent(
-						resolvedCwd,
+						// Issue #222: this step's OWN validated cwd (the pre-pass
+						// resolved it against ctx.cwd) — the mode-level
+						// resolvedCwd is the fallback for steps that declare none.
+						stepCwds[i],
 						subagentPrompt,
 						stepModel,
 						merged.thinkingLevel,
@@ -724,7 +760,7 @@ export default function (pi: ExtensionAPI) {
 					// run entry as failed — crashOutput comes from the live entry's
 					// last streamed output (the crash result itself has no
 					// messages), and errorCategory is classified onto originalParams.
-					finalizeUnitRunCrash(state, pi, run, err, "Chain step", resolvedCwd, log, {
+					finalizeUnitRunCrash(state, pi, run, err, "Chain step", stepCwds[i], log, {
 						step: i + 1,
 					});
 				}
@@ -869,9 +905,15 @@ export default function (pi: ExtensionAPI) {
 			};
 			state.persistRun(pi, chainAggregateRun);
 
+			// Per-step validation warnings ride the result, prefixed with their
+			// step (issue #222), after the JSON payload — empty renders nothing so
+			// warning-free results stay byte-identical.
 			return {
 				content: [
-					{ type: "text" as const, text: JSON.stringify(chainDetails, null, 2) },
+					{
+						type: "text" as const,
+						text: JSON.stringify(chainDetails, null, 2) + formatValidationWarnings(stepWarnings),
+					},
 				],
 				details: chainDetails,
 			};
@@ -903,32 +945,14 @@ export default function (pi: ExtensionAPI) {
 		const taskList = params.tasks as SubTaskParams[];
 
 		// R5: Check session cost limit before spawning
-		const perTaskEstimate =
-			state.config.perTaskCostEstimate > 0
-				? state.config.perTaskCostEstimate
-				: 0.05;
-		if (state.checkCostLimit(perTaskEstimate * taskList.length, ctx)) {
-			const currentTotal = state.getSessionTotalCost(ctx);
-			const limit = state.config.sessionCostLimit;
-			log.warn("Parallel delegation rejected: session cost limit reached", {
-				currentTotal,
-				estimatedCost: perTaskEstimate * taskList.length,
-				limit,
-			});
-			return {
-				content: [
-					{
-						type: "text" as const,
-						text:
-							`Cannot delegate: session cost limit reached ` +
-							`($${currentTotal.toFixed(4)} spent of $${limit.toFixed(2)} limit). ` +
-							`Increase the limit via /brl-subagent costlimit or set to 0 for unlimited.`,
-					},
-				],
-				details: undefined,
-				isError: true,
-			};
-		}
+		const costError = gateSessionCost({
+			state,
+			ctx,
+			log,
+			units: taskList.length,
+			label: "Parallel delegation",
+		});
+		if (costError) return costError;
 
 		// Reject delegation if recursion depth exceeds configured max
 		const currentDepth = getCurrentDepth();
@@ -975,17 +999,9 @@ export default function (pi: ExtensionAPI) {
 		);
 
 		// Validate CWD once
-		const cwdResult = validateCwd(globalParams.effectiveCwd, ctx.cwd);
-		if (!cwdResult.ok) {
-			return {
-				content: [
-					{ type: "text" as const, text: `Invalid cwd: ${cwdResult.error}` },
-				],
-				details: undefined,
-				isError: true,
-			};
-		}
-		const resolvedCwd = cwdResult.value;
+		const targets = validateDelegationTargets({ ctx, effectiveCwd: globalParams.effectiveCwd });
+		if (!targets.ok) return targets.error;
+		const resolvedCwd = targets.cwd;
 
 		// Pre-flight checks — fail fast before consuming resources
 		const pfResult = preflightCheck(resolvedCwd);
@@ -1008,26 +1024,64 @@ export default function (pi: ExtensionAPI) {
 		// #32). Parallel top-level tasks are empty (modeCount forbids task+tasks),
 		// so keyword warnings skip on empty text and only the hard
 		// outputFile-vs-write conflict applies (issue #34). The mode-level
-		// outputFile on globalParams is the one validated; per-step outputFiles
-		// are future work (issue #3).
-		const validation = validatePreTask({
-			task: globalParams.task,
-			toolOptions: globalParams.toolOptions,
-			thinkingLevel: globalParams.thinkingLevel,
-			gitMode: globalParams.resolvedGitMode,
-			outputFile: globalParams.outputFile,
+		// outputFile on globalParams is the one validated here; every task's own
+		// cwd/outputFile/tools are validated by the per-task pre-pass below
+		// (issue #222).
+		const preTask = runPreTaskValidation({
+			log,
+			label: "Parallel",
+			preTask: {
+				task: globalParams.task,
+				toolOptions: globalParams.toolOptions,
+				thinkingLevel: globalParams.thinkingLevel,
+				gitMode: globalParams.resolvedGitMode,
+				outputFile: globalParams.outputFile,
+			},
 		});
-		if (validation.warnings.length > 0) {
-			log.warn("Parallel pre-task validation warnings", { warnings: validation.warnings });
-		}
-		if (!validation.valid) {
-			const errText = validation.errors.join("; ");
-			log.warn("Parallel pre-task validation failed", { errors: validation.errors });
-			return {
-				content: [{ type: "text" as const, text: errText }],
-				details: undefined,
-				isError: true,
-			};
+		if (preTask.error) return preTask.error;
+
+		// Per-task pre-pass (issue #220, extended by #222): validate EVERY task
+		// before any spawn, so a single bad task rejects the batch with nothing
+		// started (`force` degrades capability errors to warnings) — the same
+		// semantics runBackgroundFanOut applies. Each task's OWN cwd is resolved
+		// and validated here (with its outputFile, resolved against that cwd) and
+		// the resolved value is what that task spawns in — issue #222 closed the
+		// gap where a per-task `cwd` was merged but the spawn still used the
+		// mode-level cwd. Per-task warnings are prefixed with their unit and
+		// collected here to ride the final result. The mode-entry validation
+		// above stays for the mode-level outputFile (issue #34).
+		const taskWarnings: string[] = [];
+		// Parallel index → the task's own validated cwd (issue #222).
+		const taskCwds: string[] = [];
+		for (let i = 0; i < taskList.length; i++) {
+			const merged = mergeSubTaskParams(globalParams, taskList[i]);
+			const taskPrefix = `Task ${i + 1} ("${displayTaskName(merged)}")`;
+
+			const taskTargets = validateDelegationTargets({
+				ctx,
+				effectiveCwd: merged.effectiveCwd,
+				outputFile: merged.outputFile,
+				prefix: taskPrefix,
+			});
+			if (!taskTargets.ok) return taskTargets.error;
+			taskCwds.push(taskTargets.cwd);
+
+			const unitValidation = runPreTaskValidation({
+				log,
+				label: "Parallel",
+				prefix: taskPrefix,
+				logContext: { task: i + 1 },
+				preTask: {
+					task: merged.task,
+					toolOptions: merged.toolOptions,
+					thinkingLevel: merged.thinkingLevel,
+					gitMode: globalParams.resolvedGitMode,
+					outputFile: merged.outputFile,
+					force: params.force as boolean | undefined,
+				},
+			});
+			if (unitValidation.error) return unitValidation.error;
+			for (const w of unitValidation.warnings) taskWarnings.push(`${taskPrefix}: ${w}`);
 		}
 
 		// Resolve model once (per-call top-level model override beats preset)
@@ -1078,6 +1132,7 @@ export default function (pi: ExtensionAPI) {
 		const runTask = async (
 			index: number,
 			merged: ReturnType<typeof mergeSubTaskParams>,
+			unitCwd: string,
 		): Promise<boolean> => {
 
 			// C3: Resolve this step's model override (step.model > global resolved model)
@@ -1154,7 +1209,8 @@ export default function (pi: ExtensionAPI) {
 			// the live ghost (grace logic treats a 'running' record as live).
 			try {
 				const result = await runSubagent(
-					resolvedCwd,
+					// Issue #222: this task's OWN validated cwd.
+					unitCwd,
 					subagentPrompt,
 					stepModel,
 					merged.thinkingLevel,
@@ -1197,7 +1253,7 @@ export default function (pi: ExtensionAPI) {
 				// the live drill-in loops forever. finalizeLiveSubagent is
 				// idempotent; the rethrow keeps Promise.allSettled semantics (the
 				// caller's finally still releases the concurrency slot).
-				finalizeUnitRunCrash(state, pi, run, err, "Parallel subtask", resolvedCwd, log, {
+				finalizeUnitRunCrash(state, pi, run, err, "Parallel subtask", unitCwd, log, {
 					index,
 				});
 			}
@@ -1275,7 +1331,7 @@ export default function (pi: ExtensionAPI) {
 			}
 			let taskSuccess = false;
 			try {
-				taskSuccess = await runTask(index, merged);
+				taskSuccess = await runTask(index, merged, taskCwds[index]);
 			} finally {
 				// Issue #137: release with the unit's real success — the status
 				// bar's "N failed" count reflects the true outcome.
@@ -1332,9 +1388,15 @@ export default function (pi: ExtensionAPI) {
 			totalCost,
 		});
 
+		// C: per-task validation warnings ride the result, prefixed with their
+		// task (issue #220), after the JSON payload — empty renders nothing so
+		// warning-free results stay byte-identical.
 		return {
 			content: [
-				{ type: "text" as const, text: JSON.stringify(parallelDetails, null, 2) },
+				{
+					type: "text" as const,
+					text: JSON.stringify(parallelDetails, null, 2) + formatValidationWarnings(taskWarnings),
+				},
 			],
 			details: parallelDetails,
 		};
@@ -1372,32 +1434,14 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		// R5: Check session cost limit before spawning
-		const perTaskEstimate =
-			state.config.perTaskCostEstimate > 0
-				? state.config.perTaskCostEstimate
-				: 0.05;
-		if (state.checkCostLimit(perTaskEstimate * graphTasks.length, ctx)) {
-			const currentTotal = state.getSessionTotalCost(ctx);
-			const limit = state.config.sessionCostLimit;
-			log.warn("Graph delegation rejected: session cost limit reached", {
-				currentTotal,
-				estimatedCost: perTaskEstimate * graphTasks.length,
-				limit,
-			});
-			return {
-				content: [
-					{
-						type: "text" as const,
-						text:
-							`Cannot delegate: session cost limit reached ` +
-							`($${currentTotal.toFixed(4)} spent of $${limit.toFixed(2)} limit). ` +
-							`Increase the limit via /brl-subagent costlimit or set to 0 for unlimited.`,
-					},
-				],
-				details: undefined,
-				isError: true,
-			};
-		}
+		const costError = gateSessionCost({
+			state,
+			ctx,
+			log,
+			units: graphTasks.length,
+			label: "Graph delegation",
+		});
+		if (costError) return costError;
 
 		// Reject delegation if recursion depth exceeds configured max
 		const currentDepth = getCurrentDepth();
@@ -1478,8 +1522,9 @@ export default function (pi: ExtensionAPI) {
 		// #32). Graph top-level tasks are empty (modeCount forbids task+graph),
 		// so keyword warnings skip on empty text and only the hard
 		// outputFile-vs-write conflict applies (issue #34). The mode-level
-		// outputFile on globalParams is the one validated; per-step outputFiles
-		// are future work (issue #3).
+		// outputFile on globalParams is the one validated here; every node's own
+		// cwd/outputFile/tools are validated by the per-node pre-pass below
+		// (issue #222).
 		const validation = validatePreTask({
 			task: globalParams.task,
 			toolOptions: globalParams.toolOptions,
@@ -1555,6 +1600,73 @@ export default function (pi: ExtensionAPI) {
 		}
 		const waves = sortResult.waves;
 
+		// Per-node pre-pass (issue #222): resolve + validate EVERY node before
+		// any spawn, so a single bad node rejects the whole graph with nothing
+		// started — the same all-before-any-spawn semantics the background
+		// fan-out, the parallel `tasks` shape and the chain use. Each node's OWN
+		// cwd is resolved and validated here (with its outputFile, resolved
+		// against that cwd) and the resolved value is what that node spawns in.
+		// The pre-pass runs on the DECLARED task text, before {id} substitution
+		// (the substituted text is only known mid-dispatch, once a dependency's
+		// output exists) — the declared text is validated with the placeholder
+		// TOKENS stripped (a dependency whose id happens to be a blocking
+		// keyword must not make `{<id>}` itself trip the keyword rules), while
+		// the SUBSTITUTED content stays unvalidated by design. The host's own
+		// wording is still validated, and refusing to validate up front would
+		// mean a bad node in the LAST wave is discovered after every earlier
+		// wave already spent its budget.
+		const nodeCwds = new Map<string, string>();
+		const nodeWarnings: string[] = [];
+		for (const graphTask of graphTasks) {
+			const merged = mergeSubTaskParams(globalParams, {
+				task: graphTask.task,
+				label: graphTask.label,
+				model: graphTask.model,
+				thinkingLevel: graphTask.thinkingLevel,
+				priority: graphTask.priority,
+				cwd: graphTask.cwd,
+				timeout: graphTask.timeout,
+				outputFile: graphTask.outputFile,
+				tools: graphTask.tools,
+				excludeTools: graphTask.excludeTools,
+				noBuiltinTools: graphTask.noBuiltinTools,
+				systemPrompt: graphTask.systemPrompt,
+				inheritSystemPrompt: graphTask.inheritSystemPrompt,
+			});
+			const nodePrefix = `Node "${graphTask.id}"`;
+
+			const nodeTargets = validateDelegationTargets({
+				ctx,
+				effectiveCwd: merged.effectiveCwd,
+				outputFile: merged.outputFile,
+				prefix: nodePrefix,
+			});
+			if (!nodeTargets.ok) return nodeTargets.error;
+			nodeCwds.set(graphTask.id, nodeTargets.cwd);
+
+			const nodeValidation = runPreTaskValidation({
+				log,
+				label: "Graph",
+				prefix: nodePrefix,
+				logContext: { id: graphTask.id },
+				preTask: {
+					// Placeholder TOKENS stripped (issue #222 review): the rules
+					// read the declared string, so a `{<id>}` whose dependency id
+					// is a blocking keyword would block on a token, not on text
+					// the host wrote. The declared wording around it is unchanged
+					// and still validated.
+					task: merged.task.replace(GRAPH_OUTPUT_PLACEHOLDER_RE, " "),
+					toolOptions: merged.toolOptions,
+					thinkingLevel: merged.thinkingLevel,
+					gitMode: globalParams.resolvedGitMode,
+					outputFile: merged.outputFile,
+					force: params.force as boolean | undefined,
+				},
+			});
+			if (nodeValidation.error) return nodeValidation.error;
+			for (const w of nodeValidation.warnings) nodeWarnings.push(`${nodePrefix}: ${w}`);
+		}
+
 		// Build base prompt once
 		const basePrompt = ctx.getSystemPrompt();
 
@@ -1626,6 +1738,10 @@ export default function (pi: ExtensionAPI) {
 					};
 
 					const merged = mergeSubTaskParams(globalParams, subTaskParams);
+					// Issue #222: the node's OWN validated cwd (pre-pass);
+					// resolvedCwd (the mode-level cwd) is the guaranteed
+					// fallback, so a node that declares none still resolves.
+					const nodeCwd = nodeCwds.get(graphTask.id) ?? resolvedCwd;
 
 					// C3: Resolve this step's model override (step.model > global resolved model)
 					const stepModel = resolveStepModel(ctx, merged.model, subagentModel);
@@ -1709,7 +1825,7 @@ export default function (pi: ExtensionAPI) {
 						const stepOnUpdate = makeLiveOnUpdate(state, runId, onUpdate);
 
 						const result = await runSubagent(
-							resolvedCwd,
+							nodeCwd,
 							subagentPrompt,
 							stepModel,
 							merged.thinkingLevel,
@@ -1760,7 +1876,7 @@ export default function (pi: ExtensionAPI) {
 						// finalizeLiveSubagent is idempotent; the rethrow keeps
 						// Promise.allSettled semantics (a failing node must NOT cancel
 						// sibling nodes in the wave).
-						finalizeUnitRunCrash(state, pi, run, err, "Graph node", resolvedCwd, log, {
+						finalizeUnitRunCrash(state, pi, run, err, "Graph node", nodeCwd, log, {
 							id: graphTask.id,
 						});
 					} finally {
@@ -1857,9 +1973,15 @@ export default function (pi: ExtensionAPI) {
 			};
 			state.persistRun(pi, graphAggregateRun);
 
+			// Per-node validation warnings ride the result, prefixed with their
+			// node id (issue #222), after the JSON payload — empty renders
+			// nothing so warning-free results stay byte-identical.
 			return {
 				content: [
-					{ type: "text" as const, text: JSON.stringify(graphDetails, null, 2) },
+					{
+						type: "text" as const,
+						text: JSON.stringify(graphDetails, null, 2) + formatValidationWarnings(nodeWarnings),
+					},
 				],
 				details: graphDetails,
 			};
@@ -1878,6 +2000,666 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
+	// -------------------------------------------------------------------
+	// runBackgroundFanOut — background fan-out for tasks mode.
+	// Resolves + validates the WHOLE batch up front (no spawn on any
+	// failure), then spawns the tasks sequentially, in task order, through the
+	// shared startBackgroundAgent tail, and returns immediately with their ids.
+	// Foreground-only gates (preflight, circuit breaker, recursion depth) are
+	// deliberately skipped — the single-background path skips them too.
+	// -------------------------------------------------------------------
+
+	async function runBackgroundFanOut(
+		pi: ExtensionAPI,
+		ctx: ExtensionContext,
+		params: Record<string, unknown>,
+		signal: AbortSignal | undefined,
+	): Promise<ToolResult<SubagentResult | undefined>> {
+		const taskList = params.tasks as SubTaskParams[];
+
+		// Session cost limit gates the WHOLE batch before any spawn — same
+		// estimate/limit logic as runParallelMode, scaled by task count.
+		const costError = gateSessionCost({
+			state,
+			ctx,
+			log,
+			units: taskList.length,
+			label: "Background fan-out",
+		});
+		if (costError) return costError;
+
+		// Resolve global params once — same call shape as runParallelMode.
+		const globalParams = resolveSubagentParams(
+			params as {
+				task: string;
+				label?: string;
+				preset?: string;
+				systemPrompt?: string;
+				inheritSystemPrompt?: boolean;
+				thinkingLevel?: string;
+				outputFile?: string;
+				timeout?: number;
+				cwd?: string;
+				tools?: string[];
+				excludeTools?: string[];
+				noBuiltinTools?: boolean;
+				gitMode?: string;
+			},
+			state,
+			ctx,
+			log,
+		);
+
+		// Resolve the global model once (per-call model beats preset/config).
+		const globalModelResult = resolveSubagentModel(
+			ctx,
+			globalParams.resolvedPreset,
+			params.model as string | undefined,
+		);
+		if (!globalModelResult.ok) return globalModelResult.error;
+		const globalModel = globalModelResult.model;
+
+		// Same rejection as the single-background path: approvalMode 'always'
+		// cannot work in background — there is no interactive dialog to approve
+		// the diff, for any of the N agents.
+		const approvalError = rejectApprovalAlwaysInBackground(globalParams.resolvedApprovalMode);
+		if (approvalError) return approvalError;
+		// W5 parity with the single-background path: 'writes' silently
+		// auto-approves in background — warn once so the caller knows none of
+		// the N agents' diffs will be gated on approval.
+		if (globalParams.resolvedApprovalMode === 'writes') {
+			log.warn("Background fan-out spawned with approvalMode 'writes' — auto-approving (no dialog in background)", {
+				tasks: taskList.length,
+			});
+		}
+
+		// gitMode 'branch' is rejected for the whole batch: the per-repository
+		// git lock is awaited inside the first spawn and held until that agent
+		// settles, so same-repository branch-mode spawns would serialize and
+		// block this call for the whole chain. The rule is blanket (not
+		// per-repository-checked) because the lock is keyed by the resolved
+		// repository root: units in different directories of one repo share the
+		// working tree and contend for the same lock.
+		if (globalParams.resolvedGitMode === 'branch') {
+			return {
+				content: [{ type: "text" as const, text:
+					`Cannot start ${taskList.length} background agents with gitMode 'branch': the per-repository git lock ` +
+					`is awaited by the first spawn and held until that agent settles, so same-repository branch-mode ` +
+					`spawns would serialize and block this call for the whole chain. Background fan-out therefore ` +
+					`rejects gitMode 'branch' for all tasks in this version. Use gitMode 'none' for the batch, or ` +
+					`dispatch each unit as a separate single-task background call.`
+				}],
+				details: undefined,
+				isError: true,
+			};
+		}
+
+		// Per-task pre-pass: resolve + validate EVERYTHING before any spawn, so a
+		// single bad task rejects the whole batch with nothing started.
+		type FanOutTask = {
+			merged: ReturnType<typeof mergeSubTaskParams>;
+			model: { provider: string; id: string };
+			cwd: string;
+			outputFile: string | undefined;
+		};
+
+		const fanOutTasks: FanOutTask[] = [];
+		// C: per-task warnings collect here to ride the immediate spawn result.
+		const taskWarnings: string[] = [];
+		for (let i = 0; i < taskList.length; i++) {
+			const merged = mergeSubTaskParams(globalParams, taskList[i]);
+			const name = displayTaskName(merged);
+			const taskPrefix = `Task ${i + 1} ("${name}")`;
+			// Per-task model override wins; the global model is the fallback.
+			const stepModel = resolveStepModel(ctx, merged.model, globalModel);
+
+			const targets = validateDelegationTargets({
+				ctx,
+				effectiveCwd: merged.effectiveCwd,
+				outputFile: merged.outputFile,
+				prefix: taskPrefix,
+			});
+			if (!targets.ok) return targets.error;
+
+			const preTask = runPreTaskValidation({
+				log,
+				label: "Background fan-out",
+				prefix: taskPrefix,
+				logContext: { task: i + 1 },
+				preTask: {
+					task: merged.task,
+					toolOptions: merged.toolOptions,
+					thinkingLevel: merged.thinkingLevel,
+					gitMode: globalParams.resolvedGitMode,
+					outputFile: merged.outputFile,
+					force: params.force as boolean | undefined,
+				},
+			});
+			if (preTask.error) return preTask.error;
+			for (const w of preTask.warnings) taskWarnings.push(`${taskPrefix}: ${w}`);
+
+			fanOutTasks.push({ merged, model: stepModel, cwd: targets.cwd, outputFile: targets.outputFile });
+		}
+
+		// Spawn pass — sequential, in task order, through the shared tail.
+		const started: Array<{ id: string; label?: string }> = [];
+		const startedIdsText = (): string => started.map((s) => s.id).join(", ");
+
+		for (let i = 0; i < fanOutTasks.length; i++) {
+			if (signal?.aborted) {
+				if (started.length === 0) {
+					return {
+						content: [{ type: "text" as const, text: `Background fan-out cancelled before any agent started.` }],
+						details: undefined,
+						isError: true,
+					};
+				}
+				return {
+					content: [{ type: "text" as const, text:
+						`Background fan-out cancelled after starting ${started.length} of ${fanOutTasks.length} agents ` +
+						`(${startedIdsText()}) — they are detached and will still wake you.`
+					}],
+					details: undefined,
+					isError: true,
+				};
+			}
+
+			const { merged, model, cwd, outputFile } = fanOutTasks[i];
+			const name = displayTaskName(merged);
+			const subagentPrompt = buildSubagentPrompt(
+				ctx.getSystemPrompt(),
+				merged.inheritSP,
+				merged.customSP,
+				outputFile,
+				merged.toolOptions?.tools,
+				globalParams.resolvedPreset?.promptGuideline,
+			);
+			const unitPriority = merged.priority ?? (params.priority as string | undefined);
+
+			let agent: BackgroundAgent;
+			try {
+				agent = await startBackgroundAgent(pi, ctx, {
+					task: merged.task,
+					type: (params.preset as string | undefined) || 'general-purpose',
+					description: merged.label,
+					model: `${model.provider}/${model.id}`,
+					thinkingLevel: merged.thinkingLevel,
+					priority: unitPriority,
+					systemPrompt: subagentPrompt,
+					cwd,
+					toolOptions: merged.toolOptions,
+					timeout: merged.timeout,
+					gitMode: globalParams.resolvedGitMode,
+					// Retry parity with createUnitRun: snapshot this unit's resolved
+					// values so a retry restores them. The execution-shape fields
+					// (background/gitMode/approvalMode/force) are deliberately NOT
+					// passed here — a fan-out unit is spec'd to retry as a single
+					// run, so it must not inherit this spawn's background-ness.
+					// Same omission in unit-run.ts's createUnitRun.
+					originalParams: snapshotOriginalParams({
+						systemPrompt: merged.customSP,
+						inheritSystemPrompt: merged.inheritSP,
+						model: merged.model,
+						thinkingLevel: merged.thinkingLevel,
+						priority: unitPriority,
+						outputFile: merged.outputFile,
+						timeout: merged.timeout,
+						cwd: merged.effectiveCwd,
+						tools: merged.toolOptions?.tools,
+						excludeTools: merged.toolOptions?.excludeTools,
+						noBuiltinTools: merged.toolOptions?.noBuiltinTools,
+						preset: globalParams.resolvedPreset?.name,
+					}),
+					sanitizeCwd: merged.effectiveCwd,
+				});
+			} catch (err) {
+				const message = sanitizeErrorMessage(
+					err instanceof Error ? err.message : String(err),
+					merged.effectiveCwd,
+				);
+				log.error("Background fan-out spawn failed", { task: i + 1, error: message });
+				const alreadyStarted = started.length > 0
+					? `\n\nAlready started: ${startedIdsText()} — they are detached and will still wake you.`
+					: "";
+				return {
+					content: [{ type: "text" as const, text:
+						`Failed to spawn background agent for Task ${i + 1} ("${name}"): ${message}` + alreadyStarted
+					}],
+					details: undefined,
+					isError: true,
+				};
+			}
+			started.push({ id: agent.id, label: merged.label });
+		}
+
+		// Text-only result: ids in task order + the wake hint. C: per-task
+		// validation warnings ride the immediate SPAWN result (prefixed with
+		// their task) so the conductor can stop/re-dispatch in the same turn.
+		const lines = started
+			.map((s, i) => `${i + 1}. ${s.label ? `"${s.label}" ` : ""}— ${s.id}`)
+			.join("\n");
+		return {
+			content: [{ type: "text" as const, text:
+				`Background agents started: ${started.length}\n\n` +
+				`${lines}\n\n` +
+				`You'll be woken with a completion message as each finishes; use get_subagent_result({ agent_id }) for retrieval and stall checks.` +
+				formatValidationWarnings(taskWarnings)
+			}],
+			details: undefined,
+		};
+	}
+
+	// -------------------------------------------------------------------
+	// startBackgroundAgent — the shared background-spawn tail.
+	// Used by BOTH spawnBackgroundRun (single task) and runBackgroundFanOut
+	// (tasks fan-out): the session-manager import, the spawn call, live-monitor
+	// registration, footer counters, the 2s progress poller and the hard-cap
+	// timer live here exactly once. Callers keep their own prelude, checks,
+	// validations and result formatting. THROWS on spawn failure — callers
+	// translate the error into their own result shape.
+	// -------------------------------------------------------------------
+
+	async function startBackgroundAgent(
+		pi: ExtensionAPI,
+		ctx: ExtensionContext,
+		spawn: {
+			task: string;
+			type?: string;
+			description?: string;
+			model?: string;
+			thinkingLevel: ThinkingLevel;
+			priority?: string;
+			systemPrompt: string;
+			cwd: string;
+			toolOptions?: SubagentToolOptions;
+			timeout?: number;
+			gitMode: GitMode;
+			originalParams?: SubagentRun["originalParams"];
+			/** cwd used to redact paths from crash notifications. */
+			sanitizeCwd: string;
+		},
+	): Promise<BackgroundAgent> {
+		const { spawnBackgroundSession, setAgentFinalOutput, extractFinalOutput, updateAgentStatus } = await import('./session-manager');
+		// Issue #31 (PR #76 review, DRY): extract final output from a
+		// possibly-released ref — the poller may observe a terminal agent
+		// whose ref was already nulled by the settlement path.
+		const extractAgentFinalOutput = (a: BackgroundAgent): string =>
+			extractFinalOutput(a._sessionRef ?? { messages: [] });
+
+		const agent = await spawnBackgroundSession(pi, ctx, {
+			task: spawn.task,
+			type: spawn.type,
+			description: spawn.description,
+			model: spawn.model,
+			thinkingLevel: spawn.thinkingLevel,
+			// Issue #114: per-unit priority rides the spawn so the background
+			// run entry + drill-in header carry it like foreground runs.
+			priority: spawn.priority,
+			systemPrompt: spawn.systemPrompt,
+			cwd: spawn.cwd,
+			toolOptions: spawn.toolOptions,
+			timeout: spawn.timeout,
+			gitMode: spawn.gitMode,
+			// Issue #98/#108: snapshotOriginalParams is the single source of truth
+			// for the caller params a later retry restores.
+			originalParams: spawn.originalParams,
+		});
+		
+		// Register for live monitor
+		state.registerLiveSubagent(agent.id, {
+			id: agent.id,
+			label: agent.description,
+			task: agent.task,
+			model: agent.model,
+			thinkingLevel: agent.thinkingLevel,
+			priority: agent.priority,
+			startedAt: agent.startedAt,
+			ctx,
+		});
+		
+		// Update footer counters
+		state.activeSubagents++;
+		updateProgressStatus(state, ctx);
+
+		let completed = false;
+		
+		// Poll for live progress
+		const pollInterval = setInterval(() => {
+			try {
+				if (completed) return;
+				
+				const session = agent._sessionRef;
+				// Issue #31: a nulled ref on a TERMINAL agent is expected (the
+				// settlement path releases the ref) — fall through to finalize
+				// below instead of treating it as a crash. A nulled ref on a
+				// live agent is still a crash.
+				if (!session && !agent.completedAt) {
+					// Session ref not available — session may have crashed.
+					// Defensive: the ref is assigned synchronously before the poller starts
+					// and is never nulled, so this is mostly unreachable — but keep the
+					// bookkeeping safe regardless.
+					completed = true;
+					clearInterval(pollInterval);
+					clearTimeout(hardCapHandle);
+					// Capture whatever output exists (may be empty — fine).
+					setAgentFinalOutput(agent.id, state.subagentSessions.get(agent.id)?.liveOutput ?? '');
+					// Gate the counter on the finalize claim: if the
+					// stale sweep already finalized this entry, the
+					// decrement happened there (PR #71 review).
+					if (state.finalizeLiveSubagent(agent.id)) {
+						state.activeSubagents--;
+						if (state.activeSubagents < 0) state.activeSubagents = 0;
+					}
+					state.failedSubagents++;
+					updateProgressStatus(state, ctx);
+					pi.sendMessage({
+						customType: "subagent-notification",
+						content: `Background agent "${agent.description}" crashed.`,
+						display: true,
+						details: { agentId: agent.id }
+					}, { deliverAs: "followUp" });
+					return;
+				}
+				
+				// While running, update the live monitor.
+				// Once completedAt is set, skip straight to finalize below.
+				// Issue #31: past the guard above, the only nulled-ref path left is a
+				// TERMINAL agent (settlement releases the ref), so a live agent always
+				// has its session — the guard already returned on the live-nulled-ref
+				// crash path. The compiler can't correlate the two checks, so assert it.
+				if (!agent.completedAt) {
+					const finalOutput = extractFinalOutput(session!);
+					
+					try {
+						const stats = session!.getSessionStats();
+						state.updateLiveSubagent(agent.id, finalOutput, stats.tokens.input, stats.tokens.output);
+					} catch {
+						state.updateLiveSubagent(agent.id, finalOutput, 0, 0);
+					}
+				}
+				
+				// Authoritative completion: the prompt promise settled — status and
+				// completedAt are set by .then()/.catch() in spawnBackgroundSession.
+				// Do NOT rely on !session.isStreaming: it is false during prompt()
+				// preflight (auth check, model resolution) and for failed starts.
+				if (agent.completedAt) {
+					completed = true;
+					clearInterval(pollInterval);
+					clearTimeout(hardCapHandle);
+					
+					// Issue #31: prefer the output already captured at settlement;
+					// the ref may already be nulled on terminal agents, so never
+					// overwrite with empty and stay null-safe.
+					const finalOutput = agent.finalOutput ?? extractAgentFinalOutput(agent);
+					setAgentFinalOutput(agent.id, finalOutput);
+					
+					// Gate the counter on the finalize claim: if the
+					// stale sweep already finalized this entry, the
+					// decrement happened there (PR #71 review).
+					if (state.finalizeLiveSubagent(agent.id)) {
+						state.activeSubagents--;
+						if (state.activeSubagents < 0) state.activeSubagents = 0;
+					}
+					
+					if (agent.status === 'failed') {
+						state.failedSubagents++;
+						updateProgressStatus(state, ctx);
+						pi.sendMessage({
+							customType: "subagent-notification",
+							content: `Background agent "${agent.description}" failed.`,
+							display: true,
+							details: { agentId: agent.id }
+						}, { deliverAs: "followUp" });
+					} else if (agent.status === 'stopped') {
+						// User-initiated stop (stop_subagent) or deadline abort
+						// (timeout/hard cap) — not a failure.
+						updateProgressStatus(state, ctx);
+					} else {
+						state.completedSubagents++;
+						state.unseenSubagents++;
+						updateProgressStatus(state, ctx);
+					}
+				}
+			} catch (err) {
+				if (!completed) {
+					completed = true;
+					clearInterval(pollInterval);
+					clearTimeout(hardCapHandle);
+					try {
+						setAgentFinalOutput(agent.id, extractAgentFinalOutput(agent));
+					} catch { /* ignore */ }
+					// Gate the counter on the finalize claim: if the
+					// stale sweep already finalized this entry, the
+					// decrement happened there (PR #71 review).
+					if (state.finalizeLiveSubagent(agent.id)) {
+						state.activeSubagents--;
+						if (state.activeSubagents < 0) state.activeSubagents = 0;
+					}
+					state.failedSubagents++;
+					updateProgressStatus(state, ctx);
+					pi.sendMessage({
+						customType: "subagent-notification",
+						content: `Background agent "${agent.description}" crashed: ${sanitizeErrorMessage((err as Error).message, spawn.sanitizeCwd)}`,
+						display: true,
+						details: { agentId: agent.id }
+					}, { deliverAs: "followUp" });
+				}
+			}
+		}, 2000);
+		
+		// Hard cap: stop polling AND abort the session after the deadline.
+		// W2 (issue #28): previously this only stopped the poller — the pi
+		// session kept running forever (orphaned). Now it pre-sets
+		// 'stopped' (so the .then keeps it, per W1) and aborts the
+		// session. The cap honors a shorter per-agent timeout.
+		const hardCapMs = Math.min(spawn.timeout ?? 30 * 60 * 1000, 30 * 60 * 1000);
+		const hardCapHandle = setTimeout(() => {
+			if (!completed && !agent.completedAt) {
+				try {
+					completed = true;
+					clearInterval(pollInterval);
+					// Pre-set stopped BEFORE aborting so the .then in
+					// spawnBackgroundSession keeps the stopped state.
+					updateAgentStatus(agent.id, 'stopped', `Timed out (${hardCapMs}ms hard cap)`);
+					agent._sessionRef?.abort().catch(() => {
+						// Abort may reject if the session is mid-dispose;
+						// the status flip above is already recorded.
+					});
+					// Capture whatever final output exists in the session
+					const hardCapSession = agent._sessionRef;
+					const hardCapFinalOutput = hardCapSession ? extractFinalOutput(hardCapSession) : '';
+					setAgentFinalOutput(agent.id, hardCapFinalOutput);
+					// Gate the counter on the finalize claim: if the
+					// stale sweep already finalized this entry, the
+					// decrement happened there (PR #71 review).
+					if (state.finalizeLiveSubagent(agent.id)) {
+						state.activeSubagents--;
+						if (state.activeSubagents < 0) state.activeSubagents = 0;
+					}
+					// m6: deadline abort is a stop, not a completion — mirror the
+					// W3/poller stopped path (no completedSubagents increment).
+					updateProgressStatus(state, ctx);
+				} catch (err) {
+					// Defensive: never let the hard-cap timer throw uncaught — that would
+					// skip finalizeLiveSubagent, the counter decrement, and the notification.
+					// Do all fallible work first (output capture), then mutate counters,
+					// then notify — a throw mid-path can't double-fire mutations.
+					completed = true;
+					clearInterval(pollInterval);
+					// m3: the try may have thrown BEFORE updateAgentStatus ran (e.g.
+					// persistAgent fs failure) — leave the record terminal so
+					// get_subagent_result doesn't report 'running' and the W3 timer
+					// guard (!agent.completedAt) can't re-fire later.
+					try {
+						updateAgentStatus(agent.id, 'stopped', `Timed out (${hardCapMs}ms hard cap)`);
+					} catch { /* ignore */ }
+					try {
+						setAgentFinalOutput(agent.id, extractAgentFinalOutput(agent));
+					} catch { /* ignore */ }
+					// Gate the counter on the finalize claim: if the
+					// stale sweep already finalized this entry, the
+					// decrement happened there (PR #71 review).
+					if (state.finalizeLiveSubagent(agent.id)) {
+						state.activeSubagents--;
+						if (state.activeSubagents < 0) state.activeSubagents = 0;
+					}
+					state.failedSubagents++;
+					updateProgressStatus(state, ctx);
+				}
+			}
+		}, hardCapMs);
+		
+		log.info("Background agent spawned", { agentId: agent.id, task: spawn.task, model: agent.model });
+
+		return agent;
+	}
+
+	// -------------------------------------------------------------------
+	// spawnBackgroundRun — Phase 6.5 background spawn, extracted verbatim
+	// from execute() (#198 phase 1) so a later phase can fan out N runs.
+	// -------------------------------------------------------------------
+
+	async function spawnBackgroundRun(
+		pi: ExtensionAPI,
+		ctx: ExtensionContext,
+		params: Omit<Parameters<typeof resolveSubagentParams>[0], "task"> & {
+			task?: string;
+			model?: string;
+			priority?: string;
+		},
+		singleTask: string,
+	): Promise<ToolResult<undefined>> {
+		// Phase 6.5: Background execution — spawn session and return ID immediately.
+		// Resolve the preset and its model BEFORE the background branch so the
+		// preset's model (and system prompt) are honored in background mode.
+		const bgResolved = resolveSubagentParams({ ...params, task: singleTask }, state, ctx, log);
+		const {
+			resolvedPreset: bgResolvedPreset,
+			autoRoutedPreset: bgAutoRoutedPreset,
+			autoRouteKeyword: bgAutoRouteKeyword,
+		} = bgResolved;
+		const bgModelResult = resolveSubagentModel(ctx, bgResolvedPreset, params.model);
+		const bgModel = bgModelResult.ok
+			? `${bgModelResult.model.provider}/${bgModelResult.model.id}`
+			: undefined;
+
+		try {
+			// W5 (issue #28): approvalMode 'always' cannot work in background —
+			// there is no interactive dialog to approve the diff. Reject loudly
+			// instead of silently running unattended with write access.
+			const approvalError = rejectApprovalAlwaysInBackground(bgResolved.resolvedApprovalMode);
+			if (approvalError) return approvalError;
+			// W5: 'writes' in background silently auto-approves — warn once so the
+			// caller knows the diff will NOT be gated on approval.
+			if (bgResolved.resolvedApprovalMode === 'writes') {
+				log.warn("Background agent spawned with approvalMode 'writes' — auto-approving (no dialog in background)", {
+					task: params.task,
+				});
+			}
+
+			// W6 (issue #28): session cost limit must gate background spawns too —
+			// the R5 check after the background branch never runs for them.
+			// Same estimate/limit logic as single mode.
+			const costError = gateSessionCost({
+				state,
+				ctx,
+				log,
+				units: 1,
+				label: "Background delegation",
+			});
+			if (costError) return costError;
+
+			// F1: Validate cwd + outputFile the same way foreground single mode does —
+			// an unvalidated outputFile would reach the prompt and could steer the
+			// background agent's write tool outside the project root.
+			const targets = validateDelegationTargets({
+				ctx,
+				effectiveCwd: bgResolved.effectiveCwd,
+				outputFile: bgResolved.outputFile,
+			});
+			if (!targets.ok) return targets.error;
+			const bgResolvedOutputFile = targets.outputFile;
+
+			// C: H1 validation for background mode — reject capability blocks and
+			// outputFile-vs-write conflicts before spawning (same as single mode;
+			// `force` honors the same override foreground does).
+			const bgPreTask = runPreTaskValidation({
+				log,
+				label: "Background",
+				preTask: {
+					task: singleTask,
+					toolOptions: bgResolved.toolOptions,
+					thinkingLevel: bgResolved.thinkingLevel,
+					gitMode: bgResolved.resolvedGitMode,
+					outputFile: bgResolvedOutputFile,
+					force: params.force,
+				},
+			});
+			if (bgPreTask.error) return bgPreTask.error;
+
+			// Build the full prompt the same way foreground single mode does:
+			// base prompt (optionally inherited) + custom prompt + preset guidance.
+			const bgPrompt = buildSubagentPrompt(
+				ctx.getSystemPrompt(),
+				bgResolved.inheritSP,
+				bgResolved.customSP,
+				bgResolvedOutputFile,
+				bgResolved.toolOptions?.tools,
+				bgResolvedPreset?.promptGuideline,
+			);
+
+			const agent = await startBackgroundAgent(pi, ctx, {
+				task: singleTask,
+				type: params.preset || 'general-purpose',
+				description: params.label,
+				model: bgModel,
+				thinkingLevel: bgResolved.thinkingLevel,
+				priority: params.priority,
+				systemPrompt: bgPrompt,
+				cwd: targets.cwd,
+				toolOptions: bgResolved.toolOptions,
+				timeout: bgResolved.timeout,
+				gitMode: bgResolved.resolvedGitMode,
+				originalParams: snapshotOriginalParams(params),
+				sanitizeCwd: bgResolved.effectiveCwd,
+			});
+
+			// B2: Surface auto-route decisions in background spawn result too —
+			// preset name + matched-keyword evidence + restriction, derived from
+			// the RESOLVED toolOptions (reflects per-call overrides).
+			const bgAutoRouteNote = bgAutoRoutedPreset
+				? `\n\n[auto-routed to preset '${bgAutoRoutedPreset.name}'${bgAutoRouteKeyword ? ` (matched keyword '${bgAutoRouteKeyword}')` : ""} — ${bgResolved.toolOptions ? formatToolRestriction(bgResolved.toolOptions) : formatPresetRestriction(bgAutoRoutedPreset)}]`
+				: "";
+
+			return {
+				content: [{
+					type: "text" as const,
+					text: `Background agent started: ${agent.id}\n\n` +
+						`Description: ${agent.description}\n` +
+						`Task: ${agent.task}\n` +
+						`Status: ${agent.status}\n\n` +
+						`You'll be woken with a completion message when it finishes; use get_subagent_result({ agent_id: "${agent.id}" }) for retrieval and stall checks.` +
+						bgAutoRouteNote +
+						// C: warnings ride the immediate SPAWN result so the conductor
+						// can stop/re-dispatch in the same turn.
+						formatValidationWarnings(bgPreTask.warnings),
+				}],
+				details: undefined,
+			};
+		} catch (err) {
+			const message = sanitizeErrorMessage(
+				err instanceof Error ? err.message : String(err),
+				bgResolved.effectiveCwd,
+			);
+			log.error("Failed to spawn background agent", { error: message });
+			return {
+				content: [{ type: "text" as const, text: `Failed to spawn background agent: ${message}` }],
+				details: undefined,
+				isError: true,
+			};
+		}
+	}
+
 	// -------------------------------------------------------------------
 	// /brl-subagent command
 	// -------------------------------------------------------------------
@@ -1973,14 +2755,14 @@ export default function (pi: ExtensionAPI) {
 			"You can customize per-call via inheritSystemPrompt and systemPrompt: set inheritSystemPrompt: false to save context, provide a systemPrompt for custom instructions, or use both to add instructions on top of inheritance.",
 			"Set thinkingLevel per call to match task complexity. The level is capped at the user's configured maximum. Map tasks to levels using this heuristic: off = file listing, grep, simple read. minimal = file diff, syntax check, find-and-replace. low = refactoring, test generation, documentation. medium = default — code review, debugging, moderate analysis. high = security audit, architecture review, complex debugging. xhigh = multi-step causal reasoning, research, novel problem solving. Default to 'off' or 'minimal' for trivial tasks — do not waste the user's budget.",
 			"Use outputFile to have the subagent write full findings to disk and return only a structured summary — saves context tokens for large investigations.",
-			"Set timeout (in ms) to limit how long a subagent can run. Useful for tasks that might hang or get stuck.",
+			"Set timeout (in ms) to limit how long a subagent can run. Useful for tasks that might hang or get stuck. Background runs are additionally hard-capped at 30 minutes, so a larger value is silently shortened.",
 			"Set cwd to override the subagent's working directory. Defaults to the current project directory.",
 			"Set label to give the subagent a human-readable name (e.g., 'security-audit' or 'docs-review'). Labels appear in the status bar and tool call display.",
 			`Use preset to apply a delegation configuration (built-in or custom via /brl-subagent preset). Preset values are defaults — explicit parameters override them. IMPORTANT: some presets restrict tools — e.g. outputFile requires the subagent's write tool, which security-auditor and code-reviewer exclude. Built-in presets: ${presetRestrictionSummary}. Custom presets are NOT listed here — inspect them via /brl-subagent preset before combining with outputFile or tool-dependent work. When combining a preset with outputFile or tool-dependent work, verify the preset allows the required tools.`,
 			buildTemplateGuideline(templateSummary),
-			"To retry a failed subagent, pass its run ID as retryRunId. The retried run uses the same task and parameters as the original. Parallel-origin entries retry as a single-subtask run carrying that subtask's task, label, and priority. Explicit parameters on this call override the original's. Use /brl-subagent retry to browse failed runs and get their IDs.",
+			"To retry a failed subagent, pass its run ID as retryRunId. The retry restores the recorded params - including background, gitMode, approvalMode, force - with explicit values on this call winning. Multi-step runs degrade to a single task. See the retryRunId description for the full field list.",
 			"Set retryOnTimeout: true to automatically retry a subagent that times out. Only retries once — the second timeout is treated as a final failure.",
-			"Set background: true to run the subagent in the background without blocking. The tool returns immediately with an agent ID. Background runs wake the conductor with a structured completion message when they finish — do not poll: polling is only correct when completion notifications are disabled (completionNotify \"off\"); one status check as a stall check is legitimate.",
+			"Set background: true to run the subagent in the background without blocking. The tool returns immediately with an agent ID. With tasks, background fans out: every task starts as its own background agent, the call returns one ID per task in task order, and the conductor is woken once per agent as each finishes; chain and graph cannot be combined with background (rejected). Background runs wake the conductor with a structured completion message when they finish — do not poll: polling is only correct when completion notifications are disabled (completionNotify \"off\"); one status check as a stall check is legitimate.",
 			"",
 			"## Conductor Guardrails",
 			"",
@@ -1989,9 +2771,9 @@ export default function (pi: ExtensionAPI) {
 			"2. **Thinking level**: Match thinking level to task complexity: off/minimal for trivial tasks (file listing, grep), low for refactoring/docs, medium for code review/debugging, high for security audits/complex debugging, xhigh for multi-step reasoning/novel problems.",
 			"3. **Git mode**: Use gitMode='branch' for tasks that create commits or PRs. Use gitMode='none' for read-only tasks.",
 			"4. **Tools**: Verify the subagent has the tools it needs. If the task writes files, ensure write and edit are not excluded. If the task runs commands, ensure bash is not excluded.",
-			"5. **Timeout**: Set timeout based on task complexity. Simple: 30s. Medium: 60s. Complex: 120s+. xhigh thinking: at least 120s.",
+			"5. **Timeout**: Set timeout based on task complexity. Simple: 30s. Medium: 60s. Complex: 120s+. xhigh thinking: at least 120s. Background runs are hard-capped at 30 minutes regardless of the value set.",
 			"",
-			"These guardrails prevent common misconfigurations. The extension also validates configuration before spawning (H1): tool warnings are informational, but outputFile with the write tool excluded is a HARD error and the delegation is rejected. Getting it right the first time is faster and more efficient.",
+			"These guardrails prevent common misconfigurations. The extension also validates configuration before spawning (H1): tool warnings are surfaced in the returned result, but two mismatches are HARD errors that reject the delegation — outputFile with the write tool excluded, and a capability-critical task/toolset mismatch (a run/execute/test/compile/benchmark task without bash, or an exploration task with none of find/ls/grep/bash; pass force: true to override the capability class). Getting it right the first time is faster and more efficient.",
 			"",
 			"Before delegating, evaluate existing presets to find the best match for the task: tech-writer (documentation), code-reviewer (code review), security-auditor (security analysis), test-engineer (test writing), debugger (debugging), refactorer (refactoring), data-analyst (data analysis), rapid-prototyper (quick prototypes). Use the preset parameter to apply the best match. If no preset fits, use dev-agent for general development tasks.",
 			"The autoRoutePreset() function can automatically select the best preset based on task keywords. Consider using it for preset selection.",
@@ -2046,7 +2828,8 @@ export default function (pi: ExtensionAPI) {
 				Type.Number({
 					description:
 						"Maximum time in milliseconds the subagent is allowed to run. " +
-						"If exceeded, the subagent is killed and an error is returned.",
+						"If exceeded, the subagent is killed and an error is returned. " +
+						"Background runs are additionally hard-capped at 30 minutes, so a larger value is silently shortened there.",
 				}),
 			),
 			cwd: Type.Optional(
@@ -2102,9 +2885,21 @@ export default function (pi: ExtensionAPI) {
 				Type.String({
 					description:
 						"ID of a previously failed subagent run to retry. " +
-						"The retried run uses the same task and parameters as the original. " +
-						"Only works with runs that ended in failure (exitCode != 0, timeout, error, or abort). " +
-						"Explicit parameters on this call override the original's.",
+						"The retry rebuilds the parameter object from a fixed field set, falling back to the " +
+						"original run's recorded values, with explicit values on this call winning: task, label, " +
+						"model, preset, systemPrompt, inheritSystemPrompt, thinkingLevel, priority, outputFile, " +
+						"timeout, cwd, tools, excludeTools, noBuiltinTools, background, gitMode, approvalMode, force. " +
+						"The execution-shape fields ARE restored: a retried background run stays background (with its " +
+						"completion wake), and a retried branch-mode run keeps its work branch, its approvalMode " +
+						"gating and its force override. Qualify that by the effective gitMode - when neither the record " +
+						"nor this call carries one, the configured default applies, which may still be 'branch'. " +
+						"Not restored: chain/tasks/graph and params, so a retried multi-step run silently degrades to a " +
+						"single task - re-issue it fresh. retryOnTimeout is explicit-only: never restored, honoured when passed. " +
+						"template is asymmetric: the original's template is NOT restored, but a template passed on the " +
+						"retry call DOES take effect (it is resolved before the retry merge). " +
+						"Fan-out units (parallel/chain/graph origin) record no background, so retrying one is a single " +
+						"foreground run - pass background: true for a background retry. " +
+						"Only works with runs that ended in failure (exitCode != 0, timeout, error, or abort).",
 				}),
 			),
 			gitMode: Type.Optional(
@@ -2129,12 +2924,22 @@ export default function (pi: ExtensionAPI) {
 						"always (ask every time). Default is user config (/brl-subagent approval).",
 				}),
 			),
+			force: Type.Optional(
+				Type.Boolean({
+					description:
+						"Override for capability pre-flight errors (default false). A dispatch is blocked when the task clearly needs a capability the resolved toolset lacks — " +
+						"a run/execute/test/compile/benchmark task with no bash, or an exploration task (search/grep/find/list/locate/glob) with none of find/ls/grep/bash. " +
+						"Set force: true to dispatch anyway: the mismatch is then delivered as a warning in the result instead of rejecting the call. " +
+						"Warnings are surfaced either way. force never suppresses outputFile-without-write conflicts.",
+				}),
+			),
 			background: Type.Optional(
 				Type.Boolean({
 					description:
 						"Run the subagent in the background without blocking the conductor. " +
 						"When true, the tool returns immediately with an agent ID. " +
 						"The conductor is woken with a completion message; use get_subagent_result for post-wake retrieval and stall checks. " +
+						"Supports a single task or the tasks array (a fan-out that starts one background agent per task; with tasks the call returns one ID per task and the conductor is woken once per agent as each finishes); combining background with chain or graph is rejected. " +
 						"Default: false (blocking mode).",
 				}),
 			),
@@ -2193,7 +2998,7 @@ export default function (pi: ExtensionAPI) {
 			})),
 			graph: Type.Optional(Type.Array(Type.Object({
 				id: Type.String({ description: "Unique identifier for this task node" }),
-				task: Type.String({ description: "Task description. Use {otherId} to reference output from another task." }),
+				task: Type.String({ description: "Task description. Use {<nodeId>} to reference output from another task (the referenced node's own id, which must be a word-character id - letters, digits, underscore; ids like 'step-1' or 'node.a' are not matched and the braces are left as literal text)." }),
 				label: Type.Optional(Type.String({})),
 				model: Type.Optional(Type.String({ description: "Model override for this step (provider/model-id). Defaults to the global subagent model." })),
 				dependsOn: Type.Optional(Type.Array(Type.String({}), { description: "IDs of tasks that must complete before this one starts" })),
@@ -2242,6 +3047,7 @@ export default function (pi: ExtensionAPI) {
 				retryRunId?: string;
 				retryOnTimeout?: boolean;
 				background?: boolean;
+				force?: boolean;
 				gitMode?: string;
 				priority?: string;
 				chain?: Array<{
@@ -2396,7 +3202,7 @@ export default function (pi: ExtensionAPI) {
 			// resolving templates first keeps a combined template + retryRunId call
 			// from silently disabling template resolution (issue #175 review).
 			if (params.retryRunId) {
-				const runEntry = state.findRunById(ctx, params.retryRunId);
+				const runEntry = state.findSpawnRunById(ctx, params.retryRunId);
 				if (runEntry) {
 					params = resolveRetryParams(params, runEntry);
 				} else {
@@ -2456,6 +3262,24 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
+			// background: true with chain/graph was silently ignored — the batch ran
+			// foreground (blocking until every unit finished) while the caller believed
+			// it was background. Both remain rejected loudly at dispatch validation;
+			// tasks (parallel) fans out into independent background agents instead.
+			if (params.background && (isChain || isGraph)) {
+				const batchMode = isChain ? "chain" : "graph";
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `background: true is not supported with ${batchMode} — batch modes run foreground and would block until every unit finishes. Remove background to run it foreground, or start each unit as its own single-task background call and sequence the dependencies yourself.`,
+						},
+					],
+					details: undefined,
+					isError: true,
+				};
+			}
+
 			if (isChain) {
 				if (params.chain!.length > MAX_CHAIN_STEPS) {
 					return {
@@ -2485,6 +3309,7 @@ export default function (pi: ExtensionAPI) {
 						isError: true,
 					};
 				}
+				if (params.background) return runBackgroundFanOut(pi, ctx, params, signal);
 				return runParallelMode(params, signal, onUpdate, ctx);
 			}
 
@@ -2497,420 +3322,20 @@ export default function (pi: ExtensionAPI) {
 			// boolean-array filter — assert, mirroring params.chain!/params.tasks! above.
 			const singleTask = params.task!; // non-empty (sanitizer guarantees; isSingle confirms)
 
-			// Phase 6.5: Background execution — spawn session and return ID immediately.
-			// Resolve the preset and its model BEFORE the background branch so the
-			// preset's model (and system prompt) are honored in background mode.
-			const bgResolved = resolveSubagentParams({ ...params, task: singleTask }, state, ctx, log);
-			const { resolvedPreset: bgResolvedPreset, autoRoutedPreset: bgAutoRoutedPreset } = bgResolved;
-			const bgModelResult = resolveSubagentModel(ctx, bgResolvedPreset, params.model);
-			const bgModel = bgModelResult.ok
-				? `${bgModelResult.model.provider}/${bgModelResult.model.id}`
-				: undefined;
-
 			if (params.background) {
-				const { spawnBackgroundSession, setAgentFinalOutput, extractFinalOutput, updateAgentStatus } = await import('./session-manager');
-				// Issue #31 (PR #76 review, DRY): extract final output from a
-				// possibly-released ref — the poller may observe a terminal agent
-				// whose ref was already nulled by the settlement path.
-				const extractAgentFinalOutput = (a: BackgroundAgent): string =>
-					extractFinalOutput(a._sessionRef ?? { messages: [] });
-				
-				try {
-					// W5 (issue #28): approvalMode 'always' cannot work in background —
-					// there is no interactive dialog to approve the diff. Reject loudly
-					// instead of silently running unattended with write access.
-					if (bgResolved.resolvedApprovalMode === 'always') {
-						return {
-							content: [{ type: "text" as const, text:
-								`Cannot spawn background agent with approvalMode 'always': background agents run unattended ` +
-								`and cannot present the approval dialog. Use approvalMode 'auto' (default) or 'writes'.`
-							}],
-							details: undefined,
-							isError: true,
-						};
-					}
-					// W5: 'writes' in background silently auto-approves — warn once so the
-					// caller knows the diff will NOT be gated on approval.
-					if (bgResolved.resolvedApprovalMode === 'writes') {
-						log.warn("Background agent spawned with approvalMode 'writes' — auto-approving (no dialog in background)", {
-							task: params.task,
-						});
-					}
-
-					// W6 (issue #28): session cost limit must gate background spawns too —
-					// the R5 check after the background branch never runs for them.
-					// Same estimate/limit logic as single mode.
-					const bgPerTaskEstimate = state.config.perTaskCostEstimate > 0
-						? state.config.perTaskCostEstimate
-						: 0.05;
-					if (state.checkCostLimit(bgPerTaskEstimate, ctx)) {
-						const bgLimit = state.config.sessionCostLimit;
-						const bgCurrentTotal = state.getSessionTotalCost(ctx);
-						log.warn("Background delegation rejected: session cost limit reached", {
-							currentTotal: bgCurrentTotal,
-							estimatedCost: bgPerTaskEstimate,
-							limit: bgLimit,
-						});
-						return {
-							content: [
-								{
-									type: "text" as const,
-									text:
-										`Cannot delegate: session cost limit reached ` +
-										`($${bgCurrentTotal.toFixed(4)} spent of $${bgLimit.toFixed(2)} limit). ` +
-										`Increase the limit via /brl-subagent costlimit or set to 0 for unlimited.`,
-								},
-							],
-							details: undefined,
-							isError: true,
-						};
-					}
-
-					// F1: Validate cwd + outputFile the same way foreground single mode does —
-					// an unvalidated outputFile would reach the prompt and could steer the
-					// background agent's write tool outside the project root.
-					const bgCwdResult = validateCwd(bgResolved.effectiveCwd, ctx.cwd);
-					if (!bgCwdResult.ok) {
-						return {
-							content: [{ type: "text" as const, text: `Invalid cwd: ${bgCwdResult.error}` }],
-							details: undefined,
-							isError: true,
-						};
-					}
-					let bgResolvedOutputFile: string | undefined;
-					if (bgResolved.outputFile) {
-						const ofResult = validateOutputFile(bgResolved.outputFile, bgCwdResult.value);
-						if (!ofResult.ok) {
-							return {
-								content: [
-									{ type: "text" as const, text: `Invalid outputFile: ${ofResult.error}` },
-								],
-								details: undefined,
-								isError: true,
-							};
-						}
-						bgResolvedOutputFile = ofResult.value;
-					}
-
-					// C: H1 validation for background mode — reject outputFile-vs-write
-					// conflicts before spawning (loud failure, same as single mode).
-					const bgValidation = validatePreTask({
-						task: singleTask,
-						toolOptions: bgResolved.toolOptions,
-						thinkingLevel: bgResolved.thinkingLevel,
-						gitMode: bgResolved.resolvedGitMode,
-						outputFile: bgResolvedOutputFile,
-					});
-					if (bgValidation.warnings.length > 0) {
-						log.warn("Background pre-task validation warnings", { warnings: bgValidation.warnings });
-					}
-					if (!bgValidation.valid) {
-						const errText = bgValidation.errors.join("; ");
-						log.warn("Background pre-task validation failed", { errors: bgValidation.errors });
-						return {
-							content: [{ type: "text" as const, text: errText }],
-							details: undefined,
-							isError: true,
-						};
-					}
-
-					// Build the full prompt the same way foreground single mode does:
-					// base prompt (optionally inherited) + custom prompt + preset guidance.
-					const bgPrompt = buildSubagentPrompt(
-						ctx.getSystemPrompt(),
-						bgResolved.inheritSP,
-						bgResolved.customSP,
-						bgResolvedOutputFile,
-						bgResolved.toolOptions?.tools,
-						bgResolvedPreset?.promptGuideline,
-					);
-
-					const agent = await spawnBackgroundSession(pi, ctx, {
-						task: singleTask,
-						type: params.preset || 'general-purpose',
-						description: params.label,
-						model: bgModel,
-						thinkingLevel: bgResolved.thinkingLevel,
-						// Issue #114: per-unit priority rides the spawn so the background
-						// run entry + drill-in header carry it like foreground runs.
-						priority: params.priority,
-						systemPrompt: bgPrompt,
-						cwd: bgCwdResult.value,
-						toolOptions: bgResolved.toolOptions,
-						timeout: bgResolved.timeout,
-						gitMode: bgResolved.resolvedGitMode,
-						// Issue #98: snapshot the caller's raw params on the run entry so a
-						// retry of this background run restores them — single source of truth
-						// snapshotOriginalParams (issue #108: no more duplicated 11-field literal).
-						originalParams: snapshotOriginalParams(params),
-					});
-					
-					// Register for live monitor
-					state.registerLiveSubagent(agent.id, {
-						id: agent.id,
-						label: agent.description,
-						task: agent.task,
-						model: agent.model,
-						thinkingLevel: agent.thinkingLevel,
-						priority: agent.priority,
-						startedAt: agent.startedAt,
-						ctx,
-					});
-					
-					// Update footer counters
-					state.activeSubagents++;
-					updateProgressStatus(state, ctx);
-
-				let completed = false;
-					
-					// Poll for live progress
-					const pollInterval = setInterval(() => {
-						try {
-							if (completed) return;
-							
-							const session = agent._sessionRef;
-							// Issue #31: a nulled ref on a TERMINAL agent is expected (the
-							// settlement path releases the ref) — fall through to finalize
-							// below instead of treating it as a crash. A nulled ref on a
-							// live agent is still a crash.
-							if (!session && !agent.completedAt) {
-								// Session ref not available — session may have crashed.
-								// Defensive: the ref is assigned synchronously before the poller starts
-								// and is never nulled, so this is mostly unreachable — but keep the
-								// bookkeeping safe regardless.
-								completed = true;
-								clearInterval(pollInterval);
-								clearTimeout(hardCapHandle);
-								// Capture whatever output exists (may be empty — fine).
-								setAgentFinalOutput(agent.id, state.subagentSessions.get(agent.id)?.liveOutput ?? '');
-								// Gate the counter on the finalize claim: if the
-								// stale sweep already finalized this entry, the
-								// decrement happened there (PR #71 review).
-								if (state.finalizeLiveSubagent(agent.id)) {
-									state.activeSubagents--;
-									if (state.activeSubagents < 0) state.activeSubagents = 0;
-								}
-								state.failedSubagents++;
-								updateProgressStatus(state, ctx);
-								pi.sendMessage({
-									customType: "subagent-notification",
-									content: `Background agent "${agent.description}" crashed.`,
-									display: true,
-									details: { agentId: agent.id }
-								}, { deliverAs: "followUp" });
-								return;
-							}
-							
-							// While running, update the live monitor.
-							// Once completedAt is set, skip straight to finalize below.
-							// Issue #31: past the guard above, the only nulled-ref path left is a
-							// TERMINAL agent (settlement releases the ref), so a live agent always
-							// has its session — the guard already returned on the live-nulled-ref
-							// crash path. The compiler can't correlate the two checks, so assert it.
-							if (!agent.completedAt) {
-								const finalOutput = extractFinalOutput(session!);
-								
-								try {
-									const stats = session!.getSessionStats();
-									state.updateLiveSubagent(agent.id, finalOutput, stats.tokens.input, stats.tokens.output);
-								} catch {
-									state.updateLiveSubagent(agent.id, finalOutput, 0, 0);
-								}
-							}
-							
-							// Authoritative completion: the prompt promise settled — status and
-							// completedAt are set by .then()/.catch() in spawnBackgroundSession.
-							// Do NOT rely on !session.isStreaming: it is false during prompt()
-							// preflight (auth check, model resolution) and for failed starts.
-							if (agent.completedAt) {
-								completed = true;
-								clearInterval(pollInterval);
-								clearTimeout(hardCapHandle);
-								
-								// Issue #31: prefer the output already captured at settlement;
-								// the ref may already be nulled on terminal agents, so never
-								// overwrite with empty and stay null-safe.
-								const finalOutput = agent.finalOutput ?? extractAgentFinalOutput(agent);
-								setAgentFinalOutput(agent.id, finalOutput);
-								
-								// Gate the counter on the finalize claim: if the
-								// stale sweep already finalized this entry, the
-								// decrement happened there (PR #71 review).
-								if (state.finalizeLiveSubagent(agent.id)) {
-									state.activeSubagents--;
-									if (state.activeSubagents < 0) state.activeSubagents = 0;
-								}
-								
-								if (agent.status === 'failed') {
-									state.failedSubagents++;
-									updateProgressStatus(state, ctx);
-									pi.sendMessage({
-										customType: "subagent-notification",
-										content: `Background agent "${agent.description}" failed.`,
-										display: true,
-										details: { agentId: agent.id }
-									}, { deliverAs: "followUp" });
-								} else if (agent.status === 'stopped') {
-									// User-initiated stop (stop_subagent) or deadline abort
-									// (timeout/hard cap) — not a failure.
-									updateProgressStatus(state, ctx);
-								} else {
-									state.completedSubagents++;
-									state.unseenSubagents++;
-									updateProgressStatus(state, ctx);
-								}
-							}
-						} catch (err) {
-							if (!completed) {
-								completed = true;
-								clearInterval(pollInterval);
-								clearTimeout(hardCapHandle);
-								try {
-									setAgentFinalOutput(agent.id, extractAgentFinalOutput(agent));
-								} catch { /* ignore */ }
-								// Gate the counter on the finalize claim: if the
-								// stale sweep already finalized this entry, the
-								// decrement happened there (PR #71 review).
-								if (state.finalizeLiveSubagent(agent.id)) {
-									state.activeSubagents--;
-									if (state.activeSubagents < 0) state.activeSubagents = 0;
-								}
-								state.failedSubagents++;
-								updateProgressStatus(state, ctx);
-								pi.sendMessage({
-									customType: "subagent-notification",
-									content: `Background agent "${agent.description}" crashed: ${sanitizeErrorMessage((err as Error).message, bgResolved.effectiveCwd)}`,
-									display: true,
-									details: { agentId: agent.id }
-								}, { deliverAs: "followUp" });
-							}
-						}
-					}, 2000);
-					
-					// Hard cap: stop polling AND abort the session after the deadline.
-					// W2 (issue #28): previously this only stopped the poller — the pi
-					// session kept running forever (orphaned). Now it pre-sets
-					// 'stopped' (so the .then keeps it, per W1) and aborts the
-					// session. The cap honors a shorter per-agent timeout.
-					const hardCapMs = Math.min(bgResolved.timeout ?? 30 * 60 * 1000, 30 * 60 * 1000);
-					const hardCapHandle = setTimeout(() => {
-						if (!completed && !agent.completedAt) {
-							try {
-								completed = true;
-								clearInterval(pollInterval);
-								// Pre-set stopped BEFORE aborting so the .then in
-								// spawnBackgroundSession keeps the stopped state.
-								updateAgentStatus(agent.id, 'stopped', `Timed out (${hardCapMs}ms hard cap)`);
-								agent._sessionRef?.abort().catch(() => {
-									// Abort may reject if the session is mid-dispose;
-									// the status flip above is already recorded.
-								});
-								// Capture whatever final output exists in the session
-								const hardCapSession = agent._sessionRef;
-								const hardCapFinalOutput = hardCapSession ? extractFinalOutput(hardCapSession) : '';
-								setAgentFinalOutput(agent.id, hardCapFinalOutput);
-								// Gate the counter on the finalize claim: if the
-								// stale sweep already finalized this entry, the
-								// decrement happened there (PR #71 review).
-								if (state.finalizeLiveSubagent(agent.id)) {
-									state.activeSubagents--;
-									if (state.activeSubagents < 0) state.activeSubagents = 0;
-								}
-								// m6: deadline abort is a stop, not a completion — mirror the
-								// W3/poller stopped path (no completedSubagents increment).
-								updateProgressStatus(state, ctx);
-							} catch (err) {
-								// Defensive: never let the hard-cap timer throw uncaught — that would
-								// skip finalizeLiveSubagent, the counter decrement, and the notification.
-								// Do all fallible work first (output capture), then mutate counters,
-								// then notify — a throw mid-path can't double-fire mutations.
-								completed = true;
-								clearInterval(pollInterval);
-								// m3: the try may have thrown BEFORE updateAgentStatus ran (e.g.
-								// persistAgent fs failure) — leave the record terminal so
-								// get_subagent_result doesn't report 'running' and the W3 timer
-								// guard (!agent.completedAt) can't re-fire later.
-								try {
-									updateAgentStatus(agent.id, 'stopped', `Timed out (${hardCapMs}ms hard cap)`);
-								} catch { /* ignore */ }
-								try {
-									setAgentFinalOutput(agent.id, extractAgentFinalOutput(agent));
-								} catch { /* ignore */ }
-								// Gate the counter on the finalize claim: if the
-								// stale sweep already finalized this entry, the
-								// decrement happened there (PR #71 review).
-								if (state.finalizeLiveSubagent(agent.id)) {
-									state.activeSubagents--;
-									if (state.activeSubagents < 0) state.activeSubagents = 0;
-								}
-								state.failedSubagents++;
-								updateProgressStatus(state, ctx);
-							}
-						}
-					}, hardCapMs);
-					
-					log.info("Background agent spawned", { agentId: agent.id, task: params.task, model: agent.model });
-
-					// B2: Surface auto-route decisions in background spawn result too.
-					// Derive the restriction from the RESOLVED toolOptions (which reflects
-					// per-call overrides) rather than the preset's declared values.
-					const bgAutoRouteNote = bgAutoRoutedPreset
-						? `\n\n[auto-routed to preset '${bgAutoRoutedPreset.name}' — ${bgResolved.toolOptions ? formatToolRestriction(bgResolved.toolOptions) : formatPresetRestriction(bgAutoRoutedPreset)}]`
-						: "";
-
-					return {
-						content: [{
-							type: "text" as const,
-							text: `Background agent started: ${agent.id}\n\n` +
-								`Description: ${agent.description}\n` +
-								`Task: ${agent.task}\n` +
-								`Status: ${agent.status}\n\n` +
-								`You'll be woken with a completion message when it finishes; use get_subagent_result({ agent_id: "${agent.id}" }) for retrieval and stall checks.` +
-								bgAutoRouteNote,
-						}],
-						details: undefined,
-					};
-				} catch (err) {
-					const message = sanitizeErrorMessage(
-						err instanceof Error ? err.message : String(err),
-						bgResolved.effectiveCwd,
-					);
-					log.error("Failed to spawn background agent", { error: message });
-					return {
-						content: [{ type: "text" as const, text: `Failed to spawn background agent: ${message}` }],
-						details: undefined,
-						isError: true,
-					};
-				}
+				return spawnBackgroundRun(pi, ctx, params, singleTask);
 			}
 
 			// R5: Check session cost limit before spawning
 			// Use a default per-task estimate of $0.05 if no perTaskCostEstimate is set
-			const perTaskEstimate = state.config.perTaskCostEstimate > 0
-				? state.config.perTaskCostEstimate
-				: 0.05;
-			const currentTotal = state.getSessionTotalCost(ctx);
-			if (state.checkCostLimit(perTaskEstimate, ctx)) {
-				const limit = state.config.sessionCostLimit;
-				log.warn("Subagent delegation rejected: session cost limit reached", {
-					currentTotal,
-					estimatedCost: perTaskEstimate,
-					limit,
-				});
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text:
-								`Cannot delegate: session cost limit reached ` +
-								`($${currentTotal.toFixed(4)} spent of $${limit.toFixed(2)} limit). ` +
-								`Increase the limit via /brl-subagent costlimit or set to 0 for unlimited.`,
-						},
-					],
-					details: undefined,
-					isError: true,
-				};
-			}
+			const costError = gateSessionCost({
+				state,
+				ctx,
+				log,
+				units: 1,
+				label: "Subagent delegation",
+			});
+			if (costError) return costError;
 
 			// Reject delegation if recursion depth exceeds configured max.
 			// This prevents subagents from spawning infinite sub-subagents while
@@ -2950,6 +3375,7 @@ export default function (pi: ExtensionAPI) {
 				resolvedApprovalMode,
 				resolvedPreset,
 				autoRoutedPreset,
+				autoRouteKeyword,
 			} = resolveSubagentParams({ ...params, task: singleTask }, state, ctx, log);
 
 			// F1: Validate CWD
@@ -2991,12 +3417,14 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// H1: Pre-task validation — deterministic check that tools/thinking match task
+			// (`force` degrades capability errors to warnings — B2's override).
 			const validation = validatePreTask({
 				task,
 				toolOptions,
 				thinkingLevel,
 				gitMode: resolvedGitMode,
 				outputFile: resolvedOutputFile,
+				force: params.force,
 			});
 			if (validation.warnings.length > 0) {
 				log.warn("Pre-task validation warnings", { warnings: validation.warnings });
@@ -3013,6 +3441,9 @@ export default function (pi: ExtensionAPI) {
 					isError: true,
 				};
 			}
+			// C: surface warnings in the returned result (not just the log) —
+			// shared renderer so foreground/background wording stays identical.
+			const warningsNote = formatValidationWarnings(validation.warnings);
 
 			// Resolve model (per-call top-level model override beats preset)
 			const modelResult = resolveSubagentModel(ctx, resolvedPreset, params.model);
@@ -3400,6 +3831,9 @@ export default function (pi: ExtensionAPI) {
 					if (suggestions.length > 0) {
 						finalMsg += "\n\nSuggestions:\n" + suggestions.map((s) => `- ${s}`).join("\n");
 					}
+					// C: warnings ride the returned result too — a failed run is
+					// exactly when the conductor most needs the mismatch signal.
+					finalMsg += warningsNote;
 
 				completeTranscript(runId, 'failed');
 
@@ -3426,16 +3860,17 @@ export default function (pi: ExtensionAPI) {
 				state.recordSuccess();
 
 				// B2: Surface auto-route decisions in the tool result so the conductor
-				// sees which preset was applied and what it restricts. Derive the
-				// restriction from the RESOLVED toolOptions (reflects per-call
-				// overrides) rather than the preset's declared values.
+				// sees WHICH preset was auto-selected, the KEYWORD evidence for it,
+				// and what it restricts. Derive the restriction from the RESOLVED
+				// toolOptions (reflects per-call overrides) rather than the preset's
+				// declared values.
 				const autoRouteNote = autoRoutedPreset
-					? `\n\n[auto-routed to preset '${autoRoutedPreset.name}' — ${toolOptions ? formatToolRestriction(toolOptions) : formatPresetRestriction(autoRoutedPreset)}]`
+					? `\n\n[auto-routed to preset '${autoRoutedPreset.name}'${autoRouteKeyword ? ` (matched keyword '${autoRouteKeyword}')` : ""} — ${toolOptions ? formatToolRestriction(toolOptions) : formatPresetRestriction(autoRoutedPreset)}]`
 					: "";
 
 				return {
 					content: [
-						{ type: "text" as const, text: (finalOutput || "(no output)") + autoRouteNote },
+						{ type: "text" as const, text: (finalOutput || "(no output)") + autoRouteNote + warningsNote },
 					],
 					details: result,
 				};
@@ -3515,11 +3950,6 @@ export default function (pi: ExtensionAPI) {
 			agent_id: Type.String({
 				description: "The agent ID returned by delegate_task when background=true",
 			}),
-			wait: Type.Optional(
-				Type.Boolean({
-					description: "If true, wait for the agent to complete before returning. Default: false.",
-				}),
-			),
 			verbose: Type.Optional(
 				Type.Boolean({
 					description: "If true, include the full conversation log. Default: false.",