@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.9

package/src/workflow/progress.ts

@@ -20,6 +20,7 @@
  * unit-testable without a terminal.
  */
 
+import type { TierDisclosure } from "../model-tiers.js";
 import type { WorkflowMeta, WorkflowPhaseMeta } from "./meta.js";
 
 /** Raw entry lifecycle, as written by the runtime. */
@@ -93,6 +94,9 @@ export interface WorkflowAgentEntry {
    * it.
    */
   requestedThinking?: string;
+  /** `Note:` line set when the child ran on the parent model because its configured one did not resolve. */
+  modelNote?: string;
+  modelTier?: TierDisclosure;
   fallbackModel?: string;
   isolation?: "worktree";
   error?: string;
@@ -510,11 +514,12 @@ export function gerund(word: string): string {
 
   // Short consonant-vowel-consonant words double the final consonant: run →
   // running. `w`, `x` and `y` never double.
-  const last = lower.at(-1) ?? "";
+  // GERUND_CANDIDATE guarantees at least three letters, so every index exists.
+  const last = lower[lower.length - 1];
   if (
     lower.length <= 4 &&
-    !VOWELS.includes(lower.at(-3) ?? "") &&
-    VOWELS.includes(lower.at(-2) ?? "") &&
+    !VOWELS.includes(lower[lower.length - 3]) &&
+    VOWELS.includes(lower[lower.length - 2]) &&
     !VOWELS.includes(last) &&
     !"wxy".includes(last)
   ) {

package/src/workflow/runtime.ts

@@ -15,6 +15,7 @@
 
 import { cpus } from "node:os";
 import { Worker } from "node:worker_threads";
+import type { TierDisclosure } from "../model-tiers.js";
 import { type JournalKeyInput, journalKey, type WorkflowJournalEntry } from "./journal.js";
 import { type CompiledSchema, compileJsonSchema } from "./json-schema.js";
 import { extractMeta, type WorkflowMeta } from "./meta.js";
@@ -95,6 +96,9 @@ export interface WorkflowSpawnRequest {
     modelId?: string;
     thinking?: string;
     requestedThinking?: string;
+    /** `Note:` line when the child ran on the parent model because its configured one did not resolve. */
+    modelNote?: string;
+    modelTier?: TierDisclosure;
   }): void;
   /**
    * Compiled from the script's `agent({ schema })`.
@@ -125,6 +129,9 @@ export interface WorkflowSpawnResult {
   text?: string;
   /** Why it failed. Present when not `ok`. */
   error?: string;
+  /** `Note:` line when the child ran on a different model than configured; also leads `text`/`error` (not a schema'd payload). */
+  modelNote?: string;
+  modelTier?: TierDisclosure;
   /** The user dismissed it rather than it failing; renders as skipped. */
   skipped?: boolean;
   tokens?: number;
@@ -146,8 +153,8 @@ export interface WorkflowSpawnResult {
    * verifies the wrong working copy. Left unset, a gate runs wherever the host
    * runs commands by default.
    *
-   * Usually unset for a worktree child even so: the copy is removed during the
-   * child's own settle, so it no longer exists by the time this is read. That
+   * Usually unset for a worktree child even so: the copy is normally removed during
+   * the child's own settle, so it no longer exists by the time this is read. That
    * is what {@link gate} is for.
    */
   cwd?: string;
@@ -275,6 +282,19 @@ export interface RunWorkflowOptions {
   signal?: AbortSignal;
   /** Fired per batch, not per entry — see the worker's progress batching. */
   onProgress?(entries: readonly WorkflowEntry[]): void;
+  /**
+   * Receives optional Istanbul counters authored inside a workflow VM.
+   *
+   * The runtime itself never instruments scripts. Test producers may pass
+   * instrumented source and merge these counters into their own collector,
+   * retaining worker/VM execution rather than measuring a substitute runner.
+   */
+  onScriptCoverage?(coverage: unknown): void;
+  /**
+   * Trusted caller-side transform applied after the workflow's metadata has
+   * passed validation and before its body enters the worker VM.
+   */
+  transformScriptBody?(input: { script: string; body: string }): string;
   concurrency?: number;
   agentCap?: number;
   itemCap?: number;
@@ -315,6 +335,8 @@ export interface WorkflowRunResult {
   /** The script's return value, JSON-checked at the boundary. */
   value?: unknown;
   error?: string;
+  /** Authored-source stack, kept separately from the concise failure message. */
+  errorStack?: string;
   /** The append-only log, in emission order. */
   progress: WorkflowEntry[];
   /** Agents scheduled, including those that failed. */
@@ -348,7 +370,8 @@ function walk(value: unknown, path: string, seen: Set<object>): void {
   if (kind === "bigint") throw boundaryError("a BigInt", path);
   if (kind === "symbol") throw boundaryError("a symbol", path);
   if (kind === "function") throw boundaryError("a function", path);
-  if (kind !== "object") throw boundaryError(`a ${kind}`, path);
+  // Every other `typeof` result is handled above; a new one fails `tsc` here.
+  kind satisfies "object";
 
   const object = value as object;
   if (seen.has(object)) throw boundaryError("a circular structure", path);
@@ -448,7 +471,7 @@ interface AgentCallPayload {
 type WorkerMessage =
   | { type: "call"; callId: number; method: string; payload: AgentCallPayload }
   | { type: "progress"; entries: WorkflowEntry[] }
-  | { type: "complete"; resultJson?: string }
+  | { type: "complete"; resultJson?: string; coverage?: unknown }
   | { type: "error"; message: string; stack?: string };
 
 /** Everything below 0x20 except tab, newline and carriage return, plus DEL. */
@@ -586,7 +609,8 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
 
   assertBoundarySafe(options.args, "args");
 
-  const { meta, body } = validateScript(script);
+  const { meta, body: validatedBody } = validateScript(script);
+  const body = options.transformScriptBody?.({ script, body: validatedBody }) ?? validatedBody;
   const agentCap = options.agentCap ?? WORKFLOW_AGENT_CAP;
   const itemCap = options.itemCap ?? WORKFLOW_ITEM_CAP;
   const semaphore = new Semaphore(options.concurrency ?? workflowConcurrency());
@@ -723,24 +747,24 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
       argsJson: options.args === undefined ? undefined : JSON.stringify(options.args),
       itemCap,
       nestedCap: options.nestedCap ?? WORKFLOW_NESTED_CAP,
+      collectCoverage: options.onScriptCoverage !== undefined,
     },
   });
 
   return await new Promise<WorkflowRunResult>(resolve => {
     const emit = (entries: WorkflowEntry[]) => {
-      if (entries.length === 0) return;
       progress.push(...entries);
       options.onProgress?.(entries);
     };
 
-    const respond = (callId: number, ok: boolean, value?: unknown, error?: string, fatal?: boolean) => {
+    const respond = (callId: number, ok: boolean, value?: unknown, error?: string, fatal?: boolean, modelNote?: string) => {
       // Cleared before the settled check: a launch answered by a run that is
       // already finishing is not an unawaited launch either.
       openLaunches.delete(callId);
       if (settled) return;
       // `spent` rides on every response, so the worker's `budget.spent()` is a
       // mirror of this number rather than a second tally of its own.
-      worker.postMessage({ type: "response", callId, ok, value, error, fatal, spent: spentOutputTokens });
+      worker.postMessage({ type: "response", callId, ok, value, error, fatal, modelNote, spent: spentOutputTokens });
     };
 
     const finish = (result: Omit<WorkflowRunResult, "meta" | "progress" | "agentCount" | "replayedCount">) => {
@@ -908,6 +932,8 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
             // dialog to annotate it "from resume journal" rather than letting a
             // 0ms agent look like one that did the work impossibly fast.
             cached: true,
+            ...(replayed.modelNote !== undefined ? { modelNote: replayed.modelNote } : {}),
+            ...(replayed.modelTier ? { modelTier: replayed.modelTier } : {}),
             resultPreview: preview(replayedText),
           },
         ]);
@@ -915,8 +941,8 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
         // Re-recorded so this run's journal is complete on its own terms: a
         // resume of a resume must not have to walk back through a chain of
         // earlier files to find the prefix.
-        recordJournal?.({ index, key: replayed.key, ok: true, text: replayedText });
-        respond(callId, true, replayedText);
+        recordJournal?.({ index, key: replayed.key, ok: true, text: replayedText, ...(replayed.modelNote !== undefined ? { modelNote: replayed.modelNote } : {}), ...(replayed.modelTier ? { modelTier: replayed.modelTier } : {}) });
+        respond(callId, true, replayedText, undefined, undefined, replayed.modelNote);
         return;
       }
 
@@ -992,12 +1018,16 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
             modelId?: string;
             thinking?: string;
             requestedThinking?: string;
+            modelNote?: string;
+            modelTier?: TierDisclosure;
           }) => {
             if (info.recordId !== undefined) base.recordId = info.recordId;
             if (info.modelName !== undefined) base.model = info.modelName;
             if (info.modelId !== undefined) base.modelId = info.modelId;
             if (info.thinking !== undefined) base.thinking = info.thinking;
             if (info.requestedThinking !== undefined) base.requestedThinking = info.requestedThinking;
+            if (info.modelNote !== undefined) base.modelNote = info.modelNote;
+            if (info.modelTier !== undefined) base.modelTier = info.modelTier;
             // `base.state` is still "start", so emitting after the row reached a
             // terminal state would revert it to running under last-write-wins.
             // Not reachable from this repo's host, which reports during startup
@@ -1091,13 +1121,15 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
             durationMs: finishedAt - startedAt,
             ...(result.tokens !== undefined ? { tokens: result.tokens } : {}),
             ...(result.toolCalls !== undefined ? { toolCalls: result.toolCalls } : {}),
+            ...(result.modelNote !== undefined ? { modelNote: result.modelNote } : {}),
+            ...(result.modelTier ? { modelTier: result.modelTier } : {}),
           };
 
           if (result.ok) {
             const text = result.text ?? "";
             emit([{ ...common, state: "done", resultPreview: preview(text) }]);
-            recordJournal?.({ index, key, ok: true, text, ...resumeMark });
-            respond(callId, true, text);
+            recordJournal?.({ index, key, ok: true, text, ...(result.modelNote !== undefined ? { modelNote: result.modelNote } : {}), ...(result.modelTier ? { modelTier: result.modelTier } : {}), ...resumeMark });
+            respond(callId, true, text, undefined, undefined, result.modelNote);
             return;
           }
           // Recorded as a failure rather than left out: a gap would be read as an
@@ -1118,7 +1150,7 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
               ...(result.skipped ? { skipped: true } : {}),
             },
           ]);
-          respond(callId, true, null);
+          respond(callId, true, null, undefined, undefined, result.modelNote);
           return;
         }
       } finally {
@@ -1157,7 +1189,7 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
         respond(callId, true, {
           name: child.meta.name,
           metaJson: JSON.stringify(child.meta),
-          body: child.body,
+          body: options.transformScriptBody?.({ script: source.script, body: child.body }) ?? child.body,
         });
       } catch (error) {
         respond(callId, false, undefined, error instanceof Error ? error.message : String(error));
@@ -1182,6 +1214,7 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
           void handleAgent(message.callId, message.payload as AgentCallPayload);
           break;
         case "complete": {
+          if (message.coverage !== undefined) options.onScriptCoverage?.(message.coverage);
           // The script is done, so every launch it made should have been
           // answered by now — a response is sent before the worker can post
           // this, so anything still open was never awaited. finish() aborts
@@ -1198,7 +1231,7 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
           break;
         }
         case "error":
-          finish({ status: "failed", error: message.message });
+          finish({ status: "failed", error: message.message, errorStack: message.stack });
           break;
       }
     });

package/src/workflow/saved.ts

@@ -39,7 +39,7 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveAgentDir } from "../home-paths.js";
 import { isSymlink, isUnsafeName, safeReadFile } from "../memory.js";
 import { isPackageResourceExcluded, packageWorkflowDirs, packageWorkflowFiles } from "../package-resources.js";
 import { hasMetaDeclaration } from "./meta.js";
@@ -61,12 +61,12 @@ const WORKFLOW_EXTENSION = ".js";
  * reaches this without an options bag travelling through `resolveWorkflowScript`,
  * `resolveWorkflowSource` and `readSavedWorkflow` purely to be consulted once.
  */
-export function savedWorkflowRoots(cwd: string): string[] {
+export function savedWorkflowRoots(cwd: string, homeDir?: string): string[] {
   return [
     join(cwd, ".pi", "workflows"),
     join(cwd, ".agents", "workflows"),
-    join(getAgentDir(), "workflows"),
-    ...packageWorkflowDirs(cwd),
+    join(resolveAgentDir(homeDir), "workflows"),
+    ...packageWorkflowDirs(cwd, { homeDir }),
   ];
 }
 
@@ -81,7 +81,7 @@ export type SavedWorkflow =
  * names that do exist — a model that guessed the name can correct itself from
  * the error instead of spending a turn asking.
  */
-export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
+export function readSavedWorkflow(name: string, cwd: string, homeDir?: string): SavedWorkflow {
   const trimmed = name.trim();
   if (isUnsafeName(trimmed)) {
     return {
@@ -92,13 +92,13 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
     };
   }
 
-  const roots = savedWorkflowRoots(cwd);
+  const roots = savedWorkflowRoots(cwd, homeDir);
   for (const root of roots) {
     if (isSymlink(root)) continue; // reject a symlinked root entirely, as skill-loader does
     const path = join(root, `${trimmed}${WORKFLOW_EXTENSION}`);
     // A `!` entry in the declaring package's manifest. Only ever true for a path
     // under a package root, so the local roots pay one set lookup for it.
-    if (isPackageResourceExcluded(path, cwd, "workflows")) continue;
+    if (isPackageResourceExcluded(path, cwd, "workflows", { homeDir })) continue;
     const script = safeReadFile(path);
     if (script === undefined) continue;
     // Found the file, so stop looking — a shadowing name that turns out not to
@@ -117,7 +117,7 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
   // Last: a package that declared an individual file rather than a directory.
   // It carries no root to look a name up in, so it is matched by name here
   // instead — after every root, which keeps package scripts lowest-precedence.
-  const declared = packageWorkflowFiles(cwd).get(trimmed);
+  const declared = packageWorkflowFiles(cwd, { homeDir }).get(trimmed);
   if (declared !== undefined) {
     const script = safeReadFile(declared);
     if (script !== undefined) {
@@ -133,7 +133,7 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
     }
   }
 
-  const known = listSavedWorkflows(cwd);
+  const known = listSavedWorkflows(cwd, homeDir);
   return {
     ok: false,
     message:
@@ -154,6 +154,7 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
 export function resolveWorkflowSource(
   ref: { name?: string; scriptPath?: string },
   cwd: string,
+  homeDir?: string,
 ): SavedWorkflow {
   const path = ref.scriptPath?.trim();
   if (path !== undefined && path !== "") {
@@ -161,21 +162,19 @@ export function resolveWorkflowSource(
     try {
       return { ok: true, script: readFileSync(resolved, "utf-8"), path: resolved };
     } catch (err) {
-      return {
-        ok: false,
-        message: `Could not read workflow script "${resolved}": ${err instanceof Error ? err.message : String(err)}`,
-      };
+      // `readFileSync` only ever throws Node's own `Error`s.
+      return { ok: false, message: `Could not read workflow script "${resolved}": ${(err as Error).message}` };
     }
   }
   const name = ref.name?.trim();
-  if (name !== undefined && name !== "") return readSavedWorkflow(name, cwd);
+  if (name !== undefined && name !== "") return readSavedWorkflow(name, cwd, homeDir);
   return { ok: false, message: "A workflow reference needs a `name` or a `scriptPath`." };
 }
 
 /** Every saved workflow name, de-duplicated across roots and sorted. */
-export function listSavedWorkflows(cwd: string): string[] {
+export function listSavedWorkflows(cwd: string, homeDir?: string): string[] {
   const names = new Set<string>();
-  for (const root of savedWorkflowRoots(cwd)) {
+  for (const root of savedWorkflowRoots(cwd, homeDir)) {
     if (!existsSync(root) || isSymlink(root)) continue;
     let entries: string[];
     try {
@@ -188,11 +187,11 @@ export function listSavedWorkflows(cwd: string): string[] {
       const name = entry.slice(0, -WORKFLOW_EXTENSION.length);
       if (isUnsafeName(name)) continue;
       const path = join(root, entry);
-      if (isPackageResourceExcluded(path, cwd, "workflows")) continue;
+      if (isPackageResourceExcluded(path, cwd, "workflows", { homeDir })) continue;
       if (isWorkflowFile(path)) names.add(name);
     }
   }
-  for (const [name, path] of packageWorkflowFiles(cwd)) {
+  for (const [name, path] of packageWorkflowFiles(cwd, { homeDir })) {
     if (isUnsafeName(name)) continue;
     if (isWorkflowFile(path)) names.add(name);
   }
@@ -228,10 +227,11 @@ function isWorkflowFile(path: string): boolean {
 export function resolveWorkflowScript(
   params: { script?: string; scriptPath?: string; name?: string },
   cwd: string,
+  homeDir?: string,
 ): { ok: true; script: string; scriptPath?: string } | { ok: false; message: string } {
   const path = params.scriptPath?.trim();
   if (path !== undefined && path !== "") {
-    const resolved = resolveWorkflowSource({ scriptPath: path }, cwd);
+    const resolved = resolveWorkflowSource({ scriptPath: path }, cwd, homeDir);
     return resolved.ok ? { ok: true, script: resolved.script, scriptPath: resolved.path } : resolved;
   }
   const script = params.script;
@@ -244,11 +244,11 @@ export function resolveWorkflowScript(
   // reference means.
   const name = params.name?.trim();
   if (name !== undefined && name !== "") {
-    const saved = resolveWorkflowSource({ name }, cwd);
+    const saved = resolveWorkflowSource({ name }, cwd, homeDir);
     return saved.ok ? { ok: true, script: saved.script, scriptPath: saved.path } : saved;
   }
 
-  const known = listSavedWorkflows(cwd);
+  const known = listSavedWorkflows(cwd, homeDir);
   return {
     ok: false,
     message:

package/src/workflow/task.ts

@@ -78,6 +78,8 @@ export interface WorkflowTask {
   logs: string[];
 
   abortController: AbortController;
+  /** Set when the parent stopped the run with `stop_subagent`; unset for a human stop. */
+  stoppedBy?: "parent";
   startTime: number;
   endTime?: number;
   /** Excluded from the elapsed clock the header shows. */
@@ -86,6 +88,8 @@ export interface WorkflowTask {
   /** The script's return value, once the run produced one. */
   value?: unknown;
   error?: string;
+  /** Full authored stack for the result; the compact status keeps only error. */
+  errorStack?: string;
 }
 
 export function createWorkflowTask(init: {
@@ -182,19 +186,22 @@ export function resumeWorkflowTask(task: WorkflowTask, now = Date.now()): boolea
   if (task.status !== "paused" || task.control === undefined) return false;
   task.control.resume();
   task.status = "running";
-  task.totalPausedMs = (task.totalPausedMs ?? 0) + Math.max(0, now - (task.pausedAt ?? now));
-  task.pausedAt = undefined;
+  bankPause(task, now);
   return true;
 }
 
+/** Close out an open pause into `totalPausedMs`; a no-op when the run is not held. */
+function bankPause(task: WorkflowTask, now: number): void {
+  if (task.pausedAt === undefined) return;
+  task.totalPausedMs += Math.max(0, now - task.pausedAt);
+  task.pausedAt = undefined;
+}
+
 /** Settle a task from the run's own result. */
 export function completeWorkflowTask(task: WorkflowTask, result: WorkflowRunResult): void {
   // Banked before the status moves off "paused": a run that finished while held
   // still spent that time held, and the elapsed figure has to say so.
-  if (task.pausedAt !== undefined) {
-    task.totalPausedMs = (task.totalPausedMs ?? 0) + Math.max(0, Date.now() - task.pausedAt);
-    task.pausedAt = undefined;
-  }
+  bankPause(task, Date.now());
   // Nothing left to control, and holding the handle would let the dialog offer
   // pause on a run that has already stopped.
   task.control = undefined;
@@ -205,6 +212,7 @@ export function completeWorkflowTask(task: WorkflowTask, result: WorkflowRunResu
   task.replayedCount = result.replayedCount;
   task.value = result.value;
   task.error = result.error;
+  task.errorStack = result.errorStack;
   task.endTime = Date.now();
 }
 
@@ -222,6 +230,13 @@ export function failWorkflowTask(task: WorkflowTask, error: string): void {
 
 /** The run's outcome as text, for the notification and the LLM-facing result. */
 export function workflowResultText(task: WorkflowTask): string {
+  if (task.errorStack !== undefined) {
+    const stack = task.errorStack.slice(0, 16384);
+    const firstLine = stack.split("\n", 1)[0];
+    const message = task.error;
+    if (message === undefined || message === "" || firstLine === message || firstLine.endsWith(`: ${message}`)) return stack;
+    return `${message}\n${stack}`;
+  }
   if (task.error !== undefined) return task.error;
   if (task.value === undefined) return "No output.";
   if (typeof task.value === "string") return task.value;
@@ -283,7 +298,7 @@ export function formatWorkflowNotification(task: WorkflowTask, now = Date.now())
   const totals = stats(task.workflowProgress, task.agentCount);
   const status =
     task.status === "completed" ? "Done"
-    : task.status === "killed" ? "Stopped"
+    : task.status === "killed" ? (task.stoppedBy === "parent" ? "Stopped by the parent with stop_subagent" : "Stopped")
     : `Error: ${task.error ?? "unknown"}`;
   const result = workflowResultText(task);
   return [

package/src/workflow/tool-description.ts

@@ -19,7 +19,7 @@
  *   - `budget.total` is always null; pi has no token-target directive.
  *   - `parallel` propagates a fatal run error instead of folding it to null.
  *   - `effort` inherits the agent definition's level, then the parent's.
- *   - `isolation` removes the worktree on settle, changes kept on a branch.
+ *   - `isolation` removes the worktree on settle (kept if cleanup fails), changes kept on a branch.
  * Additions with no upstream counterpart: `gate`, `resume`, `effort: "minimal"`,
  * the saved-workflow directories, and the reject-unknown-options guarantee.
  *
@@ -77,7 +77,7 @@ Every script must begin with \`export const meta = {...}\`:
 The \`meta\` object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation. Required fields: \`name\`, \`description\`. Optional: \`whenToUse\` (shown in the workflow list), \`phases\`. Use the SAME phase titles in meta.phases as in phase() calls — titles are matched exactly; a phase() call with no matching meta entry just gets its own progress group. Add \`model\` to a phase entry when that phase uses a specific model override.
 
 Script body hooks:
-- agent(prompt: string, opts?: {label?: string, phase?: string, schema?: object, model?: string, effort?: string, isolation?: 'worktree', agentType?: string, gate?: string, resume?: string}): Promise<any> — spawn a subagent. Without schema, returns its final text as a string. With schema (a JSON Schema), the subagent is given a StructuredOutput tool built from it and agent() returns the validated object — no parsing needed. A payload that does not match is rejected back to the child, which corrects it; a child that never answers through the tool gets one more prompt and then fails, so the call returns null — filter after every schema stage. Returns null if the user skips the agent mid-run or the subagent dies on a terminal API error after retries (filter with .filter(Boolean)). opts.label overrides the display label. opts.phase explicitly assigns this agent to a progress group (use this inside pipeline()/parallel() stages to avoid races on the global phase() state — same phase string → same group box). opts.model overrides the model for this agent call. Default to omitting it — the agent inherits the main-loop model (the resolved session model), which is almost always correct. Only set it when you're highly confident a different tier fits the task; when unsure, omit. opts.effort overrides the reasoning effort for this agent call ('minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max') — omit to inherit the agent definition's own level, then the parent's; use 'low' for cheap mechanical stages and higher tiers only for the hardest verify/judge stages. opts.isolation: 'worktree' runs the agent in a fresh git worktree — EXPENSIVE (setup time + disk per agent), use ONLY when agents mutate files in parallel and would otherwise conflict; the worktree is removed when the agent settles, its changes preserved on a branch. opts.gate: '<command>' runs a shell command after the agent finishes and requires it to pass — a non-zero exit marks the agent failed and the command's output becomes the error; prefer gate: 'npm test' over asking another agent whether the code looks right. opts.resume: '<label>' continues the child that ran under that label instead of starting fresh, so an iterative loop keeps its context — it cannot be combined with agentType, model, effort, isolation, gate or schema. opts.agentType uses a custom subagent type instead of the default workflow subagent — resolved from the same registry as the Agent tool; composes with schema. Available types:
+- agent(prompt: string, opts?: {label?: string, phase?: string, schema?: object, model?: string, effort?: string, isolation?: 'worktree', agentType?: string, gate?: string, resume?: string}): Promise<any> — spawn a subagent. Without schema, returns its final text as a string. With schema (a JSON Schema), the subagent is given a StructuredOutput tool built from it and agent() returns the validated object — no parsing needed. A payload that does not match is rejected back to the child, which corrects it; a child that never answers through the tool gets one more prompt and then fails, so the call returns null — filter after every schema stage. Returns null if the user skips the agent mid-run or the subagent dies on a terminal API error after retries (filter with .filter(Boolean)). opts.label overrides the display label. opts.phase explicitly assigns this agent to a progress group (use this inside pipeline()/parallel() stages to avoid races on the global phase() state — same phase string → same group box). opts.model overrides the model for this agent call. Default to omitting it so the configured selection policy applies: agentModels for the type, then agentModels["*"], then the agent definition, then the parent model. Only set it when you're highly confident a different tier fits the task; when unsure, omit. opts.effort overrides the reasoning effort for this agent call ('minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max') — omit to inherit the agent definition's own level, then the parent's; use 'low' for cheap mechanical stages and higher tiers only for the hardest verify/judge stages. opts.isolation: 'worktree' runs the agent in a fresh git worktree — EXPENSIVE (setup time + disk per agent), use ONLY when agents mutate files in parallel and would otherwise conflict; the worktree is removed when the agent settles, its changes preserved on a branch; if cleanup fails the worktree is kept and the agent errors. opts.gate: '<command>' runs a shell command after the agent finishes and requires it to pass — a non-zero exit marks the agent failed, returns null to the script, and records the command output on the workflow agent error; prefer gate: 'npm test' over asking another agent whether the code looks right. opts.resume: '<label>' continues the child that ran under that label instead of starting fresh, so an iterative loop keeps its context — it cannot be combined with agentType, model, effort, isolation, gate or schema. opts.agentType uses a custom subagent type instead of the default workflow subagent — resolved from the same registry as the Agent tool; composes with schema. Available types:
 {{typeList}}
 - pipeline(items, stage1, stage2, ...): Promise<any[]> — run each item through all stages independently, NO barrier between stages. Item A can be in stage 3 while item B is still in stage 1. This is the DEFAULT for multi-stage work. Wall-clock = slowest single-item chain, not sum-of-slowest-per-stage. Every stage callback receives (prevResult, originalItem, index) — use originalItem/index in later stages to label work without threading context through stage 1's return value. A stage that throws drops that item to \`null\` and skips its remaining stages.
 - parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — run tasks concurrently. This is a BARRIER: awaits all thunks before returning. A thunk that throws (or whose agent errors) resolves to \`null\` in the result array, so \`.filter(Boolean)\` before using the results; only a fatal run error — a cap breach, or a nested workflow that could not load — propagates instead of being folded into a null. Use ONLY when you genuinely need all results together.