brl-subagent 2.3.7 → 2.3.9

package/AGENT.md

@@ -19,39 +19,51 @@ delegation-heavy work.
 | single, foreground | blocks until it returns | — (result comes back inline) | no |
 | single, background | returns immediately with an agent id | yes — a `subagent-completion` message on terminal state | no |
 | chain | blocks until the chain finishes or fails | — | yes (foreground) |
-| parallel (`tasks`) | blocks until every task finishes | — | yes (foreground) |
+| parallel (`tasks`), foreground | blocks until every task finishes | — | yes (foreground) |
+| parallel, background (fan-out) | returns immediately with one agent id per task | yes — a `subagent-completion` message per agent, on each agent's terminal state | yes |
 | graph | blocks; runs in waves via `dependsOn` | — | yes (foreground) |
 
 - Foreground single blocks: you wait for the result inline.
 - Background single returns immediately with an agent id; a completion message wakes you (see below).
-- Chain, parallel, and graph are batch — one call, many subtasks. They are foreground today; background batch is future work.
+- Chain, parallel, and graph are batch — one call, many subtasks. Chain and graph are foreground; `tasks` + `background: true` fans out: every task starts as its own background agent, the call returns with one id per task in task order, and you are woken once per agent as each finishes.
+- Fan-out validates the whole batch before spawning anything: any invalid task (cwd, `outputFile`, or a pre-task check) rejects the entire batch before a single spawn starts, and the error names the task (`Task N ("label")`).
+- Fan-out rejects `gitMode: "branch"` for the batch — the git lock is awaited inside the first spawn and held until that agent settles, so branch-mode spawns targeting the same repository would serialize and block the call (the rule is blanket because the lock is keyed by the resolved repository root, so any two units of the same repo contend). It also rejects `approvalMode: "always"` up front, and the session cost limit is checked as per-task estimate × N.
+- Spawn failure mid-loop stops further spawns and reports the failed task plus the ids already started; abort mid-loop stops further spawns and reports the ids already started. Either way those agents are detached and still wake you.
 - Chain stops at the first failure; max 10 steps.
 - Parallel runs every task regardless of the others — no short-circuit.
 - Graph runs in waves, ordered by `dependsOn` edges.
 
 ## The completion contract
 
-- A background run wakes you with a structured `subagent-completion` message when it reaches a terminal state (`completed`, `failed`, or `stopped`). The `details` carry `id`, `status`, `errorCategory` (with `errorMessage` when present), cost/tokens/duration, and `label`; the content carries a tail of output.
-- The wake triggers a turn even when you are idle. Do not poll for it.
+- A background run wakes you with a structured `subagent-completion` message when it reaches a terminal state (`completed`, `failed`, or `stopped`). The `details` carry `id`, `status`, `errorCategory` (`"unknown"` when unclassified) and `label`; `errorMessage`, `stopReason`, cost/tokens/duration ride along only when the run entry has been finalized — a `stopped` run is notified at stop time, **before** finalize, so those fields are usually absent there. The content carries a tail of output when one has been captured.
+- The wake triggers a turn even when you are idle — whenever the knob's wake condition covers that terminal status (see the matrix below). Do not poll for it.
 - Delivery mode by status holds at knob `"all"`: `failed`/`stopped` → steering you to act; `completed` → follow-up. The `completionNotify` knob changes both the delivery mode and the wake: under `"failed"` a `completed` run is delivered as a passive `nextTurn` (no wake) while `failed`/`stopped` still steer; under `"off"` everything is a passive `nextTurn` and nothing wakes you. (The knob controls whether an idle conductor is triggered — see below.)
-- Knob dependency: polling is correct only when wakes are disabled (`completionNotify: "off"`). The wake is per-terminal-status and knob-scoped: under `"all"` a terminal run always wakes you; under `"failed"` only a `failed` or `stopped` run wakes you — a `completed` run stays a passive `nextTurn` (no wake); under `"off"` nothing wakes you. So polling is wrong unless wakes are disabled. One status check as a stall check is legitimate; repeated polling is not.
-- One message per run — the extension deduplicates on the first terminal event for a run id, so don't expect multiple messages for a single run.
-- Honest records: trust the message's `category`/abort source over your own guess. The provider/abort origin is authoritative on why the run stopped.
+- Knob dependency: polling is correct only when wakes are disabled (`completionNotify: "off"`). The wake is per-terminal-status and knob-scoped: under `"all"` a terminal run always wakes you; under `"failed"` only a `failed` or `stopped` run wakes you — a `completed` run stays a passive `nextTurn` (no wake); under `"off"` nothing wakes you. So repeated polling is wrong; a single status check as a stall check is legitimate, and a status check is needed only when the knob will not wake you for that outcome (`"off"`, or a `completed` run under `"failed"`).
+- One message per run — the extension deduplicates on the first terminal event for a run id, so don't expect multiple messages for a single run. A fan-out wakes you once per agent — still one message per run (each agent is its own run), never coalesced.
+- Honest records: trust the message's `errorCategory`/abort source over your own guess. The provider/abort origin is authoritative on why the run stopped.
 - Steering is not an abort. Being steered to act on a terminal run is not terminating it. A real `stop` is an abort — and a stopped run still wakes you.
 
 ## Delegation judgment
 
-- Foreground vs background: if your next step needs the result inline, run foreground. If the user can keep working or is AFK, run background and act on the wake.
+- Foreground vs background: if your next step needs the result inline, run foreground. If the user can keep working or is AFK, run background and act on the wake. Pre-declared independent work while the user is away → `tasks` + `background: true` (fan-out); act on each wake.
 - Batch vs sequential: if the work is pre-declared, use chain/parallel/graph. If you're steering incrementally with the user, issue sequential calls.
-- Retry taxonomy: `retryRunId` is a retry — it re-runs with the recorded task and params. A re-dispatch (a fresh call with the same task text) is not a retry. Never re-issue an identical spec after a termination without confirming the cause with the user (Rule 18).
+- Retry taxonomy: `retryRunId` is a retry — it re-runs with the recorded task and params. A re-dispatch (a fresh call with the same task text) is not a retry. Never re-issue an identical spec after a termination without confirming the cause with the user.
 - When to delegate: when the task needs an isolated context, a deep investigation, parallel research, or a long-running analysis.
 - Approval: `approvalMode: "always"` is rejected in background — there is no dialog. Use `auto` (default) or `writes`; `writes` auto-approves in background.
 
+### Claim verification
+
+- Ground claims about run state, liveness, or elapsed time in observed results — the subagent result API (`get_subagent_result`), the user-visible monitor, or a command's output.
+- Do not infer liveness from a run record: an agent's output record is finalized when the run completes, so a quiet record is not evidence the agent has stopped.
+- Measure elapsed time rather than estimating it; state the measured value.
+- When a claim is unverified, say so.
+
 ## Canonical shapes
 
 - Batch chain with `{previous}`: `chain: [{ task: "…" }, { task: "Use {previous} …" }]` — each step gets the prior step's output.
 - Graph with `dependsOn`: subtasks declare edges; the scheduler runs them in waves.
 - Background + act on wake: spawn a background run, then act when the completion message arrives. Never poll between spawn and wake.
+- Background fan-out: `tasks: [...], background: true` — one background agent per task, one id per task in task order, one wake per agent.
 - retryRunId: pass a failed run's id to re-run it with its recorded task and params; explicit parameters override the originals.
 
 ## Mechanics pointer

package/README.md

@@ -2,7 +2,7 @@
 
 > Multi-agent orchestration for [pi](https://github.com/earendil-works/pi) — chain, parallel, and dependency-graph delegation to isolated subagents with per-step model routing, preset-driven tool scoping, thinking-level control, and background execution with live monitoring, real abort, and per-agent timeouts.
 
-**Version:** 2.3.7 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
+**Version:** 2.3.9 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
 
 ---
 
@@ -82,14 +82,41 @@ All settings persist across sessions.
 | `inheritSystemPrompt` | boolean | `true` | Whether to inherit the main agent's system prompt. Set `false` to save tokens. |
 | `thinkingLevel` | string | — | `off` / `minimal` / `low` / `medium` / `high` / `xhigh`. Capped at user's configured max. |
 | `outputFile` | string | — | Path for the subagent to write full findings. Returns only a summary. |
-| `timeout` | number | — | Max milliseconds. Exceeded → SIGTERM (5s grace) → SIGKILL. |
+| `timeout` | number | — | Max milliseconds. Exceeded → SIGTERM (5s grace) → SIGKILL. Background runs are additionally hard-capped at 30 minutes, so a larger value is silently shortened. |
 | `cwd` | string | — | Working directory. Defaults to conductor's cwd. |
-| `background` | boolean | `false` | Spawn as an independent background session; returns an ID immediately. See [Background execution](#background-execution). |
+| `background` | boolean | `false` | Spawn as an independent background session; returns an ID immediately. With `tasks` it fans out (one background agent per task, one ID per task), and the conductor is woken once per agent as each finishes. See [Background execution](#background-execution). |
 | `priority` | string | — | Concurrency priority: `critical` / `high` / `normal` / `low`. Defaults to `normal`; higher-priority delegations queue ahead. `tasks[]` / `graph[]` steps can set `priority` per unit (see below). |
+| `tools` | array | — | Explicit tool allowlist for the subagent. |
+| `excludeTools` | array | — | Tool names to disable for the subagent. |
+| `noBuiltinTools` | boolean | — | Disable all pi built-in tools for the subagent. |
+
+### Safety & control
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `gitMode` | string | — | `'branch'` creates a work branch, captures the diff, and switches back; `'none'` does nothing. Falls back to the configured default. |
+| `approvalMode` | string | — | `auto` / `writes` / `always`. Default is user config (`/brl-subagent approval`). `always` is rejected for background runs. |
+| `force` | boolean | `false` | Dispatch anyway past a capability pre-flight block; the block is downgraded to a warning. |
+| `retryRunId` | string | — | Re-run a previously failed run with its recorded task and params. |
+| `retryOnTimeout` | boolean | `false` | Retry once if the subagent times out. The second timeout is a final failure. |
+
+**Capability pre-flight:** before spawning, the extension checks that the resolved toolset can actually do the task — a run/execute/test/compile/benchmark task with no `bash`, or an exploration task (search/grep/find/list/locate/glob) with none of `find`/`ls`/`grep`/`bash`. Such a dispatch is **rejected** by default; `force: true` downgrades the rejection to a **warning**. `force` never suppresses an `outputFile`-without-write conflict — that stays a hard error. Warnings are surfaced in the returned result in every mode.
+
+**Retries (`retryRunId`):** a retry rebuilds the parameter object from a fixed set of fields, falling back to the original run's recorded values, with explicit values on the retry call winning: `task`, `label`, `model`, `preset`, `systemPrompt`, `inheritSystemPrompt`, `thinkingLevel`, `priority`, `outputFile`, `timeout`, `cwd`, `tools`, `excludeTools`, `noBuiltinTools`, plus the four **execution-shape** fields `background`, `gitMode`, `approvalMode` and `force`.
+
+**The execution-shape fields are restored, so a retry keeps the original's shape:** retrying a background run re-runs it in the background (with its completion wake), a `gitMode: 'branch'` retry keeps its work branch, an `approvalMode`-constrained retry keeps that gating, and a retry that was capability-blocked keeps its `force`. Passing any of them explicitly on the retry call overrides the recorded value. One qualification on `gitMode`: when neither the record nor the call carries one, the **configured** default still applies — so a user with a global `gitMode: 'branch'` gets a work branch on every retry, and one with the default `'none'` gets none. Do not assume "no work branch" without checking the effective `gitMode`.
+
+**Fan-out origins are the exception.** Parallel/chain/graph units are recorded per unit, and those records deliberately snapshot **no** `background`, so retrying a unit is a **single run in the foreground**. Pass `background: true` explicitly if you want a background retry.
+
+**Not restored:** `chain` / `tasks` / `graph` and `params` are discarded, so retrying a multi-step run silently degrades to a single task — re-issue it fresh for those shapes. `retryOnTimeout` is **explicit-only**: it is never restored from the recorded run and takes effect only when you pass it on the retry call (it arms a deadline for *this* call).
+
+**`template` is asymmetric:** the original run's template is **not** restored, but a `template` you supply explicitly on the retry call **does** take effect (it is resolved before the retry merge, issue #175) — its body wins over the recorded `task`.
 
 ## Multi-step modes (chain, tasks, graph)
 
-Beyond a single `task`, `delegate_task` accepts three multi-step shapes: `chain` (sequential steps, `{previous}` references the prior step's output), `tasks` (parallel, independent), and `graph` (dependency-ordered, `{otherId}` references another task's output).
+Beyond a single `task`, `delegate_task` accepts three multi-step shapes: `chain` (sequential steps, `{previous}` references the prior step's output), `tasks` (parallel, independent), and `graph` (dependency-ordered, `{<nodeId>}` references another node's output — the referenced node's own `id`, which must be a word-character id: letters, digits, and underscore. `{step-1}` and `{node.a}` are not matched and are left as literal text).
+
+`background: true` fans out the `tasks` shape into one background agent per task (one ID per task, one completion wake per agent); `chain` and `graph` reject it.
 
 Every execution knob can be set per step: `model`, `thinkingLevel`, `tools`, `excludeTools`, `noBuiltinTools`, `systemPrompt`, `inheritSystemPrompt`, `outputFile`, `timeout`, `cwd`. Unset fields inherit from the global parameters (and their preset defaults).
 
@@ -111,7 +138,7 @@ Stops a running background agent — a real abort, not a status flip.
 |---|---|---|
 | `agent_id` | string | Agent ID of the running background session to stop |
 
-**What it does:** aborts the live session via `session.abort()` — the pending `prompt()` resolves with `stopReason: "aborted"` rather than hanging — and marks the agent `stopped`. Partial work from a `gitMode: 'branch'` run is captured in the result before the work branch is discarded. Returns an error if the agent is not found or already terminal. Use it to halt a background agent that is no longer needed.
+**What it does:** aborts the live session via `session.abort()` — the pending `prompt()` resolves with `stopReason: "aborted"` rather than hanging — and marks the agent `stopped`. Partial work from a `gitMode: 'branch'` run is captured in the result before the work branch is discarded. Returns an error if the agent is not found; an already-terminal agent is a no-op success (the call is idempotent). Use it to halt a background agent that is no longer needed.
 
 ---
 
@@ -213,10 +240,12 @@ These are deliberately THIN teaching examples — 2-4 line bodies showing `${par
 ```js
 delegate_task({
   template: "code-review",
-  params: { pr: "https://github.com/org/repo/pull/42" },
+  params: { target: "https://github.com/org/repo/pull/42" },
 });
 ```
 
+The built-in `code-review` template's slot is `${target}` (its companion `security-audit` / `refactor` templates use `${target}` too). The `${pr}` slot in the custom-template YAML example above belongs to *that* file, not the built-in one.
+
 - Every `${param}` slot in the template must be provided in `params` — a missing slot fails the call with an error listing the missing names.
 - Template fields are **defaults**: explicitly-provided `delegate_task` parameters override them.
 - The template's task **replaces** `params.task` entirely.
@@ -252,10 +281,21 @@ Set `background: true` to spawn the subagent as an independent session that retu
 
 **Background safety controls (issue #28):** background agents honor the same safety controls as foreground runs — no more unattended sessions that bypass approval, git isolation, deadlines, or cost:
 
-- **Per-agent timeout** — the deadline is armed before the prompt starts (preflight time counts toward it). On expiry the session is aborted and the agent ends with status `stopped` and the timeout reason. Timeout values are normalized (`0`/negative/`NaN`/`Infinity`/`≥ 2^31` → no timeout) and a double-fire guard prevents the timer from acting on an already-settled agent.
-- **Session cost limit (R5)** — the cost check runs before the background spawn, so a session at its limit cannot bypass it by delegating to background.
-- **Approval mode** — `approvalMode: 'always'` is rejected for background agents (there is no interactive dialog to approve a diff while running unattended); `'writes'` silently auto-approves with a warning logged.
-- **gitMode branch isolation** — with `gitMode: 'branch'` a work branch is created before the run, the agent's changes are committed at teardown so the diff is real, the diff is captured and surfaced via `get_subagent_result`, and the branch is then switched away from and deleted. This requires a clean working tree — a dirty tree is refused loudly rather than risking the base branch.
+- **Per-agent timeout** — the deadline is armed immediately after the prompt is issued, so in-prompt preflight (auth, model resolution) counts toward it. Background timeouts are hard-capped at 30 minutes — a larger `timeout` is silently shortened. On expiry the session is aborted and the agent ends with status `stopped` and the timeout reason. Timeout values are normalized (`0`/negative/`NaN`/`Infinity`/`≥ 2^31` → no timeout) and a double-fire guard prevents the timer from acting on an already-settled agent.
+- **Session cost limit (R5)** — the cost check runs before the background spawn, so a session at its limit cannot bypass it by delegating to background. For a background fan-out the whole batch is checked up front as per-task estimate × N.
+- **Approval mode** — `approvalMode: 'always'` is rejected for background agents (there is no interactive dialog to approve a diff while running unattended); `'writes'` silently auto-approves with a warning logged. For a fan-out, `'always'` rejects the whole batch before any spawn and `'writes'` warns once for the batch.
+- **gitMode branch isolation** — with `gitMode: 'branch'` a work branch is created before the run, the agent's changes are committed at teardown so the diff is real, the diff is captured and surfaced via `get_subagent_result`, and the branch is then switched away from and deleted. This requires a clean working tree — a dirty tree is refused loudly rather than risking the base branch. `gitMode: 'branch'` is rejected for background fan-out — see [Background fan-out](#background-fan-out).
+
+### Background fan-out
+
+`background: true` with `tasks: [...]` fans out: every task starts as its own background agent, the call returns immediately with **one ID per task** in task order, and the conductor is woken with **one completion message per agent** as each finishes — no coalescing, no batch wake. `chain` and `graph` cannot be combined with `background: true` (rejected loudly): sequential dependencies and dependency waves do not survive fan-out.
+
+Fan-out validates the entire batch before spawning anything. Any invalid task — `cwd`, `outputFile`, or a pre-task check — rejects the whole batch before a single spawn starts, and the error names the task (`Task N ("label")`). Per-task overrides are honoured: `model`, `thinkingLevel`, `tools` / `excludeTools` / `noBuiltinTools`, `systemPrompt` / `inheritSystemPrompt`, `outputFile`, `timeout`, `cwd`, `priority`, `label`.
+
+Three checks reject the fan-out up front, before any spawn: `approvalMode: 'always'`; `gitMode: 'branch'` for the batch (the git lock is awaited inside the first spawn and held until that agent settles, so branch-mode spawns targeting the same repository would serialize and block the call — the rule is blanket because the lock is keyed by the resolved repository root, so any two units of the same repo contend); and the session cost limit, checked as per-task estimate × N.
+
+If a spawn fails mid-loop, fan-out stops and reports the failed task plus the IDs already started; an abort mid-loop stops further spawns. Either way, the agents already started stay detached and still wake the conductor. Everything else is unchanged: single background, foreground parallel, the `MAX_PARALLEL_TASKS` cap (8), a live-monitor row per agent, `get_subagent_result` / `steer_subagent` / `stop_subagent` by agent ID, per-agent timeouts, and a single `'writes'` approval warning for the batch.
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for the release history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brl-subagent",
-  "version": "2.3.7",
+  "version": "2.3.9",
   "description": "Subagent extension for pi with configurable model and thinking mode via selection UI",
   "keywords": [
     "pi-package"
@@ -35,10 +35,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.86.0",
-    "@earendil-works/pi-ai": "^0.86.0",
-    "@earendil-works/pi-coding-agent": "^0.86.0",
-    "@earendil-works/pi-tui": "^0.86.0",
+    "@earendil-works/pi-agent-core": "^0.87.0",
+    "@earendil-works/pi-ai": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
     "jiti": "^2.7.0",
     "typebox": "^1.3.25",
     "typescript": "^5.9.3",

package/presets/test-engineer.md

@@ -11,6 +11,7 @@ tools:
   - ls
   - write
   - edit
+  - bash
 ---
 
 # Test Engineer
@@ -32,3 +33,4 @@ You are **Test Engineer**, a specialist in test design, coverage analysis, and q
 - Use descriptive test names that explain the scenario
 - Prefer explicit assertions over snapshots
 - Mock external dependencies, not internal logic
+- Run the tests you write — use bash to verify them and report the command and result; when testing a fix, confirm the test fails on the defect first

package/src/git.ts

@@ -32,6 +32,21 @@ export function getCurrentBranch(cwd: string): string {
 	return output.trim();
 }
 
+/**
+ * Resolve the repository root that contains the given directory.
+ * Returns undefined when the directory is not inside a repository, or when
+ * git is unavailable — callers fall back to the directory path itself.
+ */
+export function getRepoRoot(cwd: string): string | undefined {
+	try {
+		const output = execFileSync("git", ["rev-parse", "--show-toplevel"], gitOpts(cwd));
+		const root = output.trim();
+		return root.length > 0 ? root : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /**
  * Check if there are uncommitted changes in the working tree.
  */

package/src/history.ts

@@ -6,7 +6,7 @@
  */
 
 import type { SubagentRun, SubagentResult } from "./types";
-import { isSubagentError, getFinalOutput, isSubagentRunShape, CUSTOM_ENTRY_TYPES, MAX_RUN_HISTORY_ENTRIES } from "./types";
+import { isSubagentError, getFinalOutput, isSubagentRunShape, classifyError, coherentFailureReason, CUSTOM_ENTRY_TYPES, MAX_RUN_HISTORY_ENTRIES } from "./types";
 import type { ExtensionContext, SessionManager } from "@earendil-works/pi-coding-agent";
 
 // ---------------------------------------------------------------------------
@@ -107,6 +107,13 @@ export function finalizeRunRecord(
 	run.tokensIn = result.usage.input;
 	run.tokensOut = result.usage.output;
 	run.errorMessage = result.errorMessage;
+	// Issue #187: mirror the background finalize rule — a FAILED run always
+	// records a terminal reason that AGREES with its status (coherentFailureReason
+	// through the shared helper), while a non-failed run records whatever reason
+	// the result carried (may be undefined, e.g. a success with no stopReason).
+	run.stopReason = error
+		? coherentFailureReason(result.stopReason, classifyError(result))
+		: result.stopReason;
 	run.outputSummary = finalOutput.slice(0, 200);
 	run.fullOutput = finalOutput || undefined;
 }
@@ -118,6 +125,15 @@ export function finalizeRunRecord(
 /**
  * Merge retry parameters: explicit params override original,
  * but task falls back to the original task if not provided.
+ *
+ * The execution-shape keys (background, gitMode, approvalMode, force) follow
+ * the same explicit-wins rule as everything else: an explicitly passed value
+ * is honoured, otherwise the recorded value is restored. Fan-out unit records
+ * (src/index.ts and unit-run.ts) snapshot their resolved unit params and do
+ * NOT set these, so a retried unit stays a single foreground run.
+ * `retryOnTimeout` is deliberately explicit-only: it arms a deadline for THIS
+ * call, so it is never inherited. `template`, `chain`, `tasks`, `graph` and
+ * `params` are not carried — a retried multi-step run degrades to a single task.
  */
 export function resolveRetryParams(
 	params: {
@@ -140,6 +156,10 @@ export function resolveRetryParams(
 		noBuiltinTools?: boolean;
 		retryRunId?: string;
 		retryOnTimeout?: boolean;
+		background?: boolean;
+		gitMode?: string;
+		approvalMode?: string;
+		force?: boolean;
 	},
 	run: SubagentRun,
 ): typeof params {
@@ -160,6 +180,10 @@ export function resolveRetryParams(
 		excludeTools: params.excludeTools ?? orig?.excludeTools,
 		noBuiltinTools: params.noBuiltinTools ?? orig?.noBuiltinTools,
 		retryOnTimeout: params.retryOnTimeout,
+		background: params.background ?? orig?.background,
+		gitMode: params.gitMode ?? orig?.gitMode,
+		approvalMode: params.approvalMode ?? orig?.approvalMode,
+		force: params.force ?? orig?.force,
 	};
 }