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

package/src/validation.ts

@@ -2,17 +2,14 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import * as acorn from "acorn";
 import { Script } from "node:vm";
-import type { AgentDefinition, CheckpointInput, JsonSchema, JsonValue, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, StaticWorkflowExecution, StaticWorkflowScope, ValidatedWorkflowLaunch, WorkflowCallKind, WorkflowErrorCode, WorkflowMetadata, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
+import type { CheckpointInput, JsonSchema, JsonValue, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, StaticWorkflowExecution, StaticWorkflowScope, ValidatedWorkflowLaunch, WorkflowCallKind, WorkflowErrorCode, WorkflowMetadata, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
 import type { WorkflowRegistryApi } from "./registry.js";
-import { assertModelThinking, validateSchema, deepFreeze, errorText, fail, jsonObject, jsonValue, mergeWorkflowExtensionSettings, modelAliasName, modelCapability, object, positiveInteger, resolveModelReference, resourcePatternHasMagic, unknownModel } from "./utils.js";
+import { assertModelThinking, validateSchema, deepFreeze, errorText, fail, jsonObject, jsonValue, object, positiveInteger, resourcePatternHasMagic } from "./utils.js";
 import { WORKFLOW_CALL_KINDS } from "./types.js";
 export { validateSchema } from "./utils.js";
-import { loadAgentDefinitions, loadProjectAgentDefinitions } from "./roles.js";
-export { loadAgentDefinitions, loadProjectAgentDefinitions, parseRoleMarkdown, workflowRoleDirectories } from "./roles.js";
-export type { WorkflowRoleDirectoryInput } from "./roles.js";
 
 import { validateContextFileScopes, validateSelectorList } from "./settings.js";
-export { DEFAULT_SETTINGS, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath } from "./settings.js";
+export { DEFAULT_SETTINGS, loadCodemodeToolsSetting, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./settings.js";
 
 export function validateCheckpoint(value: unknown): CheckpointInput {
   if (!object(value) || Object.keys(value).some((key) => !["name", "prompt", "context"].includes(key)) || typeof value.name !== "string" || value.name.trim() === "" || typeof value.prompt !== "string" || !jsonValue(value.context)) fail("INVALID_METADATA", "checkpoint requires only name, prompt, and JSON context");
@@ -21,22 +18,6 @@ export function validateCheckpoint(value: unknown): CheckpointInput {
   return { name: value.name, prompt: value.prompt, context: value.context };
 }
 
-function validateRolePolicies(definitions: Readonly<Record<string, AgentDefinition>>, roles: readonly string[], availableModels: ReadonlySet<string>, aliases: Readonly<Record<string, string>> = {}, knownModels = availableModels, settingsPath?: string): void {
-  for (const role of roles) {
-    const definition = definitions[role];
-    if (!definition) continue;
-    if (definition.model !== undefined) {
-      const resolved = modelCapability(definition.model, aliases, knownModels, settingsPath);
-      if (!availableModels.has(resolved)) {
-        if (modelAliasName(definition.model, aliases)) unknownModel(definition.model, resolved, settingsPath);
-        fail("UNKNOWN_MODEL", `Unknown model for role ${role}: ${resolved}`);
-      }
-    }
-    // Role tools absent from the session are tolerated at launch: the runtime resolve emits a
-    // warning and the agent runs without them. Doctor still reports unmatched patterns.
-  }
-}
-
 function validateWorkflowMetadata(value: unknown): WorkflowMetadata {
   if (!object(value) || typeof value.name !== "string" || value.name.trim() === "") fail("INVALID_METADATA", "Workflow metadata requires a non-empty name");
   if (value.description !== undefined && (typeof value.description !== "string" || value.description.trim() === "")) fail("INVALID_METADATA", "Workflow description must be a non-empty string when provided");
@@ -219,6 +200,24 @@ function callHasTrailingComma(source: string, call: WorkflowCall): boolean {
   return current?.type.label === ")" && previous?.type.label === ",";
 }
 
+/**
+ * The `tools.<id>` members a workflow script names statically. Any other use of `tools`, such as a
+ * local declaration that shadows the global or passing it around, makes the set unknowable: undefined.
+ */
+export function scriptToolReferences(script: string): string[] | undefined {
+  const body = workflowBody(script);
+  if (!body.trim()) return [];
+  const names = new Set<string>();
+  const opaque = (node: acorn.AnyNode, parent?: acorn.AnyNode): boolean => {
+    if (node.type === "Identifier" && node.name === "tools") {
+      if (parent?.type === "MemberExpression" && parent.object === node && !parent.computed && parent.property.type === "Identifier") names.add(parent.property.name);
+      else if (!(parent?.type === "Property" && parent.key === node && !parent.computed && !parent.shorthand || parent?.type === "MemberExpression" && parent.property === node && !parent.computed)) return true;
+    }
+    return astChildren(node).some((child) => opaque(child, node));
+  };
+  return opaque(parseWorkflow(body)) ? undefined : [...names];
+}
+
 export function instrumentWorkflow(script: string): string {
   const body = workflowBody(script);
   if (!body.trim()) return body;
@@ -291,8 +290,9 @@ export function workflowPrompt(template: string, values: Readonly<Record<string,
   });
 }
 
-const AGENT_OPTION_KEYS = new Set(["label", "model", "tools", "skills", "extensions", "contextFiles", "role", "outputSchema", "retries", "timeoutMs"]);
-function validateAgentOption(key: string, value: unknown, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): void {
+const AGENT_OPTION_KEYS = new Set(["label", "model", "tools", "excludeTools", "skills", "extensions", "contextFiles", "outputSchema", "retries", "timeoutMs"]);
+export function isCoreAgentOption(key: string): boolean { return AGENT_OPTION_KEYS.has(key); }
+function validateAgentOption(key: string, value: unknown): void {
   switch (key) {
     case "label":
       if (typeof value !== "string" || !value.trim()) fail("INVALID_METADATA", "agent label must be a non-empty string");
@@ -300,19 +300,19 @@ function validateAgentOption(key: string, value: unknown, aliases?: Readonly<Rec
     case "model":
       if (typeof value !== "string" || !value.trim()) fail("INVALID_METADATA", "agent model must be a non-empty string");
       assertModelThinking(value, "agent model");
-      if (aliases !== undefined) resolveModelReference(value, aliases, knownModels, settingsPath);
       break;
     case "tools":
     case "skills":
     case "extensions":
       validateSelectorList(value, "agent options", key, "INVALID_METADATA", key !== "extensions");
       break;
+    case "excludeTools":
+      if (!Array.isArray(value) || value.some((tool) => typeof tool !== "string" || !tool.trim() || tool !== tool.trim() || tool.startsWith("!") || resourcePatternHasMagic(tool))) fail("INVALID_METADATA", "agent excludeTools must be an array of exact tool names");
+      if (value.includes("workflow_result")) fail("INVALID_METADATA", "agent excludeTools cannot remove workflow_result");
+      break;
     case "contextFiles":
       validateContextFileScopes(value, "agent options");
       break;
-    case "role":
-      if (typeof value !== "string" || !value.trim()) fail("INVALID_METADATA", "agent role must be a non-empty string");
-      break;
     case "outputSchema":
       validateSchema(value, "agent outputSchema");
       break;
@@ -411,36 +411,101 @@ export function inspectWorkflowScript(script: string): StaticWorkflowCall[] {
         if (value.known && jsonValue(value.value)) knownOptionEntries.push([key, value.value]);
       }
       const knownOptions: Record<string, JsonValue> = Object.fromEntries(knownOptionEntries);
-      const base = { ...placement, kind, start: call.start, end: call.end, name: null, prompt: staticString(first), model: staticString(propertyNode(options, "model")), label: staticString(propertyNode(options, "label")), role: staticString(propertyNode(options, "role")) };
+      const base = { ...placement, kind, start: call.start, end: call.end, name: null, prompt: staticString(first), model: staticString(propertyNode(options, "model")), label: staticString(propertyNode(options, "label")) };
       return { ...base, ...(retries.known && typeof retries.value === "number" ? { retries: retries.value } : {}), ...(staticOutputSchema === undefined ? {} : { outputSchema: staticOutputSchema }), ...(optionKeys.length ? { options: knownOptions, optionKeys } : {}) };
     }
-    if (kind === "checkpoint") return { ...placement, kind, start: call.start, end: call.end, name: staticString(propertyNode(first, "name")), prompt: staticString(propertyNode(first, "prompt")), model: null, role: null };
-    if (kind === "shell") return { ...placement, kind, start: call.start, end: call.end, name: staticString(first), prompt: null, model: null, role: null };
-    return { ...placement, kind, start: call.start, end: call.end, name: staticString(first), prompt: null, model: null, role: null };
+    if (kind === "checkpoint") return { ...placement, kind, start: call.start, end: call.end, name: staticString(propertyNode(first, "name")), prompt: staticString(propertyNode(first, "prompt")), model: null };
+    if (kind === "shell") return { ...placement, kind, start: call.start, end: call.end, name: staticString(first), prompt: null, model: null };
+    return { ...placement, kind, start: call.start, end: call.end, name: staticString(first), prompt: null, model: null };
   });
 }
 
-function validateStaticAgentOptions(node: acorn.AnyNode | undefined, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): void {
-  if (node?.type !== "ObjectExpression") return;
-  for (const key of AGENT_OPTION_KEYS) {
-    const value = staticValue(propertyNode(node, key));
-    if (value.known) validateAgentOption(key, value.value, aliases, knownModels, settingsPath);
+/** Every option is a preparation input, because any hook may read it; one dynamic value leaves the whole call to runtime. */
+function staticPreparationOptions(node: acorn.AnyNode | undefined, omitted?: string): Record<string, JsonValue> | undefined {
+  if (node?.type !== "ObjectExpression") return undefined;
+  const options = new Map<string, JsonValue>();
+  for (const property of node.properties) {
+    if (property.type === "SpreadElement" || property.computed) return undefined;
+    const key = propertyKeyName(property);
+    if (key === undefined) return undefined;
+    if (key === omitted) continue;
+    const value = staticValue(property.value);
+    // NOTE: an output schema only shapes the result, so a computed one (a const declared elsewhere) does not hide the call.
+    if (key === "outputSchema" && !value.known) continue;
+    if (!value.known || !jsonValue(value.value)) return undefined;
+    options.set(key, value.value);
   }
+  return Object.fromEntries(options);
+}
+/**
+ * A handle prepares its first turn with the create options merged with that send's options, so create options are complete
+ * only when every use of the handle provably passes no send options: `agent.create(...).send(prompt)` directly, or a
+ * `const` handle whose every reference is `handle.send(prompt)`. Computed access, destructuring, aliases or any other
+ * use leave the handle to runtime.
+ */
+function handlesWithCompleteOptions(program: acorn.Program): acorn.CallExpression[] {
+  const parents = new Map<acorn.AnyNode, acorn.AnyNode>();
+  const references = new Map<string, acorn.AnyNode[]>();
+  const visit = (node: acorn.AnyNode): void => {
+    if (node.type === "Identifier") references.set(node.name, [...(references.get(node.name) ?? []), node]);
+    for (const child of astChildren(node)) { parents.set(child, node); visit(child); }
+  };
+  visit(program);
+  const plainSend = (member: acorn.AnyNode | undefined): boolean => {
+    const call = member ? parents.get(member) : undefined;
+    return member?.type === "MemberExpression" && !member.computed && member.property.type === "Identifier" && member.property.name === "send"
+      && call?.type === "CallExpression" && call.callee === member && call.arguments.length <= 1 && call.arguments.every((argument) => argument.type !== "SpreadElement");
+  };
+  return agentCreateCalls(program).filter((create) => {
+    const parent = parents.get(create);
+    if (parent?.type === "MemberExpression" && parent.object === create) return plainSend(parent);
+    const declaration = parent ? parents.get(parent) : undefined;
+    if (parent?.type !== "VariableDeclarator" || parent.init !== create || parent.id.type !== "Identifier" || declaration?.type !== "VariableDeclaration" || declaration.kind !== "const") return false;
+    const name = parent.id.name;
+    return (references.get(name) ?? []).every((reference) => reference === parent.id || (parents.get(reference)?.type === "MemberExpression" && (parents.get(reference) as acorn.MemberExpression).object === reference && plainSend(parents.get(reference))));
+  });
 }
-function hasDynamicAgentRole(node: acorn.AnyNode | undefined): boolean {
-  if (!node) return false;
-  if (node.type !== "ObjectExpression") return true;
-  for (let index = node.properties.length - 1; index >= 0; index -= 1) {
-    const property = node.properties[index];
-    if (!property || property.type === "SpreadElement" || property.computed) return true;
-    const key = propertyKeyName(property);
-    if (key === "role") {
-      const roleValue = staticValue(property.value);
-      if (roleValue.known && typeof roleValue.value === "string") return false;
-      return true;
+/**
+ * Distinct, completely static option objects of agent(...) and agent.create(...) calls, so launch can inspect them
+ * before any effect. Calls with any dynamic option stay runtime-checked, and so do handles whose sends may add options.
+ */
+export function staticAgentPreparationOptions(script: string, registered: Readonly<Record<string, { run: (...args: never[]) => unknown }>> = {}): Array<Readonly<Record<string, JsonValue>>> {
+  const program = parseWorkflow(script);
+  const sources = [program, ...registeredFunctionPrograms(program, registered)];
+  const distinct = new Map<string, Readonly<Record<string, JsonValue>>>();
+  for (const source of sources) for (const options of programAgentOptions(source)) distinct.set(JSON.stringify(options), deepFreeze(options));
+  return [...distinct.values()];
+}
+/** Programs of the registered functions the script calls by name, so their agents are inspected before launch like inline ones. */
+function registeredFunctionPrograms(program: acorn.Program, registered: Readonly<Record<string, { run: (...args: never[]) => unknown }>>): acorn.Program[] {
+  const called = new Set<string>();
+  const visit = (node: acorn.AnyNode): void => {
+    if (node.type === "CallExpression" && node.callee.type === "Identifier" && Object.prototype.hasOwnProperty.call(registered, node.callee.name)) called.add(node.callee.name);
+    for (const child of astChildren(node)) visit(child);
+  };
+  visit(program);
+  const programs: acorn.Program[] = [];
+  for (const name of called) {
+    const source = registered[name]?.run.toString() ?? "";
+    // A method prints as `async run(...) {}`, which only parses inside an object literal.
+    for (const wrapped of [`(${source})`, `({${source}})`]) {
+      try { programs.push(acorn.parse(wrapped, { ecmaVersion: "latest", sourceType: "module" })); break; } catch { /* try the next form; an unparsable function stays runtime-checked */ }
     }
   }
-  return false;
+  return programs;
+}
+function programAgentOptions(program: acorn.Program): Array<Readonly<Record<string, JsonValue>>> {
+  const calls = workflowCalls(program).filter((call) => call.callee.name === "agent").map((call) => call.arguments.some((argument) => argument.type === "SpreadElement") ? undefined : call.arguments.length < 2 ? {} : staticPreparationOptions(callArgument(call, 1)));
+  const handles = handlesWithCompleteOptions(program).map((call) => staticPreparationOptions(callArgument(call, 0), "name"));
+  return [...calls, ...handles].filter((options): options is Record<string, JsonValue> => options !== undefined);
+}
+
+function validateStaticAgentOptions(node: acorn.AnyNode | undefined): void {
+  if (node?.type !== "ObjectExpression") return;
+  for (const key of AGENT_OPTION_KEYS) {
+    const value = staticValue(propertyNode(node, key));
+    if (value.known) validateAgentOption(key, value.value);
+  }
 }
 function validateStaticShellOptions(call: WorkflowCall): void {
   if (call.arguments.some((argument) => argument.type === "SpreadElement")) return;
@@ -477,7 +542,7 @@ export function preflight(script: string, capabilities: PreflightCapabilities, s
   const phases = calls.filter((call) => call.callee.name === "phase").map((call) => literalString(call.arguments[0])).filter((phase): phase is string => phase !== undefined);
   for (const call of calls) {
     const operation = call.callee.name;
-    if (operation === "agent") validateStaticAgentOptions(call.arguments[1], capabilities.modelAliases ?? {}, capabilities.knownModels ?? capabilities.models, capabilities.settingsPath);
+    if (operation === "agent") validateStaticAgentOptions(call.arguments[1]);
     if (operation === "withWorktree") validateStaticWithWorktree(call, compatibility);
     if (operation === "shell") validateStaticShellOptions(call);
     if ((operation === "parallel" || operation === "pipeline") && call.arguments.some((argument) => argument.type === "SpreadElement")) continue;
@@ -488,11 +553,10 @@ export function preflight(script: string, capabilities: PreflightCapabilities, s
   const handleOptions = agentCreateCalls(program).map((call) => {
     const options = call.arguments.length === 1 ? callArgument(call, 0) : undefined;
     if (options?.type !== "ObjectExpression" || !literalString(propertyNode(options, "name"))?.trim()) fail("INVALID_METADATA", "agent.create requires an options object with a stable explicit name");
-    validateStaticAgentOptions(options, capabilities.modelAliases ?? {}, capabilities.knownModels ?? capabilities.models, capabilities.settingsPath);
+    validateStaticAgentOptions(options);
     return options;
   });
   const agentOptions = [...calls.filter((call) => call.callee.name === "agent").map((call) => callArgument(call, 1)), ...handleOptions];
-  const dynamicAgentRoles = agentOptions.some((options) => hasDynamicAgentRole(options));
   const staticSchemas: JsonSchema[] = [];
   for (const options of agentOptions) {
     const value = staticValue(propertyNode(options, "outputSchema"));
@@ -502,25 +566,16 @@ export function preflight(script: string, capabilities: PreflightCapabilities, s
     staticSchemas.push(schema);
   }
   checkedSchemas.push(...staticSchemas);
-  const modelRefs = agentOptions.flatMap((options) => { const requested = literalString(propertyNode(options, "model")); return requested === undefined ? [] : [{ requested, resolved: modelCapability(requested, capabilities.modelAliases, capabilities.knownModels ?? capabilities.models, capabilities.settingsPath) }]; });
-  const models = modelRefs.map(({ resolved }) => resolved);
+  const models: string[] = [];
   const tools = agentOptions.flatMap((options) => {
     const value = propertyNode(options, "tools");
     return value?.type === "ArrayExpression" ? value.elements.flatMap((element) => { const tool = element && element.type !== "SpreadElement" ? literalString(element) : undefined; return tool === undefined ? [] : [tool]; }) : [];
   });
-  const agentTypes = agentOptions.flatMap((options) => { const value = staticString(propertyNode(options, "role")); return value === null ? [] : [value]; });
   for (const pattern of tools) {
     const body = pattern.startsWith("!") ? pattern.slice(1) : pattern;
     if (!pattern.startsWith("!") && !resourcePatternHasMagic(pattern) && !capabilities.tools.has(body)) fail("UNKNOWN_TOOL", `Unknown tool: ${body}`);
   }
-  const missingModel = capabilities.skipModelAvailability ? undefined : modelRefs.find(({ resolved }) => !capabilities.models.has(resolved));
-  if (missingModel) {
-    if (modelAliasName(missingModel.requested, capabilities.modelAliases ?? {})) unknownModel(missingModel.requested, missingModel.resolved, capabilities.settingsPath);
-    fail("UNKNOWN_MODEL", `Unknown model: ${missingModel.resolved}`);
-  }
-  const missingType = agentTypes.find((type) => !capabilities.agentTypes.has(type));
-  if (missingType) fail("UNKNOWN_AGENT_TYPE", `Unknown agent type: ${missingType}`);
-  return Object.freeze({ metadata: deepFreeze(checkedMetadata), referenced: deepFreeze({ phases, models, tools, agentTypes }), schemas: deepFreeze(checkedSchemas), dynamicAgentRoles });
+  return Object.freeze({ metadata: deepFreeze(checkedMetadata), referenced: deepFreeze({ phases, models, tools }), schemas: deepFreeze(checkedSchemas) });
 }
 
 export function validateWorkflowLaunch(params: WorkflowValidationParameters, context: WorkflowValidationContext, registry?: WorkflowRegistryApi): ValidatedWorkflowLaunch {
@@ -544,23 +599,9 @@ export function validateWorkflowLaunchWithRegistry(params: WorkflowValidationPar
   const script = typeof params.script === "string" && params.script.trim() ? params.script : fileScript ?? "";
   if (!script) fail("INVALID_SYNTAX", "Provide script or scriptPath");
   const metadata = validateWorkflowMetadata({ name: explicitName, ...(typeof params.description === "string" ? { description: params.description } : {}) });
-  const globalAgentDefinitions = loadAgentDefinitions(context.cwd, context.agentDir, false, registry && typeof registry.roleDirectoryRegistrations === "function" ? registry.roleDirectoryRegistrations() : registry && typeof registry.roleDirectories === "function" ? registry.roleDirectories() : undefined);
-  const projectAgentDefinitions = context.projectTrusted ? loadProjectAgentDefinitions(context.cwd) : {};
-  const agentDefinitions = deepFreeze({ ...globalAgentDefinitions, ...projectAgentDefinitions });
-  const aliases = context.modelAliases ?? {};
-  const knownModels = context.knownModels ?? context.availableModels;
-  const checked = preflight(script, { models: context.availableModels, tools: context.rootTools, agentTypes: new Set(Object.keys(agentDefinitions)), modelAliases: aliases, knownModels, ...(context.settingsPath ? { settingsPath: context.settingsPath } : {}) }, [], metadata);
-  const roleNames = checked.dynamicAgentRoles ? Object.keys(agentDefinitions) : checked.referenced.agentTypes;
-  validateRolePolicies(agentDefinitions, roleNames, context.availableModels, aliases, knownModels, context.settingsPath);
-  if (registry?.validateExtensionSettings) {
-    const validate = registry.validateExtensionSettings.bind(registry);
-    const validatorContext = (source: "effective" | "role", role?: string) => ({ source, cwd: context.cwd, projectTrusted: context.projectTrusted, ...(context.settingsPath ? { settingsPath: context.settingsPath } : {}), ...(role === undefined ? {} : { role }) });
-    validate(context.extensionSettings, validatorContext("effective"));
-    for (const role of roleNames) {
-      validate(mergeWorkflowExtensionSettings(context.extensionSettings, agentDefinitions[role]?.extensionSettings), validatorContext("role", role));
-    }
-  }
-  return { script, checked, agentDefinitions, projectAgentDefinitions, roleNames };
+  const checked = preflight(script, { models: context.availableModels, tools: context.rootTools, modelAliases: context.modelAliases ?? {}, knownModels: context.knownModels ?? context.availableModels, ...(context.settingsPath ? { settingsPath: context.settingsPath } : {}) }, [], metadata);
+  registry?.validateExtensionSettings(context.extensionSettings, { source: "effective", cwd: context.cwd, projectTrusted: context.projectTrusted, ...(context.settingsPath ? { settingsPath: context.settingsPath } : {}) });
+  return { script, checked };
 }
 
 export { createLaunchSnapshot, loadLaunchSnapshot } from "./utils.js";

package/starter/index.ts

@@ -27,7 +27,6 @@ const extension: WorkflowExtension = {
       resolve: ({ rootModel }) => `${rootModel.provider}/${rootModel.model}`,
     },
   },
-  roleDirectories: [new URL("./roles/", import.meta.url)],
 };
 
 export default function (): void {

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 };
@@ -69,5 +70,3 @@ export const reviewLoop = defineWorkflowFunction({
   ),
 });
 
-export const reviewLoopInputSchema = reviewLoop.input;
-export const reviewLoopOutputSchema = reviewLoop.output;

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,23 +44,23 @@ 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_inspect` | `{ id?: string }` |
+| `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 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`.
+`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`.
 
 ## Launching and concurrency
 
@@ -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,18 +29,19 @@ 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" })),
+  scope: Type.Optional(Type.Union([Type.Literal("session"), Type.Literal("all")], { description: "List scope when id is omitted: session (default) lists runs from the current Pi session; all lists every stored run" })),
 }, { additionalProperties: false });
 
 export const SUBAGENTS_ID_PARAMETERS = Type.Object({
@@ -60,15 +61,25 @@ export const SUBAGENTS_RETRY_PARAMETERS = Type.Object({
   id: Type.String({ description: "Failed or stopped subagent ID to retry" }),
 }, { additionalProperties: false });
 
-export const SUBAGENTS_TOOL_SCHEMAS = {
-  subagents_run: SUBAGENTS_RUN_PARAMETERS,
-  subagents_inspect: SUBAGENTS_INSPECT_PARAMETERS,
-  subagents_steer: SUBAGENTS_STEER_PARAMETERS,
-  subagents_stop: SUBAGENTS_STOP_PARAMETERS,
-  subagents_retry: SUBAGENTS_RETRY_PARAMETERS,
-} as const;
+// Structured results codemode scripts receive instead of the JSON text; nested records stay loose so they cannot drift from persistence.
+export const SUBAGENT_STATUS_OUTPUT = Type.Object({
+  id: Type.String(),
+  state: Type.String(),
+  sessionId: Type.Optional(Type.String()),
+  startedAt: Type.Optional(Type.Number()),
+  finishedAt: Type.Optional(Type.Number()),
+  attempts: Type.Optional(Type.Number()),
+  attemptDetails: Type.Optional(Type.Array(Type.Unknown())),
+  worktree: Type.Optional(Type.Object({ path: Type.String(), branch: Type.String() })),
+  error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String() })),
+  progress: Type.Optional(Type.Unknown()),
+  value: Type.Optional(Type.Unknown()),
+});
+// One run when id is given, otherwise the ordered run summaries; the summaries stay short in the codemode description.
+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");
@@ -103,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 };
 }