@narumitw/pi-subagents 0.26.0 → 0.27.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-subagents)](https://www.npmjs.com/package/@narumitw/pi-subagents) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. The batch `subagent` tool keeps isolated Pi subprocesses, while addressable lifecycle tools can run reusable agents either as subprocess-backed logical sessions or as public-SDK in-process child sessions.
+`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. The blocking batch `subagent` tool keeps isolated Pi subprocesses, while four detached tools run reusable agents either as subprocess-backed logical sessions or as public-SDK in-process child sessions. Together they form a fixed five-tool surface.
 
 Use it to split independent research, planning, implementation, and review work across focused workers. Under the default next-turn delivery policy, background delegation is for work the current response does not depend on. Opt-in auto-resume also supports final-answer-dependent background work by requesting a synthesis turn after completion.
 
@@ -19,7 +19,7 @@ Use it to split independent research, planning, implementation, and review work
 - Supports per-task `cwd`, hard subprocess `timeoutMs`, task-selected `thinkingLevel`, abort propagation, and streaming progress.
 - Bounds JSON lines, captured messages, stderr, final output, chain substitution, and fan-in context.
 - Enforces a recursion-depth guard and deterministic process-group termination.
-- Provides addressable stateful agents with follow-up, mailbox, list, interrupt, close, context selection, and persistence.
+- Provides addressable stateful agents with follow-up, consolidated mailbox/management actions, context selection, and persistence.
 - Publishes transient runtime status through Pi's generic extension status API while subagents are running.
 - Returns complete bounded worker output in tool details and a concise result for the main agent.
 
@@ -211,7 +211,7 @@ Run a chain where each step receives the previous output:
 
 Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects a bounded `pi-subagent-completion` custom message. Completions that settle in the same dispatch window are batched, and the broker allows at most one in-flight root wake until that parent turn starts.
 
-Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result; if it does, use blocking `subagent`. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_list` or `subagent_messages`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
+Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result; if it does, use blocking `subagent`. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_manage` with `action: "list"` or `subagent_mailbox` with `action: "read"`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
 
 A detached agent additionally needs a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
 
@@ -246,20 +246,49 @@ The direct routes remain predictable: `/subagents settings` changes user complet
 }
 ```
 
-The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. Set `"enabled": false` to remove all stateful lifecycle tools. Otherwise, the extension registers:
+The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. Set `"enabled": false` to remove all four stateful tools. Otherwise, the extension keeps the following tool membership fixed across spawn, completion, interrupt, close, and mailbox transitions. This avoids lifecycle-driven tool-schema churn and preserves a stable provider prompt prefix for KV caching.
 
 | Tool | Purpose |
 | --- | --- |
 | `subagent_spawn` | Start detached work with an optional task-selected thinking level, return an opaque `agentId` immediately, and deliver completion asynchronously. |
-| `subagent_send` | Send follow-up work to a reusable agent; shared-workspace write conflicts are guarded unless explicitly overridden. |
-| `subagent_message` | Queue a bounded mailbox message without starting a turn; sender IDs must be `root` or an agent in the same tree. |
-| `subagent_messages` | Read and optionally acknowledge unread mailbox messages. |
-| `subagent_list` | List retained agents and lifecycle states. |
-| `subagent_interrupt` | Abort the current turn while retaining its identity and history. |
-| `subagent_close` | Abort if necessary, close the agent, and remove it from retained persistence. |
+| `subagent_send` | Send follow-up work and trigger a new turn on a reusable agent; shared-workspace write conflicts are guarded unless explicitly overridden. |
+| `subagent_manage` | Use `action: "list"` to inspect agents, `"interrupt"` to retain an agent after aborting active work, or `"close"` to release it; interrupt/close accept optional `subtree`. |
+| `subagent_mailbox` | Use `action: "send"` for queue-only messages that do not start a turn, or `"read"` to read and optionally acknowledge unread messages. |
+
+The action schemas are flat for provider compatibility and reject parameters that belong to another action. For example:
+
+```json
+{
+  "action": "interrupt",
+  "agentId": "sa_example",
+  "subtree": true
+}
+```
+
+```json
+{
+  "action": "send",
+  "agentId": "sa_example",
+  "message": "Check the API compatibility note before finishing."
+}
+```
 
 Use the **Current-session agents** action in `/subagents` to inspect the indented agent tree, lifecycle state, unread count, and available actions, or to confirm clearing retained agents. `/subagents:agents list|clear` remains the compatibility command for the same current-session operations. Active turns are FIFO-limited by `maxActiveTurns`; excess retained work remains in `starting` state until a slot is available. `maxAgents` separately bounds running, queued, and idle records. `parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
 
+### Migrating from the seven-tool lifecycle surface
+
+The five replaced names are intentionally not registered as aliases. Update explicit prompts and integrations as follows:
+
+| Previous call | Fixed-surface call |
+| --- | --- |
+| `subagent_list({ includeClosed })` | `subagent_manage({ action: "list", includeClosed })` |
+| `subagent_interrupt({ agentId, subtree })` | `subagent_manage({ action: "interrupt", agentId, subtree })` |
+| `subagent_close({ agentId, subtree })` | `subagent_manage({ action: "close", agentId, subtree })` |
+| `subagent_message({ agentId, message, ... })` | `subagent_mailbox({ action: "send", agentId, message, ... })` |
+| `subagent_messages({ agentId, acknowledge, limit })` | `subagent_mailbox({ action: "read", agentId, acknowledge, limit })` |
+
+Persisted agent and mailbox records require no migration. If an explicit prompt in a resumed conversation keeps requesting an old name, update it with the mapping above or start a fresh conversation. To roll back after an upgrade, pin the package version used before the upgrade; for this migration, use `pi install npm:@narumitw/pi-subagents@0.26.0`. The previous release can read the same state directory.
+
 A spawn can request a thinking level explicitly:
 
 ```json
@@ -462,8 +491,10 @@ Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-su
 ```txt
 extensions/pi-subagents/
 ├── src/
-│   ├── subagents.ts  # Pi entrypoint and tool schema
-│   └── *.ts          # Package-local discovery, execution, rendering, and config modules
+│   ├── subagents.ts              # Pi entrypoint and blocking tool schema
+│   ├── stateful.ts               # Detached lifecycle registration and dispatch
+│   ├── stateful-tool-params.ts   # Consolidated action schemas and validation
+│   └── *.ts                      # Package-local discovery, execution, rendering, and config modules
 ├── README.md
 ├── LICENSE
 ├── tsconfig.json

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.26.0",
+	"version": "0.27.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/stateful-tool-params.ts

@@ -0,0 +1,202 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+const MANAGE_ACTIONS = ["list", "interrupt", "close"] as const;
+const MAILBOX_ACTIONS = ["send", "read"] as const;
+const MAX_MAILBOX_MESSAGE_LENGTH = 16 * 1024;
+
+export const ManageParamsSchema = Type.Object(
+	{
+		action: StringEnum(MANAGE_ACTIONS, {
+			description:
+				"Use list to inspect agents, interrupt to stop active work, or close to release agents.",
+		}),
+		agentId: Type.Optional(
+			Type.String({ minLength: 1, description: "Required for interrupt and close." }),
+		),
+		includeClosed: Type.Optional(
+			Type.Boolean({
+				default: false,
+				description: "List closed records as well as retained agents.",
+			}),
+		),
+		subtree: Type.Optional(
+			Type.Boolean({
+				default: false,
+				description: "Interrupt or close the target and all descendants child-first.",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export const MailboxParamsSchema = Type.Object(
+	{
+		action: StringEnum(MAILBOX_ACTIONS, {
+			description: "Use send for queue-only delivery or read to inspect unread mailbox messages.",
+		}),
+		agentId: Type.String({ minLength: 1, description: "Mailbox owner or message recipient." }),
+		message: Type.Optional(
+			Type.String({
+				minLength: 1,
+				maxLength: MAX_MAILBOX_MESSAGE_LENGTH,
+				description: "Message content required by send; sending does not start a turn.",
+			}),
+		),
+		senderId: Type.Optional(Type.String({ description: "Optional same-tree sender identity." })),
+		deduplicationKey: Type.Optional(
+			Type.String({ maxLength: 256, description: "Optional idempotency key for send." }),
+		),
+		acknowledge: Type.Optional(
+			Type.Boolean({ default: true, description: "Mark returned read messages as acknowledged." }),
+		),
+		limit: Type.Optional(
+			Type.Number({ minimum: 1, maximum: 20, default: 20, description: "Maximum messages." }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export type ValidatedManageParams =
+	| { action: "list"; includeClosed?: boolean }
+	| { action: "interrupt" | "close"; agentId: string; subtree?: boolean };
+
+export type ValidatedMailboxParams =
+	| {
+			action: "send";
+			agentId: string;
+			message: string;
+			senderId?: string;
+			deduplicationKey?: string;
+	  }
+	| { action: "read"; agentId: string; acknowledge?: boolean; limit?: number };
+
+export function validateManageParams(params: unknown): ValidatedManageParams {
+	const values = parameterRecord(params, "subagent_manage");
+	const action = values.action;
+	if (
+		typeof action !== "string" ||
+		!MANAGE_ACTIONS.includes(action as (typeof MANAGE_ACTIONS)[number])
+	) {
+		throw new Error(`subagent_manage action must be one of: ${MANAGE_ACTIONS.join(", ")}`);
+	}
+	if (action === "list") {
+		assertOnlyActionKeys("subagent_manage", action, values, ["action", "includeClosed"]);
+		assertOptionalBoolean("subagent_manage", action, values, "includeClosed");
+		return values as ValidatedManageParams;
+	}
+	assertOnlyActionKeys("subagent_manage", action, values, ["action", "agentId", "subtree"]);
+	assertRequiredString("subagent_manage", action, values, "agentId");
+	assertOptionalBoolean("subagent_manage", action, values, "subtree");
+	return values as ValidatedManageParams;
+}
+
+export function validateMailboxParams(params: unknown): ValidatedMailboxParams {
+	const values = parameterRecord(params, "subagent_mailbox");
+	const action = values.action;
+	if (
+		typeof action !== "string" ||
+		!MAILBOX_ACTIONS.includes(action as (typeof MAILBOX_ACTIONS)[number])
+	) {
+		throw new Error(`subagent_mailbox action must be one of: ${MAILBOX_ACTIONS.join(", ")}`);
+	}
+	if (action === "send") {
+		assertOnlyActionKeys("subagent_mailbox", action, values, [
+			"action",
+			"agentId",
+			"message",
+			"senderId",
+			"deduplicationKey",
+		]);
+		assertRequiredString("subagent_mailbox", action, values, "agentId");
+		assertRequiredString("subagent_mailbox", action, values, "message");
+		const message = values.message as string;
+		if (message.length > MAX_MAILBOX_MESSAGE_LENGTH) {
+			throw new Error(
+				`subagent_mailbox action "send" requires message at most ${MAX_MAILBOX_MESSAGE_LENGTH} characters`,
+			);
+		}
+		assertOptionalString("subagent_mailbox", action, values, "senderId");
+		assertOptionalString("subagent_mailbox", action, values, "deduplicationKey");
+		if (typeof values.deduplicationKey === "string" && values.deduplicationKey.length > 256) {
+			throw new Error(
+				'subagent_mailbox action "send" requires deduplicationKey at most 256 characters',
+			);
+		}
+		return values as ValidatedMailboxParams;
+	}
+	assertOnlyActionKeys("subagent_mailbox", action, values, [
+		"action",
+		"agentId",
+		"acknowledge",
+		"limit",
+	]);
+	assertRequiredString("subagent_mailbox", action, values, "agentId");
+	assertOptionalBoolean("subagent_mailbox", action, values, "acknowledge");
+	if (
+		values.limit !== undefined &&
+		(typeof values.limit !== "number" ||
+			!Number.isFinite(values.limit) ||
+			values.limit < 1 ||
+			values.limit > 20)
+	) {
+		throw new Error('subagent_mailbox action "read" requires limit between 1 and 20');
+	}
+	return values as ValidatedMailboxParams;
+}
+
+function parameterRecord(params: unknown, toolName: string): Record<string, unknown> {
+	if (!params || typeof params !== "object" || Array.isArray(params)) {
+		throw new Error(`${toolName} parameters must be an object`);
+	}
+	return params as Record<string, unknown>;
+}
+
+function assertOnlyActionKeys(
+	toolName: string,
+	action: string,
+	values: Record<string, unknown>,
+	allowed: readonly string[],
+): void {
+	const unexpected = Object.keys(values).find(
+		(key) => values[key] !== undefined && !allowed.includes(key),
+	);
+	if (unexpected) {
+		throw new Error(`${toolName} action "${action}" does not accept ${unexpected}`);
+	}
+}
+
+function assertRequiredString(
+	toolName: string,
+	action: string,
+	values: Record<string, unknown>,
+	key: string,
+): void {
+	const value = values[key];
+	if (value === undefined) throw new Error(`${toolName} action "${action}" requires ${key}`);
+	if (typeof value !== "string" || value.length === 0) {
+		throw new Error(`${toolName} action "${action}" requires ${key} to be a non-empty string`);
+	}
+}
+
+function assertOptionalString(
+	toolName: string,
+	action: string,
+	values: Record<string, unknown>,
+	key: string,
+): void {
+	if (values[key] !== undefined && typeof values[key] !== "string") {
+		throw new Error(`${toolName} action "${action}" requires ${key} to be a string`);
+	}
+}
+
+function assertOptionalBoolean(
+	toolName: string,
+	action: string,
+	values: Record<string, unknown>,
+	key: string,
+): void {
+	if (values[key] !== undefined && typeof values[key] !== "boolean") {
+		throw new Error(`${toolName} action "${action}" requires ${key} to be a boolean`);
+	}
+}

package/src/stateful.ts

@@ -25,6 +25,12 @@ import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import { AgentPersistence } from "./persistence.js";
 import { AgentRegistry, type AgentTurnCompletion, type ManagedAgent } from "./registry.js";
 import { readSubagentSettings } from "./settings.js";
+import {
+	MailboxParamsSchema,
+	ManageParamsSchema,
+	validateMailboxParams,
+	validateManageParams,
+} from "./stateful-tool-params.js";
 import { SubprocessTransport } from "./subprocess-transport.js";
 import { WorkspaceManager } from "./workspace.js";
 
@@ -64,8 +70,8 @@ function createSpawnPromptGuidelines(completionDelivery: CompletionDelivery): st
 		"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
 		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
 		noLocalWorkGuidance,
-		"Consume and synthesize available subagent_spawn completion messages; interrupt or close agents that are no longer needed.",
-		"subagent_spawn completion is delivered automatically. Do not poll with subagent_list or subagent_messages, repeatedly check progress, or duplicate the delegated work.",
+		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
+		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_manage action "list" or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
 	];
 }
 
@@ -91,6 +97,11 @@ export interface StatefulSubagentController {
 	clearAgents(): Promise<number>;
 }
 
+interface StatefulActionToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: Record<string, unknown>;
+}
+
 export function registerStatefulSubagents(
 	pi: ExtensionAPI,
 	dependencies: StatefulSubagentDependencies = {},
@@ -157,6 +168,11 @@ export function registerStatefulSubagents(
 		if (!registry) throw new Error("Stateful subagents are not initialized for this session");
 		return registry;
 	};
+	const requireAgent = (agentId: string) => {
+		const agent = requireRegistry().get(agentId);
+		if (!agent) throw new Error(`Unknown subagent: ${agentId}`);
+		return agent;
+	};
 
 	pi.on("session_start", async (_event, ctx) => {
 		const generation = ++runtimeGeneration;
@@ -374,7 +390,9 @@ export function registerStatefulSubagents(
 	pi.registerTool({
 		name: "subagent_send",
 		label: "Send Subagent Follow-up",
-		description: "Send a follow-up task to an idle, completed, interrupted, or failed subagent.",
+		description:
+			"Send follow-up work to an idle, completed, interrupted, or failed subagent and start a new turn. Use subagent_mailbox for queue-only messages.",
+		promptSnippet: "Start a new detached follow-up turn on a retained subagent",
 		parameters: Type.Object({
 			agentId: Type.String(),
 			task: Type.String({ minLength: 1, maxLength: DEFAULT_MAX_CONTEXT_BYTES }),
@@ -404,141 +422,66 @@ export function registerStatefulSubagents(
 	});
 
 	pi.registerTool({
-		name: "subagent_message",
-		label: "Message Subagent",
-		description: "Queue a bounded mailbox message without starting a turn.",
-		parameters: Type.Object({
-			agentId: Type.String(),
-			message: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
-			senderId: Type.Optional(Type.String()),
-			deduplicationKey: Type.Optional(Type.String({ maxLength: 256 })),
-		}),
-		async execute(_id, params) {
-			const message = await requireRegistry().sendMessage(
-				params.agentId,
-				params.message,
-				params.senderId,
-				params.deduplicationKey,
-			);
-			return {
-				content: [{ type: "text", text: `Queued ${message.id} for ${message.recipientId}.` }],
-				details: { message },
-			};
-		},
-	});
-
-	pi.registerTool({
-		name: "subagent_messages",
-		label: "Read Subagent Messages",
-		description: "Read unread mailbox messages and optionally acknowledge them.",
-		parameters: Type.Object({
-			agentId: Type.String(),
-			acknowledge: Type.Optional(Type.Boolean({ default: true })),
-			limit: Type.Optional(Type.Number({ minimum: 1, maximum: 20, default: 20 })),
-		}),
-		async execute(_id, params) {
-			const messages = await requireRegistry().readMessages(
-				params.agentId,
-				params.acknowledge,
-				params.limit,
-			);
-			const summaries = messages.map((message) => ({
-				...message,
-				content: truncateUtf8(message.content, MAX_TOOL_MESSAGE_BYTES).text,
-			}));
-			const text = summaries.length
-				? summaries
-						.map((message) => `${message.id} from ${message.senderId}: ${message.content}`)
-						.join("\n")
-				: "No unread messages.";
-			return {
-				content: [{ type: "text", text: truncateUtf8(text, DEFAULT_MAX_CONTEXT_BYTES).text }],
-				details: { messages: summaries },
-			};
-		},
-	});
-
-	pi.registerTool({
-		name: "subagent_list",
-		label: "List Subagents",
-		description: "List stateful subagents and lifecycle states.",
-		parameters: Type.Object({ includeClosed: Type.Optional(Type.Boolean({ default: false })) }),
-		async execute(_id, params) {
-			const agents = requireRegistry().list(params.includeClosed);
-			return {
-				content: [
-					{
-						type: "text",
-						text: agents.length ? agents.map(formatLine).join("\n") : "No stateful subagents.",
-					},
-				],
-				details: { agents: agents.map(summarizeAgent) },
-			};
-		},
-	});
-
-	pi.registerTool({
-		name: "subagent_interrupt",
-		label: "Interrupt Subagent",
-		description: "Interrupt the current turn while retaining the subagent for follow-up work.",
-		parameters: Type.Object({
-			agentId: Type.String(),
-			subtree: Type.Optional(Type.Boolean({ default: false })),
-		}),
-		async execute(_id, params) {
-			if (params.subtree) {
-				const agents = await requireRegistry().interruptTree(params.agentId);
-				const root = requireRegistry().get(params.agentId);
-				if (!root) throw new Error(`Unknown subagent: ${params.agentId}`);
+		name: "subagent_manage",
+		label: "Manage Subagents",
+		description:
+			"List retained subagents, interrupt active work while keeping an agent reusable, or close agents and release their resources.",
+		promptSnippet: "List or control retained detached subagents",
+		parameters: ManageParamsSchema,
+		async execute(_id, params): Promise<StatefulActionToolResult> {
+			const operation = validateManageParams(params);
+			if (operation.action === "list") {
+				const agents = requireRegistry().list(operation.includeClosed);
 				return {
-					content: [{ type: "text", text: `Interrupted ${agents.length} active agent(s).` }],
-					details: {
-						agent: summarizeAgent(root),
-						agents: agents.map(summarizeAgent),
-					},
+					content: [
+						{
+							type: "text",
+							text: agents.length ? agents.map(formatLine).join("\n") : "No stateful subagents.",
+						},
+					],
+					details: { agents: agents.map(summarizeAgent) },
 				};
 			}
-			const agent = await requireRegistry().interrupt(params.agentId);
-			return result(agent, `Interrupted ${agent.id}; it remains reusable.`);
-		},
-	});
-
-	pi.registerTool({
-		name: "subagent_close",
-		label: "Close Subagent",
-		description: "Close a stateful subagent and remove it from retained persistence.",
-		parameters: Type.Object({
-			agentId: Type.String(),
-			subtree: Type.Optional(Type.Boolean({ default: false })),
-		}),
-		async execute(_id, params) {
-			const existing = requireRegistry().get(params.agentId);
-			if (existing?.state === "closed" && !params.subtree) {
+			const agentId = operation.agentId;
+			if (operation.action === "interrupt") {
+				if (operation.subtree) {
+					const agents = await requireRegistry().interruptTree(agentId);
+					return {
+						content: [{ type: "text", text: `Interrupted ${agents.length} active agent(s).` }],
+						details: {
+							agent: summarizeAgent(requireAgent(agentId)),
+							agents: agents.map(summarizeAgent),
+						},
+					};
+				}
+				const agent = await requireRegistry().interrupt(agentId);
+				return result(agent, `Interrupted ${agent.id}; it remains reusable.`);
+			}
+			const existing = requireRegistry().get(agentId);
+			if (existing?.state === "closed" && !operation.subtree) {
 				const pendingOwner = isolatedAgents.get(existing.id);
 				if (pendingOwner) await workspaceManager.cleanup(pendingOwner);
 				isolatedAgents.delete(existing.id);
 				return result(existing, `Closed ${existing.id}.`);
 			}
-			if (params.subtree) {
+			if (operation.subtree) {
 				let agents: ManagedAgent[];
 				try {
-					agents = await requireRegistry().closeTree(params.agentId);
+					agents = await requireRegistry().closeTree(agentId);
 				} finally {
 					await cleanupClosedWorkspaces(requireRegistry(), isolatedAgents, workspaceManager);
 				}
-				const root = requireRegistry().get(params.agentId);
-				if (!root) throw new Error(`Unknown subagent: ${params.agentId}`);
 				return {
 					content: [{ type: "text", text: `Closed ${agents.length} agent(s).` }],
 					details: {
-						agent: summarizeAgent(root),
+						agent: summarizeAgent(requireAgent(agentId)),
 						agents: agents.map(summarizeAgent),
 					},
 				};
 			}
 			let agent: ManagedAgent;
 			try {
-				agent = await requireRegistry().close(params.agentId);
+				agent = await requireRegistry().close(agentId);
 			} finally {
 				await cleanupClosedWorkspaces(requireRegistry(), isolatedAgents, workspaceManager);
 			}
@@ -546,6 +489,48 @@ export function registerStatefulSubagents(
 		},
 	});
 
+	pi.registerTool({
+		name: "subagent_mailbox",
+		label: "Subagent Mailbox",
+		description:
+			"Queue a bounded message without starting a turn, or read unread mailbox messages and optionally acknowledge them.",
+		promptSnippet: "Send or read queue-only detached-subagent mailbox messages",
+		parameters: MailboxParamsSchema,
+		async execute(_id, params): Promise<StatefulActionToolResult> {
+			const operation = validateMailboxParams(params);
+			if (operation.action === "send") {
+				const message = await requireRegistry().sendMessage(
+					operation.agentId,
+					operation.message,
+					operation.senderId,
+					operation.deduplicationKey,
+				);
+				return {
+					content: [{ type: "text", text: `Queued ${message.id} for ${message.recipientId}.` }],
+					details: { message },
+				};
+			}
+			const messages = await requireRegistry().readMessages(
+				operation.agentId,
+				operation.acknowledge,
+				operation.limit,
+			);
+			const summaries = messages.map((message) => ({
+				...message,
+				content: truncateUtf8(message.content, MAX_TOOL_MESSAGE_BYTES).text,
+			}));
+			const text = summaries.length
+				? summaries
+						.map((message) => `${message.id} from ${message.senderId}: ${message.content}`)
+						.join("\n")
+				: "No unread messages.";
+			return {
+				content: [{ type: "text", text: truncateUtf8(text, DEFAULT_MAX_CONTEXT_BYTES).text }],
+				details: { messages: summaries },
+			};
+		},
+	});
+
 	pi.registerCommand("subagents:agents", {
 		description: "Inspect or clear current-session subagents",
 		getArgumentCompletions(prefix: string) {