@henryqw/pi-subagent 16.1.0 → 17.0.0

package/CONTEXT.md

@@ -25,7 +25,7 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - 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. 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.
+- 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

@@ -175,6 +175,8 @@ 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 |
@@ -190,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. |
@@ -201,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,12 +1,11 @@
 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 { 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"];
@@ -17,8 +16,9 @@ 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[];
@@ -37,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;
@@ -49,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;
@@ -64,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,12 +1,13 @@
 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 { fingerprintRoleMcpConfig, parseRoleMcpAllowlist, roleMcpFlagValue, selectRoleMcpConfig } from "./mcp-role.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";
@@ -15,7 +16,6 @@ const MULTI_CODEX_EXTENSION = fileURLToPath(import.meta.resolve("@henryqw/pi-mul
 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 = [
@@ -27,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",
@@ -46,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.`);
@@ -72,9 +77,19 @@ function mcpList(value, source) {
         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;
@@ -83,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. */
@@ -95,12 +118,10 @@ 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),
@@ -192,11 +213,39 @@ 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 mcps = mcpList(role.mcps, `Role ${role.name}`);
-    const tools = [...new Set([...role.tools, ...(input.tools ?? [])].map((tool) => cleanText(tool, "tool", `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)) {
@@ -227,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,
@@ -246,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

@@ -4,5 +4,4 @@ export interface RoleMcpConfig {
 }
 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

@@ -1,4 +1,3 @@
-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.");
@@ -29,9 +28,6 @@ export function roleMcpFlagValue(args, flag) {
         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)

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

@@ -112,7 +112,7 @@ Every launch installs the Role tool policy. At launch, a package caller may add
 
 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
 
@@ -133,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. |
@@ -148,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, 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`.
+`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:
 
@@ -174,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";
 
@@ -223,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,
@@ -231,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/extensions/role-mcp.ts

@@ -3,9 +3,7 @@ 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,
@@ -16,16 +14,7 @@ export default function roleMcp(pi: ExtensionAPI): void {
 		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/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.1.0",
+  "version": "17.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",