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

package/src/types.ts

@@ -27,29 +27,30 @@ export const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
 export const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
 export const WORKFLOW_BLOCKED_EVENT = "workflow:blocked";
 export const ERROR_CODES = [
-  "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE",
+  "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT",
   "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID",
   "TOOL_FAILED", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
   ] as const;
 
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export const CONTEXT_FILE_SCOPES = ["global", "project", "cwd"] as const;
+export type ContextFileScope = (typeof CONTEXT_FILE_SCOPES)[number];
+export function isContextFileScope(value: unknown): value is ContextFileScope { return CONTEXT_FILE_SCOPES.some((scope) => scope === value); }
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export type JsonSchema = { [key: string]: JsonValue };
 type WorkflowSchema = JsonSchema | TSchema;
-export function roleNameOf(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}
 // Extra keys are reserved for extensions and forwarded as JSON to agentOptions; core options remain typed.
 export interface AgentOptions<Schema extends TSchema = never> {
   label?: string;
   model?: string;
   tools?: string[];
+  /** Exact tool names removed after preparation hooks; never widens the parent ceiling. */
+  excludeTools?: string[];
   skills?: string[];
   extensions?: string[];
   contextFiles?: ContextFileScope[];
-  role?: string;
   outputSchema?: JsonSchema | Schema;
   retries?: number;
   timeoutMs?: number | null;
@@ -80,7 +81,7 @@ export type WorkflowRunResumedEvent = WorkflowEventBase;
 export interface WorkflowRunStateChangedEvent extends WorkflowEventBase { previousState: RunState; state: RunState; reason?: string; errorCode?: WorkflowErrorCode }
 export interface WorkflowRunCompletedEvent extends WorkflowEventBase { resultPath: string }
 export interface WorkflowRunFailedEvent extends WorkflowEventBase { error: WorkflowErrorShape }
-export interface WorkflowAgentStateChangedEvent extends WorkflowEventBase { agentId: string; displayLabel: string; role?: string; structuralPath: readonly string[]; parentId?: string; parentBreadcrumb?: string; worktreeOwner?: string; previousState?: AgentState; state: AgentState; attempt: number }
+export interface WorkflowAgentStateChangedEvent extends WorkflowEventBase { agentId: string; displayLabel: string; structuralPath: readonly string[]; parentId?: string; parentBreadcrumb?: string; worktreeOwner?: string; previousState?: AgentState; state: AgentState; attempt: number }
 export interface WorkflowPhaseChangedEvent extends WorkflowEventBase { previousPhase?: string; phase: string }
 export type WorkflowCheckpointState = "awaiting" | "approved" | "rejected";
 export interface WorkflowCheckpointStateChangedEvent extends WorkflowEventBase { name: string; state: WorkflowCheckpointState }
@@ -92,8 +93,8 @@ export interface WorkflowMetadata { name: string; description?: string }
 export interface HerdrExtensionSettings { enableFullyInspectableMode?: boolean }
 export interface TrajectoryExtensionSettings { port?: number }
 export interface WorkflowExtensionSettings { readonly [namespace: string]: JsonValue; readonly herdr?: Readonly<HerdrExtensionSettings>; readonly trajectory?: Readonly<TrajectoryExtensionSettings> }
-export type WorkflowExtensionSettingsSource = "global" | "project" | "role" | "effective";
-export interface WorkflowExtensionSettingsValidatorContext { source: WorkflowExtensionSettingsSource; cwd: string; projectTrusted: boolean; settingsPath?: string; role?: string }
+export type WorkflowExtensionSettingsSource = "global" | "project" | "effective";
+export interface WorkflowExtensionSettingsValidatorContext { source: WorkflowExtensionSettingsSource; cwd: string; projectTrusted: boolean; settingsPath?: string }
 export type WorkflowExtensionSettingsValidator = (settings: Readonly<WorkflowExtensionSettings>, context: Readonly<WorkflowExtensionSettingsValidatorContext>) => void;
 export interface WorkflowSessionStartEvent { type: "session_start"; reason: "startup" | "reload" | "new" | "resume" | "fork"; previousSessionFile?: string; settings: Readonly<WorkflowExtensionSettings> }
 export interface WorkflowRetentionSettings { olderThanDays?: number; maxTerminalRuns?: number }
@@ -101,14 +102,12 @@ export type CodemodeToolsSetting = "all" | "read-only" | "none";
 export interface WorkflowSettings { concurrency: number; backgroundWidget?: boolean; codemodeTools?: CodemodeToolsSetting; modelAliases?: Readonly<Record<string, string>>; skills?: readonly string[]; extensions?: readonly string[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; tools?: readonly string[]; retention?: Readonly<WorkflowRetentionSettings>; worktreePostCreateCommand?: readonly string[] }
 export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget" | "codemodeTools">>;
 export interface WorkflowSettingsSources { concurrency: string; modelAliases: string; skills?: string; extensions?: string; tools?: string; extensionSettings?: string; retention?: string; worktreePostCreateCommand?: string }
-export interface WorkflowSettingsResolution { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: Readonly<WorkflowSettings>; project: Readonly<WorkflowSettingsOverrides>; effective: Readonly<WorkflowSettings>; sources: Readonly<WorkflowSettingsSources> }
+export interface WorkflowSettingsResolution { selectorSources?: AgentResourceSelectorSources; globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: Readonly<WorkflowSettings>; project: Readonly<WorkflowSettingsOverrides>; effective: Readonly<WorkflowSettings>; sources: Readonly<WorkflowSettingsSources> }
 export interface AgentResourceSelectors { skills?: readonly string[]; extensions?: readonly string[]; tools?: readonly string[] }
 export interface AgentResourceSelectorSet { skills: readonly string[]; extensions: readonly string[]; tools?: readonly string[] }
-export interface AgentResourceSelectorSources { global: AgentResourceSelectors; project: AgentResourceSelectors; role?: AgentResourceSelectors; call?: AgentResourceSelectors }
-export const CONTEXT_FILE_SCOPES = ["global", "project", "cwd"] as const;
-export type ContextFileScope = (typeof CONTEXT_FILE_SCOPES)[number];
-export function isContextFileScope(value: unknown): value is ContextFileScope { return CONTEXT_FILE_SCOPES.some((scope) => scope === value); }
+export interface AgentResourceSelectorSources { global: AgentResourceSelectors; project: AgentResourceSelectors; call?: AgentResourceSelectors }
 export interface AgentResourcePolicy {
+  capabilities?: Readonly<{ tools: readonly string[]; skills: readonly string[]; extensions: readonly string[] }>;
   globalSettingsPath: string;
   projectSettingsPath: string;
   projectTrusted: boolean;
@@ -122,6 +121,8 @@ export interface AgentResourcePolicy {
   unmatchedExtensions: readonly string[];
   unmatchedTools?: readonly string[];
   selectorSources: AgentResourceSelectorSources;
+  /** Skills loaded by the parent session; ceiling for skills that extensions contribute through resources_discover. Absent for top-level agents. */
+  parentSkills?: readonly string[];
 }
 export interface AgentResourceInspection { selectors: AgentResourceSelectorSet; skills: readonly string[]; extensions: readonly string[]; tools: readonly string[]; unmatchedSkills: readonly string[]; unmatchedExtensions: readonly string[]; unmatchedTools: readonly string[]; selectorSources?: AgentResourceSelectorSources }
 
@@ -158,7 +159,6 @@ export interface AgentRecord {
   handle?: string;
   turn?: number;
   continuity?: AgentContinuity;
-  role?: string;
   requestedModel?: string;
   model: ModelSpec;
   tools: readonly string[];
@@ -208,11 +208,10 @@ export interface RunRecord {
   events?: readonly WorkflowRunEvent[];
   delivery?: WorkflowRunDelivery;
 }
-export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 6;
 export type WorkflowLaunchMode = "foreground" | "background";
-export interface AgentDefinition { prompt?: string; description?: string; model?: string; thinking?: NonNullable<ModelSpec["thinking"]>; tools?: readonly string[]; skills?: readonly string[]; extensions?: readonly string[]; overrideSystemPrompt?: boolean; contextFiles?: readonly ContextFileScope[]; extensionSettings?: Readonly<WorkflowExtensionSettings> }
 export interface LaunchSnapshot {
-  identityVersion?: number;
+  identityVersion: number;
   launchMode?: WorkflowLaunchMode;
   script: string;
   args: JsonValue;
@@ -225,14 +224,18 @@ export interface LaunchSnapshot {
   phases?: readonly string[];
   models: readonly string[];
   tools: readonly string[];
-  agentTypes: readonly string[];
-  roles?: Readonly<Record<string, AgentDefinition>>;
-  projectRoles?: readonly string[];
+  agentConfigurations: Readonly<Record<string, PreparedAgentConfiguration>>;
   schemas: readonly JsonSchema[];
 }
-export interface PreflightCapabilities { models: ReadonlySet<string>; tools: ReadonlySet<string>; agentTypes: ReadonlySet<string>; modelAliases?: Readonly<Record<string, string>>; knownModels?: ReadonlySet<string>; settingsPath?: string; skipModelAvailability?: boolean }
-export interface PreflightResult { metadata: WorkflowMetadata; referenced: { phases: readonly string[]; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[] }; schemas: readonly JsonSchema[]; dynamicAgentRoles: boolean }
-export interface WorkflowOrchestrationContext { agent: { <Schema extends TSchema>(prompt: string, options: Readonly<AgentOptions<Schema> & { outputSchema: Schema }>): Promise<Static<Schema>>; (prompt: string, options?: Readonly<AgentOptions>): Promise<JsonValue> }; shell: (command: string, options?: ShellOptions) => Promise<ShellResult>; prompt: (template: string, values: Readonly<Record<string, JsonValue>>) => string; parallel: <Tasks extends ParallelTasks>(operationName: string, tasks: Tasks) => Promise<ParallelResult<Tasks>>; pipeline: <Items extends PipelineItems, Output extends JsonValue>(operationName: string, items: Items, stages: PipelineStages<Items[keyof Items], Output>) => Promise<PipelineResult<Items, Output>>; withWorktree: <Result extends JsonValue>(name: string, callback: WorkflowWorktreeCallback<Result>) => Promise<Result>; checkpoint: (input: CheckpointInput) => Promise<boolean>; phase: (name: string) => void; log: (message: string) => void }
+export interface PreflightCapabilities { models: ReadonlySet<string>; tools: ReadonlySet<string>; modelAliases?: Readonly<Record<string, string>>; knownModels?: ReadonlySet<string>; settingsPath?: string; skipModelAvailability?: boolean }
+export interface PreflightResult { metadata: WorkflowMetadata; referenced: { phases: readonly string[]; models: readonly string[]; tools: readonly string[]; }; schemas: readonly JsonSchema[] }
+export interface AgentHandleSendOptions<Schema extends TSchema = never> { outputSchema?: JsonSchema | Schema; timeoutMs?: number | null }
+/** A persistent agent: each send continues the transcript of the previous completed turn. Sends must be awaited one at a time, in the scope that created the handle. */
+export interface AgentHandle {
+  readonly name: string;
+  send: { <Schema extends TSchema>(prompt: string, options: Readonly<AgentHandleSendOptions<Schema> & { outputSchema: Schema }>): Promise<Static<Schema>>; (prompt: string, options?: Readonly<AgentHandleSendOptions>): Promise<JsonValue> };
+}
+export interface WorkflowOrchestrationContext { agent: { <Schema extends TSchema>(prompt: string, options: Readonly<AgentOptions<Schema> & { outputSchema: Schema }>): Promise<Static<Schema>>; (prompt: string, options?: Readonly<AgentOptions>): Promise<JsonValue>; create: (options: Readonly<AgentOptions & { name: string }>) => AgentHandle }; shell: (command: string, options?: ShellOptions) => Promise<ShellResult>; prompt: (template: string, values: Readonly<Record<string, JsonValue>>) => string; parallel: <Tasks extends ParallelTasks>(operationName: string, tasks: Tasks) => Promise<ParallelResult<Tasks>>; pipeline: <Items extends PipelineItems, Output extends JsonValue>(operationName: string, items: Items, stages: PipelineStages<Items[keyof Items], Output>) => Promise<PipelineResult<Items, Output>>; withWorktree: <Result extends JsonValue>(name: string, callback: WorkflowWorktreeCallback<Result>) => Promise<Result>; checkpoint: (input: CheckpointInput) => Promise<boolean>; phase: (name: string) => void; log: (message: string) => void }
 export interface WorkflowRunContext { cwd: string; sessionId: string; runId: string; workflow: Readonly<WorkflowMetadata>; args: JsonValue; signal: AbortSignal }
 export interface WorkflowFunctionContext extends WorkflowOrchestrationContext { run: Readonly<WorkflowRunContext>; settings: Readonly<WorkflowExtensionSettings>; invoke: (name: string, input: Readonly<Record<string, JsonValue>>, label?: string) => Promise<JsonValue> }
 export type WorkflowWorktreeCallback<Result extends JsonValue = JsonValue> = (reference: Readonly<WorkflowWorktreeReference>) => Result | Promise<Result>;
@@ -267,6 +270,8 @@ export interface WorkflowAgentSession {
   getState(): Readonly<WorkflowAgentSessionState>;
   getSessionStats(): WorkflowAgentSessionStats;
   getLastAssistant(): WorkflowAgentMessage | undefined;
+  /** Set by a transport that already delivered `PreparedAgentSession.turnControl` itself; otherwise the runner steers it before the first prompt. */
+  readonly turnControlDelivered?: boolean;
   subscribe(listener: (event: WorkflowAgentSessionEvent) => void): () => void;
   subscribeAsync?(listener: (event: WorkflowAgentSessionEvent) => void | Promise<void>): () => void;
   prompt(text: string): Promise<WorkflowAgentTurnResult>;
@@ -280,7 +285,8 @@ export interface WorkflowAgentSession {
 type SessionTools = NonNullable<CreateAgentSessionOptions["tools"]>;
 type SessionCustomTools = NonNullable<CreateAgentSessionOptions["customTools"]>;
 export interface SessionInput {
-  cwd: string;
+  /** Read-only: setup hooks cannot move an agent, because Pi derives trust, settings and `.pi` resources from cwd. */
+  readonly cwd: string;
   model: ModelSpec;
   tools: SessionTools;
   sessionLabel: string;
@@ -309,6 +315,8 @@ export interface PreparedAgentSession {
   readonly sessionLabel: string;
   readonly sessionPath?: string;
   readonly initialPrompt?: string;
+  /** Dynamic per-attempt control text (retry state, budget). The runner steers it before the first prompt unless the session reports `turnControlDelivered`. */
+  readonly turnControl?: string;
   readonly agentDir?: string;
   readonly customTools?: readonly ToolDefinition[];
   readonly resultTool?: ToolDefinition;
@@ -330,17 +338,50 @@ export interface AgentTransport { readonly id: string; createSession(prepared: R
 export interface AgentSetup { prompt: string; options: AgentOptions; sessionInput: SessionInput; prepared: Readonly<PreparedAgentSession>; transport: AgentTransport }
 export interface AgentSetupContext { readonly run: Readonly<WorkflowRunContext>; readonly identity: Readonly<AgentIdentity>; readonly attempt: number; readonly signal: AbortSignal; readonly tuiIndex?: number; readonly tuiLabel?: string; readonly mode?: AgentInspectionMode; readonly settings: Readonly<WorkflowExtensionSettings> }
 
+export interface AgentPreparation {
+  label?: string;
+  model?: string;
+  tools: string[];
+  skills: string[];
+  extensions: string[];
+  contextFiles?: ContextFileScope[];
+  systemPrompt?: string;
+  systemPromptAppend: string;
+  settings: WorkflowExtensionSettings;
+}
+export interface AgentPreparationContext {
+  readonly options: Readonly<AgentOptions>;
+  readonly cwd: string;
+  /** Launch project root that owns project configuration; differs from `cwd` inside worktree scopes. Optional for older hosts. */
+  readonly projectCwd?: string;
+  readonly agentDir: string;
+  readonly projectTrusted: boolean;
+  /** `dynamicModelAliasNames` lists the `modelAliases` entries resolved by extensions rather than read from static settings. */
+  readonly defaults: Readonly<{ model: ModelSpec; modelAliases: Readonly<Record<string, string>>; dynamicModelAliasNames?: readonly string[]; selectorSources: AgentResourceSelectorSources; settings: Readonly<WorkflowExtensionSettings> }>;
+  readonly capabilities: Readonly<{ tools: readonly string[]; skills: readonly string[]; extensions: readonly string[] }>;
+  readonly knownModels: ReadonlySet<string>;
+  readonly availableModels: ReadonlySet<string>;
+  readonly signal: AbortSignal;
+  readonly mode: AgentInspectionMode;
+}
+export interface AgentPreparationHook { priority?: number; optionsSchema?: JsonSchema; prepare: (configuration: AgentPreparation, context: Readonly<AgentPreparationContext>) => void | Promise<void> }
+/** `source` is the registering extension's module provenance, when it declared one. */
+export interface RegisteredAgentPreparationHook { name: string; priority: number; optionsSchema?: JsonSchema; source?: string; prepare: AgentPreparationHook["prepare"] }
+/**
+ * `excludeTools` holds the exact tool names the agent and its ancestors excluded, frozen with the configuration so setup and
+ * children apply them even when re-evaluated options change. It is absent only in configurations prepared before it existed, which cannot resume.
+ */
+export interface PreparedAgentConfiguration extends Omit<AgentPreparation, "model"> { model: ModelSpec; projectTrusted: boolean; excludeTools?: string[] }
 export interface AgentSetupHook { priority?: number; setup: (agent: AgentSetup, context: Readonly<AgentSetupContext>) => void | Promise<void> }
 export interface RegisteredAgentSetupHook { name: string; priority: number; setup: AgentSetupHook["setup"] }
 export interface WorkflowExtensionMetadata { version: string; headline: string }
 export interface WorkflowFunctionSource { readonly module: string; readonly export: string; readonly dependencies: readonly string[] }
-export interface WorkflowRoleDirectoryRegistration { path: string; extension: WorkflowExtensionMetadata; readonly builtin?: true }
 export interface AgentAttemptActionUi { notify(message: string, level?: "info" | "warning" | "error"): void; confirm(title: string, message: string): Promise<boolean>; select(title: string, options: readonly string[]): Promise<string | undefined>; input(title: string, placeholder?: string): Promise<string | undefined>; setWorkingMessage?(message?: string): void }
 export interface StandaloneAgentRecord { readonly id: string; readonly name: string; readonly label?: string; readonly state: "running" | "completed" | "failed" | "stopped"; readonly structuralPath?: readonly string[] }
 export interface StandaloneAgentAttemptActionContext { readonly agent: Readonly<StandaloneAgentRecord>; readonly attempt: Readonly<AgentAttemptSummary>; readonly session?: WorkflowAgentSessionReference; readonly liveSession?: WorkflowAgentSession; readonly prepared?: Readonly<PreparedAgentSession>; readonly handoff?: LiveSessionHandoff; readonly signal: AbortSignal; readonly ui: Readonly<AgentAttemptActionUi> }
 export interface AgentAttemptActionContext { readonly run: Readonly<RunRecord>; readonly agent: Readonly<AgentRecord>; readonly attempt: Readonly<AgentAttemptSummary>; readonly session?: WorkflowAgentSessionReference; readonly liveSession?: WorkflowAgentSession; readonly prepared?: Readonly<PreparedAgentSession>; readonly handoff?: LiveSessionHandoff; readonly signal: AbortSignal; readonly ui: Readonly<AgentAttemptActionUi> }
 export interface AgentAttemptAction { readonly label: string; visible(context: Readonly<AgentAttemptActionContext>): boolean; run(context: Readonly<AgentAttemptActionContext>): void | Promise<void>; visibleStandalone?(context: Readonly<StandaloneAgentAttemptActionContext>): boolean; runStandalone?(context: Readonly<StandaloneAgentAttemptActionContext>): void | Promise<void> }
-export interface WorkflowExtension extends WorkflowExtensionMetadata { description?: string; source?: string; dependencies?: readonly string[]; validateSettings?: WorkflowExtensionSettingsValidator; functions?: Readonly<Record<string, WorkflowFunction>>; modelAliases?: Readonly<Record<string, WorkflowModelAlias>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>; agentAttemptActions?: Readonly<Record<string, AgentAttemptAction>>; roleDirectories?: readonly (string | URL)[] }
+export interface WorkflowExtension extends WorkflowExtensionMetadata { description?: string; source?: string; dependencies?: readonly string[]; validateSettings?: WorkflowExtensionSettingsValidator; functions?: Readonly<Record<string, WorkflowFunction>>; modelAliases?: Readonly<Record<string, WorkflowModelAlias>>; agentPreparationHooks?: Readonly<Record<string, AgentPreparationHook>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>; agentAttemptActions?: Readonly<Record<string, AgentAttemptAction>> }
 export interface WorkflowJournal { get(path: string): JsonValue | undefined; put(path: string, value: JsonValue): void }
 // The brand keeps instanceof working across the bundled extension entries, which each inline their own copy of this class.
 const WORKFLOW_ERROR_BRAND = Symbol.for("pi-extensible-workflows.workflow-error");
@@ -353,8 +394,8 @@ export class WorkflowError extends Error {
   }
 }
 Object.defineProperty(WorkflowError, WORKFLOW_ERROR_BRAND, { value: true });
-export interface WorkflowFailureAgent { id: string; label?: string; role?: string; structuralPath: readonly string[]; attempt: number; transport?: string; session?: WorkflowAgentSessionReference }
-export interface WorkflowSiblingAgent { id: string; label?: string; role?: string; structuralPath: readonly string[] }
+export interface WorkflowFailureAgent { id: string; label?: string; structuralPath: readonly string[]; attempt: number; transport?: string; session?: WorkflowAgentSessionReference }
+export interface WorkflowSiblingAgent { id: string; label?: string; structuralPath: readonly string[] }
 export interface WorkflowFailureDiagnostics { runId: string; workflowName: string; state: RunState; failedAt: string | null; error: WorkflowErrorShape; failedAgent?: WorkflowFailureAgent; completedSiblingAgents?: readonly WorkflowSiblingAgent[]; completedSiblingPaths: readonly (readonly string[])[]; retry?: { sourceRunId: string; action: string; completedPaths: readonly string[]; incompletePaths: readonly string[]; namedWorktrees: readonly string[]; warning: string }; artifacts: { runDirectory: string; statePath: string; journalPath: string } }
 export interface CheckpointInput { name: string; prompt: string; context: JsonValue }
 export interface FunctionIdentity { path: string; structuralPath: readonly string[]; occurrence: number; worktreeOwner?: string }
@@ -367,7 +408,7 @@ export interface WorkflowBridge { agent?: (prompt: string, options: Readonly<Rec
 export interface WorkflowExecution { result: Promise<JsonValue>; cancel: () => void }
 export interface StaticWorkflowScope { kind: "parallel" | "pipeline"; name: string | null; key: string | null }
 export type StaticWorkflowExecution = "parallel" | "sequential";
-export interface StaticWorkflowCall { kind: WorkflowCallKind; start: number; end: number; name: string | null; prompt: string | null; model: string | null; label?: string | null; role: string | null; retries?: number | null; outputSchema?: JsonSchema | null; options?: Readonly<Record<string, JsonValue>> | null; optionKeys?: readonly string[]; execution?: StaticWorkflowExecution; structure?: readonly StaticWorkflowScope[] }
+export interface StaticWorkflowCall { kind: WorkflowCallKind; start: number; end: number; name: string | null; prompt: string | null; model: string | null; label?: string | null; retries?: number | null; outputSchema?: JsonSchema | null; options?: Readonly<Record<string, JsonValue>> | null; optionKeys?: readonly string[]; execution?: StaticWorkflowExecution; structure?: readonly StaticWorkflowScope[] }
 export interface WorkflowCatalogFunction { name: string; version: string; headline: string; description: string; input: JsonSchema; output: JsonSchema }
 export interface WorkflowCatalogModelAlias { name: string; kind: "static" | "dynamic"; provenance: string; version?: string; headline?: string }
 export interface WorkflowCatalogSettings { concurrency: number; backgroundWidget: boolean; modelAliases: Readonly<Record<string, string>>; skills: readonly string[]; extensions: readonly string[]; tools: readonly string[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; worktreePostCreateCommand?: readonly string[]; globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; sources: WorkflowSettingsSources }
@@ -378,4 +419,4 @@ export interface WorkflowCatalogIndex { functions: readonly WorkflowCatalogIndex
 export interface WorkflowCatalogError { error: { code: "NOT_FOUND"; name: string; message: string } }
 export interface WorkflowValidationParameters { name: string; description?: string; script?: string; scriptPath?: string; args?: unknown }
 export interface WorkflowValidationContext { cwd: string; projectTrusted: boolean; availableModels: ReadonlySet<string>; rootTools: ReadonlySet<string>; modelAliases?: Readonly<Record<string, string>>; knownModels?: ReadonlySet<string>; settingsPath?: string; agentDir?: string; extensionSettings?: Readonly<WorkflowExtensionSettings> }
-export interface ValidatedWorkflowLaunch { script: string; checked: PreflightResult; agentDefinitions: Readonly<Record<string, AgentDefinition>>; projectAgentDefinitions: Readonly<Record<string, AgentDefinition>>; roleNames: readonly string[] }
+export interface ValidatedWorkflowLaunch { script: string; checked: PreflightResult }

package/src/utils.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
-import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WorkflowError, type JsonSchema, type JsonValue, type ModelSpec, type ThinkingLevel, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError, type JsonSchema, type JsonValue, type ModelSpec, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
 import { Minimatch } from "minimatch";
+import { THINKING_LEVELS, type ThinkingLevel } from "./types.js";
 export class SerialLane {
   #tail: Promise<void> = Promise.resolve();
   run<T>(task: () => Promise<T>): Promise<T> {
@@ -92,11 +93,19 @@ export const WORKFLOW_EXTENSION_NAMESPACE = /^[A-Za-z][A-Za-z0-9_-]*$/;
 export function validWorkflowExtensionNamespace(value: string): boolean { return WORKFLOW_EXTENSION_NAMESPACE.test(value) && value !== "__proto__" && value !== "constructor" && value !== "prototype"; }
 export function parseThinking(value: unknown): ModelSpec["thinking"] | undefined { return isThinkingLevel(value) ? value : undefined; }
 export function parseModelReference(value: string): ModelSpec {
-  const match = /^([^/:\s]+)\/([^:\s]+)(?::([^:\s]+))?$/.exec(value);
+  const match = /^([^/:\s]+)\/([^\s]+)$/.exec(value);
   if (!match?.[1] || !match[2]) fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
-  const thinking = match[3];
-  if (thinking !== undefined && !isThinkingLevel(thinking)) fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
-  return { provider: match[1], model: match[2], ...(thinking !== undefined ? { thinking } : {}) };
+  // The model id is everything after the first slash, so namespaced ids such as
+  // `deepseek/deepseek-v4.1-flash:nitro` survive intact. Only a trailing segment
+  // that names a thinking level is one.
+  const reference = match[2];
+  const separator = reference.lastIndexOf(":");
+  const suffix = separator === -1 ? undefined : reference.slice(separator + 1);
+  if (suffix === "") fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
+  const thinking = suffix !== undefined && isThinkingLevel(suffix) ? suffix : undefined;
+  const model = thinking === undefined ? reference : reference.slice(0, separator);
+  if (model === "") fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
+  return { provider: match[1], model, ...(thinking === undefined ? {} : { thinking }) };
 }
 export function assertModelThinking(value: string, path = "model"): void {
   if (value.includes("/") && parseModelReference(value).thinking === undefined) fail("INVALID_METADATA", `${path} must be provider/model:thinking`);
@@ -163,6 +172,10 @@ export function resolveModelReference(value: string, aliases: Readonly<Record<st
   };
   return resolveReference(value, []);
 }
+export function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string {
+  const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
+  return `${parsed.provider}/${parsed.model}`;
+}
 type ToolSource = { getActiveTools(): string[]; getAllTools?(): readonly { name: string; exposure?: string }[] };
 /**
  * Tools a session can reach, and so the ceiling for its agents: the declared tools plus the ones
@@ -181,10 +194,6 @@ export function physicalModel(spec: ModelSpec, aliases: Readonly<Record<string,
   const target = resolveModelReference(spec.model, aliases, knownModels, settingsPath);
   return spec.thinking === undefined ? target : { ...target, thinking: spec.thinking };
 }
-export function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string {
-  const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
-  return `${parsed.provider}/${parsed.model}`;
-}
 export function aliasDrift(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>): string[] {
   return [...new Set([...Object.keys(previous), ...Object.keys(current)])].sort().flatMap((name) => previous[name] === current[name] ? [] : [`${name}: ${previous[name] ?? "(missing)"} -> ${current[name] ?? "(missing)"}`]);
 }

package/src/validation.ts

@@ -2,14 +2,11 @@ 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, loadCodemodeToolsSetting, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./settings.js";
@@ -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");
@@ -309,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");
@@ -318,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;
@@ -429,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);
 }
-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;
+/**
+ * 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))));
+  });
+}
+/**
+ * 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;
@@ -495,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;
@@ -506,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"));
@@ -520,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 {
@@ -562,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 {