@henryqw/pi-subagent 16.0.2 → 17.0.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,8 +24,8 @@ 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.
-- 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.
+- 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. `prepareRoleLaunch` and `resolveConfiguredRoleLaunch` reject a nonempty `missingSkills` list before returning a prepared launch, so `delegate_task` does not start an under-capable child. Callers that bypass preparation must reject missing Skills before launch. 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.
 - User Role Markdown files and Subagent JSON config (`config/pi-subagent/config.json`) live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models/config.json`. Package-shipped built-in Roles (`implementer`, `reviewer`, `scout`) resolve from the package's own `examples/roles/` Markdown through the same parser and intentionally leave `modelClass` unset; same-named user files override built-ins for `delegate_task` and public API callers. The `synthesizer` Markdown remains the only optional inert sample.

package/README.md

@@ -15,6 +15,12 @@ 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 |
@@ -22,6 +28,7 @@ Run `/task-models` and configure the `fast` profile before delegating. Open `/ta
 | [`@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.
 
@@ -102,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.
 
@@ -157,12 +168,15 @@ 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.
 
 An unreadable or invalid Role fails loading fast. Duplicate Role names are rejected. A same-named user file overrides a built-in Role.
 
+A missing named Skill rejects `prepareRoleLaunch` and `resolveConfiguredRoleLaunch`. `delegate_task` returns a Role-specific workflow error and does not start a child.
+
 The package always provides these built-in Roles. Their files leave `modelClass` unset, so they use the configured `pi-subagent/delegateTask` assignment or declared default unless a call overrides it:
 
 | Role | Purpose | Isolation/use |
@@ -178,9 +192,12 @@ The package root includes these main exports:
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | `loadRoles` | function | Loads built-in and user Role definitions. |
+| `RoleName` / `parseRoleName` | type/function | Normalizes arbitrary Role names and rejects empty or C0/C1 control-character values. |
 | `resolveRoleSkills` | function | Resolves a Role's named Skills from Pi's effective registry. |
 | `resolveRoleLaunch` | function | Resolves a Role, route, and launch resources. |
+| `resolveConfiguredRoleLaunch` | function | Resolves a configured Role and its package resources with an explicit model class. Rejects missing Role Skills. |
 | `createRoleLaunch` | function | Builds launch arguments from a resolved route. |
+| `prepareRoleLaunch` / `finalizeRoleLaunch` | functions | Separates the stable Role prompt, exposes its immutable tool policy, and rejects missing Role Skills. |
 | `createEphemeralSubagentExecutor` | function | Creates the bounded child-process executor. |
 | Worktree helpers | functions | Create, inspect, finalize, and report child worktrees. |
 | `prepareExactReviewEvidence` | function | Create a bounded private base-to-tip patch with exact Git identity for caller-owned review. |
@@ -189,7 +206,7 @@ The executor works only inside the active Pi process. It does not discover or st
 
 `finalizeChildWorktree` returns the breaking `WorktreePayload` lifecycle union. `pruned` proves zero commits, a clean tree, and removed worktree and branch. `retained` contains measured `commits` and `dirty` values. `recovery` has an actionable `note` and only completed measurements. An omitted recovery measurement is unknown.
 
-See the [public Role and executor API](./docs/orchestration.md#public-role-and-executor-api) for contracts and a `prepare` example. Pass `modelClass` to `resolveRoleLaunch` to override a Role default.
+See the [public Role and executor API](./docs/orchestration.md#public-role-and-executor-api) for contracts and a `prepare` example. Pass `modelClass` to `resolveRoleLaunch` to override a Role default. `resolveConfiguredRoleLaunch` requires a model class and does not use Role or task defaults.
 
 ## Limits and recovery
 

package/dist/ephemeral.d.ts

@@ -44,6 +44,7 @@ export interface EphemeralSubagentRunInput {
 interface EphemeralSubagentResultBase {
     exitCode: number;
     output: string;
+    outputTruncated: boolean;
     stderr: string;
     stopReason?: string;
     errorMessage?: string;

package/dist/ephemeral.js

@@ -416,8 +416,13 @@ async function runPi(prepared, input, budget, invocation) {
         let lineEventType;
         let ignoreLine = false;
         let output = "";
+        let outputTruncated = false;
         const stderr = { prefix: "", totalBytes: 0 };
         const partial = { prefix: "", totalBytes: 0 };
+        const updateOutput = (nextOutput) => {
+            output = nextOutput;
+            outputTruncated = partial.totalBytes > MAX_OUTPUT_BYTES;
+        };
         let hasPartialText = false;
         let stopReason;
         let errorMessage;
@@ -532,6 +537,7 @@ async function runPi(prepared, input, budget, invocation) {
                     outcome,
                     exitCode,
                     output,
+                    outputTruncated,
                     stderr: boundedText(stderr),
                     stopReason,
                     errorMessage,
@@ -657,14 +663,16 @@ async function runPi(prepared, input, budget, invocation) {
                 const update = record.assistantMessageEvent;
                 if (update && typeof update === "object" && !Array.isArray(update)) {
                     const assistantEvent = update;
-                    if (assistantEvent.type === "text_start" && hasPartialText)
+                    if (assistantEvent.type === "text_start" && hasPartialText) {
                         appendBounded(partial, "\n");
+                        updateOutput(boundedText(partial));
+                    }
                     if (assistantEvent.type === "text_start")
                         hasPartialText = true;
                     if (assistantEvent.type === "text_delta" && typeof assistantEvent.delta === "string") {
                         hasPartialText = true;
                         appendBounded(partial, assistantEvent.delta);
-                        output = boundedText(partial);
+                        updateOutput(boundedText(partial));
                         invokeCallback("onUpdate", input.onUpdate, output);
                     }
                 }
@@ -697,7 +705,10 @@ async function runPi(prepared, input, budget, invocation) {
                 return;
             const text = assistantText(record.message);
             if (text !== undefined) {
-                output = capEphemeralSubagentOutput(text);
+                partial.prefix = "";
+                partial.totalBytes = 0;
+                appendBounded(partial, text);
+                updateOutput(capEphemeralSubagentOutput(text));
                 invokeCallback("onUpdate", input.onUpdate, output);
             }
             if (record.message && typeof record.message === "object" && !Array.isArray(record.message)) {

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 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 { 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_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;
@@ -14,14 +16,16 @@ export declare const DELEGATE_TASK: {
     readonly purpose: "Launch an isolated Pi subagent.";
     readonly defaultProfile: "fast";
 };
+export type RoleName = string;
 export interface Role {
-    name: string;
+    name: RoleName;
     description: string;
     modelClass?: ProfileName;
     tools: string[];
     isolation?: string;
     extensions: string[];
     skills: string[];
+    mcps?: string[];
     systemPrompt: string;
 }
 export interface PiLaunch {
@@ -33,6 +37,13 @@ export interface ResolvedRoleLaunch extends PiLaunch {
     thinkingLevel: ThinkingLevel;
     missingSkills: string[];
 }
+export interface PreparedRoleLaunch extends ResolvedRoleLaunch {
+    role: RoleName;
+    isolation?: "worktree";
+    tools: readonly string[];
+    systemPrompt: string;
+    promptArgIndex: number;
+}
 export interface CreateRoleLaunchInput {
     role: Role;
     route: ResolvedTaskRoute;
@@ -45,10 +56,16 @@ export interface ResolveRoleLaunchInput extends Omit<CreateRoleLaunchInput, "rou
     modelClass?: ProfileName;
     agentDir?: string;
 }
+export interface ResolveConfiguredRoleLaunchInput {
+    role: string;
+    modelClass: ProfileName;
+}
 export interface ResolvedRoleSkills {
     paths: string[];
     missing: string[];
 }
+/** Normalize one arbitrary Role name using the Role configuration contract. */
+export declare function parseRoleName(value: unknown, source?: string): RoleName;
 declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer", "scout"];
 export type BuiltinRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
 export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
@@ -60,5 +77,19 @@ export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
 export declare function loadRoles(agentDir?: string): Role[];
 export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string): ResolvedTaskRoute;
 export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;
+/** Resolve all enabled package resources selected by one Role's extension sources. */
+export declare function resolveRolePackageResources(role: Role, ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Promise<{
+    extensions: string[];
+    skills: string[];
+    prompts: string[];
+    themes: string[];
+}>;
 export declare function createRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: Pick<ExtensionContext, "isProjectTrusted">, input: CreateRoleLaunchInput): ResolvedRoleLaunch;
 export declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;
+/** Prepare a resolved or resolvable Role launch while keeping its system prompt out of argv. */
+export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): PreparedRoleLaunch;
+export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: CreateRoleLaunchInput): PreparedRoleLaunch;
+/** Resolve and prepare a configured Role with its package-owned resources. */
+export declare function resolveConfiguredRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveConfiguredRoleLaunchInput): Promise<PreparedRoleLaunch>;
+/** Restore the system prompt pair after a caller has prepared its launch argv. */
+export declare function finalizeRoleLaunch(prepared: PreparedRoleLaunch): ResolvedRoleLaunch;

package/dist/index.js

@@ -1,18 +1,22 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { DefaultPackageManager, getAgentDir, parseFrontmatter, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { extensionConfigDir } from "@henryqw/pi-config-store";
 import { hasDisplayControlCharacters } from "./display-text.js";
+import { selectRoleMcpConfig } from "./mcp-role.js";
 import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
+export { 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_POLICY_FLAG = "pi-subagent-role-mcps";
 export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
 export const CHILD_EXCLUDED_TOOL_NAMES = [
     "delegate_task",
@@ -23,6 +27,7 @@ export const CHILD_EXCLUDED_TOOL_NAMES = [
     "orchestrate_abort",
 ];
 export const CHILD_EXCLUDED_TOOLS = CHILD_EXCLUDED_TOOL_NAMES.join(",");
+const SYSTEM_PROMPT_FLAG = "--append-system-prompt";
 const CHILD_IDENTITY_POLICY = "You are a delegated Pi Subagent, not Main. Execute the assigned Role and task directly. Main-only delegation rules do not apply. Recursive delegation is unavailable; do not seek or invoke delegation tools.";
 export const DELEGATE_TASK = {
     id: "pi-subagent/delegateTask",
@@ -42,6 +47,10 @@ const cleanDisplayText = (value, field, source) => {
     }
     return cleanText(value, field, source);
 };
+/** Normalize one arbitrary Role name using the Role configuration contract. */
+export function parseRoleName(value, source = "Role") {
+    return cleanDisplayText(value, "name", source);
+}
 const stringList = (value, field, source) => {
     if (value === undefined)
         throw new Error(`${source}: ${field} is required.`);
@@ -62,6 +71,25 @@ 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 roleToolPolicy(role, additionalTools = []) {
+    return [...new Set([...role.tools, ...additionalTools].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
+}
+function namesMcpAdapter(extension) {
+    return extension.toLowerCase().split(/[\\/:@]+/).some((component) => component === "pi-mcp-adapter" || component.startsWith("pi-mcp-adapter."));
+}
+const FORBIDDEN_ROLE_PACKAGE_SOURCE_NAMES = ["pi-orchestrator", "pi-mcp-adapter"];
+function rejectForbiddenRolePackageSource(value, role) {
+    const components = value.toLowerCase().split(/[\\/:@]+/);
+    if (FORBIDDEN_ROLE_PACKAGE_SOURCE_NAMES.some((name) => components.some((component) => component === name || component.startsWith(`${name}.`)))) {
+        throw new Error(`Role ${role.name} extension explicitly names the forbidden ${FORBIDDEN_ROLE_PACKAGE_SOURCE_NAMES.join("/")} source: ${value}`);
+    }
+}
 function roleModelClass(value, source) {
     if (value === undefined)
         return;
@@ -70,6 +98,14 @@ function roleModelClass(value, source) {
     }
     return value;
 }
+function roleIsolation(value, source) {
+    if (value === undefined)
+        return;
+    if (cleanText(value, "isolation", source) !== "worktree") {
+        throw new Error(`${source}: isolation must be "worktree".`);
+    }
+    return "worktree";
+}
 // Built-in Roles resolved from the package-shipped Markdown relative to this module.
 const BUILTIN_ROLE_NAMES = ["implementer", "reviewer", "scout"];
 /** Single-file Role parser shared by built-in and user roles. */
@@ -82,18 +118,17 @@ function parseRoleFile(file, raw) {
         throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
     }
     const frontmatter = parsed.frontmatter;
-    const isolation = frontmatter.isolation === undefined ? undefined : cleanText(frontmatter.isolation, "isolation", file);
-    if (isolation !== undefined && isolation !== "worktree")
-        throw new Error(`${file}: isolation must be "worktree".`);
+    const isolation = roleIsolation(frontmatter.isolation, file);
     const modelClass = roleModelClass(frontmatter.modelClass, file);
     return {
-        name: cleanDisplayText(frontmatter.name, "name", file),
+        name: parseRoleName(frontmatter.name, file),
         description: cleanDisplayText(frontmatter.description, "description", file),
         ...(modelClass === undefined ? {} : { modelClass }),
         tools: stringList(frontmatter.tools, "tools", file),
         isolation,
         extensions: extensionList(frontmatter.extensions, file),
         skills: stringList(frontmatter.skills, "skills", file),
+        mcps: mcpList(frontmatter.mcps, file),
         systemPrompt: cleanText(parsed.body, "system prompt", file),
     };
 }
@@ -178,16 +213,50 @@ export function resolveRoleSkills(pi, role) {
     }
     return { paths, missing };
 }
+function packageManager(ctx) {
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(ctx.cwd, agentDir, { projectTrusted: ctx.isProjectTrusted() });
+    return new DefaultPackageManager({ cwd: ctx.cwd, agentDir, settingsManager });
+}
+/** Resolve all enabled package resources selected by one Role's extension sources. */
+export async function resolveRolePackageResources(role, ctx) {
+    const sources = role.extensions;
+    for (const source of sources)
+        rejectForbiddenRolePackageSource(source, role);
+    if (!sources.length)
+        return { extensions: [], skills: [], prompts: [], themes: [] };
+    const resolved = await packageManager(ctx).resolveExtensionSources([...sources]);
+    const resourceGroups = [resolved.extensions, resolved.skills, resolved.prompts, resolved.themes]
+        .map((resources) => resources.filter((resource) => resource.enabled));
+    const resolvedSources = new Set(resourceGroups.flat().map((resource) => resource.metadata.source));
+    const missing = sources.filter((source) => !resolvedSources.has(source));
+    if (missing.length)
+        throw new Error(`Role extension sources resolved no resources: ${missing.join(", ")}.`);
+    return {
+        extensions: resourceGroups[0].map((resource) => resource.path),
+        skills: resourceGroups[1].map((resource) => resource.path),
+        prompts: resourceGroups[2].map((resource) => resource.path),
+        themes: resourceGroups[3].map((resource) => resource.path),
+    };
+}
 export function createRoleLaunch(pi, ctx, input) {
+    return createRoleLaunchFromSkills(ctx, input, resolveRoleSkills(pi, input.role));
+}
+function createRoleLaunchFromSkills(ctx, input, skills) {
     const role = input.role;
-    const skills = resolveRoleSkills(pi, role);
-    const tools = [...new Set([...role.tools, ...(input.tools ?? [])].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
+    const mcps = mcpList(role.mcps, `Role ${role.name}`);
+    const tools = roleToolPolicy(role, input.tools);
+    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 +265,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)
@@ -205,7 +276,7 @@ export function createRoleLaunch(pi, ctx, input) {
     if (input.route.thinkingLevel)
         args.push("--thinking", input.route.thinkingLevel);
     args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
-    args.push("--append-system-prompt", `${CHILD_IDENTITY_POLICY}\n\n${cleanText(role.systemPrompt, "system prompt", `Role ${role.name}`)}`);
+    args.push(SYSTEM_PROMPT_FLAG, `${CHILD_IDENTITY_POLICY}\n\n${cleanText(role.systemPrompt, "system prompt", `Role ${role.name}`)}`);
     return {
         env,
         args,
@@ -224,3 +295,97 @@ export function resolveRoleLaunch(pi, ctx, input) {
             : resolveTaskRoute(ctx, selectedClass, agentDir),
     });
 }
+function stripRoleSystemPrompt(rawArgs) {
+    const indexes = rawArgs.flatMap((arg, index) => arg === SYSTEM_PROMPT_FLAG ? [index] : []);
+    if (indexes.length !== 1)
+        throw new Error(`Role launch must contain exactly one ${SYSTEM_PROMPT_FLAG} pair.`);
+    const promptArgIndex = indexes[0];
+    const systemPrompt = rawArgs[promptArgIndex + 1];
+    if (typeof systemPrompt !== "string" || !systemPrompt.includes("\n") || !systemPrompt.trim() || systemPrompt.includes("\0")) {
+        throw new Error(`Role ${SYSTEM_PROMPT_FLAG} value must be the exact multiline Role prompt.`);
+    }
+    const args = [...rawArgs.slice(0, promptArgIndex), ...rawArgs.slice(promptArgIndex + 2)];
+    if (args.includes(SYSTEM_PROMPT_FLAG) || args.includes(systemPrompt)) {
+        throw new Error("Sanitized Role argv must contain no prompt flag or raw Role prompt.");
+    }
+    return { args, systemPrompt, promptArgIndex };
+}
+function prepareResolvedRoleLaunch(roleDefinition, launch, additionalTools = []) {
+    const role = parseRoleName(roleDefinition.name);
+    const isolation = roleIsolation(roleDefinition.isolation, `Role ${role}`);
+    const tools = Object.freeze(roleToolPolicy(roleDefinition, additionalTools));
+    const { args, systemPrompt, promptArgIndex } = stripRoleSystemPrompt(launch.args);
+    return { ...launch, args, role, isolation, tools, systemPrompt, promptArgIndex };
+}
+function assertNoMissingRoleSkills(role, launch) {
+    if (!launch.missingSkills.length)
+        return;
+    throw new Error(`Role ${parseRoleName(role.name)} requires missing Skills: ${launch.missingSkills.join(", ")}.`);
+}
+export function prepareRoleLaunch(pi, ctx, input) {
+    const launch = "route" in input
+        ? createRoleLaunch(pi, ctx, input)
+        : resolveRoleLaunch(pi, ctx, input);
+    assertNoMissingRoleSkills(input.role, launch);
+    return prepareResolvedRoleLaunch(input.role, launch, input.tools);
+}
+/** Resolve and prepare a configured Role with its package-owned resources. */
+export async function resolveConfiguredRoleLaunch(pi, ctx, input) {
+    const roleName = parseRoleName(input.role);
+    if (input.modelClass === undefined)
+        throw new Error("Configured Role launch requires an explicit modelClass.");
+    const matches = loadRoles().filter((role) => role.name === roleName);
+    if (matches.length !== 1)
+        throw new Error(`Required configured Role ${roleName} is missing or ambiguous.`);
+    const role = matches[0];
+    if (role.mcps?.length) {
+        const { loadMcpConfig } = await import("pi-mcp-adapter/config");
+        selectRoleMcpConfig(loadMcpConfig(join(getAgentDir(), "mcp.json"), ctx.cwd), role.mcps);
+    }
+    const resources = await resolveRolePackageResources(role, ctx);
+    const effectiveRole = { ...role, extensions: resources.extensions };
+    const namedSkills = resolveRoleSkills(pi, effectiveRole);
+    const skills = {
+        ...namedSkills,
+        paths: [...new Set([...namedSkills.paths, ...resources.skills])],
+    };
+    const launch = createRoleLaunchFromSkills(ctx, {
+        role: effectiveRole,
+        route: resolveTaskRoute(ctx, input.modelClass),
+    }, skills);
+    assertNoMissingRoleSkills(effectiveRole, launch);
+    const additions = [
+        "--no-prompt-templates",
+        "--no-themes",
+        ...resources.prompts.flatMap((path) => ["--prompt-template", path]),
+        ...resources.themes.flatMap((path) => ["--theme", path]),
+    ];
+    const promptArgIndex = launch.args.indexOf(SYSTEM_PROMPT_FLAG);
+    if (promptArgIndex < 0)
+        throw new Error(`Resolved Role launch has no ${SYSTEM_PROMPT_FLAG}.`);
+    const args = [...launch.args];
+    args.splice(promptArgIndex, 0, ...additions);
+    return prepareResolvedRoleLaunch(effectiveRole, { ...launch, args });
+}
+/** Restore the system prompt pair after a caller has prepared its launch argv. */
+export function finalizeRoleLaunch(prepared) {
+    if (prepared.args.includes(SYSTEM_PROMPT_FLAG)) {
+        throw new Error(`Prepared Role launch already contains ${SYSTEM_PROMPT_FLAG}.`);
+    }
+    if (!Number.isSafeInteger(prepared.promptArgIndex)
+        || prepared.promptArgIndex < 0 || prepared.promptArgIndex > prepared.args.length) {
+        throw new Error("Prepared Role launch has an invalid system prompt insertion index.");
+    }
+    if (typeof prepared.systemPrompt !== "string" || !prepared.systemPrompt.trim() || prepared.systemPrompt.includes("\0")) {
+        throw new Error("Prepared Role launch has an invalid system prompt.");
+    }
+    const args = [...prepared.args];
+    args.splice(prepared.promptArgIndex, 0, SYSTEM_PROMPT_FLAG, prepared.systemPrompt);
+    return {
+        env: prepared.env,
+        args,
+        model: prepared.model,
+        thinkingLevel: prepared.thinkingLevel,
+        missingSkills: prepared.missingSkills,
+    };
+}

package/dist/mcp-role.d.ts

@@ -0,0 +1,7 @@
+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 selectRoleMcpConfig(config: RoleMcpConfig, allowlist: readonly string[]): RoleMcpConfig;

package/dist/mcp-role.js

@@ -0,0 +1,41 @@
+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 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/docs/adr/001-composable-ephemeral-execution.md

@@ -8,8 +8,11 @@ Generic callers compose workflows with JavaScript. Fan-out and fan-in use promis
 
 Resource Policy is split at launch preparation:
 
-- Role owns base tools, extensions, and Skill names.
+- Pi Subagent alone parses and resolves effective Roles.
+- Role owns base tools, extension capability bundles, Skill names, and an exact MCP server allowlist.
 - Caller may add explicit tools, extensions, and environment through `createRoleLaunch`.
+- `resolveConfiguredRoleLaunch` reloads the current Role, package resources, Skill registry, model route, and MCP policy for each launch.
+- The prepared launch keeps the Role system prompt separate from prompt-free argv until the caller's final launch boundary.
 - The executor receives the resulting Pi Launch and does not discover resources.
 
 Built-in `implementer`, `reviewer`, and `scout` Roles ship as Markdown in `examples/roles/` and use the same parser as user Roles. For generic delegation, a same-named user Role explicitly overrides a built-in. The package does not install, copy, or write user configuration.

package/docs/orchestration.md

@@ -103,15 +103,16 @@ 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.
+Role Skill names resolve through Main's effective Pi Skill registry at launch. Missing names are returned in `ResolvedRoleLaunch.missingSkills`. `prepareRoleLaunch` and `resolveConfiguredRoleLaunch` reject a nonempty list with `Role <name> requires missing Skills: ...` before returning a finalizable prepared launch. `delegate_task` reports that failure as a workflow error and does not start a child. Raw launch callers must reject `missingSkills` before launching.
 
 ### Role final-turn handoff
 
@@ -132,9 +133,12 @@ The package root exports the following mechanism-level APIs:
 | API | Responsibility |
 | --- | --- |
 | `loadRoles(agentDir?)` | Validate and load package-shipped built-in and user Role Markdown. |
+| `parseRoleName(value, source?)` / `RoleName` | Normalize one arbitrary Role name. Empty names and C0/C1 controls fail. |
 | `resolveRoleSkills(pi, role)` | Resolve Role Skill names from Pi's effective registry. |
 | `resolveRoleLaunch(pi, ctx, input)` | Resolve a caller-owned Model Task route, applying call-level then Role `modelClass` precedence, and produce `ResolvedRoleLaunch`. |
+| `resolveConfiguredRoleLaunch(pi, ctx, { role, modelClass })` | Reload one configured Role and package resources with a required explicit Model Class; reject missing Role Skills. |
 | `createRoleLaunch(pi, ctx, input)` | Produce the same launch from a caller-supplied resolved route. |
+| `prepareRoleLaunch` / `finalizeRoleLaunch` | Separate the stable Role prompt from argv, expose its immutable tool policy, and reject unavailable Role Skills. |
 | `createEphemeralSubagentExecutor(options)` | Queue and run one prepared no-session child per `run`. |
 | `createChildWorktree` / `finalizeChildWorktree` | Optional caller-managed worktree lifecycle; `createChildWorktree` can prepare exact metadata before allocation. |
 | `prepareExactReviewEvidence` | Validate Git identity and create a bounded private base-to-tip patch with exact `{base, tip, patchPath}` evidence. |
@@ -147,7 +151,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`.
+`parseRoleName` returns a trimmed `RoleName`. It accepts arbitrary names, not only the built-in Role catalog. 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`. `resolveConfiguredRoleLaunch` accepts a Role name and required `modelClass`. It does not use Role or task defaults. Its named and package Skill paths load once in that order. 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 prepared launch exposes an immutable, ordered, de-duplicated `tools` policy. It includes explicit caller tool additions. `prepareRoleLaunch` and `resolveConfiguredRoleLaunch` reject missing Skills before returning a prepared launch; `finalizeRoleLaunch` restores that prompt after callers add variable state.
 
 `createEphemeralSubagentExecutor` requires:
 
@@ -173,7 +177,8 @@ This JavaScript runs inside a Pi extension. `pi` is that extension's `ExtensionA
 ```js
 import {
   createEphemeralSubagentExecutor,
-  resolveRoleLaunch,
+  finalizeRoleLaunch,
+  prepareRoleLaunch,
 } from "@henryqw/pi-subagent";
 import { registerModelTask } from "@henryqw/pi-task-models";
 
@@ -222,7 +227,7 @@ export function createRunRole(pi) {
       prepare: async () => {
         // prepare runs only after this delegation owns a FIFO permit.
         const ctx = latestContext();
-        const launch = resolveRoleLaunch(pi, ctx, {
+        const prepared = prepareRoleLaunch(pi, ctx, {
           role,
           task: MODEL_TASK,
           modelClass,
@@ -230,13 +235,7 @@ export function createRunRole(pi) {
           tools,
           env,
         });
-        if (launch.missingSkills.length && ctx.hasUI) {
-          ctx.ui.notify(
-            `Skipped unavailable Skills: ${launch.missingSkills.join(", ")}`,
-            "warning",
-          );
-        }
-        return { launch, task, cwd: cwd ?? ctx.cwd };
+        return { launch: finalizeRoleLaunch(prepared), task, cwd: cwd ?? ctx.cwd };
       },
     });
   }

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,20 @@
+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 {
+	parseRoleMcpAllowlist,
+	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",
+	});
+	const allowlist = parseRoleMcpAllowlist(roleMcpFlagValue(process.argv, `--${ROLE_MCP_POLICY_FLAG}`));
+	const config = selectRoleMcpConfig(loadMcpConfig(join(getAgentDir(), "mcp.json"), process.cwd()), allowlist);
+	createMcpAdapter({ config })(pi);
+}

package/extensions/subagent.ts

@@ -16,13 +16,13 @@ import {
 	createChildWorktree,
 	createEphemeralSubagentExecutor,
 	DELEGATE_TASK,
-	createRoleLaunch,
 	DEFAULT_MAX_TURNS,
 	EphemeralSubagentError,
 	finalizeChildWorktree,
+	finalizeRoleLaunch,
 	formatDuration,
 	loadRoles,
-	resolveRoleLaunch,
+	prepareRoleLaunch,
 	WorktreeSetupError,
 	worktreeContextNote,
 	type EphemeralSubagentActivityEvent,
@@ -620,28 +620,19 @@ export default function subagentExtension(
 
 			// Resolve against the latest known session context after each FIFO permit.
 			const launchCtx = () => latestCtx ?? ctx;
-			const resolveLaunch = (role: Role, delegation: Delegation) => {
+			const prepareLaunch = (role: Role, delegation: Delegation) => {
 				const context = launchCtx();
-				const launch = resolveRoleLaunch(pi, context, {
+				const launch = prepareRoleLaunch(pi, context, {
 					role,
 					task: DELEGATE_TASK,
 					...(delegation.modelClass === undefined ? {} : { modelClass: delegation.modelClass }),
 				});
 				if (delegation.model === undefined) return launch;
-				return createRoleLaunch(pi, context, {
+				return prepareRoleLaunch(pi, context, {
 					role,
 					route: replaceRouteModel(context, delegation.model, launch),
 				});
 			};
-			const notifyMissingSkills = (role: Role, launch: ReturnType<typeof resolveLaunch>) => {
-				if (launch.missingSkills.length) {
-					ctx.ui.notify(
-						`Subagent role ${role.name} skipped unavailable Pi skills: ${launch.missingSkills.join(", ")}.`,
-						"warning",
-					);
-				}
-			};
-
 			const foregroundWorkflow: ParsedWorkflow = { ...workflow, background: false };
 			const entries = identifyWorkflowEntries(toolCallId, foregroundWorkflow);
 			const states = new Map<string, WorkflowTransportEntry>(entries.map((entry) => [entry.id, {
@@ -706,21 +697,18 @@ export default function subagentExtension(
 								// Route and effective Role resources resolve only after this entry's
 								// shared executor permit, before isolated state is created.
 								const role = reloadRole(entry.delegation.role);
-								const launch = resolveLaunch(role, entry.delegation);
-								notifyMissingSkills(role, launch);
-								model = modelReference(launch.model);
-								thinkingLevel = launch.thinkingLevel;
-								if (role.isolation === "worktree") {
+								const preparedLaunch = prepareLaunch(role, entry.delegation);
+								model = modelReference(preparedLaunch.model);
+								thinkingLevel = preparedLaunch.thinkingLevel;
+								if (preparedLaunch.isolation === "worktree") {
 									worktree = await createChildWorktree(ctx.cwd, entry.id, undefined, workflowSignal);
 								}
-								startWidgetItem(entry.id, entry.id, role.name, launch.model.id, launch.thinkingLevel, entry.delegation.name, ctx);
+								startWidgetItem(entry.id, entry.id, preparedLaunch.role, preparedLaunch.model.id, preparedLaunch.thinkingLevel, entry.delegation.name, ctx);
 								setState("running", "");
 								emitUpdate(emitToolUpdates);
-								return {
-									launch,
-									task: worktree ? `${entry.delegation.task}${worktreeContextNote(worktree)}` : entry.delegation.task,
-									cwd: worktree?.cwd ?? ctx.cwd,
-								};
+								const task = worktree ? `${entry.delegation.task}${worktreeContextNote(worktree)}` : entry.delegation.task;
+								const cwd = worktree?.cwd ?? ctx.cwd;
+								return { launch: finalizeRoleLaunch(preparedLaunch), task, cwd };
 							},
 						});
 						if (child.outcome === "failure") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "16.0.2",
+  "version": "17.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",