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

package/CHANGELOG.md

@@ -1,6 +1,151 @@
 # Changelog
 ## Unreleased
 
+## [6.2.1] - 2026-10-13
+
+### New capabilities
+
+- Registered functions can create persistent agent handles with `context.agent.create({ name, ... })` and `handle.send(...)`, with the same rules as scripts. Handle journal identity is scoped by function invocation, branch, worktree, and name. The bundled `reviewLoop` now uses one persistent developer and a fresh reviewer each iteration.
+
+### Fixes
+
+- Trajectory displays agent and system prompts as complete escaped plain text, so XML-style sections such as `<addendum>`, `<skills>`, and `<project_context>` remain visible instead of being interpreted as HTML inside Markdown. Browser regressions verify line breaks and safe rendering.
+- `agent(...)` and `handle.send(...)` now deliver the supplied text as the whole user message, on first and later turns. The repeated Workflow/Agent/Phase/Parent header, ownership paragraph, and `Task:` wrapper are gone. The `workflow_result` once-per-turn contract moved into that tool's description, child ownership into the `agent` tool description, and retry or soft-budget notes into separate control text after the task (a steered message on local sessions, appended to the pane launch prompt on Herdr; custom transports that do not set `turnControlDelivered` get the steered message). The system prompt is unchanged, so prompt caching is unaffected.
+
+### Documentation and metadata
+
+- Clarified that the workflow `model` option is optional; omitting it uses the configured defaults.
+- Updated the core package description and keywords to include codemode scripts.
+
+## [6.2.0] - 2026-10-10
+
+### New capabilities
+
+- Selecting a phase or registered function in the workflow navigator now shows total tokens, cost, and elapsed time across all its agents, including nested agents (#318).
+
+### Fixes
+
+- Launch now checks static agent calls inside registered functions that the script calls by name, so an unknown model for a later agent fails before the workflow starts. A computed `outputSchema` no longer makes a call dynamic (#309).
+- On Linux, session lease liveness uses the process start time from `/proc/<pid>/stat` instead of the `/proc/<pid>` entry time, so a live session owner is no longer reported dead (#307).
+- In the wide workflow navigator, the details column follows the scrolled tree, so details for a selected node further down a long workflow stay visible (#317).
+- Model references keep colon-bearing and namespaced model IDs, such as `openrouter/deepseek/deepseek-v4.1-flash:nitro:high`. The final `:` segment is read as a thinking level only when it names one, so `provider/model:turbo` now fails as `INVALID_METADATA` instead of `UNKNOWN_MODEL` (#314).
+- Concurrent Trajectory starts in one agent directory now share one server whose lock always names the process answering `/health`. A lock whose owner is alive but does not answer within the startup budget, or a lock that cannot be read, is kept and the attach fails with a clear error, instead of a second server being started beside it. Process liveness is checked against the kernel start time, not the `/proc` entry time, and Trajectory sends SIGKILL only to a process whose recorded start time still matches; a stale server that cannot be confirmed stopped keeps its lock and fails the attach (#315).
+
+## [6.1.0] - 2026-10-08
+
+**This minor version contains breaking changes.** Shipping them as 6.1.0 shortly after 6.0.0 is an explicit operator choice, not a SemVer-compliant version. Read the migration notes before upgrading.
+
+### Breaking changes
+
+- Roles are now interpreted only by the explicitly enabled optional `@piewf/pi-ext-roles` extension. Core and CLI have no roles dependency, discovery, typed role fields, `/roles` export, `pi-role` bridge or legacy role paths. Without the plugin, unknown agent options are opaque JSON and ignored. The five fallback roles belong to the independent package.
+- Generic `agentPreparationHooks` optionally validate original options with a schema, then prepare concrete configuration before model/resource validation. Workflow agents, handles, nested agents, standalone subagents and doctor share preparation and root/parent capability enforcement. Consumer selectors remain ordered defaults, not extra authorization ceilings.
+- New runs freeze generic prepared configurations before dispatch. Workflow identity version 6 and standalone configuration version 1 reject previous formats without migration. Retry/resume reuse configuration; new identities resolve current settings. Extension code and skill/AGENTS/SYSTEM/APPEND bytes are reread, not frozen.
+- Doctor uses `--agent-options <json>` and `agentInspection`, not role targets or `--role`. Bundles require explicit plugin resources/dependencies instead of role inference. Obsolete compatibility upgrade/warning checks are removed; generic and extension-owned regressions plus the local paired SDK/CLI harness replace their still-relevant coverage.
+- Role descriptions append to Pi's structured prompt channel, preserving existing append instructions and dynamic provider/tool prefixes (#311); they never force the entire system prompt.
+
+### Migration
+
+- To keep using `role` options, install `@piewf/pi-ext-roles` 0.2.0 or newer and enable it explicitly as a Pi extension next to workflows. Core and CLI no longer install or load it.
+- Roles and shared settings are read only from the roles package paths: `~/.pi/agent/pi-ext-roles/{settings.json,roles/}` and authorized project `.pi/pi-ext-roles/{settings.json,roles/}`. Legacy workflow role paths are ignored; move files manually, nothing is rewritten.
+- Runs persisted before 6.1.0 cannot be resumed or retried. Finish them before upgrading, then relaunch them as new runs.
+- Role text is appended through Pi's structured system-prompt append channel. Only roles with `overrideSystemPrompt: true` replace the base prompt.
+- `pi-role` is owned only by the independent `@piewf/pi-ext-roles` package, which works without workflows. Upgrade an old global `@piewf/cli` first; never overwrite the binary with `--force`.
+- Prepared options stay bounded by root and parent tool ceilings, project trust and `excludeTools`; setup hooks cannot change the agent cwd.
+
+### Fixes
+
+- Restored pre-6 behavior: `excludeTools` for workflow, nested and standalone agents, also in the `agent` and `subagents_run` tool schemas (exact names as in Pi, applied after preparation, bounded by parent ceilings and frozen with each logical agent's configuration; patterns and `workflow_result` are rejected, unknown names warn); `resources_discover` skills for root, nested and standalone agents, attributed per resource generation with Pi's path normalization; static preparation failures, including unavailable models and unknown roles, fail before shell, tool or run effects; nested children keep core error codes and their parent's structural scope under their own identity; unrelated extension load failures are CLI warnings; bundled factories run without a Pi API again and keep their module source.
+- Launch inspection covers only completely static agent options (handles only when no send adds options) and stops on cancellation, also after the session lease. Nested children are new spawns of their parent's attempt, with identities per parent spawn: after retry or cold resume they prepare against current configuration.
+- After a CLI extension load failure, every workflow registration must declare a `source` that is a loaded extension entry or a portable bundle module, or the CLI stops before running anything (a factory may register and then fail). Agent options that no such preparation hook declares in its `optionsSchema` fail with `INVALID_METADATA` instead of being ignored, also after paused resume, cold resume or retry. Setup hooks cannot reintroduce an excluded or outside-ceiling root tool as a same-named custom tool, and `excludeTools` names, own or inherited, also remove custom tools of those names.
+- Preparation context adds `projectCwd` and `defaults.dynamicModelAliasNames`, so plugins can read launch-project configuration inside worktrees and order dynamic aliases below their own static aliases. A paused run resumed after an alias change prepares new agents with the refreshed aliases. A hook passing on a virtual `workflow/<alias>` root model gets its physical target.
+- Setup hooks still cannot change the agent cwd, including to a project subdirectory; `SessionInput.cwd` is now read-only. This deliberate deviation from pre-6 prevents loading another directory's trust, settings and `.pi` resources.
+
+## [6.0.0] - 2026-10-07
+
+### Breaking changes
+
+- Roles are owned by `@piewf/pi-ext-roles`, now a registry dependency of core and CLI. `registerWorkflowExtension({ roleDirectories })` is removed and fails with migration guidance. Register packaged roles separately with `registerRoleContribution(pi, { owner: import.meta.url, roleDirectories: ["./roles"] })`; keep workflow `source` for provenance and re-export portable bundles that used the removed field.
+- The `pi-role` binary moves from `@piewf/cli` to `@piewf/pi-ext-roles`. Upgrade the old global CLI first, then install the roles package without forced binary overwrites. The retained `@piewf/cli/pi-role` import is a compatibility adapter, not the binary owner.
+- Fallback roles no longer select models or supply workflow-specific model aliases. Configure a per-call model or an overriding role/shared alias explicitly when preserving an old fallback model choice.
+
+### Migration
+
+- Workflow/subagent users receive the roles library automatically; a separately enabled roles plugin is not required. Move shared roles and settings to `~/.pi/agent/pi-ext-roles/` and `.pi/pi-ext-roles/` when ready. Workflow aliases/selectors remain consumer overrides. No user files are rewritten.
+- Legacy workflow role paths and parser/resolver imports remain temporarily supported, with one TUI migration warning per session when applicable. No compatibility removal date is scheduled. Native `pi-role` does not read legacy workflow paths; migrate its files before using it.
+- Native `pi-role` starts one Pi process from PATH. Role tool selectors control declared loadout, not a sandbox. Native tool flags remain ceilings; partial context scopes are unsupported unless suppressed with `--no-context-files`, and role/shared `extensionSettings` are ignored by the launcher. Workflow/subagent consumers retain settings delivery, partial context filtering, captured configuration, recovery and runtime ownership. See the [migration guide](https://vekexasia.github.io/pi-extensible-workflows/roles.html#migration).
+
+### Verification
+
+- Package verification uses the published roles artifact, without a sibling checkout or local dependency staging. `scripts/verify-role-upgrade.py` exercises registry installation in an isolated Pi, the `5.19.1` to major-candidate upgrade, TUI/reload, legacy settings and role precedence, binary handover, migrated contributors and re-exported bundles against a local provider.
+
+## [5.19.1] - 2026-10-05
+
+### New capabilities
+
+- Trajectory shows workflow script `shell()` and `tools.<name>()` calls: CALLS and the `script` Gantt lane share status and colours, with phase and timing. Tool arguments and results are not recorded in call state or shown in Trajectory (including live state and HTML exports/shares); tool errors keep only the code. The replay journal retains tool results unchanged. Shell calls keep inputs and output, with environment override names, not values. Calls are recorded without a count cap; tool metadata writes are best-effort, and journaled calls without finish timing show completed with unknown duration.
+
+## [5.19.0] - 2026-10-02
+
+### Breaking changes
+
+- `tools` is a reserved workflow global: registering a workflow function named `tools` fails with `GLOBAL_COLLISION`. Rename the function.
+
+### New capabilities
+
+- Workflow and subagent tools declare an `outputSchema` and return `structuredContent`, so Pi `codemode` scripts receive objects instead of JSON text. For example, `await tools.workflow_status({ runId })` resolves to `{ runId, workflowName, state, agents, ... }`. A completed foreground `workflow`, `workflow_retry`, or `workflow_resume` call resolves with the full `value`, even when the model sees only a result descriptor. Inside workflow agents, the child agent tools `agent` and `get_subagent_result` do the same, and Herdr-bridged tools keep their `outputSchema`.
+- Workflow scripts call the launching session's tools directly as `await tools.<name>(args)`, through Pi's `ctx.executeTool()`, with the names and results of Pi `codemode`. Permission handlers apply, results are journaled for resume and retry, the live workflow item shows calls in flight, and an unknown tool fails the launch with `UNKNOWN_TOOL`. Failed calls reject with the new `TOOL_FAILED` code.
+- `workflow_status`, `workflow_catalog`, and `subagents_inspect` carry the `readOnlyHint` tool annotation, so permission extensions that read annotations can skip confirming them.
+
+### Internal
+
+- Build and test against Pi 1.0.0. `@piewf/cli` bundles Pi 1.0.0.
+
+## [5.18.0] - 2026-09-30
+
+### Breaking changes
+
+- `pi-extensible-workflows` and `@piewf/herdr` require Pi 0.99.0 or later; their `@earendil-works/pi-coding-agent` peer dependency is now `>=0.99.0`. `@piewf/cli` bundles Pi 0.99.1.
+
+### New capabilities
+
+- Global model aliases appear in `/model` and `--model` as virtual models named `workflow/<alias>`, for example `workflow/cheap-model`. The alias target is read from settings on every request, and workflow agents and subagents that inherit the session model run on that target. The thinking level selected in `/model` replaces the one in the alias. Project and extension-provided aliases are not listed, and new aliases need `/reload`.
+- Workflow agents and standalone subagents load Pi's built-in `codemode`, `tool-search`, and `mcp` extensions, so they can reach the MCP servers from `mcp.json` through `codemode` or `tool_search`. `-builtin:<name>` in Pi settings still disables them. Workflow extension selectors name them `builtin:codemode`, `builtin:tool-search`, and `builtin:mcp`; a selector list that starts with `!*` needs `builtin:*` or those names to keep them.
+- The global `codemodeTools` workflow setting limits which workflow and subagent tools Pi `codemode` scripts may call: `"all"` (default), `"read-only"` (`workflow_status`, `workflow_catalog`, and `subagents_inspect`), or `"none"`. The model still calls every tool directly. Changes apply after `/reload`.
+- The agent tool ceiling includes the parent session's tools that only codemode scripts call or `tool_search` loads, such as MCP tools with the default exposure. Role and call tool selectors still restrict them.
+
+### Fixes
+
+- Prompt inspection in `piewf doctor` and role inspection renders the system prompt again on Pi 0.99, including changes made by `before_agent_start` handlers.
+- An agent that asks for a model of Pi's built-in `llama.cpp` provider fails with an error that explains why: Pi does not expose that extension to extension sessions. Declare the server as a provider in `models.json` instead.
+
+### Internal
+
+- Build and test against Pi 0.99.1. Package verification ignores three `brace-expansion` advisories that come from the `npm-shrinkwrap.json` of `@earendil-works/pi-coding-agent@0.99.1`.
+
+## [5.17.2] - 2026-09-28
+
+### Breaking changes
+
+- `subagents_inspect({})` lists only the runs of the current Pi session, matching `/subagents` and Trajectory. Pass `scope: "all"` to list every stored run as before. Lookup by `id` still resolves runs from any session ([#305](https://github.com/vekexasia/pi-extensible-workflows/pull/305)).
+
+### New capabilities
+
+- `piewf doctor` inspects a role file before it is installed: a role ending in `.md`, such as `piewf doctor ./roles/reviewer.md`, is read as a file relative to the current working directory, while other values still name an installed role. A missing file reports `ROLE_FILE_NOT_FOUND` ([#303](https://github.com/vekexasia/pi-extensible-workflows/issues/303)).
+
+### Fixes
+
+- `piewf doctor` no longer fails because of roles that another role overrides: it still reports their invalid frontmatter, but checks tools, models, and settings only for the roles that apply. A role tool missing from doctor's headless tool list is now a `ROLE_TOOL_INACTIVE` warning, because doctor cannot see tools that extensions add when a session starts and the runtime skips unavailable role tools. Role inspection and workflow agent sessions now skip the workflow host extensions of every installed copy of the package, so a Pi package installed next to `@piewf/cli` no longer fails with `Global name is already registered: reviewLoop` ([#302](https://github.com/vekexasia/pi-extensible-workflows/issues/302)).
+
+## [5.17.1] - 2026-09-26
+
+### Fixes
+
+- Running workflow agents and standalone subagents show a fixed status glyph before their names and keep the activity spinner visible after `[running]`, even without a current activity label.
+
+### Internal
+
+- Remove duplicated view and trajectory helpers, unused internal code, and tracked generated images. Preserve the public `pi-extensible-workflows/runtime` type exports.
+
 ## [5.17.0] - 2026-09-23
 
 ### New capabilities

package/README.md

@@ -11,7 +11,7 @@ The repository [README](https://github.com/vekexasia/pi-extensible-workflows#rea
 ## Install
 
 Requires Node.js 22.19 or newer. This is trusted Pi host code with the same filesystem and process access as Pi.
-The core installation includes workflow orchestration, the `reviewLoop` starter for implementation-and-review cycles, packaged `developer`/`reviewer`/`scout`/`oracle`/`researcher` roles with ready-made slash commands (`/scout`, `/oracle`, `/review`, `/parallel-review`, `/review-loop`, `/deep-research`, and more), and durable standalone subagent tools. See the [Subagents guide](https://vekexasia.github.io/pi-extensible-workflows/subagents.html) for the bundled tools.
+The core installation includes workflow orchestration, the `reviewLoop` starter for implementation-and-review cycles, ready-made slash commands (`/scout`, `/oracle`, `/review`, `/parallel-review`, `/review-loop`, `/deep-research`, and more), and durable standalone subagent tools. Role options in starters and slash commands require the separately enabled `@piewf/pi-ext-roles` Pi extension; core does not ship or interpret roles. See the [Subagents guide](https://vekexasia.github.io/pi-extensible-workflows/subagents.html) for the bundled tools.
 Trajectory live monitoring is included in the package. Restart existing Pi processes after upgrading the package so their publisher protocol matches the detached Trajectory server.
 
 ```sh
@@ -35,7 +35,7 @@ Launch with a non-empty `name` and exactly one of `script` or `scriptPath`. Regi
 
 ## Programmatic integration
 
-The package exports the workflow registry, runtime, persistence, validation, settings, role, lifecycle, and local Pi session APIs used by trusted hosts and extensions.
+The package exports the workflow registry, runtime, persistence, validation, settings, generic agent preparation, lifecycle, and local Pi session APIs used by trusted hosts and extensions.
 
 Direct consumers of `createLocalPiSession()` receive a session with extensions already bound. Always `await session.dispose()` so `session_shutdown` runs before the native session is released; disposal is idempotent.
 

package/dist/src/agent-execution.d.ts

@@ -85,18 +85,17 @@ export interface PiResourceInspection {
     }[];
     readonly systemPromptSource?: string;
 }
-import type { AgentAccounting, AgentActivity, AgentContinuity, AgentIdentity, AgentResourcePolicy, AgentResourceSelectors, AgentSetup, AgentSetupSummary, AgentTransport, AgentTransportContext, ContextFileScope, JsonSchema, JsonValue, LiveSessionHandoff, ModelSpec, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentSession, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowRunContext } from "./types.js";
-import { type AgentDefinition, type AgentState } from "./types.js";
+import type { AgentPreparationContext, PreparedAgentConfiguration, RegisteredAgentPreparationHook, AgentAccounting, AgentActivity, AgentContinuity, AgentIdentity, AgentResourcePolicy, AgentResourceSelectors, AgentSetup, AgentSetupSummary, AgentTransport, AgentTransportContext, ContextFileScope, JsonSchema, JsonValue, LiveSessionHandoff, ModelSpec, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentSession, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowRunContext } from "./types.js";
+import { type AgentState } from "./types.js";
 import type { RunStore } from "./persistence.js";
-type AgentExecutionRunStore = Pick<RunStore, "recordSystemPrompt" | "validateWorktree" | "worktree" | "snapshotWorktree">;
-export type { AgentAccounting, AgentActivity, AgentInspectionMode, AgentSetup, AgentSetupContext, AgentSetupHook, AgentTransport, AgentTransportContext, PiRuntimeLaunchInfo, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult } from "./types.js";
+type AgentExecutionRunStore = Pick<RunStore, "recordSystemPrompt" | "validateWorktree" | "worktree" | "snapshotWorktree"> & Partial<Pick<RunStore, "load" | "saveAgentConfiguration">>;
+export type { AgentPreparation, AgentPreparationContext, PreparedAgentConfiguration, RegisteredAgentPreparationHook, AgentAccounting, AgentActivity, AgentInspectionMode, AgentSetup, AgentSetupContext, AgentSetupHook, AgentTransport, AgentTransportContext, PiRuntimeLaunchInfo, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult } from "./types.js";
 export interface AgentBudgetHooks {
     beforeAttempt(): void;
     beforeTurn(): void;
     afterTurn(accounting: AgentAccounting, final: boolean): void;
     instruction(): string | undefined;
 }
-export type { AgentDefinition } from "./types.js";
 export interface AgentProviderFailure {
     label: string;
     provider: string;
@@ -122,7 +121,6 @@ export interface AgentExecutionOptions {
     skills?: readonly string[];
     extensions?: readonly string[];
     effectiveTools?: readonly string[];
-    role?: string;
     contextFiles?: readonly ContextFileScope[];
     schema?: JsonSchema;
     retries?: number;
@@ -136,31 +134,53 @@ export interface AgentExecutionOptions {
     agentIdentity?: AgentIdentity;
     inheritedExtensionSettings?: Readonly<WorkflowExtensionSettings>;
     agentNodeId?: string;
+    capabilities?: Readonly<{
+        tools: readonly string[];
+        skills: readonly string[];
+        extensions: readonly string[];
+    }>;
+    parentSkills?: readonly string[];
+    /** Tool names that ancestors excluded; with this agent's own `excludeTools`, they are removed from root and custom tools alike. */
+    inheritedExcludeTools?: readonly string[];
+    projectTrusted?: boolean;
+    configuration?: PreparedAgentConfiguration;
+    onConfiguration?: (configuration: PreparedAgentConfiguration) => void | Promise<void>;
 }
 export interface AgentExecutionRoot {
+    projectTrusted?: boolean;
     cwd: string;
     model: ModelSpec;
     tools: ReadonlySet<string>;
     extensionSettings?: Readonly<WorkflowExtensionSettings> | undefined;
     validateExtensionSettings?: (settings: Readonly<WorkflowExtensionSettings> | undefined, context: WorkflowExtensionSettingsValidatorContext) => void;
     onAgentSettings?: (agentNodeId: string, settings: Readonly<WorkflowExtensionSettings>) => void;
+    onAgentCapabilities?: (agentNodeId: string, capabilities: AgentPreparationContext["capabilities"], projectTrusted: boolean) => void;
     resourceSelectors?: AgentResourceSelectors;
-    agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
     agentDir?: string;
     additionalSkillPaths?: readonly string[];
     availableModels?: ReadonlySet<string>;
     knownModels?: ReadonlySet<string>;
     modelAliases?: Readonly<Record<string, string>>;
+    dynamicModelAliasNames?: readonly string[];
     blockedAliases?: ReadonlySet<string>;
     blockedAliasTargets?: Readonly<Record<string, string>>;
     settingsPath?: string;
     extensionSettingsPath?: string;
     runStore?: AgentExecutionRunStore;
     providerPause?: () => Promise<void>;
+    agentPreparationHooks?: readonly RegisteredAgentPreparationHook[];
     agentSetupHooks?: readonly RegisteredAgentSetupHook[];
     agentResourcePolicy?: () => AgentResourcePolicy | Promise<AgentResourcePolicy>;
     runContext?: Readonly<WorkflowRunContext>;
     onResourceWarning?: (message: string) => void;
+    /**
+     * Load failures this host tolerated and the identities of the extensions it did load. With failures, a non-core option
+     * counts as owned only by the schema of a preparation hook whose `source` is a loaded extension; others fail closed.
+     */
+    extensionLoad?: Readonly<{
+        errors: readonly string[];
+        loaded: readonly string[];
+    }>;
 }
 export interface AgentToolCallProgress {
     id: string;
@@ -222,7 +242,6 @@ export declare function getAgentAttempts(error: unknown): readonly AgentAttempt[
 export declare class WorkflowAgentExecutor {
     private readonly root;
     private readonly transport;
-    private readonly warnedRoleTools;
     constructor(root: AgentExecutionRoot, transport?: AgentTransport);
     setRunContext(runContext: Readonly<WorkflowRunContext>): void;
     resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): {
@@ -233,6 +252,7 @@ export declare class WorkflowAgentExecutor {
         systemPromptAppend: string;
         contextFiles?: readonly ContextFileScope[];
     };
+    prepare(options: AgentExecutionOptions, cwd?: string, signal?: AbortSignal, mode?: "execution" | "inspection"): Promise<PreparedAgentConfiguration>;
     execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools?: readonly ToolDefinition[], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult>;
 }
 export interface ScheduledAgentOptions {
@@ -245,7 +265,6 @@ export interface ScheduledAgentOptions {
     extensions?: readonly string[];
     worktreeOwner?: string;
     model?: string;
-    role?: string;
     contextFiles?: readonly ContextFileScope[];
     schema?: JsonSchema;
     retries?: number;
@@ -255,6 +274,14 @@ export interface ScheduledAgentOptions {
     agentOptions?: Readonly<Record<string, JsonValue>>;
     agentIdentity?: AgentIdentity;
     extensionSettings?: Readonly<WorkflowExtensionSettings>;
+    capabilities?: Readonly<{
+        tools: readonly string[];
+        skills: readonly string[];
+        extensions: readonly string[];
+    }>;
+    projectTrusted?: boolean;
+    configuration?: PreparedAgentConfiguration;
+    inheritedExcludeTools?: readonly string[];
 }
 export type ScheduledAgentResult = {
     id: string;
@@ -297,7 +324,11 @@ type ScheduledNode = {
     resolveCompletion: () => void;
     task: () => Promise<void>;
     restored: boolean;
+    attemptCapabilities?: AgentPreparationContext["capabilities"];
+    attemptProjectTrusted?: boolean;
     steer?: (message: string) => void | Promise<void>;
+    /** Children spawned so far per label; numbers the occurrence of each child's own identity. */
+    childOccurrences?: Map<string, number>;
 };
 export type OwnershipRecord = {
     id: string;
@@ -317,6 +348,8 @@ export declare class FairAgentScheduler {
     addRun(runId: string, limit?: number, beforeLaunch?: () => void, extensionSettings?: Readonly<WorkflowExtensionSettings>): void;
     updateRunLimit(runId: string, limit: number): void;
     setRunExtensionSettings(runId: string, settings: Readonly<WorkflowExtensionSettings> | undefined): void;
+    setConfiguration(agentId: string, configuration: PreparedAgentConfiguration): Promise<void>;
+    setAttemptCapabilities(agentId: string, capabilities: AgentPreparationContext["capabilities"], projectTrusted: boolean): void;
     setExtensionSettings(agentId: string, settings: Readonly<WorkflowExtensionSettings>): void;
     spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): {
         id: string;
@@ -331,7 +364,7 @@ export declare class FairAgentScheduler {
     attemptStarted(id: string): void;
     cancelRun(runId: string): Promise<void>;
     removeRun(runId: string): void;
-    toolsFor(parentId: string, resolveTools?: (role: string | undefined, tools: readonly string[] | undefined, model: string | undefined, inheritedTools: readonly string[], skills: readonly string[] | undefined, extensions: readonly string[] | undefined) => readonly string[]): ToolDefinition[];
+    toolsFor(parentId: string): ToolDefinition[];
     snapshot(): readonly OwnershipRecord[];
     restoreRun(runId: string, limit: number, ownership: readonly OwnershipRecord[], beforeLaunch?: () => void, extensionSettings?: Readonly<WorkflowExtensionSettings>): void;
     flush(runId?: string): Promise<void>;