@narumitw/pi-subagents 3.3.2 → 3.4.0

package/docs/attachments.md

@@ -20,7 +20,7 @@ An extension directory must resolve to at least one loadable Pi entrypoint. Ever
 
 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.
+Every child uses a readiness probe to confirm its exact registered chat-model pair and current provider availability before receiving the task. When an extension is attached, the probe also 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.
 
@@ -28,10 +28,16 @@ An attached extension executes trusted code with the child process's user permis
 
 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.
+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 plus the requested provider, model, and thinking level, 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.
+The child inherits each omitted `provider` or `model` independently from the main agent at spawn time. Explicit values select exact IDs without fallback; see [Model selection](./tools.md#model-selection). Unlisted custom IDs, including inherited ones, require explicit model registration. 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. This is a provider portability check, not a model-list lookup. Only the child checks exact model registration and availability. An attached extension can register a pair absent from the parent's catalog. A missing or unavailable pair fails the admitted job before the task is sent. Registered virtual models follow the same rule.
+
+The requested pair is sent through the private bootstrap, not Pi's CLI model-pattern parser. Any initial default model is provisional and receives no task. The child binds the exact requested registration through Pi's public API before readiness. Attached code must finish registering the pair before that check; factory, `session_start`, or earlier `resources_discover` hooks can register it.
+
+Exact child selection can run `model_select` hooks. Pi does not await asynchronous `thinking_level_select` handlers, so attached code can still change behavior after the initial check. 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,7 +12,9 @@ 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, explicit per-job attachments, and one task.
+The subagent still receives Pi's standard system prompt, applicable project context, its selected tools, explicit per-job attachments, and one task.
+
+Each omitted `provider` or `model` inherits independently from the main agent at spawn time. Explicit values select another exact pair. Only the child checks that the requested pair is registered and available before it receives the task.
 
 The task defines the child's specialization, while selected tools and trusted attachments define its authority.
 

package/docs/tools.md

@@ -5,13 +5,15 @@
 | Parameter | Type | Required | Constraint / default |
 | --- | --- | --- | --- |
 | `task` | `string` | Yes | Self-contained task, up to 50 KiB of UTF-8 text. |
+| `provider` | `string` | No | Exact provider ID; defaults to the main agent's effective provider at spawn time. |
+| `model` | `string` | No | Exact model ID within the selected provider; defaults independently to the main agent's effective model ID at spawn time. |
 | `tools` | `string[]` | No | Pi tools: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`, `codemode`; 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 job and returns its `jobId` immediately. The child inherits the main agent's effective model and always receives `subagent_send` and `subagent_wait`.
+Starts one job and returns its `jobId` without waiting for child startup. The child always receives `subagent_send` and `subagent_wait`.
 
 Select `codemode` explicitly with the other required tools, for example `tools: ["read", "grep", "codemode"]`.
 Pi's built-in codemode extension runs scripts against the child's callable tools, including `subagent_send` and `subagent_wait`; automatic resource discovery stays disabled.
@@ -22,6 +24,18 @@ Skills do not add tools or inject their entire bodies. An extension's `tools` li
 
 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.
 
+### Model selection
+
+Each omitted field inherits independently from one effective parent-model snapshot after attachment preflight, immediately before job admission. Supplying only `provider` keeps the parent's model ID; it never selects the new provider's default. Supplying only `model` keeps the parent's provider. Supplying both fields does not require a selected parent model. Later parent changes do not alter the admitted pair.
+
+IDs are literal and case-sensitive. No trimming, aliases, fuzzy matches, combined provider/model syntax, thinking suffixes, or default fallback are applied. `/` and `:` remain part of a legitimate model ID. Listed IDs that differ only by case or contain provider-like prefixes select their exact entries, not Pi CLI pattern matches. Empty, whitespace-only, non-string, or control-containing values are rejected rather than inherited.
+
+Only the child checks model registration and availability. Every job requires the exact pair to be a registered, available chat model in that child. The parent's model list does not limit the selection. Image and classifier models cannot run a subagent. Registered virtual chat models are supported when the child independently registers the same selection; parent-only routing state is not inherited. A trusted attached extension can register the pair before the child's readiness check.
+
+The parent validates arguments, session state, attachments, and credential portability before job admission. These errors throw from `subagent_spawn`. Model registration and availability errors occur in the child after `subagent_spawn` returns a `jobId`; the job fails without sending its task to any model. Use `subagent_wait` to read the failure. Availability checks use Pi's current provider authentication and model filtering, not the remote service's entitlement checks; a later provider request can still fail. `thinkingLevel` remains a separate parameter and Pi clamps it to the selected model's capabilities.
+
+**Compatibility:** unlisted custom model IDs that Pi's CLI previously accepted now fail, including inherited IDs. Add an exact chat-model entry to Pi's `models.json` or attach a trusted extension that registers it in the child. Reload the extension or start a new session after upgrading so the model receives the new fixed tool schema; per-job choices do not change that schema during ordinary turns.
+
 ## `subagent_inspect`
 
 No parameters. Returns privacy-filtered retained-job metadata without task text, output, selected tools, attachment paths, credentials, or messages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-subagents",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "Subagent jobs with asynchronous main-agent messaging for Pi.",
   "type": "module",
   "license": "MIT",
@@ -39,12 +39,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.3.0",
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
-    "typebox": "1.4.2",
+    "typebox": "1.4.3",
     "typescript": "7.0.2"
   },
   "repository": {
@@ -53,7 +53,7 @@
     "directory": "packages/pi-subagents"
   },
   "dependencies": {
-    "@narumitw/pi-tui-kit": "^0.66.0",
+    "@narumitw/pi-tui-kit": "^0.68.0",
     "ignore": "^7.0.13"
   }
 }

package/src/broker-credentials.ts

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import type { BrokerCredentials } from "./types.js";
+import { type BrokerCredentials, SUBAGENT_THINKING_LEVELS, type SubagentThinkingLevel } from "./types.js";
 
 export const BROKER_CREDENTIAL_FD = 3;
 export const BROKER_CREDENTIAL_FD_ENV = "PI_SUBAGENT_BROKER_FD";
@@ -7,14 +7,27 @@ 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_BOOTSTRAP_BYTES = 16 * 1024;
+export 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 interface ChildSelection {
+  provider: string;
+  model: string;
+  thinkingLevel: SubagentThinkingLevel;
+}
+
 export interface ChildBootstrap {
   communication: BrokerCredentials;
   expectedTools: string[];
+  selection: ChildSelection;
+}
+
+interface CapturedReadiness {
+  fd: number;
+  expectedTools: string[];
+  selection: ChildSelection;
 }
 
 export interface CapturedChildBootstrap extends ChildBootstrap {
@@ -32,13 +45,16 @@ export function serializeChildBootstrap(bootstrap: ChildBootstrap): string {
   return JSON.stringify(bootstrap);
 }
 
-export function assertChildBootstrapCapacity(expectedTools: string[]): void {
+export function assertChildBootstrapCapacity(expectedTools: string[], selection: ChildSelection): void {
   const serialized = serializeChildBootstrap({
     communication: { host: "127.0.0.1", port: 65_535, token: "f".repeat(64) },
     expectedTools,
+    selection,
   });
   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.`);
+    throw new Error(
+      `Subagent tools and model selection exceed the ${MAX_BOOTSTRAP_BYTES}-byte child bootstrap size limit.`,
+    );
   }
 }
 
@@ -78,23 +94,29 @@ export function captureChildBootstrap(
     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 };
+    setCapturedReadiness({
+      fd: CHILD_READINESS_FD,
+      expectedTools: [...value.expectedTools],
+      selection: { ...value.selection },
+    });
+    return { ...value, selection: { ...value.selection }, 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>;
+export function takeCapturedReadiness(): CapturedReadiness | undefined {
+  const store = globalThis as unknown as Record<symbol, CapturedReadiness | undefined>;
   const readiness = store[READINESS_STATE_KEY];
   delete store[READINESS_STATE_KEY];
-  return readiness ? { fd: readiness.fd, expectedTools: [...readiness.expectedTools] } : undefined;
+  return readiness
+    ? { fd: readiness.fd, expectedTools: [...readiness.expectedTools], selection: { ...readiness.selection } }
+    : undefined;
 }
 
-function setCapturedReadiness(readiness: { fd: number; expectedTools: string[] } | undefined): void {
-  const store = globalThis as unknown as Record<symbol, { fd: number; expectedTools: string[] } | undefined>;
+function setCapturedReadiness(readiness: CapturedReadiness | undefined): void {
+  const store = globalThis as unknown as Record<symbol, CapturedReadiness | undefined>;
   if (readiness) store[READINESS_STATE_KEY] = readiness;
   else delete store[READINESS_STATE_KEY];
 }
@@ -112,8 +134,8 @@ function readBootstrapPipe(): string {
 }
 
 function isChildBootstrap(value: unknown): value is ChildBootstrap {
-  if (!isRecord(value) || Object.keys(value).length !== 2) return false;
-  if (!isBrokerCredentials(value.communication)) return false;
+  if (!isRecord(value) || Object.keys(value).length !== 3) return false;
+  if (!isBrokerCredentials(value.communication) || !isChildSelection(value.selection)) return false;
   if (!Array.isArray(value.expectedTools) || value.expectedTools.length > MAX_EXPECTED_TOOLS) return false;
   return value.expectedTools.every(
     (tool) =>
@@ -125,6 +147,15 @@ function isChildBootstrap(value: unknown): value is ChildBootstrap {
   );
 }
 
+function isChildSelection(value: unknown): value is ChildSelection {
+  if (!isRecord(value) || Object.keys(value).length !== 3) return false;
+  return (
+    [value.provider, value.model].every(
+      (id) => typeof id === "string" && id.trim().length > 0 && !hasControlCharacter(id),
+    ) && SUBAGENT_THINKING_LEVELS.includes(value.thinkingLevel as SubagentThinkingLevel)
+  );
+}
+
 function isBrokerCredentials(value: unknown): value is BrokerCredentials {
   if (!isRecord(value) || Object.keys(value).length !== 3) return false;
   return (

package/src/child-communication-tools.ts

@@ -4,6 +4,8 @@ import {
   type BrokerSendAcknowledgement,
   MAX_IDENTIFIER_LENGTH,
   MAX_MESSAGE_BYTES,
+  optionalIdentifier,
+  requiredIdentifier,
   sanitizeTerminalText,
   validateMessage,
 } from "./message-broker.js";
@@ -98,22 +100,3 @@ export function createChildCommunicationExtension(client: ChildCommunicationClie
 function prepareWaitArguments(args: unknown): WaitArguments {
   return prepareTimeoutArguments(args) as WaitArguments;
 }
-
-function optionalIdentifier(value: unknown, field: string): string | undefined {
-  return value === undefined ? undefined : requiredIdentifier(value, field);
-}
-
-function requiredIdentifier(value: unknown, field: string): string {
-  if (typeof value !== "string" || !value.trim()) throw new Error(`Subagent ${field} is required.`);
-  const identifier = value.trim();
-  if (
-    identifier.length > MAX_IDENTIFIER_LENGTH ||
-    [...identifier].some((character) => {
-      const codePoint = character.codePointAt(0) ?? 0;
-      return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
-    })
-  ) {
-    throw new Error(`Subagent ${field} is invalid.`);
-  }
-  return identifier;
-}

package/src/child-readiness-probe.ts

@@ -1,11 +1,13 @@
 import * as fs from "node:fs";
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { toolSourceId } from "./attachment-utils.js";
-import { MAX_READINESS_FRAME_BYTES, takeCapturedReadiness } from "./broker-credentials.js";
+import { type ChildSelection, MAX_READINESS_FRAME_BYTES, takeCapturedReadiness } from "./broker-credentials.js";
+import { type ChildReadinessFrame, isChildModelPair } from "./child-readiness.js";
 
 export interface ChildReadinessState {
   fd: number;
   expectedTools: string[];
+  selection: ChildSelection;
 }
 
 const captured = takeCapturedReadiness();
@@ -14,6 +16,8 @@ const childReadinessProbe: ExtensionFactory = captured ? createChildReadinessPro
 
 export default childReadinessProbe;
 
+class ReadinessError extends Error {}
+
 export function createChildReadinessProbe(
   readiness: ChildReadinessState,
   writeFrame: (fd: number, frame: string) => void = writeReadinessFrame,
@@ -21,13 +25,17 @@ export function createChildReadinessProbe(
 ): ExtensionFactory {
   return (pi) => {
     let settled = false;
-    const publish = (value: { ok: true; sources: string[] } | { ok: false; error: string }) => {
+    let started = false;
+    let controller: AbortController | undefined;
+    let deadline: NodeJS.Timeout | undefined;
+    const publish = (value: ChildReadinessFrame) => {
       if (settled) return;
       settled = true;
-      const frame = `${JSON.stringify(value)}\n`;
+      if (deadline) clearTimeout(deadline);
+      controller?.abort();
+      let frame = `${JSON.stringify(value)}\n`;
       if (Buffer.byteLength(frame, "utf8") > MAX_READINESS_FRAME_BYTES) {
-        close(readiness.fd);
-        throw new Error("Pi-subagents readiness frame exceeded its size limit.");
+        frame = `${JSON.stringify({ ok: false, error: "Subagent readiness frame exceeded its size limit." })}\n`;
       }
       try {
         writeFrame(readiness.fd, frame);
@@ -35,22 +43,140 @@ export function createChildReadinessProbe(
         close(readiness.fd);
       }
     };
-
-    pi.on("resources_discover", () => {
-      const active = new Set(pi.getActiveTools());
-      const missing = readiness.expectedTools.filter((tool) => !active.has(tool));
+    const toolState = () => {
+      const active = pi.getActiveTools();
+      const missing = readiness.expectedTools.filter((tool) => !active.includes(tool));
       if (missing.length > 0) {
-        publish({ ok: false, error: `Unavailable subagent tools: ${missing.join(", ")}.` });
-        return;
+        throw new ReadinessError(`Unavailable subagent tools: ${missing.join(", ").slice(0, 512)}.`);
       }
-      const sources = new Map(pi.getAllTools().map((tool) => [tool.name, tool.sourceInfo.path]));
-      publish({
-        ok: true,
-        sources: readiness.expectedTools.map((tool) => {
-          const source = sources.get(tool);
-          return source ? toolSourceId(source) : "";
-        }),
+      const all = new Map(pi.getAllTools().map((tool) => [tool.name, tool.sourceInfo.path]));
+      const sources = readiness.expectedTools.map((tool) => {
+        const source = all.get(tool);
+        if (!source) throw new ReadinessError("Subagent child tool provenance is unavailable.");
+        return toolSourceId(source);
       });
+      return { active, sources };
+    };
+
+    pi.on("resources_discover", async (_event, ctx) => {
+      if (settled || started) return;
+      started = true;
+      controller = new AbortController();
+      const signal = ctx.signal ? AbortSignal.any([controller.signal, ctx.signal]) : controller.signal;
+      deadline = setTimeout(() => publish({ ok: false, error: "Subagent child model readiness timed out." }), 30_000);
+      deadline.unref();
+      try {
+        const tools = toolState();
+        const initialModel = ctx.model;
+        const initialDefinition = JSON.stringify(initialModel);
+        const pair = { provider: readiness.selection.provider, id: readiness.selection.model };
+        const registry = ctx.modelRegistry;
+        const manager = ctx.sessionManager;
+        const sessionId = manager.getSessionId();
+        const cwd = ctx.cwd;
+        const trusted = ctx.isProjectTrusted();
+        const nativeProvider = registry.getRegisteredNativeProvider(pair.provider);
+        const providerConfig = registry.getRegisteredProviderConfig(pair.provider);
+        const assertContext = () => {
+          signal.throwIfAborted();
+          if (
+            ctx.modelRegistry !== registry ||
+            ctx.sessionManager !== manager ||
+            manager.getSessionId() !== sessionId ||
+            ctx.cwd !== cwd ||
+            ctx.isProjectTrusted() !== trusted ||
+            registry.getRegisteredNativeProvider(pair.provider) !== nativeProvider ||
+            registry.getRegisteredProviderConfig(pair.provider) !== providerConfig ||
+            JSON.stringify(toolState()) !== JSON.stringify(tools)
+          )
+            throw new ReadinessError("Subagent child context changed during model readiness.");
+        };
+        const assertInitialModel = () => {
+          assertContext();
+          if (ctx.model !== initialModel || JSON.stringify(ctx.model) !== initialDefinition) {
+            throw new ReadinessError("Subagent child context changed during model readiness.");
+          }
+        };
+        // The public setter checks the configured-auth snapshot before checking fresh auth.
+        // Refresh it without network access; refresh can recompose registered model objects.
+        await registry.refresh({ providers: [pair.provider], allowNetwork: false, signal });
+        if (settled) return;
+        assertInitialModel();
+        const registration = registry.find(pair.provider, pair.id);
+        if (!registration) {
+          throw new ReadinessError("Subagent child model is not registered as an exact chat model.");
+        }
+        const registeredDefinition = JSON.stringify(registration);
+        const assertRegistration = () => {
+          if (JSON.stringify(registry.find(pair.provider, pair.id)) !== registeredDefinition) {
+            throw new ReadinessError("Subagent child registration changed during model readiness.");
+          }
+        };
+        // Use a fresh provider-scoped availability check, not the cached chat snapshot.
+        const available = await registry.getAvailableOfType("chat", pair.provider, { signal });
+        if (settled) return;
+        assertInitialModel();
+        assertRegistration();
+        if (!available.some((entry) => entry.provider === pair.provider && entry.id === pair.id)) {
+          throw new ReadinessError(
+            "Subagent child model is unavailable as an exact chat model with current credentials.",
+          );
+        }
+        // CLI matching is not literal. Bind only the exact available registration before any task.
+        // setModel has no signal; the parent startup deadline terminates the isolated child.
+        let selectedModel = ctx.model;
+        if (
+          !isChildModelPair(selectedModel) ||
+          selectedModel.provider !== pair.provider ||
+          selectedModel.id !== pair.id ||
+          JSON.stringify(selectedModel) !== registeredDefinition
+        ) {
+          const selected = await pi.setModel(registration);
+          if (settled) return;
+          assertContext();
+          assertRegistration();
+          if (!selected) throw new ReadinessError("Subagent child could not select the exact requested model.");
+          selectedModel = registration;
+        }
+        const assertSelected = () => {
+          assertContext();
+          assertRegistration();
+          const model = ctx.model;
+          if (
+            model !== selectedModel ||
+            !isChildModelPair(model) ||
+            model.provider !== pair.provider ||
+            model.id !== pair.id ||
+            JSON.stringify(model) !== registeredDefinition
+          )
+            throw new ReadinessError("Subagent child model changed during exact initial selection.");
+        };
+        assertSelected();
+        // setModel applies model/global defaults and awaits model_select hooks. Restore the request
+        // only after verifying their result; Pi clamps it to this exact model's capabilities.
+        pi.setThinkingLevel(readiness.selection.thinkingLevel);
+        assertSelected();
+        // Selection hooks can change credentials or filters without replacing registration. Include
+        // synchronous thinking hooks; Pi does not await their later asynchronous continuations.
+        const availableAfterSelection = await registry.getAvailableOfType("chat", pair.provider, { signal });
+        if (settled) return;
+        assertSelected();
+        if (!availableAfterSelection.some((entry) => entry.provider === pair.provider && entry.id === pair.id)) {
+          throw new ReadinessError(
+            "Subagent child model is unavailable as an exact chat model with current credentials.",
+          );
+        }
+        publish({ ok: true, sources: tools.sources, model: pair });
+      } catch (error) {
+        // Provider/auth errors can contain secrets and paths. Publish only bounded probe-owned diagnostics.
+        publish({
+          ok: false,
+          error: error instanceof ReadinessError ? error.message : "Subagent child model readiness failed.",
+        });
+      } finally {
+        if (deadline) clearTimeout(deadline);
+        controller.abort();
+      }
     });
 
     pi.on("session_shutdown", () => {

package/src/child-readiness.ts

@@ -0,0 +1,118 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isWithin } from "./attachment-utils.js";
+import { MAX_READINESS_FRAME_BYTES } from "./broker-credentials.js";
+import { sanitizeTerminalText } from "./message-broker.js";
+
+export interface ChildModelPair {
+  provider: string;
+  id: string;
+}
+
+export type ChildReadinessFrame = { ok: true; sources: string[]; model: ChildModelPair } | { ok: false; error: string };
+
+export function isChildModelPair(value: unknown): value is ChildModelPair {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const model = value as Record<string, unknown>;
+  return [model.provider, model.id].every(
+    (part) =>
+      typeof part === "string" &&
+      part.trim().length > 0 &&
+      ![...part].some((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+      }),
+  );
+}
+
+export function assertChildModelPair(value: unknown, expected: { provider: string; model: string }): void {
+  if (!isChildModelPair(value)) throw new Error("Subagent child model attestation returned an invalid model.");
+  if (value.provider !== expected.provider || value.id !== expected.model) {
+    throw new Error("Subagent child model does not match the requested provider and model.");
+  }
+}
+
+export function assertChildModelState(value: unknown, expected: { provider: string; model: string }): void {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Subagent child model attestation returned invalid state.");
+  }
+  assertChildModelPair((value as { model?: unknown }).model, expected);
+}
+
+export function parseReadinessFrame(buffer: Buffer, expectedToolCount: number): ChildReadinessFrame {
+  if (buffer.byteLength > MAX_READINESS_FRAME_BYTES) {
+    throw new Error("Subagent readiness frame exceeded its size limit.");
+  }
+  if (buffer.byteLength === 0) throw new Error("Subagent readiness pipe closed without a result.");
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer);
+  } catch {
+    throw new Error("Subagent readiness pipe returned invalid UTF-8.");
+  }
+  const newline = text.indexOf("\n");
+  if (newline < 0 || newline !== text.length - 1) {
+    throw new Error("Subagent readiness pipe returned an invalid frame.");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text.slice(0, newline));
+  } catch {
+    throw new Error("Subagent readiness pipe returned malformed JSON.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Subagent readiness pipe returned an invalid result.");
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    record.ok === true &&
+    Object.keys(record).length === 3 &&
+    Array.isArray(record.sources) &&
+    record.sources.length === expectedToolCount &&
+    record.sources.every((source) => typeof source === "string" && /^[a-f0-9]{64}$/u.test(source)) &&
+    isChildModelPair(record.model) &&
+    Object.keys(record.model).length === 2
+  ) {
+    return { ok: true, sources: record.sources, model: record.model };
+  }
+  if (
+    record.ok === false &&
+    Object.keys(record).length === 2 &&
+    typeof record.error === "string" &&
+    record.error.length > 0 &&
+    Buffer.byteLength(record.error, "utf8") <= 8 * 1024
+  ) {
+    return { ok: false, error: sanitizeTerminalText(record.error) };
+  }
+  throw new Error("Subagent readiness pipe returned an invalid result.");
+}
+
+export function assertTrustedChildResources(value: unknown, cwd: string): void {
+  const invalid = () => new Error("Subagent child resource attestation returned invalid commands.");
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid();
+  const commands = (value as { commands?: unknown }).commands;
+  if (!Array.isArray(commands)) throw invalid();
+  let canonicalCwd: string;
+  try {
+    canonicalCwd = fs.realpathSync(cwd);
+  } catch {
+    throw invalid();
+  }
+  for (const command of commands) {
+    if (!command || typeof command !== "object" || Array.isArray(command)) throw invalid();
+    const entry = command as { source?: unknown; sourceInfo?: { path?: unknown } };
+    if (entry.source !== "skill" && entry.source !== "prompt") continue;
+    const resourcePath = entry.sourceInfo?.path;
+    if (typeof resourcePath !== "string" || !resourcePath) throw invalid();
+    const lexicalPath = path.resolve(cwd, resourcePath);
+    let canonicalPath: string;
+    try {
+      canonicalPath = fs.realpathSync(lexicalPath);
+    } catch {
+      throw invalid();
+    }
+    if (isWithin(cwd, lexicalPath) || isWithin(canonicalCwd, canonicalPath)) {
+      throw new Error("Subagent child cannot load project resources because the project is not trusted.");
+    }
+  }
+}