brl-subagent 2.3.8 → 2.3.9

package/src/params.ts

@@ -23,7 +23,7 @@ import type {
 } from "./types";
 import { resolveThinkingLevel } from "./types";
 import { getAllPresets, getPreset } from "./presets";
-import { autoRoutePreset } from "./router";
+import { classifyTask } from "./router";
 import { normalizeTimeout } from "./validate";
 import type { SessionState } from "./state";
 import type { Logger } from "./logging";
@@ -49,7 +49,7 @@ export const KNOWN_DELEGATE_KEYS = new Set([
 	"outputFile", "label", "model", "timeout", "cwd", "tools",
 	"excludeTools", "noBuiltinTools", "preset", "template", "params",
 	"retryRunId", "gitMode", "retryOnTimeout", "approvalMode", "background",
-	"priority", "chain", "tasks", "graph",
+	"priority", "chain", "tasks", "graph", "force",
 ] as const);
 
 /**
@@ -76,6 +76,11 @@ export function findUnknownParams(
  * degrade retries of that path.
  * NOTE: the schema's `params` (template slots) key is intentionally NOT
  * snapshotted — it is a template-resolution input, not a retry override.
+ * The execution-shape keys (background, gitMode, approvalMode, force) ARE
+ * snapshotted: omitting them is the known failure mode of this design, since
+ * resolveRetryParams rebuilds a fresh literal and a key missing here is both
+ * unrestored AND discarded when passed explicitly on a retry call. Records
+ * written before this change simply lack the keys (additive, undefined-safe).
  */
 export function snapshotOriginalParams(params: {
 	systemPrompt?: string;
@@ -90,6 +95,10 @@ export function snapshotOriginalParams(params: {
 	excludeTools?: string[];
 	noBuiltinTools?: boolean;
 	preset?: string;
+	background?: boolean;
+	gitMode?: string;
+	approvalMode?: string;
+	force?: boolean;
 }): Record<string, unknown> {
 	return {
 		systemPrompt: params.systemPrompt,
@@ -104,6 +113,10 @@ export function snapshotOriginalParams(params: {
 		excludeTools: params.excludeTools,
 		noBuiltinTools: params.noBuiltinTools,
 		preset: params.preset,
+		background: params.background,
+		gitMode: params.gitMode,
+		approvalMode: params.approvalMode,
+		force: params.force,
 	};
 }
 
@@ -124,6 +137,12 @@ export function resolveSubagentParams(
 		gitMode?: string;
 		approvalMode?: string;
 		template?: string;
+		/**
+		 * Capability-block override: carried here so the validation call sites
+		 * (which receive the resolved params) can forward it to validatePreTask.
+		 * Resolution itself ignores it.
+		 */
+		force?: boolean;
 	},
 	state: SessionState,
 	ctx: ExtensionContext,
@@ -133,6 +152,9 @@ export function resolveSubagentParams(
 	resolvedApprovalMode: ApprovalMode;
 	resolvedPreset?: SubagentPreset;
 	autoRoutedPreset?: SubagentPreset; // set only when autoRoutePreset chose it
+	/** Set only when auto-route chose the preset: the keyword that matched —
+	 * the evidence the dispatch result surfaces (auto-route transparency). */
+	autoRouteKeyword?: string;
 } {
 	// E2: Auto-route to best preset only when the conductor expressed NO
 	// explicit preference — an explicit preset, template, or tool
@@ -140,17 +162,19 @@ export function resolveSubagentParams(
 	// that must win over keyword-based routing (issue #57).
 	let resolvedPreset = params.preset;
 	let wasAutoRouted = false;
+	let routeKeyword: string | undefined;
 	const hasExplicitToolPreference =
 		params.tools !== undefined ||
 		params.excludeTools !== undefined ||
 		params.noBuiltinTools !== undefined;
 	if (!resolvedPreset && !params.template && !hasExplicitToolPreference) {
 		const allPresets = getAllPresets(state.builtinPresets, state.customPresets);
-		const suggested = autoRoutePreset(params.task, allPresets);
-		if (suggested) {
-			resolvedPreset = suggested;
+		const matched = classifyTask(params.task, allPresets);
+		if (matched) {
+			resolvedPreset = matched.preset;
 			wasAutoRouted = true;
-			log.info("Auto-routed task to preset", { preset: suggested });
+			routeKeyword = matched.keyword;
+			log.info("Auto-routed task to preset", { preset: matched.preset, keyword: matched.keyword });
 		}
 	}
 
@@ -221,5 +245,6 @@ export function resolveSubagentParams(
 		resolvedApprovalMode,
 		resolvedPreset: preset,
 		autoRoutedPreset,
+		autoRouteKeyword: autoRoutedPreset ? routeKeyword : undefined,
 	};
 }

package/src/prelude.ts

@@ -0,0 +1,206 @@
+/**
+ * Shared guard/validation prelude for delegation modes (issue #201).
+ *
+ * delegate_task's mode handlers each open with the same prelude shape:
+ *
+ *   1. session cost gate — perTaskEstimate fallback ($0.05) →
+ *      checkCostLimit → the verbatim "Cannot delegate: session cost limit
+ *      reached …" rejection;
+ *   2. approvalMode 'always' rejection (background paths only) — the verbatim
+ *      "Cannot spawn background agent with approvalMode 'always' …";
+ *   3. cwd → outputFile → H1 pre-task validation — the same "Invalid cwd:" /
+ *      "Invalid outputFile:" / joined-errors messages, optionally
+ *      unit-prefixed (`Task 2 ("two"): …`) for per-unit loops.
+ *
+ * Each helper returns the rejection ToolResult when the gate trips and
+ * `undefined` when it passes, so call sites keep their original gate order:
+ *
+ *     const err = gateSessionCost({ … });
+ *     if (err) return err;
+ *
+ * Exception: runPreTaskValidation returns a { error?, warnings } outcome —
+ * `error` follows the same `if (outcome.error) return outcome.error` shape,
+ * and `warnings` must be surfaced in the returned tool result:
+ *
+ *     const pre = runPreTaskValidation({ … });
+ *     if (pre.error) return pre.error;
+ *
+ * Messages are byte-identical to the pre-extraction copies (the suites pin
+ * them); the parameters absorb only the real differences between sites — the
+ * cost-gate log label and unit count, and the H1 log label / unit prefix /
+ * extra log fields.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ApprovalMode, ToolResult } from "./types";
+import type { SessionState } from "./state";
+import type { Logger } from "./logging";
+import { validateCwd, validateOutputFile } from "./sanitize";
+import { validatePreTask, type ValidateConfig } from "./validate";
+
+/** The standard rejection result shape shared by these gates. */
+function rejection(text: string): ToolResult<undefined> {
+	return {
+		content: [{ type: "text" as const, text }],
+		details: undefined,
+		isError: true,
+	};
+}
+
+// ── Gate 1: session cost ────────────────────────────────────────────────
+
+/**
+ * Session cost gate (R5 / W6): falls back to the $0.05 per-unit estimate,
+ * checks the whole dispatch (units × estimate) against the session limit, and
+ * returns the verbatim rejection result when it would be exceeded.
+ *
+ * This module holds the codebase's SINGLE `checkCostLimit(perTaskEstimate * …)`
+ * site — the duplication that shape caused a mutation-target-drift incident
+ * (issue #201).
+ */
+export function gateSessionCost(input: {
+	state: SessionState;
+	ctx: ExtensionContext;
+	log: Logger;
+	/** Number of units this dispatch would spawn (1 for single-task modes). */
+	units: number;
+	/** e.g. "Parallel delegation" → log line "Parallel delegation rejected: session cost limit reached". */
+	label: string;
+}): ToolResult<undefined> | undefined {
+	const { state, ctx, log, units, label } = input;
+	const perTaskEstimate =
+		state.config.perTaskCostEstimate > 0
+			? state.config.perTaskCostEstimate
+			: 0.05;
+	if (state.checkCostLimit(perTaskEstimate * units, ctx)) {
+		const currentTotal = state.getSessionTotalCost(ctx);
+		const limit = state.config.sessionCostLimit;
+		log.warn(`${label}: session cost limit reached`, {
+			currentTotal,
+			estimatedCost: perTaskEstimate * units,
+			limit,
+		});
+		return rejection(
+			`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.`,
+		);
+	}
+	return undefined;
+}
+
+// ── Gate 2: approvalMode 'always' in background ─────────────────────────
+
+/**
+ * Background paths (single spawn and fan-out) reject approvalMode 'always'
+ * before spawning: there is no interactive dialog to approve the diff, so
+ * 'always' cannot work — reject loudly instead of running unattended with
+ * write access (W5, issue #28). Verbatim message, pinned by the suites.
+ */
+export function rejectApprovalAlwaysInBackground(
+	approvalMode: ApprovalMode,
+): ToolResult<undefined> | undefined {
+	if (approvalMode !== "always") return undefined;
+	return rejection(
+		`Cannot spawn background agent with approvalMode 'always': background agents run unattended ` +
+		`and cannot present the approval dialog. Use approvalMode 'auto' (default) or 'writes'.`,
+	);
+}
+
+// ── Gate 3a: cwd (+ outputFile) target validation ───────────────────────
+
+export type DelegationTargetsResult =
+	| { ok: true; cwd: string; outputFile: string | undefined }
+	| { ok: false; error: ToolResult<undefined> };
+
+/**
+ * Validate the dispatch's target cwd, then — when `outputFile` is given — the
+ * outputFile path (F1), returning both resolved values on success. `prefix`
+ * (a per-unit label like `Task 2 ("two")`) is prepended as `${prefix}: ` to
+ * the rejection messages; omit it for the unprefixed single-unit messages.
+ *
+ * Note: the foreground parallel mode historically validates only the cwd
+ * here (no outputFile step) — it simply passes no outputFile.
+ */
+export function validateDelegationTargets(input: {
+	ctx: ExtensionContext;
+	effectiveCwd: string;
+	/** Raw outputFile to path-validate; the step is skipped when omitted. */
+	outputFile?: string;
+	/** Unit prefix for the rejection messages, e.g. `Task 2 ("two")`. */
+	prefix?: string;
+}): DelegationTargetsResult {
+	const prefix = input.prefix ? `${input.prefix}: ` : "";
+
+	const cwdResult = validateCwd(input.effectiveCwd, input.ctx.cwd);
+	if (!cwdResult.ok) {
+		return { ok: false, error: rejection(`${prefix}Invalid cwd: ${cwdResult.error}`) };
+	}
+
+	let outputFile: string | undefined;
+	if (input.outputFile) {
+		const ofResult = validateOutputFile(input.outputFile, cwdResult.value);
+		if (!ofResult.ok) {
+			return { ok: false, error: rejection(`${prefix}Invalid outputFile: ${ofResult.error}`) };
+		}
+		outputFile = ofResult.value;
+	}
+
+	return { ok: true, cwd: cwdResult.value, outputFile };
+}
+
+// ── Gate 3b: H1 pre-task validation ─────────────────────────────────────
+
+/** Outcome of one pre-task validation: the rejection (hard failure) and/or
+ * the warnings the caller must surface in the tool result. */
+export interface PreTaskValidationOutcome {
+	/** Rejection result when validation failed (hard errors); undefined when it passed. */
+	error?: ToolResult<undefined>;
+	/** Validation warnings — surfaced in the returned tool result, not just logged. */
+	warnings: string[];
+}
+
+/**
+ * Render validation warnings for a tool result: one labelled, bulleted
+ * block. Empty input renders the empty string so results stay
+ * byte-identical when there is nothing to say.
+ */
+export function formatValidationWarnings(warnings: string[]): string {
+	if (warnings.length === 0) return "";
+	return `\n\n[pre-task validation warnings]\n` + warnings.map((w) => `- ${w}`).join("\n");
+}
+
+/**
+ * Run validatePreTask (H1) with the site's exact input, warn on warnings,
+ * and return the rejection outcome (joined errors) on hard failure.
+ * `label` names the site in the warn logs ("Parallel pre-task validation
+ * warnings" / "Background fan-out …" / "Background …"); `prefix` is
+ * prepended as `${prefix}: ` to the hard-failure message; `logContext` adds
+ * site fields to both warn entries (the fan-out adds the task index).
+ * The returned warnings are for RESULT surfacing — the log.warn calls stay
+ * regardless (a warning must reach both the log and the conductor).
+ */
+export function runPreTaskValidation(input: {
+	log: Logger;
+	preTask: ValidateConfig;
+	label: string;
+	/** Unit prefix for the rejection message, e.g. `Task 2 ("two")`. */
+	prefix?: string;
+	/** Extra structured fields merged into the warn entries. */
+	logContext?: Record<string, unknown>;
+}): PreTaskValidationOutcome {
+	const { log, preTask, label, prefix, logContext } = input;
+	const validation = validatePreTask(preTask);
+	if (validation.warnings.length > 0) {
+		log.warn(`${label} pre-task validation warnings`, { ...logContext, warnings: validation.warnings });
+	}
+	if (!validation.valid) {
+		const errText = validation.errors.join("; ");
+		log.warn(`${label} pre-task validation failed`, { ...logContext, errors: validation.errors });
+		return {
+			error: rejection(prefix ? `${prefix}: ${errText}` : errText),
+			warnings: validation.warnings,
+		};
+	}
+	return { warnings: validation.warnings };
+}

package/src/prompt.ts

@@ -52,7 +52,7 @@ export const SUBAGENT_INSTRUCTIONS =
  * - runner.ts (foreground subprocess: `-p` argument)
  * - session-manager.ts (background session: `session.prompt`)
  *
- * Deliberately applied AFTER {previous}/{otherId} substitution so substituted
+ * Deliberately applied AFTER {previous}/{<nodeId>} substitution so substituted
  * output (which may itself contain untrusted text) lands inside the fence.
  *
  * FIDELITY TRADEOFF (accepted, documented per PR #46 review M2): embedded

package/src/router.ts

@@ -105,15 +105,25 @@ function escapeRegExp(s: string): string {
 // Router
 // ---------------------------------------------------------------------------
 
+/** One auto-route decision: the selected preset AND the keyword that
+ * matched — the evidence the dispatch result must show (transparency). */
+export interface AutoRouteDecision {
+	/** The preset name selected. */
+	preset: string;
+	/** The classification keyword whose match selected the preset. */
+	keyword: string;
+}
+
 /**
- * Auto-classify a task description to the best preset personality.
+ * Auto-classify a task description to the best preset personality, returning
+ * the preset AND the matched keyword (evidence for the dispatch result).
  * Uses case-insensitive keyword matching, checked in priority order.
- * Returns the first matching preset name, or undefined if no match.
+ * Returns the first match, or undefined if no rule matches.
  */
-export function autoRoutePreset(
+export function classifyTask(
 	task: string,
 	presets: SubagentPreset[],
-): string | undefined {
+): AutoRouteDecision | undefined {
 	if (!task || task.trim().length === 0) return undefined;
 
 	const lower = task.toLowerCase();
@@ -124,10 +134,21 @@ export function autoRoutePreset(
 
 		for (const keyword of rule.keywords) {
 			if (keywordMatches(lower, keyword)) {
-				return rule.preset;
+				return { preset: rule.preset, keyword };
 			}
 		}
 	}
 
 	return undefined;
 }
+
+/**
+ * Auto-classify a task description to the best preset personality.
+ * Thin wrapper over classifyTask — preset name only, no evidence.
+ */
+export function autoRoutePreset(
+	task: string,
+	presets: SubagentPreset[],
+): string | undefined {
+	return classifyTask(task, presets)?.preset;
+}

package/src/runner.ts

@@ -245,7 +245,13 @@ function emitSubagentUpdate(
 				text: getFinalOutputFn(result.messages) || "(running...)",
 			},
 		],
-		details: { ...result },
+		// Issue #206: this is a STREAMING partial, not a verdict —
+		// isSubagentError is a settled-result predicate (a mid-run stopReason
+		// such as "toolUse" is not an error until the run actually ends), so
+		// stamping the unsettled sentinel (exitCode: -1) keeps the renderer on
+		// its running branch until the real result lands. The accumulator
+		// (`result` itself) is untouched — its exitCode stays the real code.
+		details: { ...result, exitCode: -1 },
 	});
 }
 

package/src/session-manager.ts

@@ -10,7 +10,7 @@ import { createEvent } from './event-bus';
 import { assertSafeAgentId, sanitizeErrorMessage } from './sanitize';
 import { wrapTask } from './prompt';
 import { createLogger } from './logging';
-import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, commitAll, captureWorkingDiff } from './git';
+import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
 
 const log = createLogger('brl-subagent');
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
@@ -20,7 +20,10 @@ import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-a
 var spawnQueue: Promise<void> = Promise.resolve();
 
 // C2: per-repo locks serializing the FULL gitMode=branch lifecycle (setup →
-// settle → teardown). Keyed by cwd because different repos don't conflict.
+// settle → teardown). Keyed by the resolved repository root, falling back to
+// the cwd path for directories that are not inside a repository — different
+// repos don't conflict, but different directories of one repo DO share a
+// working tree and must serialize (issue #224).
 const gitBranchLocks = new Map<string, Promise<void>>();
 
 /**
@@ -724,16 +727,18 @@ export async function spawnBackgroundSession(
     // would read the first's work branch as its base and both teardowns would
     // fight over the shared working tree (stranding the repo on an orphan
     // branch). The lock is released in cleanupWorkBranch (or on setup throw).
-    const prev = gitBranchLocks.get(gitCwd) ?? Promise.resolve();
+    // Key: resolved repository root, cwd fallback for non-repo paths (#224).
+    const lockKey = getRepoRoot(gitCwd) ?? gitCwd;
+    const prev = gitBranchLocks.get(lockKey) ?? Promise.resolve();
     let release!: () => void;
     const gate = new Promise<void>(r => { release = r; });
     const entry = prev.then(() => gate);
-    gitBranchLocks.set(gitCwd, entry);
+    gitBranchLocks.set(lockKey, entry);
     await prev;
     releaseGitLock = () => {
       // Delete the map entry ONLY if we are still the head of the chain — a
       // queued spawn behind us replaced the entry with its own.
-      if (gitBranchLocks.get(gitCwd) === entry) gitBranchLocks.delete(gitCwd);
+      if (gitBranchLocks.get(lockKey) === entry) gitBranchLocks.delete(lockKey);
       release();
     };
 

package/src/types.ts

@@ -299,6 +299,14 @@ export interface SubagentRun {
 		excludeTools?: string[];
 		noBuiltinTools?: boolean;
 		preset?: string;
+		// Issue #227: the execution-shape fields survive retries, so a retried
+		// background run stays background and a retried branch-mode run keeps its
+		// work branch, its approvalMode gating and its force override. Additive:
+		// records written before this change simply lack the keys.
+		background?: boolean;
+		gitMode?: string;
+		approvalMode?: string;
+		force?: boolean;
 		errorCategory?: ErrorCategory;
 	};
 }
@@ -504,6 +512,9 @@ export interface ResolvedParams {
 	toolOptions: SubagentToolOptions | undefined;
 	/** Set only when autoRoutePreset chose the preset (not explicitly requested). */
 	autoRoutedPreset: SubagentPreset | undefined;
+	/** Set only when auto-route chose the preset: the keyword that matched —
+	 * surfaced in the dispatch result as the auto-route evidence. */
+	autoRouteKeyword?: string;
 }
 
 // ---------------------------------------------------------------------------

package/src/unit-run.ts

@@ -122,6 +122,10 @@ export function createUnitRun(
 		// same priority the run entry itself carried.
 		priority: source.priority ?? priorityFloor,
 		startedAt: new Date().toISOString(),
+		// The execution-shape fields (background/gitMode/approvalMode/force) are
+		// deliberately omitted: a fan-out unit retries as a SINGLE run, so it must
+		// not inherit the fan-out's background-ness. A retry that wants background
+		// passes background: true explicitly.
 		originalParams: snapshotOriginalParams({
 			systemPrompt: source.customSP,
 			inheritSystemPrompt: source.inheritSP,

package/src/validate.ts

@@ -17,6 +17,15 @@ export interface ValidateConfig {
   thinkingLevel?: ThinkingLevel;
   gitMode?: string;
   outputFile?: string;
+  /**
+   * delegate_task's `force` param (default false). When true, capability
+   * ERRORS (the high-confidence capability-critical mismatches below)
+   * degrade to warning-class: they still surface in `warnings`, but
+   * `valid` stays true and dispatch proceeds. The outputFile hard
+   * conflict is NOT suppressible — a report the subagent cannot write
+   * can never succeed, so force does not apply to it.
+   */
+  force?: boolean;
 }
 
 export interface ValidateResult {
@@ -29,40 +38,109 @@ export interface ValidateResult {
 
 interface ToolRequirement {
   patterns: RegExp[];
+  /** ALL-of: every listed tool must be available (default semantics). */
   requiredTools: string[];
+  /**
+   * ANY-of: when set, ONE available tool satisfies the requirement and
+   * `requiredTools` is ignored — directory exploration is a single
+   * capability (the browse built-ins find/ls/grep and bash are
+   * interchangeable ways to do it), not a conjunction of all of them.
+   */
+  anyOfTools?: string[];
+  /**
+   * Warning lead, rendered as `Task ${description} but …` (and, under a
+   * unit prefix, `Task 1 ("deploy"): Task ${description} …`). Starts with
+   * the verb ("involves …") so the fixed `Task ` template reads naturally
+   * standalone AND prefixed — do not add a leading "task" (issue #220).
+   */
   description: string;
+  /**
+   * High-confidence, capability-critical subset of `patterns`: a task
+   * matching any of these with the capability ABSENT is promoted from
+   * warning to ERROR — dispatch does not spawn — unless `force` is set,
+   * which degrades the mismatch back to warning class. Only the two
+   * capability-critical shapes carry this: a run/execute/test/compile/
+   * benchmark task with no bash, and an exploration task with none of
+   * find/ls/grep/bash. Entry-less requirements never block (warnings only).
+   */
+  blockingPatterns?: RegExp[];
+  /**
+   * Builds the block message: names the missing capability, the resolved
+   * toolset, and the exact fix — including the force override. Receives
+   * the rendered `tools=…, excludeTools=…` toolset string.
+   */
+  blockMessage?: (toolset: string) => string;
 }
 
+/*
+ * COVERAGE BOUNDARY — which wording evades this table (every guard states
+ * its coverage). These are word-boundary keyword matches against the raw
+ * task text, nothing more. EVADED by: paraphrases that use none of the
+ * listed keywords ("hunt for drafts", "browse the repository", "see which
+ * files mention X"), inflected forms the patterns do not list ("running",
+ * "tests", "searching", "listing" — \btest\b does not match "tests"), and
+ * domain phrasing that never names the verb ("kick off CI", "smoke the
+ * pipeline"). The opposite failure is equally real: documentation/writing
+ * tasks that merely MENTION a keyword ("document how to run the tests")
+ * match too — which is why only the two high-confidence capability blocks
+ * (blockingPatterns below) escalate to errors, while install/deploy/npm/
+ * yarn/pnpm/cargo/pip stay warning-class (docs can name them without
+ * needing them). Widening the table is deliberate work: add the keyword
+ * here AND update this note.
+ */
+
 const TOOL_REQUIREMENTS: ToolRequirement[] = [
   {
     patterns: [/\b(write|create|generate|build|implement|add|insert|append)\b/i],
     requiredTools: ['write', 'edit'],
-    description: 'task involves writing/creating files',
+    description: 'involves writing/creating files',
   },
   {
     patterns: [/\b(edit|modify|update|change|fix|patch|refactor|rename)\b/i],
     requiredTools: ['write', 'edit'],
-    description: 'task involves editing files',
+    description: 'involves editing files',
   },
   {
     patterns: [/\b(run|execute|test|benchmark|compile|install|deploy|npm|yarn|pnpm|cargo|pip|vitest)\b/i],
     requiredTools: ['bash'],
-    description: 'task involves running commands',
+    description: 'involves running commands',
+    // Blocking subset: only the verbs that unambiguously DEMAND a shell.
+    // install/deploy/npm/yarn/pnpm/cargo/pip deliberately stay warning-class
+    // — documentation tasks can mention them without executing them.
+    blockingPatterns: [/\b(run|execute|test|compile|benchmark)\b/i],
+    blockMessage: (toolset) =>
+      `Cannot delegate: the task requires the 'bash' tool (running commands) but it is not available ` +
+      `in the resolved toolset (${toolset}). Fix: add 'bash' to this dispatch's tools (or remove it ` +
+      `from excludeTools) and re-dispatch, or pass force: true to dispatch anyway.`,
+  },
+  {
+    // Directory exploration is ONE capability, satisfied by ANY of the
+    // browse built-ins or bash — anyOfTools, not a conjunction.
+    patterns: [/\b(search|grep|find|list|locate|glob)\b/i],
+    requiredTools: [],
+    anyOfTools: ['find', 'ls', 'grep', 'bash'],
+    description: 'involves directory exploration',
+    blockingPatterns: [/\b(search|grep|find|list|locate|glob)\b/i],
+    blockMessage: (toolset) =>
+      `Cannot delegate: the task requires directory exploration, satisfied by any of 'find', 'ls', ` +
+      `'grep' or 'bash', but none is available in the resolved toolset (${toolset}). Fix: add any of ` +
+      `'find', 'ls', 'grep' or 'bash' to this dispatch's tools (or remove it from excludeTools) and ` +
+      `re-dispatch, or pass force: true to dispatch anyway.`,
   },
   {
     patterns: [/\b(delete|remove|clean|prune|uninstall|rm)\b/i],
     requiredTools: ['write', 'bash'],
-    description: 'task involves deleting files',
+    description: 'involves deleting files',
   },
   {
     patterns: [/\b(commit|push|pull|merge|rebase|checkout|branch)\b/i],
     requiredTools: ['bash'],
-    description: 'task involves git operations',
+    description: 'involves git operations',
   },
   {
     patterns: [/\b(audit|review|analyze|examine|check|inspect|scan|read)\b/i],
     requiredTools: ['read'],
-    description: 'task involves reading/analyzing files',
+    description: 'involves reading/analyzing files',
   },
 ];
 
@@ -225,15 +303,38 @@ export function validatePreTask(config: ValidateConfig): ValidateResult {
     return { valid: true, warnings: [], errors: [] };
   }
 
-  // Check tool requirements (warnings, not errors — conductor can override)
+  // Check tool requirements. A missing capability is warning-class by
+  // default (conductor can judge); the high-confidence capability-critical
+  // cases (blockingPatterns) are promoted to ERRORS unless `force` is set.
+  const toolset = `tools=${config.toolOptions?.tools?.join(',') ?? 'all'}, excludeTools=${config.toolOptions?.excludeTools?.join(',') ?? 'none'}`;
   for (const req of TOOL_REQUIREMENTS) {
     const matches = req.patterns.some(p => p.test(taskText));
     if (!matches) continue;
 
-    for (const tool of req.requiredTools) {
-      if (!isToolAvailable(tool, config.toolOptions)) {
+    const missing = req.anyOfTools
+      ? (req.anyOfTools.some(t => isToolAvailable(t, config.toolOptions)) ? [] : [...req.anyOfTools])
+      : req.requiredTools.filter(t => !isToolAvailable(t, config.toolOptions));
+    if (missing.length === 0) continue;
+
+    // Capability-critical block: high-confidence pattern matched AND the
+    // capability is absent. `force` degrades it to warning class below.
+    const capabilityBlock =
+      !config.force &&
+      req.blockMessage !== undefined &&
+      (req.blockingPatterns ?? []).some(p => p.test(taskText));
+    if (capabilityBlock) {
+      errors.push(req.blockMessage!(toolset));
+      continue;
+    }
+
+    if (req.anyOfTools) {
+      warnings.push(
+        `Task ${req.description} but none of ${req.anyOfTools.map(t => `'${t}'`).join(', ')} is available (${toolset})`,
+      );
+    } else {
+      for (const tool of missing) {
         warnings.push(
-          `Task ${req.description} but '${tool}' is not available (tools=${config.toolOptions?.tools?.join(',') ?? 'all'}, excludeTools=${config.toolOptions?.excludeTools?.join(',') ?? 'none'})`,
+          `Task ${req.description} but '${tool}' is not available (${toolset})`,
         );
       }
     }

package/templates/code-review.md

@@ -7,4 +7,4 @@ thinkingLevel: medium
 Review ${target} for correctness, security, and style.
 
 Report findings as a numbered list with file:line references,
-prioritized blocker → nit. Read-only — no edits.
+prioritized blocker → nit. Read-only — no edits. Any finding that rests on a search or a read states its coverage boundary: the query or command used, its count or range, and how it reconciles with what you expected to cover.

package/templates/debug-issue.md

@@ -6,4 +6,5 @@ thinkingLevel: medium
 ---
 Debug ${symptom}. Reproduce it first, then isolate the root cause.
 
-Show the failing input, the root cause, and the minimal fix.
+Show the failing input, the root cause, and the minimal fix. Final report: end with a Coverage line — the exact command or query used, the count or range it printed, and how it reconciles with the corpus you expected; show an empty result's size before treating it as absence.
+Before running any probe or reproduction, name its target by unique surrounding context and state the expected failure signature; when it runs tests, scope the run to the specific test file — a passing probe is first evidence the target was wrong, not that the behavior is fine.

package/templates/write-tests.md

@@ -7,4 +7,4 @@ thinkingLevel: medium
 Write tests for ${file} covering the happy path and edge cases.
 
 Include the test file path in your report and note any
-untestable code paths you skipped.
+untestable code paths you skipped. When designing a mutation to prove a test fails on the defect, name the target by unique surrounding context and state the expected failure first.