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

package/dist/src/paths.d.ts

@@ -5,6 +5,8 @@ export declare function safePart(value: string): string;
  * guessing at the identity of an object that does not exist.
  */
 export declare function canonicalPath(path: string): string;
+/** Pi names built-in extensions `builtin:<name>` instead of by a path; other extensions are files. */
+export declare function extensionIdentity(path: string): string;
 export declare function sameFilesystemPath(left: string, right: string): boolean;
 export declare function workflowProjectSettingsPath(cwd: string): string;
 export declare function projectStorageKey(cwd: string): string;

package/dist/src/paths.js

@@ -20,6 +20,8 @@ export function canonicalPath(path) {
         return absolute;
     }
 }
+/** Pi names built-in extensions `builtin:<name>` instead of by a path; other extensions are files. */
+export function extensionIdentity(path) { return path.startsWith("builtin:") ? path : canonicalPath(path); }
 export function sameFilesystemPath(left, right) { return canonicalPath(left) === canonicalPath(right); }
 export function workflowProjectSettingsPath(cwd) { return join(cwd, ".pi", "pi-extensible-workflows", "settings.json"); }
 export function projectStorageKey(cwd) {

package/dist/src/registry.js

@@ -7,7 +7,7 @@ import { loadSettings, resolveWorkflowSettings } from "./settings.js";
 import { validateSchema } from "./utils.js";
 import { canonicalPath } from "./paths.js";
 import { isCorePackageName } from "./package-identity.js";
-const RESERVED_GLOBALS = new Set(["agent", "shell", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
+const RESERVED_GLOBALS = new Set(["agent", "shell", "tools", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;

package/dist/src/roles.js

@@ -4,7 +4,7 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { registeredWorkflowRoleDirectoryRegistrations } from "./registry.js";
 import { resolveWorkflowSettings, validateContextFileScopes, validateSelectorList, validateWorkflowExtensionSettings, workflowSettingsPath } from "./settings.js";
 import { assertModelThinking, deepFreeze, object, errorText, fail, isNodeError, modelAliasName, modelCapability, resourcePatternHasMagic, resolveModelReference, selectResourcesByLayers, unmatchedResourcePatterns } from "./utils.js";
-import { canonicalPath } from "./paths.js";
+import { canonicalPath, extensionIdentity } from "./paths.js";
 const ROLE_DIRECTORY = "pi-extensible-workflows";
 // Preserve the role-file base when a discovered definition is resolved again through the public API.
 const roleDefinitionPaths = new WeakMap();
@@ -227,7 +227,8 @@ export function loadAgentDefinitions(cwd, agentDir = getAgentDir(), projectTrust
 export function canonicalExtensionSelector(selector, base = process.cwd()) {
     const negated = selector.startsWith("!");
     const body = negated ? selector.slice(1) : selector;
-    if (body === "*" || body === "**" || body.startsWith("**/"))
+    // Built-in extensions are named `builtin:<name>`, not by a path.
+    if (body === "*" || body === "**" || body.startsWith("**/") || body.startsWith("builtin:"))
         return selector;
     const resolved = resolve(base, body);
     if (resourcePatternHasMagic(body))
@@ -296,7 +297,7 @@ export function resolveRole(name, options) {
             fail("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideRootTool}`);
     }
     const selectedSkills = resources.skills === undefined ? undefined : selectResourcesByLayers(selectorLayers.skills, resources.skills);
-    const extensionResources = resources.extensions?.map((extension) => canonicalPath(extension));
+    const extensionResources = resources.extensions?.map((extension) => extensionIdentity(extension));
     const selectedExtensions = extensionResources === undefined ? undefined : selectResourcesByLayers(selectorLayers.extensions, extensionResources);
     const unmatchedSkills = resources.skills === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.skills.flatMap((layer) => layer ?? []), resources.skills);
     const unmatchedExtensions = extensionResources === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.extensions.flatMap((layer) => layer ?? []), extensionResources);

package/dist/src/script-tools.d.ts

@@ -0,0 +1,27 @@
+import type { ExtensionToolContext, ToolLoadout, ToolLoadoutChanges } from "@earendil-works/pi-coding-agent";
+import { type JsonValue } from "./types.js";
+type ScriptTool = ExtensionToolContext["tools"][number];
+type ScriptToolOutcome = Awaited<ReturnType<ExtensionToolContext["executeTool"]>>;
+/** Workflow and subagent tools stay out of scripts, so a run cannot launch or control runs. Codemode is model-only and never callable. */
+export declare function scriptToolExcluded(name: string): boolean;
+/** The identifier scripts use for a tool, the same as Pi codemode's, so its `tools.<id>(args)` lines apply to workflow scripts. */
+export declare function scriptToolIdentifier(name: string): string;
+/** The context of a Pi tool call, whose `executeTool()` runs session tools; absent for commands, session events, and headless launches. */
+export declare function scriptToolContext(ctx: unknown): ExtensionToolContext | undefined;
+export declare function scriptToolIdentifiers(context: ExtensionToolContext | undefined): string[];
+export declare function scriptTool(context: ExtensionToolContext, identifier: string): ScriptTool | undefined;
+/**
+ * What a script call resolves to, as in codemode: the structured content of a tool with an output
+ * schema, also for error results that carry one, otherwise its text; other failures throw. The value
+ * is normalized through JSON and size-checked before it is journaled, so a replay returns the same value.
+ */
+export declare function scriptToolValue(tool: ScriptTool, outcome: ScriptToolOutcome): JsonValue;
+/** Fails a launch whose script names a tool this session cannot call, before any agent runs. */
+export declare function validateScriptToolReferences(script: string, context: ExtensionToolContext | undefined): void;
+/**
+ * Tells the model what `tools.<id>(args)` resolves to for declared tools with an output schema; the
+ * workflow description says that the others resolve to their text. With codemode active its own
+ * identical `Codemode:` lines say this, and pi keeps only one description per tool, so this defers.
+ */
+export declare function prepareScriptToolLoadout(loadout: ToolLoadout): ToolLoadoutChanges | undefined;
+export {};

package/dist/src/script-tools.js

@@ -0,0 +1,87 @@
+import { WorkflowError } from "./types.js";
+import { errorText, jsonValue, object } from "./utils.js";
+import { RPC_LIMIT_BYTES } from "./execution.js";
+import { scriptToolReferences } from "./validation.js";
+/** Workflow and subagent tools stay out of scripts, so a run cannot launch or control runs. Codemode is model-only and never callable. */
+export function scriptToolExcluded(name) {
+    return name === "workflow" || name.startsWith("workflow_") || name.startsWith("subagents_");
+}
+/** The identifier scripts use for a tool, the same as Pi codemode's, so its `tools.<id>(args)` lines apply to workflow scripts. */
+export function scriptToolIdentifier(name) {
+    let identifier = "";
+    for (const char of name)
+        identifier += (identifier === "" ? /^[A-Za-z_$]$/ : /^[A-Za-z0-9_$]$/).test(char) ? char : "_";
+    return identifier || "_";
+}
+/** The context of a Pi tool call, whose `executeTool()` runs session tools; absent for commands, session events, and headless launches. */
+export function scriptToolContext(ctx) {
+    return object(ctx) && typeof ctx.executeTool === "function" && Array.isArray(ctx.tools) ? ctx : undefined;
+}
+export function scriptToolIdentifiers(context) {
+    return (context?.tools ?? []).filter(({ name }) => !scriptToolExcluded(name)).map(({ name }) => scriptToolIdentifier(name));
+}
+// NOTE: a launch rejects identifiers that several tools share; a later tool set may still collide, and the first match wins.
+export function scriptTool(context, identifier) {
+    return context.tools.find(({ name }) => !scriptToolExcluded(name) && scriptToolIdentifier(name) === identifier);
+}
+/**
+ * What a script call resolves to, as in codemode: the structured content of a tool with an output
+ * schema, also for error results that carry one, otherwise its text; other failures throw. The value
+ * is normalized through JSON and size-checked before it is journaled, so a replay returns the same value.
+ */
+export function scriptToolValue(tool, outcome) {
+    const structured = tool.outputSchema === undefined ? undefined : outcome.result.structuredContent;
+    const text = outcome.result.content.flatMap((item) => item.type === "text" ? [item.text] : []).join("\n");
+    if (structured === undefined && outcome.isError)
+        throw new WorkflowError("TOOL_FAILED", `${tool.name}: ${text || "failed"}`);
+    let value;
+    try {
+        value = JSON.parse(JSON.stringify(structured ?? text));
+    }
+    catch (error) {
+        throw new WorkflowError("TOOL_FAILED", `${tool.name} returned a result that is not JSON: ${errorText(error)}`);
+    }
+    if (!jsonValue(value))
+        throw new WorkflowError("TOOL_FAILED", `${tool.name} returned a result that is not JSON`);
+    if (Buffer.byteLength(JSON.stringify(value)) > RPC_LIMIT_BYTES)
+        throw new WorkflowError("TOOL_FAILED", `${tool.name} returned more than the 10 MB workflow RPC limit`);
+    return value;
+}
+/** Fails a launch whose script names a tool this session cannot call, before any agent runs. */
+export function validateScriptToolReferences(script, context) {
+    const references = scriptToolReferences(script);
+    if (!references?.length)
+        return;
+    if (!context)
+        throw new WorkflowError("UNKNOWN_TOOL", `Workflow scripts can call session tools only when launched by the workflow tool; this launch has none for ${references.map((name) => `tools.${name}`).join(", ")}`);
+    const identifiers = scriptToolIdentifiers(context);
+    const unknown = references.filter((name) => !identifiers.includes(name));
+    if (unknown.length)
+        throw new WorkflowError("UNKNOWN_TOOL", `Workflow script calls tools this session cannot call: ${unknown.map((name) => `tools.${name}`).join(", ")}`);
+    const ambiguous = references.filter((name) => identifiers.indexOf(name) !== identifiers.lastIndexOf(name));
+    if (ambiguous.length)
+        throw new WorkflowError("UNKNOWN_TOOL", `Workflow script calls tools whose names collide after normalization: ${ambiguous.map((name) => `tools.${name}`).join(", ")}`);
+}
+function describeScriptOutput(schema) {
+    if (!object(schema) || schema.type !== "object" || !object(schema.properties))
+        return schema === undefined ? undefined : "a JSON value";
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    return `\`{ ${Object.keys(schema.properties).map((name) => required.has(name) ? name : `${name}?`).join(", ")} }\``;
+}
+/**
+ * Tells the model what `tools.<id>(args)` resolves to for declared tools with an output schema; the
+ * workflow description says that the others resolve to their text. With codemode active its own
+ * identical `Codemode:` lines say this, and pi keeps only one description per tool, so this defers.
+ */
+export function prepareScriptToolLoadout(loadout) {
+    if (loadout.declared.some(({ name }) => name === "codemode"))
+        return undefined;
+    const callable = new Set(loadout.callable.map(({ name }) => name));
+    const descriptions = {};
+    for (const tool of loadout.declared) {
+        const output = callable.has(tool.name) && !scriptToolExcluded(tool.name) ? describeScriptOutput(tool.outputSchema) : undefined;
+        if (output)
+            descriptions[tool.name] = `${tool.description.trim()}\n\nWorkflow scripts: \`tools.${scriptToolIdentifier(tool.name)}(args)\` resolves to ${output}.`;
+    }
+    return { descriptions };
+}

package/dist/src/settings.d.ts

@@ -1,3 +1,4 @@
+import { type ToolAnnotations } from "@earendil-works/pi-coding-agent";
 import type { AgentResourcePolicy, ContextFileScope, WorkflowExtensionSettings, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution } from "./types.js";
 export { workflowProjectSettingsPath } from "./paths.js";
 export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
@@ -6,6 +7,18 @@ export declare function validateSelectorList(value: unknown, path: string, kind:
 export declare function validateContextFileScopes(value: unknown, rolePath: string): readonly ContextFileScope[] | undefined;
 export declare function validateWorkflowExtensionSettings(value: unknown, settingsPath: string, errorCode?: "INVALID_SETTINGS" | "INVALID_METADATA"): WorkflowExtensionSettings | undefined;
 export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
+/**
+ * Exposure and annotations of a workflow or subagent tool. Under the global `codemodeTools` setting,
+ * `model-only` keeps the model's direct access and stops codemode scripts from calling the tool.
+ * Tools are registered once at load, so the setting is global and applies after a reload.
+ * Read-only tools carry `readOnlyHint` so permission extensions need not confirm them.
+ */
+export declare function workflowToolExposure(name: string, codemodeTools: WorkflowSettings["codemodeTools"]): {
+    exposure?: "model-only";
+    annotations?: ToolAnnotations;
+};
+/** The `codemodeTools` setting at load time. Invalid settings keep the default; launches report them. */
+export declare function loadCodemodeToolsSetting(agentDir?: string): WorkflowSettings["codemodeTools"];
 export declare function loadSettingsOverrides(path: string): Readonly<WorkflowSettingsOverrides>;
 export declare function resolveWorkflowSettings(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): WorkflowSettingsResolution;
 export declare function validateModelAliasAvailability(aliases: Readonly<Record<string, string>>, names: readonly string[], availableModels: ReadonlySet<string>, knownModels: ReadonlySet<string>, settingsPath?: string): void;

package/dist/src/settings.js

@@ -12,7 +12,8 @@ const ROLE_DIRECTORY = "pi-extensible-workflows";
 export const DEFAULT_SETTINGS = Object.freeze({ concurrency: 8, backgroundWidget: true });
 export function workflowSettingsPath(agentDir = getAgentDir()) { return join(agentDir, ROLE_DIRECTORY, "settings.json"); }
 function normalizedResourcePath(value, settingsPath) {
-    if (value === "*")
+    // Built-in extensions are named `builtin:<name>`, not by a path.
+    if (value === "*" || value.startsWith("builtin:"))
         return value;
     let expanded = value === "~" ? homedir() : value.startsWith("~/") || value.startsWith("~\\") ? join(homedir(), value.slice(2)) : value;
     if (expanded.startsWith("file://"))
@@ -152,7 +153,7 @@ function parseSettings(path, partial) {
     }
     if (!object(parsed))
         fail("INVALID_SETTINGS", `Workflow settings at ${path} must be an object`);
-    const allowed = new Set(["concurrency", "modelAliases", "skills", "extensions", "extensionSettings", "tools", "retention", "worktreePostCreateCommand", ...(partial ? [] : ["backgroundWidget"])]);
+    const allowed = new Set(["concurrency", "modelAliases", "skills", "extensions", "extensionSettings", "tools", "retention", "worktreePostCreateCommand", ...(partial ? [] : ["backgroundWidget", "codemodeTools"])]);
     const unknown = Object.keys(parsed).find((key) => !allowed.has(key));
     if (Object.prototype.hasOwnProperty.call(parsed, "disabledAgentResources"))
         fail("INVALID_SETTINGS", `disabledAgentResources is no longer supported; use skills, extensions, and tools selectors (settings: ${path})`);
@@ -164,6 +165,9 @@ function parseSettings(path, partial) {
     const backgroundWidget = parsed.backgroundWidget === undefined ? (partial ? undefined : DEFAULT_SETTINGS.backgroundWidget) : parsed.backgroundWidget;
     if (backgroundWidget !== undefined && typeof backgroundWidget !== "boolean")
         fail("INVALID_SETTINGS", `${path}.backgroundWidget must be a boolean`);
+    const codemodeTools = parsed.codemodeTools;
+    if (codemodeTools !== undefined && codemodeTools !== "all" && codemodeTools !== "read-only" && codemodeTools !== "none")
+        fail("INVALID_SETTINGS", `${path}.codemodeTools must be "all", "read-only", or "none"`);
     const modelAliases = parsed.modelAliases === undefined ? undefined : validateModelAliases(parsed.modelAliases, path);
     const skills = validateSelectorList(parsed.skills, path, "skills");
     const tools = validateSelectorList(parsed.tools, path, "tools");
@@ -172,13 +176,33 @@ function parseSettings(path, partial) {
     const retention = validateRetention(parsed.retention, path);
     const worktreePostCreateCommand = validateWorktreePostCreateCommand(parsed.worktreePostCreateCommand, path);
     return Object.freeze({
-        ...(concurrency === undefined ? {} : { concurrency }), ...(backgroundWidget === undefined ? {} : { backgroundWidget }), ...(modelAliases === undefined ? {} : { modelAliases }),
+        ...(concurrency === undefined ? {} : { concurrency }), ...(backgroundWidget === undefined ? {} : { backgroundWidget }), ...(codemodeTools === undefined ? {} : { codemodeTools }), ...(modelAliases === undefined ? {} : { modelAliases }),
         ...(skills === undefined ? {} : { skills }), ...(extensions === undefined ? {} : { extensions }),
         ...(extensionSettings === undefined ? {} : { extensionSettings }), ...(tools === undefined ? {} : { tools }), ...(retention === undefined ? {} : { retention }),
         ...(worktreePostCreateCommand === undefined ? {} : { worktreePostCreateCommand }),
     });
 }
 export function loadSettings(path = workflowSettingsPath()) { return parseSettings(path, false); }
+const READ_ONLY_WORKFLOW_TOOLS = new Set(["workflow_status", "workflow_catalog", "subagents_inspect"]);
+/**
+ * Exposure and annotations of a workflow or subagent tool. Under the global `codemodeTools` setting,
+ * `model-only` keeps the model's direct access and stops codemode scripts from calling the tool.
+ * Tools are registered once at load, so the setting is global and applies after a reload.
+ * Read-only tools carry `readOnlyHint` so permission extensions need not confirm them.
+ */
+export function workflowToolExposure(name, codemodeTools) {
+    const readOnly = READ_ONLY_WORKFLOW_TOOLS.has(name);
+    return { ...(codemodeTools === "none" || (codemodeTools === "read-only" && !readOnly) ? { exposure: "model-only" } : {}), ...(readOnly ? { annotations: { readOnlyHint: true } } : {}) };
+}
+/** The `codemodeTools` setting at load time. Invalid settings keep the default; launches report them. */
+export function loadCodemodeToolsSetting(agentDir) {
+    try {
+        return loadSettings(workflowSettingsPath(agentDir)).codemodeTools;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function loadSettingsOverrides(path) { return parseSettings(path, true); }
 export function resolveWorkflowSettings(cwd, projectTrusted, globalSettingsPath = workflowSettingsPath()) {
     const projectSettingsPath = workflowProjectSettingsPath(cwd);

package/dist/src/trajectory.d.ts

@@ -1,5 +1,5 @@
 import { type AwaitingCheckpoint, type CompletedOperation, type EffectiveSystemPrompt, type PersistedRun } from "./persistence.js";
-import type { AgentAttemptSummary, AgentRecord, JsonValue, LaunchSnapshot, WorkflowAgentSessionReference } from "./types.js";
+import type { AgentAttemptSummary, AgentRecord, JsonValue, LaunchSnapshot, WorkflowAgentSessionReference, WorkflowErrorCode, WorkflowScriptCall } from "./types.js";
 import { type SubagentProgress, type SubagentRunRequest, type SubagentStatus } from "../subagents/src/contracts.js";
 import type { TrajectoryAction, TrajectoryTarget } from "./trajectory-contracts.js";
 export declare const TRAJECTORY_MAX_TRANSCRIPT_BYTES: number;
@@ -24,8 +24,17 @@ export type TrajectoryAgentOutput = {
 export type TrajectoryAgent = AgentRecord & {
     readonly output: TrajectoryAgentOutput;
 };
-export type TrajectoryRunRecord = Omit<PersistedRun, "agents"> & {
+export type TrajectoryScriptCall = WorkflowScriptCall & {
+    readonly output: TrajectoryAgentOutput | {
+        readonly status: "completed";
+    } | {
+        readonly status: "failed" | "cancelled";
+        readonly code: WorkflowErrorCode;
+    };
+};
+export type TrajectoryRunRecord = Omit<PersistedRun, "agents" | "scriptCalls"> & {
     readonly agents: readonly TrajectoryAgent[];
+    readonly scriptCalls?: readonly TrajectoryScriptCall[];
 };
 export type TrajectoryRun = {
     run: TrajectoryRunRecord;
@@ -135,6 +144,7 @@ export type TrajectoryPublisherInput = {
     loadTranscript?: TrajectoryTranscriptLoader;
     handleAction: TrajectoryActionHandler;
 };
+export declare function isTimingTranscriptEntry(value: unknown): boolean;
 export declare function applySystemPrompts(run: PersistedRun, prompts: readonly EffectiveSystemPrompt[]): PersistedRun;
 export declare function applyToolDescriptions(run: PersistedRun, catalog: ReadonlyMap<string, string>): PersistedRun;
 export declare function withPiToolDescriptions(run: PersistedRun): PersistedRun;

package/dist/src/trajectory.js

@@ -9,6 +9,7 @@ import { normalizeSubagentRunRequest } from "../subagents/src/contracts.js";
 import { statusValue, subagentErrorValue } from "../subagents/src/decode.js";
 import { isNodeError, jsonValue, object, resourcePatternHasMagic, selectResourcesByLayers } from "./utils.js";
 import { canonicalPath, sameFilesystemPath } from "./paths.js";
+import { TOOL_TIMING_ENTRY_TYPE } from "./tool-timing.js";
 export const TRAJECTORY_MAX_TRANSCRIPT_BYTES = 2 * 1024 * 1024;
 const TRAJECTORY_MAX_NON_TIMING_ENTRIES = 400;
 function subagentOutput(options) {
@@ -50,7 +51,7 @@ function transcriptToolCallId(value) {
             return part.id;
     return undefined;
 }
-function isTimingTranscriptEntry(value) { return object(value) && value.type === "custom" && value.customType === "pi-workflows:tool-timing"; }
+export function isTimingTranscriptEntry(value) { return object(value) && value.type === "custom" && value.customType === TOOL_TIMING_ENTRY_TYPE; }
 function timingToolCallId(value) {
     if (!object(value) || !isTimingTranscriptEntry(value) || !object(value.data))
         return undefined;
@@ -194,7 +195,8 @@ export function withPiToolDescriptionsForTools(tools, cwd) {
 function canonicalExtensionSelector(selector, base) {
     const negated = selector.startsWith("!");
     const body = negated ? selector.slice(1) : selector;
-    if (body === "*" || body === "**" || body.startsWith("**/"))
+    // Built-in extensions are named `builtin:<name>`, not by a path.
+    if (body === "*" || body === "**" || body.startsWith("**/") || body.startsWith("builtin:"))
         return selector;
     const resolved = resolve(base, body);
     if (resourcePatternHasMagic(body))
@@ -280,11 +282,20 @@ function failedAgentOutput(agent) {
     const status = agent.state === "cancelled" ? "cancelled" : "failed";
     return { status, code: error?.code ?? (status === "cancelled" ? "CANCELLED" : "AGENT_FAILED"), message: error?.message ?? `Agent ${agent.state}` };
 }
+function operationOutput(operation) {
+    const bytes = serializedJsonBytes(operation.value);
+    return bytes > DEFAULT_MAX_BYTES ? { status: "truncated", kind: "result", bytes } : { status: "available", value: operation.value, bytes };
+}
+function outputForCall(call, operation) {
+    if (operation !== undefined)
+        return call.kind === "tool" ? { status: "completed" } : operationOutput(operation);
+    if (call.error)
+        return { status: call.error.code === "CANCELLED" ? "cancelled" : "failed", code: call.error.code, ...(call.kind === "shell" ? { message: call.error.message ?? "Shell failed" } : {}) };
+    return call.finishedAt === undefined ? { status: "pending" } : { status: "unavailable" };
+}
 function outputForAgent(agent, operation) {
-    if (operation !== undefined) {
-        const bytes = serializedJsonBytes(operation.value);
-        return bytes > DEFAULT_MAX_BYTES ? { status: "truncated", kind: "result", bytes } : { status: "available", value: operation.value, bytes };
-    }
+    if (operation !== undefined)
+        return operationOutput(operation);
     if (agent.state === "failed" || agent.state === "cancelled")
         return failedAgentOutput(agent);
     if (agent.state === "completed")
@@ -294,7 +305,18 @@ function outputForAgent(agent, operation) {
 export function applyTrajectoryAgentOutputs(run, operations) {
     const byPath = new Map(operations.map((operation) => [operation.path, operation]));
     const agents = run.agents.map((agent) => ({ ...agent, output: outputForAgent(agent, agent.resultPath === undefined ? undefined : byPath.get(agent.resultPath)) }));
-    return { ...run, agents };
+    const scriptCalls = run.scriptCalls?.map((call) => {
+        const recorded = { ...call, output: outputForCall(call, byPath.get(call.path)) };
+        if (call.kind === "tool") {
+            delete recorded.input;
+            delete recorded.inputBytes;
+            if (call.error)
+                recorded.error = { code: call.error.code };
+        }
+        return recorded;
+    });
+    const rest = run;
+    return { ...rest, agents, ...(scriptCalls === undefined ? {} : { scriptCalls }) };
 }
 function overlayTrajectoryRun(run, overlay) {
     const overlaid = overlay(run);
@@ -304,7 +326,7 @@ function overlayTrajectoryRun(run, overlay) {
         const output = previous?.status === "available" || previous?.status === "truncated" ? previous : outputForAgent(agent, undefined);
         return { ...agent, output };
     });
-    return { ...overlaid, agents };
+    return { ...overlaid, agents, ...(run.scriptCalls === undefined ? {} : { scriptCalls: run.scriptCalls }) };
 }
 async function loadTrajectoryRun(store, includeTranscripts = true) {
     const value = await store.load();

package/dist/src/types.d.ts

@@ -23,7 +23,7 @@ export declare const WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT = "workflow:checkpo
 export declare const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
 export declare const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
 export declare const WORKFLOW_BLOCKED_EVENT = "workflow:blocked";
-export declare const ERROR_CODES: readonly ["CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE", "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR"];
+export declare const ERROR_CODES: readonly ["CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE", "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID", "TOOL_FAILED", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR"];
 export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
@@ -215,9 +215,11 @@ export interface WorkflowRetentionSettings {
     olderThanDays?: number;
     maxTerminalRuns?: number;
 }
+export type CodemodeToolsSetting = "all" | "read-only" | "none";
 export interface WorkflowSettings {
     concurrency: number;
     backgroundWidget?: boolean;
+    codemodeTools?: CodemodeToolsSetting;
     modelAliases?: Readonly<Record<string, string>>;
     skills?: readonly string[];
     extensions?: readonly string[];
@@ -226,7 +228,7 @@ export interface WorkflowSettings {
     retention?: Readonly<WorkflowRetentionSettings>;
     worktreePostCreateCommand?: readonly string[];
 }
-export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget">>;
+export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget" | "codemodeTools">>;
 export interface WorkflowSettingsSources {
     concurrency: string;
     modelAliases: string;
@@ -403,6 +405,21 @@ export interface WorkflowPhaseShellActivity {
     active: number;
     startedAt: number;
 }
+/** A script call recorded for inspection. Tool payloads stay in the replay journal, not this record. Oversized shell inputs are JSON prefixes, with `inputBytes` their full size. */
+export interface WorkflowScriptCall {
+    kind: "shell" | "tool";
+    name: string;
+    path: string;
+    input?: JsonValue;
+    inputBytes?: number;
+    phase?: string;
+    startedAt: number;
+    finishedAt?: number;
+    error?: {
+        code: WorkflowErrorCode;
+        message?: string;
+    };
+}
 export interface RunRecord {
     id: string;
     workflowName: string;
@@ -419,6 +436,11 @@ export interface RunRecord {
     activeShells?: number;
     activeShellStartedAt?: number;
     activeShellsByPhase?: readonly WorkflowPhaseShellActivity[];
+    activeTools?: readonly {
+        name: string;
+        startedAt: number;
+    }[];
+    scriptCalls?: readonly WorkflowScriptCall[];
     error?: WorkflowErrorShape;
     failedAt?: string;
     budget?: WorkflowBudget;
@@ -835,6 +857,11 @@ export interface ShellIdentity {
     occurrence: number;
     worktreeOwner?: string;
 }
+/** A script `tools.<id>(args)` call: the n-th call of that tool within one structural scope. */
+export interface ToolIdentity {
+    structuralPath: readonly string[];
+    occurrence: number;
+}
 export interface WorkflowBridge {
     agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
     shell?: (command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>;
@@ -846,6 +873,7 @@ export interface WorkflowBridge {
     }>>;
     phase?: (name: string) => void | Promise<void>;
     log?: (message: string) => void | Promise<void>;
+    tool?: (identifier: string, args: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: ToolIdentity) => Promise<JsonValue>;
 }
 export interface WorkflowExecution {
     result: Promise<JsonValue>;

package/dist/src/types.js

@@ -19,7 +19,7 @@ export const WORKFLOW_BLOCKED_EVENT = "workflow:blocked";
 export const ERROR_CODES = [
     "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE",
     "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID",
-    "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
+    "TOOL_FAILED", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
 ];
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export function roleNameOf(value) {

package/dist/src/utils.d.ts

@@ -6,6 +6,8 @@ export declare class SerialLane {
 export declare function object(value: unknown): value is Record<string, unknown>;
 export declare function sanitizeDisplayText(value: string): string;
 export { object as isObject };
+/** A short digest of a JSON value that ignores object key order. */
+export declare function jsonDigest(value: JsonValue): string;
 export declare function jsonValue(value: unknown, seen?: Set<object>): value is JsonValue;
 export declare function jsonObject(value: unknown): value is Record<string, JsonValue>;
 export declare function mergeWorkflowExtensionSettings(...layers: readonly (Readonly<WorkflowExtensionSettings> | undefined)[]): Readonly<WorkflowExtensionSettings> | undefined;
@@ -44,6 +46,23 @@ export declare function modelAliasName(value: string, aliases: Readonly<Record<s
 export declare function validateModelAliases(value: unknown, settingsPath?: string): Readonly<Record<string, string>>;
 export declare function unknownModel(value: string, target: string | undefined, settingsPath?: string): never;
 export declare function resolveModelReference(value: string, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
+type ToolSource = {
+    getActiveTools(): string[];
+    getAllTools?(): readonly {
+        name: string;
+        exposure?: string;
+    }[];
+};
+/**
+ * Tools a session can reach, and so the ceiling for its agents: the declared tools plus the ones
+ * only codemode scripts call or tool_search loads, such as MCP tools with the default exposure.
+ * Agent sessions allow tools by name, so leaving these out would make them unreachable there.
+ */
+export declare function reachableTools(pi: ToolSource): string[];
+/** Provider of the virtual models that expose workflow model aliases in `/model`. */
+export declare const VIRTUAL_MODEL_PROVIDER = "workflow";
+/** Child sessions do not load the workflow extension, so they receive the alias target instead of its virtual model. */
+export declare function physicalModel(spec: ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
 export declare function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string;
 export declare function aliasDrift(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>): string[];
 export declare function validateResourcePattern(pattern: string): void;

package/dist/src/utils.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WorkflowError } from "./types.js";
 import { Minimatch } from "minimatch";
 export class SerialLane {
@@ -17,6 +18,17 @@ export function sanitizeDisplayText(value) { return value.replace(ANSI_ESCAPE_SE
 export { object as isObject };
 function isStringKey(key) { return typeof key === "string"; }
 function stringKeyValue(value, key) { return object(value) ? value[key] : undefined; }
+function sortedJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortedJson);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortedJson(value[key])]));
+}
+/** A short digest of a JSON value that ignores object key order. */
+export function jsonDigest(value) {
+    return createHash("sha256").update(JSON.stringify(sortedJson(value))).digest("hex").slice(0, 16);
+}
 export function jsonValue(value, seen = new Set()) {
     if (value === null || typeof value === "boolean" || typeof value === "string")
         return true;
@@ -178,6 +190,24 @@ export function resolveModelReference(value, aliases = {}, knownModels, settings
     };
     return resolveReference(value, []);
 }
+/**
+ * Tools a session can reach, and so the ceiling for its agents: the declared tools plus the ones
+ * only codemode scripts call or tool_search loads, such as MCP tools with the default exposure.
+ * Agent sessions allow tools by name, so leaving these out would make them unreachable there.
+ */
+export function reachableTools(pi) {
+    const undeclared = pi.getAllTools?.().filter(({ exposure }) => exposure === "codemode" || exposure === "deferred").map(({ name }) => name) ?? [];
+    return [...new Set([...pi.getActiveTools(), ...undeclared])];
+}
+/** Provider of the virtual models that expose workflow model aliases in `/model`. */
+export const VIRTUAL_MODEL_PROVIDER = "workflow";
+/** Child sessions do not load the workflow extension, so they receive the alias target instead of its virtual model. */
+export function physicalModel(spec, aliases = {}, knownModels, settingsPath) {
+    if (spec.provider !== VIRTUAL_MODEL_PROVIDER || !modelAliasName(spec.model, aliases))
+        return spec;
+    const target = resolveModelReference(spec.model, aliases, knownModels, settingsPath);
+    return spec.thinking === undefined ? target : { ...target, thinking: spec.thinking };
+}
 export function modelCapability(value, aliases, knownModels, settingsPath) {
     const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
     return `${parsed.provider}/${parsed.model}`;

package/dist/src/validation.d.ts

@@ -3,8 +3,13 @@ import type { WorkflowRegistryApi } from "./registry.js";
 export { validateSchema } from "./utils.js";
 export { loadAgentDefinitions, loadProjectAgentDefinitions, parseRoleMarkdown, workflowRoleDirectories } from "./roles.js";
 export type { WorkflowRoleDirectoryInput } from "./roles.js";
-export { DEFAULT_SETTINGS, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath } from "./settings.js";
+export { DEFAULT_SETTINGS, loadCodemodeToolsSetting, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./settings.js";
 export declare function validateCheckpoint(value: unknown): CheckpointInput;
+/**
+ * The `tools.<id>` members a workflow script names statically. Any other use of `tools`, such as a
+ * local declaration that shadows the global or passing it around, makes the set unknowable: undefined.
+ */
+export declare function scriptToolReferences(script: string): string[] | undefined;
 export declare function instrumentWorkflow(script: string): string;
 export declare function workflowPrompt(template: string, values: Readonly<Record<string, JsonValue>>): string;
 export declare function validateAgentOptions(value: unknown): Readonly<Record<string, JsonValue>>;

package/dist/src/validation.js

@@ -8,7 +8,7 @@ export { validateSchema } from "./utils.js";
 import { loadAgentDefinitions, loadProjectAgentDefinitions } from "./roles.js";
 export { loadAgentDefinitions, loadProjectAgentDefinitions, parseRoleMarkdown, workflowRoleDirectories } from "./roles.js";
 import { validateContextFileScopes, validateSelectorList } from "./settings.js";
-export { DEFAULT_SETTINGS, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath } from "./settings.js";
+export { DEFAULT_SETTINGS, loadCodemodeToolsSetting, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./settings.js";
 export function validateCheckpoint(value) {
     if (!object(value) || Object.keys(value).some((key) => !["name", "prompt", "context"].includes(key)) || typeof value.name !== "string" || value.name.trim() === "" || typeof value.prompt !== "string" || !jsonValue(value.context))
         fail("INVALID_METADATA", "checkpoint requires only name, prompt, and JSON context");
@@ -244,6 +244,26 @@ function callHasTrailingComma(source, call) {
     }
     return current?.type.label === ")" && previous?.type.label === ",";
 }
+/**
+ * The `tools.<id>` members a workflow script names statically. Any other use of `tools`, such as a
+ * local declaration that shadows the global or passing it around, makes the set unknowable: undefined.
+ */
+export function scriptToolReferences(script) {
+    const body = workflowBody(script);
+    if (!body.trim())
+        return [];
+    const names = new Set();
+    const opaque = (node, parent) => {
+        if (node.type === "Identifier" && node.name === "tools") {
+            if (parent?.type === "MemberExpression" && parent.object === node && !parent.computed && parent.property.type === "Identifier")
+                names.add(parent.property.name);
+            else if (!(parent?.type === "Property" && parent.key === node && !parent.computed && !parent.shorthand || parent?.type === "MemberExpression" && parent.property === node && !parent.computed))
+                return true;
+        }
+        return astChildren(node).some((child) => opaque(child, node));
+    };
+    return opaque(parseWorkflow(body)) ? undefined : [...names];
+}
 export function instrumentWorkflow(script) {
     const body = workflowBody(script);
     if (!body.trim())

package/dist/starter/index.js

@@ -65,8 +65,6 @@ var reviewLoop = defineWorkflowFunction({
     { additionalProperties: false }
   )
 });
-var reviewLoopInputSchema = reviewLoop.input;
-var reviewLoopOutputSchema = reviewLoop.output;
 
 // starter/index.ts
 var extension = {