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

package/src/agent-execution.ts

@@ -5,7 +5,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Type } from "@earendil-works/pi-ai";
 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, type InlineExtension } from "@earendil-works/pi-coding-agent";
 import type { ExtensionContext, ModelRegistry, ToolDefinition } from "@earendil-works/pi-coding-agent";
 type HerdrModelContext = { readonly model: ExtensionContext["model"]; readonly modelRegistry: ModelRegistry | undefined };
 type AgentMessage = { role: string; content?: unknown; stopReason?: string; errorMessage?: string; usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: { total: number } } };
@@ -46,7 +46,7 @@ export interface PiResourceInspection {
   readonly systemPromptSource?: string;
 }
 import type { AgentAccounting, AgentActivity, AgentContinuity, AgentIdentity, AgentResourceInspection, AgentResourcePolicy, AgentResourceSelectors, AgentResourceSelectorSources, AgentSetup, AgentSetupSummary, AgentTransport, AgentTransportContext, ContextFileScope, JsonSchema, JsonValue, LiveSessionHandoff, ModelSpec, PiRuntimeLaunchInfo, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowRunContext, WorkflowSessionStartEvent } from "./types.js";
-import { SerialLane, assertModelThinking, byPriorityThenName, deepFreeze, errorText, jsonObject, jsonValue, mergeWorkflowExtensionSettings, object, modelAliasName, modelCapability, resolveModelReference, resourcePatternHasMagic, selectResourcesByLayers, unmatchedResourcePatterns } from "./utils.js";
+import { SerialLane, assertModelThinking, byPriorityThenName, deepFreeze, errorText, jsonObject, jsonValue, mergeWorkflowExtensionSettings, object, physicalModel, resolveModelReference, resourcePatternHasMagic, unmatchedResourcePatterns } from "./utils.js";
 import { SETTLED_AGENT_STATES, WorkflowError, isContextFileScope, zeroAccounting, type AgentDefinition, type AgentState } from "./types.js";
 import { createLiveSessionHandoff } from "./session-handoff.js";
 import { createToolTimingExtension } from "./tool-timing.js";
@@ -55,7 +55,9 @@ import { createPiRuntimeAgentRunner, isRuntimeAgentProviderError, normalizePiRun
 import type { RuntimeAgentProgress, RuntimeUsage } from "./runtime/agent-runner.js";
 import { defaultWorkflowResultSchema } from "./runtime/workflow-result.js";
 import { validateAgentOptions, validateSchema } from "./validation.js";
-import { canonicalPath } from "./paths.js";
+import { canonicalPath, extensionIdentity } from "./paths.js";
+import { isCorePackageName } from "./package-identity.js";
+import { canonicalExtensionSelector, resolveRole } from "./roles.js";
 import type { RunStore } from "./persistence.js";
 type AgentExecutionRunStore = Pick<RunStore, "recordSystemPrompt" | "validateWorktree" | "worktree" | "snapshotWorktree">;
 const localToolTimingExtension = createToolTimingExtension();
@@ -140,23 +142,22 @@ function accounting(stats: WorkflowAgentSessionStats): AgentAccounting {
   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")),
-]);
-function canonicalExtensionSelector(selector: string, base = process.cwd()): string {
-  const negated = selector.startsWith("!");
-  const body = negated ? selector.slice(1) : selector;
-  if (body === "*" || body === "**" || body.startsWith("**/")) return selector;
-  const resolved = resolve(base, body);
-  if (resourcePatternHasMagic(body)) return `${negated ? "!" : ""}${resolved}`;
-  return `${negated ? "!" : ""}${canonicalPath(resolved)}`;
+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: string): boolean {
+  const entryPath = canonicalPath(path);
+  let packageRoot = dirname(entryPath);
+  while (packageRoot !== dirname(packageRoot)) {
+    const packageMetadataPath = join(packageRoot, "package.json");
+    if (existsSync(packageMetadataPath)) {
+      try {
+        const metadata: unknown = 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: string, agentDir: string, projectTrusted: boolean): string | undefined {
@@ -191,24 +192,29 @@ function loadPiPackageDirectory(): Promise<PiPackageDirectoryResolution> {
     }
   }).catch((error: unknown) => ({ error: `could not load @earendil-works/pi-coding-agent package metadata: ${errorText(error)}` }));
 }
-let nativePromptTemplateModule: Promise<NativePromptTemplateModule> | undefined;
-async function loadNativePromptTemplateModule(): Promise<NativePromptTemplateModule> {
+const nativeCoreModules = new Map<string, Promise<unknown>>();
+/** Pi does not export these core modules, so inspection loads them from the installed package. */
+async function loadNativeCoreModule(file: string, label: string): Promise<unknown> {
   const packageDirectory = await loadPiPackageDirectory();
-  let promptTemplatePath: string | undefined;
+  let modulePath: string | undefined;
   if (packageDirectory.directory) {
-    const candidate = resolve(packageDirectory.directory, "dist/core/prompt-templates.js");
-    if (existsSync(candidate)) promptTemplatePath = candidate;
+    const candidate = resolve(packageDirectory.directory, "dist/core", file);
+    if (existsSync(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 as NativePromptTemplateModule).catch((error: unknown) => { throw new Error(`Could not load Pi prompt templates.${packageDirectoryError}`, { cause: error }); });
+  let loaded = nativeCoreModules.get(file);
+  if (!loaded) { loaded = import(modulePath).catch((error: unknown) => { throw new Error(`Could not load Pi ${label}.${packageDirectoryError}`, { cause: error }); }); nativeCoreModules.set(file, loaded); }
+  return loaded;
 }
 async function expandPromptTemplateForInspection(text: string, templates: readonly { name: string; content: string }[]): Promise<string> {
-  return (await loadNativePromptTemplateModule()).expandPromptTemplate(text, templates);
+  return (await loadNativeCoreModule("prompt-templates.js", "prompt templates") as NativePromptTemplateModule).expandPromptTemplate(text, templates);
+}
+async function buildSystemPromptForInspection(options: unknown): Promise<string> {
+  return (await loadNativeCoreModule("system-prompt.js", "system prompt builder") as { buildSystemPrompt(options: unknown): string }).buildSystemPrompt(options);
 }
 type NativePromptSession = PiSession & {
-  readonly _extensionRunner?: { hasHandlers(event: string): boolean; emitInput(text: string, images: undefined, source: "interactive"): Promise<unknown>; emitBeforeAgentStart(prompt: string, images: undefined, systemPrompt: string, options: unknown): Promise<unknown>; onError(listener: (error: unknown) => void): () => void };
-  readonly _baseSystemPrompt?: string;
+  readonly _extensionRunner?: { hasHandlers(event: string): boolean; emitInput(text: string, images: undefined, source: "interactive"): Promise<unknown>; emitBeforeAgentStart(prompt: string, images: undefined, options: unknown): Promise<unknown>; onError(listener: (error: unknown) => void): () => void };
   readonly _baseSystemPromptOptions?: unknown;
   readonly _expandSkillCommand?: (text: string) => string;
   readonly promptTemplates?: readonly { name: string; content: string }[];
@@ -217,12 +223,11 @@ async function preparePiPrompt(native: PiSession, text: string): Promise<PiPromp
   const session = native as NativePromptSession;
   const diagnostics: Array<{ type: "error"; message: string; source?: string }> = [];
   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") diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: skill expansion is missing", source: "Pi session" });
   if (!Array.isArray(templates)) diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: prompt templates are missing", source: "Pi session" });
@@ -244,9 +249,11 @@ async function preparePiPrompt(native: PiSession, text: string): Promise<PiPromp
       try { expandedPrompt = await expandPromptTemplateForInspection(skillExpanded, Array.isArray(templates) ? templates : []); }
       catch (error) { 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 prepared = result as { messages?: readonly unknown[]; systemPrompt?: unknown } | undefined;
-    return { prompt: text, expandedPrompt, systemPrompt: typeof prepared?.systemPrompt === "string" ? prepared.systemPrompt : baseSystemPrompt, systemPromptOptions: baseOptions, messages: prepared?.messages ?? [], inputHandled, diagnostics };
+    const result = !inputHandled && runner && baseOptions !== undefined ? await runner.emitBeforeAgentStart(expandedPrompt, undefined, baseOptions) : undefined;
+    const prepared = result as { messages?: readonly unknown[]; systemPromptOptions?: unknown } | undefined;
+    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?.(); }
 }
 
@@ -288,6 +295,23 @@ export function flushExtensionProviders(resourceLoader: DefaultResourceLoader, m
   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(): InlineExtension[] {
+  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: ModelSpec): boolean { return model.provider === "llama.cpp"; }
+
 async function createLocalPiSessionHandle(input: SessionInput, sessionStartEvent?: WorkflowSessionStartEvent): Promise<LocalPiSessionHandle> {
   const agentDir = input.agentDir ?? getAgentDir();
   const systemPromptSource = workflowSystemPromptPath(input.cwd, agentDir, input.resourcePolicy?.projectTrusted ?? true);
@@ -300,28 +324,33 @@ async function createLocalPiSessionHandle(input: SessionInput, sessionStartEvent
   const tools = [...new Set([...input.tools, ...customTools.map(({ name }) => name)])];
   let settingsManager: SettingsManager;
   let resourceLoader: DefaultResourceLoader;
+  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 extensionLayers = [selectorSources.global.extensions, selectorSources.project.extensions, selectorSources.role?.extensions, selectorSources.call?.extensions];
-    const extensionSelectors = extensionLayers.flatMap((layer) => (layer ?? []).map((original) => ({ original, matching: canonicalExtensionSelector(original, input.cwd) })));
-    const selectedExtensions = selectResourcesByLayers(extensionLayers.map((layer) => layer?.map((selector) => canonicalExtensionSelector(selector, input.cwd))), discoveredExtensions);
-    const extensionPaths = selectedExtensions.filter((path) => !WORKFLOW_HOST_ENTRIES.has(path));
-    const unmatchedExtensions = extensionSelectors.filter(({ matching }) => unmatchedResourcePatterns([matching], discoveredExtensions).length > 0).map(({ original }) => original);
+    const selection = resolveRole(undefined, {
+      cwd: input.cwd,
+      selectorSources,
+      resources: { extensions: discoveredExtensions },
+    });
+    const selectedExtensions = selection.selectedExtensions ?? [];
+    const extensionPaths = selectedExtensions.filter((path) => path.startsWith(BUILTIN_EXTENSION_PREFIX) || !isWorkflowHostEntry(path));
     policy.selectedExtensions = selectedExtensions;
-    policy.unmatchedExtensions = unmatchedExtensions;
+    policy.unmatchedExtensions = selection.unmatchedExtensions ?? [];
     const skillPaths = [...new Set(resolved.skills.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => path))];
     const updateSkillMatches = (skills: readonly { name: string }[]): Set<string> => {
       const names = [...new Set(skills.map(({ name }) => name))];
-      const skillLayers = [selectorSources.global.skills, selectorSources.project.skills, selectorSources.role?.skills, selectorSources.call?.skills];
-      const selectedSkills = selectResourcesByLayers(skillLayers, names);
+      const selected = resolveRole(undefined, { cwd: input.cwd, selectorSources, resources: { skills: names } });
+      const selectedSkills = selected.selectedSkills ?? [];
       policy.selectedSkills = selectedSkills;
-      policy.unmatchedSkills = unmatchedResourcePatterns(skillLayers.flatMap((layer) => layer ?? []), names);
+      policy.unmatchedSkills = selected.unmatchedSkills ?? [];
       return new Set(names.filter((name) => !selectedSkills.includes(name)));
     };
     resourceLoader = new DefaultResourceLoader({
@@ -332,7 +361,7 @@ async function createLocalPiSessionHandle(input: SessionInput, 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);
@@ -344,10 +373,10 @@ async function createLocalPiSessionHandle(input: SessionInput, sessionStartEvent
     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);
@@ -358,7 +387,7 @@ async function createLocalPiSessionHandle(input: SessionInput, 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" as const, reason: "startup" as const }), settings: input.settings ?? Object.freeze({}) };
@@ -383,13 +412,13 @@ async function createLocalPiSessionHandle(input: SessionInput, 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 = (): PiResourceInspection => {
     const extensions = resourceLoader.getExtensions();
     const skills = resourceLoader.getSkills();
     const diagnostics = [...extensions.errors.map(({ path, error }) => ({ type: "error" as const, 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(),
@@ -916,7 +945,6 @@ export class WorkflowAgentExecutor {
     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}`);
-    const candidateTools = inheritedTools !== undefined ? [...inheritedTools] : [...this.root.tools];
     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)) {
@@ -924,30 +952,30 @@ export class WorkflowAgentExecutor {
         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.`); }
       }
     }
-    const selectorLayers = [
-      this.root.resourceSelectors?.tools,
-      roleDefinition?.tools,
-      options.tools,
-    ];
-    for (const pattern of options.tools ?? []) {
-      const body = pattern.startsWith("!") ? pattern.slice(1) : pattern;
-      if (!pattern.startsWith("!") && !resourcePatternHasMagic(pattern) && !candidateTools.includes(body)) throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${body}`);
-    }
-    const outsideEffectiveTool = options.effectiveTools?.find((tool) => !candidateTools.includes(tool));
-    if (outsideEffectiveTool) throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideEffectiveTool}`);
-    const requested = options.effectiveTools ?? selectResourcesByLayers(selectorLayers, candidateTools);
-    const forbidden = requested.find((tool) => !this.root.tools.has(tool));
-    if (forbidden) throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${forbidden}`);
-    const requestedModel = options.model ?? (roleDefinition?.model && roleDefinition.thinking && !roleDefinition.model.includes(":") ? `${roleDefinition.model}:${roleDefinition.thinking}` : roleDefinition?.model);
-    const alias = requestedModel === undefined ? undefined : modelAliasName(requestedModel, this.root.modelAliases ?? {});
-    const blockedAlias = requestedModel?.split(":", 1)[0];
-    if (requestedModel !== undefined && blockedAlias && this.root.blockedAliases?.has(blockedAlias) && !alias) { const target = this.root.blockedAliasTargets?.[blockedAlias]; throw new WorkflowError("UNKNOWN_MODEL", `Unknown model alias ${requestedModel}${target ? ` resolved to ${target}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`); }
-    const model = options.modelOverride ?? parseModel(requestedModel, this.root.model, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
-    const availableModels = this.root.knownModels ?? this.root.availableModels ?? new Set([modelCapability(this.root.model)]);
-    if (!availableModels.has(modelCapability(model))) throw new WorkflowError("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
-    const overrideSystemPrompt = roleDefinition?.overrideSystemPrompt === true;
-    const contextFiles = options.contextFiles ?? roleDefinition?.contextFiles;
-    return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: requested, ...(overrideSystemPrompt ? { systemPrompt: roleDefinition.prompt ?? "" } : {}), systemPromptAppend: overrideSystemPrompt ? "" : roleDefinition?.prompt ?? "", ...(contextFiles === undefined ? {} : { contextFiles: [...contextFiles] }) };
+    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 }) };
   }
 
   async execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools: readonly ToolDefinition[] = [], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult> {
@@ -1392,6 +1420,7 @@ export class FairAgentScheduler {
     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 }),
+      outputSchema: Type.Object({ id: Type.String() }),
       execute: async (_id, params) => {
         if (!isChildAgentToolParams(params)) throw new WorkflowError("INVALID_METADATA", "Invalid child agent parameters");
         validateAgentOptions(params);
@@ -1402,13 +1431,14 @@ export class FairAgentScheduler {
         Reflect.deleteProperty(agentOptions, "prompt");
         const options: ScheduledAgentOptions = { 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 child = this.spawn(parent.runId, params.prompt, options, parentId);
-        return { content: [{ type: "text" as const, text: JSON.stringify({ id: child.id }) }], details: { id: child.id } };
+        return { content: [{ type: "text" as const, 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() }),
-      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" as const, text: JSON.stringify(value) }], details: value }; }
+      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" as const, text: JSON.stringify(value) }], details: value, structuredContent: value }; }
     });
     const steerTool = defineTool({
       name: "steer_subagent", label: "Steer Child", description: "Steer a running direct child",

package/src/background-widget.ts

@@ -49,7 +49,7 @@ const ENTRY_TYPE = "piewf-run-receipt";
  * Repaint interval. Fast enough that the spinner reads as motion rather than a
  * stutter; the underlying data is only re-read when an event says it changed.
  */
-const REPAINT_MS = 125;
+export const REPAINT_MS = 125;
 
 /**
  * Filesystem rescan interval. Shell-only activity has no event, but it does not
@@ -78,7 +78,7 @@ const MAX_ROWS = 10;
  * of thinking and far shorter than the ten minutes it takes to be declared
  * stalled.
  */
-const QUIET_MS = 3 * 60 * 1000;
+export const QUIET_MS = 3 * 60 * 1000;
 
 /** The core's own threshold for calling an agent stalled outright. */
 const STALL_MS = WORKFLOW_AGENT_STALL_THRESHOLD_MS;
@@ -144,7 +144,7 @@ const RESET = "\x1b[0m";
  * Paints text in a themed colour role. Falls back to the bare text when no
  * theme is available, so a frame rendered outside the TUI is still legible.
  */
-type Paint = (role: Parameters<Theme["fg"]>[0], text: string) => string;
+export type Paint = (role: Parameters<Theme["fg"]>[0], text: string) => string;
 
 /**
  * States that mean work is still happening, derived from the core's own lists
@@ -223,14 +223,14 @@ function spinner(now: number): string {
 }
 
 /** Status mark for a finished-or-running unit of work. */
-function mark(state: string | undefined, now: number, paint: Paint, runState?: string): string {
+export function mark(state: string | undefined, now: number, paint: Paint, runState?: string): string {
   if (state === "running" && (runState === undefined || runState === "running")) return paint(ROLE.live, spinner(now));
   if (state === "completed") return paint(ROLE.done, "✓");
   if (state === "failed" || state === "budget_exhausted") return paint(ROLE.failed, "✗");
   return paint(ROLE.quiet, "·");
 }
 
-function formatElapsed(ms: number): string {
+export function formatElapsed(ms: number): string {
   const total = Math.max(0, Math.floor(ms / 1000));
   const minutes = Math.floor(total / 60);
   const seconds = total % 60;
@@ -727,15 +727,6 @@ function renderFrame(runs: readonly Run[], now: number, width: number, offset =
   sizeOut.rows = rows.length;
   const body = collapse(rows, MAX_ROWS - 2, paint, offset, scrolling);
 
-  // Width budget: the rule takes a column and a space on each side, so the
-  // text has four fewer than the widget is given. Every piece is measured
-  // against `inner` so the right-hand rule lands in one column on every row.
-  const inner = Math.max(20, width - 4);
-
-
-  // Side rules below the lid, and no floor: the box opens downward into the
-  // editor rather than closing on itself, which is one more line kept for the
-  // run.
   // A scrollbar on the right rule, drawn only when there is more tree than
   // frame. Without it the window's position is a guess: three rows of a
   // twenty-row tree look the same near the top as near the bottom.
@@ -763,6 +754,27 @@ function renderFrame(runs: readonly Run[], now: number, width: number, offset =
     return index >= top && index < top + size ? "█" : "░";
   };
 
+  // Only advertise navigation when it can reveal hidden rows: a hint for keys
+  // that do nothing is worse than no hint.
+  const hint = !__navigationForTests.enabled || maxOffset(total, MAX_ROWS - 2) === 0
+    ? ""
+    : scrolling ? "↑/↓ to scroll · Esc to exit" : "Alt+O to scroll";
+  return drawFrame(title, hint, body, width, paint, accent, scrollbar);
+}
+
+/**
+ * The box around the live rows, shared with the subagent widget so both sit
+ * under the editor in one style.
+ */
+export function drawFrame(title: string, hint: string, body: readonly Pick<Row, "text" | "right">[], width: number, paint: Paint, accent: (text: string) => string, scrollbar: (index: number) => string | undefined = () => undefined): string[] {
+  // Width budget: the rule takes a column and a space on each side, so the
+  // text has four fewer than the widget is given. Every piece is measured
+  // against `inner` so the right-hand rule lands in one column on every row.
+  const inner = Math.max(20, width - 4);
+
+  // Side rules below the lid, and no floor: the box opens downward into the
+  // editor rather than closing on itself, which is one more line kept for the
+  // run.
   const lines = body.map((row, index) => {
     // The numbers hold the right edge; the name gives way when the two would
     // meet. A truncated workflow name is still recognisable, where a truncated
@@ -784,11 +796,6 @@ function renderFrame(runs: readonly Run[], now: number, width: number, offset =
   // rather than sitting under a separate run of dashes. In ten rows a line
   // spent on decoration is a line not spent on the run, and the box still
   // reads as closed at the top.
-  // Only advertise navigation when it can reveal hidden rows: a hint for keys
-  // that do nothing is worse than no hint.
-  const hint = !__navigationForTests.enabled || maxOffset(total, MAX_ROWS - 2) === 0
-    ? ""
-    : scrolling ? "↑/↓ to scroll · Esc to exit" : "Alt+O to scroll";
   const label = ` ${title} `;
   const tail = hint === "" ? "" : ` ${hint} `;
   const spare = inner + 2 - visibleLength(label) - visibleLength(tail);

package/src/decoders.ts

@@ -17,6 +17,7 @@ type PersistedAgent = RunRecord["agents"][number];
 type PersistedPhaseRecord = NonNullable<RunRecord["phaseHistory"]>[number];
 type PersistedShellActivity = NonNullable<RunRecord["activeShellsByPhase"]>[number];
 type PersistedDelivery = NonNullable<RunRecord["delivery"]>;
+type PersistedScriptCall = NonNullable<RunRecord["scriptCalls"]>[number];
 type PersistedIdentity = NonNullable<ScheduledAgentOptions["agentIdentity"]>;
 type PersistedOptions = ScheduledAgentOptions;
 
@@ -115,8 +116,9 @@ export function decodeWorkflowExtensions(value: unknown): WorkflowExtensionSetti
       continue;
     }
     if (namespace === "trajectory") {
+      // Snapshots persisted before the themes setting was removed still carry a boolean `themes`; it is accepted and dropped.
       if (!object(raw) || Object.keys(raw).some((key) => key !== "port" && key !== "themes") || raw.port !== undefined && (typeof raw.port !== "number" || !Number.isSafeInteger(raw.port) || raw.port < 1 || raw.port > 65535) || raw.themes !== undefined && typeof raw.themes !== "boolean") return undefined;
-      normalized.trajectory = { ...(raw.port === undefined ? {} : { port: raw.port }), ...(raw.themes === undefined ? {} : { themes: raw.themes }) };
+      normalized.trajectory = { ...(raw.port === undefined ? {} : { port: raw.port }) };
       continue;
     }
     if (!jsonValue(raw)) return undefined;
@@ -393,6 +395,22 @@ function decodeRunEvent(value: unknown): WorkflowRunEvent | undefined {
   if (timestamp === INVALID_PERSISTED_VALUE) return undefined;
   return { type: value.type, message: value.message, ...(timestamp === undefined ? {} : { timestamp }) };
 }
+function decodeScriptCall(value: unknown): PersistedScriptCall | undefined {
+  if (!object(value) || value.kind !== "shell" && value.kind !== "tool" || typeof value.name !== "string" || typeof value.path !== "string" || !finiteNumber(value.startedAt)) return undefined;
+  const shell = value.kind === "shell";
+  if (shell && !jsonValue(value.input)) return undefined;
+  const inputBytes = shell ? optionalNumber(value.inputBytes) : undefined;
+  const phase = optionalString(value.phase);
+  const finishedAt = optionalNumber(value.finishedAt);
+  let error: PersistedScriptCall["error"];
+  if (value.error !== undefined) {
+    if (shell) error = decodeWorkflowError(value.error);
+    else if (object(value.error) && typeof value.error.code === "string") error = { code: isWorkflowErrorCode(value.error.code) ? value.error.code : "INTERNAL_ERROR" };
+    if (!error) return undefined;
+  }
+  if (inputBytes === INVALID_PERSISTED_VALUE || phase === INVALID_PERSISTED_VALUE || finishedAt === INVALID_PERSISTED_VALUE) return undefined;
+  return { kind: value.kind, name: value.name, path: value.path, ...(shell && jsonValue(value.input) ? { input: value.input } : {}), ...(inputBytes === undefined ? {} : { inputBytes }), ...(phase === undefined ? {} : { phase }), startedAt: value.startedAt, ...(finishedAt === undefined ? {} : { finishedAt }), ...(error === undefined ? {} : { error }) };
+}
 function decodeDelivery(value: unknown): PersistedDelivery | undefined {
   if (!object(value)) return undefined;
   const mode = value.mode;
@@ -422,6 +440,8 @@ export function decodePersistedRun(value: unknown, allowLegacyAgentSessions = fa
   const budgetEvents = value.budgetEvents === undefined ? undefined : decodeArray(value.budgetEvents, decodeBudgetEvent);
   const events = value.events === undefined ? undefined : decodeArray(value.events, decodeRunEvent);
   const delivery = value.delivery === undefined ? undefined : decodeDelivery(value.delivery);
+  const scriptCalls = value.scriptCalls === undefined ? undefined : decodeArray(value.scriptCalls, decodeScriptCall);
+  if (value.scriptCalls !== undefined && !scriptCalls) return undefined;
   if (!agentSessions || !agents || parentRunId === INVALID_PERSISTED_VALUE || value.retry !== undefined && !retry || phase === INVALID_PERSISTED_VALUE || value.phaseHistory !== undefined && !phaseHistory || phaseHistoryIndex === INVALID_PERSISTED_VALUE || activeShells === INVALID_PERSISTED_VALUE || activeShellStartedAt === INVALID_PERSISTED_VALUE || value.activeShellsByPhase !== undefined && !activeShellsByPhase || value.error !== undefined && !error || failedAt === INVALID_PERSISTED_VALUE || value.budget !== undefined && !budget || budgetVersion === INVALID_PERSISTED_VALUE || value.budgetVersion !== undefined && !integer(budgetVersion) || value.usage !== undefined && !usage || value.budgetEvents !== undefined && !budgetEvents || value.events !== undefined && !events || value.delivery !== undefined && !delivery) return undefined;
   if (value.agentSessions === undefined && !allowLegacyAgentSessions) return undefined;
   return {
@@ -440,6 +460,7 @@ export function decodePersistedRun(value: unknown, allowLegacyAgentSessions = fa
     ...(activeShells === undefined ? {} : { activeShells }),
     ...(activeShellStartedAt === undefined ? {} : { activeShellStartedAt }),
     ...(activeShellsByPhase === undefined ? {} : { activeShellsByPhase }),
+    ...(scriptCalls === undefined ? {} : { scriptCalls }),
     ...(error === undefined ? {} : { error }),
     ...(failedAt === undefined ? {} : { failedAt }),
     ...(budget === undefined ? {} : { budget }),

package/src/execution.ts

@@ -5,9 +5,9 @@ import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { RunStore, structuralPath as operationPath } from "./persistence.js";
 import type { AgentAttempt } from "./agent-execution.js";
-import type { AgentIdentity, AgentAttemptSummary, FunctionIdentity, JsonValue, ShellIdentity, ShellOptions, ShellResult, WorkflowAgentSessionReference, WorkflowBridge, WorkflowErrorCode, WorkflowExecution } from "./types.js";
+import type { AgentIdentity, AgentAttemptSummary, FunctionIdentity, JsonValue, ShellIdentity, ShellOptions, ShellResult, ToolIdentity, WorkflowAgentSessionReference, WorkflowBridge, WorkflowErrorCode, WorkflowExecution } from "./types.js";
 import { WorkflowError, roleNameOf, sumAccounting, zeroAccounting } from "./types.js";
-import { asWorkflowError, errorText, fail, isWorkflowAuthored, isWorkflowErrorCode, jsonValue, markWorkflowAuthored, object, positiveInteger } from "./utils.js";
+import { asWorkflowError, errorText, fail, isWorkflowAuthored, isWorkflowErrorCode, jsonDigest, jsonValue, markWorkflowAuthored, object, positiveInteger } from "./utils.js";
 import { instrumentWorkflow, validateAgentOptions, validateShellCommand, validateShellOptions } from "./validation.js";
 
 export const RPC_LIMIT_BYTES = 10 * 1024 * 1024;
@@ -275,6 +275,30 @@ const functions = Object.freeze(Object.fromEntries(Object.entries(config.functio
   Object.defineProperty(result, "toJSON", { value() { throw workError("INVALID_METADATA", "Workflow function result is a Promise; await it before serialization"); } });
   return result;
 }])));
+// tools.<id>(args) runs a Pi session tool through the host. Any identifier resolves, so a resumed run
+// replays journaled calls even when the tool is gone; the host rejects identifiers it cannot call.
+// A call is the n-th call with the same arguments in its scope, so replay does not depend on the
+// order in which concurrent calls start.
+const NOT_TOOLS = new Set(["then", "toJSON", "toString", "valueOf", "constructor"]);
+const sortedJson = value => Array.isArray(value) ? value.map(sortedJson) : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, sortedJson(value[key])])) : value;
+const toolOccurrences = new Map();
+const toolCall = id => (...values) => {
+  if (worktreeOwners.getStore()) throw workError("INVALID_METADATA", "tools." + id + " is unavailable inside withWorktree: session tools resolve paths against the session working directory");
+  if (values.length > 1 || values[0] !== undefined && (!values[0] || typeof values[0] !== "object" || Array.isArray(values[0]))) throw workError("INVALID_METADATA", "tools." + id + " takes one arguments object");
+  const args = values[0] === undefined ? {} : values[0];
+  const structuralPath = inheritedAgentPath.getStore() || [];
+  const key = JSON.stringify([structuralPath, id, sortedJson(args)]);
+  const occurrence = (toolOccurrences.get(key) || 0) + 1;
+  toolOccurrences.set(key, occurrence);
+  return guardedResult(rpc("tool", [id, args, { structuralPath: [...structuralPath], occurrence }]), "tool");
+};
+const tools = new Proxy(Object.create(null), {
+  get: (_target, key) => typeof key === "string" && !NOT_TOOLS.has(key) ? toolCall(key) : undefined,
+  // Probing would branch on the session that resumed the run; the launch already checks named tools.
+  has: () => { throw workError("INVALID_METADATA", "Workflow scripts cannot probe tools with 'in'; call tools.<name>(...) directly, and the launch checks that the tool exists"); },
+  set: () => false,
+  defineProperty: () => false,
+});
 const recordEntries = (value, kind) => {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw workError("INVALID_METADATA", kind + " must be a record");
   return Object.entries(value);
@@ -335,7 +359,7 @@ const pipeline = async (operationName, items, stages) => {
   return Object.fromEntries(results.map(result => [result.name, result.value]));
 };
 const safeMath = Object.fromEntries(Object.getOwnPropertyNames(Math).filter(name => name !== "random").map(name => [name, Math[name]]));
-const sandbox = { agent, shell, withWorktree: rejectWorktree, prompt, checkpoint, parallel, pipeline, phase, log, args: config.args, Promise, JSON, Math: Object.freeze(safeMath) };
+const sandbox = { agent, shell, withWorktree: rejectWorktree, prompt, checkpoint, parallel, pipeline, phase, log, tools, args: config.args, Promise, JSON, Math: Object.freeze(safeMath) };
 for (const [name, fn] of Object.entries(functions)) Object.defineProperty(sandbox, name, { value: fn, writable: false, configurable: false });
 for (const name of ["Date","eval","Function","WebAssembly","process","require","module","exports","console","fetch","XMLHttpRequest","WebSocket","performance","crypto","setTimeout","setInterval","setImmediate","queueMicrotask","Intl","SharedArrayBuffer","Atomics"]) sandbox[name] = undefined;
 const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
@@ -384,6 +408,14 @@ function readShellIdentity(value: unknown): ShellIdentity {
   const identity = readAgentIdentity(value);
   return { structuralPath: identity.structuralPath, callSite: identity.callSite, occurrence: identity.occurrence, ...(identity.worktreeOwner ? { worktreeOwner: identity.worktreeOwner } : {}) };
 }
+function readToolIdentity(value: unknown): ToolIdentity {
+  if (!object(value) || !Array.isArray(value.structuralPath) || !value.structuralPath.every((part): part is string => typeof part === "string" && Boolean(part.trim())) || !positiveInteger(value.occurrence)) fail("INTERNAL_ERROR", "Invalid workflow tool identity");
+  return { structuralPath: [...value.structuralPath], occurrence: value.occurrence };
+}
+/** The journal path of a script tool call; the arguments' digest keeps calls with different arguments apart whatever order they start in. */
+export function toolIdentityPath(identifier: string, args: JsonValue, identity: ToolIdentity): string {
+  return operationPath("tool", ...identity.structuralPath, identifier, `args:${jsonDigest(args)}`, String(identity.occurrence));
+}
 export function agentHandleTurnPath(handle: string, turn: number): string {
   return operationPath("agent", "handle", handle, `turn:${String(turn)}`);
 }
@@ -595,6 +627,11 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
           if (!OUTCOME_ERRORS.has(typed.code)) throw typed;
           value = branded({ name, ok: false, failedAt: name, error: workerErrorShape(typed) });
         }
+      } else if (method === "tool") {
+        if (typeof values[0] !== "string" || !object(values[1])) fail("INTERNAL_ERROR", "tool requires an identifier and object arguments");
+        const identity = readToolIdentity(values[2]);
+        if (!bridge.tool) fail("UNKNOWN_TOOL", `tools.${values[0]} is unavailable: this run has no session tools`);
+        value = await bridge.tool(values[0], values[1], controller.signal, identity);
       } else if (method === "worktree") {
         if (!bridge.worktree || typeof values[0] !== "string" || !values[0]) fail("INTERNAL_ERROR", "worktree requires an active host bridge and scope");
         value = await bridge.worktree(values[0], controller.signal);
@@ -649,4 +686,4 @@ export async function persistAgentAttempts(store: RunStore, id: string, attempts
     return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: attempts.length, attemptDetails, accounting: total } : candidate), agentSessions: [...run.agentSessions.filter(({ transport, sessionId }) => !sessionKeys.has(`${transport}:${sessionId}`)), ...sessions] };
   });
 }
-export type { AgentIdentity, FunctionIdentity, ShellIdentity, WorkflowBridge, WorkflowExecution } from "./types.js";
+export type { AgentIdentity, FunctionIdentity, ShellIdentity, ToolIdentity, WorkflowBridge, WorkflowExecution } from "./types.js";