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

package/dist/src/agent-execution.js

@@ -1,22 +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, 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, 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 } from "./paths.js";
-import { canonicalExtensionSelector, resolveRole } from "./roles.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, validateContextFileScopes, validateSelectorList, validateWorkflowExtensionSettings } from "./settings.js";
+import { agentIdentityPath } from "./execution.js";
 const localToolTimingExtension = createToolTimingExtension();
 function parseModel(value, fallback, aliases = {}, knownModels, settingsPath) {
     if (!value)
@@ -24,19 +27,83 @@ 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 };
 }
-const extensionDirectory = dirname(fileURLToPath(import.meta.url));
-const workflowPackageRoot = basename(dirname(extensionDirectory)) === "dist" ? resolve(extensionDirectory, "../..") : resolve(extensionDirectory, "..");
-const WORKFLOW_HOST_ENTRIES = new Set([
-    canonicalPath(resolve(workflowPackageRoot, "src/index.ts")),
-    canonicalPath(resolve(workflowPackageRoot, "dist/src/index.js")),
-    canonicalPath(resolve(workflowPackageRoot, "starter/index.ts")),
-    canonicalPath(resolve(workflowPackageRoot, "dist/starter/index.js")),
-    canonicalPath(resolve(workflowPackageRoot, "subagents/index.ts")),
-    canonicalPath(resolve(workflowPackageRoot, "dist/subagents/index.js")),
-]);
+const WORKFLOW_HOST_ENTRY_PATHS = ["src/index.ts", "dist/src/index.js", "starter/index.ts", "dist/starter/index.js", "subagents/index.ts", "dist/subagents/index.js"];
+function isWorkflowHostEntry(path) {
+    const entryPath = canonicalPath(path);
+    let packageRoot = dirname(entryPath);
+    while (packageRoot !== dirname(packageRoot)) {
+        const packageMetadataPath = join(packageRoot, "package.json");
+        if (existsSync(packageMetadataPath)) {
+            try {
+                const metadata = JSON.parse(readFileSync(packageMetadataPath, "utf8"));
+                if (typeof metadata !== "object" || metadata === null || !("name" in metadata) || !isCorePackageName(metadata.name))
+                    return false;
+                return WORKFLOW_HOST_ENTRY_PATHS.some((entry) => canonicalPath(join(packageRoot, entry)) === entryPath);
+            }
+            catch {
+                return false;
+            }
+        }
+        packageRoot = dirname(packageRoot);
+    }
+    return false;
+}
 const WORKFLOW_DIRECTORY = "pi-extensible-workflows";
 function workflowSystemPromptPath(cwd, agentDir, projectTrusted) {
     const projectPath = join(cwd, ".pi", WORKFLOW_DIRECTORY, "SYSTEM.md");
@@ -71,34 +138,41 @@ function loadPiPackageDirectory() {
         }
     }).catch((error) => ({ error: `could not load @earendil-works/pi-coding-agent package metadata: ${errorText(error)}` }));
 }
-let nativePromptTemplateModule;
-async function loadNativePromptTemplateModule() {
+const nativeCoreModules = new Map();
+/** Pi does not export these core modules, so inspection loads them from the installed package. */
+async function loadNativeCoreModule(file, label) {
     const packageDirectory = await loadPiPackageDirectory();
-    let promptTemplatePath;
+    let modulePath;
     if (packageDirectory.directory) {
-        const candidate = resolve(packageDirectory.directory, "dist/core/prompt-templates.js");
+        const candidate = resolve(packageDirectory.directory, "dist/core", file);
         if (existsSync(candidate))
-            promptTemplatePath = candidate;
+            modulePath = candidate;
     }
-    promptTemplatePath ??= resolve(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "core/prompt-templates.js");
+    modulePath ??= resolve(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "core", file);
     const packageDirectoryError = packageDirectory.error ? ` Package directory lookup failed: ${packageDirectory.error}` : "";
-    return nativePromptTemplateModule ??= import(promptTemplatePath).then((module) => module).catch((error) => { throw new Error(`Could not load Pi prompt templates.${packageDirectoryError}`, { cause: error }); });
+    let loaded = nativeCoreModules.get(file);
+    if (!loaded) {
+        loaded = import(modulePath).catch((error) => { throw new Error(`Could not load Pi ${label}.${packageDirectoryError}`, { cause: error }); });
+        nativeCoreModules.set(file, loaded);
+    }
+    return loaded;
 }
 async function expandPromptTemplateForInspection(text, templates) {
-    return (await loadNativePromptTemplateModule()).expandPromptTemplate(text, templates);
+    return (await loadNativeCoreModule("prompt-templates.js", "prompt templates")).expandPromptTemplate(text, templates);
+}
+async function buildSystemPromptForInspection(options) {
+    return (await loadNativeCoreModule("system-prompt.js", "system prompt builder")).buildSystemPrompt(options);
 }
 async function preparePiPrompt(native, text) {
     const session = native;
     const diagnostics = [];
     const runner = session._extensionRunner;
-    const baseSystemPrompt = typeof session._baseSystemPrompt === "string" ? session._baseSystemPrompt : session.systemPrompt ?? "";
+    const baseSystemPrompt = session.systemPrompt ?? "";
     const baseOptions = session._baseSystemPromptOptions;
     const expandSkillCommand = session._expandSkillCommand;
     const templates = session.promptTemplates;
     if (!runner)
         diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: extension runner is missing", source: "Pi session" });
-    if (typeof session._baseSystemPrompt !== "string")
-        diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: base system prompt is missing", source: "Pi session" });
     if (baseOptions === undefined)
         diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: base system prompt options are missing", source: "Pi session" });
     if (typeof expandSkillCommand !== "function")
@@ -129,9 +203,11 @@ async function preparePiPrompt(native, text) {
                 diagnostics.push({ type: "error", message: `Pi prompt template expansion is unavailable: ${errorText(error)}`, source: "Pi session" });
             }
         }
-        const result = !inputHandled && runner && baseOptions !== undefined ? await runner.emitBeforeAgentStart(expandedPrompt, undefined, baseSystemPrompt, baseOptions) : undefined;
+        const result = !inputHandled && runner && baseOptions !== undefined ? await runner.emitBeforeAgentStart(expandedPrompt, undefined, baseOptions) : undefined;
         const prepared = result;
-        return { prompt: text, expandedPrompt, systemPrompt: typeof prepared?.systemPrompt === "string" ? prepared.systemPrompt : baseSystemPrompt, systemPromptOptions: baseOptions, messages: prepared?.messages ?? [], inputHandled, diagnostics };
+        const systemPromptOptions = prepared?.systemPromptOptions ?? baseOptions;
+        const systemPrompt = prepared?.systemPromptOptions === undefined ? baseSystemPrompt : await buildSystemPromptForInspection(prepared.systemPromptOptions);
+        return { prompt: text, expandedPrompt, systemPrompt, systemPromptOptions, messages: prepared?.messages ?? [], inputHandled, diagnostics };
     }
     finally {
         unsubscribe?.();
@@ -175,6 +251,64 @@ export function flushExtensionProviders(resourceLoader, modelRuntime) {
     runtime.pendingNativeProviderRegistrations = [];
     return failures;
 }
+/**
+ * The CLI adds Pi's built-in extensions itself; SDK sessions only get them from these public
+ * factories (docs/sdk.md). As `builtin` entries they obey `-builtin:<name>` settings, and like the
+ * CLI's they are replaceable by an extension that registers the same tools or commands.
+ * NOTE: Pi does not export the built-in llama.cpp extension, so workflow agents cannot use models it
+ * provides. Declare the server as a provider in models.json instead.
+ */
+function builtinExtensions() {
+    return [
+        { name: "codemode", factory: createCodemodeExtension(), replaceable: true, builtin: true },
+        { name: "tool-search", factory: createToolSearchExtension(), replaceable: true, builtin: true },
+        { name: "mcp", factory: createMcpExtension(), replaceable: true, builtin: true },
+    ];
+}
+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);
@@ -188,33 +322,34 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
     const tools = [...new Set([...input.tools, ...customTools.map(({ name }) => name)])];
     let settingsManager;
     let resourceLoader;
+    const builtins = builtinExtensions();
+    const builtinNames = builtins.flatMap((extension) => typeof extension === "function" ? [] : [extension.name]);
+    const extensionFactories = [...builtins, ...(input.extensionFactories ?? [])];
     const policy = input.resourcePolicy;
     if (policy) {
         settingsManager = SettingsManager.create(input.cwd, agentDir, { projectTrusted: false });
         settingsManager.setProjectTrusted(policy.projectTrusted);
-        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
+        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager, builtinExtensions: builtinNames });
         const resolved = await packageManager.resolve();
-        const discoveredExtensions = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalPath(path)))];
+        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 extensionPaths = selectedExtensions.filter((path) => !WORKFLOW_HOST_ENTRIES.has(path));
+        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,
@@ -222,23 +357,24 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
             additionalExtensionPaths: extensionPaths,
             noSkills: true,
             additionalSkillPaths: [...new Set([...skillPaths, ...(input.additionalSkillPaths ?? [])])],
-            ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
+            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 {
         settingsManager = SettingsManager.create(input.cwd, agentDir, { projectTrusted: true });
-        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
+        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager, builtinExtensions: builtinNames });
         const resolved = await packageManager.resolve();
-        const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled }) => enabled).map(({ path }) => canonicalPath(path)).filter((path) => !WORKFLOW_HOST_ENTRIES.has(path)))];
-        resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, settingsManager, noExtensions: true, additionalExtensionPaths: extensionPaths, ...(input.additionalSkillPaths?.length ? { additionalSkillPaths: [...input.additionalSkillPaths] } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(contextFilesOverride ? { agentsFilesOverride: contextFilesOverride } : {}), ...systemPromptOptions, ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
+        const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled }) => enabled).map(({ path }) => extensionIdentity(path)).filter((path) => path.startsWith(BUILTIN_EXTENSION_PREFIX) || !isWorkflowHostEntry(path)))];
+        resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, settingsManager, noExtensions: true, additionalExtensionPaths: extensionPaths, ...(input.additionalSkillPaths?.length ? { additionalSkillPaths: [...input.additionalSkillPaths] } : {}), extensionFactories, ...(contextFilesOverride ? { agentsFilesOverride: contextFilesOverride } : {}), ...systemPromptOptions, ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
         await resourceLoader.reload();
     }
     const providerFailures = flushExtensionProviders(resourceLoader, modelRuntime);
@@ -249,11 +385,11 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
         // missing, so the failure travels with the complaint rather than being
         // swallowed — otherwise a misconfigured gateway reads as a typo in a model
         // name.
-        const because = providerFailures.length > 0 ? ` (provider registration failed — ${providerFailures.join("; ")})` : "";
+        const because = providerFailures.length > 0 ? ` (provider registration failed — ${providerFailures.join("; ")})` : isLlamaModel(input.model) ? " (Pi does not expose its built-in llama.cpp provider to extension sessions; declare the llama.cpp server as a provider in models.json and use that model instead)" : "";
         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) => {
@@ -278,13 +414,13 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
         await shutdown("quit").catch(() => undefined);
         throw error;
     }
-    const resourcePaths = { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => canonicalPath(resolvedPath)), skills: resourceLoader.getSkills().skills.map(({ filePath }) => canonicalPath(filePath)) };
+    const resourcePaths = { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => extensionIdentity(resolvedPath)), skills: resourceLoader.getSkills().skills.map(({ filePath }) => canonicalPath(filePath)) };
     const resourceInspection = () => {
         const extensions = resourceLoader.getExtensions();
         const skills = resourceLoader.getSkills();
         const diagnostics = [...extensions.errors.map(({ path, error }) => ({ type: "error", message: error, source: path })), ...skills.diagnostics.map(({ type, path, message }) => ({ type, message, ...(path ? { source: path } : {}) }))];
         const systemSource = systemPromptSource;
-        return { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => canonicalPath(resolvedPath)), skills: skills.skills.map(({ name }) => name), diagnostics, ...(systemSource ? { systemPromptSource: systemSource } : resourceLoader.getSystemPrompt() !== undefined ? { systemPromptSource: "Pi resource loader" } : {}) };
+        return { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => extensionIdentity(resolvedPath)), skills: skills.skills.map(({ name }) => name), diagnostics, ...(systemSource ? { systemPromptSource: systemSource } : resourceLoader.getSystemPrompt() !== undefined ? { systemPromptSource: "Pi resource loader" } : {}) };
     };
     const managedSession = Object.assign(session, {
         getLeafId: () => manager.getLeafId(),
@@ -623,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")
@@ -635,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))
@@ -662,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;
@@ -735,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) {
@@ -795,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;
@@ -821,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" } : {}) });
@@ -885,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 };
@@ -926,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: resolved.model ?? this.root.model, ...(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;
@@ -979,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) {
@@ -1009,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) {
@@ -1036,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 };
@@ -1072,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");
@@ -1113,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)
@@ -1152,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,
@@ -1160,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,
@@ -1232,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;
@@ -1274,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)) });
@@ -1285,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;
@@ -1302,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);
@@ -1320,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)
@@ -1362,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)
@@ -1432,13 +1707,14 @@ 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))
                     throw new WorkflowError("INVALID_METADATA", "Invalid child agent parameters");
@@ -1446,19 +1722,20 @@ 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 } };
+                return { content: [{ type: "text", text: JSON.stringify({ id: child.id }) }], details: { id: child.id }, structuredContent: { id: child.id } };
             },
         });
         const resultTool = defineTool({
             name: "get_subagent_result", label: "Child Result", description: "Wait for a direct child and return its result once; repeated retrieval fails with AGENT_RESULT_COLLECTED",
             parameters: Type.Object({ id: Type.String() }),
+            outputSchema: Type.Object({ id: Type.String(), ok: Type.Boolean(), value: Type.Optional(Type.Unknown()), error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String() })) }),
             execute: async (_id, params) => { const value = await this.result(parentId, params.id); if (!value.ok && value.error.code === "BUDGET_EXHAUSTED")
-                throw new WorkflowError("BUDGET_EXHAUSTED", value.error.message); return { content: [{ type: "text", text: JSON.stringify(value) }], details: value }; }
+                throw new WorkflowError("BUDGET_EXHAUSTED", value.error.message); return { content: [{ type: "text", text: JSON.stringify(value) }], details: value, structuredContent: value }; }
         });
         const steerTool = defineTool({
             name: "steer_subagent", label: "Steer Child", description: "Steer a running direct child",
@@ -1519,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() {
@@ -1548,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;
                 }
             }
@@ -1601,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) {