pi-extensible-workflows 3.1.0 → 3.3.0

package/evals/cases/recovery-completed-worktree.yaml

@@ -0,0 +1,17 @@
+id: recovery-completed-worktree
+prompt: >-
+  The completed workflow run ID is "completed-run-42". You need a new workflow to do named worktree work,
+  so launch the workflow with exactly parentRunId "completed-run-42". Use exactly the workflow arguments {"name":"borrow-worktree","script":"return true;","parentRunId":"completed-run-42"}.
+  Do not call workflow_retry because the source is completed and parentRunId only borrows the named worktree; it does not replay or resume.
+maxCost: 0.1
+expectations:
+  firstTool: workflow
+  firstBatchToolSequence:
+    startsWith: [workflow]
+  parentToolSequence:
+    startsWith: [workflow]
+  workflowCallCount: 1
+expectedWorkflowCalls: 1
+semanticCriteria:
+  - id: parent-run-id
+    description: The captured workflow call has exactly name borrow-worktree, script return true;, and parentRunId completed-run-42; it does not call workflow_retry.

package/evals/cases/recovery-failed-run.yaml

@@ -0,0 +1,14 @@
+id: recovery-failed-run
+prompt: >-
+  A workflow failure diagnostic identifies the persisted failed run ID "failed-run-42" and says the exact next action is
+  workflow_retry({ runId: "failed-run-42" }). Select that recovery tool now with exactly {"runId":"failed-run-42"}.
+  Do not launch a new workflow, use parentRunId, or answer with prose.
+maxCost: 0.1
+expectedWorkflowCalls: 0
+expectations:
+  firstTool: workflow_retry
+  firstBatchToolSequence:
+    equals: [workflow_retry]
+  parentToolSequence:
+    equals: [workflow_retry]
+  workflowCallCount: 0

package/examples/workflow-extension-template/README.md

@@ -0,0 +1,37 @@
+# Workflow extension template
+
+This is a small, copyable extension rather than a generator. It shows the usual
+registration shape with one function and one packaged role. Copy the directory
+into a project, rename the metadata and function, then edit the role body.
+
+
+## Run it
+
+From the repository root after installing dependencies and building the package:
+
+```sh
+node --test examples/workflow-extension-template/extension.test.mjs
+```
+
+For a published package, run the same test from this directory after installing
+`pi-extensible-workflows` in the surrounding project. Copy the directory into a
+trusted Pi extension location; Pi auto-discovers its `index.js` entry point.
+
+
+## Files
+
+- `index.js` registers `greet` and resolves `roles/` from `import.meta.url`.
+  Relative role-directory strings are not accepted by the extension API.
+- `roles/reviewer.md` is a portable packaged role with no provider or tool
+  assumptions.
+- `extension.test.mjs` checks registration, function behavior, role packaging,
+  and the advanced examples.
+
+
+## Optional advanced pieces
+
+The dynamic `template-model` alias and `templateAdvisor` setup hook are
+optional examples. The hook only changes an agent after the call includes
+`{ templateAdvisor: true }`; remove either section if the extension does not
+need it. Both features are trusted host code and should be kept under explicit
+project policy.

package/examples/workflow-extension-template/extension.test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { cp, mkdir, mkdtemp, rm, symlink } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { discoverAndLoadExtensions } from "@earendil-works/pi-coding-agent";
+import { beginWorkflowExtensionLoading, loadingRegistry, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, resetWorkflowRegistry, workflowCatalog } from "pi-extensible-workflows";
+
+test("discovers the copied directory as a trusted Pi extension", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workflow-extension-template-"));
+  try {
+    const destination = join(root, ".pi", "extensions", "workflow-extension-template");
+    await mkdir(join(root, "node_modules"), { recursive: true });
+    const packageEntry = fileURLToPath(import.meta.resolve("pi-extensible-workflows"));
+    const packageRoot = join(dirname(packageEntry), "..", "..");
+    await symlink(packageRoot, join(root, "node_modules", "pi-extensible-workflows"), "dir");
+    await cp(dirname(fileURLToPath(import.meta.url)), destination, { recursive: true });
+    const result = await discoverAndLoadExtensions([], root, join(root, ".pi", "agent"));
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.extensions.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+
+  resetWorkflowRegistry();
+  const { default: extension } = await import("./index.js");
+  beginWorkflowExtensionLoading();
+  extension();
+
+  const catalog = workflowCatalog();
+  assert.deepEqual(catalog.functions.map(({ name }) => name), ["greet"]);
+  assert.deepEqual(catalog.modelAliasEntries?.filter(({ name }) => name === "template-model").map(({ name, kind }) => ({ name, kind })), [{ name: "template-model", kind: "dynamic" }]);
+  assert.equal(await registeredWorkflowFunctions().greet.run({ name: "Ada" }, {}), "Hello, Ada!");
+
+  const registration = registeredWorkflowRoleDirectoryRegistrations()[0];
+  assert.ok(registration);
+  assert.match(readFileSync(join(registration.path, "reviewer.md"), "utf8"), /Packaged reviewer role/);
+
+  const resolved = await loadingRegistry().resolveModelAliases({
+    cwd: process.cwd(),
+    projectTrusted: true,
+    rootModel: { provider: "example", model: "root" },
+    knownModels: new Set(["example/root", "example/available"]),
+    availableModels: new Set(["example/available"]),
+    signal: new AbortController().signal,
+  });
+  assert.deepEqual(resolved, { "template-model": "example/available" });
+
+  const hook = loadingRegistry().agentSetupHooks().find(({ name }) => name === "templateAdvisor");
+  assert.ok(hook);
+  const agent = { prompt: "Review this", options: {}, sessionInput: {} };
+  await hook.setup(agent, { signal: new AbortController().signal });
+  assert.equal(agent.sessionInput.systemPromptAppend, undefined);
+  agent.options.templateAdvisor = true;
+  await hook.setup(agent, { signal: new AbortController().signal });
+  assert.match(agent.sessionInput.systemPromptAppend, /one concrete risk/);
+});

package/examples/workflow-extension-template/index.js

@@ -0,0 +1,51 @@
+import { registerWorkflowExtension } from "pi-extensible-workflows";
+
+const templateExtension = {
+  version: "1.0.0",
+  headline: "Workflow extension template",
+  description: "A copyable registered function with a packaged role.",
+  functions: {
+    greet: {
+      description: "Return a greeting for one person.",
+      input: {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+        additionalProperties: false,
+      },
+      output: { type: "string" },
+      run(input) {
+        return `Hello, ${String(input.name)}!`;
+      },
+    },
+  },
+  // Packaged resources must be absolute paths or file URLs. This URL stays
+  // correct when the extension is copied or installed elsewhere.
+  roleDirectories: [new URL("./roles/", import.meta.url)],
+  // Optional advanced example: select an available model without naming a
+  // provider-specific model in the extension.
+  modelAliases: {
+    "template-model": {
+      resolve({ availableModels, rootModel }) {
+        const root = `${rootModel.provider}/${rootModel.model}`;
+        return availableModels.has(root) ? root : availableModels.values().next().value ?? root;
+      },
+    },
+  },
+  // Optional advanced example: mutate setup only for explicitly opted-in
+  // agents. Setup hooks are trusted code and should stay narrowly scoped.
+  agentSetupHooks: {
+    templateAdvisor: {
+      setup(agent, context) {
+        if (context.signal.aborted || agent.options.templateAdvisor !== true) return;
+        const suffix = "\n\nAdvisor: call out one concrete risk and one next check.";
+        const existing = agent.sessionInput.systemPromptAppend;
+        agent.sessionInput.systemPromptAppend = existing ? existing + suffix : suffix;
+      },
+    },
+  },
+};
+
+export default function extension() {
+  registerWorkflowExtension(templateExtension);
+}

package/examples/workflow-extension-template/roles/reviewer.md

@@ -0,0 +1,4 @@
+---
+description: Packaged reviewer role
+---
+Review the requested change carefully. Return concrete findings with file names and a next check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -25,6 +25,7 @@
     "src",
     "skills",
     "evals",
+    "examples",
     "test/fixtures"
   ],
   "scripts": {
@@ -32,7 +33,7 @@
     "inspect": "node dist/src/cli.js inspect",
     "lint": "eslint .",
     "test": "npm run build && TEST_FILES='dist/test/*.test.js' npm run test:run",
-    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test $TEST_FILES",
+    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test --test-concurrency=1 $TEST_FILES",
     "acceptance": "npm run build && TEST_FILES='dist/test/runtime-acceptance.test.js' npm run test:run",
     "docs:check": "node scripts/check-docs.mjs",
     "check": "npm run lint && npm test && npm run docs:check",

package/skills/pi-extensible-workflows/SKILL.md

@@ -5,47 +5,36 @@ description: Use when the task is complex enough to require multiple subagents o
 
 # pi-extensible-workflows
 
-Use `workflow` only for genuinely multi-agent orchestration; one agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
+## Default path
 
-## Example
+Use `workflow` only for genuinely multi-agent orchestration; a single agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
 
-```js
-const reportSchema = {
-  type: "object",
-  properties: {
-    summary: { type: "string" },
-    findings: { type: "array", items: { type: "string" } },
-  },
-  required: ["summary", "findings"],
-  additionalProperties: false,
-};
+For most multi-agent tasks, start with a named inline workflow: provide a non-empty `name` and a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns.
 
+```js
 const reports = await parallel("research", {
-  first: () =>
-    agent("Research the first target.", {
-      role: "scout",
-      outputSchema: reportSchema,
-    }),
-  second: () =>
-    agent("Research the second target.", {
-      role: "scout",
-      outputSchema: reportSchema,
-    }),
+  first: () => agent("Research the first target."),
+  second: () => agent("Research the second target."),
 });
 
-return agent(prompt("Review these reports:\n\n{reports}", { reports }), {
-  role: "reviewer",
-  outputSchema: reportSchema,
-});
+return await agent(
+  prompt("Summarize these reports:\n\n{reports}", { reports }),
+);
 ```
 
+Await `parallel(...)` or `pipeline(...)` results before interpolation. Runs are backgrounded by default; set the tool-call `foreground: true` when the caller must wait for the final value.
+
+## Runtime and safety rules
+
+
 Inline launches require a non-empty `name`. Registered function launches must omit `name`; they use `workflow` as the run name:
 
 ```json
 { "workflow": "workflowName", "args": { "issue": 42 } }
 ```
-
-Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. A terminal `parentRunId` reuses matching named `withWorktree` scopes but does not replay journal results. For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. Retry versus per-agent `retries` and `workflow_resume` is always explicit; external side effects before failure are not guaranteed exactly once.
+Recovery map: `agent(..., { retries })` reruns one agent call in the same run for transient failures; `workflow_retry({ runId, foreground? })` replays a failed run into a child; `workflow_resume({ runId, budget?, foreground? })` continues a `budget_exhausted` run; recovery inherits the source snapshot's foreground/background launch mode, while legacy snapshots without `launchMode` recover in background; set `foreground: true` or `false` to override it; `parentRunId` on a new launch only borrows named worktrees and never replays or resumes. Use each only for its stated case.
+For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. External side effects before failure are not guaranteed exactly once.
+Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground launches and foreground recovery retain their terminal value and completed `runId`, while background launches and recovery return `runId` immediately and deliver completion or failure as a follow-up. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
 Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task.
 
 Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.
@@ -63,6 +52,10 @@ if (testRes.exitCode === 0) {
 
 Most of the times using `shell()` to perform mutations is an antipattern. Use it mainly for verifications or idempotent actions.
 
+## Advanced capabilities
+
+Registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` remain available for workflows that need them. Treat these as advanced controls rather than requirements for the default inline path.
+
 ## `agent()` options
 
 ```typescript

package/src/agent-execution.ts

@@ -1,4 +1,5 @@
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
@@ -16,7 +17,7 @@ export interface AgentBudgetHooks {
   afterTurn(accounting: AgentAccounting, final: boolean): void;
   instruction(): string | undefined;
 }
-export interface AgentDefinition { prompt?: string; description?: string; model?: string; thinking?: ThinkingLevel; tools?: readonly string[]; disabledAgentResources?: AgentResourceExclusions }
+export interface AgentDefinition { prompt?: string; description?: string; model?: string; thinking?: ThinkingLevel; tools?: readonly string[]; overrideSystemPrompt?: boolean; disabledAgentResources?: AgentResourceExclusions }
 export interface AgentProviderFailure { label: string; provider: string; model: string; error: string }
 export type AgentProviderRecovery = "retry" | "abort" | { model: string };
 export interface AgentExecutionOptions {
@@ -49,6 +50,7 @@ export interface AgentExecutionRoot {
   tools: ReadonlySet<string>;
   agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
   agentDir?: string;
+  additionalSkillPaths?: readonly string[];
   availableModels?: ReadonlySet<string>;
   knownModels?: ReadonlySet<string>;
   modelAliases?: Readonly<Record<string, string>>;
@@ -64,7 +66,7 @@ export interface AgentExecutionRoot {
 export interface AgentAccounting { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }
 export interface AgentToolCallProgress { id: string; name: string; state: "running" | "completed" | "failed" }
 export interface AgentActivity { kind: "reasoning" | "tool" | "text"; text: string }
-export interface AgentProgress { accounting: AgentAccounting; toolCalls: readonly AgentToolCallProgress[]; activity?: AgentActivity; persist: boolean }
+export interface AgentProgress { accounting: AgentAccounting; toolCalls: readonly AgentToolCallProgress[]; activity?: AgentActivity; lastEventAt?: number; persist: boolean }
 export interface AgentAttempt { attempt: number; sessionId: string; sessionFile: string; result?: JsonValue; error?: { code: string; message: string }; accounting: AgentAccounting; setup?: AgentSetupSummary }
 export interface AgentExecutionResult { value: JsonValue; attempts: readonly AgentAttempt[]; cwd: string }
 
@@ -106,14 +108,41 @@ function terminalProviderError(error: WorkflowError): TerminalProviderError | un
   const candidate = value as Partial<TerminalProviderError>;
   return typeof candidate.provider === "string" && typeof candidate.model === "string" && typeof candidate.error === "string" ? { provider: candidate.provider, model: candidate.model, error: candidate.error } : undefined;
 }
+type ProviderRecoveryMarker = { providerRecoveryHandled?: boolean; providerRecovery?: AgentProviderRecovery; providerRecoveryFailed?: boolean };
+const providerContinuationPrompt = "The provider error was transient. Continue the task from your current state.";
+async function recoverTerminalProviderError(session: NativeSession, fallbackModel: ModelSpec, label: string, recovery: AgentExecutionOptions["providerErrorRecovery"], continuePrompt: () => Promise<void>): Promise<boolean> {
+  let continued = false;
+  for (;;) {
+    try { throwIfTerminalAssistantError(session, fallbackModel); return continued; }
+    catch (error) {
+      const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", error instanceof Error ? error.message : String(error));
+      const terminal = terminalProviderError(typed);
+      if (!terminal || !recovery) throw error;
+      let action: AgentProviderRecovery;
+      try { action = await recovery({ label, ...terminal }); } catch { Object.assign(typed, { providerRecoveryHandled: true, providerRecoveryFailed: true }); throw typed; }
+      if (action === "retry") { continued = true; await continuePrompt(); continue; }
+      Object.assign(typed, { providerRecoveryHandled: true, providerRecovery: action });
+      throw typed;
+    }
+  }
+}
 
 function accounting(stats: ReturnType<NativeSession["getSessionStats"]>): AgentAccounting {
   return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
 }
 function canonicalSourcePath(path: string): string { try { return realpathSync(path); } catch { return resolve(path); } }
+const WORKFLOW_DIRECTORY = "pi-extensible-workflows";
+function workflowSystemPromptPath(cwd: string, agentDir: string, projectTrusted: boolean): string | undefined {
+  const projectPath = join(cwd, ".pi", WORKFLOW_DIRECTORY, "SYSTEM.md");
+  if (projectTrusted && existsSync(projectPath)) return projectPath;
+  const globalPaths = [join(homedir(), ".pi", WORKFLOW_DIRECTORY, "SYSTEM.md"), join(agentDir, WORKFLOW_DIRECTORY, "SYSTEM.md")];
+  return globalPaths.find((path) => existsSync(path));
+}
 
 export async function createNativeAgentSession(input: SessionInput): Promise<NativeSession> {
   const agentDir = input.agentDir ?? getAgentDir();
+  const systemPromptSource = workflowSystemPromptPath(input.cwd, agentDir, input.resourcePolicy?.projectTrusted ?? true);
+  const systemPromptOptions = input.systemPrompt !== undefined ? { systemPromptOverride: () => input.systemPrompt } : systemPromptSource !== undefined ? { systemPrompt: systemPromptSource } : {};
   const manager = input.agentDir ? SessionManager.create(input.cwd, join(agentDir, "sessions")) : SessionManager.create(input.cwd);
   manager.appendSessionInfo(input.sessionLabel);
   const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: join(agentDir, "models.json") });
@@ -147,17 +176,18 @@ export async function createNativeAgentSession(input: SessionInput): Promise<Nat
       noExtensions: true,
       additionalExtensionPaths: extensionPaths,
       noSkills: true,
-      additionalSkillPaths: skillPaths,
+      additionalSkillPaths: [...new Set([...skillPaths, ...(input.additionalSkillPaths ?? [])])],
       ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
       skillsOverride: (base) => {
         const disabledSkills = updateSkillMatches(base.skills);
         return { ...base, skills: base.skills.filter(({ name }) => !disabledSkills.has(name)) };
       },
       ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}),
+      ...systemPromptOptions,
     });
     await resourceLoader.reload();
-  } else if (input.systemPromptAppend || input.extensionFactories?.length) {
-    resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
+  } else if (input.systemPrompt !== undefined || systemPromptSource !== undefined || input.systemPromptAppend || input.extensionFactories?.length || input.additionalSkillPaths?.length) {
+    resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.additionalSkillPaths?.length ? { additionalSkillPaths: [...input.additionalSkillPaths] } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...systemPromptOptions, ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
     await resourceLoader.reload();
   }
   const { session } = await createAgentSession({ ...(input.options ?? {}), cwd: input.cwd, agentDir, modelRuntime, model, ...(settingsManager ? { settingsManager } : {}), ...(input.model.thinking ? { thinkingLevel: input.model.thinking } : {}), tools, ...(customTools.length ? { customTools } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(resourceLoader ? { resourceLoader } : {}), sessionManager: manager });
@@ -199,13 +229,13 @@ function fallbackSetupContext(root: AgentExecutionRoot, options: AgentExecutionO
 function resourcePolicySummary(policy: AgentResourcePolicy): NonNullable<AgentSetupSummary["disabledAgentResources"]> {
   return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], excludedSkills: [...(policy.excludedSkills ?? [])], excludedExtensions: [...(policy.excludedExtensions ?? [])], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
 }
-async function prepareAgentSetup(root: AgentExecutionRoot, createSession: SessionFactory, task: string, options: AgentExecutionOptions, resolved: { model: ModelSpec; tools: readonly string[]; systemPromptAppend: string }, cwd: string, attempt: number, signal: AbortSignal | undefined, customTools: readonly ToolDefinition[], resultTool: ToolDefinition | undefined): Promise<{ setup: AgentSetup; summary: AgentSetupSummary }> {
+async function prepareAgentSetup(root: AgentExecutionRoot, createSession: SessionFactory, task: string, options: AgentExecutionOptions, resolved: { model: ModelSpec; tools: readonly string[]; systemPrompt?: string; systemPromptAppend: string }, cwd: string, attempt: number, signal: AbortSignal | undefined, customTools: readonly ToolDefinition[], resultTool: ToolDefinition | undefined): Promise<{ setup: AgentSetup; summary: AgentSetupSummary }> {
   const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
   const baselineOptions = structuredClone(options.agentOptions ?? {});
   const baseResourcePolicy = await root.agentResourcePolicy?.();
   const roleExclusions = options.role ? root.agentDefinitions?.[options.role]?.disabledAgentResources : undefined;
   const resourcePolicy = baseResourcePolicy && roleExclusions ? { ...baseResourcePolicy, effective: mergeAgentResourceExclusions(baseResourcePolicy.effective, roleExclusions) } : baseResourcePolicy;
-  const sessionInput: SessionInput = { cwd, model: { ...resolved.model }, tools: [...resolved.tools], sessionLabel: `${options.workflowName}:${options.label}:attempt-${String(attempt)}`, ...(root.agentDir ? { agentDir: root.agentDir } : {}), ...(customTools.length ? { customTools: [...customTools] } : {}), ...(resultTool ? { resultTool } : {}), systemPromptAppend: resolved.systemPromptAppend, ...(resourcePolicy ? { resourcePolicy } : {}), options: structuredClone(baselineOptions) };
+  const sessionInput: SessionInput = { cwd, model: { ...resolved.model }, tools: [...resolved.tools], sessionLabel: `${options.workflowName}:${options.label}:attempt-${String(attempt)}`, ...(root.agentDir ? { agentDir: root.agentDir } : {}), ...(root.additionalSkillPaths?.length ? { additionalSkillPaths: [...root.additionalSkillPaths] } : {}), ...(customTools.length ? { customTools: [...customTools] } : {}), ...(resultTool ? { resultTool } : {}), ...(resolved.systemPrompt !== undefined ? { systemPrompt: resolved.systemPrompt } : {}), systemPromptAppend: resolved.systemPromptAppend, ...(resourcePolicy ? { resourcePolicy } : {}), options: structuredClone(baselineOptions) };
   const setup: AgentSetup = { prompt: task, options: sessionInput.options ?? {}, sessionInput, createSession };
   const base = fallbackSetupContext(root, options, setupSignal);
   const context = Object.freeze({ run: base.run, identity: base.identity, attempt, signal: setupSignal });
@@ -230,7 +260,7 @@ export class WorkflowAgentExecutor {
   constructor(private readonly root: AgentExecutionRoot, private readonly createSession: SessionFactory = createNativeAgentSession) {}
   setRunContext(runContext: Readonly<WorkflowRunContext>): void { this.root.runContext = runContext; }
 
-  resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): { model: ModelSpec; requestedModel?: string; tools: readonly string[]; systemPromptAppend: string } {
+  resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): { model: ModelSpec; requestedModel?: string; tools: readonly string[]; systemPrompt?: string; systemPromptAppend: string } {
     const role = options.role;
     const definition = role ? this.root.agentDefinitions?.[role] : undefined;
     if (role && !definition) throw new WorkflowError("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${role}`);
@@ -246,7 +276,8 @@ export class WorkflowAgentExecutor {
     const model = options.modelOverride ?? parseModel(requestedModel, this.root.model, options.thinking ?? (aliasThinking === undefined ? definition?.thinking : undefined), this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
     const availableModels = this.root.knownModels ?? this.root.availableModels ?? new Set([modelCapability(this.root.model)]);
     if (!availableModels.has(modelCapability(model))) throw new WorkflowError("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
-    return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
+    const overrideSystemPrompt = definition?.overrideSystemPrompt === true;
+    return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: [...requested], ...(overrideSystemPrompt ? { systemPrompt: definition.prompt ?? "" } : {}), systemPromptAppend: overrideSystemPrompt ? "" : definition?.prompt ?? "" };
   }
 
   async execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools: readonly ToolDefinition[] = [], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult> {
@@ -299,6 +330,8 @@ export class WorkflowAgentExecutor {
       } as ToolDefinition : undefined;
       const toolCalls = new Map<string, AgentToolCallProgress>();
       let activity: AgentActivity | undefined;
+      let lastEventAt: number | undefined;
+      let lastReportedEventAt: number | undefined;
       let progress = Promise.resolve();
       let unsubscribe: (() => void) | undefined;
       let systemPromptTurn = 0;
@@ -310,9 +343,15 @@ export class WorkflowAgentExecutor {
       };
       const report = (persist: boolean) => {
         if (!session || !options.onProgress) return;
-        const update = { accounting: accounting(session.getSessionStats()), toolCalls: [...toolCalls.values()], ...(activity ? { activity } : {}), persist };
+        const update = { accounting: accounting(session.getSessionStats()), toolCalls: [...toolCalls.values()], ...(activity ? { activity } : {}), ...(lastEventAt === undefined ? {} : { lastEventAt }), persist };
+        if (lastEventAt !== undefined) lastReportedEventAt = lastEventAt;
         progress = progress.then(() => options.onProgress?.(update)).then(() => undefined);
       };
+      const reportTimestamp = () => {
+        if (lastEventAt !== undefined && lastReportedEventAt !== undefined && lastEventAt - lastReportedEventAt < 1000) return;
+        report(false);
+      };
+      const activityChanged = (previous: AgentActivity | undefined) => previous?.kind !== activity?.kind || previous?.text !== activity?.text;
       try {
         setupFailed = true;
         const prepared = await prepareAgentSetup(this.root, this.createSession, task, options, resolved, cwd, attempt, executionSignal, customTools, resultTool);
@@ -326,7 +365,20 @@ export class WorkflowAgentExecutor {
         const includeAttemptSetup = Boolean(this.root.agentSetupHooks?.length || setup.sessionInput.resourcePolicy);
         await options.onAttempt?.({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), ...(includeAttemptSetup ? { setup: setupSummary } : {}) });
         const activeSession = session;
+        const sessionModel = setup.sessionInput.model;
+        const recoverTerminal = () => recoverTerminalProviderError(activeSession, sessionModel, options.label, options.providerErrorRecovery, async () => { try { await promptWithProviderPause(activeSession, providerContinuationPrompt, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause); } catch (error) { if (!hasSchemaResult()) throw error; } });
+        const promptAndRecover = async (prompt: string): Promise<void> => {
+          let promptFailed = false;
+          let promptError: unknown;
+          try { await promptWithProviderPause(activeSession, prompt, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause); } catch (error) { promptFailed = true; promptError = error; }
+          const recovered = await recoverTerminal();
+          if (promptFailed && !hasSchemaResult() && !recovered) throw promptError;
+        };
         unsubscribe = activeSession.subscribe?.((event) => {
+          lastEventAt = Date.now();
+          let persist = false;
+          let shouldReport = false;
+          let removeToolCallId: string | undefined;
           if (event.type === "agent_start" && session?.systemPrompt !== undefined) {
             if (this.root.runStore) {
               systemPromptTurn += 1;
@@ -336,20 +388,32 @@ export class WorkflowAgentExecutor {
           }
           if (event.type === "message_start" && event.message.role === "assistant") {
             if (!turnStarted) { try { options.budget?.beforeTurn(); turnStarted = true; } catch (error) { budgetError ??= error instanceof WorkflowError ? error : new WorkflowError("BUDGET_EXHAUSTED", error instanceof Error ? error.message : String(error)); void session?.abort?.(); } }
-            activity = { kind: "text", text: "responding" }; report(false);
+            activity = { kind: "text", text: "responding" };
+            shouldReport = true;
+          }
+          if (event.type === "message_update") {
+            const previousActivity = activity;
+            if (["thinking_start", "thinking_delta", "thinking_end"].includes(event.assistantMessageEvent.type)) activity = { kind: "reasoning", text: "reasoning" };
+            else if (["text_start", "text_delta", "text_end", "toolcall_start", "toolcall_delta", "toolcall_end"].includes(event.assistantMessageEvent.type)) activity = { kind: "text", text: "responding" };
+            shouldReport = activityChanged(previousActivity);
           }
           if (event.type === "message_end") {
+            const previousActivity = activity;
             activity = undefined;
+            shouldReport = activityChanged(previousActivity);
             if (event.message.role === "assistant") {
               const needsMoreWork = hasToolCall(event.message);
               const final = !needsMoreWork || (options.schema !== undefined && hasSchemaResult());
               if (!budgetError) { try { options.budget?.afterTurn(accounting(activeSession.getSessionStats()), final); if (!final) { const instruction = options.budget?.instruction(); if (instruction) void session?.steer?.(instruction); } } catch (error) { budgetError ??= error instanceof WorkflowError ? error : new WorkflowError("BUDGET_EXHAUSTED", error instanceof Error ? error.message : String(error)); void session?.abort?.(); } }
               turnStarted = false;
-              report(true);
+              persist = true;
             }
           }
-          if (event.type === "tool_execution_start") { toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: "running" }); activity = { kind: "tool", text: event.toolName }; report(false); }
-          if (event.type === "tool_execution_end") { toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: event.isError ? "failed" : "completed" }); if (activity?.kind === "tool" && activity.text === event.toolName) activity = undefined; report(false); toolCalls.delete(event.toolCallId); }
+          if (event.type === "tool_execution_start") { toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: "running" }); activity = { kind: "tool", text: event.toolName }; shouldReport = true; }
+          if (event.type === "tool_execution_update") { const previousActivity = activity; activity = { kind: "tool", text: event.toolName }; shouldReport = activityChanged(previousActivity); }
+          if (event.type === "tool_execution_end") { toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: event.isError ? "failed" : "completed" }); if (activity?.kind === "tool" && activity.text === event.toolName) activity = undefined; shouldReport = true; removeToolCallId = event.toolCallId; }
+          if (shouldReport || persist) report(persist); else reportTimestamp();
+          if (removeToolCallId) toolCalls.delete(removeToolCallId);
         });
         report(false);
         if (setSteer) {
@@ -361,18 +425,21 @@ export class WorkflowAgentExecutor {
         const promptText = `${context}\n\nTask:\n${setup.prompt}${instruction ? `\n\n${instruction}` : ""}`;
         options.budget?.beforeTurn();
         turnStarted = true;
-        try { await promptWithProviderPause(session, promptText, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause); } catch (error) { if (!hasSchemaResult()) throw error; }
-        throwIfTerminalAssistantError(session, setup.sessionInput.model);
+        await promptAndRecover(promptText);
         { const completedAccounting = accounting(session.getSessionStats()); options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? hasSchemaResult() : !latestAssistantHasToolCall(session.messages)); turnStarted = false; }
         if (budgetError) throw budgetError;
         if (options.schema) {
           if (!hasSchemaResult()) {
-            try { options.budget?.beforeTurn(); turnStarted = true; await promptWithProviderPause(session, "Submit the final result now by calling workflow_result exactly once. Do not return prose.", remaining(options.timeoutMs, started), executionSignal, this.root.providerPause); { const completedAccounting = accounting(session.getSessionStats()); options.budget?.afterTurn(completedAccounting, true); turnStarted = false; } } catch (error) { if (!hasSchemaResult()) throw error; }
+            options.budget?.beforeTurn();
+            turnStarted = true;
+            await promptAndRecover("Submit the final result now by calling workflow_result exactly once. Do not return prose.");
+            { const completedAccounting = accounting(session.getSessionStats()); options.budget?.afterTurn(completedAccounting, true); turnStarted = false; }
           }
-          throwIfTerminalAssistantError(session, setup.sessionInput.model);
           if (!hasSchemaResult()) {
-            try { options.budget?.beforeTurn(); turnStarted = true; await promptWithProviderPause(session, "Your result was missing or invalid. Repair it by calling workflow_result exactly once with a schema-valid value.", remaining(options.timeoutMs, started), executionSignal, this.root.providerPause); { const completedAccounting = accounting(session.getSessionStats()); options.budget?.afterTurn(completedAccounting, true); turnStarted = false; } } catch (error) { if (!hasSchemaResult()) throw error; }
-            throwIfTerminalAssistantError(session, setup.sessionInput.model);
+            options.budget?.beforeTurn();
+            turnStarted = true;
+            await promptAndRecover("Your result was missing or invalid. Repair it by calling workflow_result exactly once with a schema-valid value.");
+            { const completedAccounting = accounting(session.getSessionStats()); options.budget?.afterTurn(completedAccounting, true); turnStarted = false; }
           }
           if (schemaResult === undefined) throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
         }
@@ -402,21 +469,26 @@ export class WorkflowAgentExecutor {
         }
         if (options.worktreeOwner && typed.code !== "WORKTREE_FAILED") await this.root.runStore?.snapshotWorktree(options.worktreeOwner).catch(() => undefined);
         const terminal = terminalProviderError(typed);
-        if (terminal && options.providerErrorRecovery) {
-          let recovery: AgentProviderRecovery;
+        const recoveryState = typed as WorkflowError & ProviderRecoveryMarker;
+        let recovery = recoveryState.providerRecovery;
+        if (terminal && options.providerErrorRecovery && !recoveryState.providerRecoveryHandled) {
           try { recovery = await options.providerErrorRecovery({ label: options.label, ...terminal }); } catch { throw Object.assign(typed, { attempts }); }
-          if (recovery === "retry" || typeof recovery === "object" && typeof recovery.model === "string") {
-            if (typeof recovery === "object") {
-              try {
-                const selected = resolveModelReference(recovery.model, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
-                recoveryModel = selected.thinking === undefined && resolved.model.thinking ? { ...selected, thinking: resolved.model.thinking } : selected;
-              } catch { throw Object.assign(typed, { attempts }); }
-            }
+          if (recovery === "retry") {
             maxAttempts += 1;
             beforeRetry?.();
             continue;
           }
         }
+        if (recoveryState.providerRecoveryFailed || recovery === "abort") throw Object.assign(typed, { attempts });
+        if (typeof recovery === "object" && typeof recovery.model === "string") {
+          try {
+            const selected = resolveModelReference(recovery.model, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
+            recoveryModel = selected.thinking === undefined && resolved.model.thinking ? { ...selected, thinking: resolved.model.thinking } : selected;
+          } catch { throw Object.assign(typed, { attempts }); }
+          maxAttempts += 1;
+          beforeRetry?.();
+          continue;
+        }
         if (attempt === maxAttempts || setupFailed || typed.code === "CANCELLED" || typed.code === "WORKTREE_FAILED" || typed.code === "RESUME_INCOMPATIBLE") throw Object.assign(typed, { attempts });
         beforeRetry?.();
       }