@narumitw/pi-subagents 3.0.1 → 3.1.0

package/docs/attachments.md

@@ -0,0 +1,37 @@
+# Pi Subagents attachment behavior
+
+`subagent_spawn` accepts explicit local `skills` and `extensions` for one child job. Automatic resource discovery and inheritance from the parent session remain disabled. See [Tools](./tools.md) for argument shapes and [Security and privacy](../README.md#-security-and-privacy) before attaching executable code.
+
+## Skills
+
+Each `skills` path must be an existing local Markdown file or directory with at least one skill Pi can load. Skill names must be unique across explicit paths and skills contributed by attached extension packages. Repeated canonical skill paths are removed in first-use order.
+
+Every non-ignored declared skill must load successfully, including skills contributed by an attached extension package: an invalid or unreadable sibling cannot be hidden by a valid one. Pi-ignored draft skills remain excluded. Non-Markdown file paths, directories without a loadable skill, and duplicate skill names fail before launch.
+
+Skills use Pi's progressive disclosure. Attaching one does not inject its complete body, add work tools, or force the child to invoke it.
+
+Skill preflight is asynchronous and cancellation-aware. It rejects recursive directory links and combined explicit and package-skill scans exceeding 4,096 entries, depth 32, 4 MiB of candidate skill content, or 1 MiB of ignore-file content before Pi's synchronous loader runs.
+
+## Extensions
+
+Each `extensions` entry specifies an existing local extension file or directory and the exact extension tools to select initially. An empty `tools` list permits provider or lifecycle behavior without initially exposing extension tools. Tool names cannot overlap Pi core or the built-in `subagent_send` and `subagent_wait` tools; different attachments cannot request the same extension tool name.
+
+An extension directory must resolve to at least one loadable Pi entrypoint. Every exact `pi.extensions` declaration must contribute a directly loadable entrypoint. Partially resolved packages and authoritative Pi manifests without extensions are rejected before launch.
+
+Extension-package preflight is asynchronous and cancellation-aware. It rejects source globs in Pi resource declarations, recursive resource-directory links, and non-regular manifests or ignore files; its shared discovery budget is 4,096 entries, depth 32, and 1 MiB of metadata.
+
+When an extension is attached, a readiness probe reports source fingerprints for the requested active tools through a private descriptor after extension factory, session, and resource-discovery hooks. The parent matches each requested tool to the specified attachment's resolved entrypoints and observes startup-hook errors through an ordered RPC barrier before sending the task to the model. A missing or misattributed tool, invalid readiness response, startup failure, or cancellation fails the job before a model request. For untrusted projects, the parent also checks Pi's loaded skill and prompt command paths after resource discovery and before sending the task; project-local paths and symlinks into the project fail the job. Headless RPC does not expose themes to the child model.
+
+An attached extension executes trusted code with the child process's user permissions and can alter prompts, providers, tools, or the active tool list after that initial check. The selected tool list is not a sandbox.
+
+## Paths, limits, and providers
+
+Attachment paths may be absolute or relative to the child working directory. They must already refer to regular files or directories and are canonicalized before launch. npm, Git, URL, and other nonlocal sources are not accepted. Repeated extension paths merge their selected tools in first-use order.
+
+A job accepts at most 16 skill paths, 16 extension entries, and 64 selected core and extension tool names. Each path is limited to 4 KiB of UTF-8 text; each extension tool name is limited to 128 characters without commas or control characters. The serialized child bootstrap, including selected and communication tool names, must fit 16 KiB of UTF-8 JSON. On Windows, the child command line must fit the 32,767 UTF-16 code-unit process limit.
+
+When the project is untrusted, both lexical and symlink-resolved paths inside the child working directory are rejected for attachments and resources resolved from their extension packages. Explicit external paths remain available. Only attach code you trust: attachments are not permission boundaries.
+
+The child inherits the main agent's effective provider and model. Unavailable core tools, invalid attachments, or an unavailable session broker also fail before launch. Without an attached extension, a provider registered only in the parent by an extension is unavailable to the child and spawn rejects it. When an extension is attached, the child may register that provider during startup; startup fails if it does not. Process-local runtime API keys, including a parent-only `--api-key`, cannot be forwarded. Attached providers must use stored credentials or inherited environment credentials the child can read independently.
+
+Canonical attachment paths are passed to Pi as child-process arguments. Parent-generated inspection, completion, and broker metadata omit them; child diagnostic errors redact requested attachment roots before publication. Attached code and model output can still disclose accessible paths.

package/docs/design-principles.md

@@ -12,9 +12,15 @@ That isolation is not a limitation—it is the point.
 
 Fresh does not mean empty.
 
-The subagent still receives Pi's standard system prompt, the main agent's effective model, applicable project context, its selected tools, and one explicit task.
+The subagent still receives Pi's standard system prompt, the main agent's effective model, applicable project context, its selected tools, explicit per-job attachments, and one task.
 
-The task defines the child's specialization, while the selected tools define its authority.
+The task defines the child's specialization, while selected tools and trusted attachments define its authority.
+
+Skills add progressively disclosed instructions without automatically adding tools or injecting their complete bodies.
+
+Extensions add fully privileged executable code and may change prompts, providers, tools, or lifecycle behavior, so their initial tool lists are least-privilege loadout declarations rather than a sandbox.
+
+Load only explicit local attachments, require project trust for project-local code, and never infer or inherit parent resources automatically.
 
 Give each subagent a self-contained task containing only the context needed to complete that task.
 

package/docs/messaging.md

@@ -0,0 +1,23 @@
+# Pi Subagents messaging and lifecycle
+
+Main and child processes have separate `subagent_send` definitions. The main agent starts a request with an active job ID as `recipient` and answers a child request with its `requestId`. A child omits `requestId` to ask the main agent a question and provides it to answer a pending main-agent request. See [Tools](./tools.md) for the parameter schemas.
+
+## Delivery and waiting
+
+A main-originated request to a queued job waits for the child RPC prompt to be accepted, then uses Pi steering to reach the running child. After RPC accepts steering, the runtime interrupts active child response waits without consuming their original requests. The child may retry `subagent_wait` for a response it still needs.
+
+Caller cancellation before RPC delivery starts rolls the request back. Once delivery starts, cancellation stops only the caller's wait: the request may still arrive and remains answerable until delivery fails or the job terminates. A wait timeout likewise stops only that wait, not the job or the underlying message request.
+
+A child response arrives asynchronously in the main session and interrupts the next active main-agent `subagent_wait`, including when the response arrived immediately before the wait started. The first accepted response wins; repeated responses acknowledge the existing response without replacing it.
+
+Each job may have up to four unresolved or answered-but-not-consumed requests across both directions. Requests and responses are limited to 48 KiB and 1,992 lines so their envelopes fit Pi's model-text bounds. Terminal jobs, unknown requests, cross-job responses, responses from the request originator, and stale session credentials throw. Successful sends and responses return `{ requestId, accepted, duplicate }`.
+
+## Job lifecycle
+
+A job starts `queued`, becomes `running`, and reaches exactly one terminal state: `completed`, `partial`, `failed`, `timed_out`, or `cancelled`. Job execution timeouts start after Pi accepts the RPC prompt. The runtime retains up to 32 recent terminal records for up to 24 hours in the current extension session; inspection reports removed records through `omitted.jobs`.
+
+Cancelling or terminalizing a job revokes its communication token and rejects pending child waits before stale output can replace the terminal state. Session replacement and shutdown cancel active work, suppress stale completion delivery, revoke credentials, close sockets, and stop the broker. An asynchronous job completion does not wake an otherwise idle main-agent model turn.
+
+The session starts one loopback TCP broker on `127.0.0.1` with an ephemeral port. Each job receives a random token bound to its job identity and session generation. The parent passes credentials through a private inherited pipe rather than the child's initial environment or command line. Child broker calls use request-scoped connections; response waits use abortable long polling.
+
+For authorization boundaries and credential exposure, see [Security and privacy](../README.md#-security-and-privacy).

package/docs/tools.md

@@ -5,29 +5,21 @@
 | Parameter | Type | Required | Constraint / default |
 | --- | --- | --- | --- |
 | `task` | `string` | Yes | Self-contained task, up to 50 KiB of UTF-8 text. |
-| `tools` | `string[]` | No | Up to 64 names from `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, and `ls`; defaults to `read`, `grep`, `find`, and `ls`. |
-| `thinkingLevel` | `string` | No | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; defaults to the main agent's effective thinking level. |
-| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default timeout. |
+| `tools` | `string[]` | No | Pi core tools: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`; defaults to `read`, `grep`, `find`, `ls`. |
+| `skills` | `string[]` | No | Up to 16 local skill files or directories; Pi uses progressive disclosure. |
+| `extensions` | `{ path: string; tools: string[] }[]` | No | Up to 16 trusted local extensions and their initially selected tools. |
+| `thinkingLevel` | `string` | No | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; defaults to the main agent's level. |
+| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default. |
 
-Starts one task-specialized subagent job with the selected tool capabilities and returns its job ID immediately.
+Starts one job and returns its `jobId` immediately. The child inherits the main agent's effective model and always receives `subagent_send` and `subagent_wait`.
 
-The runtime always adds `subagent_send` and `subagent_wait` to the selected tools.
+Skills do not add tools or inject their entire bodies. An extension's `tools` list selects its initial tools; use an empty list for provider or lifecycle behavior only. An attached extension runs trusted code with full child-process permissions, not in a sandbox.
 
-The child inherits the main agent's effective provider and model at spawn time.
-
-Providers registered by a parent extension throw before the job is queued because children disable unrelated extensions.
-
-A process-local runtime API key, including a parent-only `--api-key` value, also throws before queuing.
-
-Use Pi's stored credentials or environment credentials that the child process can read.
-
-Unavailable or extension-only tool names throw before the job is queued.
-
-Throws without launching a child when the session broker is unavailable.
+Attachments must be existing local paths. Every non-ignored declared skill must load successfully, each skill name must be unique, and each skill path must contain at least one loadable Pi skill. Missing or misattributed extension tools fail before the child model receives the task. See [Attachment behavior](./attachments.md) for validation, trust, limits, provider credentials, and startup failures.
 
 ## `subagent_inspect`
 
-No parameters.
+No parameters. Returns privacy-filtered retained-job metadata without task text, output, selected tools, attachment paths, credentials, or messages.
 
 ## `subagent_cancel`
 
@@ -35,6 +27,8 @@ No parameters.
 | --- | --- | --- | --- |
 | `jobId` | `string` | Yes | Job ID returned by `subagent_spawn`. |
 
+Cancels a queued or running job; repeating the call is safe.
+
 ## `subagent_wait`
 
 ### Main agent
@@ -42,26 +36,22 @@ No parameters.
 | Parameter | Type | Required | Constraint / default |
 | --- | --- | --- | --- |
 | `jobId` | `string` | Yes | Job ID to wait for. |
-| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default and does not cancel the job. |
+| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default. |
 
-Returns `{ jobId, state, timedOut: false, interrupted: true, reason: "subagent_message" }` without cancelling the job when a child request or response arrives.
+Returns the job result, or returns early with `reason: "subagent_message"` when a child request or response arrives. A wait timeout does not cancel the job.
 
 ### Subagent
 
 | Parameter | Type | Required | Constraint / default |
 | --- | --- | --- | --- |
 | `requestId` | `string` | Yes | Request ID returned by a child-originated `subagent_send`. |
-| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default and does not cancel the request. |
-
-Returns the main agent's response as plain text.
-
-A timeout, caller cancellation, or incoming main-agent request throws and stops only that wait, so the child may wait for the same request again.
+| `timeout` | `number` | No | Seconds; `> 0` through `2,147,483.647`; no default. |
 
-The runtime interrupts an active child wait only after Pi RPC accepts the incoming main request for steering.
+Returns the main agent's response as plain text. A timeout, cancellation, or incoming main-agent request throws and stops only this wait; the original request remains active and can be waited on again.
 
 ## `subagent_send`
 
-Main and child processes receive separate provider-visible definitions for their own context.
+Main and child processes receive separate tool definitions.
 
 ### Main agent
 
@@ -69,41 +59,17 @@ Main and child processes receive separate provider-visible definitions for their
 | --- | --- | --- | --- |
 | `recipient` | `string` | Conditional | Active job ID for a new request. |
 | `requestId` | `string` | Conditional | Pending child request to answer. |
-| `message` | `string` | Yes | Plain-text request or response, up to 48 KiB of UTF-8 text and 1,992 lines. |
-
-Provide exactly one of `recipient` or `requestId`.
-
-A new request provides an active queued or running job ID as `recipient` and omits `requestId`.
+| `message` | `string` | Yes | Plain text, up to 48 KiB of UTF-8 text and 1,992 lines. |
 
-A response provides `requestId` and omits `recipient`.
+Provide exactly one of `recipient` (new request) or `requestId` (response).
 
 ### Subagent
 
 | Parameter | Type | Required | Constraint / default |
 | --- | --- | --- | --- |
-| `requestId` | `string` | No | Pending main-agent request to answer; omit to start a new request to main. |
-| `message` | `string` | Yes | Plain-text request or response, up to 48 KiB of UTF-8 text and 1,992 lines. |
-
-A new request omits `requestId` and returns a request ID immediately for an optional `subagent_wait` call.
-
-A response provides the pending main-agent `requestId`.
-
-A main-originated request waits for the child RPC prompt to be accepted and then uses Pi steering to reach the running child.
-
-After steering is queued, the runtime interrupts active child response waits without consuming their original requests.
-
-Caller cancellation before RPC delivery starts rolls the request back.
-
-Once RPC delivery starts, cancellation stops only the caller's wait; the request may still arrive and remains answerable until delivery fails or the job terminates.
-
-A child response arrives asynchronously in the main session and interrupts the next active main-agent `subagent_wait`, including when the response arrived immediately before the wait started.
-
-The first accepted response wins, and repeated responses acknowledge the existing response without replacing it.
-
-Each job may have up to four unresolved or answered-but-not-consumed requests across both directions.
-
-Requests and responses are limited to 1,992 lines so their protocol envelopes fit Pi's 2,000-line model-text bound.
+| `requestId` | `string` | No | Pending main-agent request to answer; omit to start a request. |
+| `message` | `string` | Yes | Plain text, up to 48 KiB of UTF-8 text and 1,992 lines. |
 
-Terminal jobs, unknown requests, cross-job responses, responses from the request originator, and stale session credentials throw.
+A new request returns a `requestId` for an optional `subagent_wait` call. A successful send or response returns `{ requestId, accepted, duplicate }`.
 
-A successful call returns `{ requestId, accepted, duplicate }`.
+See [Messaging and lifecycle](./messaging.md) for delivery, cancellation, retry, and response behavior.

package/package.json

@@ -1,56 +1,58 @@
 {
-	"name": "@narumitw/pi-subagents",
-	"version": "3.0.1",
-	"description": "Subagent jobs with asynchronous main-agent messaging for Pi.",
-	"type": "module",
-	"license": "MIT",
-	"private": false,
-	"keywords": [
-		"pi-package",
-		"pi-extension",
-		"pi",
-		"subagents",
-		"agents",
-		"delegation"
-	],
-	"files": [
-		"src",
-		"dist",
-		"docs",
-		"README.md",
-		"LICENSE"
-	],
-	"pi": {
-		"extensions": [
-			"./dist/index.ts"
-		]
-	},
-	"scripts": {
-		"build": "node scripts/build-runtime.mjs",
-		"check": "npm run build && biome check . && npm run typecheck",
-		"format": "biome check --write .",
-		"typecheck": "tsc --noEmit",
-		"prepack": "npm run build"
-	},
-	"peerDependencies": {
-		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
-		"typebox": "*"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "2.5.11",
-		"@earendil-works/pi-ai": "0.84.4",
-		"@earendil-works/pi-coding-agent": "0.84.4",
-		"@earendil-works/pi-tui": "0.84.4",
-		"@types/node": "26.4.0",
-		"esbuild": "0.28.2",
-		"typebox": "1.3.20",
-		"typescript": "7.0.2"
-	},
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/narumiruna/pi-extensions",
-		"directory": "packages/pi-subagents"
-	}
+  "name": "@narumitw/pi-subagents",
+  "version": "3.1.0",
+  "description": "Subagent jobs with asynchronous main-agent messaging for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "subagents",
+    "agents",
+    "delegation"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/build-runtime.mjs",
+    "check": "npm run build && biome check . && npm run typecheck",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.86.0",
+    "@earendil-works/pi-coding-agent": "0.86.0",
+    "@earendil-works/pi-tui": "0.86.0",
+    "@types/node": "26.6.2",
+    "esbuild": "0.28.2",
+    "typebox": "1.3.34",
+    "typescript": "7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/narumiruna/pi-extensions",
+    "directory": "packages/pi-subagents"
+  },
+  "dependencies": {
+    "ignore": "^7.0.8"
+  }
 }

package/src/attachment-utils.ts

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import * as path from "node:path";
+import type ignore from "ignore";
+import { sanitizeTerminalText } from "./message-broker.js";
+
+const ATTACHMENT_IGNORE_FILE_NAMES = [".gitignore", ".ignore", ".fdignore"];
+
+export type IgnoreMatcher = ReturnType<typeof ignore>;
+
+function throwInvalidAttachmentIgnoreFile(): never {
+  throw new Error("Subagent attachment ignore files must be regular files.");
+}
+
+export function throwIfAttachmentAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  const error = new Error("Subagent attachment validation was cancelled.");
+  error.name = "AbortError";
+  throw error;
+}
+
+export function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+function prefixIgnorePattern(line: string, prefix: string): string | null {
+  const trimmed = line.trim();
+  if (!trimmed || (trimmed.startsWith("#") && !trimmed.startsWith("\\#"))) return null;
+  let pattern = line;
+  let negated = false;
+  if (pattern.startsWith("!")) {
+    negated = true;
+    pattern = pattern.slice(1);
+  } else if (pattern.startsWith("\\!")) {
+    pattern = pattern.slice(1);
+  }
+  if (pattern.startsWith("/")) pattern = pattern.slice(1);
+  const prefixed = prefix ? `${prefix}${pattern}` : pattern;
+  return negated ? `!${prefixed}` : prefixed;
+}
+
+export async function addAttachmentIgnoreRules(
+  ignoreMatcher: IgnoreMatcher,
+  directory: string,
+  rootDirectory: string,
+  signal: AbortSignal | undefined,
+  accountForFile: (ignorePath: string, bytes: number) => void,
+): Promise<void> {
+  const relativeDirectory = path.relative(rootDirectory, directory);
+  const prefix = relativeDirectory ? `${toPosixPath(relativeDirectory)}/` : "";
+  for (const filename of ATTACHMENT_IGNORE_FILE_NAMES) {
+    throwIfAttachmentAborted(signal);
+    const ignorePath = path.join(directory, filename);
+    let ignoreStats: Awaited<ReturnType<typeof stat>>;
+    try {
+      ignoreStats = await stat(ignorePath);
+    } catch (error) {
+      if (isAbortError(error)) throw error;
+      throwIfAttachmentAborted(signal);
+      continue;
+    }
+    if (!ignoreStats.isFile()) throwInvalidAttachmentIgnoreFile();
+    accountForFile(ignorePath, ignoreStats.size);
+    try {
+      const content = await readFile(ignorePath, { encoding: "utf8", signal });
+      throwIfAttachmentAborted(signal);
+      const patterns = content
+        .split(/\r?\n/u)
+        .map((line) => prefixIgnorePattern(line, prefix))
+        .filter((line): line is string => line !== null);
+      if (patterns.length > 0) ignoreMatcher.add(patterns);
+    } catch (error) {
+      if (isAbortError(error)) throw error;
+      throwIfAttachmentAborted(signal);
+      // Pi ignores unreadable ignore files.
+    }
+  }
+}
+
+export function toPosixPath(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+export function toolSourceId(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function realpath(value: string, label: string): string {
+  try {
+    return realpathSync(value);
+  } catch {
+    throw new Error(`${label} path does not exist: ${sanitizeTerminalText(value).slice(0, 512)}`);
+  }
+}
+
+export function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/broker-credentials.ts

@@ -3,69 +3,147 @@ import type { BrokerCredentials } from "./types.js";
 
 export const BROKER_CREDENTIAL_FD = 3;
 export const BROKER_CREDENTIAL_FD_ENV = "PI_SUBAGENT_BROKER_FD";
+export const CHILD_READINESS_FD = 4;
+export const CHILD_READINESS_FD_ENV = "PI_SUBAGENT_READINESS_FD";
+export const MAX_READINESS_FRAME_BYTES = 16 * 1024;
 
-const MAX_CREDENTIAL_BYTES = 1_024;
+const MAX_BOOTSTRAP_BYTES = 16 * 1024;
+const MAX_EXPECTED_TOOLS = 66;
+const MAX_TOOL_NAME_LENGTH = 128;
+const READINESS_STATE_KEY = Symbol.for("@narumitw/pi-subagents/child-readiness");
 
-export function brokerCredentialEnvironment(): NodeJS.ProcessEnv {
-	return { [BROKER_CREDENTIAL_FD_ENV]: String(BROKER_CREDENTIAL_FD) };
+export interface ChildBootstrap {
+  communication: BrokerCredentials;
+  expectedTools: string[];
 }
 
-export function serializeBrokerCredentials(credentials: BrokerCredentials): string {
-	return JSON.stringify(credentials);
+export interface CapturedChildBootstrap extends ChildBootstrap {
+  readinessFd?: number;
 }
 
-export function captureBrokerCredentials(
-	readCredentials: () => string = readCredentialPipe,
-): BrokerCredentials | undefined {
-	const descriptor = process.env[BROKER_CREDENTIAL_FD_ENV];
-	delete process.env[BROKER_CREDENTIAL_FD_ENV];
-	if (descriptor === undefined) return undefined;
-	if (descriptor !== String(BROKER_CREDENTIAL_FD)) {
-		throw new Error("Invalid pi-subagents broker credential descriptor.");
-	}
-	let serialized: string;
-	try {
-		serialized = readCredentials();
-	} catch {
-		throw new Error("Unable to read pi-subagents broker credentials.");
-	}
-	if (Buffer.byteLength(serialized, "utf8") > MAX_CREDENTIAL_BYTES) {
-		throw new Error("Invalid pi-subagents broker credentials.");
-	}
-	let value: unknown;
-	try {
-		value = JSON.parse(serialized);
-	} catch {
-		throw new Error("Invalid pi-subagents broker credentials.");
-	}
-	if (!isBrokerCredentials(value)) {
-		throw new Error("Invalid pi-subagents broker credentials.");
-	}
-	return value;
+export function childBootstrapEnvironment(expectReadiness: boolean): NodeJS.ProcessEnv {
+  return {
+    [BROKER_CREDENTIAL_FD_ENV]: String(BROKER_CREDENTIAL_FD),
+    ...(expectReadiness ? { [CHILD_READINESS_FD_ENV]: String(CHILD_READINESS_FD) } : {}),
+  };
 }
 
-function readCredentialPipe(): string {
-	try {
-		return fs.readFileSync(BROKER_CREDENTIAL_FD, "utf8");
-	} finally {
-		try {
-			fs.closeSync(BROKER_CREDENTIAL_FD);
-		} catch {
-			// The descriptor may already be closed after a failed read.
-		}
-	}
+export function serializeChildBootstrap(bootstrap: ChildBootstrap): string {
+  return JSON.stringify(bootstrap);
+}
+
+export function assertChildBootstrapCapacity(expectedTools: string[]): void {
+  const serialized = serializeChildBootstrap({
+    communication: { host: "127.0.0.1", port: 65_535, token: "f".repeat(64) },
+    expectedTools,
+  });
+  if (Buffer.byteLength(serialized, "utf8") > MAX_BOOTSTRAP_BYTES) {
+    throw new Error(`Subagent selected tool names exceed the ${MAX_BOOTSTRAP_BYTES}-byte child bootstrap size limit.`);
+  }
+}
+
+export function captureChildBootstrap(
+  readBootstrap: () => string = readBootstrapPipe,
+): CapturedChildBootstrap | undefined {
+  const credentialDescriptor = process.env[BROKER_CREDENTIAL_FD_ENV];
+  const readinessDescriptor = process.env[CHILD_READINESS_FD_ENV];
+  delete process.env[BROKER_CREDENTIAL_FD_ENV];
+  delete process.env[CHILD_READINESS_FD_ENV];
+  setCapturedReadiness(undefined);
+  if (credentialDescriptor === undefined) {
+    if (readinessDescriptor !== undefined) throw new Error("Unexpected pi-subagents readiness descriptor.");
+    return undefined;
+  }
+  if (credentialDescriptor !== String(BROKER_CREDENTIAL_FD)) {
+    throw new Error("Invalid pi-subagents broker credential descriptor.");
+  }
+  let serialized: string;
+  try {
+    serialized = readBootstrap();
+  } catch {
+    throw new Error("Unable to read pi-subagents child bootstrap.");
+  }
+  if (Buffer.byteLength(serialized, "utf8") > MAX_BOOTSTRAP_BYTES) {
+    throw new Error("Invalid pi-subagents child bootstrap.");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(serialized);
+  } catch {
+    throw new Error("Invalid pi-subagents child bootstrap.");
+  }
+  if (!isChildBootstrap(value)) throw new Error("Invalid pi-subagents child bootstrap.");
+
+  if (value.expectedTools.length > 0) {
+    if (readinessDescriptor !== String(CHILD_READINESS_FD)) {
+      throw new Error("Invalid pi-subagents readiness descriptor.");
+    }
+    setCapturedReadiness({ fd: CHILD_READINESS_FD, expectedTools: [...value.expectedTools] });
+    return { ...value, readinessFd: CHILD_READINESS_FD };
+  }
+  if (readinessDescriptor !== undefined) throw new Error("Unexpected pi-subagents readiness descriptor.");
+  setCapturedReadiness(undefined);
+  return value;
+}
+
+export function takeCapturedReadiness(): { fd: number; expectedTools: string[] } | undefined {
+  const store = globalThis as unknown as Record<symbol, { fd: number; expectedTools: string[] } | undefined>;
+  const readiness = store[READINESS_STATE_KEY];
+  delete store[READINESS_STATE_KEY];
+  return readiness ? { fd: readiness.fd, expectedTools: [...readiness.expectedTools] } : undefined;
+}
+
+function setCapturedReadiness(readiness: { fd: number; expectedTools: string[] } | undefined): void {
+  const store = globalThis as unknown as Record<symbol, { fd: number; expectedTools: string[] } | undefined>;
+  if (readiness) store[READINESS_STATE_KEY] = readiness;
+  else delete store[READINESS_STATE_KEY];
+}
+
+function readBootstrapPipe(): string {
+  try {
+    return fs.readFileSync(BROKER_CREDENTIAL_FD, "utf8");
+  } finally {
+    try {
+      fs.closeSync(BROKER_CREDENTIAL_FD);
+    } catch {
+      // The descriptor may already be closed after a failed read.
+    }
+  }
+}
+
+function isChildBootstrap(value: unknown): value is ChildBootstrap {
+  if (!isRecord(value) || Object.keys(value).length !== 2) return false;
+  if (!isBrokerCredentials(value.communication)) return false;
+  if (!Array.isArray(value.expectedTools) || value.expectedTools.length > MAX_EXPECTED_TOOLS) return false;
+  return value.expectedTools.every(
+    (tool) =>
+      typeof tool === "string" &&
+      tool.length > 0 &&
+      tool.length <= MAX_TOOL_NAME_LENGTH &&
+      !tool.includes(",") &&
+      !hasControlCharacter(tool),
+  );
 }
 
 function isBrokerCredentials(value: unknown): value is BrokerCredentials {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const candidate = value as Record<string, unknown>;
-	return (
-		Object.keys(candidate).length === 3 &&
-		candidate.host === "127.0.0.1" &&
-		Number.isSafeInteger(candidate.port) &&
-		(candidate.port as number) >= 1 &&
-		(candidate.port as number) <= 65_535 &&
-		typeof candidate.token === "string" &&
-		/^[a-f0-9]{64}$/u.test(candidate.token)
-	);
+  if (!isRecord(value) || Object.keys(value).length !== 3) return false;
+  return (
+    value.host === "127.0.0.1" &&
+    Number.isSafeInteger(value.port) &&
+    (value.port as number) >= 1 &&
+    (value.port as number) <= 65_535 &&
+    typeof value.token === "string" &&
+    /^[a-f0-9]{64}$/u.test(value.token)
+  );
+}
+
+function hasControlCharacter(value: string): boolean {
+  return [...value].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }