pi-minimal-dispatch 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.2.0 — 2026-10-23
+
+Requires pi ≥ 1.4.0 (the MCP reach rules the validator encodes are pi
+1.4.0's documented `--tools` semantics).
+
+- `dispatch` no longer spawns blind MCP lanes: with MCP enabled, a lane whose
+  `tools` allowlist names neither `codemode` nor `tool_search` is rejected at
+  the tool boundary — pi's `--tools` allowlist replaces the whole selection,
+  and a lane never reaches MCP tools through anything else unless the server
+  has `direct` exposure (which dispatch cannot know). Pass `codemode`/
+  `tool_search` in `tools` or set `mcp: false`.
+- `tools` now accepts only a plain allowlist: `+name`/`-name` modifier lists
+  (pi applies them to its default selection, silently granting
+  `bash`/`edit`/`write`) and empty lists are rejected.
+- README and docs/API.md document the reach rule and both reach recipes; the
+  `mcp` schema text no longer claims MCP tools "stay reachable" by default.
+
+- `lanes` gained `action: "wait"` (+ `waitSec`, default 300, max 3600):
+  holds one call open, re-deriving at the `pollMs` cadence, until every lane
+  is terminal — replaces blind sleep-then-status polling (which wakes late
+  after settles); times out as a normal status result, honors cancellation.
+
 ## 0.1.0 — 2026-10-23
 
 Initial release. Requires pi ≥ 1.3.0 (1.4.0 recommended — see README).

package/README.md

@@ -24,7 +24,7 @@ the dispatcher, observable as plain files, collectible by any later session.**
 - `dispatch` returns the moment lanes are spawned — the dispatcher keeps working
 - **the deadline leash is GNU `timeout -k` around each process** — it fires even
   after the dispatcher has exited
-- a later session re-adopts any wave from its manifest: `status`, `kill`, `collect`
+- a later session re-adopts any wave from its manifest: `status`, `wait`, `kill`, `collect`
 - the final text is a file on disk (`<wave>-<name>.md`), not a block pasted back
   into the parent's context
 
@@ -36,8 +36,7 @@ crash, and never-started are indistinguishable after the fact.
 
 ## Requirements
 
-- pi ≥ 1.3.0 — 1.4.0 recommended (it fixes pi deactivating extension tools after
-  `/resume` and `/tree` navigation, which wave re-adoption relies on)
+- pi ≥ 1.4.0
 - **macOS or Linux** — Windows is not supported (the extension relies on POSIX
   process groups, `ps`, and `timeout`)
 - GNU `timeout`: preinstalled on Linux; on macOS install it with
@@ -49,8 +48,9 @@ crash, and never-started are indistinguishable after the fact.
 ## Install
 
 ```bash
-pi install git:github.com/zhtmike/pi-minimal-dispatch   # or npm:pi-minimal-dispatch
-pi -e ./src/index.ts                                    # try it for one invocation
+pi install npm:pi-minimal-dispatch                         # official (registry)
+pi install git:github.com/zhtmike/pi-minimal-dispatch      # tracks main — between releases
+pi -e ./src/index.ts                                       # try it for one invocation
 ```
 
 ## Try this first
@@ -60,29 +60,37 @@ expected deliverable), then ask in plain language:
 
 ```text
 Dispatch two lanes: docs summarizes the request-handling module, review audits src/auth.
-Poll them and collect the artifacts when they settle.
+Wait for them to settle and collect the artifacts.
 ```
 
 pi decides when to call the tools. A real session looks like:
 
 ```text
 > dispatch  wave="survey" lanes=[{name:"docs", briefPath:".pi/work/survey-docs-brief.md",
-            model:"zai/glm-5.3-flash", deadlineSec:600}]
-  wave 'survey' dispatched — 1/1 lanes spawned
-    docs: pid 99015 (deadline 600s)
+            model:"zai/glm-5.3-flash", mcp:false},
+            {name:"review", briefPath:".pi/work/survey-review-brief.md", mcp:false}]
+  wave 'survey' dispatched — 2/2 lanes spawned
+    docs: pid 99015 (deadline 900s)
+    review: pid 99016 (deadline 900s)
   manifest: /abs/path/to/.pi/work/survey-manifest.json
 
-> lanes     wave="survey"
-  docs · running · 1 turns · tok 2966in/84out, $0.0005 · stop:toolUse · last 3s ago
+> lanes     wave="survey" action="wait"
+  docs · settled · 2 turns · tok 5703in/90out, $0.0009 · stop:stop · last 0.8s ago
+  review · settled · 4 turns · tok 12021in/310out, $0.0041 · stop:stop · last 2.1s ago
 
 > lanes     wave="survey" action="collect"
   collect wave 'survey':
     docs: /abs/path/to/.pi/work/survey-docs.md stop:stop
+    review: /abs/path/to/.pi/work/survey-review.md stop:stop
 ```
 
-The ceremony is *write briefs → `dispatch` → poll `lanes status` → `collect` →
-clean up*. For a quick single task: dispatch one lane, poll once after the
-expected duration, collect — there is deliberately no blocking mode.
+The ceremony is *write briefs → `dispatch` → `lanes wait` (or poll `status`) →
+`collect` → clean up*. For a quick single task: dispatch one lane and let a
+single `wait` call hold open until it settles — no sleep-then-poll guessing,
+no waking late after a settle. `dispatch` itself never blocks; waiting is an
+explicit, bounded `lanes` call (`waitSec`, default 300, max 3600) that returns
+the status table as soon as a poll finds every lane `settled`/`failed`
+(within one `pollMs`).
 
 **Steering** is kill + redispatch: briefs are files, so refine the brief and run
 a new wave (slugs are single-use). **Hang detection**: `lastEventAgeSec` is the
@@ -98,9 +106,21 @@ Two tools — full parameter, output, and configuration reference in
   the wave slug atomically, spawn every lane detached in its own process
   group, return in under a second. Per-lane: `model`, `deadlineSec`, `tools`,
   `noExtensions`, `mcp`.
-- **`lanes`** `{wave, action?, workDir?}` — stateless `status` / `kill` /
-  `collect` over the wave's manifest; any session can re-adopt a wave,
-  including after the dispatcher exited.
+- **`lanes`** `{wave, action?, waitSec?, workDir?}` — stateless `status` /
+  `wait` / `kill` / `collect` over the wave's manifest; any session can re-adopt
+  a wave, including after the dispatcher exited.
+
+**Web/MCP reach**: the default lane is offline. MCP servers connecting grants
+nothing by themselves — a lane reaches their tools only through `codemode` or
+`tool_search` named in its `tools` (`codemode` scripts and `tool_search` wait
+for the servers they need; an `mcp__server__*` entry declares tools directly
+only when the server has `direct` exposure in `mcp.json`, so it is a scope,
+not a route). A lane that leaves MCP enabled without `codemode`/`tool_search`
+in `tools` would run blind, so `dispatch` rejects it — pass a route or set
+`mcp: false` (servers never connect). Entries reach pi verbatim, no shell
+quoting: `tools: "read,grep,find,ls,codemode"`. Plain names/patterns only:
+`+name`/`-name` modifier lists (which pi applies to its default selection,
+silently granting `bash`/`edit`/`write`) and empty lists are rejected too.
 
 ## Configuration
 
@@ -154,8 +174,9 @@ when the process crashed. The statusbar and `/lanes` are TUI/RPC-only —
 
 ```bash
 node tests/config.test.ts    # configuration precedence + validation
-node tests/derive.test.ts    # state derivation, liveness guard, event parsing
+node tests/derive.test.ts    # state derivation, wait loop, liveness guard, event parsing
 node tests/format.test.ts    # presentation formatters
+node tests/lane.test.ts      # slugs, briefs, argv, lane tool-contract validation
 bash tests/prove.sh          # integration: replays a live wave (bills models)
 ```
 

package/docs/API.md

@@ -22,9 +22,9 @@ the leash. Events stream to `<workDir>/<wave>-<name>.events.jsonl`.
 | `lanes[].briefPath` | string | — | Path to the lane's brief file (its `@file` prompt) |
 | `lanes[].model` | string? | pi default | Pin a model id; omitted: pi's **configured default model** — not the dispatcher session's active model |
 | `lanes[].deadlineSec` | number? | `deadlineSec` config (900) | Leash in seconds; holds even if the dispatcher is gone. Minimum 1 |
-| `lanes[].tools` | string? | `read,grep,find,ls` | Tool allowlist for `--tools`; add `bash` when a lane must run commands (bash can still invoke git) |
+| `lanes[].tools` | string? | `read,grep,find,ls` | Tool allowlist for `--tools` — plain names or `*` patterns; no `+name`/`-name` modifiers, no shell quoting, not empty. Add `bash` when a lane must run commands (bash can still invoke git). With MCP enabled, reach requires `codemode` or `tool_search` here — see [MCP and web reach](#mcp-and-web-reach) |
 | `lanes[].noExtensions` | boolean? | false | Pass `-ne` (drop extensions incl. MCP in the lane) |
-| `lanes[].mcp` | boolean? | reachable | Set `false` to pass `--no-mcp` (default: MCP tools stay reachable per pi's tool-exposure rules) |
+| `lanes[].mcp` | boolean? | enabled | Set `false` to pass `--no-mcp` (no MCP servers connect). With MCP enabled, `tools` must name `codemode` or `tool_search` or the call is rejected — servers connecting alone never declares MCP tools to the lane |
 | `workDir` | string? | `workDir` config (`.pi/work`) | Directory for manifest, events, and artifacts |
 
 **Result:** text summary plus `structuredContent` — `{ wave, manifestPath, lanes[] }`
@@ -33,7 +33,38 @@ immediately; a lane that failed to spawn appears as `SPAWN ERROR: …`.
 
 **Errors** (the whole call fails, zero lanes spawned, no slug claimed):
 a brief file missing (all missing paths listed) · malformed or duplicate slugs ·
-wave slug already exists · `timeoutBin`/`piBin` not found on `PATH`.
+`tools` that is not a plain allowlist (`+name`/`-name` modifiers, shell quoting,
+or an empty list) · a lane leaving MCP enabled while its `tools` names neither
+`codemode` nor `tool_search` · wave slug already exists · `timeoutBin`/`piBin`
+not found on `PATH`.
+
+### MCP and web reach
+
+`mcp` only controls whether servers connect; it never grants reach. A plain
+`--tools` allowlist replaces the whole selection, and pi declares a server's
+tools to the lane only through the routes below — anything else leaves
+connected servers as unreachable dead weight, so `dispatch` rejects a lane
+that leaves MCP enabled without one:
+
+- `codemode` — scripts reach every non-hidden server's tools and wait for the
+  servers they name: `tools: "read,grep,find,ls,codemode"`
+- `tool_search` — loads non-direct MCP tools on demand, waiting for all
+  servers when it runs
+
+An `mcp__server__*` entry is a *scope*, not a route: it keeps only that
+server's tools registered (for `codemode`/`tool_search` to use) and declares
+them directly **only when the server or tool has `direct` exposure** in
+`mcp.json` (`"exposure": "direct"` / `toolExposure`) — dispatch cannot know
+the lane's server exposures, so `mcp__` entries alone never satisfy the rule.
+For direct-exposure servers: `tools: "read,grep,find,ls,codemode,mcp__server__*"`
+declares the tools and keeps them callable from scripts. The MCP resource
+tools (`list_mcp_resources`, `list_mcp_resource_templates`,
+`read_mcp_resource`) are exposure-gated the same way and do not count either.
+
+Lanes that need no MCP set `mcp: false`. Entries reach pi verbatim (the
+allowlist is one argv value — no shell quoting), and `+name`/`-name` modifier
+lists are rejected because pi applies them to its default selection, silently
+granting `bash`/`edit`/`write`.
 
 **Recursion guard:** lanes run with `PI_MINIMAL_DISPATCH_CHILD=1` in their
 environment, and the extension's factory stays out of any process carrying that
@@ -49,7 +80,8 @@ fresh one after the dispatcher exited — sees the same truth.
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `wave` | string | — | Wave slug |
-| `action` | string? | `"status"` | `"status"` \| `"kill"` \| `"collect"` |
+| `action` | string? | `"status"` | `"status"` \| `"wait"` \| `"kill"` \| `"collect"` |
+| `waitSec` | number? | `300` | `wait` only: max seconds to hold the call open (1–3600) |
 | `workDir` | string? | `workDir` config (`.pi/work`) | Directory holding the manifest |
 
 ### `status`
@@ -71,6 +103,18 @@ Per-lane `structuredContent` entries. Note: `settled` only means the
 | `spawnError` | string? | why a `spawn`-failed lane never started |
 | `errTail` | string? | last lines of `.err` for `crashed` lanes |
 
+### `wait`
+
+Holds the tool call open, re-reading the manifest and re-deriving state every
+`pollMs`, until every lane is terminal (`settled` or `failed`), `waitSec`
+(default 300, max 3600) elapses, or the call is cancelled — then returns
+exactly the `status` payload. A timeout is **not** an error: lanes still
+running show as `running`, and the caller waits again (or proceeds to
+`kill`/`collect`, which refuse running lanes as usual). This replaces
+sleep-then-status polling, which guesses the duration and wakes late after a
+settle. `dispatch` still returns in under a second — blocking is always this
+explicit, bounded observation call, and the deadline leash needs no observer.
+
 ### `kill`
 
 SIGTERM to each eligible lane's process group (never a

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-minimal-dispatch",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Minimal detached lane dispatch with visible state for the pi coding agent — dispatch/lanes tools over a manifest + JSON-event protocol",
 	"author": "Mike Cheung",
 	"keywords": [

package/src/derive.ts

@@ -159,6 +159,53 @@ export function deriveLane(lane: LaneRecord, now: number): LaneStatus {
 	};
 }
 
+/** Whether every lane of a wave has reached a terminal state (`settled` or `failed`). */
+export function waveTerminal(lanes: LaneRecord[], now: number): boolean {
+	return lanes.every((lane) => {
+		const state = deriveLane(lane, now).state;
+		return state === "settled" || state === "failed";
+	});
+}
+
+/**
+ * Poll a wave until every lane is terminal, `waitMs` elapses, or the signal
+ * aborts; returns the final statuses. Re-reads the manifest on every poll —
+ * the same derived truth as the status action, held open.
+ */
+export async function waitForTerminal(
+	workDir: string,
+	wave: string,
+	waitMs: number,
+	pollMs: number,
+	signal?: AbortSignal,
+): Promise<LaneStatus[]> {
+	const deadline = Date.now() + waitMs;
+	for (;;) {
+		const lanes = readManifest(workDir, wave).lanes;
+		const now = Date.now();
+		if (waveTerminal(lanes, now) || now >= deadline || signal?.aborted) {
+			return lanes.map((lane) => deriveLane(lane, now));
+		}
+		// The sleep races the abort so a cancelled call returns at once, not at the next poll.
+		await new Promise<void>((resolve) => {
+			const delay = Math.min(pollMs, deadline - now);
+			if (signal === undefined) {
+				setTimeout(resolve, delay);
+				return;
+			}
+			const timer = setTimeout(() => {
+				signal.removeEventListener("abort", onAbort);
+				resolve();
+			}, delay);
+			const onAbort = () => {
+				clearTimeout(timer);
+				resolve();
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+}
+
 /** Final assistant message text (concatenated text blocks of the last assistant message_end). */
 export function finalAssistantText(events: LaneEvent[]): string {
 	let text = "";

package/src/index.ts

@@ -23,10 +23,11 @@ import {
 	pidAlive,
 	psLstart,
 	readManifest,
+	waitForTerminal,
 	writeManifestAtomic,
 } from "./derive.ts";
 import { formatStatusBarSummary, formatWaveStatus } from "./format.ts";
-import { type LaneParams, assertSlugs, buildLaneArgs, laneEnv, missingBriefs, resolveExecutable, selectKillTargets } from "./lane.ts";
+import { type LaneParams, assertLaneTools, assertSlugs, buildLaneArgs, laneEnv, missingBriefs, resolveExecutable, selectKillTargets } from "./lane.ts";
 
 /** Spawn one lane detached; a failure at any step becomes the record's spawnError, never a throw. */
 function spawnLane(workDir: string, wave: string, lane: LaneParams, cfg: DispatchConfig, timeoutBin: string): LaneRecord {
@@ -97,7 +98,8 @@ const dispatchTool = defineTool({
 		"process group, streaming JSON events to <workDir>/<wave>-<name>.events.jsonl. Lanes survive this " +
 		"session's exit. Write briefs first — one brief file per lane is the lane's entire prompt; " +
 		"lanes run in fresh processes (JSON event mode, no session) with skills unloaded (-ns), " +
-		"a read-only tool default, and never the dispatch tool itself. Every lane in the call is " +
+		"a read-only tool default, MCP reach only via a route named in tools (else set mcp: false), " +
+		"and never the dispatch tool itself. Every lane in the call is " +
 		"spawned — the caller bounds the wave. " +
 		"Then poll with the lanes tool; collect artifacts when settled.",
 	parameters: Type.Object({
@@ -108,9 +110,9 @@ const dispatchTool = defineTool({
 				briefPath: Type.String({ description: "Path to the lane's brief file (@file prompt)" }),
 				model: Type.Optional(Type.String({ description: "Pin a model id for this lane; omitted: pi's configured default model — not necessarily the dispatcher session's active model" })),
 				deadlineSec: Type.Optional(Type.Number({ description: "Deadline leash in seconds (config default: 900)", minimum: 1 })),
-				tools: Type.Optional(Type.String({ description: "Tool allowlist for --tools; omitted: 'read,grep,find,ls' — add 'bash' when a lane must run commands (bash can still invoke git)" })),
+				tools: Type.Optional(Type.String({ description: "Tool allowlist for --tools; omitted: 'read,grep,find,ls' — add 'bash' when a lane must run commands (bash can still invoke git). Plain names or mcp__/tool patterns only: +name/-name modifiers, shell quoting, and empty lists are rejected. With mcp enabled, MCP/web tools are reachable only through 'codemode' or 'tool_search' named here ('mcp__server__*' entries declare tools directly only for direct-exposure servers)" })),
 				noExtensions: Type.Optional(Type.Boolean({ description: "Pass -ne (drop extensions incl. MCP)" })),
-				mcp: Type.Optional(Type.Boolean({ description: "Set false to pass --no-mcp (default: MCP tools stay reachable per pi's tool-exposure rules)" })),
+				mcp: Type.Optional(Type.Boolean({ description: "Set false to pass --no-mcp (no MCP servers connect). Servers connecting alone grants no reach: with mcp enabled, tools must name 'codemode' or 'tool_search' or dispatch rejects the lane" })),
 			}),
 			{ minItems: 1 },
 		),
@@ -130,6 +132,9 @@ const dispatchTool = defineTool({
 			throw new Error(`brief file(s) not found: ${missing.join(", ")} — nothing spawned`);
 		}
 
+		// Tool contracts are validated before the manifest claim: a post-claim throw would strand the slug.
+		assertLaneTools(params.lanes);
+
 		// Claim the wave slug atomically; an existing manifest rejects it.
 		const manifestPath = manifestPathFor(workDir, params.wave);
 		let claimFd: number;
@@ -204,7 +209,10 @@ const lanesTool = defineTool({
 	description:
 		"Observe/control a dispatched wave. action=status (default): per-lane derived state " +
 		"(starting/running/settled/failed + cause spawn|killed|deadline|crashed), turns, run-total usage, " +
-		"stopReason, last-event age, .err tail for crashed lanes. action=kill: SIGTERM the lane process group " +
+		"stopReason, last-event age, .err tail for crashed lanes. action=wait: hold this call open, " +
+		"re-deriving at the pollMs cadence, until every lane is settled/failed or waitSec (default 300, " +
+		"max 3600) elapses — then return the status table; replaces blind sleep-then-status polling. " +
+		"action=kill: SIGTERM the lane process group " +
 		"(SIGKILL after the configured grace), start-time guarded. action=collect: write each finished lane's final assistant " +
 		"message to <wave>-<name>.md (suspect-flagged on failure/empty/non-clean stopReason); a refusal " +
 		"(running / never spawned) is a successful result with a per-lane reason. Stateless: reads the manifest " +
@@ -213,7 +221,8 @@ const lanesTool = defineTool({
 		"it back. Discover waves: ls <workDir>/*-manifest.json.",
 	parameters: Type.Object({
 		wave: Type.String({ description: "Wave slug" }),
-		action: Type.Optional(StringEnum(["status", "kill", "collect"])),
+		action: Type.Optional(StringEnum(["status", "wait", "kill", "collect"])),
+		waitSec: Type.Optional(Type.Number({ description: "wait action only: max seconds to hold the call open (default 300; 1–3600)", minimum: 1, maximum: 3600 })),
 		workDir: Type.Optional(Type.String({ description: "Directory holding the manifest (config default: .pi/work)" })),
 	}),
 
@@ -234,6 +243,16 @@ const lanesTool = defineTool({
 			};
 		}
 
+		if (action === "wait") {
+			// A timeout is a normal status result with running lanes, never an error.
+			const statuses = await waitForTerminal(workDir, params.wave, (params.waitSec ?? 300) * 1000, cfg.pollMs, signal);
+			return {
+				content: [{ type: "text", text: formatWaveStatus(params.wave, statuses) }],
+				structuredContent: { wave: params.wave, lanes: statuses },
+				details: { wave: params.wave },
+			};
+		}
+
 		if (action === "kill") {
 			const killed: string[] = [];
 			try {

package/src/lane.ts

@@ -11,6 +11,16 @@ import type { LaneRecord } from "./derive.ts";
 
 export const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
 
+/** Tool allowlist used when a lane omits `tools` — read-only by design. */
+export const DEFAULT_LANE_TOOLS = "read,grep,find,ls";
+
+/**
+ * Tools that route a lane to MCP tools whatever the servers' exposure —
+ * `mcp__` entries and the resource tools declare tools only under `direct`
+ * exposure (pi waits for those), which dispatch cannot know in advance.
+ */
+const MCP_REACH_TOOLS = ["codemode", "tool_search"];
+
 /** Lane parameters as they arrive from the dispatch tool. */
 export type LaneParams = {
 	name: string;
@@ -58,6 +68,65 @@ export function resolveExecutable(name: string): string {
 	throw new Error(`executable '${name}' not found on PATH`);
 }
 
+/** Parse a `tools` string exactly as pi parses `--tools`: split on commas, trim, drop empties. */
+export function toolEntries(lane: LaneParams): string[] {
+	return (lane.tools ?? DEFAULT_LANE_TOOLS)
+		.split(",")
+		.map((s) => s.trim())
+		.filter((e) => e !== "");
+}
+
+/** Whether a `--tools` entry matches a tool name — exact, or a `*` pattern anchored both ends (pi's matcher). */
+function entryMatches(entry: string, name: string): boolean {
+	if (!entry.includes("*")) return entry === name;
+	const source = entry.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+	return new RegExp(`^${source}$`).test(name);
+}
+
+/**
+ * Validate every lane's `tools` at the tool boundary. An allowlist names plain
+ * tools or `*` patterns — `+name`/`-name` lists are not allowlists: pi applies
+ * them to its default selection and would silently grant `bash`/`edit`/`write`.
+ * A lane that leaves MCP enabled must name `codemode` or `tool_search`, else
+ * its connected servers stay unreachable dead weight.
+ */
+export function assertLaneTools(lanes: LaneParams[]): void {
+	const problems: string[] = [];
+	for (const lane of lanes) {
+		const entries = toolEntries(lane);
+		const modifiers = entries.filter((e) => e.startsWith("+") || e.startsWith("-"));
+		if (modifiers.length > 0) {
+			problems.push(
+				`lane '${lane.name}': tools must be a plain allowlist, not +name/-name modifiers (${modifiers.join(", ")}) — ` +
+					"modifiers apply to pi's default selection and silently grant bash/edit/write; list every tool instead",
+			);
+			continue;
+		}
+		const quoted = entries.filter((e) => e.includes("'") || e.includes('"'));
+		if (quoted.length > 0) {
+			problems.push(
+				`lane '${lane.name}': tools entries must not carry shell quoting (${quoted.join(", ")}) — ` +
+					"the allowlist is one argv value and pi takes entries verbatim, so a quoted name matches no tool; write read, not 'read'",
+			);
+			continue;
+		}
+		if (entries.length === 0) {
+			problems.push(`lane '${lane.name}': tools allowlist is empty — name at least one tool`);
+			continue;
+		}
+		if (lane.mcp === false || lane.noExtensions === true) continue; // MCP never connects
+		const hasRoute = entries.some((e) => MCP_REACH_TOOLS.some((t) => entryMatches(e, t)));
+		if (!hasRoute) {
+			problems.push(
+				`lane '${lane.name}': MCP left enabled but tools '${lane.tools ?? DEFAULT_LANE_TOOLS}' grants no route to MCP tools — ` +
+					"name 'codemode' or 'tool_search' (an 'mcp__server__*' entry alone reaches only direct-exposure servers; pair it with codemode), " +
+					"or set mcp:false — entries reach pi verbatim, no shell quoting",
+			);
+		}
+	}
+	if (problems.length > 0) throw new Error(problems.join("\n"));
+}
+
 /**
  * Build the lane argv: `timeout -k <graceSec> <deadlineSec> pi --mode json
  * --no-session -ns [flags] @<brief>`. The json/no-session/-ns triple is the
@@ -78,7 +147,7 @@ export function buildLaneArgs(lane: LaneParams, cfg: Pick<DispatchConfig, "piBin
 		"-ns",
 		...(lane.noExtensions ? ["-ne"] : []),
 		"--tools",
-		lane.tools ?? "read,grep,find,ls",
+		lane.tools ?? DEFAULT_LANE_TOOLS,
 		...(lane.mcp === false ? ["--no-mcp"] : []),
 		...(lane.model ? ["--model", lane.model] : []),
 		`@${path.resolve(lane.briefPath)}`,