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

package/dist/src/agent-execution.js

@@ -1,23 +1,25 @@
-import { existsSync, realpathSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { copyFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Type } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
 import { Compile } from "typebox/compile";
-import { createAgentSession, createCodemodeExtension, createMcpExtension, createToolSearchExtension, DefaultPackageManager, DefaultResourceLoader, defineTool, getAgentDir, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, createCodemodeExtension, createMcpExtension, createToolSearchExtension, DefaultPackageManager, DefaultResourceLoader, defineTool, getAgentDir, ModelRuntime, SessionManager, SettingsManager, loadSkills } from "@earendil-works/pi-coding-agent";
 ;
-import { SerialLane, assertModelThinking, byPriorityThenName, deepFreeze, errorText, jsonObject, jsonValue, mergeWorkflowExtensionSettings, object, physicalModel, resolveModelReference, resourcePatternHasMagic, unmatchedResourcePatterns } from "./utils.js";
+import { SerialLane, assertModelThinking, byPriorityThenName, deepFreeze, errorCode, errorText, jsonObject, jsonValue, object, physicalModel, resolveModelReference, resourcePatternHasMagic, selectResourcesByLayers, modelCapability, unmatchedResourcePatterns } from "./utils.js";
 import { SETTLED_AGENT_STATES, WorkflowError, isContextFileScope, zeroAccounting } from "./types.js";
 import { createLiveSessionHandoff } from "./session-handoff.js";
 import { createToolTimingExtension } from "./tool-timing.js";
 import { isEmptyAbortedAssistant, normalizePiMessage, normalizePiSessionEvent, runtimeProgressToAgentProgress } from "./pi-runtime-adapter.js";
 import { createPiRuntimeAgentRunner, isRuntimeAgentProviderError, normalizePiRuntimeError } from "./pi-runtime-runner.js";
 import { defaultWorkflowResultSchema } from "./runtime/workflow-result.js";
-import { validateAgentOptions, validateSchema } from "./validation.js";
-import { canonicalPath, extensionIdentity } from "./paths.js";
+import { isCoreAgentOption, validateAgentOptions, validateSchema } from "./validation.js";
+import { canonicalPath, extensionIdentity, piResourceContains, piResourcePath, sameFilesystemPath } from "./paths.js";
 import { isCorePackageName } from "./package-identity.js";
-import { canonicalExtensionSelector, resolveRole } from "./roles.js";
+import { canonicalExtensionSelector, validateContextFileScopes, validateSelectorList, validateWorkflowExtensionSettings } from "./settings.js";
+import { agentIdentityPath } from "./execution.js";
 const localToolTimingExtension = createToolTimingExtension();
 function parseModel(value, fallback, aliases = {}, knownModels, settingsPath) {
     if (!value)
@@ -25,6 +27,59 @@ function parseModel(value, fallback, aliases = {}, knownModels, settingsPath) {
     assertModelThinking(value);
     return resolveModelReference(value, aliases, knownModels, settingsPath);
 }
+async function authorizedResources(root, cwd, options) {
+    const agentDir = root.agentDir ?? getAgentDir();
+    const trusted = root.projectTrusted ?? false;
+    const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+    settingsManager.setProjectTrusted(trusted);
+    const resolved = await new DefaultPackageManager({ cwd, agentDir, settingsManager, builtinExtensions: ["codemode", "tool-search", "mcp"] }).resolve();
+    const extensions = resolved.extensions.filter(({ enabled, metadata }) => enabled && (trusted || metadata.scope !== "project")).map(({ path }) => extensionIdentity(path));
+    const skillPaths = resolved.skills.filter(({ enabled, metadata }) => enabled && (trusted || metadata.scope !== "project")).map(({ path }) => path);
+    const skills = loadSkills({ cwd, agentDir, skillPaths: [...skillPaths, ...(root.additionalSkillPaths ?? [])], includeDefaults: false }).skills.map(({ name }) => name);
+    const parent = options.capabilities;
+    return { tools: [...root.tools].filter((tool) => options.effectiveTools === undefined || options.effectiveTools.includes(tool)).filter((tool) => parent === undefined || parent.tools.includes(tool)), skills: [...new Set(skills)].filter((name) => parent === undefined || parent.skills.includes(name)), extensions: [...new Set(extensions)].filter((path) => parent === undefined || parent.extensions.includes(path)) };
+}
+function validatePreparedConfiguration(root, configuration, capabilities, cwd, resumed) {
+    const code = resumed ? "RESUME_INCOMPATIBLE" : "INVALID_METADATA";
+    if (!jsonObject(configuration) || typeof configuration.projectTrusted !== "boolean" || typeof configuration.systemPromptAppend !== "string" || configuration.systemPrompt !== undefined && typeof configuration.systemPrompt !== "string")
+        throw new WorkflowError(code, "Invalid prepared agent configuration");
+    if (configuration.projectTrusted && !root.projectTrusted)
+        throw new WorkflowError("RESUME_INCOMPATIBLE", "Prepared agent configuration lost project trust");
+    if (!object(configuration.model) || typeof configuration.model.provider !== "string" || typeof configuration.model.model !== "string")
+        throw new WorkflowError(code, "Invalid prepared model");
+    const model = resolveModelReference(`${configuration.model.provider}/${configuration.model.model}${configuration.model.thinking === undefined ? "" : `:${configuration.model.thinking}`}`);
+    if (root.availableModels !== undefined && !root.availableModels.has(modelCapability(model)))
+        throw new WorkflowError(resumed ? "RESUME_INCOMPATIBLE" : "UNKNOWN_MODEL", `Required model is unavailable: ${modelCapability(model)}`);
+    const tools = validateSelectorList(configuration.tools, "configuration", "tools", "INVALID_METADATA", false);
+    if (tools === undefined)
+        throw new WorkflowError(code, "Prepared tools are missing");
+    const missing = tools.find((tool) => !capabilities.tools.includes(tool));
+    if (missing)
+        throw new WorkflowError(resumed ? "RESUME_INCOMPATIBLE" : "UNKNOWN_TOOL", `Required tool is unavailable: ${missing}`);
+    const excludeTools = configuration.excludeTools;
+    try {
+        validateAgentOptions({ excludeTools });
+    }
+    catch {
+        throw new WorkflowError(code, "Invalid prepared excludeTools");
+    }
+    if (!Array.isArray(excludeTools) || tools.some((tool) => excludeTools.includes(tool)))
+        throw new WorkflowError(code, "Prepared excludeTools contradict the prepared tools");
+    validateSelectorList(configuration.skills, "configuration", "skills", "INVALID_METADATA", false);
+    validateSelectorList(configuration.extensions, "configuration", "extensions", "INVALID_METADATA", false);
+    if (resumed)
+        for (const key of ["skills", "extensions"]) {
+            const selectors = configuration[key];
+            const selected = selectors.slice(selectors.lastIndexOf("!*") + 1);
+            const missing = selected.find((name) => !capabilities[key].includes(name));
+            if (missing)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", `Required ${key} capability is unavailable: ${missing}`);
+        }
+    validateContextFileScopes(configuration.contextFiles, "configuration");
+    validateWorkflowExtensionSettings(configuration.settings, "configuration", "INVALID_METADATA");
+    root.validateExtensionSettings?.(configuration.settings, { source: "effective", cwd, projectTrusted: root.projectTrusted ?? false });
+    return deepFreeze(structuredClone(configuration));
+}
 function accounting(stats) {
     return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
 }
@@ -212,6 +267,48 @@ function builtinExtensions() {
 }
 const BUILTIN_EXTENSION_PREFIX = "builtin:";
 function isLlamaModel(model) { return model.provider === "llama.cpp"; }
+/**
+ * Pi only extends resources with paths that loaded extensions return from resources_discover. Recording them, normalized as
+ * Pi does, lets selection tell those skills from the static inventory. Like Pi's own source attribution, the record belongs
+ * to one resource generation: reload() starts a new one, so withdrawn contributions stop counting as discovered.
+ */
+class WorkflowResourceLoader extends DefaultResourceLoader {
+    loaderCwd;
+    extensionSkillPaths = [];
+    constructor(loaderCwd, options) {
+        super(options);
+        this.loaderCwd = loaderCwd;
+    }
+    async reload(...args) {
+        this.extensionSkillPaths.length = 0;
+        await super.reload(...args);
+    }
+    extendResources(paths) {
+        this.extensionSkillPaths.push(...(paths.skillPaths ?? []).map(({ path }) => piResourcePath(path, this.loaderCwd)));
+        super.extendResources(paths);
+    }
+}
+/**
+ * Prepared selectors end with a frozen segment: `!*` followed by the static inventory. Extension-discovered skills keep every
+ * other selector, including negations setup hooks inserted anywhere (a terminal `!*` too), but not that frozen restriction.
+ * Setup can only insert negations, so the inventory names are matched from the right and the boundary is the nearest `!*`
+ * before them; any `!*` with only negations up to the inventory selects the same skills.
+ */
+function discoveredSkillSelectors(selectors, inventory) {
+    if (selectors === undefined || inventory === undefined)
+        return selectors;
+    const frozen = new Set();
+    let index = selectors.length;
+    for (const name of [...inventory].reverse().concat("!*")) {
+        do
+            index -= 1;
+        while (index >= 0 && selectors[index] !== name);
+        if (index < 0)
+            return selectors;
+        frozen.add(index);
+    }
+    return selectors.filter((_selector, position) => !frozen.has(position));
+}
 async function createLocalPiSessionHandle(input, sessionStartEvent) {
     const agentDir = input.agentDir ?? getAgentDir();
     const systemPromptSource = workflowSystemPromptPath(input.cwd, agentDir, input.resourcePolicy?.projectTrusted ?? true);
@@ -236,25 +333,23 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
         const resolved = await packageManager.resolve();
         const discoveredExtensions = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => extensionIdentity(path)))];
         const selectorSources = policy.selectorSources;
-        const selection = resolveRole(undefined, {
-            cwd: input.cwd,
-            selectorSources,
-            resources: { extensions: discoveredExtensions },
-        });
-        const selectedExtensions = selection.selectedExtensions ?? [];
+        const selectedExtensions = selectResourcesByLayers(resourceSelectorLayers(selectorSources, "extensions"), discoveredExtensions).filter((path) => policy.capabilities === undefined || policy.capabilities.extensions.includes(path));
         const extensionPaths = selectedExtensions.filter((path) => path.startsWith(BUILTIN_EXTENSION_PREFIX) || !isWorkflowHostEntry(path));
         policy.selectedExtensions = selectedExtensions;
-        policy.unmatchedExtensions = selection.unmatchedExtensions ?? [];
+        policy.unmatchedExtensions = unmatchedResourcePatterns(policy.effective.extensions, discoveredExtensions);
         const skillPaths = [...new Set(resolved.skills.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => path))];
-        const updateSkillMatches = (skills) => {
+        const updateSkillMatches = (skills, extensionSkillPaths) => {
             const names = [...new Set(skills.map(({ name }) => name))];
-            const selected = resolveRole(undefined, { cwd: input.cwd, selectorSources, resources: { skills: names } });
-            const selectedSkills = selected.selectedSkills ?? [];
+            const discovered = new Set(skills.filter(({ filePath }) => extensionSkillPaths.some((path) => piResourceContains(path, filePath))).map(({ name }) => name));
+            const [global, project, call] = resourceSelectorLayers(selectorSources, "skills");
+            const selectedStatic = selectResourcesByLayers([global, project, call], names.filter((name) => !discovered.has(name))).filter((name) => policy.capabilities === undefined || policy.capabilities.skills.includes(name));
+            const selectedDiscovered = selectResourcesByLayers([discoveredSkillSelectors(global, policy.capabilities?.skills), project, call], [...discovered]).filter((name) => policy.parentSkills === undefined || policy.parentSkills.includes(name));
+            const selectedSkills = [...selectedStatic, ...selectedDiscovered];
             policy.selectedSkills = selectedSkills;
-            policy.unmatchedSkills = selected.unmatchedSkills ?? [];
+            policy.unmatchedSkills = unmatchedResourcePatterns(policy.effective.skills, names);
             return new Set(names.filter((name) => !selectedSkills.includes(name)));
         };
-        resourceLoader = new DefaultResourceLoader({
+        const workflowLoader = new WorkflowResourceLoader(input.cwd, {
             cwd: input.cwd,
             agentDir,
             settingsManager,
@@ -265,12 +360,13 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
             extensionFactories,
             ...(contextFilesOverride ? { agentsFilesOverride: contextFilesOverride } : {}),
             skillsOverride: (base) => {
-                const disabledSkills = updateSkillMatches(base.skills);
+                const disabledSkills = updateSkillMatches(base.skills, workflowLoader.extensionSkillPaths);
                 return { ...base, skills: base.skills.filter(({ name }) => !disabledSkills.has(name)) };
             },
             ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}),
             ...systemPromptOptions,
         });
+        resourceLoader = workflowLoader;
         await resourceLoader.reload();
     }
     else {
@@ -293,7 +389,7 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
         throw new WorkflowError("UNKNOWN_MODEL", `Unknown model: ${input.model.provider}/${input.model.model}${because}`);
     }
     const effectiveSessionStartEvent = input.settings === undefined && sessionStartEvent === undefined ? undefined : { ...(sessionStartEvent ?? { type: "session_start", reason: "startup" }), settings: input.settings ?? Object.freeze({}) };
-    const { session } = await createAgentSession({ ...(input.options ?? {}), cwd: input.cwd, agentDir, modelRuntime, model, settingsManager, ...(input.model.thinking ? { thinkingLevel: input.model.thinking } : {}), tools, ...(customTools.length ? { customTools } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), resourceLoader, ...(effectiveSessionStartEvent ? { sessionStartEvent: effectiveSessionStartEvent } : {}), sessionManager: manager });
+    const { session } = await createAgentSession({ cwd: input.cwd, agentDir, modelRuntime, model, settingsManager, ...(input.model.thinking ? { thinkingLevel: input.model.thinking } : {}), tools, ...(customTools.length ? { customTools } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), resourceLoader, ...(effectiveSessionStartEvent ? { sessionStartEvent: effectiveSessionStartEvent } : {}), sessionManager: manager });
     const nativeDispose = session.dispose.bind(session);
     let disposal;
     const shutdown = (reason, targetSessionFile) => {
@@ -663,6 +759,11 @@ export async function createLocalWorkflowAgentSession(prepared, context) {
     return session;
 }
 export const localAgentTransport = Object.freeze({ id: "local", createSession: createLocalWorkflowAgentSession });
+/** Like Pi's excludeTools, exclusions name tools exactly and apply to every tool the session would get, custom tools included. */
+function excludedToolNames(options) {
+    const own = options.agentOptions?.excludeTools;
+    return new Set([...(options.inheritedExcludeTools ?? []), ...(Array.isArray(own) ? own.filter((tool) => typeof tool === "string") : [])]);
+}
 function changedOption(options, baseline, key) { return JSON.stringify(options[key]) !== JSON.stringify(baseline[key]); }
 function isChildAgentToolParams(value) {
     if (!jsonObject(value) || typeof value.prompt !== "string" || typeof value.label !== "string")
@@ -675,8 +776,6 @@ function isChildAgentToolParams(value) {
         return false;
     if (value.model !== undefined && typeof value.model !== "string")
         return false;
-    if (value.role !== undefined && (typeof value.role !== "string" || !value.role.trim()))
-        return false;
     if (value.contextFiles !== undefined && (!Array.isArray(value.contextFiles) || !value.contextFiles.every(isContextFileScope)))
         return false;
     if (value.outputSchema !== undefined && !jsonObject(value.outputSchema))
@@ -702,7 +801,7 @@ function resourcePolicySummary(policy, tools = policy.selectedTools ?? []) {
 }
 const RESOURCE_SELECTOR_KEYS = ["skills", "extensions", "tools"];
 function resourceSelectorLayers(sources, key) {
-    return [sources.global[key], sources.project[key], sources.role?.[key], sources.call?.[key]];
+    return [sources.global[key], sources.project[key], sources.call?.[key]];
 }
 function selectorListWidened(ceiling, candidate) {
     let candidateIndex = 0;
@@ -775,7 +874,7 @@ function appendResourcePolicyNarrowing(ceiling, candidate) {
     };
 }
 function packageRoot(start) {
-    let current = dirname(realpathSync(start));
+    let current = dirname(canonicalPath(start));
     for (;;) {
         const candidates = [current, join(current, "..", "@earendil-works", "pi-coding-agent"), join(current, "..", "pi-coding-agent")];
         for (const candidate of candidates) {
@@ -835,10 +934,9 @@ async function resolvePiRuntime() {
     }
 }
 const piRuntimeResolution = resolvePiRuntime();
-function workflowAgentPrompt(task, options, attempt, previousError) {
-    const basePrompt = [`Workflow: ${options.workflowName}`, `Agent: ${options.label}`, options.phase ? `Phase: ${options.phase}` : "", options.parent ? `Parent: ${options.parent}` : "", "You own this task and any direct child agents you create. Return child results to your parent; do not leave descendants running.", options.schema ? "Call workflow_result exactly once with the final result matching its schema. Do not return prose as the final result." : "Call workflow_result exactly once with { result: \"final response\" } to submit the final response. Do not return prose as the final result.", attempt > 1 ? `Retry attempt ${String(attempt)}. Previous state: ${options.retryState ?? previousError ?? "failed attempt"}` : ""].filter(Boolean).join("\n");
-    const instruction = options.budget?.instruction();
-    return `${basePrompt}\n\nTask:\n${task}${instruction ? `\n\n${instruction}` : ""}`;
+/** Transient per-attempt control text. It is queued as a separate steered message after the task, so the system prompt stays stable and the task message stays exact. */
+function attemptControlText(options, attempt, previousError) {
+    return [attempt > 1 ? `Retry attempt ${String(attempt)}. Previous state: ${options.retryState ?? previousError ?? "failed attempt"}` : "", options.budget?.instruction() ?? ""].filter(Boolean).join("\n");
 }
 async function preparedAgentSession(input, initialPrompt) {
     const { runtime: piRuntime, error: piRuntimeError } = await piRuntimeResolution;
@@ -861,47 +959,27 @@ async function attemptSessionInput(source, attempt) {
     await copyFile(source, target);
     return target;
 }
-async function prepareAgentSetup(root, transport, task, options, resolved, cwd, attempt, signal, customTools, resultTool, inspection = false, previousError) {
+async function prepareAgentSetup(root, transport, task, options, resolved, cwd, attempt, signal, customTools, resultTool, inspection = false) {
     const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
     const baselineOptions = structuredClone(options.agentOptions ?? {});
     const baseResourcePolicy = await root.agentResourcePolicy?.();
-    const roleName = typeof options.role === "string" ? options.role : undefined;
-    const roleDefinition = roleName ? root.agentDefinitions?.[roleName] : undefined;
-    const roleSelectors = roleDefinition ? {
-        ...(roleDefinition.skills === undefined ? {} : { skills: roleDefinition.skills }),
-        ...(roleDefinition.extensions === undefined ? {} : { extensions: roleDefinition.extensions.map((selector) => canonicalExtensionSelector(selector, cwd)) }),
-        ...(roleDefinition.tools === undefined ? {} : { tools: roleDefinition.tools }),
-    } : undefined;
-    const selectorValue = (key, fallback) => {
-        const value = baselineOptions[key];
-        if (Array.isArray(value) && value.every((entry) => typeof entry === "string"))
-            return value;
-        return options.agentOptions === undefined ? fallback : undefined;
+    const configuration = options.configuration;
+    const resourcePolicy = {
+        ...(baseResourcePolicy ?? { globalSettingsPath: "", projectSettingsPath: "", projectTrusted: root.projectTrusted ?? false, global: { skills: [], extensions: [] }, project: { skills: [], extensions: [] }, unmatchedSkills: [], unmatchedExtensions: [] }),
+        projectTrusted: configuration?.projectTrusted ?? root.projectTrusted ?? baseResourcePolicy?.projectTrusted ?? false,
+        effective: { skills: configuration?.skills ?? [], extensions: configuration?.extensions ?? [], tools: resolved.tools },
+        selectorSources: { global: { skills: configuration?.skills ?? [], extensions: configuration?.extensions ?? [], tools: resolved.tools }, project: {} },
+        ...(options.capabilities ? { capabilities: options.capabilities } : {}),
+        ...(options.parentSkills ? { parentSkills: [...options.parentSkills] } : {}),
+        selectedTools: resolved.tools,
     };
-    const rawCallSkills = selectorValue("skills", options.skills);
-    const rawCallExtensions = selectorValue("extensions", options.extensions)?.map((selector) => canonicalExtensionSelector(selector, cwd));
-    const rawCallTools = selectorValue("tools", options.tools);
-    const callSelectors = { ...(rawCallSkills === undefined ? {} : { skills: rawCallSkills }), ...(rawCallExtensions === undefined ? {} : { extensions: rawCallExtensions }), ...(rawCallTools === undefined ? {} : { tools: rawCallTools }) };
-    const resourcePolicy = baseResourcePolicy ? {
-        ...baseResourcePolicy,
-        effective: {
-            skills: [...baseResourcePolicy.effective.skills, ...(roleSelectors?.skills ?? []), ...(rawCallSkills ?? [])],
-            extensions: [...baseResourcePolicy.effective.extensions, ...(roleSelectors?.extensions ?? []), ...(rawCallExtensions ?? [])],
-            ...(baseResourcePolicy.effective.tools === undefined && roleSelectors?.tools === undefined && rawCallTools === undefined ? {} : { tools: [...(baseResourcePolicy.effective.tools ?? []), ...(roleSelectors?.tools ?? []), ...(rawCallTools ?? [])] }),
-        },
-        selectorSources: { global: baseResourcePolicy.selectorSources.global, project: baseResourcePolicy.selectorSources.project, ...(roleSelectors ? { role: roleSelectors } : {}), ...(Object.keys(callSelectors).length ? { call: callSelectors } : {}) },
-    } : undefined;
-    if (resourcePolicy) {
-        resourcePolicy.selectedTools = resolved.tools;
-        resourcePolicy.unmatchedTools = unmatchedResourcePatterns(resourceSelectorLayers(resourcePolicy.selectorSources, "tools").flatMap((layer) => layer ?? []), [...root.tools]);
-    }
-    const resourcePolicyCeiling = resourcePolicy ? structuredClone(resourcePolicy) : undefined;
+    const resourcePolicyCeiling = structuredClone(resourcePolicy);
     const sessionPath = options.sessionPath === undefined || inspection ? options.sessionPath : await attemptSessionInput(options.sessionPath, attempt);
-    const extensionSettings = mergeWorkflowExtensionSettings(options.inheritedExtensionSettings ?? root.extensionSettings, roleDefinition?.extensionSettings) ?? Object.freeze({});
-    root.validateExtensionSettings?.(extensionSettings, { source: roleName === undefined ? "effective" : "role", cwd, projectTrusted: resourcePolicy?.projectTrusted ?? true, ...((root.extensionSettingsPath ?? root.settingsPath) ? { settingsPath: root.extensionSettingsPath ?? root.settingsPath } : {}), ...(roleName === undefined ? {} : { role: roleName }) });
+    const extensionSettings = configuration?.settings ?? options.inheritedExtensionSettings ?? root.extensionSettings ?? Object.freeze({});
+    root.validateExtensionSettings?.(extensionSettings, { source: "effective", cwd, projectTrusted: resourcePolicy.projectTrusted, ...((root.extensionSettingsPath ?? root.settingsPath) ? { settingsPath: root.extensionSettingsPath ?? root.settingsPath } : {}) });
     if (options.agentNodeId !== undefined)
         root.onAgentSettings?.(options.agentNodeId, extensionSettings);
-    const sessionInput = { cwd, model: { ...resolved.model }, tools: [...resolved.tools], sessionLabel: `${options.workflowName}:${options.label}:attempt-${String(attempt)}`, ...(sessionPath ? { sessionPath } : {}), ...(root.agentDir ? { agentDir: root.agentDir } : {}), ...(root.additionalSkillPaths?.length ? { additionalSkillPaths: [...root.additionalSkillPaths] } : {}), ...(resolved.contextFiles === undefined ? {} : { contextFiles: [...resolved.contextFiles] }), ...(customTools.length ? { customTools: [...customTools] } : {}), ...(resultTool ? { resultTool } : {}), ...(resolved.systemPrompt !== undefined ? { systemPrompt: resolved.systemPrompt } : {}), systemPromptAppend: resolved.systemPromptAppend, ...(resourcePolicy ? { resourcePolicy } : {}), settings: extensionSettings, options: structuredClone(baselineOptions) };
+    const sessionInput = { cwd, model: { ...resolved.model }, tools: [...resolved.tools], sessionLabel: `${options.workflowName}:${options.label}:attempt-${String(attempt)}`, ...(sessionPath ? { sessionPath } : {}), ...(root.agentDir ? { agentDir: root.agentDir } : {}), ...(root.additionalSkillPaths?.length ? { additionalSkillPaths: [...root.additionalSkillPaths] } : {}), ...(resolved.contextFiles === undefined ? {} : { contextFiles: [...resolved.contextFiles] }), ...(customTools.length ? { customTools: [...customTools] } : {}), ...(resultTool ? { resultTool } : {}), ...(resolved.systemPrompt !== undefined ? { systemPrompt: resolved.systemPrompt } : {}), systemPromptAppend: resolved.systemPromptAppend, resourcePolicy, settings: extensionSettings, options: structuredClone(baselineOptions) };
     const setup = { prompt: task, options: sessionInput.options ?? {}, sessionInput, prepared: await preparedAgentSession(sessionInput, task), transport };
     const base = fallbackSetupContext(root, options, setupSignal);
     const context = Object.freeze({ run: base.run, identity: base.identity, attempt, signal: setupSignal, settings: extensionSettings, ...(base.tuiIndex === undefined ? {} : { tuiIndex: base.tuiIndex }), ...(base.tuiLabel === undefined ? {} : { tuiLabel: base.tuiLabel }), ...(inspection ? { mode: "inspection" } : {}) });
@@ -925,30 +1003,69 @@ async function prepareAgentSetup(root, transport, task, options, resolved, cwd,
         if (resourcePolicyWidened(resourcePolicyCeiling, setup.sessionInput.resourcePolicy))
             throw new WorkflowError("INVALID_METADATA", "Agent setup widened the prepared resource policy");
         appendResourcePolicyNarrowing(resourcePolicyCeiling, setup.sessionInput.resourcePolicy);
+        if (setup.sessionInput.resourcePolicy) {
+            const policy = setup.sessionInput.resourcePolicy;
+            policy.effective.extensions = policy.effective.extensions.map((selector) => canonicalExtensionSelector(selector, cwd));
+            for (const layer of [policy.selectorSources.global, policy.selectorSources.project, policy.selectorSources.call])
+                if (layer?.extensions !== undefined)
+                    layer.extensions = layer.extensions.map((selector) => canonicalExtensionSelector(selector, cwd));
+            if (resourcePolicyCeiling.parentSkills === undefined)
+                Reflect.deleteProperty(policy, "parentSkills");
+            else
+                policy.parentSkills = [...resourcePolicyCeiling.parentSkills];
+        }
         setup.sessionInput.options = setup.options;
         if (changedOption(setup.options, baselineOptions, "model") && typeof setup.options.model === "string")
             setup.sessionInput.model = parseModel(setup.options.model, setup.sessionInput.model, root.modelAliases, root.knownModels ?? root.availableModels, root.settingsPath);
         if (changedOption(setup.options, baselineOptions, "tools") && Array.isArray(setup.options.tools) && setup.options.tools.every((tool) => typeof tool === "string"))
             setup.sessionInput.tools = [...setup.options.tools];
-        if (changedOption(setup.options, baselineOptions, "cwd") && typeof setup.options.cwd === "string")
-            setup.sessionInput.cwd = setup.options.cwd;
+        // Pi derives trust, settings and .pi resources from cwd, so neither the session input nor a cwd option may move it.
+        if (changedOption(setup.options, baselineOptions, "cwd") || !sameFilesystemPath(cwd, setup.sessionInput.cwd))
+            throw new WorkflowError("INVALID_METADATA", "Agent setup cannot change cwd");
+        if (!root.availableModels?.has(modelCapability(setup.sessionInput.model)) && root.availableModels !== undefined)
+            throw new WorkflowError("UNKNOWN_MODEL", "Agent setup selected an unavailable model");
+        // A custom tool must not reintroduce, by name, a root tool the prepared policy left out (excludeTools, parent ceilings, selectors).
+        const shadowed = (setup.sessionInput.customTools ?? []).map(({ name }) => name).find((name) => root.tools.has(name) && !resolved.tools.includes(name));
+        if (shadowed)
+            throw new WorkflowError("UNKNOWN_TOOL", `Custom tool reintroduces a tool outside the prepared agent policy: ${shadowed}`);
+        // Like Pi's excludeTools, own and inherited exclusions also remove custom tools of those names, including ones setup hooks
+        // add, before materialization. A name that matches no root or custom tool excludes nothing and only warns. The names are
+        // the frozen configuration's, so re-evaluated options of a later turn, retry or resume cannot change them.
+        const excludedTools = new Set(configuration?.excludeTools ?? excludedToolNames(options));
+        const excludedCustomTools = (setup.sessionInput.customTools ?? []).filter(({ name }) => excludedTools.has(name)).map(({ name }) => name);
+        if (excludedCustomTools.length) {
+            setup.sessionInput.customTools = setup.sessionInput.customTools?.filter(({ name }) => !excludedTools.has(name)) ?? [];
+            // Hooks may also list their custom tool by name; root names stay subject to the policy checks below.
+            setup.sessionInput.tools = setup.sessionInput.tools.filter((tool) => root.tools.has(tool) || !excludedCustomTools.includes(tool));
+        }
+        for (const tool of excludedTools)
+            if (!options.inheritedExcludeTools?.includes(tool) && !root.tools.has(tool) && !excludedCustomTools.includes(tool))
+                root.onResourceWarning?.(`excludeTools names no root or custom tool of this agent: ${tool}`);
         const customToolNames = new Set([...(setup.sessionInput.customTools ?? []).map(({ name }) => name), ...(setup.sessionInput.resultTool ? [setup.sessionInput.resultTool.name] : [])]);
         const widened = setup.sessionInput.tools.find((tool) => !resolved.tools.includes(tool) && !customToolNames.has(tool));
         const outsideTool = widened ?? setup.sessionInput.tools.find((tool) => !root.tools.has(tool) && !customToolNames.has(tool));
         if (outsideTool)
             throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the prepared agent policy: ${outsideTool}`);
+        if (setup.sessionInput.resourcePolicy) {
+            const policy = setup.sessionInput.resourcePolicy;
+            setup.sessionInput.tools = selectResourcesByLayers(resourceSelectorLayers(policy.selectorSources, "tools"), setup.sessionInput.tools);
+            if (policy.projectTrusted !== resourcePolicyCeiling.projectTrusted)
+                policy.capabilities = await authorizedResources({ ...root, projectTrusted: policy.projectTrusted }, cwd, options);
+        }
+        if (!setup.sessionInput.tools.includes("agent"))
+            setup.sessionInput.customTools = setup.sessionInput.customTools?.filter(({ name }) => name !== "agent" && name !== "get_subagent_result" && name !== "steer_subagent") ?? [];
     }
     catch (error) {
         setup.prepared = await preparedAgentSession(setup.sessionInput, task);
         return { setup, summary: agentSetupSummary(setup, hookNames), failure: { error } };
     }
-    setup.prepared = await preparedAgentSession(setup.sessionInput, inspection ? task : workflowAgentPrompt(setup.prompt, options, attempt, previousError));
+    setup.prepared = await preparedAgentSession(setup.sessionInput, inspection ? task : setup.prompt);
     return { setup, summary: agentSetupSummary(setup, hookNames) };
 }
 export async function prepareAgentSetupForInspection(root, task, options, transport) {
     const executor = new WorkflowAgentExecutor(root);
-    const resolved = executor.resolve(options);
-    return prepareAgentSetup(root, transport, task, options, resolved, root.cwd, 1, root.runContext?.signal, [], undefined, true);
+    const configuration = await executor.prepare(options, root.cwd, root.runContext?.signal, "inspection");
+    return prepareAgentSetup(root, transport, task, { ...options, label: configuration.label ?? options.label, configuration, capabilities: { tools: configuration.tools, skills: configuration.skills.slice(configuration.skills.lastIndexOf("!*") + 1), extensions: configuration.extensions.slice(configuration.extensions.lastIndexOf("!*") + 1) } }, configuration, root.cwd, 1, root.runContext?.signal, [], undefined, true);
 }
 function attemptRecord(transport, attempt, session, setup, stats, result, error) {
     return { attempt, transport, session: session.reference, ...(result === undefined ? {} : { result }), ...(error ? { error } : {}), accounting: stats, setup };
@@ -966,52 +1083,105 @@ export function getAgentAttempts(error) {
 export class WorkflowAgentExecutor {
     root;
     transport;
-    warnedRoleTools = new Set();
     constructor(root, transport = localAgentTransport) {
         this.root = root;
         this.transport = transport;
     }
     setRunContext(runContext) { this.root.runContext = runContext; }
     resolve(options, inheritedTools) {
-        const roleName = typeof options.role === "string" ? options.role : undefined;
-        const roleDefinition = roleName ? this.root.agentDefinitions?.[roleName] : undefined;
-        if (roleName && !roleDefinition)
-            throw new WorkflowError("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${roleName}`);
-        if (inheritedTools === undefined)
-            for (const pattern of roleDefinition?.tools ?? []) {
-                const body = pattern.startsWith("!") ? pattern.slice(1) : pattern;
-                if (!pattern.startsWith("!") && !resourcePatternHasMagic(pattern) && !this.root.tools.has(body)) {
-                    const key = `${roleName ?? "agent"}:${body}`;
-                    if (!this.warnedRoleTools.has(key)) {
-                        this.warnedRoleTools.add(key);
-                        this.root.onResourceWarning?.(`Tool not available in this session for role ${roleName ?? "agent"}: ${body}. The agent runs without it.`);
-                    }
-                }
+        if (options.configuration)
+            return { ...options.configuration, ...(options.modelOverride ? { model: options.modelOverride } : {}) };
+        const ceiling = inheritedTools ?? [...this.root.tools];
+        for (const pattern of options.tools ?? [])
+            if (!pattern.startsWith("!") && !resourcePatternHasMagic(pattern) && !ceiling.includes(pattern))
+                throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the prepared agent policy: ${pattern}`);
+        const tools = options.effectiveTools ?? selectResourcesByLayers([this.root.resourceSelectors?.tools, options.tools], [...(inheritedTools ?? this.root.tools)]);
+        const missing = tools.find((tool) => !ceiling.includes(tool));
+        if (missing)
+            throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the prepared agent policy: ${missing}`);
+        const model = options.modelOverride ?? parseModel(options.model, this.root.model, this.root.modelAliases, this.root.knownModels, this.root.settingsPath);
+        return { model: physicalModel(model, this.root.modelAliases, this.root.knownModels, this.root.settingsPath), tools, systemPromptAppend: "", ...(options.contextFiles === undefined ? {} : { contextFiles: options.contextFiles }) };
+    }
+    async prepare(options, cwd = this.root.cwd, signal = this.root.runContext?.signal ?? new AbortController().signal, mode = "execution") {
+        const root = { ...this.root, projectTrusted: Boolean(this.root.projectTrusted) && options.projectTrusted !== false };
+        const policy = await this.root.agentResourcePolicy?.();
+        const capabilities = await authorizedResources(root, cwd, options);
+        // Children are new spawns of their parent's attempt; their scheduler node keys the configuration their own retries reuse.
+        const persistedKey = options.parent !== undefined ? options.agentNodeId : options.agentIdentity?.handle !== undefined ? `handle:${options.agentIdentity.handle}` : options.agentIdentity ? agentIdentityPath(options.agentIdentity) : options.agentNodeId;
+        const stored = options.configuration ?? (mode === "execution" && persistedKey && this.root.runStore?.load ? (await this.root.runStore.load()).snapshot.agentConfigurations[persistedKey] : undefined);
+        if (stored) {
+            // Without the field, the configuration was prepared before exclusions were frozen. Re-evaluated options cannot prove
+            // which exclusions it had, so it never resumes.
+            if (stored.excludeTools === undefined)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", "Prepared agent configuration predates frozen excludeTools; relaunch the workflow");
+            return validatePreparedConfiguration(root, stored, capabilities, cwd, true);
+        }
+        const original = deepFreeze(structuredClone(validateAgentOptions(options.agentOptions ?? {
+            ...(options.model === undefined ? {} : { model: options.model }), ...(options.tools === undefined ? {} : { tools: [...options.tools] }), ...(options.skills === undefined ? {} : { skills: [...options.skills] }), ...(options.extensions === undefined ? {} : { extensions: [...options.extensions] }), ...(options.contextFiles === undefined ? {} : { contextFiles: [...options.contextFiles] }),
+        })));
+        const dynamicModelAliasNames = this.root.dynamicModelAliasNames;
+        const defaults = deepFreeze({ model: { ...this.root.model }, modelAliases: { ...this.root.modelAliases }, ...(dynamicModelAliasNames === undefined ? {} : { dynamicModelAliasNames: [...dynamicModelAliasNames] }), selectorSources: structuredClone(policy?.selectorSources ?? { global: this.root.resourceSelectors ?? {}, project: {} }), settings: structuredClone(options.inheritedExtensionSettings ?? this.root.extensionSettings ?? {}) });
+        const context = Object.freeze({ options: original, cwd, projectCwd: this.root.cwd, agentDir: this.root.agentDir ?? getAgentDir(), projectTrusted: root.projectTrusted, defaults, capabilities: deepFreeze(structuredClone(capabilities)), knownModels: new Set(this.root.knownModels), availableModels: new Set(this.root.availableModels), signal, mode });
+        const configuration = {
+            ...(typeof original.label === "string" ? { label: original.label } : {}), ...(typeof original.model === "string" ? { model: original.model } : {}),
+            tools: [...(policy?.effective.tools ?? this.root.resourceSelectors?.tools ?? []), ...(options.tools ?? [])], skills: [...(policy?.effective.skills ?? this.root.resourceSelectors?.skills ?? []), ...(options.skills ?? [])], extensions: [...(policy?.effective.extensions ?? this.root.resourceSelectors?.extensions ?? []), ...(options.extensions ?? []).map((selector) => canonicalExtensionSelector(selector, cwd))],
+            ...(options.contextFiles === undefined ? {} : { contextFiles: [...options.contextFiles] }), systemPromptAppend: "", settings: structuredClone(defaults.settings),
+        };
+        for (const key of ["tools", "skills", "extensions"])
+            if (Array.isArray(original[key])) {
+                const selectors = validateSelectorList(original[key], "agent options", key, "INVALID_METADATA", false) ?? [];
+                configuration[key] = [...(policy?.effective[key] ?? this.root.resourceSelectors?.[key] ?? []), ...selectors.map((selector) => key === "extensions" ? canonicalExtensionSelector(selector, cwd) : selector)];
             }
-        const resolved = resolveRole(roleName, {
-            cwd: this.root.cwd,
-            ...(roleDefinition === undefined ? {} : { definition: roleDefinition }),
-            ...(this.root.agentDefinitions === undefined ? {} : { definitions: this.root.agentDefinitions }),
-            ...(this.root.agentDir === undefined ? {} : { agentDir: this.root.agentDir }),
-            selectorSources: { global: this.root.resourceSelectors ?? {}, project: {} },
-            ...(this.root.modelAliases === undefined ? {} : { modelAliases: this.root.modelAliases }),
-            ...(this.root.knownModels === undefined ? {} : { knownModels: this.root.knownModels }),
-            ...(this.root.availableModels === undefined ? {} : { availableModels: this.root.availableModels }),
-            ...(this.root.blockedAliases === undefined ? {} : { blockedAliases: this.root.blockedAliases }),
-            ...(this.root.blockedAliasTargets === undefined ? {} : { blockedAliasTargets: this.root.blockedAliasTargets }),
-            ...(this.root.settingsPath === undefined ? {} : { settingsPath: this.root.settingsPath }),
-            rootModel: this.root.model,
-            rootTools: this.root.tools,
-            ...(inheritedTools === undefined ? {} : { inheritedTools }),
-            ...(options.model === undefined ? {} : { model: options.model }),
-            ...(options.modelOverride === undefined ? {} : { modelOverride: options.modelOverride }),
-            ...(options.tools === undefined ? {} : { tools: options.tools }),
-            ...(options.skills === undefined ? {} : { skills: options.skills }),
-            ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
-            ...(options.contextFiles === undefined ? {} : { contextFiles: options.contextFiles }),
-            ...(options.effectiveTools === undefined ? {} : { effectiveTools: options.effectiveTools }),
-        });
-        return { model: physicalModel(resolved.model ?? this.root.model, this.root.modelAliases, this.root.knownModels, this.root.settingsPath), ...(resolved.requestedModel === undefined ? {} : { requestedModel: resolved.requestedModel }), tools: resolved.tools ?? [], ...(resolved.overrideSystemPrompt ? { systemPrompt: resolved.prompt } : {}), systemPromptAppend: resolved.overrideSystemPrompt ? "" : resolved.prompt, ...(resolved.contextFiles === undefined ? {} : { contextFiles: resolved.contextFiles }) };
+        if (original.contextFiles !== undefined)
+            configuration.contextFiles = [...(validateContextFileScopes(original.contextFiles, "agent options") ?? [])];
+        const hooks = [...(this.root.agentPreparationHooks ?? [])].sort(byPriorityThenName);
+        const load = this.root.extensionLoad;
+        if (load?.errors.length) {
+            // A failed extension may have owned an option, and its factory may have registered hooks before it failed. Only a
+            // schema whose registration names a loaded extension as `source` proves ownership.
+            const loaded = new Set(load.loaded.map(extensionIdentity));
+            const declared = new Set(hooks.flatMap(({ optionsSchema, source }) => source !== undefined && loaded.has(extensionIdentity(source)) && object(optionsSchema?.properties) ? Object.keys(optionsSchema.properties) : []));
+            const unowned = Object.keys(original).find((key) => !isCoreAgentOption(key) && !declared.has(key));
+            if (unowned !== undefined)
+                throw new WorkflowError("INVALID_METADATA", `Agent option ${unowned} has no owner proven to have loaded while extensions failed to load: ${load.errors.join("; ")}`);
+        }
+        for (const hook of hooks)
+            if (hook.optionsSchema !== undefined && !Value.Check(hook.optionsSchema, original))
+                throw new WorkflowError("INVALID_METADATA", `Agent options do not match preparation schema: ${hook.name}`);
+        if (typeof original.model === "string" && this.root.blockedAliases?.has(original.model.split(":")[0] ?? ""))
+            throw new WorkflowError("UNKNOWN_MODEL", `Unknown model alias ${original.model} resolved to ${this.root.blockedAliasTargets?.[original.model.split(":")[0] ?? ""] ?? "an unavailable target"}`);
+        for (const hook of hooks) {
+            if (signal.aborted)
+                throw new WorkflowError("CANCELLED", "Agent preparation cancelled");
+            await hook.prepare(configuration, context);
+        }
+        if (signal.aborted)
+            throw new WorkflowError("CANCELLED", "Agent preparation cancelled");
+        const { model: preparedModel, ...preparedOptions } = configuration;
+        validateAgentOptions(preparedOptions);
+        if (preparedModel !== undefined && (typeof preparedModel !== "string" || !preparedModel.trim()))
+            throw new WorkflowError("INVALID_METADATA", "Prepared agent model must be a non-empty string");
+        if (preparedModel && this.root.blockedAliases?.has(preparedModel.split(":")[0] ?? ""))
+            throw new WorkflowError("UNKNOWN_MODEL", `Unknown model alias ${preparedModel} resolved to ${this.root.blockedAliasTargets?.[preparedModel.split(":")[0] ?? ""] ?? "an unavailable target"}`);
+        configuration.extensions = configuration.extensions.map((selector) => canonicalExtensionSelector(selector, cwd));
+        // A hook that passes on an inherited virtual `workflow/<alias>` root model gets the same physical target as no hook.
+        const model = physicalModel(preparedModel === undefined ? this.root.model : resolveModelReference(preparedModel, this.root.modelAliases, this.root.knownModels, this.root.settingsPath), this.root.modelAliases, this.root.knownModels, this.root.settingsPath);
+        const excludedTools = excludedToolNames({ agentOptions: original, ...(options.inheritedExcludeTools ? { inheritedExcludeTools: options.inheritedExcludeTools } : {}) });
+        const tools = selectResourcesByLayers([configuration.tools], capabilities.tools).filter((tool) => !excludedTools.has(tool));
+        for (const pattern of validateSelectorList(original.tools, "agent options", "tools", "INVALID_METADATA", false) ?? [])
+            if (!pattern.startsWith("!") && !resourcePatternHasMagic(pattern) && !capabilities.tools.includes(pattern))
+                throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the prepared agent policy: ${pattern}`);
+        for (const pattern of unmatchedResourcePatterns(configuration.tools, capabilities.tools))
+            this.root.onResourceWarning?.(`Tool selector currently matches no authorized tool: ${pattern}`);
+        const skills = selectResourcesByLayers([configuration.skills], capabilities.skills);
+        const extensions = selectResourcesByLayers([configuration.extensions], capabilities.extensions);
+        const concrete = validatePreparedConfiguration(root, { ...configuration, model, tools, excludeTools: [...excludedTools], skills: [...configuration.skills, "!*", ...skills], extensions: [...configuration.extensions, "!*", ...extensions], projectTrusted: context.projectTrusted }, capabilities, cwd, false);
+        if (mode === "execution") {
+            if (persistedKey && this.root.runStore?.saveAgentConfiguration)
+                await this.root.runStore.saveAgentConfiguration(persistedKey, concrete);
+            await options.onConfiguration?.(concrete);
+        }
+        return concrete;
     }
     async execute(task, options, signal, customTools = [], setSteer, beforeRetry) {
         const executionSignal = signal ?? this.root.runContext?.signal;
@@ -1019,7 +1189,7 @@ export class WorkflowAgentExecutor {
             throw new WorkflowError("INVALID_METADATA", "retries must be a non-negative integer");
         if (options.timeoutMs !== undefined && options.timeoutMs !== null && (!Number.isInteger(options.timeoutMs) || options.timeoutMs <= 0))
             throw new WorkflowError("INVALID_METADATA", "timeoutMs must be null or a positive integer");
-        let resolved = this.resolve(options);
+        let resolved;
         let recoveryModel;
         let cwd;
         if (options.parent) {
@@ -1049,6 +1219,15 @@ export class WorkflowAgentExecutor {
                 throw new WorkflowError("INVALID_METADATA", "Only child agents or worktree scopes may provide a cwd");
             cwd = this.root.cwd;
         }
+        const configuration = await this.prepare(options, cwd, executionSignal);
+        const parentSkills = options.parent === undefined ? undefined : options.capabilities?.skills;
+        options = { ...options, label: configuration.label ?? options.label, configuration, ...(parentSkills ? { parentSkills } : {}), capabilities: { tools: configuration.tools, skills: configuration.skills.slice(configuration.skills.lastIndexOf("!*") + 1), extensions: configuration.extensions.slice(configuration.extensions.lastIndexOf("!*") + 1) } };
+        resolved = this.resolve(options);
+        if (!resolved.tools.includes("agent"))
+            customTools = customTools.filter(({ name }) => name !== "agent" && name !== "get_subagent_result" && name !== "steer_subagent");
+        // A child's skill ceiling is what its parent session has loaded when it spawns, so withdrawn skills never stay in it.
+        let publishLoadedSkills;
+        customTools = customTools.map((tool) => tool.name !== "agent" ? tool : { ...tool, execute: (...args) => { publishLoadedSkills?.(); return tool.execute(...args); } });
         const attempts = [];
         let maxAttempts = (options.retries ?? 0) + 1;
         for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
@@ -1076,7 +1255,7 @@ export class WorkflowAgentExecutor {
             const resultSchema = Compile(options.schema ?? defaultWorkflowResultSchema);
             let resultAccepted = false;
             const resultTool = defineTool({
-                name: "workflow_result", label: "Workflow Result", description: "Submit the terminal workflow result", parameters: resultSchema.Type(),
+                name: "workflow_result", label: "Workflow Result", description: options.schema ? "Submit the terminal workflow result. Call exactly once to finish the current task or message, with a value matching the required schema. Do not return prose as the final result." : "Submit the terminal workflow result. Call exactly once to finish the current task or message, with { result: \"final response\" }. Do not return prose as the final result.", parameters: resultSchema.Type(),
                 async execute(_id, value) {
                     if (!resultSchema.Check(value) || !jsonValue(value))
                         return { content: [{ type: "text", text: "Result does not match the required schema." }], details: {}, isError: true };
@@ -1112,12 +1291,24 @@ export class WorkflowAgentExecutor {
             } : undefined;
             try {
                 setupFailed = true;
-                const prepared = await prepareAgentSetup(this.root, this.transport, task, options, resolved, cwd, attempt, attemptSignal, customTools, resultTool, false, attempts.at(-1)?.error?.message);
+                const prepared = await prepareAgentSetup(this.root, this.transport, task, options, resolved, cwd, attempt, attemptSignal, customTools, resultTool, false);
                 setup = prepared.setup;
                 const attemptSetup = prepared.setup;
                 setupSummary = prepared.summary;
                 if (prepared.failure)
                     throw prepared.failure.error;
+                let attemptCapabilities;
+                if (options.agentNodeId !== undefined) {
+                    const policy = setup.prepared.resourcePolicy;
+                    const sources = policy?.selectorSources;
+                    const capabilities = policy?.capabilities ?? options.capabilities;
+                    attemptCapabilities = {
+                        tools: setup.prepared.tools,
+                        skills: selectResourcesByLayers(sources ? resourceSelectorLayers(sources, "skills") : [], capabilities?.skills ?? []),
+                        extensions: selectResourcesByLayers(sources ? resourceSelectorLayers(sources, "extensions") : [], capabilities?.extensions ?? []),
+                    };
+                    this.root.onAgentCapabilities?.(options.agentNodeId, attemptCapabilities, policy?.projectTrusted ?? false);
+                }
                 setupFailed = false;
                 if (attemptSignal.aborted)
                     throw new WorkflowError("CANCELLED", "Agent cancelled");
@@ -1153,6 +1344,14 @@ export class WorkflowAgentExecutor {
                             }
                             if (policy)
                                 setupSummary = { ...setupSummary, resourceSelectors: { ...resourcePolicySummary(policy, attemptSetup.sessionInput.tools), ...(inspection ? { skills: [...inspection.skills], extensions: [...inspection.extensions] } : {}) } };
+                            // The session's currently loaded skills, within its authorization, are the skill ceiling its children inherit.
+                            const nodeId = options.agentNodeId, selected = attemptCapabilities, live = session;
+                            publishLoadedSkills = nodeId === undefined || selected === undefined || live?.getResourceInspection === undefined ? undefined : () => {
+                                const loaded = live.getResourceInspection?.();
+                                if (loaded)
+                                    this.root.onAgentCapabilities?.(nodeId, { ...selected, skills: [...loaded.skills] }, attemptSetup.prepared.resourcePolicy?.projectTrusted ?? false);
+                            };
+                            publishLoadedSkills?.();
                         },
                         onBeforeComplete: async () => {
                             if (options.worktreeOwner)
@@ -1192,6 +1391,7 @@ export class WorkflowAgentExecutor {
                 const runtimeRun = { id: transportBase.run.runId, namespaceId: transportBase.run.sessionId, workflowName: transportBase.run.workflow.name };
                 const providerRecovery = options.providerErrorRecovery;
                 const runtimeAgent = { id: transportBase.identity.callSite, structuralPath: [...transportBase.identity.structuralPath], ...(options.parent ? { parentId: options.parent } : {}) };
+                const attemptControl = attemptControlText(options, attempt, attempts.at(-1)?.error?.message);
                 const runtimeRequest = {
                     task: setup.prepared.initialPrompt ?? setup.prompt,
                     cwd: setup.prepared.cwd,
@@ -1200,6 +1400,7 @@ export class WorkflowAgentExecutor {
                     // Pi sessions execute the prepared native definitions; the executor does not duplicate them as neutral request tools.
                     customTools: [],
                     ...(options.schema ? { resultSchema: options.schema } : {}),
+                    ...(attemptControl ? { turnControl: attemptControl } : {}),
                     run: runtimeRun,
                     agent: runtimeAgent,
                     signal: attemptSignal,
@@ -1272,6 +1473,30 @@ export class WorkflowAgentExecutor {
         throw new WorkflowError("AGENT_FAILED", "Agent execution failed");
     }
 }
+/**
+ * A child spawned by its parent's `agent` tool shares the parent's structural scope, breadcrumb and worktree, but owns its
+ * call site under the parent's identity and spawn generation, with a per-label occurrence. It never carries the parent's
+ * handle or turn. Children are new spawns: a retried or resumed parent spawns them again under new identities.
+ */
+function childIdentity(parent, scope, label) {
+    const occurrences = parent.childOccurrences ?? new Map();
+    parent.childOccurrences = occurrences;
+    const occurrence = (occurrences.get(label) ?? 0) + 1;
+    occurrences.set(label, occurrence);
+    // The parent's scheduler node number marks the spawn generation: a cold-resumed or retried parent runs as a new node.
+    const generation = parent.id.slice(parent.id.lastIndexOf(":") + 1);
+    return { structuralPath: [...scope.structuralPath], callSite: `child:${agentIdentityPath(scope)}/spawn:${generation}/${label}`, occurrence, ...(scope.parentBreadcrumb ? { parentBreadcrumb: scope.parentBreadcrumb } : {}), ...(scope.worktreeOwner ? { worktreeOwner: scope.worktreeOwner } : {}) };
+}
+/**
+ * Foreign errors keep descriptive core codes such as UNKNOWN_MODEL. Cancellation and budget exhaustion drive node and run
+ * state, so a foreign error may claim CANCELLED only for an aborted node and never BUDGET_EXHAUSTED.
+ */
+function scheduledErrorCode(error, aborted) {
+    if (error instanceof WorkflowError)
+        return error.code;
+    const code = errorCode(error);
+    return code === undefined || code === "BUDGET_EXHAUSTED" || (code === "CANCELLED" && !aborted) ? "AGENT_FAILED" : code;
+}
 export class FairAgentScheduler {
     runner;
     sessionLimit;
@@ -1314,6 +1539,17 @@ export class FairAgentScheduler {
             throw new WorkflowError("INTERNAL_ERROR", `Unknown scheduler run: ${runId}`);
         run.extensionSettings = settings === undefined ? undefined : deepFreeze(structuredClone(settings));
     }
+    async setConfiguration(agentId, configuration) {
+        const node = this.#node(agentId);
+        node.options = Object.freeze({ ...node.options, configuration: deepFreeze(structuredClone(configuration)), tools: Object.freeze([...configuration.tools]) });
+        this.#persist(node.runId);
+        await this.flush(node.runId);
+    }
+    setAttemptCapabilities(agentId, capabilities, projectTrusted) {
+        const node = this.#node(agentId);
+        node.attemptCapabilities = deepFreeze(structuredClone(capabilities));
+        node.attemptProjectTrusted = projectTrusted;
+    }
     setExtensionSettings(agentId, settings) {
         const node = this.#node(agentId);
         node.options = Object.freeze({ ...node.options, extensionSettings: deepFreeze(structuredClone(settings)) });
@@ -1325,7 +1561,7 @@ export class FairAgentScheduler {
             throw new WorkflowError("INTERNAL_ERROR", `Unknown scheduler run: ${runId}`);
         const parent = parentId ? this.#nodes.get(parentId) : undefined;
         if (parentId && (!parent || parent.runId !== runId))
-            throw new WorkflowError("UNKNOWN_AGENT_TYPE", "Parent agent is not owned by this run");
+            throw new WorkflowError("UNKNOWN_AGENT", "Parent agent is not owned by this run");
         const effective = this.#inherit(run, parent, options);
         const id = `${runId}:${String(++this.#nextId)}`;
         const tuiIndex = ++run.nextIndex;
@@ -1342,12 +1578,11 @@ export class FairAgentScheduler {
             node.state = "running";
             this.#persist(runId);
             try {
-                const value = await this.runner({ id, runId, tuiIndex, ...(parentId ? { parentId } : {}), prompt, options: effective, signal: node.controller.signal, setSteer: (handler) => { node.steer = handler; } });
+                const value = await this.runner({ id, runId, tuiIndex, ...(parentId ? { parentId } : {}), prompt, options: node.options, signal: node.controller.signal, setSteer: (handler) => { node.steer = handler; } });
                 this.#settle(node, { id, ok: true, value });
             }
             catch (error) {
-                const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", errorText(error));
-                this.#settle(node, { id, ok: false, error: { code: typed.code, message: typed.message } });
+                this.#settle(node, { id, ok: false, error: { code: scheduledErrorCode(error, node.controller.signal.aborted), message: errorText(error) } });
             }
         };
         this.#nodes.set(id, node);
@@ -1360,7 +1595,7 @@ export class FairAgentScheduler {
         const parent = this.#node(parentId);
         const child = this.#node(childId);
         if (child.parentId !== parentId)
-            throw new WorkflowError("UNKNOWN_AGENT_TYPE", "Results are scoped to direct children");
+            throw new WorkflowError("UNKNOWN_AGENT", "Results are scoped to direct children");
         if (child.collected || !child.promise)
             throw new WorkflowError("AGENT_RESULT_COLLECTED", "Child result has already been collected; nested results are one-shot");
         if (child.collecting)
@@ -1402,7 +1637,7 @@ export class FairAgentScheduler {
     async steer(parentId, childId, message) {
         const child = this.#node(childId);
         if (child.parentId !== parentId)
-            throw new WorkflowError("UNKNOWN_AGENT_TYPE", "Steering is scoped to direct children");
+            throw new WorkflowError("UNKNOWN_AGENT", "Steering is scoped to direct children");
         if (child.state !== "running" && child.state !== "waiting_for_child")
             throw new WorkflowError("AGENT_FAILED", "Child is not running");
         if (!child.steer)
@@ -1472,13 +1707,13 @@ export class FairAgentScheduler {
         }
         this.#dispatch();
     }
-    toolsFor(parentId, resolveTools) {
+    toolsFor(parentId) {
         const parent = this.#node(parentId);
-        if (!parent.options.tools.includes("agent"))
+        if (!(parent.attemptCapabilities?.tools ?? parent.options.tools).includes("agent"))
             return [];
         const agentTool = defineTool({
-            name: "agent", label: "Child Agent", description: "Start a direct child agent",
-            parameters: Type.Object({ prompt: Type.String(), label: Type.String(), tools: Type.Optional(Type.Array(Type.String())), skills: Type.Optional(Type.Array(Type.String())), extensions: Type.Optional(Type.Array(Type.String())), model: Type.Optional(Type.String()), role: Type.Optional(Type.String()), contextFiles: Type.Optional(Type.Array(Type.String())), outputSchema: Type.Optional(Type.Record(Type.String(), Type.Unknown())), retries: Type.Optional(Type.Integer({ minimum: 0 })), timeoutMs: Type.Optional(Type.Union([Type.Integer({ minimum: 1 }), Type.Null()])) }, { additionalProperties: true }),
+            name: "agent", label: "Child Agent", description: "Start a direct child agent. You own the children you create: collect each result with get_subagent_result and do not leave descendants running.",
+            parameters: Type.Object({ prompt: Type.String(), label: Type.String(), tools: Type.Optional(Type.Array(Type.String())), excludeTools: Type.Optional(Type.Array(Type.String(), { description: "Exact tool names removed after preparation; cannot remove workflow_result" })), skills: Type.Optional(Type.Array(Type.String())), extensions: Type.Optional(Type.Array(Type.String())), model: Type.Optional(Type.String()), contextFiles: Type.Optional(Type.Array(Type.String())), outputSchema: Type.Optional(Type.Record(Type.String(), Type.Unknown())), retries: Type.Optional(Type.Integer({ minimum: 0 })), timeoutMs: Type.Optional(Type.Union([Type.Integer({ minimum: 1 }), Type.Null()])) }, { additionalProperties: true }),
             outputSchema: Type.Object({ id: Type.String() }),
             execute: async (_id, params) => {
                 if (!isChildAgentToolParams(params))
@@ -1487,10 +1722,10 @@ export class FairAgentScheduler {
                 const outputSchema = params.outputSchema;
                 if (outputSchema !== undefined)
                     validateSchema(outputSchema, "agent outputSchema");
-                const tools = (params.tools !== undefined || params.role !== undefined || params.skills !== undefined || params.extensions !== undefined ? resolveTools?.(params.role, params.tools, params.model, parent.options.tools, params.skills, params.extensions) : undefined) ?? params.tools ?? parent.options.tools;
+                const tools = parent.attemptCapabilities?.tools ?? parent.options.tools;
                 const agentOptions = { ...params };
                 Reflect.deleteProperty(agentOptions, "prompt");
-                const options = { label: params.label, requestedLabel: params.label, cwd: parent.options.cwd, tools, agentOptions, ...(params.skills ? { skills: params.skills } : {}), ...(params.extensions ? { extensions: params.extensions } : {}), ...(params.model ? { model: params.model } : {}), ...(params.role ? { role: params.role } : {}), ...(params.contextFiles ? { contextFiles: params.contextFiles } : {}), ...(outputSchema === undefined ? {} : { schema: outputSchema }), ...(params.retries === undefined ? {} : { retries: params.retries }), ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }) };
+                const options = { label: params.label, requestedLabel: params.label, cwd: parent.options.cwd, tools, agentOptions, ...(params.skills ? { skills: params.skills } : {}), ...(params.extensions ? { extensions: params.extensions } : {}), ...(params.model ? { model: params.model } : {}), ...(params.contextFiles ? { contextFiles: params.contextFiles } : {}), ...(outputSchema === undefined ? {} : { schema: outputSchema }), ...(params.retries === undefined ? {} : { retries: params.retries }), ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }) };
                 const child = this.spawn(parent.runId, params.prompt, options, parentId);
                 return { content: [{ type: "text", text: JSON.stringify({ id: child.id }) }], details: { id: child.id }, structuredContent: { id: child.id } };
             },
@@ -1561,11 +1796,15 @@ export class FairAgentScheduler {
             return Object.freeze({ ...options, tools: Object.freeze([...inheritedTools]), ...(extensionSettings === undefined ? {} : { extensionSettings }), ...(options.agentOptions ? { agentOptions: structuredClone(options.agentOptions) } : {}), ...(options.agentIdentity ? { agentIdentity: Object.freeze({ ...options.agentIdentity, structuralPath: Object.freeze([...options.agentIdentity.structuralPath]) }) } : {}) });
         if (options.cwd !== parent.options.cwd)
             throw new WorkflowError("UNKNOWN_TOOL", "Child cwd cannot differ from its parent");
-        const forbidden = inheritedTools.find((tool) => !parent.options.tools.includes(tool));
+        const parentCapabilities = parent.attemptCapabilities ?? (parent.options.configuration ? { tools: parent.options.configuration.tools, skills: parent.options.configuration.skills.slice(parent.options.configuration.skills.lastIndexOf("!*") + 1), extensions: parent.options.configuration.extensions.slice(parent.options.configuration.extensions.lastIndexOf("!*") + 1) } : parent.options.capabilities);
+        const forbidden = inheritedTools.find((tool) => !(parentCapabilities?.tools ?? parent.options.tools).includes(tool));
         if (forbidden)
             throw new WorkflowError("UNKNOWN_TOOL", `Child tool escalates parent boundary: ${forbidden}`);
-        const identity = options.agentIdentity ?? parent.options.agentIdentity;
-        return Object.freeze({ ...options, cwd: parent.options.cwd, tools: Object.freeze([...inheritedTools]), ...(extensionSettings === undefined ? {} : { extensionSettings }), ...(options.agentOptions ? { agentOptions: structuredClone(options.agentOptions) } : {}), ...(parent.options.parentBreadcrumb && !options.parentBreadcrumb ? { parentBreadcrumb: parent.options.parentBreadcrumb } : {}), ...(identity ? { agentIdentity: Object.freeze({ ...identity, structuralPath: Object.freeze([...identity.structuralPath]) }) } : {}), ...(parent.options.worktreeOwner ? { worktreeOwner: parent.options.worktreeOwner } : {}) });
+        const identity = options.agentIdentity ?? (parent.options.agentIdentity ? childIdentity(parent, parent.options.agentIdentity, options.label) : undefined);
+        // Children inherit the exclusions frozen in their parent's configuration, not its re-evaluated options.
+        const inheritedExcludeTools = [...(parent.options.configuration?.excludeTools ?? excludedToolNames(parent.options))];
+        const projectTrusted = (parent.attemptProjectTrusted ?? parent.options.configuration?.projectTrusted ?? parent.options.projectTrusted) !== false && options.projectTrusted !== false;
+        return Object.freeze({ ...options, projectTrusted, ...(inheritedExcludeTools.length ? { inheritedExcludeTools: Object.freeze(inheritedExcludeTools) } : {}), ...(parentCapabilities ? { capabilities: parentCapabilities } : {}), cwd: parent.options.cwd, tools: Object.freeze([...inheritedTools]), ...(extensionSettings === undefined ? {} : { extensionSettings }), ...(options.agentOptions ? { agentOptions: structuredClone(options.agentOptions) } : {}), ...(parent.options.parentBreadcrumb && !options.parentBreadcrumb ? { parentBreadcrumb: parent.options.parentBreadcrumb } : {}), ...(identity ? { agentIdentity: Object.freeze({ ...identity, structuralPath: Object.freeze([...identity.structuralPath]) }) } : {}), ...(parent.options.worktreeOwner ? { worktreeOwner: parent.options.worktreeOwner } : {}) });
     }
     #enqueue(runId, node, start) { this.#runs.get(runId)?.queue.push({ ...(node ? { node } : {}), start }); this.#dispatch(); }
     #dispatch() {
@@ -1590,8 +1829,7 @@ export class FairAgentScheduler {
                     run.beforeLaunch?.();
                 }
                 catch (error) {
-                    const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", errorText(error));
-                    this.#settle(item.node, { id: item.node.id, ok: false, error: { code: typed.code, message: typed.message } });
+                    this.#settle(item.node, { id: item.node.id, ok: false, error: { code: scheduledErrorCode(error, item.node.controller.signal.aborted), message: errorText(error) } });
                     continue;
                 }
             }
@@ -1643,7 +1881,7 @@ export class FairAgentScheduler {
     #node(id) {
         const node = this.#nodes.get(id);
         if (!node)
-            throw new WorkflowError("UNKNOWN_AGENT_TYPE", `Unknown owned agent: ${id}`);
+            throw new WorkflowError("UNKNOWN_AGENT", `Unknown owned agent: ${id}`);
         return node;
     }
     #persist(runId) {