@quintinshaw/pi-dynamic-workflows 1.9.1 → 1.9.2

package/src/workflow-manager.ts

@@ -3,7 +3,8 @@
  */
 
 import { EventEmitter } from "node:events";
-import type { WorkflowSnapshot } from "./display.js";
+import type { WorkflowAgent } from "./agent.js";
+import { preview, type WorkflowSnapshot } from "./display.js";
 import { WorkflowError, WorkflowErrorCode } from "./errors.js";
 import {
   createRunPersistence,
@@ -27,6 +28,27 @@ export interface ManagedRun {
   args?: unknown;
   /** Accumulated agent results for resume (deterministic call index -> result). */
   journal: JournalEntry[];
+  /**
+   * True when the run was started in the background (or resumed) and the caller is
+   * not awaiting its result inline. Only background runs deliver their result back
+   * into the conversation; a foreground sync run already returns it as the tool
+   * result, so re-delivering would duplicate it.
+   */
+  background: boolean;
+}
+
+/** Per-execution options shared by sync, background, and resume runs. */
+export interface ExecOptions {
+  /** Replay these journaled agent results for the unchanged prefix (resume). */
+  resumeJournal?: Map<number, JournalEntry>;
+  /** Cap on total agents for this run. */
+  maxAgents?: number;
+  /** Per-agent timeout in milliseconds. */
+  agentTimeoutMs?: number;
+  /** Host signal (e.g. tool/Esc) that should abort this run when fired. */
+  externalSignal?: AbortSignal;
+  /** Called with the live snapshot on every progress event. */
+  onProgress?: (snapshot: WorkflowSnapshot) => void;
 }
 
 export interface WorkflowManagerOptions {
@@ -34,6 +56,10 @@ export interface WorkflowManagerOptions {
   concurrency?: number;
   /** Resolve a saved-workflow name to its script, enabling nested `workflow('name')`. */
   loadSavedWorkflow?: (name: string) => string | undefined;
+  /** Inject a custom agent runner (tests); defaults to a real subagent session. */
+  agent?: Pick<WorkflowAgent, "run">;
+  /** The session's main model (provider/id), for auto-tiering explore agents. */
+  mainModel?: string;
 }
 
 export class WorkflowManager extends EventEmitter {
@@ -42,15 +68,25 @@ export class WorkflowManager extends EventEmitter {
   private cwd: string;
   private concurrency: number;
   private loadSavedWorkflow?: (name: string) => string | undefined;
+  private agent?: Pick<WorkflowAgent, "run">;
+  /** The session's main model (provider/id), for auto-tiering explore agents. */
+  private mainModel?: string;
 
   constructor(options: WorkflowManagerOptions = {}) {
     super();
     this.cwd = options.cwd ?? process.cwd();
     this.concurrency = options.concurrency ?? 8;
     this.loadSavedWorkflow = options.loadSavedWorkflow;
+    this.agent = options.agent;
+    this.mainModel = options.mainModel;
     this.persistence = createRunPersistence(this.cwd);
   }
 
+  /** Set the session's main model (provider/id). Used to auto-tier explore agents. */
+  setMainModel(spec: string | undefined): void {
+    this.mainModel = spec;
+  }
+
   /**
    * Start a workflow in the background.
    * Returns immediately with a run ID; the workflow executes asynchronously.
@@ -79,6 +115,7 @@ export class WorkflowManager extends EventEmitter {
       script,
       args,
       journal: [],
+      background: true,
     };
 
     this.runs.set(runId, managed);
@@ -104,15 +141,25 @@ export class WorkflowManager extends EventEmitter {
   }
 
   /**
-   * Execute a workflow synchronously (blocking).
+   * Execute a workflow synchronously (blocking) while still tracking it like a
+   * background run, so the `/workflows` navigator and the live task panel see it.
+   * `onProgress` fires on every progress event with the current snapshot, letting
+   * a caller (e.g. the workflow tool) drive its own inline display.
    */
-  async runSync(script: string, args?: unknown): Promise<WorkflowRunResult> {
-    const runId = generateRunId();
-    const controller = new AbortController();
-    const parsed = parseWorkflowScript(script);
+  async runSync(script: string, args?: unknown, exec: ExecOptions = {}): Promise<WorkflowRunResult> {
+    const managed = this.createManaged(script, args);
+    this.runs.set(managed.runId, managed);
+    // Persist the initial state immediately so listRuns()/the task panel can see
+    // the run the moment it starts, not only after the first agent journals.
+    this.persistRun(managed);
+    return this.executeRun(managed, script, args, exec);
+  }
 
-    const managed: ManagedRun = {
-      runId,
+  /** Build a fresh managed run with an empty snapshot. */
+  private createManaged(script: string, args?: unknown): ManagedRun {
+    const parsed = parseWorkflowScript(script);
+    return {
+      runId: generateRunId(),
       status: "running",
       snapshot: {
         name: parsed.meta.name,
@@ -125,29 +172,38 @@ export class WorkflowManager extends EventEmitter {
         doneCount: 0,
         errorCount: 0,
       },
-      controller,
+      controller: new AbortController(),
       startedAt: new Date(),
       script,
       args,
       journal: [],
+      background: false,
     };
-
-    this.runs.set(runId, managed);
-    return this.executeRun(managed, script, args);
   }
 
   private async executeRun(
     managed: ManagedRun,
     script: string,
     args?: unknown,
-    resumeJournal?: Map<number, JournalEntry>,
+    exec: ExecOptions = {},
   ): Promise<WorkflowRunResult> {
+    const { resumeJournal, maxAgents, agentTimeoutMs, externalSignal, onProgress } = exec;
+    const progress = () => onProgress?.(managed.snapshot);
+    // Let a host abort (e.g. Esc during a blocking tool call) cancel this run.
+    if (externalSignal) {
+      if (externalSignal.aborted) managed.controller.abort();
+      else externalSignal.addEventListener("abort", () => managed.controller.abort(), { once: true });
+    }
     try {
       const result = await runWorkflow(script, {
         cwd: this.cwd,
         args,
+        agent: this.agent,
+        mainModel: this.mainModel,
         signal: managed.controller.signal,
         concurrency: this.concurrency,
+        maxAgents,
+        agentTimeoutMs,
         loadSavedWorkflow: this.loadSavedWorkflow,
         resumeJournal,
         resumeFromRunId: resumeJournal ? managed.runId : undefined,
@@ -160,6 +216,7 @@ export class WorkflowManager extends EventEmitter {
         onLog: (message) => {
           managed.snapshot.logs.push(message);
           this.emit("log", { runId: managed.runId, message });
+          progress();
         },
         onPhase: (title) => {
           managed.snapshot.currentPhase = title;
@@ -167,6 +224,7 @@ export class WorkflowManager extends EventEmitter {
             managed.snapshot.phases.push(title);
           }
           this.emit("phase", { runId: managed.runId, title });
+          progress();
         },
         onAgentStart: (event) => {
           managed.snapshot.agents.push({
@@ -175,8 +233,10 @@ export class WorkflowManager extends EventEmitter {
             phase: event.phase,
             prompt: event.prompt,
             status: "running",
+            model: event.model,
           });
           this.emit("agentStart", { runId: managed.runId, ...event });
+          progress();
         },
         onAgentEnd: (event) => {
           const agent = [...managed.snapshot.agents]
@@ -184,8 +244,17 @@ export class WorkflowManager extends EventEmitter {
             .find((a) => a.label === event.label && a.status === "running");
           if (agent) {
             agent.status = event.result === null ? "error" : "done";
+            agent.resultPreview = preview(event.result);
+            agent.tokens = event.tokens;
+            if (event.model) agent.model = event.model;
           }
           this.emit("agentEnd", { runId: managed.runId, ...event });
+          progress();
+        },
+        onTokenUsage: (usage) => {
+          managed.snapshot.tokenUsage = usage;
+          this.emit("tokenUsage", { runId: managed.runId, usage });
+          progress();
         },
       });
 
@@ -241,6 +310,13 @@ export class WorkflowManager extends EventEmitter {
       })),
       logs: managed.snapshot.logs,
       result: managed.result?.result,
+      tokenUsage: managed.snapshot.tokenUsage
+        ? {
+            input: managed.snapshot.tokenUsage.input,
+            output: managed.snapshot.tokenUsage.output,
+            total: managed.snapshot.tokenUsage.total,
+          }
+        : undefined,
       startedAt: managed.startedAt.toISOString(),
       updatedAt: new Date().toISOString(),
       completedAt: managed.status === "completed" ? new Date().toISOString() : undefined,
@@ -292,13 +368,14 @@ export class WorkflowManager extends EventEmitter {
       script: persisted.script,
       args: persisted.args,
       journal: persisted.journal ?? [],
+      background: true,
     };
     this.runs.set(runId, managed);
 
     const resumeJournal = new Map((persisted.journal ?? []).map((e) => [e.index, e] as const));
     this.emit("resumed", { runId });
     // Run in the background; executeRun records status/errors on the managed run.
-    void this.executeRun(managed, persisted.script, persisted.args, resumeJournal).catch(() => {});
+    void this.executeRun(managed, persisted.script, persisted.args, { resumeJournal }).catch(() => {});
     return true;
   }
 

package/src/workflow-tool.ts

@@ -1,19 +1,39 @@
 import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { listAvailableModelSpecs } from "./agent.js";
 import {
   createToolUpdateWorkflowDisplay,
   createWorkflowSnapshot,
-  preview,
   recomputeWorkflowSnapshot,
   renderWorkflowText,
   type WorkflowSnapshot,
 } from "./display.js";
 import { WorkflowError, WorkflowErrorCode } from "./errors.js";
-import { parseWorkflowScript, runWorkflow, type WorkflowRunResult } from "./workflow.js";
+import { parseWorkflowScript, type WorkflowRunResult } from "./workflow.js";
 import { WorkflowManager } from "./workflow-manager.js";
 import { createWorkflowStorage, type WorkflowStorage } from "./workflow-saved.js";
 
+/**
+ * Per-agent model-routing policy handed to the workflow author (the model). It
+ * states the rule and lists the user's currently available models, then lets the
+ * author choose each agent's model via opts.model — no hardcoded family mapping.
+ */
+function modelRoutingGuideline(): string {
+  const available = listAvailableModelSpecs();
+  const list = available.length
+    ? `The user's currently available models (route only to these) are: ${available.join(", ")}.`
+    : "Use models the user has configured.";
+  return [
+    "For workflow, decide each agent's model yourself via opts.model, following this policy:",
+    "If the user named a specific model, use exactly that.",
+    "Otherwise, for exploration/search/inventory/gathering agents, pick a model one tier BELOW the main model in the SAME family (e.g. Claude→Haiku, ChatGPT/GPT→a mini, DeepSeek→a lighter/flash variant), choosing the closest match from the available list.",
+    "For analysis/synthesis/judgment/decision/verification agents, omit opts.model so the agent runs on the main model.",
+    "Never route to a model that is not in the available list; if no suitable lighter sibling exists, omit opts.model (use the main model).",
+    list,
+  ].join(" ");
+}
+
 const workflowToolSchema = Type.Object({
   script: Type.String({
     description: [
@@ -28,7 +48,8 @@ const workflowToolSchema = Type.Object({
   ),
   background: Type.Optional(
     Type.Boolean({
-      description: "Run the workflow in the background. Default: false. When true, returns immediately with a run ID.",
+      description:
+        "Run the workflow in the background. Default: true — the tool returns immediately with a run ID, the turn ends so the user isn't blocked, and the result is delivered back into the conversation when it finishes. Set to false only when you need the result inline in this same turn (the call will block until the workflow completes).",
     }),
   ),
   maxAgents: Type.Optional(
@@ -62,8 +83,13 @@ export interface WorkflowToolOptions {
 
 export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefinition<typeof workflowToolSchema, any> {
   const storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
-  const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-  const loadSavedWorkflow = (name: string) => storage.load(name)?.script;
+  const manager =
+    options.manager ??
+    new WorkflowManager({
+      cwd: options.cwd,
+      concurrency: options.concurrency,
+      loadSavedWorkflow: (name: string) => storage.load(name)?.script,
+    });
 
   return defineTool({
     name: "workflow",
@@ -87,38 +113,35 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
       "For workflow, failed agent(), parallel(), or pipeline() branches return null and log the failure unless the workflow is aborted. Check for nulls before synthesizing conclusions.",
       "For workflow, include a final synthesis/assertion agent when combining multiple subagent results; return a compact JSON-serializable value with ok/verdict plus the important outputs.",
       "For workflow, if agent() needs machine-readable output, pass a plain JSON Schema via opts.schema; agent() will return the validated object. Use JSON Schema syntax, not TypeScript or TypeBox constructors.",
+      modelRoutingGuideline(),
       "For workflow, do not assume the parent assistant has repository code context inside subagents; include enough task context and relevant paths in each agent prompt.",
-      "For workflow, set background: true to run asynchronously. The workflow will return immediately with a run ID that can be used to check status later.",
+      "For workflow, runs are background by default: the tool returns immediately with a run ID, the turn ends so the user isn't blocked, and the result is delivered back into the conversation when the run finishes. Pass background: false only when you must use the result inline in this same turn (it will block).",
       "For workflow, you may call `await workflow('saved-name', argsObject)` to run a saved workflow inline and use its result; nesting is one level deep only, and the global 16-concurrent / 1000-total caps hold across the nesting.",
     ],
     parameters: workflowToolSchema,
     prepareArguments(args) {
       return normalizeWorkflowToolArgs(args);
     },
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, onUpdate, _ctx) {
       const script = normalizeWorkflowScript(params.script);
       const parsed = parseWorkflowScript(script);
 
-      // Background execution
-      if (params.background) {
+      // Background execution is the default: return immediately so the turn ends
+      // and the user isn't blocked. The result is delivered back into the
+      // conversation when the run finishes (see installResultDelivery). Only an
+      // explicit `background: false` blocks for the result inline.
+      if (params.background ?? true) {
         const { runId } = manager.startInBackground(script, params.args);
         return {
-          content: [
-            {
-              type: "text",
-              text: [
-                `Workflow "${parsed.meta.name}" started in background.`,
-                `Run ID: ${runId}`,
-                `Use /workflows status ${runId} to check progress.`,
-                `Use /workflows stop ${runId} to cancel.`,
-              ].join("\n"),
-            },
-          ],
+          content: [{ type: "text", text: backgroundStartedText(parsed.meta.name, runId) }],
           details: { runId, background: true },
         };
       }
 
-      // Synchronous execution (blocking)
+      // Synchronous execution (blocking) — but routed through the manager so the
+      // run shows up live in the /workflows navigator and the task panel while it
+      // runs, then stays in history afterwards. We still block on the result and
+      // return it inline, so the model gets the full output in the same turn.
       let snapshot: WorkflowSnapshot = createWorkflowSnapshot(parsed.meta);
       const display = createToolUpdateWorkflowDisplay(onUpdate, undefined, {
         key: "workflow",
@@ -128,55 +151,15 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
         showResultPreviews: false,
       });
 
-      const update = () => {
-        snapshot = recomputeWorkflowSnapshot(snapshot);
-        display.update(snapshot);
-      };
-
       let result: WorkflowRunResult;
       try {
-        result = await runWorkflow(script, {
-          cwd: options.cwd ?? ctx.cwd,
-          args: params.args,
-          signal,
-          concurrency: options.concurrency,
+        result = await manager.runSync(script, params.args, {
           maxAgents: params.maxAgents,
           agentTimeoutMs: params.agentTimeoutMs,
-          loadSavedWorkflow,
-          onLog(message) {
-            snapshot.logs.push(message);
-            update();
-          },
-          onPhase(title) {
-            snapshot.currentPhase = title;
-            if (!snapshot.phases.includes(title)) snapshot.phases.push(title);
-            update();
-          },
-          onAgentStart(event) {
-            if (signal?.aborted) throw new Error("Workflow was aborted");
-            snapshot.agents.push({
-              id: snapshot.agents.length + 1,
-              label: event.label,
-              phase: event.phase,
-              prompt: event.prompt,
-              status: "running",
-            });
-            update();
-          },
-          onAgentEnd(event) {
-            const agent = [...snapshot.agents]
-              .reverse()
-              .find((item) => item.label === event.label && item.status === "running");
-            if (agent) {
-              agent.status = event.result === null ? "error" : "done";
-              agent.resultPreview = preview(event.result);
-              agent.tokens = event.tokens;
-            }
-            update();
-          },
-          onTokenUsage(usage) {
-            snapshot.tokenUsage = usage;
-            update();
+          externalSignal: signal,
+          onProgress(live) {
+            snapshot = recomputeWorkflowSnapshot(live);
+            display.update(snapshot);
           },
         });
       } catch (error) {
@@ -245,6 +228,25 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
   });
 }
 
+/**
+ * The tool result returned when a workflow starts in the background. It both
+ * informs the model and tells it to reassure the user: the run continues on its
+ * own and the conversation will resume automatically when it finishes, so the
+ * user can just wait here (or go do something else).
+ */
+export function backgroundStartedText(name: string, runId: string): string {
+  return [
+    `Workflow "${name}" started in the background.`,
+    `Run ID: ${runId}`,
+    "It keeps running on its own. When it finishes, the result is delivered back",
+    "here and the conversation continues automatically — the user does not need to",
+    "do anything. Tell the user they can simply wait here for it to finish (it will",
+    "resume the conversation by itself), or keep chatting / working on other things",
+    "in the meantime; either way the result will come back to this conversation.",
+    `They can also track or cancel it with /workflows status ${runId} or /workflows stop ${runId}.`,
+  ].join("\n");
+}
+
 function normalizeWorkflowToolArgs(args: unknown): WorkflowToolInput {
   if (!args || typeof args !== "object") throw new Error("workflow requires an object argument with a script string");
   const value = args as Record<string, unknown>;

package/src/workflow-ui.ts

@@ -63,6 +63,14 @@ interface AgentRow {
   status: string;
   phase?: string;
   tokens?: number;
+  model?: string;
+}
+
+/** Short, human-friendly model label: drop the provider prefix for display. */
+function shortModel(model: string | undefined): string | undefined {
+  if (!model) return undefined;
+  const slash = model.indexOf("/");
+  return slash > 0 ? model.slice(slash + 1) : model;
 }
 
 /** Reads run/phase/agent data from the manager, preferring live snapshots. */
@@ -127,7 +135,7 @@ export class NavigatorModel {
     if (!snap) return [];
     return snap.agents
       .filter((a) => (a.phase ?? "(no phase)") === phase)
-      .map((a) => ({ id: a.id, label: a.label, status: a.status, phase: a.phase, tokens: a.tokens }));
+      .map((a) => ({ id: a.id, label: a.label, status: a.status, phase: a.phase, tokens: a.tokens, model: a.model }));
   }
 
   agentDetail(runId: string, agentId: number): WorkflowAgentSnapshot | undefined {
@@ -150,6 +158,7 @@ function persistedToSnapshot(p: PersistedRunState): WorkflowSnapshot {
       resultPreview:
         a.result == null ? undefined : String(typeof a.result === "string" ? a.result : JSON.stringify(a.result)),
       error: a.error,
+      model: a.model,
     })),
     agentCount: p.agents.length,
     runningCount: p.agents.filter((a) => a.status === "running").length,
@@ -293,8 +302,9 @@ export function renderNavigator(
     lines.push(theme.bold(`${model.runName(state.runId)} › ${state.phase}`));
     agents.forEach((a, i) => {
       const icon = STATUS_ICON[a.status] ?? "?";
-      const tok = a.tokens ? dim(` ${fmtTokens(a.tokens)}`) : "";
-      lines.push(sel(i, `${icon} ${a.label}${tok}`));
+      const mdl = shortModel(a.model);
+      const meta = [mdl, a.tokens ? fmtTokens(a.tokens) : undefined].filter(Boolean).join(" · ");
+      lines.push(sel(i, `${icon} ${a.label}${meta ? dim(`  ${meta}`) : ""}`));
     });
   } else if (state.kind === "detail" && state.runId && state.agentId != null) {
     const a = model.agentDetail(state.runId, state.agentId);
@@ -302,6 +312,7 @@ export function renderNavigator(
     if (a) {
       const body: string[] = [];
       body.push(dim("Status: ") + (a.status ?? ""));
+      if (a.model) body.push(dim("Model: ") + (shortModel(a.model) ?? ""));
       if (a.error) body.push(dim("Error: ") + a.error);
       body.push("", dim("Prompt:"));
       body.push(...wrap(a.prompt ?? "", width));
@@ -454,9 +465,20 @@ export function openWorkflowNavigator(
             if (id) ui.notify(manager.stop(id) ? `Stopped ${id}` : `Cannot stop ${id}`, "info");
             break;
           }
-          case "restart":
-            ui.notify("Restarting a single agent isn't supported yet", "warning");
+          case "restart": {
+            // Restart re-runs the whole workflow from scratch as a fresh
+            // background run (per-agent restart isn't meaningful — agents are
+            // driven by the script). The new run auto-delivers when it finishes.
+            const id = state.activeRunId(model);
+            const run = id ? manager.listRuns().find((r) => r.runId === id) : undefined;
+            if (!run?.script) {
+              ui.notify(id ? `Cannot restart ${id} (no script saved)` : "No run selected to restart", "warning");
+              break;
+            }
+            const { runId: newId } = manager.startInBackground(run.script, run.args);
+            ui.notify(`Restarted ${run.workflowName || "workflow"} as ${newId}`, "info");
             break;
+          }
           case "save": {
             const id = state.activeRunId(model);
             const run = id ? manager.listRuns().find((r) => r.runId === id) : undefined;

package/src/workflow.ts

@@ -48,6 +48,8 @@ export interface SharedRuntime {
 export interface WorkflowRunOptions extends WorkflowAgentOptions {
   args?: unknown;
   agent?: Pick<WorkflowAgent, "run">;
+  /** The session's main model (provider/id), shown in /workflows for default agents. */
+  mainModel?: string;
   concurrency?: number;
   tokenBudget?: number | null;
   signal?: AbortSignal;
@@ -72,7 +74,14 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
   onAgentStart?: (event: { label: string; phase?: string; prompt: string; model?: string }) => void;
-  onAgentEnd?: (event: { label: string; phase?: string; result: unknown; tokens?: number; worktree?: string }) => void;
+  onAgentEnd?: (event: {
+    label: string;
+    phase?: string;
+    result: unknown;
+    tokens?: number;
+    worktree?: string;
+    model?: string;
+  }) => void;
   onTokenUsage?: (usage: { input: number; output: number; total: number; cost: number }) => void;
 }
 
@@ -96,6 +105,12 @@ export interface AgentOptions<TSchemaDef extends TSchema | undefined = TSchema |
   label?: string;
   phase?: string;
   schema?: TSchemaDef;
+  /**
+   * Run this agent on a specific model (`provider/modelId` or a bare `modelId`).
+   * The workflow author chooses per-agent models per the routing policy in the
+   * tool guidelines (e.g. a lighter model for exploration, the main model for
+   * analysis). When omitted, the session's main model is used.
+   */
   model?: string;
   isolation?: "worktree";
   agentType?: string;
@@ -203,6 +218,10 @@ export async function runWorkflow<T = unknown>(
     const requestedLabel = agentOptions.label?.trim();
     // Precedence: explicit agentOptions.model > phase model (meta.phases[].model).
     const modelSpec = agentOptions.model ?? resolveModelForPhase(assignedPhase, routingConfig);
+    // For display in /workflows: the model this agent runs on — its explicit/phase
+    // spec, else the session's main model. The real resolved id overrides this via
+    // onModelResolved once the subagent session is created.
+    let displayModel = modelSpec ?? options.mainModel;
 
     // Deterministic resume key: assigned at lexical call time, before the limiter,
     // so parallel()/pipeline() fan-out is reproducible for a fixed script.
@@ -215,8 +234,8 @@ export async function runWorkflow<T = unknown>(
     if (cached && cached.hash === callHash) {
       shared.agentCount++;
       const label = requestedLabel || defaultAgentLabel(assignedPhase, shared.agentCount);
-      options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
-      options.onAgentEnd?.({ label, phase: assignedPhase, result: cached.result, tokens: 0 });
+      options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: displayModel });
+      options.onAgentEnd?.({ label, phase: assignedPhase, result: cached.result, tokens: 0, model: displayModel });
       return cached.result;
     }
 
@@ -225,7 +244,7 @@ export async function runWorkflow<T = unknown>(
       const label = requestedLabel || defaultAgentLabel(assignedPhase, shared.agentCount);
       const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
 
-      options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
+      options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: displayModel });
 
       // Optional per-agent worktree isolation (deterministic name -> stable resume keys).
       let worktree: Worktree | undefined;
@@ -262,6 +281,9 @@ export async function runWorkflow<T = unknown>(
             instructions: buildAgentInstructions(assignedPhase, agentOptions),
             model: modelSpec,
             cwd: runCwd,
+            onModelResolved: (id: string) => {
+              displayModel = id;
+            },
             onUsage: (u: AgentUsage) => {
               usage = u;
             },
@@ -274,7 +296,7 @@ export async function runWorkflow<T = unknown>(
 
         const tokens = recordTokens(result);
         options.onAgentJournal?.({ index: callIndex, hash: callHash, result });
-        options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens, worktree: runCwd });
+        options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens, worktree: runCwd, model: displayModel });
         return result;
       } catch (error) {
         if (options.signal?.aborted) throw error;