pi-legion 2.0.0 → 2.0.2

package/src/extension/legion-status.ts

@@ -0,0 +1,172 @@
+/**
+ * `/legion status [name]` — chat text for humans.
+ *
+ * No name: the whole tree, same lines as `formatTree` (the legion_tree summary).
+ * A name: `renderLiveChildStatus`, the same text as `subagent({ action: "status" })`
+ * when a run-store child record is available.
+ */
+
+import { NODE_STATUSES, type LegionNode } from "../legion/nodes.ts";
+import { formatTree } from "./legion-tools.ts";
+import {
+	renderLiveChildStatus,
+	type LiveChildStatusInput,
+} from "./runtime.ts";
+
+/** Child snapshot the status tool already prints. `now` is supplied by the caller. */
+export type LegionChildStatusFacts = Omit<LiveChildStatusInput, "now">;
+
+export interface LegionStatusJob {
+	name: string;
+	nodeId?: string;
+	state: string;
+}
+
+export interface LegionStatusInput {
+	/** Empty shows the tree. Otherwise a node id, short id, or child name. */
+	query?: string;
+	nodes: readonly LegionNode[];
+	jobs?: readonly LegionStatusJob[];
+	/**
+	 * Persisted child behind the subagent status action.
+	 * Undefined when this process has no run-store record for the name.
+	 */
+	lookupChild?: (name: string) => LegionChildStatusFacts | undefined;
+	now?: number;
+}
+
+export interface LegionStatusReport {
+	ok: boolean;
+	text: string;
+}
+
+const LIVE_NODE_STATUSES = new Set(["starting", "running", "blocked"]);
+
+function nodesMatching(nodes: readonly LegionNode[], query: string): LegionNode[] {
+	const byId = nodes.filter((node) => node.id === query);
+	if (byId.length > 0) return byId;
+	return nodes.filter((node) =>
+		node.name === query || node.id.slice(node.id.lastIndexOf(".") + 1) === query,
+	);
+}
+
+function statusCounts(nodes: readonly LegionNode[]): string {
+	const counts = new Map<string, number>();
+	for (const node of nodes) counts.set(node.status, (counts.get(node.status) ?? 0) + 1);
+	const known = new Set<string>(NODE_STATUSES);
+	const ordered = [
+		...NODE_STATUSES.filter((status) => counts.has(status)),
+		...[...counts.keys()].filter((status) => !known.has(status)),
+	];
+	return ordered.map((status) => `${status}=${counts.get(status)}`).join(", ");
+}
+
+function withNow(facts: LegionChildStatusFacts, now: number | undefined): LiveChildStatusInput {
+	return now === undefined ? facts : { ...facts, now };
+}
+
+function liveJobForNode(node: LegionNode, jobs: readonly LegionStatusJob[]): LegionStatusJob | undefined {
+	return jobs.find((job) =>
+		job.state !== "retired" && (job.nodeId === node.id || (job.nodeId === undefined && job.name === node.name)),
+	);
+}
+
+function renderFacts(facts: LegionChildStatusFacts, now: number | undefined): string {
+	return renderLiveChildStatus(withNow(facts, now));
+}
+
+function renderNode(
+	node: LegionNode,
+	jobs: readonly LegionStatusJob[],
+	lookupChild: LegionStatusInput["lookupChild"],
+	now: number | undefined,
+): string {
+	const facts = lookupChild?.(node.name);
+	if (facts) return renderFacts(facts, now);
+	const job = liveJobForNode(node, jobs);
+	const alive = job
+		? job.state === "working" || job.state === "blocked"
+		: LIVE_NODE_STATUSES.has(node.status);
+	return renderLiveChildStatus(withNow({
+		name: node.name,
+		state: node.status,
+		agent: node.role,
+		kind: node.kind,
+		sessionFile: node.sessionFile ?? "",
+		alive,
+	}, now));
+}
+
+function renderJob(
+	job: LegionStatusJob,
+	lookupChild: LegionStatusInput["lookupChild"],
+	now: number | undefined,
+): string {
+	const facts = lookupChild?.(job.name);
+	if (facts) return renderFacts(facts, now);
+	return renderLiveChildStatus(withNow({
+		name: job.name,
+		state: job.state,
+		sessionFile: "",
+		alive: job.state === "working" || job.state === "blocked",
+	}, now));
+}
+
+function jobsOutsideTree(nodes: readonly LegionNode[], jobs: readonly LegionStatusJob[]): LegionStatusJob[] {
+	const ids = new Set(nodes.map((node) => node.id));
+	const names = new Set(nodes.map((node) => node.name));
+	return jobs.filter((job) =>
+		job.state !== "retired" &&
+		(job.nodeId === undefined || !ids.has(job.nodeId)) &&
+		!names.has(job.name),
+	);
+}
+
+function renderTree(nodes: readonly LegionNode[], jobs: readonly LegionStatusJob[]): string {
+	const noun = nodes.length === 1 ? "node" : "nodes";
+	const counts = nodes.length > 0 ? ` · ${statusCounts(nodes)}` : "";
+	const lines = [`Legion status · ${nodes.length} ${noun}${counts}`];
+	lines.push("");
+	lines.push(nodes.length > 0 ? formatTree(nodes) : "No legion nodes.");
+	const extras = jobsOutsideTree(nodes, jobs);
+	if (extras.length > 0) {
+		lines.push("", "Live jobs not in the tree:");
+		for (const job of extras) lines.push(`- ${job.name} state=${job.state}`);
+	}
+	lines.push("", "One node: /legion status <name>");
+	return lines.join("\n");
+}
+
+/** Human-readable `/legion status` text. `ok: false` is an unknown or ambiguous name. */
+export function renderLegionStatus(input: LegionStatusInput): LegionStatusReport {
+	const query = input.query?.trim() ?? "";
+	const jobs = input.jobs ?? [];
+	if (!query) return { ok: true, text: renderTree(input.nodes, jobs) };
+
+	const matches = nodesMatching(input.nodes, query);
+	if (matches.length > 1) {
+		return {
+			ok: false,
+			text: `"${query}" is ambiguous; use a full node id with /legion status <node-id>.`,
+		};
+	}
+	if (matches.length === 1) {
+		return { ok: true, text: renderNode(matches[0]!, jobs, input.lookupChild, input.now) };
+	}
+
+	const namedJobs = jobs.filter((job) => job.name === query || job.nodeId === query);
+	if (namedJobs.length > 1) {
+		return {
+			ok: false,
+			text: `"${query}" is ambiguous; use a full node id with /legion status <node-id>.`,
+		};
+	}
+	if (namedJobs.length === 1) {
+		return { ok: true, text: renderJob(namedJobs[0]!, input.lookupChild, input.now) };
+	}
+
+	const facts = input.lookupChild?.(query);
+	if (facts) return { ok: true, text: renderFacts(facts, input.now) };
+
+	return { ok: false, text: `Unknown Legion node "${query}".` };
+}

package/src/extension/legion-stop.ts

@@ -3,10 +3,9 @@
  *   - `/legion stop` (all) / `/legion stop <name>` — thin wrapper over the
  *     subagent tool's `stop` action (graceful retire; a retired parent's own
  *     session shutdown retires its subtree, so stopping a parent cascades).
- *   - Esc while the main agent is idle, the editor is empty and children are
- *     live → confirm → stop all.
  *   - `x` on the selected agent in the /legion view → confirm → stop it.
- * Everything here is pure/injectable so it can be unit tested.
+ * Esc no longer stops children (esc-no-retire-v3); only `/legion stop` or
+ * process exit retires. Everything here is pure/injectable for unit tests.
  */
 
 export interface StopJob {
@@ -114,37 +113,6 @@ export async function runLegionStop(arg: string, deps: StopDeps): Promise<string
 	return say(result.text, result.ok ? "info" : "error");
 }
 
-export interface IdleEscDeps {
-	/** Main agent not streaming / running a turn. */
-	isIdle(): boolean;
-	editorEmpty(): boolean;
-	/** An overlay, dialog or non-editor component has focus. */
-	uiBusy(): boolean;
-	liveCount(): number;
-	confirm(title: string, message: string): Promise<boolean>;
-	stopAll(): Promise<void>;
-}
-
-/**
- * Raw terminal input hook: consumes a bare Esc only when the main agent is
- * idle, the editor is empty, nothing else owns focus and children are live.
- * Every other key (and Esc in any other state) passes through to pi.
- */
-export function createIdleEscStop(deps: IdleEscDeps): (data: string) => { consume: true } | undefined {
-	let prompting = false;
-	return (data) => {
-		if (data !== "\x1b" || prompting) return undefined;
-		const count = deps.liveCount();
-		if (count === 0 || !deps.isIdle() || !deps.editorEmpty() || deps.uiBusy()) return undefined;
-		prompting = true;
-		void deps.confirm("Stop subagents", `Stop ${count} running subagent${count === 1 ? "" : "s"}?`)
-			.then((yes) => (yes ? deps.stopAll() : undefined))
-			.catch(() => {})
-			.finally(() => { prompting = false; });
-		return { consume: true };
-	};
-}
-
-/** Dim hint shown in the railway header while the main agent is idle and children are live. */
-export const IDLE_STOP_HINT = "esc stop all · /legion stop [name]";
-export const IDLE_STOP_HINT_SHORT = "esc stop all";
+/** Dim hint shown in the status strip while children are live (aboveEditor / tree). */
+export const IDLE_STOP_HINT = "/legion stop [name|all]";
+export const IDLE_STOP_HINT_SHORT = "/legion stop";

package/src/extension/playbook.ts

@@ -7,10 +7,10 @@ export const PLAYBOOK_NAME = "pi-legion-playbook";
 export const PARENT_PLAYBOOK = [
 	"Pi Legion playbook (frozen — do not invent a launch recipe):",
 	"1. Call the `subagent` tool immediately with the matching role from the roster in this prompt. Do not substitute bash/curl/web fetch for a search or research role.",
-	'   One child:  subagent({ agent: "<role>", task: "..." })',
+	'   One child:  subagent({ agent: "<role>", task: "...", name?: "scout-a" })  // optional name= registers that handle (not auto scout-N)',
 	"   Parallel:   subagent({ tasks: [{ agent, task }, { agent, task }] })",
 	"2. Prefer tasks[] for independent parallel work. Child processes are headless RPC children; no pane or tab is created.",
-	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` when you need blocking results, and `collect` to inspect a child's session JSONL. Pressing Esc to abort a parent turn gracefully retires its children; a wait interrupted by Esc returns `interrupted (parent turn aborted)` after cascade shutdown.",
+	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` when you need blocking results, and `collect` to inspect a child's session JSONL. Esc / wait interrupt only ends the parent turn's wait — children keep running and settle still notifies; only an explicit `stop` or session exit retires them. A wait interrupted by Esc returns `interrupted (parent turn ended; children still running)`. In `pi --print` or JSON mode, session shutdown waits for live async children to settle (up to each child's turn timeout) before retiring them. Use same-turn `wait`/`collect` or `async: false` when that print turn must include the child's result.",
 	"4. Later control is only through `subagent({ action, name, message })`; use `stop` to gracefully retire one child or all tracked children. If a child exits oddly (Model not found, missing tools, memory refused, …), call `subagent({ action: \"diagnose\" })` or ask the user to run `/legion doctor` / `/legion doctor models` — children use `--no-extensions`, so provider packages must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
 	"5. A collect timeout with a live RPC child is a progress signal, not a verdict. Check status or session JSONL before deciding to steer or resume.",
 	"6. Isolation is YOUR call. Pass `worktree: true` when another parent may write this repo or the child must ship via MR; pass `worktree: false` to share the checkout. Omit it for the role default.",
@@ -22,8 +22,8 @@ export const PARENT_PLAYBOOK = [
 export const TOOL_DESCRIPTION = [
 	PARENT_PLAYBOOK,
 	"Roles: the system prompt lists every loaded role. Prefer the matching role over doing that work yourself.",
-	"Launch is async by default. Outcomes come from the child session JSONL.",
-	"Actions: launch (default), continue, steer, resume, status, collect, wait, list, retire, stop, diagnose. `diagnose` prints the Legion doctor report (host vs child extensions/providers/models/memory). `wait` is event-driven: it returns when a child settles, times out, or the parent turn is aborted; an Esc abort also gracefully retires children owned by that turn. `stop` explicitly and gracefully retires selected children.",
+	"Launch is async by default. Outcomes come from the child session JSONL. In non-interactive `pi --print` / JSON mode, shutdown waits for those children before retiring them; pass `async: false` or call `wait`/`collect` in the same turn to fold the result into the print output.",
+	"Actions: launch (default), continue, steer, resume, status, collect, wait, list, retire, stop, diagnose. `diagnose` prints the Legion doctor report (host vs child extensions/providers/models/memory). `wait` is event-driven: it returns when a child settles, times out, or the parent turn is interrupted; Esc does not retire children — use `stop` (or exit the session) to retire them.",
 ].join(" ");
 
 /** Split shell commands into sequential chunks while preserving old helper API. */

package/src/extension/runtime.ts

@@ -30,7 +30,7 @@ import {
 } from "../tui/status.ts";
 import { progressFromSessionFile } from "../shared/progress.ts";
 import { isTransientConnectionFailure } from "../shared/session.ts";
-import { DEFAULTS, type AgentKind } from "../shared/types.ts";
+import { DEFAULTS, type AgentKind, type RetireOptions } from "../shared/types.ts";
 import type {
 	EventSubscriptionOptions,
 	SupervisorEvent,
@@ -81,7 +81,7 @@ export interface TrackedJobInput {
 	isAlive?: () => boolean;
 	persist?: (snapshot: CollectSnapshot) => Promise<void>;
 	/** Retire the RPC child after a terminal collect. Blocked children stay alive. */
-	retire?: () => Promise<void>;
+	retire?: (opts?: RetireOptions) => Promise<void>;
 	/**
 	 * Called when collect reports a blocked child. `resume` rewatches after
 	 * the parent approved or denied; `hold` keeps the widget up.
@@ -190,10 +190,35 @@ export function lastJsonlEventAgeMs(sessionFile: string, now: number): number |
 	}
 }
 
+/** Quiet age at or above this is treated as a long silent stretch (P2a). */
+export const LONG_QUIET_MS = 30_000;
+
+/**
+ * Lead line for a living child: process is up, session JSONL quiet for N seconds.
+ * `ageMs` undefined means the session file is missing or unreadable.
+ * Long quiet (>= {@link LONG_QUIET_MS}) adds `(living)` so 「活着但安静」reads first.
+ */
+export function formatAliveQuiet(ageMs: number | undefined): string {
+	if (ageMs === undefined) return "alive · quiet unknown";
+	const secs = Math.floor(ageMs / 1000);
+	if (ageMs >= LONG_QUIET_MS) return `alive · quiet ${secs}s (living)`;
+	return `alive · quiet ${secs}s`;
+}
+
+/** @deprecated Prefer {@link formatAliveQuiet}; kept for older call sites. */
 export function formatLastEventAge(ageMs: number): string {
 	return `last event ${Math.floor(ageMs / 1000)}s ago`;
 }
 
+/**
+ * Collect-deadline / transient-connection / "still alive" reasons are progress
+ * signals, not verdicts. Showing them next to quiet age steals the eye.
+ */
+export function isAliveProgressSignalReason(reason: string | undefined): boolean {
+	if (!reason) return false;
+	return /still alive|rpc child alive|transient connection/i.test(reason);
+}
+
 function persistedSnapshotIsStale(input: LiveChildStatusInput): boolean {
 	if (!input.alive) return false;
 	if (input.state === "retired" || input.state === "exited") return true;
@@ -202,12 +227,27 @@ function persistedSnapshotIsStale(input: LiveChildStatusInput): boolean {
 	return isTransientConnectionFailure(execution);
 }
 
+function formatExecutionStatusLine(
+	alive: boolean,
+	execution: { status: string; reason?: string },
+): string {
+	const label = alive ? "execution snapshot" : "execution";
+	// Alive + progress-signal reason: status only — quiet age owns the liveness story.
+	if (alive && isAliveProgressSignalReason(execution.reason)) {
+		return `${label}: ${execution.status}`;
+	}
+	return `${label}: ${execution.status}${execution.reason ? ` (${execution.reason})` : ""}`;
+}
+
 /**
- * Status text for one child.
+ * Status text for one child (`/legion status <name>` and `subagent status`).
  *
- * A living child always reports how long the session JSONL has been quiet.
- * A retired/failed record left behind by a connection blip is not the current
- * state while that process is still alive.
+ * Living children lead with `alive · quiet Ns` so a long silent reasoning
+ * stretch is obvious before any execution/acceptance snapshot. Progress-signal
+ * reasons (collect deadline, transient connection) are omitted from the
+ * snapshot line while alive so they do not steal attention from quiet age.
+ * A retired or failed record left by a connection blip is not treated as
+ * current state while the RPC process is still alive.
  */
 export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 	const stale = persistedSnapshotIsStale(input);
@@ -217,13 +257,18 @@ export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 		: input.execution;
 	const lines = [
 		`${input.name} — state=${state} agent=${input.agent ?? "?"} kind=${input.kind ?? "?"}`,
+	];
+	if (input.alive) {
+		const age = lastJsonlEventAgeMs(input.sessionFile, input.now ?? Date.now());
+		lines.push(formatAliveQuiet(age));
+	}
+	// Quiet age first; path metadata after snapshots so old store lines stay below.
+	const meta = [
 		"supervisor=rpc",
 		`session=${input.sessionFile}`,
 	];
 	if (execution) {
-		lines.push(
-			`execution: ${execution.status}${execution.reason ? ` (${execution.reason})` : ""}`,
-		);
+		lines.push(formatExecutionStatusLine(input.alive, execution));
 		if (execution.usage) {
 			lines.push(
 				`usage: in=${execution.usage.input} out=${execution.usage.output} cost=${execution.usage.cost.toFixed(4)}`,
@@ -231,14 +276,12 @@ export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 		}
 	}
 	if (!stale && input.acceptance) {
+		const acceptanceLabel = input.alive ? "acceptance snapshot" : "acceptance";
 		lines.push(
-			`acceptance: ${input.acceptance.status}${input.acceptance.level ? ` (${input.acceptance.level})` : ""}`,
+			`${acceptanceLabel}: ${input.acceptance.status}${input.acceptance.level ? ` (${input.acceptance.level})` : ""}`,
 		);
 	}
-	if (input.alive) {
-		const age = lastJsonlEventAgeMs(input.sessionFile, input.now ?? Date.now());
-		if (age !== undefined) lines.push(formatLastEventAge(age));
-	}
+	lines.push(...meta);
 	if (stale) {
 		const persistedExecution = input.execution
 			? `execution=${input.execution.status}${input.execution.reason ? ` (${input.execution.reason})` : ""}`
@@ -257,7 +300,7 @@ export interface WaitResult {
 	snapshot?: CollectSnapshot;
 	/** Still running when the timeout fired. */
 	stillRunning?: boolean;
-	/** The parent turn aborted while this wait was pending. */
+	/** The parent turn ended while this wait was pending; children still running. */
 	interrupted?: boolean;
 	/** Not tracked live and no finished cache (pre-validated upstream). */
 	missing?: boolean;
@@ -296,8 +339,6 @@ export interface SessionRuntime {
 	refreshUi(): void;
 	/** Live visualization data (nodes + token-rate sampler) for the /legion view. */
 	vizSnapshot(): StatusVizSnapshot;
-	/** Main agent idle flag for the railway stop hint. */
-	setParentIdle(idle: boolean): void;
 	/** TUI hosting the status widget (unknown shape; used for overlay/focus checks). */
 	statusTui(): unknown;
 	/** Forward join config to the internal coordinator (settings wiring). */
@@ -310,6 +351,11 @@ export interface SessionRuntime {
 		names: string[],
 		opts?: { timeoutMs?: number; signal?: AbortSignal },
 	): Promise<WaitResult[]>;
+	/**
+	 * Non-interactive shutdown: let in-flight collects finish before the
+	 * caller retires whatever is still alive. Watches do not re-arm.
+	 */
+	drainBeforeShutdown(): Promise<void>;
 	dispose(): void;
 }
 
@@ -329,6 +375,8 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 	let dbEventSource: DbEventSource | undefined;
 	let timer: ReturnType<typeof setInterval> | undefined;
 	let disposed = false;
+	let draining = false;
+	let drainPromise: Promise<void> | undefined;
 	let busyRaised = false;
 
 	// Smart join: batch completion notices per runId. The deliver sink merges
@@ -659,9 +707,10 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			}
 			const outcome = await Promise.race(racers);
 			if (outcome === WAIT_INTERRUPTED) {
-				// The session-level abort cascade retires this job, so do not arm
-				// a completion watcher for a child that is about to be closed.
+				// Esc / parent-turn abort does not retire children (esc-no-retire-v3).
+				// Re-arm watch so settle still notifies the parent.
 				job.consumedByTool = false;
+				if (!job.watching) runtime.watch(name);
 				return { name, interrupted: true };
 			}
 			const snapshot = outcome;
@@ -800,6 +849,15 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				try {
 					snapshot = await ensureCollect(job);
 					if (disposed || job.generation !== gen) return;
+					// Print/json shutdown is waiting on this collect. A timeout or
+					// a blocked child must stay tracked so the caller can retire
+					// it; re-arming would start another turn after the process
+					// has already decided to exit.
+					if (draining && !shouldRecycleAfterCollect(snapshot.execution.status)) {
+						hold = true;
+						job.watching = false;
+						return;
+					}
 					if (snapshot.blocked) {
 						job.state = "blocked";
 						refreshUi();
@@ -1006,9 +1064,6 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			return [...jobs.values()];
 		},
 
-		setParentIdle(idle) {
-			board.setIdleHint?.(idle);
-		},
 		statusTui() {
 			return board.getTui?.();
 		},
@@ -1087,6 +1142,26 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			);
 		},
 
+		drainBeforeShutdown() {
+			if (disposed) return Promise.resolve();
+			if (drainPromise) return drainPromise;
+			draining = true;
+			const pending = [...jobs.values()];
+			drainPromise = (async () => {
+				await Promise.all(pending.map(async (job) => {
+					try {
+						await ensureCollect(job);
+					} catch {
+						// The watch records the failure; shutdown still retires the child.
+					}
+				}));
+				// The watch continuation shares this collect and must observe
+				// `draining` before the caller snapshots the jobs it will retire.
+				await new Promise<void>((resolve) => setImmediate(resolve));
+			})();
+			return drainPromise;
+		},
+
 		dispose() {
 			if (disposed) return;
 			disposed = true;

package/src/extension/scout-guard.ts

@@ -3,8 +3,11 @@
  *
  * Counts consecutive read-like tool calls in the parent session. When the
  * streak reaches N with no subagent/vexillatio dispatch in between, inject
- * one follow-up reminder. The tool_call hook only updates state; the
- * reminder is scheduled so it cannot block the current tool call.
+ * one follow-up reminder. First-class read tools (`read`, `grep`, `find`,
+ * `ls`) count the same as read-only bash; playbooks prefer those over bash,
+ * so ignoring them let a main-session scout miss the threshold. The
+ * tool_call hook only updates state; the reminder is scheduled so it cannot
+ * block the current tool call.
  *
  * Children carry PI_SUBAGENT_ROLE and must not run this logic.
  */
@@ -74,6 +77,12 @@ const PACKAGE_WRITE = new Set([
 ]);
 
 const DISPATCH_TOOLS = new Set(["subagent", "vexillatio"]);
+/**
+ * Pi built-in read-only tools (`createReadOnlyTools`): `read`, `grep`,
+ * `find`, `ls`. `find` here is the read-only search tool, not shell `find
+ * -delete` (that path is classified from bash).
+ */
+const READ_TOOLS = new Set(["read", "grep", "find", "ls"]);
 const WRITE_TOOLS = new Set(["edit", "write"]);
 
 export function initialScoutGuardState(): ScoutGuardState {
@@ -132,7 +141,7 @@ export function classifyScoutToolCall(toolName: string, input: unknown): ScoutTo
 	if (DISPATCH_TOOLS.has(toolName)) {
 		return isDispatchCall(toolName, input) ? "dispatch" : "ignore";
 	}
-	if (toolName === "read") return "read";
+	if (READ_TOOLS.has(toolName)) return "read";
 	if (WRITE_TOOLS.has(toolName)) return "write";
 	if (toolName !== "bash") return "ignore";
 	const command = record(input)?.command;

package/src/runs/args.ts

@@ -76,6 +76,8 @@ export interface BuildArgsInput {
 	sessionFile: string;
 	/** Resolved model id, may already include a `:thinking` suffix. */
 	model?: string;
+	/** Provider id for `--provider` when the resolved model id is ambiguous. */
+	modelProvider?: string;
 	thinking?: string | false;
 	/** Where to write an oversized task / system prompt. */
 	tempDir: string;
@@ -128,7 +130,17 @@ export function buildPiArgs(input: BuildArgsInput): BuildArgsResult {
 /** `--model provider/id[:thinking]`, omitted when no model resolved. */
 function pushModelArgs(args: string[], input: BuildArgsInput): void {
 	const modelArg = applyThinkingSuffix(input.model, input.thinking);
-	if (modelArg) args.push("--model", modelArg);
+	if (!modelArg) return;
+	args.push("--model", modelArg);
+	// Pin the provider so a bare model id cannot be hijacked by a colliding
+	// static provider in models.json (#123: `workbuddy/...` ids also exist under
+	// a provider with no usable auth; under `--no-extensions` the child resolved
+	// them there and died with "No API key found"). Models may carry their own
+	// slash (e.g. `any-endpoint/workbuddy/hy4-preview-ioa`), so only the longest
+	// known provider prefix qualifies; an id with no provider stays bare, and
+	// `--provider` without `--model` is rejected by pi, so both move together.
+	const provider = input.modelProvider;
+	if (provider) args.push("--provider", provider);
 }
 
 export const CHILD_INHERIT_EXTENSIONS_ENV = "PI_LEGION_CHILD_INHERIT_EXTENSIONS";
@@ -152,6 +164,60 @@ export function childInheritsExtensions(agent: Pick<AgentConfig, "inheritExtensi
 	return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
 }
 
+/** Light pi builtin that registers the `codemode` tool (`-e builtin:codemode`). */
+export const BUILTIN_CODEMODE = "builtin:codemode";
+
+/** True for `builtin:<name>` refs — must not be `path.resolve`d. */
+export function isBuiltinExtensionRef(ext: string): boolean {
+	return ext.trimStart().startsWith("builtin:");
+}
+
+/** Dedup key for an `--extension` value (path or builtin ref). */
+export function extensionDedupeKey(ext: string): string {
+	return isBuiltinExtensionRef(ext) ? ext.trim() : path.resolve(ext);
+}
+
+export function roleListsCodemode(agent: Pick<AgentConfig, "tools">): boolean {
+	return (agent.tools ?? []).some((t) => t === "codemode");
+}
+
+export function isCodemodeExtension(ext: string): boolean {
+	const t = ext.trim();
+	return t === BUILTIN_CODEMODE || t.endsWith("/" + BUILTIN_CODEMODE);
+}
+
+/**
+ * Effective `--extension` values for a child under `--no-extensions`.
+ *
+ * Includes role `extensions` / `subagentOnlyExtensions`, `PI_LEGION_CHILD_EXTENSIONS`,
+ * auto `builtin:codemode` when `tools` lists `codemode` (#89), and the child-guard.
+ */
+export function collectChildExtensions(
+	agent: Pick<AgentConfig, "tools" | "extensions" | "subagentOnlyExtensions">,
+	env: NodeJS.ProcessEnv = process.env,
+): string[] {
+	const list = [
+		...(agent.extensions ?? []),
+		...(agent.subagentOnlyExtensions ?? []),
+		...childExtraExtensions(env),
+	];
+	// #89: codemode is a light builtin (unlike heavy pi-lens). Keep tools:codemode
+	// honest when discovery is disabled via `--no-extensions`.
+	if (roleListsCodemode(agent) && !list.some(isCodemodeExtension)) {
+		list.push(BUILTIN_CODEMODE);
+	}
+	list.push(childGuardExtensionPath());
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const ext of list) {
+		const key = extensionDedupeKey(ext);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(ext);
+	}
+	return out;
+}
+
 /** `--tools a,b`, `--no-extensions` (unless inherited), plus one `--extension` per explicit extension. */
 function pushToolArgs(args: string[], agent: AgentConfig): void {
 	const tools = agent.tools?.filter(Boolean) ?? [];
@@ -164,19 +230,9 @@ function pushToolArgs(args: string[], agent: AgentConfig): void {
 	// silently inherit every extension the parent happens to have loaded
 	// (#43: each host extension such as an LSP stack costs ~1 GB per child).
 	// `--no-extensions` stops discovery; explicit `--extension` paths below
-	// (the role's list + this package for the guard / nested spawning) still load.
+	// (the role's list + auto builtin:codemode + this package for the guard) still load.
 	if (!childInheritsExtensions(agent)) args.push("--no-extensions");
-	const extensions = [
-		...(agent.extensions ?? []),
-		...(agent.subagentOnlyExtensions ?? []),
-		...childExtraExtensions(),
-		childGuardExtensionPath(),
-	];
-	const seen = new Set<string>();
-	for (const ext of extensions) {
-		const resolved = path.resolve(ext);
-		if (seen.has(resolved)) continue;
-		seen.add(resolved);
+	for (const ext of collectChildExtensions(agent)) {
 		args.push("--extension", ext);
 	}
 }