brl-subagent 2.3.7 → 2.3.9

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;
 }
 
 // ---------------------------------------------------------------------------
@@ -808,6 +819,27 @@ export function classifyTerminalOutcome(
 	}
 }
 
+/**
+ * Issue #179 (C1 fix): a failed run entry/result must carry a terminal reason
+ * that AGREES with its status — never undefined, never "stop". Any reason the
+ * classifier already treats as a failure (error / length / toolUse / deferred
+ * / pending / aborted) is coherent and kept; a missing or success reason is
+ * coerced to the honest failure reason derived from the classified category.
+ *
+ * Issue #187: lives here (not session-manager) so BOTH the background
+ * finalize (session-manager.ts) and the foreground finalize (history.ts) apply
+ * the SAME rule through one implementation instead of two copies.
+ */
+export function coherentFailureReason(
+	stopReason: string | undefined,
+	errorCategory: ErrorCategory | undefined,
+): string {
+	if (stopReason && classifyTerminalOutcome(stopReason).status !== "completed") {
+		return stopReason;
+	}
+	return errorCategory === "aborted" ? "aborted" : "error";
+}
+
 export function formatModel(m: { provider: string; id: string } | undefined): string {
 	return m ? `${m.provider}/${m.id}` : "Not set (will use main agent\u2019s model)";
 }

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.