brl-subagent 2.3.8 → 2.4.0

package/src/index.ts

@@ -1,3 +1,4 @@
+// Purpose: Entry point: tool/command registration, the delegate_task handlers, and the execution-mode runners.
 /**
  * brl-subagent — multi-agent orchestration for pi.
  * Entry point: tool registrations, command surface, and the multi-mode runners.
@@ -29,6 +30,7 @@ import type {
 	GraphDetails,
 	GraphWave,
 	DelegateTaskDetails,
+	DelegateTaskParams,
 	Priority,
 	TaskTemplate,
 	ToolResult,
@@ -65,10 +67,12 @@ 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";
+import { validatePreTask, diagnoseFailure, DEFAULT_BACKGROUND_DEADLINE_MS } from "./validate";
 import { findUnknownParams, KNOWN_DELEGATE_KEYS, resolveSubagentParams, snapshotOriginalParams } from "./params";
+import { delegateTaskParamsSchema } from "./schema";
 import { createSessionState } from "./state";
 import { makeLiveOnUpdate, createUnitRun, finalizeUnitRun, finalizeUnitRunCrash, pruneHistoryIfNeeded, registerLiveRun } from "./unit-run";
 import { buildSubagentPrompt, describePromptMode } from "./prompt";
@@ -99,6 +103,7 @@ import {
 	showRunHistory,
 	showMonitor,
 	showDashboard,
+	showComplianceMenu,
 	showRetryMenu,
 	renderDelegateCall,
 	renderDelegateResult,
@@ -118,35 +123,6 @@ import {
 // Helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Sanitize a text preview for markdown-rendered notifications: strip code
- * fences (``` and ~~~) and backticks, keep whole non-empty lines with
- * mid-line truncation for over-long lines, and never split surrogate pairs
- * at the boundary.
- */
-function sanitizePreview(text: string, maxLen = 500): string {
-  // Strip markdown fences and backticks
-  const cleaned = text.replace(/```/g, '').replace(/~~~+/g, '').replace(/`/g, '');
-  const lines = cleaned.split('\n').filter(l => l.trim());
-  let out = '';
-  for (const line of lines) {
-    if (out.length + line.length + 1 > maxLen) {
-      // Mid-line truncation: keep as much of this line as fits
-      const remaining = maxLen - out.length - 1;
-      if (remaining > 10) {
-        out += line.slice(0, remaining - 3) + '...\n';
-      }
-      break;
-    }
-    out += line + '\n';
-  }
-  // Avoid splitting surrogate pairs at the boundary (reachable now via slice above)
-  const safe = out.slice(0, maxLen);
-  const lastChar = safe[safe.length - 1];
-  const stripped = lastChar && /[\uD800-\uDBFF]/.test(lastChar) ? safe.slice(0, -1) : safe;
-  return stripped.trimEnd();
-}
-
 /**
  * DRY helper (issue #154 review): shape an inventory of items into a single
  * comma-delimited summary line for the LLM-facing delegation guidance. Both
@@ -191,6 +167,17 @@ export function buildTemplateGuideline(templateSummary: string): string {
 // Extension entry point
 // ---------------------------------------------------------------------------
 
+/**
+ * Compile-time coverage (issue #229 item 4): fails to compile if
+ * DelegateTaskParams omits any KNOWN_DELEGATE_KEYS entry. Runtime drift is
+ * invisible (the schema passes the key through, the handler ignores it), so
+ * only the compiler can catch it. Together with per-step-model.test.ts's
+ * runtime ratchet this closes the chain: registered schema <-> KNOWN_DELEGATE_KEYS <-> DelegateTaskParams.
+ */
+type _KnownDelegateKey = (typeof KNOWN_DELEGATE_KEYS extends Set<infer K> ? K : never) & string;
+type _ExpectNever<T extends never> = T;
+type _DelegateParamCoverage = _ExpectNever<Exclude<_KnownDelegateKey, keyof DelegateTaskParams>>;
+
 export default function (pi: ExtensionAPI) {
 	const log = createLogger("brl-subagent");
 
@@ -399,49 +386,39 @@ 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
 	// -------------------------------------------------------------------
 
 	async function runChainMode(
-		params: Record<string, unknown>,
+		params: DelegateTaskParams,
 		signal: AbortSignal | undefined,
 		onUpdate: AgentToolUpdateCallback<DelegateTaskDetails> | undefined,
 		ctx: ExtensionContext,
 	): Promise<ToolResult<SubagentResult | ChainDetails | undefined>> {
-		const chainSteps = params.chain as SubTaskParams[];
+		const chainSteps: SubTaskParams[] = params.chain!;
 
 		// Issue #133: dispatch-start timestamp — the aggregate run entry's
 		// startedAt (captured once, at mode entry, not at completion).
 		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 +498,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 +520,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 +725,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 +746,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 +891,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,
 			};
@@ -895,40 +923,22 @@ export default function (pi: ExtensionAPI) {
 	// -------------------------------------------------------------------
 
 	async function runParallelMode(
-		params: Record<string, unknown>,
+		params: DelegateTaskParams,
 		signal: AbortSignal | undefined,
 		onUpdate: AgentToolUpdateCallback<DelegateTaskDetails> | undefined,
 		ctx: ExtensionContext,
 	): Promise<ToolResult<SubagentResult | ParallelDetails | undefined>> {
-		const taskList = params.tasks as SubTaskParams[];
+		const taskList: SubTaskParams[] = params.tasks!;
 
 		// 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 +985,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 +1010,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 +1118,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 +1195,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 +1239,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 +1317,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 +1374,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,
 		};
@@ -1345,12 +1393,12 @@ export default function (pi: ExtensionAPI) {
 	// -------------------------------------------------------------------
 
 	async function runGraphMode(
-		params: Record<string, unknown>,
+		params: DelegateTaskParams,
 		signal: AbortSignal | undefined,
 		onUpdate: AgentToolUpdateCallback<DelegateTaskDetails> | undefined,
 		ctx: ExtensionContext,
 	): Promise<ToolResult<SubagentResult | GraphDetails | undefined>> {
-		const graphTasks = params.graph as GraphTask[];
+		const graphTasks: GraphTask[] = params.graph!;
 
 		// Issue #133: dispatch-start timestamp — the aggregate run entry's
 		// startedAt (captured once, at mode entry, not at completion).
@@ -1372,32 +1420,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 +1508,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 +1586,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 +1724,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 +1811,7 @@ export default function (pi: ExtensionAPI) {
 						const stepOnUpdate = makeLiveOnUpdate(state, runId, onUpdate);
 
 						const result = await runSubagent(
-							resolvedCwd,
+							nodeCwd,
 							subagentPrompt,
 							stepModel,
 							merged.thinkingLevel,
@@ -1760,7 +1862,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 +1959,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,
 			};
@@ -1890,39 +1998,21 @@ export default function (pi: ExtensionAPI) {
 	async function runBackgroundFanOut(
 		pi: ExtensionAPI,
 		ctx: ExtensionContext,
-		params: Record<string, unknown>,
+		params: DelegateTaskParams,
 		signal: AbortSignal | undefined,
 	): Promise<ToolResult<SubagentResult | undefined>> {
-		const taskList = params.tasks as SubTaskParams[];
+		const taskList: SubTaskParams[] = params.tasks!;
 
 		// Session cost limit gates the WHOLE batch before any spawn — same
 		// estimate/limit logic as runParallelMode, scaled by task count.
-		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("Background fan-out 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: "Background fan-out",
+		});
+		if (costError) return costError;
 
 		// Resolve global params once — same call shape as runParallelMode.
 		const globalParams = resolveSubagentParams(
@@ -1958,16 +2048,8 @@ export default function (pi: ExtensionAPI) {
 		// 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.
-		if (globalParams.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,
-			};
-		}
+		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.
@@ -1981,9 +2063,9 @@ export default function (pi: ExtensionAPI) {
 		// 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
-		// same-cwd-only) because the lock is keyed by the cwd string, not the
-		// repository root — different subdirectories of one repo share a working
-		// tree without sharing a lock.
+		// 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:
@@ -2006,11 +2088,10 @@ export default function (pi: ExtensionAPI) {
 			cwd: string;
 			outputFile: string | undefined;
 		};
-		const displayTaskName = (merged: ReturnType<typeof mergeSubTaskParams>): string =>
-			merged.label ??
-			(merged.task.length > 60 ? `${merged.task.slice(0, 57)}...` : merged.task);
 
 		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);
@@ -2018,48 +2099,32 @@ export default function (pi: ExtensionAPI) {
 			// Per-task model override wins; the global model is the fallback.
 			const stepModel = resolveStepModel(ctx, merged.model, globalModel);
 
-			const cwdResult = validateCwd(merged.effectiveCwd, ctx.cwd);
-			if (!cwdResult.ok) {
-				return {
-					content: [{ type: "text" as const, text: `${taskPrefix}: Invalid cwd: ${cwdResult.error}` }],
-					details: undefined,
-					isError: true,
-				};
-			}
-			let resolvedOutputFile: string | undefined;
-			if (merged.outputFile) {
-				const ofResult = validateOutputFile(merged.outputFile, cwdResult.value);
-				if (!ofResult.ok) {
-					return {
-						content: [{ type: "text" as const, text: `${taskPrefix}: Invalid outputFile: ${ofResult.error}` }],
-						details: undefined,
-						isError: true,
-					};
-				}
-				resolvedOutputFile = ofResult.value;
-			}
-
-			const validation = validatePreTask({
-				task: merged.task,
-				toolOptions: merged.toolOptions,
-				thinkingLevel: merged.thinkingLevel,
-				gitMode: globalParams.resolvedGitMode,
+			const targets = validateDelegationTargets({
+				ctx,
+				effectiveCwd: merged.effectiveCwd,
 				outputFile: merged.outputFile,
+				prefix: taskPrefix,
 			});
-			if (validation.warnings.length > 0) {
-				log.warn("Background fan-out pre-task validation warnings", { task: i + 1, warnings: validation.warnings });
-			}
-			if (!validation.valid) {
-				const errText = validation.errors.join("; ");
-				log.warn("Background fan-out pre-task validation failed", { task: i + 1, errors: validation.errors });
-				return {
-					content: [{ type: "text" as const, text: `${taskPrefix}: ${errText}` }],
-					details: undefined,
-					isError: true,
-				};
-			}
+			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: cwdResult.value, outputFile: resolvedOutputFile });
+			fanOutTasks.push({ merged, model: stepModel, cwd: targets.cwd, outputFile: targets.outputFile });
 		}
 
 		// Spawn pass — sequential, in task order, through the shared tail.
@@ -2112,7 +2177,11 @@ export default function (pi: ExtensionAPI) {
 					timeout: merged.timeout,
 					gitMode: globalParams.resolvedGitMode,
 					// Retry parity with createUnitRun: snapshot this unit's resolved
-					// values so a retry restores them.
+					// 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,
@@ -2149,7 +2218,9 @@ export default function (pi: ExtensionAPI) {
 			started.push({ id: agent.id, label: merged.label });
 		}
 
-		// Text-only result: ids in task order + the wake hint.
+		// 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");
@@ -2157,7 +2228,8 @@ export default function (pi: ExtensionAPI) {
 			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.`
+				`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,
 		};
@@ -2167,10 +2239,10 @@ export default function (pi: ExtensionAPI) {
 	// 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.
+	// registration, footer counters, the 2s progress poller and the default
+	// deadline 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(
@@ -2326,7 +2398,7 @@ export default function (pi: ExtensionAPI) {
 						}, { deliverAs: "followUp" });
 					} else if (agent.status === 'stopped') {
 						// User-initiated stop (stop_subagent) or deadline abort
-						// (timeout/hard cap) — not a failure.
+						// (timeout/deadline) — not a failure.
 						updateProgressStatus(state, ctx);
 					} else {
 						state.completedSubagents++;
@@ -2361,20 +2433,28 @@ export default function (pi: ExtensionAPI) {
 			}
 		}, 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(() => {
+		// Default deadline: 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.
+		// Issue #240: an explicit per-agent timeout is HONORED verbatim; this
+		// deadline DEFAULTS to 30m only when no timeout is given. It is a
+		// default, not a ceiling. Issue #244: exactly ONE deadline timer per
+		// run — an explicit timeout is owned by the session-manager W3 timer,
+		// so this index timer arms ONLY on the no-timeout path, mirroring
+		// spawnBackgroundSession's `params.timeout && params.timeout > 0` guard
+		// (with no timeout, it owns the 30m default, #28).
+		const hasExplicitDeadline = spawn.timeout !== undefined && spawn.timeout > 0;
+		const hardCapMs = spawn.timeout ?? DEFAULT_BACKGROUND_DEADLINE_MS;
+		const hardCapHandle: ReturnType<typeof setTimeout> | undefined =
+			hasExplicitDeadline ? undefined : 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)`);
+					updateAgentStatus(agent.id, 'stopped', `Timed out (${hardCapMs}ms deadline)`);
 					agent._sessionRef?.abort().catch(() => {
 						// Abort may reject if the session is mid-dispose;
 						// the status flip above is already recorded.
@@ -2394,7 +2474,7 @@ export default function (pi: ExtensionAPI) {
 					// W3/poller stopped path (no completedSubagents increment).
 					updateProgressStatus(state, ctx);
 				} catch (err) {
-					// Defensive: never let the hard-cap timer throw uncaught — that would
+					// Defensive: never let the deadline 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.
@@ -2405,7 +2485,7 @@ export default function (pi: ExtensionAPI) {
 					// 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)`);
+						updateAgentStatus(agent.id, 'stopped', `Timed out (${hardCapMs}ms deadline)`);
 					} catch { /* ignore */ }
 					try {
 						setAgentFinalOutput(agent.id, extractAgentFinalOutput(agent));
@@ -2447,7 +2527,11 @@ export default function (pi: ExtensionAPI) {
 		// 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 {
+			resolvedPreset: bgResolvedPreset,
+			autoRoutedPreset: bgAutoRoutedPreset,
+			autoRouteKeyword: bgAutoRouteKeyword,
+		} = bgResolved;
 		const bgModelResult = resolveSubagentModel(ctx, bgResolvedPreset, params.model);
 		const bgModel = bgModelResult.ok
 			? `${bgModelResult.model.provider}/${bgModelResult.model.id}`
@@ -2457,16 +2541,8 @@ export default function (pi: ExtensionAPI) {
 			// 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,
-				};
-			}
+			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') {
@@ -2478,79 +2554,42 @@ export default function (pi: ExtensionAPI) {
 			// 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,
-				};
-			}
+			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 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,
+			const targets = validateDelegationTargets({
+				ctx,
+				effectiveCwd: bgResolved.effectiveCwd,
+				outputFile: bgResolved.outputFile,
 			});
-			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,
-				};
-			}
+			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.
@@ -2571,7 +2610,7 @@ export default function (pi: ExtensionAPI) {
 				thinkingLevel: bgResolved.thinkingLevel,
 				priority: params.priority,
 				systemPrompt: bgPrompt,
-				cwd: bgCwdResult.value,
+				cwd: targets.cwd,
 				toolOptions: bgResolved.toolOptions,
 				timeout: bgResolved.timeout,
 				gitMode: bgResolved.resolvedGitMode,
@@ -2579,11 +2618,11 @@ export default function (pi: ExtensionAPI) {
 				sanitizeCwd: bgResolved.effectiveCwd,
 			});
 
-			// 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.
+			// 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}' — ${bgResolved.toolOptions ? formatToolRestriction(bgResolved.toolOptions) : formatPresetRestriction(bgAutoRoutedPreset)}]`
+				? `\n\n[auto-routed to preset '${bgAutoRoutedPreset.name}'${bgAutoRouteKeyword ? ` (matched keyword '${bgAutoRouteKeyword}')` : ""} — ${bgResolved.toolOptions ? formatToolRestriction(bgResolved.toolOptions) : formatPresetRestriction(bgAutoRoutedPreset)}]`
 				: "";
 
 			return {
@@ -2594,7 +2633,10 @@ export default function (pi: ExtensionAPI) {
 						`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,
+						bgAutoRouteNote +
+						// C: warnings ride the immediate SPAWN result so the conductor
+						// can stop/re-dispatch in the same turn.
+						formatValidationWarnings(bgPreTask.warnings),
 				}],
 				details: undefined,
 			};
@@ -2648,6 +2690,11 @@ export default function (pi: ExtensionAPI) {
 				retry: () => showRetryMenu(ctx, state),
 			sla: () => showSLAConfig(ctx, state, applyConfig),
 			"sla-stats": () => showSLAStats(ctx, state),
+			// E5: the compliance report menu (file access / secrets exposure /
+			// full summary) shipped in tui.ts but had no handler key, so
+			// `/brl-subagent compliance` fell through to the config menu and the
+			// feature was unreachable (broken wiring, not dead code).
+			compliance: () => showComplianceMenu(ctx, state),
 			};
 
 			if (trimmed && trimmed in handlers) {
@@ -2707,13 +2754,13 @@ 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 default to a 30-minute deadline when no timeout is given; an explicit timeout is honored as given (30 minutes is a default, not a ceiling).",
 			"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.",
-			"Set retryOnTimeout: true to automatically retry a subagent that times out. Only retries once — the second timeout is treated as a final failure.",
+			"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 FOREGROUND subagent that times out. Only retries once — the second timeout is treated as a final failure. Background runs are not auto-retried; re-dispatch with retryRunId.",
 			"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",
@@ -2723,309 +2770,19 @@ 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 default to a 30-minute deadline when no timeout is set; an explicit timeout is honored.",
 			"",
-			"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.",
 			"Prefer a preset when the delegation matches a standard shape — review/audit/test/docs; override per-call deliberately.",
 		],
-		parameters: Type.Object({
-			task: Type.Optional(Type.String({
-				description: "Detailed description of the task for the subagent to complete (required for single mode, optional for chain/tasks/graph)",
-			})),
-			systemPrompt: Type.Optional(
-				Type.String({
-					description:
-						"Custom system prompt or additional instructions for the subagent. " +
-						"When inheritSystemPrompt is true (default), this is appended after the inherited prompt. " +
-						"When inheritSystemPrompt is false, this replaces the inherited prompt entirely.",
-				}),
-			),
-			inheritSystemPrompt: Type.Optional(
-				Type.Boolean({
-					description:
-						"Whether to inherit the main agent's system prompt. " +
-						"Default: true. Set to false to use only your custom systemPrompt, " +
-						"or to avoid passing a large inherited prompt to the subagent.",
-				}),
-			),
-			thinkingLevel: Type.Optional(
-				Type.String({
-					description:
-						"Requested thinking level for this subagent call. " +
-						"One of: off, minimal, low, medium, high, xhigh. " +
-						"Capped at the user's configured maximum. If omitted, the user's configured level is used.",
-				}),
-			),
-			outputFile: Type.Optional(
-				Type.String({
-					description:
-						"Project-relative path where the subagent should write its full findings. " +
-						"When provided, the subagent is instructed to write complete output to this file " +
-						"and return only a structured summary.",
-				}),
-			),
-			label: Type.Optional(
-				Type.String({
-					description:
-						"Human-readable label for this subagent (e.g., 'security-audit', 'docs-review'). " +
-						"Appears in the status bar and tool call display. " +
-						"Omit to use the default anonymous counter.",
-				}),
-			),
-			model: Type.Optional(Type.String({ description: "Model override (provider/model-id). Defaults to the global subagent model." })),
-			timeout: Type.Optional(
-				Type.Number({
-					description:
-						"Maximum time in milliseconds the subagent is allowed to run. " +
-						"If exceeded, the subagent is killed and an error is returned.",
-				}),
-			),
-			cwd: Type.Optional(
-				Type.String({
-					description:
-						"Working directory for the subagent. Must be an existing directory. " +
-						"Defaults to the conductor's current working directory.",
-				}),
-			),
-			tools: Type.Optional(
-				Type.Array(Type.String(), {
-					description:
-						"Explicit allowlist of tool names for the subagent. Maps to pi's --tools flag.",
-				}),
-			),
-			excludeTools: Type.Optional(
-				Type.Array(Type.String(), {
-					description:
-						"Tool names to disable for the subagent. Maps to pi's --exclude-tools flag.",
-				}),
-			),
-			noBuiltinTools: Type.Optional(
-				Type.Boolean({
-					description:
-						"Disable all built-in tools for the subagent. Maps to pi's --no-builtin-tools flag.",
-				}),
-			),
-			preset: Type.Optional(
-				Type.String({
-					description:
-						"Name of a saved delegation preset (created via /brl-subagent preset). " +
-						"Preset values are used as defaults; explicit parameters on this call override them.",
-				}),
-			),
-			template: Type.Optional(
-				Type.String({
-					description:
-						"Name of a saved task template. Use with params to fill template slots. " +
-						"Templates are file-backed: 9 builtin templates ship with the extension " +
-						"(browse via /brl-subagent templates); override or add via .md files in " +
-						"~/.pi/agent/brl-subagent/templates/ or .pi/brl-subagent/templates/ " +
-						"(project-local wins over user-global over builtin).",
-				}),
-			),
-			params: Type.Optional(
-				Type.Record(Type.String(), Type.String(), {
-					description:
-						"Parameter values for template ${param} slots. " +
-						"Keys are param names, values are the substitution text.",
-				}),
-			),
-			retryRunId: Type.Optional(
-				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.",
-				}),
-			),
-			gitMode: Type.Optional(
-				Type.String({
-					description:
-						"Git integration mode for this subagent call. " +
-						"'branch' creates a work branch, captures the diff, and switches back. " +
-						"'none' (default) does nothing. Falls back to the configured default.",
-				}),
-			),
-			retryOnTimeout: Type.Optional(
-				Type.Boolean({
-					description:
-						"If true and the subagent times out, automatically retry with the same parameters. " +
-						"Only retries once — the second timeout is treated as a final failure.",
-				}),
-			),
-			approvalMode: Type.Optional(
-				Type.String({
-					description:
-						"Change approval mode: auto (never ask), writes (ask when files changed), " +
-						"always (ask every time). Default is user config (/brl-subagent approval).",
-				}),
-			),
-			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).",
-				}),
-			),
-			priority: Type.Optional(
-				Type.Union([
-					Type.Literal("critical"),
-					Type.Literal("high"),
-					Type.Literal("normal"),
-					Type.Literal("low"),
-				], {
-					description: "Concurrency priority for this delegation: critical, high, normal, or low. Higher-priority delegations queue ahead. Defaults to normal.",
-				})
-			),
-			// Issue #114: NO per-step `priority` on chain[] — chain steps never
-			// compete for concurrency slots (the chain holds ONE slot for its whole
-			// duration); array order IS the priority.
-			chain: Type.Optional(Type.Array(Type.Object({
-				task: Type.String({ description: "Task description. Use {previous} to reference the previous step output." }),
-				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." })),
-				thinkingLevel: Type.Optional(Type.String({})),
-				cwd: Type.Optional(Type.String({})),
-				timeout: Type.Optional(Type.Number({})),
-				outputFile: Type.Optional(Type.String({})),
-				tools: Type.Optional(Type.Array(Type.String({}))),
-				excludeTools: Type.Optional(Type.Array(Type.String({}))),
-				noBuiltinTools: Type.Optional(Type.Boolean({})),
-				systemPrompt: Type.Optional(Type.String({})),
-				inheritSystemPrompt: Type.Optional(Type.Boolean({})),
-			}), {
-				description: "Sequential chain of tasks. Each step receives the previous step output via {previous} placeholder in the task string. Chain stops at the first failure. Max " + MAX_CHAIN_STEPS + " steps."
-			})),
-			tasks: Type.Optional(Type.Array(Type.Object({
-				task: Type.String({ description: "Task description for this parallel subtask" }),
-				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." })),
-				thinkingLevel: Type.Optional(Type.String({})),
-				priority: Type.Optional(
-					Type.Union([
-						Type.Literal("critical"),
-						Type.Literal("high"),
-						Type.Literal("normal"),
-						Type.Literal("low"),
-					], { description: "Concurrency priority for this subtask (overrides the call-level default)." })
-				),
-				cwd: Type.Optional(Type.String({})),
-				timeout: Type.Optional(Type.Number({})),
-				outputFile: Type.Optional(Type.String({})),
-				tools: Type.Optional(Type.Array(Type.String({}))),
-				excludeTools: Type.Optional(Type.Array(Type.String({}))),
-				noBuiltinTools: Type.Optional(Type.Boolean({})),
-				systemPrompt: Type.Optional(Type.String({})),
-				inheritSystemPrompt: Type.Optional(Type.Boolean({})),
-			}), {
-				description: "Parallel tasks to execute concurrently. All tasks run regardless of individual failures. Max " + MAX_PARALLEL_TASKS + " tasks."
-			})),
-			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." }),
-				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" })),
-				thinkingLevel: Type.Optional(Type.String({})),
-				priority: Type.Optional(
-					Type.Union([
-						Type.Literal("critical"),
-						Type.Literal("high"),
-						Type.Literal("normal"),
-						Type.Literal("low"),
-					], { description: "Concurrency priority for this subtask (overrides the call-level default)." })
-				),
-				cwd: Type.Optional(Type.String({})),
-				timeout: Type.Optional(Type.Number({})),
-				outputFile: Type.Optional(Type.String({})),
-				tools: Type.Optional(Type.Array(Type.String({}))),
-				excludeTools: Type.Optional(Type.Array(Type.String({}))),
-				noBuiltinTools: Type.Optional(Type.Boolean({})),
-				systemPrompt: Type.Optional(Type.String({})),
-				inheritSystemPrompt: Type.Optional(Type.Boolean({})),
-			}), {
-				description: "Declare tasks with dependencies. The scheduler parallelizes independent tasks and sequences dependent ones. Max " + MAX_GRAPH_TASKS + " tasks."
-			})),
-		}),
+		parameters: delegateTaskParamsSchema,
 
 		async execute(
 			_toolCallId: string,
-			params: {
-				// Schema registers task as Type.Optional — required for single mode only,
-				// omitted by chain/tasks/graph calls. Aligned with Static<TParams>.
-				task?: string;
-				label?: string;
-				model?: string;
-				preset?: string;
-				systemPrompt?: string;
-				inheritSystemPrompt?: boolean;
-				thinkingLevel?: string;
-				outputFile?: string;
-				timeout?: number;
-				cwd?: string;
-				tools?: string[];
-				excludeTools?: string[];
-				noBuiltinTools?: boolean;
-				template?: string;
-				params?: Record<string, string>;
-				retryRunId?: string;
-				retryOnTimeout?: boolean;
-				background?: boolean;
-				gitMode?: string;
-				priority?: string;
-				chain?: Array<{
-					task: string;
-					label?: string;
-					model?: string;
-					thinkingLevel?: string;
-					cwd?: string;
-					timeout?: number;
-					outputFile?: string;
-					tools?: string[];
-					excludeTools?: string[];
-					noBuiltinTools?: boolean;
-					systemPrompt?: string;
-					inheritSystemPrompt?: boolean;
-				}>;
-				tasks?: Array<{
-					task: string;
-					label?: string;
-					model?: string;
-					thinkingLevel?: string;
-					priority?: string;
-					cwd?: string;
-					timeout?: number;
-					outputFile?: string;
-					tools?: string[];
-					excludeTools?: string[];
-					noBuiltinTools?: boolean;
-					systemPrompt?: string;
-					inheritSystemPrompt?: boolean;
-				}>;
-				graph?: Array<{
-					id: string;
-					task: string;
-					label?: string;
-					model?: string;
-					dependsOn?: string[];
-					thinkingLevel?: string;
-					priority?: string;
-					cwd?: string;
-					timeout?: number;
-					outputFile?: string;
-					tools?: string[];
-					excludeTools?: string[];
-					noBuiltinTools?: boolean;
-					systemPrompt?: string;
-					inheritSystemPrompt?: boolean;
-				}>;
-			},
+			params: DelegateTaskParams,
 			signal: AbortSignal | undefined,
 			onUpdate: AgentToolUpdateCallback<DelegateTaskDetails> | undefined,
 			ctx: ExtensionContext,
@@ -3133,7 +2890,7 @@ export default function (pi: ExtensionAPI) {
 			if (params.retryRunId) {
 				const runEntry = state.findSpawnRunById(ctx, params.retryRunId);
 				if (runEntry) {
-					params = resolveRetryParams(params, runEntry);
+					params = resolveRetryParams(params, runEntry) as DelegateTaskParams;
 				} else {
 					// Issue #98: a silent no-op here made retries of background runs
 					// (which previously never wrote run entries) start as FRESH runs
@@ -3257,31 +3014,14 @@ export default function (pi: ExtensionAPI) {
 
 			// 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
@@ -3321,6 +3061,7 @@ export default function (pi: ExtensionAPI) {
 				resolvedApprovalMode,
 				resolvedPreset,
 				autoRoutedPreset,
+				autoRouteKeyword,
 			} = resolveSubagentParams({ ...params, task: singleTask }, state, ctx, log);
 
 			// F1: Validate CWD
@@ -3362,12 +3103,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 });
@@ -3384,6 +3127,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);
@@ -3771,6 +3517,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');
 
@@ -3797,16 +3546,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,
 				};
@@ -3886,11 +3636,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.",
@@ -3979,7 +3724,7 @@ export default function (pi: ExtensionAPI) {
 		label: "Steer Subagent",
 		description: [
 			"Send a steering message to a running background agent.",
-			"The message interrupts after the current tool execution.",
+			"The message is delivered after the agent's current tool call finishes, before its next model call.",
 			"Use this to redirect an agent's work without restarting it.",
 		].join(" "),
 		parameters: Type.Object({
@@ -3994,7 +3739,7 @@ export default function (pi: ExtensionAPI) {
 			const { steerAgent } = await import('./session-manager');
 			
 			try {
-				const agent = steerAgent(params.agent_id, params.message);
+				const agent = await steerAgent(params.agent_id, params.message);
 				
 				if (!agent) {
 					return {