@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/src/workflow-artifacts.ts

@@ -0,0 +1,35 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { JsonValue } from "./types.js";
+
+export interface WorkflowArtifact { extension: ".js" | ".json" | ".md"; content: string }
+export type WorkflowTui = { stop(): void; start(): void; requestRender(force?: boolean): void };
+
+export function workflowScriptArtifact(script: string): WorkflowArtifact { return { extension: ".js", content: script }; }
+export function workflowPromptArtifact(prompt: string): WorkflowArtifact { return { extension: ".md", content: prompt }; }
+export function workflowResultArtifact(value: JsonValue): WorkflowArtifact { return typeof value === "string" ? { extension: ".md", content: value } : { extension: ".json", content: `${JSON.stringify(value, null, 2)}\n` }; }
+
+async function spawnWorkflowEditor(command: string, path: string): Promise<number | null> {
+  const [editor, ...editorArgs] = command.split(" ");
+  if (!editor) return null;
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(editor, [...editorArgs, path], { stdio: "inherit", shell: process.platform === "win32" });
+      child.once("error", () => { resolve(null); });
+      child.once("close", (code) => { resolve(code); });
+    } catch { resolve(null); }
+  });
+}
+
+export async function openWorkflowArtifact(tui: WorkflowTui, command: string, artifact: WorkflowArtifact): Promise<number | null> {
+  const directory = await mkdtemp(join(tmpdir(), "pi-workflow-editor-"));
+  const path = join(directory, `artifact${artifact.extension}`);
+  try {
+    await writeFile(path, artifact.content, { encoding: "utf8", mode: 0o600 });
+    tui.stop();
+    try { return await spawnWorkflowEditor(command, path); }
+    finally { tui.start(); tui.requestRender(true); }
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}

package/starter/index.ts

@@ -0,0 +1,35 @@
+import {
+  registerWorkflowExtension,
+  type WorkflowExtension,
+} from "@marcoscale98/pi-extensible-workflows";
+import { reviewLoop } from "./review-loop.js";
+
+const extension: WorkflowExtension = {
+  source: import.meta.url,
+  dependencies: ["typebox"],
+  version: "1.0.0",
+  headline: "Developer-review starter workflows",
+  functions: { reviewLoop },
+  modelAliases: {
+    "reviewer-model": {
+      resolve: ({ rootModel }) => `${rootModel.provider}/${rootModel.model}`,
+    },
+    "developer-model": {
+      resolve: ({ rootModel }) => `${rootModel.provider}/${rootModel.model}`,
+    },
+    "scout-model": {
+      resolve: ({ rootModel }) => `${rootModel.provider}/${rootModel.model}`,
+    },
+    "oracle-model": {
+      resolve: ({ rootModel }) => `${rootModel.provider}/${rootModel.model}`,
+    },
+    "researcher-model": {
+      resolve: ({ rootModel }) => `${rootModel.provider}/${rootModel.model}`,
+    },
+  },
+  roleDirectories: [new URL("./roles/", import.meta.url)],
+};
+
+export default function (): void {
+  registerWorkflowExtension(extension);
+}

package/starter/prompts/council.md

@@ -0,0 +1,16 @@
+---
+description: Convene 2-3 oracle advisors with distinct lenses and write a decision memo
+argument-hint: "<question or decision>"
+---
+
+Convene a bounded advisory council on this decision. You are the supervisor: you pick the lenses, you synthesize, you decide what feedback is valid. Advisors do not talk to each other.
+
+If the question is trivial or already settled, answer directly instead of convening a council.
+
+Pick 2-3 distinct lenses suited to the decision (for example: simplicity and maintenance cost, correctness and failure modes, migration and compatibility risk). Launch a named workflow whose script fans out one `agent(taskPrompt, { role: "oracle" })` per lens with `parallel(...)`, each given the decision, the relevant context, and its lens in `taskPrompt`. One pass only; do not run advisor rounds.
+
+Synthesize the returned opinions yourself into a short decision memo: the recommendation, the strongest argument against it, what each lens surfaced, and the decision that remains mine.
+
+Question:
+
+$@

package/starter/prompts/deep-research.md

@@ -0,0 +1,16 @@
+---
+description: Fan out researcher subagents on a question and synthesize a cited answer
+argument-hint: "<question>"
+---
+
+Run a deep research on this question. Do not research it yourself.
+
+First check this session's tools: if the question needs web evidence and no web search or fetch tool is available, say so and stop instead of producing an uncited answer.
+
+Decompose the question into 2-4 independent sub-questions with distinct angles. Launch a named workflow whose script fans the sub-questions out with `parallel(...)`, one `agent(taskPrompt, { role: "researcher" })` per sub-question with its question and context in `taskPrompt`, then passes the keyed briefs into one final `agent(...)` that synthesizes a single answer with citations and returns it.
+
+When the run completes, report the synthesized answer with its citations, plus anything the researchers marked as unverified.
+
+Question:
+
+$@

package/starter/prompts/oracle.md

@@ -0,0 +1,14 @@
+---
+description: Get a second opinion on a plan, design, or decision from an oracle subagent
+argument-hint: "<plan, decision, or question>"
+---
+
+Get a second opinion before committing to this plan or decision. Do not judge it yourself.
+
+Use `subagents_run` with `role: "oracle"` and `mode: "foreground"`. Give it the proposal below plus the relevant context from this conversation: the goal, the constraints, and any decisions already made. Point it at the files involved instead of pasting file contents.
+
+When it returns, relay the strongest challenge, the hidden assumptions, and the recommendation. State plainly whether the oracle endorsed the proposal.
+
+Proposal:
+
+$@

package/starter/prompts/parallel-review.md

@@ -0,0 +1,22 @@
+---
+description: Adversarial review with parallel fresh reviewers on distinct angles
+argument-hint: "[target or focus]"
+---
+
+Run an adversarial parallel review of the current work. Do not review it yourself and do not edit files.
+
+If a target or focus is given below, review that; otherwise review the current uncommitted diff.
+
+Choose 2-3 distinct review angles from the actual change (for example correctness and regressions, tests and validation, simplicity and maintainability; add security, performance, or docs when the change calls for it). Prefer three strong reviewers over many vague ones.
+
+Launch a named workflow whose script fans out one `agent(taskPrompt, { role: "reviewer" })` per angle with `parallel(...)`, each told its angle in `taskPrompt` and to inspect the repository and diff directly with its own tools. Await the keyed reviews, then synthesize them yourself into:
+
+- fixes worth doing now;
+- optional improvements;
+- feedback to ignore or defer, with a short reason.
+
+Report the synthesis and each reviewer's merge verdict. Do not apply fixes unless I ask.
+
+Target or focus:
+
+$@

package/starter/prompts/parallel-scout.md

@@ -0,0 +1,16 @@
+---
+description: Fan out scout subagents across areas of the codebase and merge the briefs
+argument-hint: "<question or task to scope>"
+---
+
+Recon this question across the codebase with parallel scouts. Do not explore it yourself.
+
+If the question is small enough for one scout, launch a single subagent with the `scout` role instead of a workflow.
+
+Otherwise split the question into 2-3 independent areas (for example: the feature's entry points, the data layer it touches, the tests that cover it). Launch a named workflow whose script fans out one `agent(taskPrompt, { role: "scout" })` per area with `parallel(...)`, putting its question and context in `taskPrompt`, then merge the keyed briefs yourself into one map: relevant files, how the flow works end to end, patterns to reuse, and open questions.
+
+Report the merged brief. Keep it compact; no implementation plan.
+
+Question:
+
+$@

package/starter/prompts/review-loop.md

@@ -0,0 +1,14 @@
+---
+description: Implement a task with the developer-and-reviewer loop workflow
+argument-hint: "<task> [max iterations]"
+---
+
+Run the bundled `reviewLoop` workflow for this task. Do not implement it yourself.
+
+Launch it with the `workflow` tool: a named run whose script returns `await reviewLoop({ task: args.task })`, passing the task below through `args`. If a max iteration count is given, pass `maxIterations` too. Leave the run in the background unless I asked to wait.
+
+When the run completes, report whether the reviewer passed the implementation, how many iterations ran, and any remaining findings.
+
+Task:
+
+$@

package/starter/prompts/review.md

@@ -0,0 +1,14 @@
+---
+description: Review the current diff or a named target with a fresh reviewer subagent
+argument-hint: "[target or focus]"
+---
+
+Launch a fresh-context review of the current work. Do not review it yourself and do not edit files.
+
+Use `subagents_run` with `role: "reviewer"` and `mode: "foreground"`. If a target or focus is given below, review that; otherwise review the current uncommitted diff. Tell the reviewer to inspect the repository and diff directly with its own tools, not to rely on this conversation.
+
+When it returns, relay the findings grouped by P0/P1/P2 and the merge verdict. Do not apply fixes unless I ask.
+
+Target or focus:
+
+$@

package/starter/prompts/scout.md

@@ -0,0 +1,14 @@
+---
+description: Launch a read-only scout subagent to recon the codebase
+argument-hint: "<question or area to explore>"
+---
+
+Launch one subagent with the `scout` role to answer this recon question. Do not explore the codebase yourself.
+
+Use `subagents_run` with `role: "scout"`, `mode: "foreground"`, and a prompt containing the question below plus any paths or constraints already known in this conversation.
+
+When it returns, relay the brief as-is: relevant files, flow, patterns to reuse, and open questions. Do not pad it.
+
+Question:
+
+$@

package/starter/review-loop.ts

@@ -0,0 +1,73 @@
+import { Type, type Static } from "typebox";
+import {
+  defineWorkflowFunction,
+  type JsonValue,
+} from "@marcoscale98/pi-extensible-workflows";
+
+export const reviewLoop = defineWorkflowFunction({
+  description:
+    "Run developer and reviewer agents until review passes or the iteration limit is reached",
+  async run({ task, maxIterations = 5 }, { agent, prompt }) {
+    const reviewSchema = Type.Object(
+      {
+        pass: Type.Boolean(),
+        findings: Type.Array(Type.String()),
+      },
+      { additionalProperties: false },
+    );
+    let devResult: JsonValue = null;
+    let review: Static<typeof reviewSchema> = { pass: false, findings: [] };
+
+    for (let iterations = 1; iterations <= maxIterations; iterations += 1) {
+      const devPrompt =
+        iterations === 1
+          ? prompt("Implement this task:\n\n{task}", { task })
+          : prompt(
+              `Address the previous review findings and complete the task.
+<original_task>{task}</original_task>
+<last_review>{review}</last_review>`,
+              { task, review: review.findings },
+            );
+      devResult = await agent(devPrompt, { role: "developer" });
+      review = await agent(
+        prompt(
+          `Review the implementation against the task. Set pass=true only when the task is complete and correct. The developer may have addressed a previous review run of yours. So its summary is related to the last round of review if present.
+<original_task>{task}</original_task>
+<last_review>{review}</last_review>
+<dev_summary>{devResult}</dev_summary>`,
+          { task, devResult, review: review.findings },
+        ),
+        { role: "reviewer", outputSchema: reviewSchema },
+      );
+
+      if (review.pass) return { pass: true, iterations, devResult, review };
+    }
+
+    return { pass: false, iterations: maxIterations, devResult, review };
+  },
+  input: Type.Object(
+    {
+      task: Type.String(),
+      maxIterations: Type.Optional(Type.Integer({ minimum: 1 })),
+    },
+    { additionalProperties: false },
+  ),
+  output: Type.Object(
+    {
+      pass: Type.Boolean(),
+      iterations: Type.Integer(),
+      devResult: Type.Any(),
+      review: Type.Object(
+        {
+          pass: Type.Boolean(),
+          findings: Type.Array(Type.String()),
+        },
+        { additionalProperties: false },
+      ),
+    },
+    { additionalProperties: false },
+  ),
+});
+
+export const reviewLoopInputSchema = reviewLoop.input;
+export const reviewLoopOutputSchema = reviewLoop.output;

package/starter/roles/developer.md

@@ -0,0 +1,6 @@
+---
+model: developer-model
+description: Developer focused agent
+---
+
+Act as a senior developer. Implement the requested task with the smallest working change. Read the relevant flow first, reuse existing project patterns, keep the change surgical, and verify the result with the smallest relevant check.

package/starter/roles/oracle.md

@@ -0,0 +1,18 @@
+---
+model: oracle-model
+tools: ["!*", "read", "grep", "find", "ls", "bash"]
+description: Oracle. Use for a second opinion on a plan, design, or decision before committing to it
+---
+
+Give a second opinion on the presented plan, design, or decision. Do not edit files. You are not a second decision-maker; you challenge, verify, and report.
+
+Reconstruct the stated goals and constraints first, then verify the claims against the actual code, tests, and docs. Run read-only commands when they settle a question. When source contradicts the plan or its assumptions, trust source and report the conflict.
+
+Return:
+
+- The strongest challenge to the proposal, with evidence.
+- Hidden assumptions or contradictions you found.
+- What the proposal gets right and should keep.
+- A recommendation, naming any decision that still belongs to the caller.
+
+If the proposal is sound, say so plainly instead of inventing objections.

package/starter/roles/researcher.md

@@ -0,0 +1,20 @@
+---
+model: researcher-model
+tools: ["!edit", "!write", "!bash"]
+description: Researcher. Use for deep research across the codebase, docs, and the web when web tools are available
+---
+
+Research the requested question in depth. Do not edit files.
+
+Use every read and search capability you have: code, files, docs, and any web search or fetch tools present in this session. If the question needs web evidence and no web tool is available, say so explicitly instead of guessing.
+
+Verify claims against primary sources: the actual code, official docs, or the cited page. Prefer primary sources over aggregators.
+
+Return a research brief:
+
+- Direct answer to the question.
+- Evidence per claim, citing files and lines for code and URLs for web sources.
+- Contradictions or version-specific caveats you found.
+- What is known, what is uncertain, and what would settle the open questions.
+
+Report only what you verified. Mark everything else as unverified.

package/starter/roles/reviewer.md

@@ -0,0 +1,19 @@
+---
+model: reviewer-model
+tools: ["!*", "read", "grep", "find", "ls"]
+description: Reviewer. Use when we need to review decisions or code changes
+---
+
+Inspect the requested change for correctness, missed callers, broken assumptions, regressions, security or data-loss risk, and missing verification. Do not edit files.
+
+Filter findings on evidence, not severity: report only concrete, current issues caused or made reachable by the change, backed by source proof, a failing test or repro, or a contract contradiction. Cite exact files and lines. Ignore style unless it hides a real defect. Do not report speculative or pre-existing issues unless asked.
+
+Label each finding:
+
+- P0: blocks merge (broken behavior, data loss, security).
+- P1: should be fixed before release.
+- P2: report-only note.
+
+If nothing qualifies, say exactly `No issues found.`
+
+End with one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`.

package/starter/roles/scout.md

@@ -0,0 +1,18 @@
+---
+model: scout-model
+tools: ["!*", "read", "grep", "find", "ls"]
+description: Scout. Use for fast read-only codebase recon before planning or implementing
+---
+
+Perform fast, read-only reconnaissance of the codebase for the requested question. Do not edit files.
+
+Locate the relevant files, entry points, and data flow. Trace the actual code paths instead of inferring from names. Note existing patterns, helpers, and tests the task should reuse.
+
+Return a compact brief:
+
+- Relevant files with one-line purpose each.
+- How the flow works end to end, citing files and lines.
+- Existing patterns or utilities to reuse.
+- What is known, what is uncertain, and the smallest next step.
+
+Report only what you verified in the code. Mark anything unverified as an open question. Keep output concise; no implementation plan.

package/subagents/README.md

@@ -0,0 +1,145 @@
+# Built-in subagent extension
+
+Single-shot agents for Pi: each run launches one independent agent session from one task, without writing a workflow script. Single-shot describes the orchestration shape, not one model turn; the agent can use tools and accept steering while it runs.
+
+[Full Subagents documentation](https://vekexasia.github.io/pi-extensible-workflows/subagents.html) | [Main package](https://github.com/vekexasia/pi-extensible-workflows#readme) | [Roles](https://vekexasia.github.io/pi-extensible-workflows/roles.html) | [Settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings)
+
+Use the built-in subagent tools for focused, independent tasks. Use `pi-extensible-workflows` when work needs dependency batches, parallel or pipeline stages, checkpoints, approvals, or resumable orchestration.
+
+## Subagents vs workflows
+
+| Built-in subagent tools | `pi-extensible-workflows` |
+| --- | --- |
+| One independently launched agent per run | A deterministic script orchestrating one or more agents |
+| One task with a durable ID and lifecycle controls | Multi-stage coordination, dependencies, approvals, replay, and resume |
+| Start in the background or wait in the foreground | Run a named workflow in the background or foreground |
+
+## Highlights
+
+- Five focused tools: run, inspect, steer, stop, and retry.
+- Background fan-out with one durable ID per run, or foreground execution with an inline terminal result.
+- Reuses workflow roles, model aliases, settings including extension-defined namespaces, and agent options: `label`, `model`, `tools`, `skills`, `extensions`, `contextFiles`, `worktree`, `outputSchema`, `retries` (0 through 255), and `timeoutMs`.
+- Repeatable inspection of progress, token accounting, tool calls, results, failures, and worktrees.
+
+Built-in subagent tools are available when the core extension is installed. Use the core package's Pi extension manifest to enable them.
+
+## Quick start
+
+Start work in the background and inspect it later:
+
+```text
+subagents_run({ prompt: "Review the current changes.", label: "review" })
+# => { "id": "...", "state": "running" }
+
+subagents_inspect({ id: "..." })
+# => progress while running, then the terminal value or error
+```
+
+Use foreground mode when the result must return in the same tool call:
+
+```text
+subagents_run({ prompt: "Summarize README.md.", mode: "foreground" })
+# => { "id": "...", "state": "completed", "value": ... }
+```
+
+## Interactive inspection
+
+In Pi's TUI, `/subagents` opens a picker of durable standalone runs for the current session. Select a run to inspect the same activity, stall warning, state, model, role, tools, attempts, duration, cumulative token accounting, cost, and error fields used by `/workflow`; prompt, request failure, and result details remain bounded, and requests without a role remain `role=none`. The detail view also exposes registered standalone agent actions plus `Steer` and `Stop` while running, `Retry` for failed or stopped runs, and copy/editor controls where applicable. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, or retry a run.
+
+## Tools
+
+Every tool schema is a closed object. Unknown properties are rejected. The model-visible standalone surface contains exactly these five names:
+
+| Tool | Input schema |
+| --- | --- |
+| `subagents_run` | `{ prompt: string, mode?: "background" \| "foreground", label?: string, model?: string, tools?: string[], skills?: string[], extensions?: string[], contextFiles?: string[], role?: string, worktree?: string, outputSchema?: object, retries?: integer 0..255, timeoutMs?: positive integer \| null }` |
+| `subagents_inspect` | `{ id?: string }` |
+| `subagents_steer` | `{ id: string, message: string }` |
+| `subagents_stop` | `{ id: string }` |
+| `subagents_retry` | `{ id: string }` |
+
+`prompt` is the only required `subagents_run` property. `mode` defaults to "background". Resource candidates start enabled, so plain positive top-level selector lists are additive and top-level `[]` adds no matches. Use `["!*", "read", "grep"]` to restrict a selector to those resources, or `["!*"]` to select none. A `role` string selects an existing workflow role. Model, tools, skills, extensions, and contextFiles are top-level `AgentOptions` overrides applied after the role file. Concrete models are `provider/model:thinking`. Capability selectors use ordered minimatch rules and are applied after global, trusted-project, and role selectors. Use `tools: ["*"]` to re-enable all tools after a role restriction.
+
+`subagents_inspect({})` returns all accessible run summaries ordered by start time. `subagents_inspect({ id })` returns the detailed lifecycle record, including state, start and finish timestamps, and the live snapshot under `progress`: `state`, cumulative `accounting`, `toolCalls`, `activity`, and `lastEventAt`. The snapshot state never includes the effective system prompt, and inspection has no `usage` field; token totals are derived from accounting. Materialized worktree path and branch are included when available. For completed runs it also includes `value`; for failed runs it includes `error`. A running run has no terminal value yet. Unknown IDs fail with `RUN_NOT_FOUND`.
+
+## Launching and concurrency
+
+Background mode starts execution immediately and returns one durable UUID:
+
+```json
+{"id":"01900000-0000-4000-8000-000000000000","state":"running"}
+```
+
+Use foreground mode when the terminal envelope is needed in the same tool call:
+
+```json
+{"id":"01900000-0000-4000-8000-000000000000","state":"completed","value":{"answer":"done"}}
+```
+
+A foreground failure returns `{"id":"...","state":"failed","error":{"code":"AGENT_FAILED","message":"..."}}`. Foreground cancellation aborts the active native session and persists a failed record with code `CANCELLED`. A foreground run does not generate a background completion follow-up.
+
+Each call owns an independent run, so calls can execute concurrently and settle independently up to the effective workflow `concurrency` setting for the launch context (an integer from 1 through 16, default 8). When the limit is reached, `subagents_run` and `subagents_retry` reject with `AGENT_FAILED`; no queue is maintained, so retry after an active run settles. Background completed and failed runs can produce one follow-up message when the host supplies `sendMessage`; the message points to the ID and `subagents_inspect` rather than embedding the full result.
+
+## IDs, inspection, and terminal values
+
+Run records are stored below the agent directory's private `subagents/<id>/` directory, normally `~/.pi/agent/subagents/<id>/`. The record includes the normalized request, its frozen external settings and role definitions for deterministic retries, and status. A shared storage owner marker uses the process ID, process start, session ID, and token; every running record carries the same manager identity so a live manager does not reconcile another manager's active run.
+
+Inspection is repeatable. Use the list form for ordered summaries and the ID form for one detailed status plus its terminal value or failure information. Progress is retained in memory and is persisted when the executor marks a progress update for persistence. The result and failure files remain available after manager restart.
+
+## Steering and stopping
+
+`subagents_steer` sends a message to a running agent. Messages sent before the executor exposes its steering handler are queued and delivered in order. The queue is bounded at 16 pending messages. Steering a settled, stopped, or unknown run fails; steering never targets a sibling run.
+
+`subagents_stop` aborts only the selected run, clears its steering queue, persists `state: "stopped"`, aborts its active session, and cleans its worktree. Stopping one run does not stop other runs. Use this tool when the desired terminal state is `stopped`; cancelling a foreground `subagents_run` instead records `failed` with `CANCELLED`.
+
+## Retries
+
+`subagents_retry` is available for `failed` and `stopped` runs. It reads the original normalized request and frozen external configuration, then starts a fresh execution with a new UUID. Historic records without that frozen configuration are reported as incompatible rather than retried with current settings. The old record and ID remain available. Completed or currently running runs are not retryable. The retry preserves the original `background` or `foreground` launch mode, so retrying a foreground run returns its new terminal envelope inline.
+
+## Worktrees
+
+Set `worktree` on `subagents_run` to create a named isolated Git worktree for that run. The default adapter uses the core `RunStore`: the worktree branches from the repository's clean `HEAD`, and a dirty working tree (tracked or untracked non-ignored changes) fails the run with `WORKTREE_FAILED`. The optional global or trusted-project `worktreePostCreateCommand` setting runs its executable and arguments directly, once after a physical checkout, from the launch-relative directory inside the new worktree. Install that external executable separately; missing executables, nonzero exits, spawn failures, and the fixed 60-second timeout fail with `WORKTREE_FAILED` and roll back creation. The setting is captured when the subagent starts, and an untrusted project cannot enable it. The executor runs in the worktree and inspection exposes its path and branch while materialized. Cleanup runs when the agent settles, stops, or the manager reconciles an interrupted record. After successful cleanup, the public and persisted worktree path, branch, and cleanup context are removed; if cleanup fails, all of that metadata is retained for a later retry. A run ID keeps concurrent worktrees separate even when their names are the same.
+
+## Agent options, roles, and settings
+
+`subagents_run` accepts the same execution options as a workflow `agent(...)`: model, thinking level, tool, skill, and extension selectors, named roles or inline role overrides, worktrees, structured output, retries, and timeout. The extension also reuses workflow model aliases, settings, resource selector policy, and role discovery:
+
+- global roles: `<agentDir>/pi-extensible-workflows/roles/<name>.md`, normally `~/.pi/agent/pi-extensible-workflows/roles/`;
+- trusted project roles: `<cwd>/.pi/pi-extensible-workflows/roles/<name>.md`;
+- global and trusted project settings: the normal workflow settings path under the agent directory and `<cwd>/.pi/pi-extensible-workflows/settings.json`.
+
+The current Pi model, thinking level, active tools, project trust, session ID, role definitions, aliases, and resource policy are captured from the extension context for each run. Internal workflow and subagent control tools are not exposed to the child agent.
+
+## Programmatic host integration
+
+Pi discovers this extension through the core package's `pi.extensions` manifest. The manifest entry point is `subagents/index.ts` in the core package; Pi loads this TypeScript entry directly. The following host-integration sketch is pseudocode; Pi supplies `pi` and a host may supply the optional manager:
+
+```ts
+import extension, { type SubagentManager } from "./index.js";
+
+const manager: SubagentManager = /* host implementation, or omit this option */;
+extension(pi, { manager });
+```
+
+The default export registers the five tools. `createSubagentManager()` and `createSubagentTools()` are also exported for hosts that need explicit lifecycle or dependency injection.
+
+## Shutdown and restoration
+
+The default extension subscribes to `session_shutdown`. Disposal aborts active runs, disposes owned agent sessions and listeners, cleans active worktrees, waits for pending completion notifications, releases the storage owner, and is idempotent. Terminal records and results remain on disk. Terminal worktree path, branch, and cleanup context are removed after successful cleanup; failed cleanup retains all three for retry on a later manager startup.
+
+**Cross-session restoration of a live native subagent session is unsupported.** On a new manager, a persisted `running` record is reconciled to `failed` with an interruption error unless a result or failure was already persisted. Use `subagents_retry` to start a new run; it does not restore conversation context or reuse the old native session. Persisted completed and failed records remain readable, subject to the storage owner and filesystem being available.
+
+## Migrating from v5.3 to v5.4
+
+The v5.4 release removes the seven-tool surface's redundant `subagents_list`, `subagents_status`, and `subagents_result` names. There are no compatibility aliases. Replace calls as follows:
+
+| v5.3 call | v5.4 call |
+| --- | --- |
+| `subagents_run({ prompt, ... })` | unchanged for background runs; `mode: "foreground"` is new |
+| `subagents_list({})` | `subagents_inspect({})` |
+| `subagents_status({ id })` followed by `subagents_result({ id })` | `subagents_inspect({ id })` |
+| `subagents_steer({ id, message })` | unchanged |
+| `subagents_stop({ id })` | unchanged |
+| `subagents_retry({ id })` | unchanged; the original launch mode is preserved |
+
+The standalone manager deliberately keeps durable run IDs, repeatable inspection, bounded steering, named worktree cleanup, and workflow role/settings reuse.

package/subagents/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public package entry point for the Pi subagents extension.
+ *
+ * Pi discovers the compiled default export from the package manifest. The entry point registers the namespaced
+ * standalone tools; the manager API can also be imported directly.
+ */
+export * from "./src/index.js";
+export { default } from "./src/index.js";