@cr1ms0n/pi-subagent 0.8.9 → 0.10.0

package/skills/subagent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent
-description: Delegate work to isolated child agents with the subagent tool — model and thinking policy, explore/review/general profiles, parallel fanout with synthesis, worktree isolation and the diff/apply/discard loop, background runs, steering, output_schema, context fork, and backend tradeoffs (pi/codex/claude). Use when delegating exploration or implementation, running tasks in parallel, or when a subagent run needs inspecting, steering, or landing.
+description: Delegate work to isolated child agents with the subagent tool. Jev routes each new dispatch to an execution model and individual tools from the user's configured candidate list; covers explore/review/general profiles, parallel fanout with best-effort synthesis, worktree isolation and the diff/apply/discard loop, background runs, steering, output_schema, context fork, and the Pi-only new-dispatch rule. Use when delegating exploration or implementation, running tasks in parallel, or when a subagent run needs inspecting, steering, or landing.
 ---
 
 # Subagent
@@ -20,24 +20,24 @@ from isolation, parallelism, or a fresh context.
 ## Core calls
 
 ```ts
-// Examples use placeholders only. Replace these with the exact model selected
-// from the current modelPolicy route; they do not configure a real model.
-const routeModel = "<exact model from current modelPolicy route>";
+// Omit model and fallback_models. Jev selects the execution model from the
+// user's configured candidate list and the individual tools from the locally
+// permitted catalog. An explicit model/fallback is rejected on new work.
 
 // Single foreground task (default profile: general)
-{ task: "Find call sites of parseConfig", description: "Map parseConfig", model: routeModel }
+{ task: "Find call sites of parseConfig", description: "Map parseConfig" }
 
 // Parallel read-only explorers (default profile for tasks[]: explore)
 {
   tasks: [
-    { task: "Map auth middleware", description: "Auth flow", model: routeModel },
-    { task: "List env vars in server/", description: "Env inventory", model: routeModel }
+    { task: "Map auth middleware", description: "Auth flow" },
+    { task: "List env vars in server/", description: "Env inventory" }
   ],
   synthesis: "Merge into one prioritized brief"
 }
 
-// Background — notified on completion; wait/status still work
-{ task: "Audit dependency licenses", model: routeModel, async: true }
+// Background: notified on completion; wait/status still work
+{ task: "Audit dependency licenses", async: true }
 { action: "status", id: "abc123" }
 { action: "wait", id: "abc123" }           // interruptible; does not cancel
 { action: "cancel", id: "abc123" }
@@ -45,69 +45,102 @@ const routeModel = "<exact model from current modelPolicy route>";
 // subagent_wait { id: "abc123", timeout_ms?: number }
 
 // Worktree loop
-{ task: "Implement feature A", model: routeModel, profile: "general", isolation: "worktree" }
+{ task: "Implement feature A", profile: "general", isolation: "worktree" }
 { action: "diff", id: "abc123", index: 1 }
 { action: "apply", id: "abc123", index: 1 }
 { action: "discard", id: "abc123", index: 1 }
 
-// Dry-run validation + resolved plan (no spawn)
-// plan is a dry-run, but every task still needs the policy-routed model.
-{ action: "plan", tasks: [{ task: "…", model: routeModel, isolation: "worktree" }] }
+// Dry-run validation + resolved plan (no spawn).
+// plan calls Jev and incurs selector fees, then a later dispatch selects again.
+{ action: "plan", tasks: [{ task: "…", isolation: "worktree" }] }
 ```
 
 ## Profiles
 
 | Profile   | Tools                                                     | Writes                                      |
 | --------- | --------------------------------------------------------- | ------------------------------------------- |
-| `explore` | read/search/ls (+safe) + Pi context tools                | no project-file writes                      |
+| `explore` | locally permitted read-only tools + Pi context tools      | no project-file writes                      |
 | `review`  | same as explore                                           | no project-file writes                      |
-| `general` | inherited active tools + Pi context tools                | yes if tools include bash/edit/write        |
+| `general` | Jev chooses from the full available locally permitted catalog + Pi context tools | yes if the selected tools include bash/edit/write |
+
+Jev picks individual tool names, not a capability bundle. Candidates come from
+the full available locally permitted catalog, not from agent `tools` defaults and
+not from only the parent's active tools. An explicit `tools` list is a ceiling,
+explore/review stay read-only regardless of the answer, and an empty selection
+never means "all tools".
 
 For Pi children, `new_context`, `get_context_remaining`, `history`, and
-`notes` are control-plane tools. When available in the parent they remain in
-the child allowlist—even if a narrower tool list was requested—so Pi's remote
-`contextManagement` can stay active. They may update context notes/window
-state, but never grant `bash`, `edit`, or `write` access.
+`notes` are added locally when the parent exposes them, so the selector never
+asks about them. They are control-plane tools: they may update context
+notes/window state, but never grant `bash`, `edit`, or `write` access. Route
+metadata reports them as local additions.
+
+The finalized tool subset is passed to the child as Pi's `--tools` allowlist
+(`--no-tools` for a true empty set). Pi 0.86.0 is the verified baseline for
+built-in, extension and late-registered tool enforcement; an unsupported host is
+refused rather than silently weakened.
 
 Parallel write-capable tasks sharing one checkout are rejected unless each uses
 `isolation: "worktree"`, a distinct `cwd`, or `allow_shared_writes: true`.
 
 ## Backends
 
-`backend: "pi" | "codex" | "claude"` (default `pi`). Unsupported combinations are
-**refused**, not silently degraded:
-
-|                          | pi             | codex                  | claude         |
-| ------------------------ | -------------- | ---------------------- | -------------- |
-| `max_cost`               | yes            | refused (tokens only)  | yes            |
-| read-only profile        | tool allowlist | OS sandbox             | tool allowlist |
-| steering / grace wrap-up | yes            | no                     | no             |
-| `context: "fork"`        | yes            | refused                | yes            |
-| `thinking`               | yes            | no                     | no             |
-| `output_schema`          | yes            | yes                    | yes            |
+New dispatch is Pi-only. `backend: "codex"` or `backend: "claude"` on new work
+is **refused** before any selector or provider work, including a backend
+inherited from agent frontmatter, and is never silently switched to Pi. Existing
+Codex/Claude runs remain manageable through `status`/`wait`/`cancel`/`steer`/
+`diff`/`apply`/`discard`.
+
+Another provider's execution model is still eligible through Pi when the user
+lists it in their candidate configuration. Unsupported combinations inside the
+Pi path are **refused**, not silently degraded:
+
+|                          | pi             |
+| ------------------------ | -------------- |
+| `max_cost`               | yes (provider-reported execution only; not selector currency) |
+| read-only profile        | tool allowlist |
+| steering / grace wrap-up | yes            |
+| `context: "fork"`        | yes            |
+| `thinking`               | yes            |
+| `output_schema`          | yes            |
 
 ## Budgets and safety
 
 - Prefer `max_turns`, `max_cost`, and/or `timeout_ms` on long or write-capable runs.
+  `timeout_ms` is absolute: local preflight, Jev selection, setup, queue and
+  runtime all count against it.
 - `output_schema` asks the child for a fenced `json:result` block (one repair round).
-- `context: "fork"` continues from a fork of the parent session (pi/claude).
-- Do not poll `status` in a tight loop — use `wait` / `subagent_wait`, or let the
+- `context: "fork"` continues from a fork of the parent session.
+- Do not poll `status` in a tight loop. Use `wait` / `subagent_wait`, or let the
   completion notification arrive for `async: true` runs.
 - Point the user at `/subagents` for the live inspector and `/subagent-cost` for
-  the root / subagent / combined ledger.
-
-## Model policy
-
-Every new task must pass a `model` that exactly matches the current
-`modelPolicy` mapping in `~/.pi/subagent.json`; agent frontmatter,
-`taskDefaults.model`, and parent-session model inheritance are ignored. An
-agent route replaces the default route, and configured fallback order is
-immutable. Omit `fallback_models` to use the route; if supplied, it must match
-exactly. An optional route `thinking` value is an opaque Pi thinking-level
-string; common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`,
-and `max`, but model-specific values are passed through unchanged. It is a
-default; explicit task, agent, and profile `taskDefaults.thinking` values
-override it. Management actions do not require model. The extension re-reads
-this policy on each dispatch and injects it into
-the parent prompt. If the policy is missing or invalid, management remains
-available but new spawns and synthesis are rejected.
+  the root / subagent / routing / combined ledger. Routing cost is reported as
+  unreported (tokens only, no currency).
+
+## Routing
+
+Omit `model` and `fallback_models` on every new call: both are legacy fields,
+and an explicit value is rejected rather than bypassing selection. Jev chooses
+one execution model from the user's dedicated candidate list plus an individual
+include/exclude decision per eligible tool. The local policy then re-validates
+the answer: unknown or unsafe tools cannot launch, explore/review stay read-only,
+and management actions need no routing config or credential.
+
+There are no emergency or fallback models, and low confidence is accepted rather
+than treated as a threshold. A Jev timeout or API failure stops the affected new
+dispatch with an actionable error; existing runs stay queryable and cancellable.
+Transient child failures retry the already selected model and tool set within the
+original deadline, up to `max_retries`; a quality failure never reselects.
+
+An optional candidate `thinking` value is an opaque Pi thinking-level string;
+common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and
+`max`, but model-specific values are passed through unchanged. It is a default:
+explicit task, agent, and profile `taskDefaults.thinking` values override it.
+The extension re-reads `jevRouting` on each dispatch and injects non-secret
+routing guidance into the parent prompt. The user stores the TypeSafe credential
+in `jevRouting.apiKey` in the private `~/.pi/subagent.json`; do not read, display
+or copy the key into task text, prompts or output. Legacy `apiKeyEnv` is rejected
+with migration guidance; there is no environment fallback. If the config or key
+is missing or invalid, management remains available but new spawns, `/btw`, plan,
+resume, fork and synthesis are rejected. This config-file credential contract ships in
+npm 0.10.0; published npm 0.9.0 uses the old environment mechanism.

package/src/backends/pi.ts

@@ -1,94 +1,164 @@
-/**
- * Pi backend — the original and default. Spawns `pi --mode rpc` and speaks
- * Pi's documented JSON event stream over stdio.
- *
- * This is a straight extraction of the logic that lived inline in
- * `ChildRunner.run()`; behavior is unchanged. It is the only backend that
- * supports every capability, because the protocol was designed for it.
- */
-
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { BackendAdapter, BackendCapabilities, BackendInvocation, BackendLaunchContext, BackendParser } from "../backend.js";
-import { ProtocolParser } from "../protocol.js";
-import { schemaContract } from "../structured.js";
-import type { TaskSpec } from "../types.js";
-
-const PI_CAPABILITIES: BackendCapabilities = {
-  steer: true,
-  gracefulWrapUp: true,
-  costReporting: true,
-  resume: true,
-  fork: true,
-  toolRestriction: true,
-  thinking: true,
-  outputSchema: true,
-};
-
-export class PiBackend implements BackendAdapter {
-  readonly name = "pi" as const;
-  readonly capabilities = PI_CAPABILITIES;
-
-  async buildInvocation(spec: TaskSpec, context: BackendLaunchContext): Promise<BackendInvocation> {
-    // RPC mode keeps a live stdin command channel so steering messages can be
-    // injected mid-run. The event stream on stdout is a superset of json mode.
-    const args = ["--mode", "rpc", "--session-dir", context.sessionDir];
-    if (spec.forkResume && spec.resume) args.push("--fork", spec.resume);
-    else if (spec.resume) args.push("--session", spec.resume);
-    else if (spec.contextFork) {
-      // Context fork: the child starts from a real branched copy of the
-      // parent conversation, then receives the task as its next prompt.
-      // Fail fast rather than silently degrading to a fresh session.
-      if (!spec.parentSessionFile) {
-        throw new Error("context:'fork' requires a persisted parent session (none available). Save the session or use context:'fresh'.");
-      }
-      await fs.access(spec.parentSessionFile).catch(() => {
-        throw new Error(`context:'fork' failed: parent session file ${spec.parentSessionFile} is not readable.`);
-      });
-      args.push("--fork", spec.parentSessionFile);
-    }
-    if (spec.model) args.push("--model", spec.model);
-    if (spec.thinking) args.push("--thinking", spec.thinking);
-    if (spec.tools !== undefined) {
-      const tools = spec.tools.filter((tool) => tool !== "subagent");
-      if (tools.length === 0) args.push("--no-tools");
-      else args.push("--tools", tools.join(","));
-    }
-    // Persona/system prompt first, structured-output contract last (highest salience).
-    const appendPrompt = [spec.systemPrompt?.trim(), spec.outputSchema ? schemaContract(spec.outputSchema) : undefined]
-      .filter(Boolean)
-      .join("\n\n");
-    const cleanupDirs: string[] = [];
-    if (appendPrompt) {
-      const tempPromptDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-subagent-prompt-"));
-      cleanupDirs.push(tempPromptDir);
-      const promptPath = path.join(tempPromptDir, "system-prompt.md");
-      await fs.writeFile(promptPath, appendPrompt, { encoding: "utf8", mode: 0o600 });
-      args.push("--append-system-prompt", promptPath);
-    }
-
-    const invocation = context.getPiCommand(args);
-    return { command: invocation.command, args: invocation.args, cleanupDirs };
-  }
-
-  createParser(): BackendParser {
-    return new ProtocolParser();
-  }
-
-  steerCommand(message: string): unknown {
-    return { type: "steer", message };
-  }
-
-  promptCommand(message: string): unknown {
-    return { type: "prompt", message };
-  }
-
-  uiCancelCommand(id: string): unknown {
-    return { type: "extension_ui_response", id, cancelled: true };
-  }
-
-  stateCommand(): unknown {
-    return { type: "get_state" };
-  }
-}
+/**
+ * Pi backend — the original and default. Spawns `pi --mode rpc` and speaks
+ * Pi's documented JSON event stream over stdio.
+ *
+ * This is a straight extraction of the logic that lived inline in
+ * `ChildRunner.run()`; behavior is unchanged. It is the only backend that
+ * supports every capability, because the protocol was designed for it.
+ */
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { BackendAdapter, BackendCapabilities, BackendInvocation, BackendLaunchContext, BackendParser } from "../backend.js";
+import { ProtocolParser } from "../protocol.js";
+import { schemaContract } from "../structured.js";
+import type { TaskSpec } from "../types.js";
+import {
+  PREFLIGHT_MANIFEST_ENV,
+  PREFLIGHT_MANIFEST_SCHEMA,
+  createPreflightNonce,
+  startupFailure,
+  type PreflightManifest,
+} from "../startup-check.js";
+
+/** Nested dispatch tools whose loaded source the startup check must verify. */
+const NESTED_DISPATCH_TOOLS = ["subagent", "subagent_wait"] as const;
+
+const PI_CAPABILITIES: BackendCapabilities = {
+  steer: true,
+  gracefulWrapUp: true,
+  costReporting: true,
+  resume: true,
+  fork: true,
+  toolRestriction: true,
+  thinking: true,
+  outputSchema: true,
+};
+
+export class PiBackend implements BackendAdapter {
+  readonly name = "pi" as const;
+  readonly capabilities = PI_CAPABILITIES;
+
+  async buildInvocation(spec: TaskSpec, context: BackendLaunchContext): Promise<BackendInvocation> {
+    // A Jev-routed spec requires the provider-free startup check before the real task
+    // prompt: Pi silently drops unknown `--tools` names, so parent catalog knowledge is
+    // not proof of what the child actually loaded.
+    const routed = spec.routing !== undefined;
+    if (routed) {
+      if (!spec.model?.trim()) {
+        throw startupFailure(
+          "model_missing",
+          "A routed subagent task must carry the Jev-selected execution model.",
+        );
+      }
+      if (!Array.isArray(spec.tools)) {
+        throw startupFailure(
+          "tools_missing",
+          "A routed subagent task must carry the finalized tool allowlist so the child's active set can be verified.",
+        );
+      }
+    }
+
+    // RPC mode keeps a live stdin command channel so steering messages can be
+    // injected mid-run. The event stream on stdout is a superset of json mode.
+    const args = ["--mode", "rpc", "--session-dir", context.sessionDir];
+    if (spec.forkResume && spec.resume) args.push("--fork", spec.resume);
+    else if (spec.resume) args.push("--session", spec.resume);
+    else if (spec.contextFork) {
+      // Context fork: the child starts from a real branched copy of the
+      // parent conversation, then receives the task as its next prompt.
+      // Fail fast rather than silently degrading to a fresh session.
+      if (!spec.parentSessionFile) {
+        throw new Error("context:'fork' requires a persisted parent session (none available). Save the session or use context:'fresh'.");
+      }
+      await fs.access(spec.parentSessionFile).catch(() => {
+        throw new Error(`context:'fork' failed: parent session file ${spec.parentSessionFile} is not readable.`);
+      });
+      args.push("--fork", spec.parentSessionFile);
+    }
+    if (spec.model) args.push("--model", spec.model);
+    if (spec.thinking) args.push("--thinking", spec.thinking);
+    // A routed task's finalized tools are already profile-filtered and include the
+    // mandatory Pi control-plane tools; the parent applies depth/spawn/profile gating
+    // before `subagent`/`subagent_wait` become candidates, so they are no longer
+    // stripped here. Unrouted (trusted SDK) callers keep the historical behaviour.
+    let toolList: string[] | undefined;
+    if (spec.tools !== undefined) {
+      toolList = routed ? [...new Set(spec.tools)] : spec.tools.filter((tool) => tool !== "subagent");
+      if (toolList.length === 0) args.push("--no-tools");
+      else args.push("--tools", toolList.join(","));
+    }
+    // Persona/system prompt first, structured-output contract last (highest salience).
+    const appendPrompt = [spec.systemPrompt?.trim(), spec.outputSchema ? schemaContract(spec.outputSchema) : undefined]
+      .filter(Boolean)
+      .join("\n\n");
+    const cleanupDirs: string[] = [];
+    try {
+    if (appendPrompt) {
+      const tempPromptDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-subagent-prompt-"));
+      cleanupDirs.push(tempPromptDir);
+      const promptPath = path.join(tempPromptDir, "system-prompt.md");
+      await fs.writeFile(promptPath, appendPrompt, { encoding: "utf8", mode: 0o600 });
+      args.push("--append-system-prompt", promptPath);
+    }
+
+    let env: Record<string, string> | undefined;
+    if (routed) {
+      env = {};
+      const preflightExtension = fileURLToPath(new URL("../child-preflight.ts", import.meta.url));
+      await fs.access(preflightExtension).catch(() => {
+        throw startupFailure(
+          "preflight_extension_missing",
+          "The packaged child-preflight extension is missing, so the routed child's model and tools cannot be verified.",
+        );
+      });
+      const nestedTools = (toolList ?? []).filter((tool) => (NESTED_DISPATCH_TOOLS as readonly string[]).includes(tool));
+      const manifest: PreflightManifest = {
+        schema: PREFLIGHT_MANIFEST_SCHEMA,
+        nonce: createPreflightNonce(),
+        model: spec.model!,
+        tools: toolList ?? [],
+        ...(nestedTools.length > 0 ? { nestedTools } : {}),
+      };
+      const tempPreflightDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-subagent-preflight-"));
+      cleanupDirs.push(tempPreflightDir);
+      const manifestPath = path.join(tempPreflightDir, "preflight.json");
+      await fs.writeFile(manifestPath, JSON.stringify(manifest), { encoding: "utf8", mode: 0o600 });
+      // Bounded, non-secret expectation only: nonce, model ID, tool names, manifest path.
+      env[PREFLIGHT_MANIFEST_ENV] = manifestPath;
+      // Explicit `-e` pins the package-local extension. `--no-extensions` is deliberately
+      // NOT used: the child must still load the extensions that provide Jev-selected tools.
+      args.push("-e", preflightExtension);
+    }
+
+    const invocation = context.getPiCommand(args);
+    return { command: invocation.command, args: invocation.args, env, cleanupDirs };
+    } catch (error) {
+      // The runner cannot own cleanupDirs until an invocation is returned.
+      for (const dir of cleanupDirs) await fs.rm(dir, { recursive: true, force: true }).catch(() => { /* best-effort cleanup */ });
+      throw error;
+    }
+  }
+
+  createParser(): BackendParser {
+    return new ProtocolParser();
+  }
+
+  steerCommand(message: string): unknown {
+    return { type: "steer", message };
+  }
+
+  promptCommand(message: string): unknown {
+    return { type: "prompt", message };
+  }
+
+  uiCancelCommand(id: string): unknown {
+    return { type: "extension_ui_response", id, cancelled: true };
+  }
+
+  stateCommand(): unknown {
+    return { type: "get_state" };
+  }
+}

package/src/child-preflight.ts

@@ -0,0 +1,166 @@
+/**
+ * Private, package-local Pi extension that answers the routed startup handshake.
+ *
+ * Loaded explicitly by the Pi backend (`pi -e <this file>`) for Jev-routed child tasks
+ * only. It registers one nonce-specific command and, when invoked, reports the child's
+ * *actual* active model and tool set plus nested-tool provenance. The control side
+ * (`src/runner.ts`, via `src/startup-check.ts`) is what decides pass/fail — this file
+ * never grants anything and never trusts itself.
+ *
+ * Deliberate properties:
+ *
+ *  - Registers the command unconditionally: nesting/depth/spawn registration rules must
+ *    never disable the check.
+ *  - Reads only the temporary manifest path from the environment; the manifest carries
+ *    the nonce, the expected model ID and tool names — no task text, credentials or
+ *    paths from the parent conversation.
+ *  - Sends a bounded custom message with `triggerTurn: false` so no model turn starts.
+ *  - Uses no imports beyond this package's own handshake module and Node builtins.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  PREFLIGHT_ACK_SCHEMA,
+  PREFLIGHT_ACK_TYPE,
+  PREFLIGHT_MANIFEST_ENV,
+  parsePreflightManifest,
+  preflightCommandBase,
+} from "./startup-check.js";
+
+/** Minimal structural view of the child ExtensionContext we rely on. */
+interface PreflightCommandContext {
+  model?: { provider?: unknown; id?: unknown } | null;
+}
+
+interface PreflightToolMetadata {
+  name?: unknown;
+  sourceInfo?: { path?: unknown; source?: unknown } | null;
+}
+
+/** Minimal structural view of the Pi extension API we rely on. */
+interface PreflightApi {
+  registerCommand(
+    name: string,
+    options: { description?: string; handler: (args: string, ctx: PreflightCommandContext) => unknown },
+  ): void;
+  getActiveTools(): unknown;
+  getAllTools(): unknown;
+  sendMessage(
+    message: { customType: string; content: string; display?: boolean },
+    options?: { triggerTurn?: boolean },
+  ): unknown;
+}
+
+const HOST_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
+const HOST_SEARCH_DEPTH = 6;
+
+function safeActiveTools(pi: PreflightApi): string[] | null {
+  try {
+    const active = pi.getActiveTools();
+    return Array.isArray(active) && active.every((name) => typeof name === "string") ? active : null;
+  } catch {
+    return null;
+  }
+}
+
+function safeNestedProvenance(pi: PreflightApi, wanted: ReadonlySet<string>): Array<{
+  name: string;
+  path: string | null;
+  source: string | null;
+}> {
+  if (wanted.size === 0) return [];
+  try {
+    const all = pi.getAllTools();
+    if (!Array.isArray(all)) return [];
+    return (all as PreflightToolMetadata[])
+      .filter((tool) => typeof tool?.name === "string" && wanted.has(tool.name))
+      .map((tool) => ({
+        name: tool.name as string,
+        path: typeof tool.sourceInfo?.path === "string" ? tool.sourceInfo.path : null,
+        source: typeof tool.sourceInfo?.source === "string" ? tool.sourceInfo.source : null,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Best-effort host identification for the version gate. `PI_PACKAGE_DIR` is documented,
+ * and `process.argv[1]` is the CLI entry for Node-launched Pi. Anything unresolvable
+ * stays `null`; the behavioural handshake, not a guessed version, is the real gate.
+ */
+function readHostInfo(): { version: string | null; packageDir: string | null } {
+  const candidates: string[] = [];
+  try {
+    const override = process.env.PI_PACKAGE_DIR;
+    if (typeof override === "string" && override.trim()) candidates.push(override.trim());
+    const argv1 = process.argv[1];
+    if (typeof argv1 === "string" && argv1) {
+      let dir = path.dirname(path.resolve(argv1));
+      for (let depth = 0; depth < HOST_SEARCH_DEPTH; depth += 1) {
+        candidates.push(dir);
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    }
+  } catch {
+    /* fall through to unknown */
+  }
+  for (const dir of candidates) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.name === HOST_PACKAGE_NAME && typeof parsed.version === "string") {
+        return { version: parsed.version, packageDir: dir };
+      }
+    } catch {
+      /* not a package dir; keep looking */
+    }
+  }
+  return { version: null, packageDir: null };
+}
+
+export default function childPreflight(pi: PreflightApi): void {
+  const manifestPath = process.env[PREFLIGHT_MANIFEST_ENV];
+  if (typeof manifestPath !== "string" || manifestPath.length === 0) return;
+
+  let manifest;
+  try {
+    manifest = parsePreflightManifest(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return;
+  }
+  if (!manifest.ok) return;
+  const expectation = manifest.manifest;
+  const nestedWanted = new Set(expectation.nestedTools ?? []);
+
+  pi.registerCommand(preflightCommandBase(expectation.nonce), {
+    description: "private pi-subagent startup check",
+    handler: async (_args: string, ctx: PreflightCommandContext) => {
+      const model = ctx?.model
+        ? {
+            provider: typeof ctx.model.provider === "string" ? ctx.model.provider : undefined,
+            id: typeof ctx.model.id === "string" ? ctx.model.id : undefined,
+          }
+        : null;
+      const payload = {
+        schema: PREFLIGHT_ACK_SCHEMA,
+        nonce: expectation.nonce,
+        model,
+        tools: safeActiveTools(pi),
+        nestedToolsWithSource: safeNestedProvenance(pi, nestedWanted),
+        host: readHostInfo(),
+      };
+      pi.sendMessage(
+        {
+          customType: PREFLIGHT_ACK_TYPE,
+          content: JSON.stringify(payload),
+          display: false,
+        },
+        { triggerTurn: false },
+      );
+    },
+  });
+}