@quintinshaw/pi-dynamic-workflows 1.0.0 → 1.2.0

package/README.md

@@ -86,8 +86,11 @@ return { inventory, summary }
 | `label` | string | Human-readable label for progress display |
 | `phase` | string | Override the current phase for this agent |
 | `schema` | object | JSON Schema for structured output |
+| `model` | string | Run this agent on a specific model — `provider/modelId` or a bare `modelId` |
 | `timeoutMs` | number | Override the default 5-minute agent timeout |
 
+Models can also be set per phase via `meta.phases[].model`. Precedence is `opts.model` > phase model > session default; an unknown model logs a warning and falls back to the default.
+
 ### Structured output
 
 Pass a JSON Schema via `opts.schema` and the subagent returns a validated object:
@@ -116,16 +119,16 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 
 - **Core runtime** — `agent` / `parallel` / `pipeline` / `phase` / `log` / `budget` in a sandboxed script
 - **Structured output** — JSON-Schema-validated subagent results
+- **Real token & cost accounting** — read from each subagent's SDK session (input / output / total / cost), with a character estimate only as fallback when a provider reports no usage; `budget` gates on the real total
+- **Real per-agent / per-phase model routing** — `opts.model` and `meta.phases[].model` actually select the model (resolved against your authed model registry), with graceful fallback
 - **Safety limits** — 1000-agent cap (`maxAgents`), per-agent timeout (`agentTimeoutMs`), recoverable-vs-fatal error classification
-- **Live progress + token display**, `Esc` to abort
+- **Live progress + token/cost display**, `Esc` to abort
 - **Log persistence** to `.pi/workflows/runs/`
 
 ## Roadmap
 
 Tracked toward closer parity with Claude Code dynamic workflows:
 
-- **Real per-agent / per-phase model routing** (`opts.model`, `meta.phases[].model`)
-- **Real token accounting** via the SDK's session stats (today's display uses an estimate)
 - **Command surface** — `/workflows` (list / status / stop) and reachable background runs
 - **Resume** — journaled results, replay the unchanged prefix, run the rest live
 - **Worktree isolation** for parallel edits, and **bundled `/deep-research`**

package/dist/agent.d.ts

@@ -9,12 +9,35 @@ export interface WorkflowAgentOptions {
     /** Extra system guidance prepended to every subagent task. */
     instructions?: string;
 }
+/** Real token/cost usage for a single subagent run, read from the SDK session. */
+export interface AgentUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+    cost: number;
+}
 export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefined> {
     label?: string;
     schema?: TSchemaDef;
     tools?: ToolDefinition[];
     instructions?: string;
     signal?: AbortSignal;
+    /**
+     * Called once with this subagent's real usage, read from the session right
+     * before disposal. Fires on both the success and error paths so partial
+     * usage is never lost. `total === 0` means the provider reported no usage.
+     */
+    onUsage?: (usage: AgentUsage) => void;
+    /**
+     * Model spec for this subagent: either `provider/modelId` (unambiguous) or a
+     * bare `modelId`. When it can't be resolved, the session default is used and
+     * a warning is logged. When omitted, the session default applies.
+     */
+    model?: string;
+    /** Called with the resolved model id once known (for display/telemetry). */
+    onModelResolved?: (modelId: string) => void;
 }
 export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema ? Static<TSchemaDef> : string;
 export declare class WorkflowAgent {
@@ -22,7 +45,16 @@ export declare class WorkflowAgent {
     private readonly baseTools;
     private readonly sessionOptions;
     private readonly instructions?;
+    /** Lazily built once; shares the SDK's agentDir/auth so resolved models are authed. */
+    private registry?;
     constructor(options?: WorkflowAgentOptions);
+    private getRegistry;
+    /**
+     * Resolve a model spec to a Model. Accepts `provider/modelId` (unambiguous)
+     * or a bare `modelId` (prefers auth-configured models, then any known model).
+     * Returns undefined when nothing matches.
+     */
+    private resolveModel;
     run<TSchemaDef extends TSchema | undefined = undefined>(prompt: string, options?: AgentRunOptions<TSchemaDef>): Promise<AgentRunResult<TSchemaDef>>;
     private buildPrompt;
     private lastAssistantText;

package/dist/agent.js

@@ -1,22 +1,60 @@
-import { createAgentSession, createCodingTools, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { AuthStorage, createAgentSession, createCodingTools, getAgentDir, ModelRegistry, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { createStructuredOutputTool } from "./structured-output.js";
 export class WorkflowAgent {
     cwd;
     baseTools;
     sessionOptions;
     instructions;
+    /** Lazily built once; shares the SDK's agentDir/auth so resolved models are authed. */
+    registry;
     constructor(options = {}) {
         this.cwd = options.cwd ?? process.cwd();
         this.baseTools = options.tools ?? createCodingTools(this.cwd);
         this.sessionOptions = options.session ?? {};
         this.instructions = options.instructions;
     }
+    getRegistry() {
+        if (!this.registry) {
+            const dir = getAgentDir();
+            // Same agentDir/auth files createAgentSession uses by default, so a model
+            // resolved here carries valid credentials.
+            const auth = AuthStorage.create(join(dir, "auth.json"));
+            this.registry = ModelRegistry.create(auth, join(dir, "models.json"));
+        }
+        return this.registry;
+    }
+    /**
+     * Resolve a model spec to a Model. Accepts `provider/modelId` (unambiguous)
+     * or a bare `modelId` (prefers auth-configured models, then any known model).
+     * Returns undefined when nothing matches.
+     */
+    resolveModel(spec) {
+        const registry = this.getRegistry();
+        const slash = spec.indexOf("/");
+        if (slash > 0) {
+            return registry.find(spec.slice(0, slash), spec.slice(slash + 1));
+        }
+        return registry.getAvailable().find((m) => m.id === spec) ?? registry.getAll().find((m) => m.id === spec);
+    }
     async run(prompt, options = {}) {
         const capture = { called: false, value: undefined };
         const customTools = [...this.baseTools, ...(options.tools ?? [])];
         if (options.schema) {
             customTools.push(createStructuredOutputTool({ schema: options.schema, capture }));
         }
+        // Resolve a requested model spec to a Model object. A given-but-unresolved
+        // spec falls back to the session default (with a warning) rather than failing.
+        let resolvedModel;
+        if (options.model) {
+            resolvedModel = this.resolveModel(options.model);
+            if (resolvedModel) {
+                options.onModelResolved?.(`${resolvedModel.provider}/${resolvedModel.id}`);
+            }
+            else {
+                console.warn(`[workflow] model "${options.model}" not found; using session default`);
+            }
+        }
         const agentDir = getAgentDir();
         const { session } = await createAgentSession({
             cwd: this.cwd,
@@ -29,6 +67,8 @@ export class WorkflowAgent {
             settingsManager: SettingsManager.create(this.cwd, agentDir),
             customTools,
             ...this.sessionOptions,
+            // Per-call model wins over any sessionOptions.model.
+            ...(resolvedModel ? { model: resolvedModel } : {}),
         });
         let removeAbortListener;
         try {
@@ -52,6 +92,23 @@ export class WorkflowAgent {
         }
         finally {
             removeAbortListener?.();
+            // Read real usage before disposing — dispose tears down the session state.
+            if (options.onUsage) {
+                try {
+                    const { tokens, cost } = session.getSessionStats();
+                    options.onUsage({
+                        input: tokens.input,
+                        output: tokens.output,
+                        cacheRead: tokens.cacheRead,
+                        cacheWrite: tokens.cacheWrite,
+                        total: tokens.total,
+                        cost,
+                    });
+                }
+                catch {
+                    // Usage is best-effort; never let stats failure mask the real result/error.
+                }
+            }
             session.dispose();
         }
     }

package/dist/display.d.ts

@@ -29,6 +29,7 @@ export interface WorkflowSnapshot {
         input: number;
         output: number;
         total: number;
+        cost?: number;
     };
     runId?: string;
 }

package/dist/display.js

@@ -80,8 +80,10 @@ export function renderWorkflowLines(snapshot, options = {}) {
         : snapshot.runningCount > 0
             ? `, ${snapshot.runningCount} running`
             : "";
-    // Build header with token info
-    const tokenInfo = snapshot.tokenUsage ? ` · ${snapshot.tokenUsage.total.toLocaleString()} tokens` : "";
+    // Build header with token info (and cost when the provider reports it)
+    const usage = snapshot.tokenUsage;
+    const costInfo = usage?.cost ? ` · $${usage.cost.toFixed(4)}` : "";
+    const tokenInfo = usage ? ` · ${usage.total.toLocaleString()} tokens${costInfo}` : "";
     const lines = [
         `◆ Workflow: ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state}${tokenInfo})`,
     ];

package/dist/workflow-tool.js

@@ -160,8 +160,10 @@ export function createWorkflowTool(options = {}) {
             snapshot.durationMs = result.durationMs;
             snapshot = recomputeWorkflowSnapshot(snapshot);
             display.complete(snapshot);
-            // Format token usage
-            const tokenInfo = result.tokenUsage ? `\n\nToken usage: ${result.tokenUsage.total.toLocaleString()} tokens` : "";
+            // Format token usage (include cost when the provider reports it)
+            const tokenInfo = result.tokenUsage
+                ? `\n\nToken usage: ${result.tokenUsage.total.toLocaleString()} tokens${result.tokenUsage.cost ? ` ($${result.tokenUsage.cost.toFixed(4)})` : ""}`
+                : "";
             return {
                 content: [
                     {

package/dist/workflow.d.ts

@@ -31,6 +31,7 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
         label: string;
         phase?: string;
         prompt: string;
+        model?: string;
     }) => void;
     onAgentEnd?: (event: {
         label: string;
@@ -42,6 +43,7 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
         input: number;
         output: number;
         total: number;
+        cost: number;
     }) => void;
 }
 export interface WorkflowRunResult<T = unknown> {
@@ -56,6 +58,7 @@ export interface WorkflowRunResult<T = unknown> {
         input: number;
         output: number;
         total: number;
+        cost: number;
     };
 }
 export interface AgentOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined> {

package/dist/workflow.js

@@ -4,10 +4,13 @@ import { WorkflowAgent } from "./agent.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENTS_PER_RUN, MAX_CONCURRENCY } from "./config.js";
 import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
 import { createWorkflowLogger } from "./logger.js";
+import { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
 const DETERMINISM_BLOCKLIST = /\bDate\s*\.\s*now\b|\bMath\s*\.\s*random\b|\bnew\s+Date\s*\(\s*\)/;
 export async function runWorkflow(script, options = {}) {
     const started = Date.now();
     const { meta, body } = parseWorkflowScript(script);
+    // Per-phase model routing from meta.phases[].model (empty when none declared).
+    const routingConfig = parseModelRoutingFromMeta(meta.phases);
     const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
     const agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
     const runId = options.runId ?? `run-${started.toString(36)}`;
@@ -23,7 +26,7 @@ export async function runWorkflow(script, options = {}) {
         phases: [],
         agentCount: 0,
         spent: 0,
-        tokenUsage: { input: 0, output: 0, total: 0 },
+        tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
     };
     const agentRunner = options.agent ?? new WorkflowAgent(options);
     const concurrency = Math.max(1, Math.min(options.concurrency ?? Math.max(1, (globalThis.navigator?.hardwareConcurrency ?? 8) - 2), MAX_CONCURRENCY));
@@ -62,11 +65,27 @@ export async function runWorkflow(script, options = {}) {
         }
         const assignedPhase = agentOptions.phase ?? state.currentPhase;
         const requestedLabel = agentOptions.label?.trim();
+        // Precedence: explicit agentOptions.model > phase model (meta.phases[].model).
+        const modelSpec = agentOptions.model ?? resolveModelForPhase(assignedPhase, routingConfig);
         return limiter(async () => {
             state.agentCount++;
             const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
             const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
-            options.onAgentStart?.({ label, phase: assignedPhase, prompt });
+            options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
+            // Captured from the subagent's real session usage; falls back to an
+            // estimate when the provider reports no usage (total === 0).
+            let usage;
+            const recordTokens = (result) => {
+                const tokens = usage && usage.total > 0 ? usage.total : estimateTokens(result) + estimateTokens(prompt);
+                if (usage) {
+                    state.tokenUsage.input += usage.input;
+                    state.tokenUsage.output += usage.output;
+                    state.tokenUsage.cost += usage.cost;
+                }
+                state.tokenUsage.total += tokens;
+                state.spent += tokens;
+                return tokens;
+            };
             try {
                 throwIfAborted();
                 // Run agent with timeout
@@ -75,12 +94,13 @@ export async function runWorkflow(script, options = {}) {
                     schema: agentOptions.schema,
                     signal: options.signal,
                     instructions: buildAgentInstructions(assignedPhase, agentOptions),
+                    model: modelSpec,
+                    onUsage: (u) => {
+                        usage = u;
+                    },
                 }), timeout, `Agent "${label}" timed out after ${timeout}ms`);
                 throwIfAborted();
-                // Estimate token usage
-                const tokens = estimateTokens(result) + estimateTokens(prompt);
-                state.spent += tokens;
-                state.tokenUsage.total += tokens;
+                const tokens = recordTokens(result);
                 options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens });
                 return result;
             }
@@ -89,9 +109,8 @@ export async function runWorkflow(script, options = {}) {
                     throw error;
                 const workflowError = wrapError(error, { agentLabel: label });
                 logger.error(`agent ${label} failed: ${workflowError.message}`);
-                const errorTokens = estimateTokens(prompt);
-                state.tokenUsage.total += errorTokens;
-                options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens: errorTokens });
+                const tokens = recordTokens(null);
+                options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens });
                 // Return null for recoverable errors
                 if (workflowError.recoverable) {
                     return null;
@@ -337,8 +356,7 @@ function buildAgentInstructions(phase, options) {
         lines.push(`Act as workflow subagent type: ${options.agentType}`);
     if (options.isolation)
         lines.push(`Requested isolation: ${options.isolation}`);
-    if (options.model)
-        lines.push(`Requested model: ${options.model}`);
+    // Note: options.model is applied for real via the session, not injected as prose.
     return lines.length ? lines.join("\n") : undefined;
 }
 function estimateTokens(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quintinshaw/pi-dynamic-workflows",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Claude-Code-style dynamic workflow orchestration for Pi.",
   "type": "module",
   "main": "./dist/index.js",

package/src/agent.ts

@@ -1,9 +1,12 @@
-import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import { join } from "node:path";
+import type { AssistantMessage, Model, TextContent } from "@earendil-works/pi-ai";
 import {
+  AuthStorage,
   type CreateAgentSessionOptions,
   createAgentSession,
   createCodingTools,
   getAgentDir,
+  ModelRegistry,
   SessionManager,
   SettingsManager,
   type ToolDefinition,
@@ -21,12 +24,36 @@ export interface WorkflowAgentOptions {
   instructions?: string;
 }
 
+/** Real token/cost usage for a single subagent run, read from the SDK session. */
+export interface AgentUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+  cost: number;
+}
+
 export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefined> {
   label?: string;
   schema?: TSchemaDef;
   tools?: ToolDefinition[];
   instructions?: string;
   signal?: AbortSignal;
+  /**
+   * Called once with this subagent's real usage, read from the session right
+   * before disposal. Fires on both the success and error paths so partial
+   * usage is never lost. `total === 0` means the provider reported no usage.
+   */
+  onUsage?: (usage: AgentUsage) => void;
+  /**
+   * Model spec for this subagent: either `provider/modelId` (unambiguous) or a
+   * bare `modelId`. When it can't be resolved, the session default is used and
+   * a warning is logged. When omitted, the session default applies.
+   */
+  model?: string;
+  /** Called with the resolved model id once known (for display/telemetry). */
+  onModelResolved?: (modelId: string) => void;
 }
 
 export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema
@@ -38,6 +65,8 @@ export class WorkflowAgent {
   private readonly baseTools: ToolDefinition[];
   private readonly sessionOptions: Partial<CreateAgentSessionOptions>;
   private readonly instructions?: string;
+  /** Lazily built once; shares the SDK's agentDir/auth so resolved models are authed. */
+  private registry?: ModelRegistry;
 
   constructor(options: WorkflowAgentOptions = {}) {
     this.cwd = options.cwd ?? process.cwd();
@@ -46,6 +75,31 @@ export class WorkflowAgent {
     this.instructions = options.instructions;
   }
 
+  private getRegistry(): ModelRegistry {
+    if (!this.registry) {
+      const dir = getAgentDir();
+      // Same agentDir/auth files createAgentSession uses by default, so a model
+      // resolved here carries valid credentials.
+      const auth = AuthStorage.create(join(dir, "auth.json"));
+      this.registry = ModelRegistry.create(auth, join(dir, "models.json"));
+    }
+    return this.registry;
+  }
+
+  /**
+   * Resolve a model spec to a Model. Accepts `provider/modelId` (unambiguous)
+   * or a bare `modelId` (prefers auth-configured models, then any known model).
+   * Returns undefined when nothing matches.
+   */
+  private resolveModel(spec: string): Model<any> | undefined {
+    const registry = this.getRegistry();
+    const slash = spec.indexOf("/");
+    if (slash > 0) {
+      return registry.find(spec.slice(0, slash), spec.slice(slash + 1));
+    }
+    return registry.getAvailable().find((m) => m.id === spec) ?? registry.getAll().find((m) => m.id === spec);
+  }
+
   async run<TSchemaDef extends TSchema | undefined = undefined>(
     prompt: string,
     options: AgentRunOptions<TSchemaDef> = {},
@@ -57,6 +111,18 @@ export class WorkflowAgent {
       customTools.push(createStructuredOutputTool({ schema: options.schema, capture }) as unknown as ToolDefinition);
     }
 
+    // Resolve a requested model spec to a Model object. A given-but-unresolved
+    // spec falls back to the session default (with a warning) rather than failing.
+    let resolvedModel: Model<any> | undefined;
+    if (options.model) {
+      resolvedModel = this.resolveModel(options.model);
+      if (resolvedModel) {
+        options.onModelResolved?.(`${resolvedModel.provider}/${resolvedModel.id}`);
+      } else {
+        console.warn(`[workflow] model "${options.model}" not found; using session default`);
+      }
+    }
+
     const agentDir = getAgentDir();
     const { session } = await createAgentSession({
       cwd: this.cwd,
@@ -69,6 +135,8 @@ export class WorkflowAgent {
       settingsManager: SettingsManager.create(this.cwd, agentDir),
       customTools,
       ...this.sessionOptions,
+      // Per-call model wins over any sessionOptions.model.
+      ...(resolvedModel ? { model: resolvedModel } : {}),
     });
 
     let removeAbortListener: (() => void) | undefined;
@@ -93,6 +161,22 @@ export class WorkflowAgent {
       return this.lastAssistantText(session.messages) as AgentRunResult<TSchemaDef>;
     } finally {
       removeAbortListener?.();
+      // Read real usage before disposing — dispose tears down the session state.
+      if (options.onUsage) {
+        try {
+          const { tokens, cost } = session.getSessionStats();
+          options.onUsage({
+            input: tokens.input,
+            output: tokens.output,
+            cacheRead: tokens.cacheRead,
+            cacheWrite: tokens.cacheWrite,
+            total: tokens.total,
+            cost,
+          });
+        } catch {
+          // Usage is best-effort; never let stats failure mask the real result/error.
+        }
+      }
       session.dispose();
     }
   }

package/src/display.ts

@@ -32,6 +32,7 @@ export interface WorkflowSnapshot {
     input: number;
     output: number;
     total: number;
+    cost?: number;
   };
   runId?: string;
 }
@@ -143,8 +144,10 @@ export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: Workflo
       : snapshot.runningCount > 0
         ? `, ${snapshot.runningCount} running`
         : "";
-  // Build header with token info
-  const tokenInfo = snapshot.tokenUsage ? ` · ${snapshot.tokenUsage.total.toLocaleString()} tokens` : "";
+  // Build header with token info (and cost when the provider reports it)
+  const usage = snapshot.tokenUsage;
+  const costInfo = usage?.cost ? ` · $${usage.cost.toFixed(4)}` : "";
+  const tokenInfo = usage ? ` · ${usage.total.toLocaleString()} tokens${costInfo}` : "";
   const lines = [
     `◆ Workflow: ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state}${tokenInfo})`,
   ];

package/src/workflow-tool.ts

@@ -198,8 +198,12 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
       snapshot = recomputeWorkflowSnapshot(snapshot);
       display.complete(snapshot);
 
-      // Format token usage
-      const tokenInfo = result.tokenUsage ? `\n\nToken usage: ${result.tokenUsage.total.toLocaleString()} tokens` : "";
+      // Format token usage (include cost when the provider reports it)
+      const tokenInfo = result.tokenUsage
+        ? `\n\nToken usage: ${result.tokenUsage.total.toLocaleString()} tokens${
+            result.tokenUsage.cost ? ` ($${result.tokenUsage.cost.toFixed(4)})` : ""
+          }`
+        : "";
 
       return {
         content: [

package/src/workflow.ts

@@ -2,10 +2,12 @@ import vm from "node:vm";
 import type { Node } from "acorn";
 import { parse } from "acorn";
 import type { TSchema } from "typebox";
+import type { AgentUsage } from "./agent.js";
 import { WorkflowAgent, type WorkflowAgentOptions } from "./agent.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENTS_PER_RUN, MAX_CONCURRENCY } from "./config.js";
 import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
 import { createWorkflowLogger } from "./logger.js";
+import { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
 
 export interface WorkflowMetaPhase {
   title: string;
@@ -36,9 +38,9 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
   runId?: string;
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
-  onAgentStart?: (event: { label: string; phase?: string; prompt: string }) => void;
+  onAgentStart?: (event: { label: string; phase?: string; prompt: string; model?: string }) => void;
   onAgentEnd?: (event: { label: string; phase?: string; result: unknown; tokens?: number }) => void;
-  onTokenUsage?: (usage: { input: number; output: number; total: number }) => void;
+  onTokenUsage?: (usage: { input: number; output: number; total: number; cost: number }) => void;
 }
 
 export interface WorkflowRunResult<T = unknown> {
@@ -53,6 +55,7 @@ export interface WorkflowRunResult<T = unknown> {
     input: number;
     output: number;
     total: number;
+    cost: number;
   };
 }
 
@@ -77,6 +80,7 @@ interface RuntimeState {
     input: number;
     output: number;
     total: number;
+    cost: number;
   };
 }
 
@@ -90,6 +94,8 @@ export async function runWorkflow<T = unknown>(
 ): Promise<WorkflowRunResult<T>> {
   const started = Date.now();
   const { meta, body } = parseWorkflowScript(script);
+  // Per-phase model routing from meta.phases[].model (empty when none declared).
+  const routingConfig = parseModelRoutingFromMeta(meta.phases);
   const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
   const agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
   const runId = options.runId ?? `run-${started.toString(36)}`;
@@ -107,7 +113,7 @@ export async function runWorkflow<T = unknown>(
     phases: [],
     agentCount: 0,
     spent: 0,
-    tokenUsage: { input: 0, output: 0, total: 0 },
+    tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
   };
 
   const agentRunner = options.agent ?? new WorkflowAgent(options);
@@ -161,13 +167,30 @@ export async function runWorkflow<T = unknown>(
 
     const assignedPhase = agentOptions.phase ?? state.currentPhase;
     const requestedLabel = agentOptions.label?.trim();
+    // Precedence: explicit agentOptions.model > phase model (meta.phases[].model).
+    const modelSpec = agentOptions.model ?? resolveModelForPhase(assignedPhase, routingConfig);
 
     return limiter(async () => {
       state.agentCount++;
       const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
       const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
 
-      options.onAgentStart?.({ label, phase: assignedPhase, prompt });
+      options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
+
+      // Captured from the subagent's real session usage; falls back to an
+      // estimate when the provider reports no usage (total === 0).
+      let usage: AgentUsage | undefined;
+      const recordTokens = (result: unknown): number => {
+        const tokens = usage && usage.total > 0 ? usage.total : estimateTokens(result) + estimateTokens(prompt);
+        if (usage) {
+          state.tokenUsage.input += usage.input;
+          state.tokenUsage.output += usage.output;
+          state.tokenUsage.cost += usage.cost;
+        }
+        state.tokenUsage.total += tokens;
+        state.spent += tokens;
+        return tokens;
+      };
 
       try {
         throwIfAborted();
@@ -179,6 +202,10 @@ export async function runWorkflow<T = unknown>(
             schema: agentOptions.schema,
             signal: options.signal,
             instructions: buildAgentInstructions(assignedPhase, agentOptions),
+            model: modelSpec,
+            onUsage: (u: AgentUsage) => {
+              usage = u;
+            },
           } as any),
           timeout,
           `Agent "${label}" timed out after ${timeout}ms`,
@@ -186,11 +213,7 @@ export async function runWorkflow<T = unknown>(
 
         throwIfAborted();
 
-        // Estimate token usage
-        const tokens = estimateTokens(result) + estimateTokens(prompt);
-        state.spent += tokens;
-        state.tokenUsage.total += tokens;
-
+        const tokens = recordTokens(result);
         options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens });
         return result;
       } catch (error) {
@@ -198,9 +221,8 @@ export async function runWorkflow<T = unknown>(
 
         const workflowError = wrapError(error, { agentLabel: label });
         logger.error(`agent ${label} failed: ${workflowError.message}`);
-        const errorTokens = estimateTokens(prompt);
-        state.tokenUsage.total += errorTokens;
-        options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens: errorTokens });
+        const tokens = recordTokens(null);
+        options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens });
 
         // Return null for recoverable errors
         if (workflowError.recoverable) {
@@ -464,7 +486,7 @@ function buildAgentInstructions(phase: string | undefined, options: AgentOptions
   if (phase) lines.push(`Workflow phase: ${phase}`);
   if (options.agentType) lines.push(`Act as workflow subagent type: ${options.agentType}`);
   if (options.isolation) lines.push(`Requested isolation: ${options.isolation}`);
-  if (options.model) lines.push(`Requested model: ${options.model}`);
+  // Note: options.model is applied for real via the session, not injected as prose.
   return lines.length ? lines.join("\n") : undefined;
 }