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

package/src/validation.ts

@@ -1,20 +1,19 @@
-import { atomicWriteFile } from "./persistence.js";
-import { mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, extname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import * as acorn from "acorn";
 import { Script } from "node:vm";
-import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import type { AgentDefinition, AgentResourceSelectors, AgentResourceSelectorSet, AgentResourcePolicy, CheckpointInput, ContextFileScope, JsonSchema, JsonValue, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, StaticWorkflowExecution, StaticWorkflowScope, ValidatedWorkflowLaunch, WorkflowCallKind, WorkflowErrorCode, WorkflowExtensionMetadata, WorkflowExtensionSettings, WorkflowMetadata, WorkflowRetentionSettings, WorkflowRoleDirectoryRegistration, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution, WorkflowSettingsSources, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
+import type { AgentDefinition, CheckpointInput, JsonSchema, JsonValue, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, StaticWorkflowExecution, StaticWorkflowScope, ValidatedWorkflowLaunch, WorkflowCallKind, WorkflowErrorCode, WorkflowMetadata, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
 import type { WorkflowRegistryApi } from "./registry.js";
-import { registeredWorkflowRoleDirectoryRegistrations } from "./registry.js";
-import { annotateModelAliasError, assertModelThinking, deepFreeze, errorText, fail, isNodeError, jsonObject, jsonValue, mergeWorkflowExtensionSettings, modelAliasName, modelCapability, object, positiveInteger, resolveModelReference, resourcePatternHasMagic, unknownModel, validateModelAliases, validateResourcePattern, validWorkflowExtensionNamespace } from "./utils.js";
-import { WORKFLOW_CALL_KINDS, isContextFileScope } from "./types.js";
-import { canonicalPath, workflowProjectSettingsPath } from "./paths.js";
-export { workflowProjectSettingsPath } from "./paths.js";
+import { assertModelThinking, validateSchema, deepFreeze, errorText, fail, jsonObject, jsonValue, mergeWorkflowExtensionSettings, modelAliasName, modelCapability, object, positiveInteger, resolveModelReference, resourcePatternHasMagic, unknownModel } from "./utils.js";
+import { WORKFLOW_CALL_KINDS } from "./types.js";
+export { validateSchema } from "./utils.js";
+import { loadAgentDefinitions, loadProjectAgentDefinitions } from "./roles.js";
+export { loadAgentDefinitions, loadProjectAgentDefinitions, parseRoleMarkdown, workflowRoleDirectories } from "./roles.js";
+export type { WorkflowRoleDirectoryInput } from "./roles.js";
+
+import { validateContextFileScopes, validateSelectorList } from "./settings.js";
+export { DEFAULT_SETTINGS, loadCodemodeToolsSetting, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./settings.js";
 
-export const DEFAULT_SETTINGS: Readonly<WorkflowSettings> = Object.freeze({ concurrency: 8, backgroundWidget: true });
 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");
   if (Buffer.byteLength(value.prompt) > 1024) fail("INVALID_METADATA", "checkpoint prompt exceeds 1024 UTF-8 bytes");
@@ -22,342 +21,6 @@ export function validateCheckpoint(value: unknown): CheckpointInput {
   return { name: value.name, prompt: value.prompt, context: value.context };
 }
 
-export function workflowSettingsPath(agentDir = getAgentDir()): string { return join(agentDir, ROLE_DIRECTORY, "settings.json"); }
-function normalizedResourcePath(value: string, settingsPath: string): string {
-  if (value === "*") 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);
-  if (expanded === "**" || expanded.startsWith("**/") || expanded.startsWith("**\\")) return expanded;
-  if (resourcePatternHasMagic(expanded)) {
-    const magicIndex = resolved.search(/[*?\x5b\x5d{}()]/);
-    const separatorIndex = Math.max(resolved.lastIndexOf("/", magicIndex), resolved.lastIndexOf("\\", magicIndex));
-    const rootBoundary = separatorIndex === 0 || (separatorIndex === 2 && /^[A-Za-z]:[\\/]/.test(resolved));
-    const prefix = rootBoundary ? resolved.slice(0, separatorIndex + 1) : separatorIndex >= 0 ? resolved.slice(0, separatorIndex) : resolved;
-    const suffix = rootBoundary ? resolved.slice(separatorIndex + 1) : separatorIndex >= 0 ? resolved.slice(separatorIndex) : "";
-    return `${canonicalPath(prefix)}${suffix}`;
-  }
-  return canonicalPath(resolved);
-}
-function validateSelectorList(value: unknown, path: string, kind: "skills" | "extensions" | "tools", errorCode: "INVALID_SETTINGS" | "INVALID_METADATA" = "INVALID_SETTINGS", normalizeExtensions = true): readonly string[] | undefined {
-  if (value === undefined) return undefined;
-  if (!Array.isArray(value)) fail(errorCode, `${path}.${kind} must be an array`);
-  const normalized: string[] = [];
-  for (const [index, entry] of value.entries()) {
-    if (typeof entry !== "string" || !entry.trim()) fail(errorCode, `${path}.${kind}[${String(index)}] must be a non-empty string`);
-    let selector = entry.trim();
-    if (kind === "extensions" && normalizeExtensions) {
-      const negated = selector.startsWith("!");
-      const body = negated ? selector.slice(1) : selector;
-      if (!body) fail(errorCode, `${path}.${kind}[${String(index)}] must be a valid minimatch pattern: Empty minimatch pattern ${JSON.stringify(selector)}`);
-      try { selector = `${negated ? "!" : ""}${normalizedResourcePath(body, path)}`; } catch (error) { fail(errorCode, `${path}.${kind}[${String(index)}] must be a valid path: ${errorText(error)}`); }
-    }
-    try { validateResourcePattern(selector); } catch (error) { fail(errorCode, `${path}.${kind}[${String(index)}] must be a valid minimatch pattern: ${errorText(error)}`); }
-    normalized.push(selector);
-  }
-  return Object.freeze(normalized);
-}
-function validateWorktreePostCreateCommand(value: unknown, settingsPath: string): readonly string[] | undefined {
-  if (value === undefined) return undefined;
-  if (!Array.isArray(value) || value.length === 0) fail("INVALID_SETTINGS", `${settingsPath}.worktreePostCreateCommand must be a non-empty array`);
-  return Object.freeze(value.map((entry, index) => {
-    if (typeof entry !== "string" || !entry.trim()) fail("INVALID_SETTINGS", `${settingsPath}.worktreePostCreateCommand[${String(index)}] must be a non-empty string`);
-    return entry;
-  }));
-}
-function selectorsFromSettings(settings: Readonly<WorkflowSettings | WorkflowSettingsOverrides>): AgentResourceSelectors {
-  return {
-    ...(settings.skills === undefined ? {} : { skills: settings.skills }),
-    ...(settings.extensions === undefined ? {} : { extensions: settings.extensions }),
-    ...(settings.tools === undefined ? {} : { tools: settings.tools }),
-  };
-}
-function selectorSet(value: AgentResourceSelectors | undefined): AgentResourceSelectorSet { return { skills: [...(value?.skills ?? [])], extensions: [...(value?.extensions ?? [])], ...(value?.tools === undefined ? {} : { tools: [...value.tools] }) }; }
-function validateContextFileScopes(value: unknown, rolePath: string): readonly ContextFileScope[] | undefined {
-  if (value === undefined) return undefined;
-  if (!Array.isArray(value) || !value.every(isContextFileScope)) fail("INVALID_METADATA", `${rolePath}.contextFiles must be an array containing only global, project, or cwd`);
-  return [...value];
-}
-export function validateWorkflowExtensionSettings(value: unknown, settingsPath: string, errorCode: "INVALID_SETTINGS" | "INVALID_METADATA" = "INVALID_SETTINGS", applyDefaults = true): WorkflowExtensionSettings | undefined {
-  if (value === undefined) return undefined;
-  const base = `${settingsPath}.extensionSettings`;
-  if (!object(value)) fail(errorCode, `${base} must be an object`);
-  const normalized: Record<string, JsonValue> = {};
-  for (const [namespace, raw] of Object.entries(value)) {
-    if (!validWorkflowExtensionNamespace(namespace)) fail(errorCode, `${base} contains an invalid namespace: ${namespace}`);
-    if (namespace === "herdr") {
-      if (!object(raw)) fail(errorCode, `${base}.herdr must be an object`);
-      if (Object.keys(raw).some((key) => key !== "enableFullyInspectableMode")) fail(errorCode, `${base}.herdr contains an unsupported setting`);
-      if (raw.enableFullyInspectableMode !== undefined && typeof raw.enableFullyInspectableMode !== "boolean") fail(errorCode, `${base}.herdr.enableFullyInspectableMode must be a boolean`);
-      normalized.herdr = Object.freeze({ ...(raw.enableFullyInspectableMode === undefined ? {} : { enableFullyInspectableMode: raw.enableFullyInspectableMode }) });
-      continue;
-    }
-    if (namespace === "trajectory") {
-      if (!object(raw)) fail(errorCode, `${base}.trajectory must be an object`);
-      if (Object.keys(raw).some((key) => key !== "port" && key !== "themes")) fail(errorCode, `${base}.trajectory contains an unsupported setting`);
-      if (raw.port !== undefined && (!positiveInteger(raw.port) || raw.port > 65535)) fail(errorCode, `${base}.trajectory.port must be an integer from 1 to 65535`);
-      if (raw.themes !== undefined && typeof raw.themes !== "boolean") fail(errorCode, `${base}.trajectory.themes must be a boolean`);
-      normalized.trajectory = Object.freeze({ ...(raw.port === undefined ? {} : { port: raw.port }), ...(raw.themes === undefined ? (applyDefaults ? { themes: false } : {}) : { themes: raw.themes }) });
-      continue;
-    }
-    if (!jsonValue(raw)) fail(errorCode, `${base}.${namespace} must be JSON-compatible`);
-    normalized[namespace] = structuredClone(raw);
-  }
-  return deepFreeze(normalized as WorkflowExtensionSettings);
-}
-function positiveRetentionInteger(value: unknown): value is number { return positiveInteger(value) && Number.isSafeInteger(value); }
-function validateRetention(value: unknown, settingsPath: string): Readonly<WorkflowRetentionSettings> | undefined {
-  if (value === undefined) return undefined;
-  const base = `${settingsPath}.retention`;
-  if (!object(value)) fail("INVALID_SETTINGS", `${base} must be an object`);
-  const unknown = Object.keys(value).find((key) => key !== "olderThanDays" && key !== "maxTerminalRuns");
-  if (unknown) fail("INVALID_SETTINGS", `Unknown retention setting at ${base}: ${unknown}`);
-  if (value.olderThanDays !== undefined && !positiveRetentionInteger(value.olderThanDays)) fail("INVALID_SETTINGS", `${base}.olderThanDays must be a positive integer`);
-  if (value.maxTerminalRuns !== undefined && !positiveRetentionInteger(value.maxTerminalRuns)) fail("INVALID_SETTINGS", `${base}.maxTerminalRuns must be a positive integer`);
-  return Object.freeze({ ...(value.olderThanDays === undefined ? {} : { olderThanDays: value.olderThanDays }), ...(value.maxTerminalRuns === undefined ? {} : { maxTerminalRuns: value.maxTerminalRuns }) });
-}
-function parseSettings(path: string, partial: false): Readonly<WorkflowSettings>;
-function parseSettings(path: string, partial: true): Readonly<WorkflowSettingsOverrides>;
-function parseSettings(path: string, partial: boolean): Readonly<WorkflowSettings | WorkflowSettingsOverrides> {
-  let parsed: unknown;
-  try { parsed = JSON.parse(readFileSync(path, "utf8")); }
-  catch (error) {
-    if (isNodeError(error, "ENOENT")) return partial ? Object.freeze({}) : DEFAULT_SETTINGS;
-    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 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}`);
-  const concurrency = parsed.concurrency === undefined ? (partial ? undefined : DEFAULT_SETTINGS.concurrency) : parsed.concurrency;
-  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 modelAliases = parsed.modelAliases === undefined ? undefined : validateModelAliases(parsed.modelAliases, path);
-  const skills = validateSelectorList(parsed.skills, path, "skills");
-  const tools = validateSelectorList(parsed.tools, path, "tools");
-  const extensions = validateSelectorList(parsed.extensions, path, "extensions");
-  const extensionSettings = parsed.extensionSettings === undefined ? undefined : validateWorkflowExtensionSettings(parsed.extensionSettings, path, "INVALID_SETTINGS", !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 }),
-    ...(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); }
-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);
-  const global = loadSettings(globalSettingsPath);
-  const project: Readonly<WorkflowSettingsOverrides> = projectTrusted ? loadSettingsOverrides(projectSettingsPath) : Object.freeze({});
-  const projectHas = (key: keyof WorkflowSettingsOverrides): boolean => Object.prototype.hasOwnProperty.call(project, key);
-  const sourceFor = (key: "skills" | "extensions" | "tools"): string => projectHas(key) ? projectSettingsPath : globalSettingsPath;
-  const globalSelectors = selectorsFromSettings(global);
-  const projectSelectors = selectorsFromSettings(project);
-  const effectiveSelectors = selectorSet({
-    skills: [...(globalSelectors.skills ?? []), ...(projectSelectors.skills ?? [])],
-    extensions: [...(globalSelectors.extensions ?? []), ...(projectSelectors.extensions ?? [])],
-    ...(globalSelectors.tools === undefined && projectSelectors.tools === undefined ? {} : { tools: [...(globalSelectors.tools ?? []), ...(projectSelectors.tools ?? [])] }),
-  });
-  const hasExtensionSelectors = global.extensions !== undefined || project.extensions !== undefined;
-  const extensionSettings = projectHas("extensionSettings") ? project.extensionSettings : global.extensionSettings;
-  const sources: WorkflowSettingsSources = {
-    concurrency: projectHas("concurrency") ? projectSettingsPath : globalSettingsPath,
-    modelAliases: projectHas("modelAliases") ? projectSettingsPath : globalSettingsPath,
-    skills: sourceFor("skills"), extensions: sourceFor("extensions"), tools: sourceFor("tools"),
-    ...(extensionSettings === undefined ? {} : { extensionSettings: projectHas("extensionSettings") ? projectSettingsPath : globalSettingsPath }),
-    ...(project.retention === undefined && global.retention === undefined ? {} : { retention: project.retention === undefined ? globalSettingsPath : projectSettingsPath }),
-    ...(projectHas("worktreePostCreateCommand") || global.worktreePostCreateCommand !== undefined ? { worktreePostCreateCommand: projectHas("worktreePostCreateCommand") ? projectSettingsPath : globalSettingsPath } : {}),
-  };
-  const effective = Object.freeze({
-    concurrency: project.concurrency ?? global.concurrency,
-    backgroundWidget: global.backgroundWidget ?? true,
-    ...(projectHas("modelAliases") ? { modelAliases: project.modelAliases } : global.modelAliases === undefined ? {} : { modelAliases: global.modelAliases }),
-    ...(effectiveSelectors.skills.length ? { skills: effectiveSelectors.skills } : global.skills !== undefined || project.skills !== undefined ? { skills: effectiveSelectors.skills } : {}),
-    ...(hasExtensionSelectors ? { extensions: effectiveSelectors.extensions } : {}),
-    ...(extensionSettings === undefined ? {} : { extensionSettings }),
-    ...(effectiveSelectors.tools?.length ? { tools: effectiveSelectors.tools } : global.tools !== undefined || project.tools !== undefined ? { tools: effectiveSelectors.tools } : {}),
-    ...((project.retention ?? global.retention) === undefined ? {} : { retention: project.retention ?? global.retention }),
-    ...(projectHas("worktreePostCreateCommand") ? { worktreePostCreateCommand: project.worktreePostCreateCommand } : global.worktreePostCreateCommand === undefined ? {} : { worktreePostCreateCommand: global.worktreePostCreateCommand }),
-  });
-  return { globalSettingsPath, projectSettingsPath, projectTrusted, global, project, effective, sources };
-}
-export function validateModelAliasAvailability(aliases: Readonly<Record<string, string>>, names: readonly string[], availableModels: ReadonlySet<string>, knownModels: ReadonlySet<string>, settingsPath?: string): void {
-  for (const name of names) {
-    try {
-      const target = modelCapability(name, aliases, knownModels, settingsPath);
-      if (!availableModels.has(target)) unknownModel(name, target, settingsPath);
-    } catch (error) { throw annotateModelAliasError(error, name); }
-  }
-}
-export function resolveAgentResourcePolicy(cwd: string, projectTrusted: boolean, globalSettingsPath = workflowSettingsPath()): AgentResourcePolicy {
-  const resolved = resolveWorkflowSettings(cwd, projectTrusted, globalSettingsPath);
-  const global = selectorSet(selectorsFromSettings(resolved.global));
-  const project = selectorSet(selectorsFromSettings(resolved.project));
-  const effective = selectorSet(selectorsFromSettings(resolved.effective));
-  return { globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted, global, project, effective, unmatchedSkills: [], unmatchedExtensions: [], unmatchedTools: [], selectorSources: { global: selectorsFromSettings(resolved.global), project: selectorsFromSettings(resolved.project) } };
-}
-export function saveModelAliases(path = workflowSettingsPath(), aliases: Readonly<Record<string, string>> = {}): void {
-  const normalized = validateModelAliases(aliases, path);
-  let parsed: unknown = {};
-  try {
-    loadSettings(path);
-    parsed = JSON.parse(readFileSync(path, "utf8"));
-  } catch (error) {
-    if (!isNodeError(error, "ENOENT")) throw error;
-  }
-  if (!object(parsed)) fail("INVALID_SETTINGS", `Workflow settings at ${path} must be an object`);
-  mkdirSync(dirname(path), { recursive: true });
-  atomicWriteFile(path, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, true);
-}
-
-export function parseRoleMarkdown(content: string, strict = false, rolePath?: string): AgentDefinition {
-  if (!strict) {
-    if (!content.startsWith("---\n")) return { prompt: content };
-    const end = content.indexOf("\n---", 4);
-    if (end < 0) return { prompt: content };
-    const meta: Record<string, string> = {};
-    for (const line of content.slice(4, end).split("\n")) {
-      const match = /^(model|tools|skills|extensions|description|overrideSystemPrompt|override_system_prompt|is_system_prompt|contextFiles|extensionSettings|disabledAgentResources|thinking)\s*:\s*(.+)$/.exec(line.trim());
-      if (match?.[1] === "disabledAgentResources") fail("INVALID_METADATA", "disabledAgentResources is no longer supported; use skills, extensions, and tools selectors");
-      if (match?.[1] === "thinking") fail("INVALID_METADATA", "Role thinking is not supported; put it on model as provider/model:thinking");
-      if (match?.[1] && match[2]) meta[match[1]] = match[2].trim();
-    }
-    const unquote = (v: string) => v.replace(/^['"]|['"]$/g, "");
-    const parseList = (value: string | undefined): string[] | undefined => value === undefined ? undefined : value.replace(/^\[|\]$/g, "").split(",").map((entry) => unquote(entry.trim())).filter(Boolean);
-    const tools = parseList(meta.tools);
-    const skills = parseList(meta.skills);
-    const extensions = parseList(meta.extensions);
-    let extensionSettings: unknown;
-    if (meta.extensionSettings !== undefined) {
-      try { extensionSettings = JSON.parse(meta.extensionSettings) as unknown; }
-      catch (error) { fail("INVALID_METADATA", `Invalid role extensionSettings: ${errorText(error)}`); }
-    }
-    const rolePathValue = rolePath ?? "<role>";
-    const normalizedExtensionSettings = validateWorkflowExtensionSettings(extensionSettings, rolePathValue, "INVALID_METADATA", false);
-    const definition: AgentDefinition = { prompt: content.slice(end + 4).replace(/^\n/, "") };
-    if (meta.model) {
-      const model = unquote(meta.model);
-      assertModelThinking(model, "Role model");
-      definition.model = model;
-    }
-    if (meta.description) definition.description = unquote(meta.description);
-    if (tools) definition.tools = tools;
-    if (skills) definition.skills = skills;
-    if (extensions) definition.extensions = extensions;
-    if (normalizedExtensionSettings !== undefined) definition.extensionSettings = normalizedExtensionSettings;
-    const overrideSystemPrompt = meta.overrideSystemPrompt ?? meta.override_system_prompt ?? meta.is_system_prompt;
-    const contextFiles = meta.contextFiles ? meta.contextFiles.replace(/^\[|\]$/g, "").split(",").map((scope) => unquote(scope.trim())).filter(Boolean) : undefined;
-    const normalizedContextFiles = validateContextFileScopes(contextFiles, "role");
-    if (overrideSystemPrompt) definition.overrideSystemPrompt = overrideSystemPrompt === "true";
-    if (normalizedContextFiles) definition.contextFiles = normalizedContextFiles;
-    return definition;
-  }
-  const normalized = content.replace(/\r\n?/g, "\n");
-  if (normalized.startsWith("---\n") && normalized.indexOf("\n---", 3) < 0) fail("INVALID_METADATA", "Role frontmatter is missing its closing delimiter");
-  let parsed: ReturnType<typeof parseFrontmatter>;
-  try { parsed = parseFrontmatter(content); }
-  catch (error) { fail("INVALID_METADATA", `Invalid role frontmatter: ${errorText(error)}`); }
-  if (!object(parsed.frontmatter)) fail("INVALID_METADATA", "Role frontmatter must be an object");
-  const { model, tools, skills, extensions, extensionSettings, description, contextFiles } = parsed.frontmatter;
-  if (Object.prototype.hasOwnProperty.call(parsed.frontmatter, "disabledAgentResources")) fail("INVALID_METADATA", "disabledAgentResources is no longer supported; use skills, extensions, and tools selectors");
-  if (Object.prototype.hasOwnProperty.call(parsed.frontmatter, "thinking")) fail("INVALID_METADATA", "Role thinking is not supported; put it on model as provider/model:thinking");
-  const overrideSystemPrompt = parsed.frontmatter.overrideSystemPrompt ?? parsed.frontmatter.override_system_prompt ?? parsed.frontmatter.is_system_prompt;
-  if (model !== undefined && (typeof model !== "string" || model.trim() === "")) fail("INVALID_METADATA", "Role model must be a non-empty string");
-  if (description !== undefined && (typeof description !== "string" || description.trim() === "" || description.length > 1024 || /[\r\n]/.test(description))) fail("INVALID_METADATA", "Role description must be a non-empty single-line string of at most 1024 characters");
-  if (overrideSystemPrompt !== undefined && typeof overrideSystemPrompt !== "boolean") fail("INVALID_METADATA", "Role overrideSystemPrompt must be a boolean");
-  const normalizedContextFiles = validateContextFileScopes(contextFiles, rolePath ?? "<role>");
-  const rolePathValue = rolePath ?? "<role>";
-  const normalizedTools = validateSelectorList(tools, rolePathValue, "tools", "INVALID_METADATA");
-  const normalizedSkills = validateSelectorList(skills, rolePathValue, "skills", "INVALID_METADATA");
-  const normalizedExtensions = validateSelectorList(extensions, rolePathValue, "extensions", "INVALID_METADATA");
-  const normalizedExtensionSettings = validateWorkflowExtensionSettings(extensionSettings, rolePathValue, "INVALID_METADATA", false);
-  const normalizedDescription = typeof description === "string" ? description.trim() : undefined;
-  const normalizedModel = typeof model === "string" ? model.trim() : undefined;
-  if (normalizedModel !== undefined) assertModelThinking(normalizedModel, "Role model");
-  const definition: AgentDefinition = { prompt: parsed.body };
-  if (normalizedDescription !== undefined) definition.description = normalizedDescription;
-  if (normalizedModel !== undefined) definition.model = normalizedModel;
-  if (normalizedTools !== undefined) definition.tools = normalizedTools;
-  if (normalizedSkills !== undefined) definition.skills = normalizedSkills;
-  if (normalizedExtensions !== undefined) definition.extensions = normalizedExtensions;
-  if (normalizedExtensionSettings !== undefined) definition.extensionSettings = normalizedExtensionSettings;
-  if (typeof overrideSystemPrompt === "boolean") definition.overrideSystemPrompt = overrideSystemPrompt;
-  if (normalizedContextFiles !== undefined) definition.contextFiles = normalizedContextFiles;
-  return definition;
-}
-
-const ROLE_DIRECTORY = "pi-extensible-workflows";
-
-export function workflowRoleDirectories(agentDir = getAgentDir()): readonly string[] {
-  return [join(agentDir, ROLE_DIRECTORY, "roles")];
-}
-
-function projectRoleDirectories(root: string): readonly string[] {
-  return [join(root, ROLE_DIRECTORY, "roles")];
-}
-
-type RoleDirectorySource = { path: string; extension?: WorkflowExtensionMetadata; builtin?: true };
-export type WorkflowRoleDirectoryInput = string | WorkflowRoleDirectoryRegistration;
-type RoleFile = { name: string; path: string; source: RoleDirectorySource };
-function roleDirectorySources(dirs: readonly WorkflowRoleDirectoryInput[]): RoleDirectorySource[] {
-  const seen = new Set<string>();
-  return dirs.flatMap((value) => {
-    const source = typeof value === "string" ? { path: value } : { path: value.path, extension: value.extension, ...(value.builtin === true ? { builtin: true as const } : {}) };
-    if (seen.has(source.path)) return [];
-    seen.add(source.path);
-    return [source];
-  });
-}
-function roleDirectoryLabel(source: RoleDirectorySource, extension = true): string {
-  return source.extension ? `Extension "${source.extension.headline}" (${source.extension.version})` : extension ? "Registered workflow extension" : "Standard workflow";
-}
-function isRoleFile(dir: string, entry: import("node:fs").Dirent): boolean {
-  if (extname(entry.name) !== ".md") return false;
-  if (entry.isFile()) return true;
-  if (!entry.isSymbolicLink()) return false;
-  try { return statSync(join(dir, entry.name)).isFile(); }
-  catch (error) { if (isNodeError(error, "ENOENT")) return false; throw error; }
-}
-function scanRoleFiles(dirs: readonly WorkflowRoleDirectoryInput[], extension: boolean): RoleFile[] {
-  const files: RoleFile[] = [];
-  for (const source of roleDirectorySources(dirs)) {
-    let entries: import("node:fs").Dirent[];
-    try { entries = readdirSync(source.path, { withFileTypes: true }); }
-    catch (error) {
-      if (!extension && isNodeError(error, "ENOENT")) continue;
-      fail("INVALID_METADATA", `${roleDirectoryLabel(source, extension)} role directory "${source.path}" could not be scanned: ${errorText(error)}`);
-    }
-    for (const entry of entries) if (isRoleFile(source.path, entry)) files.push({ name: basename(entry.name, ".md"), path: join(source.path, entry.name), source });
-  }
-  return files.sort((left, right) => left.name.localeCompare(right.name) || left.path.localeCompare(right.path));
-}
-function readRoleDefinitions(dirs: readonly WorkflowRoleDirectoryInput[], extension = false): Record<string, AgentDefinition> {
-  const files = scanRoleFiles(dirs, extension);
-  const starterFiles = files.filter(({ source }) => source.builtin === true);
-  const regularFiles = files.filter(({ source }) => source.builtin !== true);
-  if (extension) {
-    const byName = new Map<string, RoleFile[]>();
-    for (const file of regularFiles) byName.set(file.name, [...(byName.get(file.name) ?? []), file]);
-    for (const [name, matches] of byName) if (matches.length > 1) fail("INVALID_METADATA", `Duplicate extension role "${name}": ${matches.map(({ path, source }) => `${roleDirectoryLabel(source)} role directory "${source.path}" (${path})`).join("; ")}`);
-  }
-  const read = (roleFiles: readonly RoleFile[]): Record<string, AgentDefinition> => Object.fromEntries(roleFiles.map(({ name, path, source }) => {
-    try { return [name, parseRoleMarkdown(readFileSync(path, "utf8"), true, path)]; }
-    catch (error) {
-      if (extension) fail("INVALID_METADATA", `${roleDirectoryLabel(source)} role directory "${source.path}" contains invalid role "${name}" at "${path}": ${errorText(error)}`);
-      throw error;
-    }
-  }));
-  return extension ? { ...read(starterFiles), ...read(regularFiles) } : read(files);
-}
-export function loadProjectAgentDefinitions(cwd: string): Readonly<Record<string, AgentDefinition>> { return readRoleDefinitions(projectRoleDirectories(join(cwd, ".pi"))); }
-export function loadAgentDefinitions(cwd: string, agentDir = getAgentDir(), projectTrusted = true, extensionRoleDirectories: readonly WorkflowRoleDirectoryInput[] = registeredWorkflowRoleDirectoryRegistrations()): Readonly<Record<string, AgentDefinition>> {
-  return deepFreeze({ ...readRoleDefinitions(extensionRoleDirectories, true), ...readRoleDefinitions(workflowRoleDirectories(agentDir)), ...(projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(cwd, ".pi"))) : {}) });
-}
 function validateRolePolicies(definitions: Readonly<Record<string, AgentDefinition>>, roles: readonly string[], availableModels: ReadonlySet<string>, aliases: Readonly<Record<string, string>> = {}, knownModels = availableModels, settingsPath?: string): void {
   for (const role of roles) {
     const definition = definitions[role];
@@ -556,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;
@@ -628,13 +309,6 @@ export function workflowPrompt(template: string, values: Readonly<Record<string,
   });
 }
 
-export function validateSchema(schema: unknown, at = "schema"): asserts schema is JsonSchema {
-  if (!object(schema) || Object.getPrototypeOf(schema) !== Object.prototype || !jsonValue(schema)) fail("INVALID_SCHEMA", `${at} must be a plain JSON-compatible Schema object`);
-  if (typeof schema.type !== "string" && !Array.isArray(schema.type) && schema.$ref === undefined && schema.anyOf === undefined && schema.oneOf === undefined && schema.allOf === undefined && schema.const === undefined && schema.enum === undefined) fail("INVALID_SCHEMA", `${at} has no JSON Schema shape`);
-  if (schema.required !== undefined && (!Array.isArray(schema.required) || schema.required.some((key) => typeof key !== "string"))) fail("INVALID_SCHEMA", `${at}.required must be an array of strings`);
-  if (schema.properties !== undefined && !object(schema.properties)) fail("INVALID_SCHEMA", `${at}.properties must be an object`);
-}
-
 const AGENT_OPTION_KEYS = new Set(["label", "model", "tools", "skills", "extensions", "contextFiles", "role", "outputSchema", "retries", "timeoutMs"]);
 function validateAgentOption(key: string, value: unknown, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): void {
   switch (key) {

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

@@ -44,7 +44,7 @@ subagents_run({ prompt: "Summarize README.md.", mode: "foreground" })
 
 ## Interactive inspection
 
-In Pi's TUI, `/subagents` opens a picker of durable standalone runs for the current session. Select a run to inspect the same activity, stall warning, state, model, role, tools, attempts, duration, cumulative token accounting, cost, and error fields used by `/workflow`; prompt, request failure, and result details remain bounded, and requests without a role remain `role=none`. The detail view also exposes registered standalone agent actions plus `Steer` and `Stop` while running, `Retry` for failed or stopped runs, and copy/editor controls where applicable. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, or retry a run.
+In Pi's TUI, `/subagents` opens the `/workflow` dashboard layout for the durable standalone runs of the current session: the run list sits beside the selected run's details at 80 columns or wider, and narrower terminals drill down from the list to the details. The details show the run ID and the same activity, stall warning, state, model, role, tools, attempts, duration, cumulative token accounting, cost, and error fields as a `/workflow` agent; a running run shows its live activity, which `subagents_inspect` leaves out. Requests without a role show `Role: (none)`. While a run is active the view refreshes the active runs and the selection every second; runs launched while it is open appear after an action or when it reopens. `a` or `enter` opens registered standalone agent actions, editor controls for the prompt, the live system prompt, and the result, `Steer` and `Stop` while running, `Retry` for failed or stopped runs, and the `/workflow` run actions that apply: `Delete`, `Delete all completed`, `Delete all failed`, `Copy run path`, and `Copy agent ID`. Stop and every deletion ask for confirmation, and a run whose worktree still awaits cleanup cannot be deleted. Outside the TUI, `/subagents` opens a picker with the same run summary and bulk deletions as the `/workflow` picker. Background runs appear below the editor in the workflow widget's frame, one row per run with its model, tokens, cost, elapsed time, and quiet or stalled warning, and each leaves a receipt in the transcript when it settles. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, retry, or delete a run.
 
 ## Tools
 
@@ -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 {
@@ -114,6 +125,8 @@ export interface SubagentManagerContext {
   readonly extensionContext: ExtensionContext;
   readonly waitForForeground?: boolean;
   readonly includeAttemptMetadata?: boolean;
+  /** Adds the live progress and activity of an active run; tool results leave streamed activity out. */
+  readonly includeActivity?: boolean;
 }
 export interface SubagentAttemptActionData {
   readonly attempt: AgentAttemptSummary;
@@ -160,6 +173,8 @@ export interface SubagentManager {
   steer(request: Readonly<SubagentSteerRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
   stop(request: Readonly<SubagentIdRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
   retry(request: Readonly<SubagentIdRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
+  /** Removes a settled run record; used by the /subagents navigator only. */
+  delete?(request: Readonly<SubagentIdRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
   getAttemptActionData?(id: string): Readonly<SubagentAttemptActionData> | undefined;
   dispose?(): Promise<void>;
 }

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">>;
+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 });
@@ -170,9 +179,11 @@ export function registerSubagentsExtension(pi: SubagentsExtensionAPI, options: S
   const onResourceWarning = sendMessage === undefined ? undefined : (message: string): void => {
     sendMessage.call(pi, { customType: "subagents", content: `Warning: ${message}`, display: true }, { deliverAs: "steer" });
   };
-  const widget = createSubagentBackgroundWidget();
+  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);