@marcoscale98/pi-extensible-workflows 5.19.1-fork.1 → 6.2.1-fork.1

package/starter/review-loop.ts

@@ -17,27 +17,28 @@ export const reviewLoop = defineWorkflowFunction({
     );
     let devResult: JsonValue = null;
     let review: Static<typeof reviewSchema> = { pass: false, findings: [] };
+    // One developer keeps its transcript across iterations; each reviewer starts fresh.
+    const developer = agent.create({ name: "developer", label: "Developer", role: "developer" });
 
     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>
+              `Address the latest review findings and complete the original task.
 <last_review>{review}</last_review>`,
-              { task, review: review.findings },
+              { review: review.findings },
             );
-      devResult = await agent(devPrompt, { role: "developer" });
+      devResult = await developer.send(devPrompt);
       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.
+          `Review the actual current implementation against the entire original task. Inspect the code and run relevant checks yourself. Do not rely on the developer summary or on previous findings; they may be incomplete or wrong. Set pass=true only when the whole task is complete and correct.
 <original_task>{task}</original_task>
-<last_review>{review}</last_review>
+<previous_review_findings>{review}</previous_review_findings>
 <dev_summary>{devResult}</dev_summary>`,
           { task, devResult, review: review.findings },
         ),
-        { role: "reviewer", outputSchema: reviewSchema },
+        { label: `Reviewer ${String(iterations)}`, role: "reviewer", outputSchema: reviewSchema },
       );
 
       if (review.pass) return { pass: true, iterations, devResult, review };

package/starter/roles/developer.md

@@ -1,5 +1,4 @@
 ---
-model: developer-model
 description: Developer focused agent
 ---
 

package/starter/roles/oracle.md

@@ -1,5 +1,4 @@
 ---
-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
 ---

package/starter/roles/researcher.md

@@ -1,5 +1,4 @@
 ---
-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
 ---

package/starter/roles/reviewer.md

@@ -1,5 +1,4 @@
 ---
-model: reviewer-model
 tools: ["!*", "read", "grep", "find", "ls"]
 description: Reviewer. Use when we need to review decisions or code changes
 ---

package/starter/roles/scout.md

@@ -1,5 +1,4 @@
 ---
-model: scout-model
 tools: ["!*", "read", "grep", "find", "ls"]
 description: Scout. Use for fast read-only codebase recon before planning or implementing
 ---

package/subagents/README.md

@@ -18,7 +18,7 @@ Use the built-in subagent tools for focused, independent tasks. Use `pi-extensib
 
 - 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`.
+- Reuses generic workflow preparation hooks, 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.
@@ -44,21 +44,21 @@ subagents_run({ prompt: "Summarize README.md.", mode: "foreground" })
 
 ## Interactive inspection
 
-In Pi's TUI, `/subagents` opens the `/workflow` dashboard layout for the durable standalone runs of the current session: the run list sits beside the selected run's details at 80 columns or wider, and narrower terminals drill down from the list to the details. The details show the run ID and the same activity, stall warning, state, model, role, tools, attempts, duration, cumulative token accounting, cost, and error fields as a `/workflow` agent; a running run shows its live activity, which `subagents_inspect` leaves out. Requests without a role show `Role: (none)`. While a run is active the view refreshes the active runs and the selection every second; runs launched while it is open appear after an action or when it reopens. `a` or `enter` opens registered standalone agent actions, editor controls for the prompt, the live system prompt, and the result, `Steer` and `Stop` while running, `Retry` for failed or stopped runs, and the `/workflow` run actions that apply: `Delete`, `Delete all completed`, `Delete all failed`, `Copy run path`, and `Copy agent ID`. Stop and every deletion ask for confirmation, and a run whose worktree still awaits cleanup cannot be deleted. Outside the TUI, `/subagents` opens a picker with the same run summary and bulk deletions as the `/workflow` picker. Background runs appear below the editor in the workflow widget's frame, one row per run with its model, tokens, cost, elapsed time, and quiet or stalled warning, and each leaves a receipt in the transcript when it settles. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, retry, or delete a run.
+In Pi's TUI, `/subagents` opens the `/workflow` dashboard layout for the durable standalone runs of the current session: the run list sits beside the selected run's details at 80 columns or wider, and narrower terminals drill down from the list to the details. The details show the run ID and the same activity, stall warning, state, model, tools, attempts, duration, cumulative token accounting, cost, and error fields as a `/workflow` agent; a running run shows its live activity, which `subagents_inspect` leaves out. While a run is active the view refreshes the active runs and the selection every second; runs launched while it is open appear after an action or when it reopens. `a` or `enter` opens registered standalone agent actions, editor controls for the prompt, the live system prompt, and the result, `Steer` and `Stop` while running, `Retry` for failed or stopped runs, and the `/workflow` run actions that apply: `Delete`, `Delete all completed`, `Delete all failed`, `Copy run path`, and `Copy agent ID`. Stop and every deletion ask for confirmation, and a run whose worktree still awaits cleanup cannot be deleted. Outside the TUI, `/subagents` opens a picker with the same run summary and bulk deletions as the `/workflow` picker. Background runs appear below the editor in the workflow widget's frame, one row per run with its model, tokens, cost, elapsed time, and quiet or stalled warning, and each leaves a receipt in the transcript when it settles. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, retry, or delete a run.
 
 ## Tools
 
-Every tool schema is a closed object. Unknown properties are rejected. The model-visible standalone surface contains exactly these five names:
+`subagents_run` accepts additional JSON agent options for loaded preparation hooks; unknown options are ignored when no plugin handles them. The other control-tool schemas are closed objects. 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_run` | `{ prompt: string, mode?: "background" \| "foreground", label?: string, model?: string, tools?: string[], skills?: string[], extensions?: string[], contextFiles?: string[], worktree?: string, outputSchema?: object, retries?: integer 0..255, timeoutMs?: positive integer \| null }` |
 | `subagents_inspect` | `{ id?: string, scope?: "session" \| "all" }` |
 | `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.
+`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. Unknown JSON options are forwarded to enabled plugins. `role` has no core meaning. Concrete models are `provider/model:thinking`. Capability selectors cannot exceed root and parent ceilings. `excludeTools` takes exact tool names removed after preparation hooks, as Pi's `excludeTools` does; patterns and `workflow_result` are rejected with `INVALID_METADATA`, names also remove same-named custom tools, are frozen with the configuration that retries reuse, and names matching no root or custom tool only warn.
 
 `subagents_inspect({})` returns the current Pi session's run summaries ordered by start time; `subagents_inspect({ scope: "all" })` lists every stored run. `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`.
 
@@ -82,7 +82,7 @@ Each call owns an independent run, so calls can execute concurrently and settle
 
 ## 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.
+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 concrete prepared configuration 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.
 
@@ -102,13 +102,7 @@ Set `worktree` on `subagents_run` to create a named isolated Git worktree for th
 
 ## 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.
+`subagents_run` accepts the same execution options as workflow agents, plus JSON extension options. Enable the optional `@piewf/pi-ext-roles` extension in the parent Pi session when role behavior is required; core does not discover role files or read shared role settings. [Generic preparation hooks](https://vekexasia.github.io/pi-extensible-workflows/extensions.html#preparation) receive authorized inventories, effective cwd/agentDir/trust, root defaults, immutable original options, and cancellation. Prepared configurations are persisted before execution and reused on retry without resolving external policies again. Lost capabilities or trust fail closed. Internal workflow and subagent control tools remain excluded from the child agent.
 
 ## Programmatic host integration
 
@@ -142,4 +136,4 @@ The v5.4 release removes the seven-tool surface's redundant `subagents_list`, `s
 | `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.
+The standalone manager deliberately keeps durable run IDs, repeatable inspection, bounded steering, named worktree cleanup, and generic workflow preparation and settings reuse.

package/subagents/src/contracts.ts

@@ -29,15 +29,15 @@ export const SUBAGENTS_RUN_PARAMETERS = Type.Object({
   label: Type.Optional(Type.String({ description: "Optional display label for the subagent" })),
   model: Type.Optional(Type.String({ description: "Optional model as provider/model:thinking or alias[:thinking]" })),
   tools: Type.Optional(Type.Array(Type.String(), { description: "Optional ordered tool selectors; candidates start enabled and !* restricts the set" })),
+  excludeTools: Type.Optional(Type.Array(Type.String(), { description: "Optional exact tool names removed after preparation; no patterns, cannot remove workflow_result" })),
   skills: Type.Optional(Type.Array(Type.String(), { description: "Optional ordered skill selectors; candidates start enabled and !* restricts the set" })),
   extensions: Type.Optional(Type.Array(Type.String(), { description: "Optional ordered extension selectors; candidates start enabled and !* restricts the set" })),
   contextFiles: Type.Optional(Type.Array(Type.String(), { description: "Optional context-file scopes: global, project, cwd" })),
-  role: Type.Optional(Type.String({ description: "Workflow role name" })),
   worktree: Type.Optional(Type.String({ description: "Optional named worktree; requires a clean working tree" })),
   outputSchema: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional JSON schema for the result" })),
   retries: Type.Optional(Type.Integer({ minimum: 0, maximum: SUBAGENT_MAX_RETRIES, description: "Optional retry count; at most 255 retries" })),
   timeoutMs: Type.Optional(Type.Union([Type.Integer({ minimum: 1, description: "Optional execution timeout in milliseconds" }), Type.Null()])),
-}, { additionalProperties: false });
+}, { additionalProperties: true });
 
 export const SUBAGENTS_INSPECT_PARAMETERS = Type.Object({
   id: Type.Optional(Type.String({ description: "Subagent ID; omit to list ordered run summaries" })),
@@ -79,7 +79,7 @@ export const SUBAGENT_STATUS_OUTPUT = Type.Object({
 export const SUBAGENTS_INSPECT_OUTPUT = Type.Union([SUBAGENT_STATUS_OUTPUT, Type.Array(Type.Object({ id: Type.String(), state: Type.String() }))]);
 export const SUBAGENTS_STEER_OUTPUT = Type.Object({ id: Type.String(), accepted: Type.Boolean() });
 
-export type SubagentRunRequest = Static<typeof SUBAGENTS_RUN_PARAMETERS>;
+export type SubagentRunRequest = Static<typeof SUBAGENTS_RUN_PARAMETERS> & { readonly [key: string]: unknown };
 export function normalizeSubagentRunRequest(value: unknown): SubagentRunRequest {
   if (!Value.Check(SUBAGENTS_RUN_PARAMETERS, value)) throw new WorkflowError("INVALID_METADATA", "Invalid subagents_run parameters");
   if (typeof value.worktree === "string" && !value.worktree.trim()) throw new WorkflowError("INVALID_METADATA", "worktree name must be a non-empty string");
@@ -114,7 +114,6 @@ export interface SubagentStatus {
 export interface SubagentNotification {
   readonly id: string;
   readonly label?: string;
-  readonly role?: string;
   readonly state: "completed" | "failed";
   readonly error?: { readonly code: string; readonly message: string };
 }

package/subagents/src/index.ts

@@ -26,7 +26,7 @@ export { createSubagentManager, createUnavailableSubagentManager } from "./manag
 export { createRunStoreWorktreeAdapter, defaultWorktreeHome } from "./worktree.js";
 export type { SubagentWorktreeAdapter, SubagentWorktreeContext, SubagentWorktreeHandle, SubagentWorktreeRunStore } from "./worktree.js";
 
-type SubagentsExtensionAPI = Pick<ExtensionAPI, "registerTool"> & Partial<Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "on" | "sendMessage" | "registerCommand" | "appendEntry" | "registerEntryRenderer">>;
+type SubagentsExtensionAPI = Pick<ExtensionAPI, "registerTool"> & Partial<Pick<ExtensionAPI, "events" | "getActiveTools" | "getAllTools" | "on" | "sendMessage" | "registerCommand" | "appendEntry" | "registerEntryRenderer">>;
 
 function validateSubagentRunRequest(value: unknown): SubagentRunRequest {
   return normalizeSubagentRunRequest(value);
@@ -141,8 +141,7 @@ export function createSubagentTools(manager: SubagentManager): readonly ToolDefi
 
 function notificationContent(notification: SubagentNotification): string {
   const label = notification.label?.trim();
-  const role = notification.role?.trim() || "none";
-  const identity = label ? `${label} role=${role} (${notification.id})` : `${notification.id} role=${role}`;
+  const identity = label ? `${label} (${notification.id})` : notification.id;
   if (notification.state === "completed") return `Subagent ${identity} completed. Inspect it with subagents_inspect({ id: "${notification.id}" }).`;
   return `Subagent ${identity} failed: ${notification.error?.message ?? "unknown error"}. Inspect it with subagents_inspect({ id: "${notification.id}" }).`;
 }

package/subagents/src/manager.ts

@@ -2,67 +2,11 @@ import { randomUUID } from "node:crypto";
 import { chmod, link, mkdir, open, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import {
-  addAccounting,
-  deepFreeze,
-  errorCode,
-  errorText,
-  finiteNumber,
-  isNodeError,
-  isThinkingLevel,
-  jsonValue,
-  object,
-  loadingRegistry,
-  localAgentTransport,
-  resolveAgentResourcePolicy,
-  resolveWorkflowSettings,
-  roleNameOf,
-  sanitizeDisplayText,
-  sumAccounting,
-  structuralPath,
-  validateModelAliasAvailability,
-  WorkflowAgentExecutor,
-  WorkflowError,
-  workflowProjectSettingsPath,
-  workflowSettingsPath,
-  type AgentAccounting,
-  type AgentAttempt,
-  type AgentAttemptSummary,
-  type AgentDefinition,
-  type AgentExecutionOptions,
-  type AgentExecutionRoot,
-  type AgentProgress,
-  type AgentToolCallProgress,
-  type JsonSchema,
-  type JsonValue,
-  type ModelSpec,
-  type WorkflowAgentSessionState,
-  type WorkflowExtensionSettings,
-  type WorkflowRunContext,
-  SerialLane,
-} from "../../src/index.js";
-import { decodeAgentDefinition, decodeWorkflowExtensions } from "../../src/decoders.js";
-import { loadAgentDefinitions } from "../../src/roles.js";
+import { addAccounting, errorCode, errorText, finiteNumber, isNodeError, isThinkingLevel, jsonValue, object, loadingRegistry, localAgentTransport, resolveAgentResourcePolicy, resolveWorkflowSettings, sanitizeDisplayText, sumAccounting, structuralPath, validateModelAliasAvailability, WorkflowAgentExecutor, WorkflowError, workflowSettingsPath, type AgentAccounting, type AgentAttempt, type AgentAttemptSummary, type PreparedAgentConfiguration, type AgentExecutionOptions, type AgentExecutionRoot, type AgentProgress, type AgentToolCallProgress, type JsonSchema, type JsonValue, type ModelSpec, type WorkflowAgentSessionState, type WorkflowRunContext, SerialLane } from "../../src/index.js";
+import { decodePreparedAgentConfiguration } from "../../src/decoders.js";
 import { atomicJson, json as readJson, processAlive } from "../../src/persistence.js";
 import { accountingValue, activityValue, legacyAccountingValue, worktreeValue } from "./decode.js";
-import {
-  SUBAGENT_ATTEMPT_DETAILS_LIMIT,
-  SUBAGENT_MAX_RETRIES,
-  SUBAGENT_SYSTEM_PROMPT_LIMIT,
-  SUBAGENTS_TOOL_NAMES,
-  normalizeSubagentRunRequest,
-  type SubagentInspectRequest,
-  type SubagentLiveness,
-  type SubagentAttemptActionData,
-  type SubagentManager,
-  type SubagentManagerContext,
-  type SubagentManagerDependencies,
-  type SubagentNotification,
-  type SubagentOwnerMarker,
-  type SubagentProgress,
-  type SubagentRunRequest,
-  type SubagentStatus,
-} from "./contracts.js";
+import { SUBAGENT_ATTEMPT_DETAILS_LIMIT, SUBAGENT_MAX_RETRIES, SUBAGENT_SYSTEM_PROMPT_LIMIT, SUBAGENTS_TOOL_NAMES, normalizeSubagentRunRequest, type SubagentInspectRequest, type SubagentLiveness, type SubagentAttemptActionData, type SubagentManager, type SubagentManagerContext, type SubagentManagerDependencies, type SubagentNotification, type SubagentOwnerMarker, type SubagentProgress, type SubagentRunRequest, type SubagentStatus } from "./contracts.js";
 import { createRunStoreWorktreeAdapter, defaultWorktreeHome, type SubagentWorktreeContext, type SubagentWorktreeHandle } from "./worktree.js";
 
 const WORKFLOW_NAME = "subagents";
@@ -77,12 +21,7 @@ const MAX_PERSISTED_ATTEMPT_ARRAY_ITEMS = SUBAGENT_MAX_RETRIES + 1;
 const MAX_PERSISTED_ATTEMPT_STRING_CHARS = 4096;
 const MAX_PERSISTED_ATTEMPT_LOCATOR_CHARS = 16 * 1024;
 const SUBAGENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-type StandaloneExternalConfiguration = Readonly<{
-  projectTrusted: boolean;
-  globalExtensionSettings?: Readonly<WorkflowExtensionSettings>;
-  projectExtensionSettings?: Readonly<WorkflowExtensionSettings>;
-  agentDefinitions: Readonly<Record<string, AgentDefinition>>;
-}>;
+type StandaloneExternalConfiguration = Readonly<PreparedAgentConfiguration>;
 class InvalidPersistedSubagentStatusError extends WorkflowError {
   constructor() { super("INTERNAL_ERROR", "Persisted subagent status is invalid"); }
 }
@@ -169,22 +108,11 @@ function rootModel(context: Readonly<SubagentManagerContext>): ModelSpec {
   const thinking = context.extensionContext.thinkingLevel;
   return { provider: model.provider, model: model.id, ...(thinking === undefined ? {} : { thinking }) };
 }
-function standaloneExtensionSettingsPath(cwd: string, agentDir: string, trustedProject: boolean, external: StandaloneExternalConfiguration): string {
-  return trustedProject && external.projectExtensionSettings !== undefined ? workflowProjectSettingsPath(cwd) : workflowSettingsPath(agentDir);
-}
-function validateStandaloneExtensionSources(context: Readonly<SubagentManagerContext>, external: StandaloneExternalConfiguration, registry: ReturnType<typeof loadingRegistry>, agentDir: string): void {
-  const cwd = context.extensionContext.cwd;
-  const globalSettingsPath = workflowSettingsPath(agentDir);
-  const trustedProject = context.extensionContext.isProjectTrusted();
-  if (external.globalExtensionSettings !== undefined) registry.validateExtensionSettings(external.globalExtensionSettings, { source: "global", cwd, projectTrusted: trustedProject, settingsPath: globalSettingsPath });
-  if (trustedProject && external.projectExtensionSettings !== undefined) registry.validateExtensionSettings(external.projectExtensionSettings, { source: "project", cwd, projectTrusted: true, settingsPath: workflowProjectSettingsPath(cwd) });
-}
-function executionRoot(context: Readonly<SubagentManagerContext>, dependencies: Readonly<SubagentManagerDependencies>, signal: AbortSignal, runId: string, worktree: SubagentWorktreeHandle | undefined, external: StandaloneExternalConfiguration): AgentExecutionRoot {
+function executionRoot(context: Readonly<SubagentManagerContext>, dependencies: Readonly<SubagentManagerDependencies>, signal: AbortSignal, runId: string, worktree: SubagentWorktreeHandle | undefined): AgentExecutionRoot {
   const extensionContext = context.extensionContext;
   const model = rootModel(context);
   const agentDir = dependencies.agentDir ?? getAgentDir();
   const currentTrustedProject = extensionContext.isProjectTrusted();
-  if (external.projectTrusted && !currentTrustedProject) throw new WorkflowError("RESUME_INCOMPATIBLE", "Cannot retry standalone configuration from an untrusted project");
   const trustedProject = currentTrustedProject;
   const settingsPath = workflowSettingsPath(agentDir);
   const settings = resolveWorkflowSettings(extensionContext.cwd, trustedProject, settingsPath);
@@ -207,11 +135,13 @@ function executionRoot(context: Readonly<SubagentManagerContext>, dependencies:
     signal,
   };
   const registry = loadingRegistry();
-  validateStandaloneExtensionSources(context, external, registry, agentDir);
-  const extensionSettings = trustedProject && external.projectExtensionSettings !== undefined ? external.projectExtensionSettings : external.globalExtensionSettings;
-  const extensionSettingsPath = standaloneExtensionSettingsPath(extensionContext.cwd, agentDir, trustedProject, external);
+  if (settings.global.extensionSettings !== undefined) registry.validateExtensionSettings(settings.global.extensionSettings, { source: "global", cwd: extensionContext.cwd, projectTrusted: trustedProject, settingsPath: settings.globalSettingsPath });
+  if (trustedProject && settings.project.extensionSettings !== undefined) registry.validateExtensionSettings(settings.project.extensionSettings, { source: "project", cwd: extensionContext.cwd, projectTrusted: true, settingsPath: settings.projectSettingsPath });
+  const extensionSettings = settings.effective.extensionSettings;
+  const extensionSettingsPath = settings.sources.extensionSettings ?? settingsPath;
   return {
     cwd: extensionContext.cwd,
+    projectTrusted: trustedProject,
     model,
     tools,
     resourceSelectors: resourcePolicy.effective,
@@ -221,9 +151,10 @@ function executionRoot(context: Readonly<SubagentManagerContext>, dependencies:
     availableModels,
     knownModels,
     ...(Object.keys(staticAliases).length ? { modelAliases: staticAliases } : {}),
+    dynamicModelAliasNames: [],
     settingsPath: settings.sources.modelAliases,
     extensionSettingsPath,
-    agentDefinitions: external.agentDefinitions,
+    agentPreparationHooks: registry.agentPreparationHooks(),
     agentSetupHooks: registry.agentSetupHooks(),
     validateExtensionSettings: registry.validateExtensionSettings,
     agentResourcePolicy: () => structuredClone(resourcePolicy),
@@ -240,12 +171,11 @@ async function addDynamicAliases(context: Readonly<SubagentManagerContext>, sign
   const trustedProject = resourcePolicy?.projectTrusted ?? context.extensionContext.isProjectTrusted();
   const dynamicAliases = await registry.resolveModelAliases({ cwd: context.extensionContext.cwd, projectTrusted: trustedProject, rootModel: root.model, knownModels: root.knownModels ?? new Set(), availableModels: root.availableModels ?? new Set(), signal }, new Set(Object.keys(staticAliases)));
   validateModelAliasAvailability(dynamicAliases, Object.keys(dynamicAliases), root.availableModels ?? new Set(), root.knownModels ?? new Set(), root.settingsPath);
-  return { ...root, modelAliases: { ...dynamicAliases, ...staticAliases } };
+  return { ...root, modelAliases: { ...dynamicAliases, ...staticAliases }, dynamicModelAliasNames: Object.keys(dynamicAliases) };
 }
 
 function executionOptions(request: Readonly<SubagentRunRequest>, onAttempt: NonNullable<AgentExecutionOptions["onAttempt"]>, onProgress: NonNullable<AgentExecutionOptions["onProgress"]>): AgentExecutionOptions {
-  const role = request.role;
-  const label = request.label ?? roleNameOf(role) ?? "subagent";
+  const label = request.label ?? "subagent";
   return {
     label,
     workflowName: WORKFLOW_NAME,
@@ -254,11 +184,11 @@ function executionOptions(request: Readonly<SubagentRunRequest>, onAttempt: NonN
     ...(request.skills === undefined ? {} : { skills: request.skills }),
     ...(request.extensions === undefined ? {} : { extensions: request.extensions }),
     ...(request.contextFiles === undefined ? {} : { contextFiles: request.contextFiles as NonNullable<AgentExecutionOptions["contextFiles"]> }),
-    ...(role === undefined ? {} : { role }),
     ...(request.worktree === undefined ? {} : { worktreeOwner: structuralPath("worktree", "named", request.worktree) }),
     ...(request.outputSchema === undefined ? {} : { schema: request.outputSchema as JsonSchema }),
     ...(request.retries === undefined ? {} : { retries: request.retries }),
     ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+    agentOptions: Object.fromEntries(Object.entries(request).filter(([key]) => !["prompt", "mode", "worktree"].includes(key))) as Record<string, JsonValue>,
     onAttempt,
     onProgress,
   };
@@ -398,32 +328,8 @@ function checkedRequest(request: unknown): SubagentRunRequest {
   return normalizeSubagentRunRequest(request);
 }
 function decodePersistedStandaloneExternalConfiguration(value: unknown): StandaloneExternalConfiguration | undefined {
-  if (!object(value) || !jsonValue(value) || typeof value.projectTrusted !== "boolean") return undefined;
-  const globalExtensionSettings = value.globalExtensionSettings === undefined ? undefined : decodeWorkflowExtensions(value.globalExtensionSettings);
-  const projectExtensionSettings = value.projectExtensionSettings === undefined ? undefined : decodeWorkflowExtensions(value.projectExtensionSettings);
-  if (value.globalExtensionSettings !== undefined && globalExtensionSettings === undefined || value.projectExtensionSettings !== undefined && projectExtensionSettings === undefined) return undefined;
-  if (!object(value.agentDefinitions)) return undefined;
-  const agentDefinitions = Object.create(null) as Record<string, AgentDefinition>;
-  for (const [name, definition] of Object.entries(value.agentDefinitions)) {
-    const decoded = decodeAgentDefinition(definition);
-    if (decoded === undefined) return undefined;
-    agentDefinitions[name] = decoded;
-  }
-  return deepFreeze({ projectTrusted: value.projectTrusted, ...(globalExtensionSettings === undefined ? {} : { globalExtensionSettings }), ...(projectExtensionSettings === undefined ? {} : { projectExtensionSettings }), agentDefinitions });
-}
-function standaloneExternalConfiguration(context: Readonly<SubagentManagerContext>, dependencies: Readonly<SubagentManagerDependencies>): StandaloneExternalConfiguration {
-  const cwd = context.extensionContext.cwd;
-  const trustedProject = context.extensionContext.isProjectTrusted();
-  const agentDir = dependencies.agentDir ?? getAgentDir();
-  const resolution = resolveWorkflowSettings(cwd, trustedProject, workflowSettingsPath(agentDir));
-  const globalExtensionSettings = resolution.global.extensionSettings;
-  const projectExtensionSettings = resolution.project.extensionSettings;
-  return deepFreeze({
-    projectTrusted: trustedProject,
-    ...(globalExtensionSettings === undefined ? {} : { globalExtensionSettings: structuredClone(globalExtensionSettings) }),
-    ...(projectExtensionSettings === undefined ? {} : { projectExtensionSettings: structuredClone(projectExtensionSettings) }),
-    agentDefinitions: structuredClone(loadAgentDefinitions(cwd, agentDir, trustedProject)),
-  });
+  if (!object(value) || value.version !== 1) return undefined;
+  return decodePreparedAgentConfiguration(value.configuration);
 }
 
 function checkedId(request: Readonly<{ id: string }>): string {
@@ -719,7 +625,7 @@ function emitUpdate(run: LiveRun): void {
   try { run.observe?.(publicStatus(live, true, true)); } catch { /* A widget failure is display-only. */ }
 }
 
-async function createRunStorage(root: string, id: string, request: Readonly<SubagentRunRequest>, status: PersistedSubagentStatus, external: StandaloneExternalConfiguration): Promise<string> {
+async function createRunStorage(root: string, id: string, request: Readonly<SubagentRunRequest>, status: PersistedSubagentStatus, external: StandaloneExternalConfiguration | undefined): Promise<string> {
   await secureDirectory(root);
   const directory = runDirectory(root, id);
   let created = false;
@@ -728,7 +634,7 @@ async function createRunStorage(root: string, id: string, request: Readonly<Suba
     created = true;
     await chmod(directory, 0o700);
     await atomicJson(requestPath(directory), request);
-    await atomicJson(configurationPath(directory), external);
+    if (external !== undefined) await atomicJson(configurationPath(directory), { version: 1, configuration: external });
     await atomicJson(statusPath(directory), status);
     return directory;
   } catch (error) {
@@ -918,6 +824,7 @@ function unavailable(operation: string): { ok: false; error: { code: "SUBAGENTS_
 
 class PersistentSubagentManager implements SubagentManager {
   private readonly activeRuns = new Map<string, LiveRun>();
+  private readonly pendingStarts = new Set<Promise<void>>();
   private activeRunCount = 0;
   private readonly terminalSummaries = new Map<string, TerminalSummary>();
   private readonly reconciliationErrors = new Map<string, WorkflowError>();
@@ -968,8 +875,8 @@ class PersistentSubagentManager implements SubagentManager {
     await this.ensureInitialized();
     if (this.disposed) throw new WorkflowError("CANCELLED", "Subagent manager is disposed");
     if (context.signal?.aborted) throw new WorkflowError("CANCELLED", "Subagent cancelled");
-    const external = frozenExternal ?? standaloneExternalConfiguration(context, this.dependencies);
-    if (external.projectTrusted && !context.extensionContext.isProjectTrusted()) throw new WorkflowError("RESUME_INCOMPATIBLE", "Cannot retry standalone configuration from an untrusted project");
+    const external = frozenExternal;
+    if (external?.projectTrusted && !context.extensionContext.isProjectTrusted()) throw new WorkflowError("RESUME_INCOMPATIBLE", "Cannot retry standalone configuration from an untrusted project");
     const id = randomUUID();
     const startedAt = Date.now();
     const sessionId = context.extensionContext.sessionManager.getSessionId();
@@ -982,13 +889,23 @@ class PersistentSubagentManager implements SubagentManager {
     this.activeRunCount += 1;
     const controller = new AbortController();
     const initialStatus: PersistedSubagentStatus = { id, sessionId, state: "running", startedAt, owner: { ...owner } };
+    let finishStart!: () => void;
+    const pendingStart = new Promise<void>((resolve) => { finishStart = resolve; });
+    this.pendingStarts.add(pendingStart);
     let directory: string;
     try {
       directory = await createRunStorage(storageDirectory(this.dependencies), id, snapshot, initialStatus, external);
+      if (this.disposePromise !== undefined || context.signal?.aborted) {
+        await atomicJson(statusPath(directory), reconciledStatus(initialStatus, "stopped", Date.now()));
+        throw new WorkflowError("CANCELLED", "Subagent cancelled");
+      }
     } catch (error) {
       this.activeRunCount -= 1;
       if (error instanceof WorkflowError) throw error;
       throw internalStorageError(error, `Unable to start subagent ${id}`);
+    } finally {
+      this.pendingStarts.delete(pendingStart);
+      finishStart();
     }
     const current: { run?: LiveRun } = {};
     let resolveTerminal!: (result: ForegroundResult) => void;
@@ -1019,12 +936,9 @@ class PersistentSubagentManager implements SubagentManager {
           throw new WorkflowError("CANCELLED", "Subagent cancelled");
         }
       }
-      const baseRoot = executionRoot(context, this.dependencies, controller.signal, id, worktree, external);
-      const root = loadingRegistry().modelAliases().length === 0 ? baseRoot : await addDynamicAliases(context, controller.signal, baseRoot);
+      const baseRoot = executionRoot(context, this.dependencies, controller.signal, id, worktree);
+      const root = external !== undefined || loadingRegistry().modelAliases().length === 0 ? baseRoot : await addDynamicAliases(context, controller.signal, baseRoot);
       const transport = this.dependencies.transport ?? localAgentTransport;
-      const injectedExecutor = this.dependencies.createExecutor?.(root, transport);
-      executorOwnership.default = injectedExecutor === undefined;
-      if (current.run) current.run.executorOwnsSession = executorOwnership.default;
       const setSteer = (handler: SteerHandler): void => {
         const run = current.run;
         if (run) this.registerSteerHandler(run, handler);
@@ -1066,6 +980,13 @@ class PersistentSubagentManager implements SubagentManager {
         if (run.state !== "running") return;
         emitUpdate(run);
       }, (progress) => this.recordProgress(current.run, progress));
+      if (external !== undefined) options.configuration = structuredClone(external);
+      options.onConfiguration = (configuration) => atomicJson(configurationPath(directory), { version: 1, configuration });
+      const cwd = worktree?.cwd ?? root.cwd;
+      options.configuration = await new WorkflowAgentExecutor(root, transport).prepare(options, cwd, controller.signal);
+      const injectedExecutor = this.dependencies.createExecutor?.({ ...root, extensionSettings: options.configuration.settings }, transport);
+      executorOwnership.default = injectedExecutor === undefined;
+      if (current.run) current.run.executorOwnsSession = executorOwnership.default;
       if (injectedExecutor) return injectedExecutor.execute(snapshot.prompt, options, controller.signal, setSteer);
       return new WorkflowAgentExecutor(root, transport).execute(snapshot.prompt, options, controller.signal, [], setSteer);
     });
@@ -1176,11 +1097,11 @@ class PersistentSubagentManager implements SubagentManager {
 
   async dispose(): Promise<void> {
     if (this.disposePromise) return this.disposePromise;
+    this.disposed = true;
     this.disposePromise = (async () => {
       await this.initialization;
-      this.disposed = true;
       const runs = [...this.activeRuns.values()];
-      await Promise.allSettled(runs.map((run) => this.stopRun(run, true)));
+      await Promise.allSettled([...this.pendingStarts, ...runs.map((run) => this.stopRun(run, true))]);
       await Promise.allSettled([...this.notificationPromises]);
       const owner = this.storageOwner;
       this.storageOwner = undefined;
@@ -1533,9 +1454,8 @@ class PersistentSubagentManager implements SubagentManager {
     const notify = this.dependencies.notify;
     if (!notify || run.notificationSent || run.disposed) return;
     run.notificationSent = true;
-    const role = roleNameOf(run.request.role) ?? "none";
-    const label = run.request.label?.trim() || (role === "none" ? "subagent" : role);
-    const notification: SubagentNotification = { id: run.id, label, role, state: run.state as "completed" | "failed", ...(run.error === undefined ? {} : { error: run.error }) };
+    const label = run.request.label?.trim() || "subagent";
+    const notification: SubagentNotification = { id: run.id, label, state: run.state as "completed" | "failed", ...(run.error === undefined ? {} : { error: run.error }) };
     const pending = Promise.resolve().then(() => notify(notification));
     this.notificationPromises.add(pending);
     void pending.then(() => { this.notificationPromises.delete(pending); }, () => { this.notificationPromises.delete(pending); });

package/subagents/src/navigator.ts

@@ -71,16 +71,10 @@ async function inspectEntry(manager: SubagentManager, storageDirectory: string,
   };
 }
 
-function requestRole(request: SubagentRunRequest | undefined): string {
-  const role: unknown = request?.role;
-  if (typeof role === "string" && role.trim()) return role.trim();
-  const override = objectValue(role);
-  return typeof override?.name === "string" && override.name.trim() ? override.name.trim() : "none";
-}
+
 function shortId(id: string): string { return id.length > 12 ? id.slice(0, 8) : id; }
 function entryName(entry: NavigatorEntry): string {
-  const role = requestRole(entry.request);
-  return boundedText(entry.request?.label?.trim() || (role === "none" ? shortId(entry.status.id) : role), 256);
+  return boundedText(entry.request?.label?.trim() || shortId(entry.status.id), 256);
 }
 /** Names for a list of runs; a repeated name carries its short ID, as in the `/workflow` picker, so every row stays unique. */
 function listNames(entries: readonly NavigatorEntry[]): string[] {
@@ -113,7 +107,7 @@ function usageAccounting(status: SubagentStatus): SubagentProgress["accounting"]
   return status.progress?.accounting;
 }
 function detailPresentation(inspection: Inspection): AgentDetailPresentation {
-  const { status, request } = inspection.entry;
+  const { status } = inspection.entry;
   const attempt = latestAttempt(status);
   const state = status.progress?.state;
   const activity = status.progress?.activity;
@@ -122,14 +116,12 @@ function detailPresentation(inspection: Inspection): AgentDetailPresentation {
   const lastEventAt = status.progress?.lastEventAt;
   const attempts = status.attempts ?? attempt?.attempt;
   const accounting = usageAccounting(status);
-  const role = requestRole(request);
   const error = status.error ?? attempt?.error;
   return {
     state: status.state,
     ...(activity === undefined ? {} : { activity: { kind: activity.kind, text: boundedText(activity.text) } }),
     ...(lastEventAt === undefined ? {} : { lastEventAt }),
     ...(model === undefined ? {} : { model: { provider: boundedText(model.provider, 256), model: boundedText(model.model, 256), ...(model.thinking === undefined ? {} : { thinking: model.thinking }) } }),
-    ...(role === "none" ? {} : { role: boundedText(role, 256) }),
     ...(tools === undefined ? {} : { tools: tools.slice(0, 256).map((tool) => boundedText(tool, 256)) }),
     ...(attempts === undefined ? {} : { attempts }),
     ...(status.startedAt === undefined ? {} : { startedAt: status.startedAt }),
@@ -186,8 +178,7 @@ function standaloneActionContext(manager: SubagentManager, inspection: Inspectio
   const session = attempt.session;
   const live = liveData?.liveSession && session && liveData.liveSession.reference.transport === session.transport && liveData.liveSession.reference.sessionId === session.sessionId ? liveData.liveSession : undefined;
   const label = request?.label?.trim();
-  const role = requestRole(request);
-  const name = label || (role === "none" ? "subagent" : role);
+  const name = label || "subagent";
   const ui = {
     notify: (message: string, level: "info" | "warning" | "error" = "info") => { context.ui.notify(message, level); },
     confirm: (title: string, message: string) => context.ui.confirm(title, message),