@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/extensions/session-bus/store.ts

@@ -11,8 +11,9 @@ import { createHash, randomBytes } from "node:crypto";
 import { mkdir, link, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { asRecord, readJson } from "../../lib/config.ts";
-import { claimsConflict } from "./protocol.ts";
+import { claimsConflict } from "./overlap.ts";
 import type { BusMessage, ClaimConflict, ClaimRecord, SessionRecord } from "./types.ts";
+import { INBOX_DIR_NAME, SESSIONS_DIR_NAME } from "../../lib/session-roster.ts";
 
 const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
@@ -27,6 +28,8 @@ export interface BusStore {
 	ensure(): Promise<void>;
 	writeSession(record: SessionRecord): Promise<void>;
 	sessions(): Promise<SessionRecord[]>;
+	/** One session's record, or undefined when it is not on disk. */
+	session(id: string): Promise<SessionRecord | undefined>;
 	removeSession(id: string): Promise<void>;
 	writeMessage(target: string, message: BusMessage): Promise<void>;
 	/** Read a recipient's messages without consuming them, oldest first. */
@@ -44,12 +47,36 @@ export interface BusStore {
 	releaseAll(owner: string): Promise<string[]>;
 	prune(input: {
 		now: number;
+		/** The sessions known to be live when the caller read the bus. */
 		activeIds: ReadonlySet<string>;
+		/**
+		 * Records whose process the caller found gone: they keep their row until their
+		 * heartbeat ages out, and own no path and no mail in the meantime.
+		 */
+		goneIds?: ReadonlySet<string>;
 		sessionTtlMs: number;
 		messageTtlMs: number;
 	}): Promise<void>;
 }
 
+/**
+ * Release each path through `release`, reporting the ones this session did not
+ * hold. One copy, because `release` and `leave` answer the same two lists, and a
+ * second loop is how the two answers drift.
+ */
+export async function releaseClaimed(
+	paths: readonly string[],
+	release: (path: string) => Promise<boolean>,
+): Promise<{ released: string[]; notOwned: string[] }> {
+	const released: string[] = [];
+	const notOwned: string[] = [];
+	for (const path of paths) {
+		if (await release(path)) released.push(path);
+		else notOwned.push(path);
+	}
+	return { released, notOwned };
+}
+
 const SHA = (value: string): string => createHash("sha256").update(value).digest("hex").slice(0, 32);
 
 function isSession(value: unknown): value is SessionRecord {
@@ -63,10 +90,18 @@ function isSession(value: unknown): value is SessionRecord {
 		typeof entry.repoRoot === "string" &&
 		typeof entry.mode === "string" &&
 		typeof entry.startedAt === "number" &&
-		typeof entry.lastSeen === "number"
+		typeof entry.lastSeen === "number" &&
+		(entry.startToken === undefined || typeof entry.startToken === "string") &&
+		(entry.watching === undefined || isWatchingState(entry.watching))
 	);
 }
 
+/** The optional listening field, validated only when it is there. */
+function isWatchingState(value: unknown): boolean {
+	const entry = asRecord(value);
+	return entry !== undefined && typeof entry.armed === "boolean" && typeof entry.wake === "boolean";
+}
+
 function isMessage(value: unknown): value is BusMessage {
 	const entry = asRecord(value);
 	if (!entry) return false;
@@ -136,8 +171,8 @@ async function dropIfEmpty(dir: string): Promise<void> {
 /** Create a store rooted at one repository's bus directory. */
 export function createBusStore(options: BusStoreOptions): BusStore {
 	const { dir } = options;
-	const sessionsDir = join(dir, "sessions");
-	const inboxRoot = join(dir, "inbox");
+	const sessionsDir = join(dir, SESSIONS_DIR_NAME);
+	const inboxRoot = join(dir, INBOX_DIR_NAME);
 	const claimsDir = join(dir, "claims");
 
 	const sessionFile = (id: string): string => join(sessionsDir, `${SHA(id)}.json`);
@@ -270,6 +305,8 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 
 		sessions: readSessions,
 
+		session: async (id) => readTyped(sessionFile(id), isSession),
+
 		async removeSession(id) {
 			await rm(sessionFile(id), { force: true });
 			await dropIfEmpty(inboxDir(id));
@@ -305,16 +342,27 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 			return released;
 		},
 
-		async prune({ now: at, activeIds, sessionTtlMs, messageTtlMs }) {
+		async prune({ now: at, activeIds, goneIds, sessionTtlMs, messageTtlMs }) {
+			// The caller's set can lag: a peer that joined and claimed since that read is
+			// live on disk, and its claims are its own. This read is the answer, so the
+			// set only adds to what it found rather than deciding who survives — except for
+			// a record whose process is gone, which the caller knows and the file cannot.
+			// That record keeps its row until the heartbeat ages out and owns nothing.
+			const live = new Set(activeIds);
+			const gone = new Set(goneIds ?? []);
 			for (const session of await readSessions()) {
 				if (at - session.lastSeen > sessionTtlMs) {
 					await rm(sessionFile(session.id), { force: true });
 					await dropIfEmpty(inboxDir(session.id));
-					activeIds = new Set([...activeIds].filter((id) => id !== session.id));
+					live.delete(session.id);
+				} else if (gone.has(session.id)) {
+					live.delete(session.id);
+				} else {
+					live.add(session.id);
 				}
 			}
 			for (const claim of await readClaims()) {
-				if (!activeIds.has(claim.owner)) await rm(claimFile(claim.path), { force: true });
+				if (!live.has(claim.owner)) await rm(claimFile(claim.path), { force: true });
 			}
 			for (const name of await readdir(inboxRoot).catch(() => [] as string[])) {
 				const directory = join(inboxRoot, name);

package/extensions/session-bus/tools.ts

@@ -2,10 +2,10 @@
  * The `session` tool.
  *
  * One action-shaped tool keeps the prompt surface small: status, send, inbox,
- * claim, release, join, leave, watch, name. The runtime owns file I/O and
- * lifecycle; this module only validates the action, calls the runtime, and hands
- * the result to the shared presentation module — one collapsed line, or the
- * board's rows on expand.
+ * claim, release, join. The runtime owns file I/O and lifecycle; this
+ * module only validates the action, calls the runtime, and hands the result to
+ * the shared presentation module — one collapsed line, or the board's rows on
+ * expand.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -14,16 +14,7 @@ import { Type, type Static } from "typebox";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { errorResult, textResult } from "../../lib/tool-result.ts";
 import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
-import {
-	formatClaim,
-	formatInbox,
-	formatJoin,
-	formatName,
-	formatRelease,
-	formatSend,
-	formatStatus,
-	formatWatch,
-} from "./format.ts";
+import { formatClaim, formatInbox, formatJoin, formatRelease, formatSend, formatStatus } from "./format.ts";
 import { normalizeAction, TOOL_NAME } from "./protocol.ts";
 import type { SessionBus } from "./runtime.ts";
 import { collapsedLine, resultSections, SessionResult } from "./result.ts";
@@ -32,8 +23,8 @@ import type { SessionDetails } from "./types.ts";
 export { TOOL_NAME };
 
 const SessionParams = Type.Object({
-	action: StringEnum(["status", "send", "inbox", "claim", "release", "join", "leave", "watch", "name"] as const, {
-		description: "status, send, inbox, claim, release, join, leave, watch, or name.",
+	action: StringEnum(["status", "send", "inbox", "claim", "release", "join"] as const, {
+		description: "status, send, inbox, claim, release, or join.",
 	}),
 	to: Type.Optional(Type.String({ description: "Target session label/id, or * for an event broadcast." })),
 	text: Type.Optional(Type.String({ description: "Message text, at most 4000 characters." })),
@@ -50,19 +41,16 @@ const SessionParams = Type.Object({
 	),
 	wake: Type.Optional(
 		Type.Boolean({
-			description:
-				"With watch: set the mode — true raises one turn per burst, false waits for the next turn, omitted keeps it.",
+			description: "With join: mail raises one turn per burst once the agent is idle; omitted waits for the next turn.",
 		}),
 	),
-	stop: Type.Optional(Type.Boolean({ description: "With watch: turn this session's inbox watch off." })),
-	team: Type.Optional(
-		Type.String({
-			description: "With join/leave: the split's name — the plan file name without `.md`.",
+	listen: Type.Optional(
+		Type.Boolean({
+			description: "With join: false joins without listening, so mail waits in the inbox until `inbox` reads it.",
 		}),
 	),
-	unit: Type.Optional(Type.String({ description: "With join/leave: the unit to claim or release, e.g. `core`." })),
 	label: Type.Optional(
-		Type.String({ description: "With name: what other sessions call this one, e.g. `billing-lead`." }),
+		Type.String({ description: "With join: what other sessions call this one, e.g. `billing-lead`." }),
 	),
 });
 
@@ -74,19 +62,14 @@ type SessionArgs = Static<typeof SessionParams>;
  * identity of the call.
  */
 function callSubject(action: string, args: Record<string, unknown>): string {
-	if (action === "name") {
+	if (action === "join") {
 		const label = typeof args.label === "string" ? args.label.trim() : "";
-		return label ? `name ${label}` : "name";
+		return label ? `join ${label}` : "join";
 	}
 	if (action === "send") {
 		const to = typeof args.to === "string" ? args.to : "";
 		return to ? `send ${to}` : "send";
 	}
-	if (action === "join" || action === "leave") {
-		const unit = typeof args.unit === "string" ? args.unit : "";
-		const team = typeof args.team === "string" ? args.team : "";
-		return [action, unit, team && !unit ? team : ""].filter(Boolean).join(" ");
-	}
 	if (action !== "claim" && action !== "release") return action;
 	const paths = Array.isArray(args.paths) ? args.paths.filter((path): path is string => typeof path === "string") : [];
 	const [first, ...rest] = paths;
@@ -99,16 +82,14 @@ export function registerTools(pi: ExtensionAPI, bus: SessionBus): void {
 		name: TOOL_NAME,
 		label: "Session bus",
 		description:
-			"Coordinate parallel Pi sessions on this repository. Actions: `status` (sessions, unread, claims, joined units), " +
+			"Coordinate parallel Pi sessions on this repository. Actions: `status` (sessions, unread, claims), " +
 			"`send` (to a label/id, or `*` for an event), `inbox` (consume messages), `claim`/`release` (paths), " +
-			"`join`/`leave` (a unit of an approved split, by `team` and `unit`), " +
-			"`watch` (report new mail at your next turn, or raise one with `wake`; `stop` turns it off). " +
-			"Delivery is pull-based unless this session arms `watch`.",
-		promptSnippet: "Coordinate parallel sessions: status, send, inbox, claim, release, join, leave, watch, name.",
+			"`join` (get on the bus under a label, and listen for mail unless `listen: false`; `wake` raises a turn). " +
+			"Delivery is pull-based unless this session joined and is listening.",
+		promptSnippet: "Coordinate parallel sessions: status, send, inbox, claim, release, join.",
 		promptGuidelines: [
-			"Check `session inbox` when starting or joining a coordinated turn.",
+			"Check `session inbox` when starting a coordinated turn.",
 			"Claim the paths you will edit before changing them; release them when done.",
-			"When a plan was approved with a split, `join` its unit once at the start of the work and `leave` it when merged.",
 			'Send `kind: "event"` for contract, build, or test changes another session needs.',
 			"Never put credentials or secrets in a session-bus message.",
 		],
@@ -161,38 +142,22 @@ export function registerTools(pi: ExtensionAPI, bus: SessionBus): void {
 						});
 					}
 					case "join": {
-						const result = await bus.join({ team: args.team, unit: args.unit });
-						return textResult(formatJoin(result.team, result.unit, result.claimed, result.conflicts), {
-							action,
-							team: result.team,
-							unit: result.unit,
-							claimed: result.claimed,
-							conflicts: result.conflicts,
+						const label = typeof args.label === "string" ? args.label.trim() : "";
+						const joined = await bus.join({
+							...(label === "" ? {} : { label }),
+							...(args.wake === undefined ? {} : { wake: args.wake }),
+							...(args.listen === undefined ? {} : { listen: args.listen }),
 						});
-					}
-					case "leave": {
-						const result = await bus.leave({ team: args.team, unit: args.unit });
-						return textResult(formatRelease(result.released, result.notOwned), {
+						// A label is the bus's name and Pi's session name in one act, so the footer,
+						// `/resume`, and the record a peer addresses agree. A bare join derives its
+						// label from the name Pi already shows and must not rename it back.
+						if (label !== "") pi.setSessionName(joined.label);
+						return textResult(formatJoin(joined.label, joined.watching), {
 							action,
-							released: result.released,
-							notOwned: result.notOwned,
-							...(args.team === undefined ? {} : { team: args.team }),
-							...(args.unit === undefined ? {} : { unit: args.unit }),
+							label: joined.label,
+							watching: joined.watching,
 						});
 					}
-					case "watch": {
-						const watching = await bus.watch({ wake: args.wake, stop: args.stop });
-						return textResult(formatWatch(watching), { action, watching });
-					}
-					case "name": {
-						const label = typeof args.label === "string" ? args.label.trim() : "";
-						if (!label) return errorResult(action, 'name requires a label, e.g. "billing-lead".');
-						const named = await bus.rename(label);
-						// The bus's label and Pi's session name are one identity: the footer,
-						// `/resume`, and the record a peer addresses have to agree.
-						pi.setSessionName(named);
-						return textResult(formatName(named), { action, label: named });
-					}
 				}
 			} catch (error) {
 				return errorResult(action, error instanceof Error ? error.message : String(error));

package/extensions/session-bus/tui.ts

@@ -17,7 +17,7 @@ import { type DetailContents, DockListScreen } from "../../lib/tui/dock-screen.t
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { keyValueRow } from "../../lib/tui/rows.ts";
 import { paint } from "../../lib/tui/tokens.ts";
-import { shortId } from "./format.ts";
+import { idSuffix } from "./format.ts";
 import {
 	type SessionRow,
 	claimRowLine,
@@ -48,7 +48,7 @@ const SCOPE_TITLE: Readonly<Record<BoardScope, string>> = {
 };
 
 const SCOPE_EMPTY: Readonly<Record<BoardScope, string>> = {
-	sessions: "No sessions on this bus.",
+	sessions: "No sessions on this bus yet. Press w to join and listen.",
 	inbox: "No unread mail.",
 	claims: "No claims.",
 };
@@ -76,7 +76,7 @@ function paneFacts(theme: Theme, row: SessionRow, now: number, width: number): s
 	const labelWidth = 10;
 	return [
 		keyValueRow(theme, width, { label: "mode", labelWidth, value: sanitizeLine(row.session.mode) }),
-		keyValueRow(theme, width, { label: "id", labelWidth, value: shortId(row.session.id) }),
+		keyValueRow(theme, width, { label: "id", labelWidth, value: idSuffix(row.session.id) }),
 		keyValueRow(theme, width, {
 			label: "last seen",
 			labelWidth,
@@ -96,7 +96,7 @@ function boardKey(board: BoardSnapshot | undefined): string {
 	return [
 		...board.status.sessions.map(
 			(session) =>
-				`${session.id}:${session.label}:${session.unread}:${session.lastSeen}:${session.mode}:${session.cwd}`,
+				`${session.id}:${session.label}:${session.unread}:${session.lastSeen}:${session.mode}:${session.cwd}:${session.state}`,
 		),
 		...board.status.claims.map((claim) => `${claim.path}:${claim.owner}:${claim.ownerLabel}:${claim.at}`),
 		board.status.watching ? `${board.status.watching.armed}:${board.status.watching.wake}` : "",
@@ -229,7 +229,7 @@ export class SessionListComponent extends DockListScreen<BoardRow> {
 		switch (this.scope) {
 			case "sessions": {
 				const sessions = rows.flatMap((row) => (row.kind === "session" ? [row.row] : []));
-				return summaryCells(this.theme, sessions, watching);
+				return summaryCells(this.theme, sessions, watching, this.board?.status.onBus !== false);
 			}
 			case "inbox": {
 				const cells = [paint(this.theme, "meta", count(rows.length, "unread message"))];

package/extensions/session-bus/types.ts

@@ -5,6 +5,7 @@
  * `store.ts` and the lifecycle in `runtime.ts`.
  */
 
+import type { RosterState } from "../../lib/session-roster.ts";
 import type { MessageKind, SessionMode } from "./protocol.ts";
 
 /** One registered Pi session. */
@@ -12,6 +13,14 @@ export interface SessionRecord {
 	id: string;
 	label: string;
 	pid: number;
+	/**
+	 * That process's start time, when the host can name one.
+	 *
+	 * It is what tells the record's process apart from an unrelated one that has since
+	 * been given the same pid, so `gone` does not have to wait for the heartbeat to age.
+	 * Absent on a platform without `ps`, and on a record written before this existed.
+	 */
+	startToken?: string;
 	/** Working directory of the session; the worktree root when there is one. */
 	cwd: string;
 	/** Repository root the session belongs to, for relative claims. */
@@ -20,6 +29,14 @@ export interface SessionRecord {
 	mode: SessionMode;
 	startedAt: number;
 	lastSeen: number;
+	/**
+	 * Whether this session is listening for mail, written when it joins.
+	 *
+	 * Absent means "not listening": a record written before this existed and a session
+	 * that stopped listening read the same way, which is the honest answer for a peer
+	 * deciding whether mail will reach it.
+	 */
+	watching?: { armed: boolean; wake: boolean };
 }
 
 /** One message waiting in a recipient's inbox. */
@@ -47,15 +64,10 @@ export interface ClaimRecord {
 /** What `session status` returns. */
 export interface SessionStatus {
 	me: { id: string; label: string };
-	sessions: Array<SessionRecord & { unread: number }>;
+	/** False while this session has only read the bus: it joins by naming itself. */
+	onBus: boolean;
+	sessions: Array<SessionRecord & { unread: number; state: RosterState }>;
 	claims: ClaimRecord[];
-	/** The newest split in this repository, and who holds each unit, on an explicit status call. */
-	units?: {
-		team: string;
-		joined: number;
-		total: number;
-		rows: Array<{ unit: string; lead?: boolean; holder?: string }>;
-	};
 	/** Present only when this session armed its inbox watch. */
 	watching?: { armed: boolean; wake: boolean };
 }
@@ -78,10 +90,7 @@ export interface BoardSnapshot {
 
 /** Structured result carried in the `session` tool's details. */
 export interface SessionDetails {
-	action: "status" | "send" | "inbox" | "claim" | "release" | "join" | "leave" | "watch" | "name";
-	/** With join/leave: the split and the unit, so a resumed transcript still says which. */
-	team?: string;
-	unit?: string;
+	action: "status" | "send" | "inbox" | "claim" | "release" | "join";
 	status?: SessionStatus;
 	delivered?: string[];
 	messageId?: string;
@@ -90,9 +99,9 @@ export interface SessionDetails {
 	conflicts?: ClaimConflict[];
 	released?: string[];
 	notOwned?: string[];
-	/** Whether the inbox watch is on, and whether it raises a turn. */
+	/** Whether the inbox watch is on, and whether it raises a turn; `join` reports it. */
 	watching?: { armed: boolean; wake: boolean };
-	/** With name: the label the bus settled on, which is what this session is called. */
+	/** With join: the label the bus settled on, which is what this session is called. */
 	label?: string;
 	error?: string;
 }

package/extensions/subagent/agents.ts

@@ -16,6 +16,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { READ_DOC_TOOL, WEB_FETCH_TOOL, WEB_SEARCH_TOOL } from "../../lib/tool-names.ts";
 
 /** Where an agent definition came from. */
 export type AgentSource = "builtin" | "user" | "project";
@@ -44,7 +45,7 @@ export const BUILTIN_AGENTS: readonly AgentConfig[] = [
 	{
 		name: "explorer",
 		description: "Fast codebase recon that returns compressed context for handoff to other agents",
-		tools: ["read", "grep", "find", "ls"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL],
 		source: "builtin",
 		systemPrompt: `You are an explorer. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
 
@@ -94,7 +95,7 @@ Which file to look at first and why.`,
 		name: "planner",
 		description:
 			"Delegated implementation planning in an isolated context (headless/chain; use plan mode for interactive planning)",
-		tools: ["read", "grep", "find", "ls"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL],
 		source: "builtin",
 		systemPrompt: `You are a delegated planning specialist working in an isolated context. The caller hands you planning when it wants a plan produced without adding exploration to its own transcript — for example an explorer → planner → worker chain, or a headless run.
 
@@ -134,7 +135,7 @@ Keep the plan concrete. The worker agent will execute it verbatim.`,
 	{
 		name: "reviewer",
 		description: "Code review specialist for quality and security analysis",
-		tools: ["read", "grep", "find", "ls", "bash"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a senior code reviewer. Analyze code for quality, security, and maintainability.
 
@@ -168,7 +169,7 @@ Be specific with file paths and line numbers.`,
 	{
 		name: "worker",
 		description: "General-purpose subagent with full capabilities and an isolated context window",
-		tools: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+		tools: ["read", "write", "edit", "bash", "grep", "find", "ls", READ_DOC_TOOL],
 		source: "builtin",
 		systemPrompt: `You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
 
@@ -192,7 +193,7 @@ If handing off to another agent (e.g. reviewer), include:
 	{
 		name: "researcher",
 		description: "Web research specialist that returns sourced findings on external questions",
-		tools: ["read", "grep", "find", "ls", "web_search", "web_fetch"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL, WEB_SEARCH_TOOL, WEB_FETCH_TOOL],
 		source: "builtin",
 		systemPrompt: `You are a research specialist. You investigate questions using web_search and web_fetch, then return findings another agent can act on.
 
@@ -228,7 +229,7 @@ What the caller should do with this, in 2-3 sentences.`,
 	{
 		name: "tester",
 		description: "Writes or updates tests for a change and runs them",
-		tools: ["read", "write", "edit", "grep", "find", "ls", "bash"],
+		tools: ["read", "write", "edit", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a test engineer. You add or update tests for a change and run them.
 
@@ -260,7 +261,7 @@ What is still untested and why.`,
 	{
 		name: "debugger",
 		description: "Root-cause analysis for a failing test or bug, read-only plus running tests",
-		tools: ["read", "grep", "find", "ls", "bash"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a debugging specialist. You find the root cause of a failure from evidence, not guesses.
 
@@ -295,7 +296,7 @@ What else the bug or the fix could affect.`,
 	{
 		name: "documenter",
 		description: "Updates docs, READMEs, and changelog entries to match the code",
-		tools: ["read", "write", "edit", "grep", "find", "ls", "bash"],
+		tools: ["read", "write", "edit", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a documentation specialist. You keep docs accurate and consistent with the code.
 

package/extensions/subagent/commands.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { planModeRefusal } from "../../lib/plan-entry.ts";
 import { isPlanModeEnabled } from "../../lib/plan-state.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import type { BackgroundRuntime } from "./background.ts";
@@ -20,7 +21,7 @@ async function openAgents(
 	ctx: ExtensionCommandContext,
 ): Promise<void> {
 	if (isPlanModeEnabled(ctx.sessionManager.getBranch())) {
-		ctx.ui.notify("Plan mode is read-only. Approve the plan before managing background runs.", "warning");
+		ctx.ui.notify(planModeRefusal("managing background runs"), "warning");
 		return;
 	}
 

package/extensions/subagent/invocation.ts

@@ -6,13 +6,15 @@
  * import for invocation concerns.
  */
 
+import { WORKSPACE_READERS } from "../../lib/policy.ts";
+import { WEB_FETCH_TOOL, WEB_SEARCH_TOOL } from "../../lib/tool-names.ts";
 import type { AgentConfig } from "./agents.ts";
 import type { DispatchDefaults } from "./types.ts";
 
 export { getPiInvocation, type PiInvocation } from "../../lib/pi-invocation.ts";
 
-/** Tools a read-only delegation may use: structured readers and web readers only. */
-export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "web_search", "web_fetch"] as const;
+/** Tools a read-only delegation may use: structured readers, documents, and web readers only. */
+export const READ_ONLY_TOOLS = [...WORKSPACE_READERS, WEB_SEARCH_TOOL, WEB_FETCH_TOOL] as const;
 
 /** Appended to a read-only agent's system prompt; the `--tools` list is the real gate. */
 export const READ_ONLY_NOTE =