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

package/src/settings.ts

@@ -3,7 +3,7 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, type ToolAnnotations } from "@earendil-works/pi-coding-agent";
 import type { AgentResourcePolicy, AgentResourceSelectors, AgentResourceSelectorSet, ContextFileScope, JsonValue, WorkflowExtensionSettings, WorkflowRetentionSettings, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution, WorkflowSettingsSources } from "./types.js";
 import { isContextFileScope } from "./types.js";
 import { annotateModelAliasError, deepFreeze, errorText, fail, isNodeError, jsonValue, modelCapability, object, positiveInteger, resourcePatternHasMagic, unknownModel, validateModelAliases, validateResourcePattern, validWorkflowExtensionNamespace } from "./utils.js";
@@ -14,7 +14,8 @@ const ROLE_DIRECTORY = "pi-extensible-workflows";
 export const DEFAULT_SETTINGS: Readonly<WorkflowSettings> = Object.freeze({ concurrency: 8, backgroundWidget: true });
 export function workflowSettingsPath(agentDir = getAgentDir()): string { return join(agentDir, ROLE_DIRECTORY, "settings.json"); }
 function normalizedResourcePath(value: string, settingsPath: string): string {
-  if (value === "*") return 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://")) expanded = fileURLToPath(expanded);
   const resolved = resolve(dirname(settingsPath), expanded);
@@ -115,7 +116,7 @@ function parseSettings(path: string, partial: boolean): Readonly<WorkflowSetting
     fail("CONFIG_ERROR", `Invalid workflow settings JSON at ${path}: ${errorText(error)}`);
   }
   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})`);
   if (unknown) fail("INVALID_SETTINGS", `Unknown workflow setting at ${path}: ${unknown}`);
@@ -123,6 +124,8 @@ function parseSettings(path: string, partial: boolean): Readonly<WorkflowSetting
   if (concurrency !== undefined && (!positiveInteger(concurrency) || concurrency > 16)) fail("INVALID_SETTINGS", `${path}.concurrency must be an integer from 1 to 16`);
   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");
@@ -131,13 +134,28 @@ function parseSettings(path: string, partial: boolean): Readonly<WorkflowSetting
   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()): Readonly<WorkflowSettings> { return parseSettings(path, false); }
+const READ_ONLY_WORKFLOW_TOOLS: ReadonlySet<string> = 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: string, codemodeTools: WorkflowSettings["codemodeTools"]): { exposure?: "model-only"; annotations?: ToolAnnotations } {
+  const readOnly = READ_ONLY_WORKFLOW_TOOLS.has(name);
+  return { ...(codemodeTools === "none" || (codemodeTools === "read-only" && !readOnly) ? { exposure: "model-only" as const } : {}), ...(readOnly ? { annotations: { readOnlyHint: true } } : {}) };
+}
+/** The `codemodeTools` setting at load time. Invalid settings keep the default; launches report them. */
+export function loadCodemodeToolsSetting(agentDir?: string): WorkflowSettings["codemodeTools"] {
+  try { return loadSettings(workflowSettingsPath(agentDir)).codemodeTools; } catch { return undefined; }
+}
 export function loadSettingsOverrides(path: string): Readonly<WorkflowSettingsOverrides> { return parseSettings(path, true); }
 export function resolveWorkflowSettings(cwd: string, projectTrusted: boolean, globalSettingsPath = workflowSettingsPath()): WorkflowSettingsResolution {
   const projectSettingsPath = workflowProjectSettingsPath(cwd);

package/src/trajectory.ts

@@ -5,12 +5,13 @@ import { basename, dirname, join, resolve } from "node:path";
 import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, DefaultPackageManager, getAgentDir, SettingsManager, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import { listRunIds, RunStore, type AwaitingCheckpoint, type CompletedOperation, type EffectiveSystemPrompt, type PersistedRun } from "./persistence.js";
 import { navigatorAttentionSortByState } from "./host-view.js";
-import type { AgentAttemptSummary, AgentRecord, JsonValue, LaunchSnapshot, WorkflowAgentSessionReference } from "./types.js";
+import type { AgentAttemptSummary, AgentRecord, JsonValue, LaunchSnapshot, WorkflowAgentSessionReference, WorkflowErrorCode, WorkflowScriptCall } from "./types.js";
 import { normalizeSubagentRunRequest, type SubagentProgress, type SubagentRunRequest, type SubagentStatus } from "../subagents/src/contracts.js";
 import { statusValue, subagentErrorValue } from "../subagents/src/decode.js";
 import { isNodeError, jsonValue, object, resourcePatternHasMagic, selectResourcesByLayers } from "./utils.js";
 import type { TrajectoryAction, TrajectoryTarget } from "./trajectory-contracts.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;
@@ -22,7 +23,8 @@ export type TrajectoryAgentOutput =
   | { readonly status: "truncated"; readonly kind: "result" | "failure"; readonly bytes: number; readonly path?: string }
   | { readonly status: "unavailable" };
 export type TrajectoryAgent = AgentRecord & { readonly output: TrajectoryAgentOutput };
-export type TrajectoryRunRecord = Omit<PersistedRun, "agents"> & { readonly agents: readonly TrajectoryAgent[] };
+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;
   snapshot: Readonly<LaunchSnapshot>;
@@ -124,7 +126,7 @@ function transcriptToolCallId(value: unknown): string | undefined {
   for (const part of message.content) if (object(part) && typeof part.id === "string") return part.id;
   return undefined;
 }
-function isTimingTranscriptEntry(value: unknown): boolean { return object(value) && value.type === "custom" && value.customType === "pi-workflows:tool-timing"; }
+export function isTimingTranscriptEntry(value: unknown): boolean { return object(value) && value.type === "custom" && value.customType === TOOL_TIMING_ENTRY_TYPE; }
 function timingToolCallId(value: unknown): string | undefined {
   if (!object(value) || !isTimingTranscriptEntry(value) || !object(value.data)) return undefined;
   return typeof value.data.toolCallId === "string" ? value.data.toolCallId : undefined;
@@ -243,7 +245,8 @@ export function withPiToolDescriptionsForTools(tools: readonly string[], cwd: st
 function canonicalExtensionSelector(selector: string, base: string): string {
   const negated = selector.startsWith("!");
   const body = negated ? selector.slice(1) : selector;
-  if (body === "*" || body === "**" || body.startsWith("**/")) return selector;
+  // 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)) return `${negated ? "!" : ""}${resolved}`;
   return `${negated ? "!" : ""}${canonicalPath(resolved)}`;
@@ -319,11 +322,17 @@ function failedAgentOutput(agent: PersistedRun["agents"][number]): TrajectoryAge
   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: CompletedOperation): TrajectoryAgentOutput {
+  const bytes = serializedJsonBytes(operation.value);
+  return bytes > DEFAULT_MAX_BYTES ? { status: "truncated", kind: "result", bytes } : { status: "available", value: operation.value, bytes };
+}
+function outputForCall(call: WorkflowScriptCall, operation: CompletedOperation | undefined): TrajectoryScriptCall["output"] {
+  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: PersistedRun["agents"][number], operation: CompletedOperation | undefined): TrajectoryAgentOutput {
-  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") return { status: "unavailable" };
   return { status: "pending" };
@@ -331,17 +340,27 @@ function outputForAgent(agent: PersistedRun["agents"][number], operation: Comple
 export function applyTrajectoryAgentOutputs(run: PersistedRun, operations: readonly CompletedOperation[]): TrajectoryRunRecord {
   const byPath = new Map(operations.map((operation) => [operation.path, operation]));
   const agents: readonly TrajectoryAgent[] = 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): TrajectoryScriptCall => {
+    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: Omit<PersistedRun, "scriptCalls"> = run;
+  return { ...rest, agents, ...(scriptCalls === undefined ? {} : { scriptCalls }) };
 }
 function overlayTrajectoryRun(run: TrajectoryRunRecord, overlay: (run: PersistedRun) => PersistedRun): TrajectoryRunRecord {
-  const overlaid = overlay(run);
+  const overlaid: Omit<PersistedRun, "scriptCalls"> = overlay(run);
   const outputs = new Map(run.agents.map((agent) => [agent.id, agent.output]));
   const agents: readonly TrajectoryAgent[] = overlaid.agents.map((agent) => {
     const previous = outputs.get(agent.id);
     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: RunStore, includeTranscripts = true): Promise<TrajectoryRun> {
   const value = await store.load();

package/src/types.ts

@@ -29,7 +29,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",
   ] as const;
 
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -97,8 +97,9 @@ export interface WorkflowExtensionSettingsValidatorContext { source: WorkflowExt
 export type WorkflowExtensionSettingsValidator = (settings: Readonly<WorkflowExtensionSettings>, context: Readonly<WorkflowExtensionSettingsValidatorContext>) => void;
 export interface WorkflowSessionStartEvent { type: "session_start"; reason: "startup" | "reload" | "new" | "resume" | "fork"; previousSessionFile?: string; settings: Readonly<WorkflowExtensionSettings> }
 export interface WorkflowRetentionSettings { olderThanDays?: number; maxTerminalRuns?: number }
-export interface WorkflowSettings { concurrency: number; backgroundWidget?: boolean; modelAliases?: Readonly<Record<string, string>>; skills?: readonly string[]; extensions?: readonly string[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; tools?: readonly string[]; retention?: Readonly<WorkflowRetentionSettings>; worktreePostCreateCommand?: readonly string[] }
-export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget">>;
+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[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; tools?: readonly string[]; retention?: Readonly<WorkflowRetentionSettings>; worktreePostCreateCommand?: readonly string[] }
+export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget" | "codemodeTools">>;
 export interface WorkflowSettingsSources { concurrency: string; modelAliases: string; skills?: string; extensions?: string; tools?: string; extensionSettings?: string; retention?: string; worktreePostCreateCommand?: string }
 export interface WorkflowSettingsResolution { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: Readonly<WorkflowSettings>; project: Readonly<WorkflowSettingsOverrides>; effective: Readonly<WorkflowSettings>; sources: Readonly<WorkflowSettingsSources> }
 export interface AgentResourceSelectors { skills?: readonly string[]; extensions?: readonly string[]; tools?: readonly string[] }
@@ -178,6 +179,8 @@ export interface WorkflowRunEvent { type: string; message: string; timestamp?: n
 export interface WorkflowRetryProvenance { sourceRunId: string; lineageRootRunId: string; completedPaths: readonly string[]; incompletePaths: readonly string[]; namedWorktrees: readonly string[] }
 export interface WorkflowPhaseRecord { phase: string; afterAgent: number }
 export interface WorkflowPhaseShellActivity { phaseIndex: number; 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;
@@ -194,6 +197,8 @@ export interface RunRecord {
   activeShells?: number;
   activeShellStartedAt?: number;
   activeShellsByPhase?: readonly WorkflowPhaseShellActivity[];
+  activeTools?: readonly { name: string; startedAt: number }[]; // Script tool calls in flight: a live overlay for rendering, never persisted.
+  scriptCalls?: readonly WorkflowScriptCall[];
   error?: WorkflowErrorShape;
   failedAt?: string;
   budget?: WorkflowBudget;
@@ -356,7 +361,9 @@ export interface FunctionIdentity { path: string; structuralPath: readonly strin
 export type AgentContinuity = "fresh" | "continued";
 export interface AgentIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; parentBreadcrumb?: string; worktreeOwner?: string; handle?: string; turn?: number }
 export interface ShellIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; worktreeOwner?: string }
-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>; checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>; function?: (name: string, input: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: FunctionIdentity) => Promise<JsonValue>; worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>; functions?: Readonly<Record<string, { name: string }>>; phase?: (name: string) => void | Promise<void>; log?: (message: string) => void | Promise<void> }
+/** 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>; checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>; function?: (name: string, input: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: FunctionIdentity) => Promise<JsonValue>; worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>; functions?: Readonly<Record<string, { name: string }>>; 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>; cancel: () => void }
 export interface StaticWorkflowScope { kind: "parallel" | "pipeline"; name: string | null; key: string | null }
 export type StaticWorkflowExecution = "parallel" | "sequential";

package/src/utils.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WorkflowError, type JsonSchema, type JsonValue, type ModelSpec, type ThinkingLevel, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
 import { Minimatch } from "minimatch";
 export class SerialLane {
@@ -18,6 +19,15 @@ export function sanitizeDisplayText(value: string): string { return value.replac
 export { object as isObject };
 function isStringKey(key: PropertyKey): key is string { return typeof key === "string"; }
 function stringKeyValue(value: object, key: string): unknown { return object(value) ? value[key] : undefined; }
+function sortedJson(value: JsonValue): JsonValue {
+  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] as JsonValue)]));
+}
+/** A short digest of a JSON value that ignores object key order. */
+export function jsonDigest(value: JsonValue): string {
+  return createHash("sha256").update(JSON.stringify(sortedJson(value))).digest("hex").slice(0, 16);
+}
 export function jsonValue(value: unknown, seen = new Set<object>()): value is JsonValue {
   if (value === null || typeof value === "boolean" || typeof value === "string") return true;
   if (typeof value === "number") return Number.isFinite(value);
@@ -153,6 +163,24 @@ export function resolveModelReference(value: string, aliases: Readonly<Record<st
   };
   return resolveReference(value, []);
 }
+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 function reachableTools(pi: ToolSource): string[] {
+  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: ModelSpec, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec {
+  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: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string {
   const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
   return `${parsed.provider}/${parsed.model}`;

package/src/validation.ts

@@ -12,7 +12,7 @@ export { loadAgentDefinitions, loadProjectAgentDefinitions, parseRoleMarkdown, w
 export type { WorkflowRoleDirectoryInput } 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: unknown): CheckpointInput {
   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");
@@ -219,6 +219,24 @@ function callHasTrailingComma(source: string, call: WorkflowCall): boolean {
   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: string): string[] | undefined {
+  const body = workflowBody(script);
+  if (!body.trim()) return [];
+  const names = new Set<string>();
+  const opaque = (node: acorn.AnyNode, parent?: acorn.AnyNode): boolean => {
+    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: string): string {
   const body = workflowBody(script);
   if (!body.trim()) return body;

package/starter/review-loop.ts

@@ -69,5 +69,3 @@ export const reviewLoop = defineWorkflowFunction({
   ),
 });
 
-export const reviewLoopInputSchema = reviewLoop.input;
-export const reviewLoopOutputSchema = reviewLoop.output;

package/subagents/README.md

@@ -53,14 +53,14 @@ Every tool schema is a closed object. Unknown properties are rejected. The model
 | Tool | Input schema |
 | --- | --- |
 | `subagents_run` | `{ prompt: string, mode?: "background" \| "foreground", label?: string, model?: string, tools?: string[], skills?: string[], extensions?: string[], contextFiles?: string[], role?: string, worktree?: string, outputSchema?: object, retries?: integer 0..255, timeoutMs?: positive integer \| null }` |
-| `subagents_inspect` | `{ id?: string }` |
+| `subagents_inspect` | `{ id?: string, scope?: "session" \| "all" }` |
 | `subagents_steer` | `{ id: string, message: string }` |
 | `subagents_stop` | `{ id: string }` |
 | `subagents_retry` | `{ id: string }` |
 
 `prompt` is the only required `subagents_run` property. `mode` defaults to "background". Resource candidates start enabled, so plain positive top-level selector lists are additive and top-level `[]` adds no matches. Use `["!*", "read", "grep"]` to restrict a selector to those resources, or `["!*"]` to select none. A `role` string selects an existing workflow role. Model, tools, skills, extensions, and contextFiles are top-level `AgentOptions` overrides applied after the role file. Concrete models are `provider/model:thinking`. Capability selectors use ordered minimatch rules and are applied after global, trusted-project, and role selectors. Use `tools: ["*"]` to re-enable all tools after a role restriction.
 
-`subagents_inspect({})` returns all accessible run summaries ordered by start time. `subagents_inspect({ id })` returns the detailed lifecycle record, including state, start and finish timestamps, and the live snapshot under `progress`: `state`, cumulative `accounting`, `toolCalls`, `activity`, and `lastEventAt`. The snapshot state never includes the effective system prompt, and inspection has no `usage` field; token totals are derived from accounting. Materialized worktree path and branch are included when available. For completed runs it also includes `value`; for failed runs it includes `error`. A running run has no terminal value yet. Unknown IDs fail with `RUN_NOT_FOUND`.
+`subagents_inspect({})` returns the current Pi session's run summaries ordered by start time; `subagents_inspect({ scope: "all" })` lists every stored run. `subagents_inspect({ id })` returns the detailed lifecycle record, including state, start and finish timestamps, and the live snapshot under `progress`: `state`, cumulative `accounting`, `toolCalls`, `activity`, and `lastEventAt`. The snapshot state never includes the effective system prompt, and inspection has no `usage` field; token totals are derived from accounting. Materialized worktree path and branch are included when available. For completed runs it also includes `value`; for failed runs it includes `error`. A running run has no terminal value yet. Unknown IDs fail with `RUN_NOT_FOUND`.
 
 ## Launching and concurrency
 

package/subagents/src/contracts.ts

@@ -41,6 +41,7 @@ export const SUBAGENTS_RUN_PARAMETERS = Type.Object({
 
 export const SUBAGENTS_INSPECT_PARAMETERS = Type.Object({
   id: Type.Optional(Type.String({ description: "Subagent ID; omit to list ordered run summaries" })),
+  scope: Type.Optional(Type.Union([Type.Literal("session"), Type.Literal("all")], { description: "List scope when id is omitted: session (default) lists runs from the current Pi session; all lists every stored run" })),
 }, { additionalProperties: false });
 
 export const SUBAGENTS_ID_PARAMETERS = Type.Object({
@@ -60,13 +61,23 @@ export const SUBAGENTS_RETRY_PARAMETERS = Type.Object({
   id: Type.String({ description: "Failed or stopped subagent ID to retry" }),
 }, { additionalProperties: false });
 
-export const SUBAGENTS_TOOL_SCHEMAS = {
-  subagents_run: SUBAGENTS_RUN_PARAMETERS,
-  subagents_inspect: SUBAGENTS_INSPECT_PARAMETERS,
-  subagents_steer: SUBAGENTS_STEER_PARAMETERS,
-  subagents_stop: SUBAGENTS_STOP_PARAMETERS,
-  subagents_retry: SUBAGENTS_RETRY_PARAMETERS,
-} as const;
+// Structured results codemode scripts receive instead of the JSON text; nested records stay loose so they cannot drift from persistence.
+export const SUBAGENT_STATUS_OUTPUT = Type.Object({
+  id: Type.String(),
+  state: Type.String(),
+  sessionId: Type.Optional(Type.String()),
+  startedAt: Type.Optional(Type.Number()),
+  finishedAt: Type.Optional(Type.Number()),
+  attempts: Type.Optional(Type.Number()),
+  attemptDetails: Type.Optional(Type.Array(Type.Unknown())),
+  worktree: Type.Optional(Type.Object({ path: Type.String(), branch: Type.String() })),
+  error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String() })),
+  progress: Type.Optional(Type.Unknown()),
+  value: Type.Optional(Type.Unknown()),
+});
+// One run when id is given, otherwise the ordered run summaries; the summaries stay short in the codemode description.
+export const SUBAGENTS_INSPECT_OUTPUT = Type.Union([SUBAGENT_STATUS_OUTPUT, Type.Array(Type.Object({ id: Type.String(), state: Type.String() }))]);
+export const SUBAGENTS_STEER_OUTPUT = Type.Object({ id: Type.String(), accepted: Type.Boolean() });
 
 export type SubagentRunRequest = Static<typeof SUBAGENTS_RUN_PARAMETERS>;
 export function normalizeSubagentRunRequest(value: unknown): SubagentRunRequest {

package/subagents/src/index.ts

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import { defineTool, getAgentDir, type AgentToolResult, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
-import { WorkflowError, loadingRegistry } from "../../src/index.js";
+import { WorkflowError, loadCodemodeToolsSetting, loadingRegistry, reachableTools, workflowToolExposure, type JsonValue } from "../../src/index.js";
 import { clearSubagentManager, setSubagentManager } from "../../src/subagent-manager-handle.js";
 import type { SubagentIdRequest, SubagentInspectRequest, SubagentManager, SubagentManagerContext, SubagentNotification, SubagentsExtension, SubagentsExtensionOptions, SubagentRunRequest, SubagentStatus, SubagentSteerRequest } from "./contracts.js";
 import { createSubagentManager } from "./manager.js";
@@ -9,10 +9,13 @@ import { registerSubagentNavigator } from "./navigator.js";
 import { createSubagentBackgroundWidget, renderSubagentCall, renderSubagentControlCall, renderSubagentControlResult, renderSubagentInspectCall, renderSubagentInspectResult, renderSubagentResult } from "./view.js";
 import {
   normalizeSubagentRunRequest,
+  SUBAGENT_STATUS_OUTPUT,
   SUBAGENTS_ID_PARAMETERS,
+  SUBAGENTS_INSPECT_OUTPUT,
   SUBAGENTS_INSPECT_PARAMETERS,
   SUBAGENTS_RETRY_PARAMETERS,
   SUBAGENTS_RUN_PARAMETERS,
+  SUBAGENTS_STEER_OUTPUT,
   SUBAGENTS_STEER_PARAMETERS,
   SUBAGENTS_STOP_PARAMETERS,
 } from "./contracts.js";
@@ -23,7 +26,7 @@ export { createSubagentManager, createUnavailableSubagentManager } from "./manag
 export { createRunStoreWorktreeAdapter, defaultWorktreeHome } from "./worktree.js";
 export type { SubagentWorktreeAdapter, SubagentWorktreeContext, SubagentWorktreeHandle, SubagentWorktreeRunStore } from "./worktree.js";
 
-type SubagentsExtensionAPI = Pick<ExtensionAPI, "registerTool"> & Partial<Pick<ExtensionAPI, "getActiveTools" | "on" | "sendMessage" | "registerCommand" | "appendEntry" | "registerEntryRenderer">>;
+type SubagentsExtensionAPI = Pick<ExtensionAPI, "registerTool"> & Partial<Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "on" | "sendMessage" | "registerCommand" | "appendEntry" | "registerEntryRenderer">>;
 
 function validateSubagentRunRequest(value: unknown): SubagentRunRequest {
   return normalizeSubagentRunRequest(value);
@@ -55,7 +58,7 @@ function serialize(value: unknown): string {
 }
 
 function toolResult(value: unknown): AgentToolResult<unknown> {
-  return { content: [{ type: "text", text: serialize(value) }], details: value };
+  return { content: [{ type: "text", text: serialize(value) }], details: value, structuredContent: value as JsonValue };
 }
 
 function managerContext(toolCallId: string, signal: AbortSignal | undefined, onUpdate: ((value: AgentToolResult<unknown>) => void) | undefined, context: ExtensionContext): SubagentManagerContext {
@@ -78,6 +81,7 @@ export function createSubagentTools(manager: SubagentManager): readonly ToolDefi
         "Do not poll a running ID; use subagents_inspect({ id }) when you need its current status or terminal result.",
       ],
       parameters: SUBAGENTS_RUN_PARAMETERS,
+      outputSchema: SUBAGENT_STATUS_OUTPUT,
       async execute(toolCallId, params, signal, onUpdate, context) {
         return toolResult(await manager.run(validateSubagentRunRequest(params), managerContext(toolCallId, signal, onUpdate, context)));
       },
@@ -87,8 +91,9 @@ export function createSubagentTools(manager: SubagentManager): readonly ToolDefi
     defineTool({
       name: "subagents_inspect",
       label: "Subagents Inspect",
-      description: "Inspect durable subagent runs. Omit id for ordered run summaries, or provide id for detailed status, progress, activity, accounting, tool calls, timestamps, worktree metadata, and a terminal value or error when available.",
+      description: "Inspect durable subagent runs. Omit id for ordered run summaries of the current session (scope all for every session), or provide id for detailed status, progress, activity, accounting, tool calls, timestamps, worktree metadata, and a terminal value or error when available.",
       parameters: SUBAGENTS_INSPECT_PARAMETERS,
+      outputSchema: SUBAGENTS_INSPECT_OUTPUT,
       async execute(toolCallId, params, signal, onUpdate, context) {
         return toolResult(await manager.inspect(validateSubagentInspectRequest(params), managerContext(toolCallId, signal, onUpdate, context)));
       },
@@ -100,6 +105,7 @@ export function createSubagentTools(manager: SubagentManager): readonly ToolDefi
       label: "Subagents Steer",
       description: "Send a message to a running subagent. The message is queued safely if its steering handler is not ready; settled runs cannot be steered.",
       parameters: SUBAGENTS_STEER_PARAMETERS,
+      outputSchema: SUBAGENTS_STEER_OUTPUT,
       async execute(toolCallId, params, signal, onUpdate, context) {
         return toolResult(await manager.steer(validateSubagentSteerRequest(params), managerContext(toolCallId, signal, onUpdate, context)));
       },
@@ -111,6 +117,7 @@ export function createSubagentTools(manager: SubagentManager): readonly ToolDefi
       label: "Subagents Stop",
       description: "Stop one running subagent, abort its active session, persist state \"stopped\", and clean its worktree without affecting sibling runs.",
       parameters: SUBAGENTS_STOP_PARAMETERS,
+      outputSchema: SUBAGENT_STATUS_OUTPUT,
       async execute(toolCallId, params, signal, onUpdate, context) {
         return toolResult(await manager.stop(validateSubagentIdRequest(params, "subagents_stop"), managerContext(toolCallId, signal, onUpdate, context)));
       },
@@ -122,6 +129,7 @@ export function createSubagentTools(manager: SubagentManager): readonly ToolDefi
       label: "Subagents Retry",
       description: "Start a fresh run from a failed or stopped subagent's persisted request. The new run gets a new ID and preserves its original background or foreground mode.",
       parameters: SUBAGENTS_RETRY_PARAMETERS,
+      outputSchema: SUBAGENT_STATUS_OUTPUT,
       async execute(toolCallId, params, signal, onUpdate, context) {
         return toolResult(await manager.retry(validateSubagentIdRequest(params, "subagents_retry"), managerContext(toolCallId, signal, onUpdate, context)));
       },
@@ -162,7 +170,8 @@ export function createSubagentsExtension(options: SubagentsExtensionOptions = {}
 
 export function registerSubagentsExtension(pi: SubagentsExtensionAPI, options: SubagentsExtensionOptions = {}): SubagentsExtension {
   const getActiveTools = pi.getActiveTools;
-  const activeTools = getActiveTools === undefined ? undefined : () => getActiveTools.call(pi);
+  const getAllTools = pi.getAllTools;
+  const activeTools = getActiveTools === undefined ? undefined : () => reachableTools({ getActiveTools: () => getActiveTools.call(pi), ...(getAllTools === undefined ? {} : { getAllTools: () => getAllTools.call(pi) }) });
   const sendMessage = pi.sendMessage;
   const notify = sendMessage === undefined ? undefined : (notification: SubagentNotification): void => {
     sendMessage.call(pi, { customType: "subagents", content: notificationContent(notification), display: true, details: notification }, { deliverAs: "steer", triggerTurn: true });
@@ -173,7 +182,8 @@ export function registerSubagentsExtension(pi: SubagentsExtensionAPI, options: S
   const appendEntry = pi.appendEntry;
   const widget = createSubagentBackgroundWidget({ ...(appendEntry === undefined ? {} : { appendEntry: (customType, data) => { appendEntry.call(pi, customType, data); } }), ...(pi.registerEntryRenderer === undefined ? {} : { registerEntryRenderer: pi.registerEntryRenderer.bind(pi) }) });
   const extension = createSubagentsExtension(options, activeTools, notify, (status, request) => { widget.update(status, request); const registry = loadingRegistry(); if (typeof registry.observeSubagentStatus === "function") registry.observeSubagentStatus(status, request); }, onResourceWarning);
-  for (const tool of extension.tools) pi.registerTool(tool);
+  const codemodeTools = loadCodemodeToolsSetting(options.managerDependencies?.agentDir);
+  for (const tool of extension.tools) pi.registerTool({ ...tool, ...workflowToolExposure(tool.name, codemodeTools) });
   if (pi.registerCommand !== undefined) registerSubagentNavigator(pi.registerCommand.bind(pi), extension.manager, storageDirectory(options), options.clipboard);
   if (pi.on !== undefined) {
     setSubagentManager(extension.manager);

package/subagents/src/manager.ts

@@ -1113,9 +1113,9 @@ class PersistentSubagentManager implements SubagentManager {
       }
       return inspection;
     }
-    return this.inspectList();
+    return this.inspectList(request.scope === "all" ? undefined : context.extensionContext.sessionManager.getSessionId());
   }
-  private async inspectList(): Promise<unknown> {
+  private async inspectList(sessionId: string | undefined): Promise<unknown> {
     const root = storageDirectory(this.dependencies);
     await secureDirectory(root);
     const entries = await readdir(root, { withFileTypes: true });
@@ -1127,7 +1127,7 @@ class PersistentSubagentManager implements SubagentManager {
       try {
         const active = this.activeRuns.get(entry.name);
         const status = publicStatus(active ? persistedStatus(active) : this.terminalSummaries.get(entry.name) ?? await loadPersistedStatus(root, entry.name, false));
-        if (status.startedAt === undefined) continue;
+        if (status.startedAt === undefined || (sessionId !== undefined && status.sessionId !== sessionId)) continue;
         statuses.push({ status, startedAt: status.startedAt });
       } catch (error) {
         if (error instanceof WorkflowError && (error.code === "RUN_NOT_FOUND" || error instanceof InvalidPersistedSubagentStatusError)) continue;