@henryqw/pi-subagent 2.1.0 → 2.3.1

package/CONTEXT.md

@@ -0,0 +1,27 @@
+# Pi Subagent Context
+
+## Purpose
+
+Provide validated user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, and a `delegate_task` extension that runs one bounded task in one isolated child process.
+
+## Domain glossary
+
+- **Main**: Pi session delegating work.
+- **Subagent**: isolated Pi child process handling one task.
+- **Role**: user-owned Markdown profile defining name, description, system instructions, optional exact tool allowlist, extensions, and Skill names.
+- **Model Class**: `fast`, `balanced`, or `frontier`, assigned in shared task-model settings or overridden by Main from task complexity.
+- **Route**: configured model and thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback.
+- **Delegated Task**: one bounded work request sent from Main to one Role.
+- **Pi Launch**: reusable `{env,args}` policy for one Role, resolved model route, explicit caller resources, and project trust.
+- **Managed Subagent**: Pi agent hosted in a reconciled Herdr tab or pane; lifecycle orchestration remains with the caller.
+
+## Invariants
+
+- One Delegated Task creates one ephemeral child process and no saved session.
+- Ambient child extensions and Skills stay disabled; Role explicitly selects extension sources and named Skills. Pi loads Skills supplied by those extension packages or their resource discovery. Omitted Role tools use Pi's effective `defaultTools`; an explicit list sets base tools while loaded extension tools activate automatically.
+- Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.
+- Main selects Role and may override Model Class per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
+- The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
+- Role config lives only in user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`; repository roles do not execute.
+- Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
+- Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -1,6 +1,6 @@
 # `@henryqw/pi-subagent`
 
-Delegate one bounded task to one isolated Pi process. Main chooses the role and may override shared task-model effort per call.
+Delegate one bounded task to one isolated Pi process, or reuse validated Role launch and managed Herdr hosting for durable workers. Main chooses Role and may override shared task-model effort per call.
 
 ## Install
 
@@ -25,7 +25,7 @@ pi install npm:@henryqw/pi-subagent
 
 `modelClass` is `fast`, `balanced`, or `frontier`. Omitted class uses the shared `pi-subagent/delegateTask` assignment, which defaults to `balanced`. Primary route is resolved against current scoped text models; fallback is tried only before launch. If no route is usable, delegation rejects with `Run /task-models`. A started child is never retried.
 
-Each call starts one isolated child (`pi --mode json -p --no-session`). Ambient extensions and skills are off; only role resources load. Child uses the delegated working directory and Main's project approval. Abort kills the child process group. Streaming output is capped at 50 KiB. Unused JSON event types are discarded before payload buffering; consumed or unclassifiable events above 1 MiB fail delegation.
+Each call starts one isolated child (`pi --mode json -p --no-session`). Ambient extensions and Skills are off. Role/caller extensions load; those packages' tools and Skills auto-load, plus any extra `skills` names. Child uses the delegated working directory and Main's project approval. Abort kills the child process group. Streaming output is capped at 50 KiB. Unused JSON event types are discarded before payload buffering; consumed or unclassifiable events above 1 MiB fail delegation.
 
 TUI shows one row per Subagent with role, route, task, tokens, and elapsed time. Terminal rows drop after one second.
 
@@ -53,13 +53,41 @@ Do not edit files.
 | --- | --- | --- |
 | `name` | yes | Role selected by Main |
 | `description` | yes | Tells Main when to use the role |
-| `tools` | no | Omit for Pi `defaultTools`; a non-empty list is an exact allowlist; `[]` means none |
-| `extensions` | no | Absolute/`~/` paths or package sources. Repository-relative paths are rejected. |
-| `skills` | no | Effective Pi skill names, resolved from Main's registry |
+| `tools` | no | Omit for Pi defaults; when present, base tools are listed and every loaded Role/caller extension tool is added automatically. `[]` leaves extension tools only. |
+| `extensions` | no | Absolute/`~/` paths or package sources. Package-declared Skills and Pi `resources_discover` Skill paths load automatically. Repository-relative paths are rejected. |
+| `skills` | no | Additional effective Pi Skill names, resolved from Main's registry |
 | Markdown body | yes | Role system instructions |
 
 Missing skills warn and skip; they do not block delegation. No repo-controlled `.pi/agents` roles. No package-local model picker.
 
+## Library API
+
+Package root exports shared `Role` loading, Skill resolution, task-routed Pi launch, and generic managed Herdr lifecycle:
+
+```ts
+import {
+  loadRoles,
+  resolveRoleLaunch,
+  managedSubagentWorkspaceId,
+  reconcileManagedSubagentTab,
+  startManagedSubagent,
+} from "@henryqw/pi-subagent";
+
+const role = loadRoles().find(({ name }) => name === "reviewer")!;
+const launch = resolveRoleLaunch(pi, ctx, {
+  role,
+  taskId: "your-package/review",
+  extensions: [adapterExtensionPath],
+  tools: ["submit_review"],
+});
+const workspaceId = await managedSubagentWorkspaceId(ctx.cwd, mainPane, { execute });
+const host = { cwd: ctx.cwd, workspaceId };
+const tab = await reconcileManagedSubagentTab(host, { cwd: worktree, launch, label }, { execute });
+await startManagedSubagent(host, agentName, tab.paneId, launch, { execute });
+```
+
+`resolveRoleLaunch` uses shared task assignment and effective Pi registries. Caller tools extend Role base tools; Role and caller extension tools activate automatically. Omitted Role `tools` preserves Pi defaults. Generic host APIs contain no workflow prompts or durable state.
+
 ## Remove
 
 ```bash

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type HerdrExecutor } from "@henryqw/pi-herdr";
+import { type AvailableModel, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
+export interface Role {
+    name: string;
+    description: string;
+    tools?: string[];
+    extensions: string[];
+    skills: string[];
+    systemPrompt: string;
+}
+export interface PiLaunch {
+    env: Record<string, string>;
+    args: string[];
+}
+export interface ResolvedRoleLaunch extends PiLaunch {
+    model: AvailableModel;
+    thinkingLevel: ThinkingLevel;
+    missingSkills: string[];
+}
+export interface CreateRoleLaunchInput {
+    role: Role;
+    route: ResolvedTaskRoute;
+    extensions?: readonly string[];
+    tools?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+}
+export interface ResolveRoleLaunchInput extends Omit<CreateRoleLaunchInput, "route"> {
+    taskId: string;
+    agentDir?: string;
+}
+export interface ResolvedRoleSkills {
+    paths: string[];
+    missing: string[];
+}
+export declare const isProfileName: (value: unknown) => value is ProfileName;
+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;
+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;
+export interface ManagedSubagentHost {
+    cwd: string;
+    workspaceId: string;
+}
+export interface ManagedSubagentCommandOptions {
+    cwd: string;
+}
+export type ManagedSubagentExecutor = HerdrExecutor<ManagedSubagentCommandOptions>;
+export interface ManagedSubagentHostOptions {
+    execute: ManagedSubagentExecutor;
+    delay?: (milliseconds: number) => Promise<void>;
+}
+export interface ManagedSubagentTab {
+    tabId: string;
+    paneId: string;
+}
+export declare function launchEnvironmentArgs(launch: PiLaunch): string[];
+export declare function managedSubagentName(workspaceId: string, ...identity: string[]): string;
+export declare function managedSubagentWorkspaceId(cwd: string, mainPane: string, options: ManagedSubagentHostOptions): Promise<string>;
+/** Returns pane ID to Herdr status for agents owned by this workspace. */
+export declare function listManagedSubagents(host: ManagedSubagentHost, options: ManagedSubagentHostOptions): Promise<Map<string, string>>;
+export declare function createManagedSubagentTab(host: ManagedSubagentHost, cwd: string, launch: PiLaunch, label: string, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab>;
+export declare function reconcileManagedSubagentTab(host: ManagedSubagentHost, input: {
+    tabId?: string;
+    paneId?: string;
+    cwd: string;
+    launch: PiLaunch;
+    label: string;
+}, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab>;
+export declare function findManagedSubagentTab(host: ManagedSubagentHost, label: string, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab | undefined>;
+export declare function managedSubagentTabExists(host: ManagedSubagentHost, tabId: string, options: ManagedSubagentHostOptions): Promise<boolean>;
+export declare function reconcileManagedSubagentPane(host: ManagedSubagentHost, tabId: string, rootPaneId: string, cwd: string, launch: PiLaunch, label: string, options: ManagedSubagentHostOptions): Promise<string>;
+export declare function startManagedSubagent(host: ManagedSubagentHost, agent: string, pane: string, launch: PiLaunch, options: ManagedSubagentHostOptions, hooks?: {
+    beforeStart?: () => Promise<void>;
+    onStarted?: () => Promise<void>;
+}): Promise<"existing" | "started">;
+export declare function promptManagedSubagent(host: ManagedSubagentHost, agent: string, prompt: string | Record<string, unknown>, options: ManagedSubagentHostOptions): Promise<void>;
+export declare function retireManagedSubagentTab(host: ManagedSubagentHost, tabId: string, options: ManagedSubagentHostOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,395 @@
+import { createHash } from "node:crypto";
+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 { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode } from "@henryqw/pi-herdr";
+import { modelReference, orderedProfileRoutes, PROFILE_NAMES, readTaskModelsConfig, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
+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_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts", import.meta.url));
+const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+export const isProfileName = (value) => typeof value === "string" && PROFILE_NAMES.includes(value);
+const cleanText = (value, field, source) => {
+    if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
+        throw new Error(`${source}: ${field} must be non-empty text.`);
+    }
+    return value.trim();
+};
+const stringList = (value, field, source, required = false) => {
+    if (value === undefined) {
+        if (required)
+            throw new Error(`${source}: ${field} is required.`);
+        return [];
+    }
+    const values = typeof value === "string" ? value.split(",") : value;
+    if (!Array.isArray(values) || values.some((item) => typeof item !== "string" || !item.trim() || item.includes("\0"))) {
+        throw new Error(`${source}: ${field} must be an array of strings.`);
+    }
+    return values.map((item) => item.trim());
+};
+function validateExtension(extension, source) {
+    const value = cleanText(extension, "extension", source);
+    const packageSource = /^(?:npm|git|github|https?|ssh):/.test(value);
+    const userPath = isAbsolute(value) || value.startsWith("~/") || value.startsWith("~\\") || value.startsWith("file://");
+    if (!packageSource && !userPath) {
+        throw new Error(`${source}: extensions entries must be absolute paths or package sources.`);
+    }
+    return value;
+}
+function extensionList(value, source) {
+    return stringList(value, "extensions", source).map((extension) => validateExtension(extension, source));
+}
+export function loadRoles(agentDir = getAgentDir()) {
+    const dir = join(agentDir, "config", "pi-subagent");
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const roles = entries
+        .filter((entry) => entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink()))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((entry) => {
+        const file = join(dir, entry.name);
+        let parsed;
+        try {
+            parsed = parseFrontmatter(readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const frontmatter = parsed.frontmatter;
+        return {
+            name: cleanText(frontmatter.name, "name", file),
+            description: cleanText(frontmatter.description, "description", file),
+            tools: frontmatter.tools === undefined ? undefined : stringList(frontmatter.tools, "tools", file, true),
+            extensions: extensionList(frontmatter.extensions, file),
+            skills: stringList(frontmatter.skills, "skills", file),
+            systemPrompt: cleanText(parsed.body, "system prompt", file),
+        };
+    });
+    const names = new Set();
+    for (const role of roles) {
+        if (names.has(role.name))
+            throw new Error(`Duplicate Subagent role: ${role.name}.`);
+        names.add(role.name);
+    }
+    return roles;
+}
+export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
+    let config;
+    try {
+        config = readTaskModelsConfig(agentDir);
+    }
+    catch {
+        throw new Error("Couldn't read task model config. Run /task-models.");
+    }
+    return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName]);
+}
+function resolveConfiguredRoute(ctx, profileName, profile) {
+    if (!profile)
+        throw new Error(`No ${profileName} task model profile is configured. Run /task-models.`);
+    for (const route of orderedProfileRoutes(profile)) {
+        const resolved = resolveTaskModelRoute(ctx, route);
+        if (resolved)
+            return resolved;
+    }
+    throw new Error(`No usable ${profileName} task model route. Run /task-models.`);
+}
+export function resolveRoleSkills(pi, role) {
+    const skills = new Map(pi.getCommands()
+        .filter((command) => command.source === "skill")
+        .map((command) => [command.name, command.sourceInfo.path]));
+    const paths = [];
+    const missing = [];
+    for (const name of role.skills) {
+        const path = skills.get(`skill:${name}`);
+        if (path)
+            paths.push(path);
+        else
+            missing.push(name);
+    }
+    return { paths, missing };
+}
+export function createRoleLaunch(pi, ctx, input) {
+    const role = input.role;
+    const skills = resolveRoleSkills(pi, role);
+    const tools = role.tools === undefined
+        ? undefined
+        : [...new Set([...role.tools, ...(input.tools ?? [])].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
+    const extensions = [
+        ...role.extensions,
+        ...(input.extensions ?? []),
+        ...(CODEX_ALIAS.test(input.route.model.provider) ? [MULTI_CODEX_EXTENSION] : []),
+        ...(tools === undefined ? [] : [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}`);
+        if (typeof value !== "string" || value.includes("\0"))
+            throw new Error(`Invalid launch environment value: ${key}`);
+        return [key, value];
+    }));
+    const args = ["--no-session", "--no-extensions", "--no-skills"];
+    for (const extension of new Set(extensions))
+        args.push("--extension", extension);
+    for (const skill of skills.paths)
+        args.push("--skill", skill);
+    if (tools !== undefined)
+        args.push(`--${ROLE_TOOL_POLICY_FLAG}`, JSON.stringify(tools));
+    args.push("--model", modelReference(input.route.model));
+    if (input.route.thinkingLevel)
+        args.push("--thinking", input.route.thinkingLevel);
+    args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
+    args.push("--append-system-prompt", cleanText(role.systemPrompt, "system prompt", `Role ${role.name}`));
+    return {
+        env,
+        args,
+        model: input.route.model,
+        thinkingLevel: input.route.thinkingLevel,
+        missingSkills: skills.missing,
+    };
+}
+export function resolveRoleLaunch(pi, ctx, input) {
+    const taskId = cleanText(input.taskId, "task ID", "Role launch");
+    return createRoleLaunch(pi, ctx, {
+        ...input,
+        route: resolveConfiguredTaskRoute(ctx, taskId, input.agentDir),
+    });
+}
+export function launchEnvironmentArgs(launch) {
+    return Object.entries(launch.env).flatMap(([key, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== "string" || value.includes("\0")) {
+            throw new Error(`Invalid launch environment: ${key}`);
+        }
+        return ["--env", `${key}=${value}`];
+    });
+}
+export function managedSubagentName(workspaceId, ...identity) {
+    const parts = [nonEmptyString(workspaceId, "Herdr workspace id"), ...identity.map((part, index) => nonEmptyString(part, `Subagent identity ${index}`))];
+    if (!identity.length)
+        throw new Error("Managed Subagent identity is required");
+    return `subagent-${createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 23)}`;
+}
+export async function managedSubagentWorkspaceId(cwd, mainPane, options) {
+    const paneId = nonEmptyString(mainPane, "recorded main Herdr pane");
+    const pane = (await listPanes(cwd, options))
+        .map((entry, index) => object(entry, `Herdr pane ${index}`))
+        .find((entry) => entry.pane_id === paneId);
+    if (!pane)
+        throw new Error(`Recorded main Herdr pane is missing: ${paneId}`);
+    return nonEmptyString(pane.workspace_id, "recorded main Herdr workspace");
+}
+/** Returns pane ID to Herdr status for agents owned by this workspace. */
+export async function listManagedSubagents(host, options) {
+    const workspaceId = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const response = object(await createHerdrClient(options.execute).json(["agent", "list"], { cwd: host.cwd }), "Herdr agent list response");
+    const result = object(response.result, "Herdr agent list result");
+    return new Map(array(result.agents, "Herdr agents").flatMap((entry, index) => {
+        const agent = object(entry, `Herdr agent ${index}`);
+        if (nonEmptyString(agent.workspace_id, `Herdr agent ${index} workspace`) !== workspaceId)
+            return [];
+        return [[
+                nonEmptyString(agent.pane_id, `Herdr agent ${index} pane`),
+                nonEmptyString(agent.agent_status, `Herdr agent ${index} status`),
+            ]];
+    }));
+}
+export async function createManagedSubagentTab(host, cwd, launch, label, options) {
+    const response = await createHerdrClient(options.execute).json([
+        "tab", "create", "--workspace", nonEmptyString(host.workspaceId, "recorded Herdr workspace"), "--cwd", cwd,
+        ...launchEnvironmentArgs(launch), "--label", nonEmptyString(label, "Herdr tab label"), "--no-focus",
+    ], { cwd: host.cwd });
+    const result = object(object(response, "Herdr tab response").result, "Herdr tab result");
+    return {
+        tabId: nonEmptyString(object(result.tab, "Herdr tab").tab_id, "Herdr tab id"),
+        paneId: nonEmptyString(object(result.root_pane, "Herdr root pane").pane_id, "Herdr root pane id"),
+    };
+}
+export async function reconcileManagedSubagentTab(host, input, options) {
+    if (input.tabId && input.paneId && await managedSubagentTabExists(host, input.tabId, options)) {
+        return { tabId: input.tabId, paneId: input.paneId };
+    }
+    return await findManagedSubagentTab(host, input.label, options)
+        ?? await createManagedSubagentTab(host, input.cwd, input.launch, input.label, options);
+}
+export async function findManagedSubagentTab(host, label, options) {
+    const workspaceId = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const matches = (await listTabs(host.cwd, options))
+        .map((entry, index) => object(entry, `Herdr tab ${index}`))
+        .filter((tab, index) => nonEmptyString(tab.workspace_id, `Herdr tab ${index} workspace`) === workspaceId)
+        .filter((tab) => tab.label === label);
+    if (matches.length > 1)
+        throw new Error(`Multiple Herdr tabs match provisioning identity: ${label}`);
+    if (!matches.length)
+        return undefined;
+    const tabId = nonEmptyString(object(matches[0], "Herdr tab").tab_id, "Herdr tab id");
+    const panes = (await listPanes(host.cwd, options))
+        .filter((entry, index) => object(entry, `Herdr pane ${index}`).tab_id === tabId);
+    if (panes.length !== 1)
+        throw new Error(`Provisioned Herdr tab ${tabId} must contain exactly one root pane`);
+    return { tabId, paneId: nonEmptyString(object(panes[0], "Herdr pane").pane_id, "Herdr pane id") };
+}
+export async function managedSubagentTabExists(host, tabId, options) {
+    const expected = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const id = nonEmptyString(tabId, "Herdr tab id");
+    const tab = (await listTabs(host.cwd, options))
+        .map((entry, index) => object(entry, `Herdr tab ${index}`))
+        .find((entry) => entry.tab_id === id);
+    if (!tab)
+        return false;
+    const actual = nonEmptyString(tab.workspace_id, `Herdr tab ${id} workspace`);
+    if (actual !== expected)
+        throw new Error(`Herdr tab ${id} belongs to workspace ${actual}, expected initiating workspace ${expected}`);
+    return true;
+}
+export async function reconcileManagedSubagentPane(host, tabId, rootPaneId, cwd, launch, label, options) {
+    const tab = nonEmptyString(tabId, "Herdr tab id");
+    const workspace = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const ownerTab = (await listTabs(host.cwd, options))
+        .map((entry, index) => object(entry, `Herdr tab ${index}`))
+        .find((entry) => entry.tab_id === tab);
+    if (!ownerTab)
+        throw new Error(`Herdr tab is missing: ${tab}`);
+    const ownerWorkspace = nonEmptyString(ownerTab.workspace_id, `Herdr tab ${tab} workspace`);
+    if (ownerWorkspace !== workspace)
+        throw new Error(`Herdr tab ${tab} belongs to workspace ${ownerWorkspace}, expected initiating workspace ${workspace}`);
+    const root = nonEmptyString(rootPaneId, "Herdr root pane");
+    const panes = (await listPanes(host.cwd, options)).map((entry, index) => object(entry, `Herdr pane ${index}`));
+    const owner = panes.find((pane) => pane.pane_id === root);
+    if (!owner)
+        throw new Error(`Herdr root pane is missing: ${root}`);
+    if (owner.tab_id !== tab)
+        throw new Error(`Herdr root pane ${root} does not belong to tab ${tab}`);
+    const siblings = panes.filter((pane) => pane.tab_id === tab && pane.pane_id !== root);
+    const named = siblings.filter((pane) => pane.label === label);
+    if (named.length > 1)
+        throw new Error(`Multiple Herdr panes match provisioning identity: ${label}`);
+    if (named.length)
+        return nonEmptyString(named[0].pane_id, "Herdr Subagent pane id");
+    if (siblings.length > 1)
+        throw new Error(`Provisioned Herdr tab ${tab} has multiple Subagent panes`);
+    if (siblings.length)
+        return nonEmptyString(siblings[0].pane_id, "Herdr Subagent pane id");
+    const herdr = createHerdrClient(options.execute);
+    const response = await herdr.json([
+        "pane", "split", "--pane", root, "--direction", "right", "--cwd", cwd,
+        ...launchEnvironmentArgs(launch), "--no-focus",
+    ], { cwd: host.cwd });
+    const result = object(object(response, "Herdr pane response").result, "Herdr pane result");
+    const pane = nonEmptyString(object(result.pane, "Herdr Subagent pane").pane_id, "Herdr Subagent pane id");
+    await herdr.run(["pane", "rename", pane, nonEmptyString(label, "Herdr pane label")], { cwd: host.cwd });
+    return pane;
+}
+export async function startManagedSubagent(host, agent, pane, launch, options, hooks = {}) {
+    assertAgentName(agent);
+    const name = nonEmptyString(agent, "Herdr agent name");
+    const paneId = nonEmptyString(pane, "Herdr agent pane");
+    const existing = await getManagedSubagent(host, name, options);
+    if (existing) {
+        assertAgentPane(name, paneId, existing);
+        return "existing";
+    }
+    await hooks.beforeStart?.();
+    const arguments_ = ["agent", "start", name, "--kind", "pi", "--pane", paneId, "--", ...launch.args];
+    const herdr = createHerdrClient(options.execute);
+    for (let attempt = 1; attempt <= 5; attempt += 1) {
+        const result = await herdr.exec(arguments_, { cwd: host.cwd });
+        if (result.code === 0 && !result.killed) {
+            await hooks.onStarted?.();
+            return "started";
+        }
+        if (hasHerdrErrorCode(result, "agent_name_taken")) {
+            const raced = await getManagedSubagent(host, name, options);
+            if (!raced)
+                throw new Error(`Herdr agent ${name} reported agent_name_taken but could not be found; refusing to start a duplicate`);
+            assertAgentPane(name, paneId, raced);
+            return "existing";
+        }
+        if (!hasHerdrErrorCode(result, "agent_pane_busy") || attempt === 5) {
+            throw new Error(herdrCommandFailure(arguments_, result));
+        }
+        await (options.delay ?? delay)(250);
+    }
+    throw new Error(`Herdr agent ${name} could not be started`);
+}
+export async function promptManagedSubagent(host, agent, prompt, options) {
+    assertAgentName(agent);
+    const text = typeof prompt === "string" ? nonEmptyString(prompt, "Subagent prompt") : JSON.stringify(prompt);
+    await createHerdrClient(options.execute).run(["agent", "prompt", agent, text], { cwd: host.cwd });
+}
+export async function retireManagedSubagentTab(host, tabId, options) {
+    const id = nonEmptyString(tabId, "Herdr tab id");
+    try {
+        if (!(await managedSubagentTabExists(host, id, options)))
+            return;
+        await createHerdrClient(options.execute).run(["tab", "close", id], { cwd: host.cwd });
+    }
+    catch (error) {
+        if (!(await confirmsTabAbsent(host, id, options)))
+            throw error;
+    }
+}
+function assertAgentName(agent) {
+    if (!/^[a-z][a-z0-9_-]{0,31}$/.test(agent))
+        throw new Error(`Invalid Herdr agent name: ${agent}`);
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function array(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    return value;
+}
+function nonEmptyString(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    if (!value.trim() || value.includes("\0"))
+        throw new Error(`${label} must not be empty`);
+    return value;
+}
+async function listTabs(cwd, options) {
+    const response = await createHerdrClient(options.execute).json(["tab", "list"], { cwd });
+    return array(object(object(response, "Herdr tab list response").result, "Herdr tab list result").tabs, "Herdr tabs");
+}
+async function listPanes(cwd, options) {
+    const response = await createHerdrClient(options.execute).json(["pane", "list"], { cwd });
+    return array(object(object(response, "Herdr pane list response").result, "Herdr pane list result").panes, "Herdr panes");
+}
+async function getManagedSubagent(host, name, options) {
+    const arguments_ = ["agent", "get", name];
+    const result = await createHerdrClient(options.execute).exec(arguments_, { cwd: host.cwd });
+    if (result.code !== 0 || result.killed) {
+        if (hasHerdrErrorCode(result, "agent_not_found"))
+            return undefined;
+        throw new Error(herdrCommandFailure(arguments_, result));
+    }
+    const response = object(JSON.parse(result.stdout), "Herdr agent get response");
+    return object(object(response.result, "Herdr agent get result").agent, `Herdr agent ${name}`);
+}
+function assertAgentPane(name, expected, agent) {
+    const actual = typeof agent.pane_id === "string" ? agent.pane_id : "missing";
+    if (actual !== expected) {
+        throw new Error(`Herdr agent name collision for ${name}: expected pane ${expected}, found ${actual}; refusing to reuse or replace it`);
+    }
+}
+async function confirmsTabAbsent(host, tabId, options) {
+    try {
+        const result = await createHerdrClient(options.execute).exec(["tab", "get", tabId], { cwd: host.cwd });
+        return !result.killed && result.code !== 0 && hasHerdrErrorCode(result, "tab_not_found");
+    }
+    catch {
+        return false;
+    }
+}
+async function delay(milliseconds) {
+    await new Promise((done) => { setTimeout(done, milliseconds); });
+}

package/extensions/role-tools.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+
+function configuredTools(value: unknown): string[] | undefined {
+	if (value === undefined) return;
+	if (typeof value !== "string") throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+	}
+	if (!Array.isArray(parsed) || parsed.some((name) => typeof name !== "string" || !name.trim() || name.includes("\0"))) {
+		throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+	}
+	return [...new Set(parsed.map((name) => name.trim()))];
+}
+
+export default function roleTools(pi: ExtensionAPI): void {
+	pi.registerFlag(ROLE_TOOL_POLICY_FLAG, {
+		description: "Internal Pi Subagent Role tool policy",
+		type: "string",
+	});
+	pi.on("session_start", () => {
+		const selected = configuredTools(pi.getFlag(ROLE_TOOL_POLICY_FLAG));
+		if (!selected) return;
+		const extensionTools = pi.getAllTools()
+			.filter((tool) => !["builtin", "sdk", "inline"].includes(tool.sourceInfo.source))
+			.map((tool) => tool.name);
+		pi.setActiveTools([...new Set([...selected, ...extensionTools])]);
+	});
+}

package/extensions/subagent.ts

@@ -1,29 +1,15 @@
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, isAbsolute, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { type ExtensionAPI, type ExtensionContext, getAgentDir, parseFrontmatter, type Theme } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth, type TUI, visibleWidth } from "@earendil-works/pi-tui";
-import {
-	DEFAULT_TASK_ASSIGNMENTS,
-	modelReference,
-	orderedProfileRoutes,
-	PROFILE_NAMES,
-	readTaskModelsConfig,
-	resolveTaskModelRoute,
-	type ProfileName,
-	type ResolvedTaskRoute,
-} from "@henryqw/pi-task-models";
+import { modelReference, PROFILE_NAMES, type ProfileName } from "@henryqw/pi-task-models";
 import { Type } from "typebox";
+import { createRoleLaunch, isProfileName, loadRoles, resolveRoleLaunch, resolveTaskRoute } from "@henryqw/pi-subagent";
 
 const MODEL_CLASSES = PROFILE_NAMES;
 const SUBAGENT_TASK = "pi-subagent/delegateTask";
-const DEFAULT_MODEL_CLASS = DEFAULT_TASK_ASSIGNMENTS[SUBAGENT_TASK];
-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 MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
 const CONSUMED_JSON_EVENTS = new Set(["message_start", "message_update", "message_end"]);
@@ -35,14 +21,6 @@ const MAX_WIDGET_ROWS = 8;
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 type ModelClass = ProfileName;
-type Role = {
-	name: string;
-	description: string;
-	tools?: string[];
-	extensions: string[];
-	skills: string[];
-	systemPrompt: string;
-};
 type ChildResult = {
 	exitCode: number;
 	output: string;
@@ -61,27 +39,7 @@ type WidgetItem = {
 	removeAt?: number;
 };
 
-const isModelClass = (value: unknown): value is ModelClass =>
-	typeof value === "string" && MODEL_CLASSES.includes(value as ModelClass);
-const isNumberedCodexProvider = (provider: string): boolean => CODEX_ALIAS.test(provider);
-
-function resolveTaskRoute(ctx: ExtensionContext, modelClass?: ModelClass): ResolvedTaskRoute {
-	let config;
-	try {
-		config = readTaskModelsConfig();
-	} catch {
-		throw new Error("Couldn't read task model config. Run /task-models.");
-	}
-
-	const profileName = modelClass ?? config.tasks[SUBAGENT_TASK] ?? DEFAULT_MODEL_CLASS;
-	const profile = config.profiles[profileName];
-	if (!profile) throw new Error(`No ${profileName} task model profile is configured. Run /task-models.`);
-	for (const route of orderedProfileRoutes(profile)) {
-		const resolved = resolveTaskModelRoute(ctx, route);
-		if (resolved) return resolved;
-	}
-	throw new Error(`No usable ${profileName} task model route. Run /task-models.`);
-}
+const isModelClass = isProfileName;
 
 const cleanText = (value: unknown, field: string, file: string): string => {
 	if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
@@ -90,70 +48,6 @@ const cleanText = (value: unknown, field: string, file: string): string => {
 	return value.trim();
 };
 
-const stringList = (value: unknown, field: string, file: string, required = false): string[] => {
-	if (value === undefined) {
-		if (required) throw new Error(`${file}: ${field} is required.`);
-		return [];
-	}
-	const values = typeof value === "string" ? value.split(",") : value;
-	if (!Array.isArray(values) || values.some((item) => typeof item !== "string" || !item.trim() || item.includes("\0"))) {
-		throw new Error(`${file}: ${field} must be an array of strings.`);
-	}
-	return values.map((item) => item.trim());
-};
-
-const extensionList = (value: unknown, file: string): string[] => {
-	const extensions = stringList(value, "extensions", file);
-	for (const extension of extensions) {
-		const packageSource = /^(?:npm|git|github|https?|ssh):/.test(extension);
-		const userPath = isAbsolute(extension) || extension.startsWith("~/") || extension.startsWith("~\\") || extension.startsWith("file://");
-		if (!packageSource && !userPath) {
-			throw new Error(`${file}: extensions entries must be absolute paths or package sources.`);
-		}
-	}
-	return extensions;
-};
-
-export function loadRoles(agentDir = getAgentDir()): Role[] {
-	const dir = join(agentDir, "config", "pi-subagent");
-	let entries;
-	try {
-		entries = readdirSync(dir, { withFileTypes: true });
-	} catch (error: unknown) {
-		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
-		throw error;
-	}
-
-	const roles = entries
-		.filter((entry) => entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink()))
-		.sort((a, b) => a.name.localeCompare(b.name))
-		.map((entry): Role => {
-			const file = join(dir, entry.name);
-			let parsed: ReturnType<typeof parseFrontmatter>;
-			try {
-				parsed = parseFrontmatter(readFileSync(file, "utf8"));
-			} catch (error) {
-				throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-			}
-			const frontmatter = parsed.frontmatter;
-			return {
-				name: cleanText(frontmatter.name, "name", file),
-				description: cleanText(frontmatter.description, "description", file),
-				tools: frontmatter.tools === undefined ? undefined : stringList(frontmatter.tools, "tools", file, true),
-				extensions: extensionList(frontmatter.extensions, file),
-				skills: stringList(frontmatter.skills, "skills", file),
-				systemPrompt: cleanText(parsed.body, "system prompt", file),
-			};
-		});
-
-	const names = new Set<string>();
-	for (const role of roles) {
-		if (names.has(role.name)) throw new Error(`Duplicate Subagent role: ${role.name}.`);
-		names.add(role.name);
-	}
-	return roles;
-}
-
 function piInvocation(args: string[]): { command: string; args: string[] } {
 	const currentScript = process.argv[1];
 	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
@@ -471,20 +365,6 @@ const roleSummary = (): string => {
 	}
 };
 
-function resolveSkillPaths(pi: ExtensionAPI, names: string[]): { paths: string[]; missing: string[] } {
-	const skills = new Map(pi.getCommands()
-		.filter((command) => command.source === "skill")
-		.map((command) => [command.name, command.sourceInfo.path]));
-	const paths: string[] = [];
-	const missing: string[] = [];
-	for (const name of names) {
-		const path = skills.get(`skill:${name}`);
-		if (path) paths.push(path);
-		else missing.push(name);
-	}
-	return { paths, missing };
-}
-
 export default function subagentExtension(pi: ExtensionAPI): void {
 	const widgetItems = new Map<string, WidgetItem>();
 	let widgetInstalled = false;
@@ -590,40 +470,22 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			if (params.modelClass !== undefined && !isModelClass(params.modelClass)) {
 				throw new Error("delegate_task modelClass must be fast, balanced, or frontier.");
 			}
-			const resolvedRoute = resolveTaskRoute(ctx, params.modelClass);
-			const model = resolvedRoute.model;
-			const modelReferenceValue = modelReference(model);
-			const thinkingLevel = resolvedRoute.thinkingLevel;
-
-			const resolvedSkills = resolveSkillPaths(pi, role.skills);
-			if (resolvedSkills.missing.length) {
+			const launch = params.modelClass === undefined
+				? resolveRoleLaunch(pi, ctx, { role, taskId: SUBAGENT_TASK })
+				: createRoleLaunch(pi, ctx, { role, route: resolveTaskRoute(ctx, params.modelClass) });
+			const modelReferenceValue = modelReference(launch.model);
+			const thinkingLevel = launch.thinkingLevel;
+			if (launch.missingSkills.length) {
 				ctx.ui.notify(
-					`Subagent role ${role.name} skipped unavailable Pi skills: ${resolvedSkills.missing.join(", ")}.`,
+					`Subagent role ${role.name} skipped unavailable Pi skills: ${launch.missingSkills.join(", ")}.`,
 					"warning",
 				);
 			}
 
-			const tempDir = await mkdtemp(join(tmpdir(), "pi-subagent-"));
-			const promptPath = join(tempDir, "system.md");
 			let widgetStatus: Exclude<WidgetStatus, "working"> = "failure";
 			try {
-				await writeFile(promptPath, role.systemPrompt, { encoding: "utf8", mode: 0o600 });
-				const args = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--no-skills"];
-				const extensions = isNumberedCodexProvider(model.provider)
-					? [...role.extensions, MULTI_CODEX_EXTENSION]
-					: role.extensions;
-				for (const extension of new Set(extensions)) args.push("--extension", extension);
-				for (const skill of resolvedSkills.paths) args.push("--skill", skill);
-				if (role.tools !== undefined) {
-					if (role.tools.length) args.push("--tools", role.tools.join(","));
-					else args.push("--no-tools");
-				}
-				args.push("--model", modelReferenceValue);
-				if (thinkingLevel) args.push("--thinking", thinkingLevel);
-				args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
-				args.push("--append-system-prompt", promptPath, `Task: ${task}`);
-
-				startWidgetItem(toolCallId, role.name, model.id, thinkingLevel, task, ctx);
+				const args = ["--mode", "json", "-p", ...launch.args, `Task: ${task}`];
+				startWidgetItem(toolCallId, role.name, launch.model.id, thinkingLevel, task, ctx);
 				const details = { role: role.name, model: modelReferenceValue, thinkingLevel };
 				const result = await runPi(
 					args,
@@ -642,11 +504,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				if (signal?.aborted) widgetStatus = "aborted";
 				throw error;
 			} finally {
-				try {
-					await rm(tempDir, { recursive: true, force: true });
-				} finally {
-					finishWidgetItem(toolCallId, widgetStatus);
-				}
+				finishWidgetItem(toolCallId, widgetStatus);
 			}
 		},
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "2.1.0",
+  "version": "2.3.1",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",
@@ -14,13 +14,24 @@
   },
   "license": "MIT",
   "files": [
+    "dist",
     "extensions",
     "README.md",
+    "CONTEXT.md",
     "LICENSE"
   ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "test": "node --test test/*.test.ts",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/subagent.ts test/*.test.ts",
+    "build": "tsc --project tsconfig.build.json",
+    "test": "npm run build && node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck src/*.ts extensions/*.ts test/*.test.ts",
+    "prepack": "npm run build",
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
@@ -46,7 +57,8 @@
     ]
   },
   "dependencies": {
+    "@henryqw/pi-herdr": "^0.1.1",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^0.2.0"
+    "@henryqw/pi-task-models": "^0.3.0"
   }
 }