@henryqw/pi-subagent 16.0.1 → 16.1.0

package/CONTEXT.md

@@ -15,7 +15,7 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - **Workflow**: generic orchestration of one or more Delegated Tasks; `delegate_task` owns its selected mode, while library callers compose executor runs in JavaScript.
 - **Workflow Mode**: `delegate_task` tool policy selected per call for `single`, `parallel`, or `chain` execution; not a Role property or executor API.
 - **Exact Review Evidence**: caller-requested private base-to-tip patch plus exact `{base, tip, patchPath}` identity prepared by `prepareExactReviewEvidence`.
-- **Resource Policy**: Role ownership of base tools, extensions, and Skill names, plus explicit caller additions of tools, extensions, and environment through `createRoleLaunch`.
+- **Resource Policy**: Role ownership of base tools, extensions, Skill names, and an exact MCP server allowlist, plus explicit caller additions of tools, extensions, and environment through `createRoleLaunch`.
 - **Pi Launch**: reusable `{env,args}` policy for one Role, resolved model route, explicit caller resources, and project trust.
 - **Ephemeral Executor**: mechanism that receives a prepared Pi Launch, runs one bounded Delegated Task in one no-session child process, and returns its result without discovering resources or composing a Workflow.
 
@@ -24,7 +24,7 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - One Delegated Task creates one ephemeral child process and no saved session. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns` is a safe integer >= 1; default 50), attempted continuation after the optional token handoff, or `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). A terminal turn 50 succeeds; attempted continuation rejects with `turn_limit`, accumulated usage, and bounded output. Optional `maxTokens` is a safe integer >= 1 with an unlimited default. It is one global executor default applied independently to every `delegate_task` child; it is neither a shared pool nor a per-call or environment option. Token accounting sums each completed assistant response's `Usage.totalTokens` once, matching the executor's aggregate `Usage`. A terminal response crossing the limit succeeds. A continuing crossing turn and its tools finish, then exactly one extra response turn is permitted. Further continuation rejects with typed `token_limit`, aggregate usage, and bounded last assistant output. This permits a crossing turn plus the final response to overshoot; it is not an exact hard cap. Raw executor launches enforce the extra-turn window but do not guarantee tools are disabled.
 - Every Role launch installs the shared tool policy. On a continuing token crossing, or the continuing penultimate `maxTurns` turn, the policy waits for `turn_end`, disables every tool, and steers one structured final report. This covers `delegate_task` and library Role launches made with the public launch API. With `maxTurns` set to 1, tools are disabled during `session_start`, and the sole provider turn is the response-only handoff. The fixed decision packet is the default, but exact task or Role output takes precedence and is returned alone. Terminal boundary responses get no handoff. Before the final boundary, the policy steers the fixed convergence warning once at each 80% threshold for completed turns, aggregate tokens when configured, and maximum runtime. It combines thresholds first due together and starts no timer or extra warning turn. Timeout, provider, or child-process failures can prevent a handoff. After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable in `~/.pi/agent/config/pi-subagent/config.json` (`maxTurns` defaults to 50; `maxTokens` defaults to unlimited; `timeout.idleMinutes`/`maxMinutes` default to 10/30).
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/config.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout.
-- Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
+- Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. Optional `mcps` defaults to an empty deny-all list. Non-empty `mcps` loads `pi-mcp-adapter` with an isolated in-memory config containing only those exact configured servers; every tool that those servers expose is active, unknown names fail before the first model turn, and direct adapter loading is rejected. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.
 - Route precedence is explicit call-level `modelClass` > Role `modelClass` > configured Model Task assignment or declared default. pi-subagent's local `pi-subagent/delegateTask` declaration defaults to `fast`. A direct model replaces only the selected route model and must honor its exact thinking level. Library callers select a Role plus their own Model Task declaration.
 - The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. A direct model never changes the route level and fails before launch if it cannot honor it. A missing local JSON config uses defaults quietly. Missing shared task-model config warns once per session because delegation needs a route. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.

package/README.md

@@ -15,12 +15,20 @@ pi install npm:@henryqw/pi-subagent
 
 Run `/task-models` and configure the `fast` profile before delegating. Open `/task-models` again and verify that `fast` no longer says `not configured`.
 
+Install `pi-mcp-adapter` when any Role declares an MCP server allowlist:
+
+```bash
+pi install npm:pi-mcp-adapter
+```
+
 ## Works with
 
 | Package | Relationship | Purpose |
 | --- | --- | --- |
 | [`@henryqw/pi-orchestrator`](https://pi.henry.wang/extensions/pi-orchestrator) | Consumer | Owns durable checked local implementation graphs. |
 | [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required | Supplies `fast`, `balanced`, `frontier`, and `fav` model routes. |
+| [`@henryqw/pi-process`](https://pi.henry.wang/packages/pi-process) | Required | Runs bounded captured Git commands. |
+| [`pi-mcp-adapter`](https://www.npmjs.com/package/pi-mcp-adapter) | Optional | Exposes only the MCP servers selected by a Role. |
 
 Routes come from `~/.pi/agent/config/pi-task-models/config.json`. It stores explicit task overrides. Missing shared model config warns once because delegation needs a route.
 
@@ -101,7 +109,11 @@ Its ordinary review loop is optional. Use it only when the caller or repository
 - Fix initial findings together. Validate repaired inputs once before focused re-review. Include the original findings and acceptance criteria, exact repaired-candidate evidence, and validation evidence.
 - Only `PASS` completes the loop. Surface and block on re-review findings or empty output. Retry empty output only when explicit caller policy requires one. A second empty result blocks. Do not add another round.
 
-A Role selects base tools, extensions, named Skills, instructions, and optional worktree isolation. Named Skills resolve from Main's effective Pi registry. Unavailable names warn and skip.
+A Role selects base tools, extensions, named Skills, MCP servers, instructions, and optional worktree isolation. Named Skills resolve from Main's effective Pi registry. Unavailable names warn and skip.
+
+Use `mcps` to allow configured MCP servers by exact name. An omitted or empty `mcps` list denies MCP access. Every tool exposed by an allowed server is available through `pi-mcp-adapter`.
+
+The adapter receives an isolated in-memory config containing only those servers. Unknown names fail before the first model turn. Loading `pi-mcp-adapter` directly through `extensions` is rejected because it would bypass the allowlist.
 
 Children disable ambient extension and Skill discovery. `tools: []` adds no base tools, but selected extension tools and caller tools still activate. `extensions: []` adds no Role extension bundle. `skills: []` adds no separately named Role Skills, but selected extension Skills still load.
 
@@ -156,6 +168,7 @@ Role Markdown files live beside the config file. They require frontmatter and a
 | `isolation` | Optional; only `worktree`. |
 | `extensions` | Required YAML array. Entries are absolute paths, `~/…`, `file://`, or `npm:`, `git:`, `github:`, `https?:`, or `ssh:` sources. |
 | `skills` | Required YAML array of non-empty Skill names. |
+| `mcps` | Optional YAML array of exact MCP server names. Omitted or `[]` denies MCP access. |
 | body | Required Markdown system prompt after the frontmatter. |
 
 A Role's `modelClass` is a default. A call-level class wins.

package/dist/git-process.d.ts

@@ -0,0 +1,8 @@
+export type GitResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type GitRunner = (args: string[], cwd: string, signal?: AbortSignal) => Promise<GitResult>;
+/** Run one ordinary Git command with bounded output; transport failures never throw. */
+export declare const runGit: GitRunner;

package/dist/git-process.js

@@ -0,0 +1,32 @@
+import { spawnBounded } from "@henryqw/pi-process";
+const GIT_TIMEOUT_MS = 30_000;
+const GIT_OUTPUT_LIMIT_BYTES = 1 * 1024 * 1024;
+const GIT_DIAGNOSTIC_LIMIT = 200;
+/** Run one ordinary Git command with bounded output; transport failures never throw. */
+export const runGit = async (args, cwd, signal) => {
+    try {
+        const result = await spawnBounded("git", ["--no-pager", ...args], {
+            cwd,
+            signal,
+            timeoutMs: GIT_TIMEOUT_MS,
+            stdoutLimitBytes: GIT_OUTPUT_LIMIT_BYTES,
+            stderrLimitBytes: GIT_OUTPUT_LIMIT_BYTES,
+        });
+        if (result.killed) {
+            return {
+                code: -1,
+                stdout: "",
+                stderr: result.stderr.trim().slice(0, GIT_DIAGNOSTIC_LIMIT) || "git was killed",
+            };
+        }
+        return { code: result.code, stdout: result.stdout, stderr: result.stderr };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            code: -1,
+            stdout: "",
+            stderr: reason.slice(0, GIT_DIAGNOSTIC_LIMIT) || "git execution failed",
+        };
+    }
+};

package/dist/index.d.ts

@@ -1,10 +1,13 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.ts";
+export { fingerprintRoleMcpConfig, parseRoleMcpAllowlist, roleMcpFlagValue, selectRoleMcpConfig, type RoleMcpConfig } from "./mcp-role.ts";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutionBudget, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
 export declare const PI_ORCHESTRATOR_PROCESS_LEASE = "PI_ORCHESTRATOR_PROCESS_LEASE";
+export declare const ROLE_MCP_CONFIG_SHA256_FLAG = "pi-subagent-role-mcp-config-sha256";
+export declare const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
 export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
 export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "ask_question", "orchestrate_execute", "orchestrate_status", "orchestrate_resume", "orchestrate_abort"];
 export declare const CHILD_EXCLUDED_TOOLS: string;
@@ -22,6 +25,7 @@ export interface Role {
     isolation?: string;
     extensions: string[];
     skills: string[];
+    mcps?: string[];
     systemPrompt: string;
 }
 export interface PiLaunch {

package/dist/index.js

@@ -6,13 +6,17 @@ import { extensionConfigDir } from "@henryqw/pi-config-store";
 import { hasDisplayControlCharacters } from "./display-text.js";
 import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
+export { fingerprintRoleMcpConfig, parseRoleMcpAllowlist, roleMcpFlagValue, selectRoleMcpConfig } from "./mcp-role.js";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, } from "./worktree.js";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
 const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
 const MULTI_CODEX_EXTENSION = fileURLToPath(import.meta.resolve("@henryqw/pi-multi-codex/extensions/multi-codex.ts"));
+const ROLE_MCP_EXTENSION = fileURLToPath(new URL("../extensions/role-mcp.ts", import.meta.url));
 const ROLE_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts", import.meta.url));
 export const PI_ORCHESTRATOR_PROCESS_LEASE = "PI_ORCHESTRATOR_PROCESS_LEASE";
+export const ROLE_MCP_CONFIG_SHA256_FLAG = "pi-subagent-role-mcp-config-sha256";
+export const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
 export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
 export const CHILD_EXCLUDED_TOOL_NAMES = [
     "delegate_task",
@@ -62,6 +66,15 @@ function validateExtension(extension, source) {
 function extensionList(value, source) {
     return stringList(value, "extensions", source).map((extension) => validateExtension(extension, source));
 }
+function mcpList(value, source) {
+    const names = stringList(value ?? [], "mcps", source);
+    if (new Set(names).size !== names.length)
+        throw new Error(`${source}: mcps contains duplicate MCP server names.`);
+    return names;
+}
+function namesMcpAdapter(extension) {
+    return extension.toLowerCase().split(/[\\/:@]+/).some((component) => component === "pi-mcp-adapter" || component.startsWith("pi-mcp-adapter."));
+}
 function roleModelClass(value, source) {
     if (value === undefined)
         return;
@@ -94,6 +107,7 @@ function parseRoleFile(file, raw) {
         isolation,
         extensions: extensionList(frontmatter.extensions, file),
         skills: stringList(frontmatter.skills, "skills", file),
+        mcps: mcpList(frontmatter.mcps, file),
         systemPrompt: cleanText(parsed.body, "system prompt", file),
     };
 }
@@ -181,13 +195,19 @@ export function resolveRoleSkills(pi, role) {
 export function createRoleLaunch(pi, ctx, input) {
     const role = input.role;
     const skills = resolveRoleSkills(pi, role);
+    const mcps = mcpList(role.mcps, `Role ${role.name}`);
     const tools = [...new Set([...role.tools, ...(input.tools ?? [])].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
+    const selectedExtensions = [...role.extensions, ...(input.extensions ?? [])]
+        .map((extension) => validateExtension(extension, `Role ${role.name}`));
+    if (selectedExtensions.some(namesMcpAdapter)) {
+        throw new Error(`Role ${role.name} must select MCP servers with mcps instead of loading pi-mcp-adapter directly.`);
+    }
     const extensions = [
-        ...role.extensions,
-        ...(input.extensions ?? []),
+        ...selectedExtensions,
         ...(CODEX_ALIAS.test(input.route.model.provider) ? [MULTI_CODEX_EXTENSION] : []),
+        ...(mcps.length ? [ROLE_MCP_EXTENSION] : []),
         ROLE_TOOLS_EXTENSION,
-    ].map((extension) => validateExtension(extension, `Role ${role.name}`));
+    ];
     const env = Object.fromEntries(Object.entries(input.env ?? {}).map(([key, value]) => {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
             throw new Error(`Invalid launch environment name: ${key}`);
@@ -196,6 +216,8 @@ export function createRoleLaunch(pi, ctx, input) {
         return [key, value];
     }));
     const args = ["--no-session", "--no-extensions", "--no-skills", "--exclude-tools", CHILD_EXCLUDED_TOOLS];
+    if (mcps.length)
+        args.push(`--${ROLE_MCP_POLICY_FLAG}`, JSON.stringify(mcps));
     for (const extension of new Set(extensions))
         args.push("--extension", extension);
     for (const skill of skills.paths)

package/dist/mcp-role.d.ts

@@ -0,0 +1,8 @@
+export interface RoleMcpConfig {
+    mcpServers: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+}
+export declare function parseRoleMcpAllowlist(value: unknown): string[];
+export declare function roleMcpFlagValue(args: readonly string[], flag: string): string | undefined;
+export declare function fingerprintRoleMcpConfig(config: RoleMcpConfig): string;
+export declare function selectRoleMcpConfig(config: RoleMcpConfig, allowlist: readonly string[]): RoleMcpConfig;

package/dist/mcp-role.js

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+export function parseRoleMcpAllowlist(value) {
+    if (typeof value !== "string")
+        throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
+    }
+    if (!Array.isArray(parsed)
+        || parsed.some((name) => typeof name !== "string" || !name.trim() || name.includes("\0"))) {
+        throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
+    }
+    const names = parsed.map((name) => name.trim());
+    if (new Set(names).size !== names.length)
+        throw new Error("The Role MCP policy flag contains duplicate MCP server names.");
+    return names;
+}
+export function roleMcpFlagValue(args, flag) {
+    const indexes = args.flatMap((arg, index) => arg === flag ? [index] : []);
+    if (indexes.length > 1)
+        throw new Error(`${flag} must appear at most once.`);
+    if (!indexes.length)
+        return;
+    const value = args[indexes[0] + 1];
+    if (value === undefined)
+        throw new Error(`${flag} requires a value.`);
+    return value;
+}
+export function fingerprintRoleMcpConfig(config) {
+    return createHash("sha256").update(JSON.stringify(config)).digest("hex");
+}
+export function selectRoleMcpConfig(config, allowlist) {
+    const missing = allowlist.filter((name) => !Object.hasOwn(config.mcpServers, name));
+    if (missing.length)
+        throw new Error(`Role MCP servers are not configured: ${missing.join(", ")}.`);
+    const mcpServers = Object.fromEntries(allowlist.map((name) => [name, config.mcpServers[name]]));
+    const { agentPluginPaths: _agentPluginPaths, hostConfigDiscovery: _hostConfigDiscovery, ...settings } = config.settings ?? {};
+    return {
+        mcpServers,
+        ...(Object.keys(settings).length ? { settings } : {}),
+    };
+}

package/dist/review-evidence.js

@@ -1,28 +1,20 @@
-import { execFile, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { inspectIndexFlags } from "./worktree.js";
+import { runGit as runCapturedGit } from "./git-process.js";
 const GIT_TIMEOUT_MS = 30_000;
 export const REVIEW_MAX_PATHS = 1_000;
 export const REVIEW_MAX_PATCH_BYTES = 512 * 1024;
 const STDERR_LIMIT = 200;
-const git = (args, cwd, signal) => new Promise((resolve) => {
-    execFile("git", ["--no-pager", ...args], { cwd, signal, timeout: GIT_TIMEOUT_MS }, (error, stdout, stderr) => {
-        resolve({
-            code: error ? (typeof error.code === "number" ? error.code : -1) : 0,
-            stdout: String(stdout),
-            stderr: String(stderr).slice(0, STDERR_LIMIT),
-        });
-    });
-});
 function failure(args, result) {
-    const detail = result.stderr.trim();
+    const detail = result.stderr.slice(0, STDERR_LIMIT).trim();
     return new Error(`git ${args.join(" ")} failed with exit ${result.code}${detail ? `: ${detail}` : ""}`);
 }
 async function runGit(args, cwd, signal) {
     signal?.throwIfAborted();
-    const result = await git(args, cwd, signal);
+    const result = await runCapturedGit(args, cwd, signal);
     signal?.throwIfAborted();
     if (result.code !== 0)
         throw failure(args, result);
@@ -126,7 +118,7 @@ async function assertCleanRegisteredWorktree(worktree, tip, signal) {
     if (await runGit(["status", "--porcelain=v1", "--untracked-files=all", "--ignore-submodules=none"], worktree, signal)) {
         throw new Error("Review evidence worktree is not clean.");
     }
-    const flags = await inspectIndexFlags(worktree, git, signal);
+    const flags = await inspectIndexFlags(worktree, runCapturedGit, signal);
     if (flags.failure)
         throw new Error(`Review evidence index inspection failed: ${flags.failure}`);
     if (flags.hidden)

package/dist/worktree.d.ts

@@ -1,3 +1,4 @@
+import { type GitRunner } from "./git-process.ts";
 export interface WorktreeInfo {
     path: string;
     cwd: string;
@@ -23,11 +24,6 @@ export type WorktreePayload = {
     commits?: number;
     dirty?: boolean;
 };
-export type GitRunner = (args: string[], cwd: string, signal?: AbortSignal) => Promise<{
-    code: number;
-    stdout: string;
-    stderr: string;
-}>;
 export declare class WorktreeSetupError extends Error {
     name: string;
     readonly worktree: WorktreeInfo;

package/dist/worktree.js

@@ -1,9 +1,8 @@
-import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync } from "node:fs";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-const GIT_TIMEOUT_MS = 30_000;
+import { runGit } from "./git-process.js";
 const WORKTREES_DIRNAME = ".worktrees";
 const BRANCH_NAMESPACE = "pi-subagent";
 export class WorktreeSetupError extends Error {
@@ -14,16 +13,6 @@ export class WorktreeSetupError extends Error {
         this.worktree = worktree;
     }
 }
-/** Runs git, capturing output; never throws on non-zero exit or spawn failure. */
-const runGit = (args, cwd, signal) => new Promise((resolve) => {
-    execFile("git", args, { cwd, timeout: GIT_TIMEOUT_MS, signal }, (error, stdout, stderr) => {
-        resolve({
-            code: error ? (typeof error.code === "number" ? error.code : -1) : 0,
-            stdout: String(stdout),
-            stderr: String(stderr),
-        });
-    });
-});
 const sanitizeShortId = (childId) => createHash("sha256").update(childId).digest("hex").slice(0, 24);
 const stripGitLineEnd = (value) => value.replace(/\r?\n$/, "");
 function hasRepositoryMarker(cwd) {
@@ -71,10 +60,15 @@ async function ensureLocalExclude(gitDir) {
  */
 export async function createChildWorktree(cwd, childId, run = runGit, signal, onPrepared) {
     const root = await run(["rev-parse", "--show-toplevel"], cwd, signal);
+    signal?.throwIfAborted();
+    if (root.code === -1)
+        throw new Error(`git rev-parse failed (${root.stderr.trim().slice(0, 200)})`);
     if (root.code !== 0) {
         signal?.throwIfAborted();
         const repository = await run(["-c", "safe.directory=*", "rev-parse", "--show-toplevel"], cwd, signal);
         signal?.throwIfAborted();
+        if (repository.code === -1)
+            throw new Error(`git rev-parse failed (${repository.stderr.trim().slice(0, 200)})`);
         if (repository.code !== 0 && !hasRepositoryMarker(cwd) && !process.env.GIT_DIR && !process.env.GIT_WORK_TREE)
             return undefined;
         throw new Error(`git rev-parse failed (${root.stderr.trim().slice(0, 200)})`); // dubious ownership, timeout, …
@@ -87,6 +81,9 @@ export async function createChildWorktree(cwd, childId, run = runGit, signal, on
         throw new Error(`git rev-parse --show-prefix failed (${prefix.stderr.trim().slice(0, 200)})`);
     const relativeCwd = stripGitLineEnd(prefix.stdout);
     const base = await run(["rev-parse", "HEAD"], repoRoot, signal);
+    signal?.throwIfAborted();
+    if (base.code === -1)
+        throw new Error(`git rev-parse HEAD failed (${base.stderr.trim().slice(0, 200)})`);
     if (base.code !== 0) {
         signal?.throwIfAborted();
         const head = await run(["symbolic-ref", "--quiet", "HEAD"], repoRoot, signal);

package/docs/orchestration.md

@@ -103,13 +103,14 @@ A Role file requires:
 - base tools: a YAML array; `tools: []` activates no base built-ins, while trusted selected extension tools still activate;
 - explicit extension paths or package sources: a YAML array; `extensions: []` selects no Role extension bundle;
 - additional effective Pi Skill names: a YAML array; `skills: []` selects no separately named Role Skills, while trusted selected extension Skills still load;
+- optional exact MCP server names: `mcps: []` or an omitted field denies MCP access, while allowed servers expose all their tools through `pi-mcp-adapter`;
 - system instructions;
 - optional `modelClass` default (`fast`, `balanced`, `frontier`, or `fav`); and
 - optional `isolation: worktree` for the tool layer.
 
 Every launch installs the Role tool policy. At launch, a package caller may add `tools`, `extensions`, and `env`; caller tools are unioned into the Role base list and loaded extension tools activate in every case. Caller `env` adds to or overrides the active Pi process environment for the child.
 
-Children start with ambient extension and Skill discovery disabled. Only explicit Role or caller extensions, resolved Skill paths, extension package resources, and required internal tool-policy or Codex adapters load. Loaded extension tools activate even when the Role base list is empty. Child-inappropriate parent tools are always excluded: `delegate_task`, `orchestrate_execute`, `orchestrate_status`, `orchestrate_resume`, `orchestrate_abort`, and `ask_question`. Explicit Role or caller tool names are verified against the final filtered registry after each provider extension completes `session_start`. Unavailable names fail before the first model turn and identify the missing names with provider guidance.
+Children start with ambient extension and Skill discovery disabled. Only explicit Role or caller extensions, resolved Skill paths, extension package resources, and required internal tool-policy, MCP, or Codex adapters load. A non-empty `mcps` list requires an installed `pi-mcp-adapter`. The MCP adapter receives an isolated in-memory config containing only the named servers. Unknown server names fail before the first model turn, and direct adapter loading through `extensions` is rejected. Loaded extension tools activate even when the Role base list is empty. Child-inappropriate parent tools are always excluded: `delegate_task`, `orchestrate_execute`, `orchestrate_status`, `orchestrate_resume`, `orchestrate_abort`, and `ask_question`. Explicit Role or caller tool names are verified against the final filtered registry after each provider extension completes `session_start`. Unavailable names fail before the first model turn and identify the missing names with provider guidance.
 
 Role Skill names resolve through Main's effective Pi Skill registry at launch. Missing names are returned in `ResolvedRoleLaunch.missingSkills`; `delegate_task` warns and skips them. Library callers must surface that warning themselves. Missing Skills do not block launch.
 
@@ -147,7 +148,7 @@ The package root exports the following mechanism-level APIs:
 | `retained` | `path`, `branch`, `commits`, `dirty` | Work was preserved. Both measurements are known. |
 | `recovery` | `path`, `branch`, `note`, optional `commits`, `dirty` | Recovery needs action. The note tells Main what to inspect. Present measurements completed; omitted values are unknown. |
 
-A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, optional `modelClass` and `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, a caller-owned `task` Model Task declaration, optional call-level `modelClass`, and optional caller `agentDir`, `extensions`, `tools`, and `env`. At extension load, callers invoke `registerModelTask(pi, task)` from `@henryqw/pi-task-models` once to expose that declaration in the shared control plane. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
+A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, a normalized `mcps` array, optional `modelClass` and `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, a caller-owned `task` Model Task declaration, optional call-level `modelClass`, and optional caller `agentDir`, `extensions`, `tools`, and `env`. At extension load, callers invoke `registerModelTask(pi, task)` from `@henryqw/pi-task-models` once to expose that declaration in the shared control plane. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
 
 `createEphemeralSubagentExecutor` requires:
 

package/examples/roles/implementer.md

@@ -11,6 +11,7 @@ tools:
   - ls
 extensions: []
 skills: []
+mcps: []
 isolation: worktree
 ---
 

package/examples/roles/reviewer.md

@@ -8,6 +8,7 @@ tools:
   - ls
 extensions: []
 skills: []
+mcps: []
 ---
 
 Review the supplied candidate read-only. Use only supplied requirements and named files or evidence; do not prepare Git or broaden discovery. If evidence is insufficient, say so and stop.

package/examples/roles/scout.md

@@ -8,6 +8,7 @@ tools:
   - ls
 extensions: []
 skills: []
+mcps: []
 ---
 
 Answer only the bounded discovery questions.

package/extensions/role-mcp.ts

@@ -0,0 +1,31 @@
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createMcpAdapter } from "pi-mcp-adapter";
+import { loadMcpConfig } from "pi-mcp-adapter/config";
+import {
+	fingerprintRoleMcpConfig,
+	parseRoleMcpAllowlist,
+	ROLE_MCP_CONFIG_SHA256_FLAG,
+	ROLE_MCP_POLICY_FLAG,
+	roleMcpFlagValue,
+	selectRoleMcpConfig,
+} from "@henryqw/pi-subagent";
+
+export default function roleMcp(pi: ExtensionAPI): void {
+	pi.registerFlag(ROLE_MCP_POLICY_FLAG, {
+		description: "Internal Pi Subagent Role MCP policy",
+		type: "string",
+	});
+	pi.registerFlag(ROLE_MCP_CONFIG_SHA256_FLAG, {
+		description: "Internal Pi Subagent Role MCP config fingerprint",
+		type: "string",
+	});
+	const allowlist = parseRoleMcpAllowlist(roleMcpFlagValue(process.argv, `--${ROLE_MCP_POLICY_FLAG}`));
+	const config = selectRoleMcpConfig(loadMcpConfig(join(getAgentDir(), "mcp.json"), process.cwd()), allowlist);
+	const expectedFingerprint = roleMcpFlagValue(process.argv, `--${ROLE_MCP_CONFIG_SHA256_FLAG}`);
+	if (expectedFingerprint !== undefined
+		&& (typeof expectedFingerprint !== "string" || fingerprintRoleMcpConfig(config) !== expectedFingerprint)) {
+		throw new Error("Role MCP config fingerprint drifted before launch.");
+	}
+	createMcpAdapter({ config })(pi);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "16.0.1",
+  "version": "16.1.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -63,6 +63,7 @@
   "dependencies": {
     "@henryqw/pi-config-store": "^1.0.0",
     "@henryqw/pi-multi-codex": "^1.0.0",
+    "@henryqw/pi-process": "^0.1.0",
     "@henryqw/pi-task-models": "^5.0.0"
   }
 }