@fyeeme/pi-dynamic-workflows 1.1.0 → 2.0.2

package/README.md

@@ -1,5 +1,12 @@
 # @fyeeme/pi-dynamic-workflows
 
+**2.0.0 — major release** (from 1.1.0 on npm), part of the 2.0 extensions family wave:
+
+- **Composed sub-agent stack** — the extension factory composes [`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents) 2.1.1 from its npm dependency: the live agent fleet surface and the `subagent` tool work out of the box; no manifest path wiring, no separate install.
+- **Run persistence** — journaled runs under `.pi/workflows/` (journal + manifest): a re-run resumes cached agent calls keyed by `sha256(workflow + prompt + signature)` with zero re-dispatch, and the manifest tracks live state for inspection.
+- **Per-call budget override** — `run_workflow` accepts a `budget` object that merges over the workflow definition's own `maxAgents`/`maxTokens`, making "halve the fan-out for large diffs" an actual parameter.
+- **Authoring aids shipped** — `workflow-author` skill, `/wf-*` prompts, and seed workflows (`review-local-diff`, `review-extension`) using `import type` for load determinism.
+
 **Deterministic TypeScript workflow orchestration for [pi](https://github.com/earendil-works/pi-mono).**
 
 Define a workflow as a declarative list of typed steps, run it, and get resumable, budget-bounded, abortable execution. Fuses the pi-dynamic-workflows design (10 step primitives + heuristic planner + outcome collectors) with Claude Code's workflow-engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort, dynamic budget, runaway caps).
@@ -20,16 +27,20 @@ A workflow run is a list of steps (`agent` / `code` / `log` / `fan_out` / `loop_
 
 ---
 
-## Install
+**Batteries included**: this package's extension factory composes
+[`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents)
+(the single below-editor fleet surface with its conversation viewer, and the `subagent` tool)
+from its version-pinned dependency copy, so workflow runs are observable out
+of the box. A standalone pi-subagents install is optional and coexists
+(idempotent composition).
 
-This is a pi extension package (workspace / local), not yet published to npm. From a pi workspace:
+## Install
 
 ```bash
-npm install --ignore-scripts   # hydrate (the package is a workspace dep)
+pi install npm:@fyeeme/pi-dynamic-workflows
 ```
 
-This resolves [`@fyeeme/pi-subagent-core`](https://www.npmjs.com/package/@fyeeme/pi-subagent-core)
-(`^0.5.0`, from the npm registry — no sibling-repo layout requirement).
+This resolves [`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents) 2.1.1 from the npm registry (the composed sub-agent stack lights up with no separate install).
 
 Then import the public API from the package root module (a TypeScript barrel; the package ships `.ts` source):
 
@@ -38,10 +49,10 @@ import { defineWorkflow, runWorkflow } from "@fyeeme/pi-dynamic-workflows/src/in
 ```
 
 > The package's `pi.extensions` entry registers the `run_workflow` tool plus
-> the shared sub-agent UI from pi-subagent-core (live agent widget above the
-> editor, FleetView below it, and the `/agents` transcript viewer — every
-> spawned workflow agent appears there under its step id). The engine is also
-> fully usable via the imports shown here.
+> the shared sub-agent UI from pi-subagents (the below-editor fleet roster —
+> every spawned workflow agent appears there under its stable id; ↓ at an
+> empty editor opens the list, Enter shows an agent's live transcript). The
+> engine is also fully usable via the imports shown here.
 
 ---
 
@@ -169,6 +180,9 @@ defineWorkflow({
 // results: { candidates, winner, judges: [{winner, reason}] }
 
 // Classify input, then run the matching route's sub-steps.
+// On pi 0.99+ hosts with a classifier model, the category comes from
+// ModelRuntime.classify() (no classification subprocess); without one, an
+// agent answers the classification. The step result records which path ran.
 defineWorkflow({
 	name: "route",
 	steps: [
@@ -184,7 +198,7 @@ defineWorkflow({
 		},
 	],
 });
-// results: { category, matched, route: StepResult[], routeStatus }
+// results: { category, matched, route: StepResult[], routeStatus, path }
 ```
 
 Judge/classifier JSON is parsed leniently (LLMs return `"true"`/`"0"` as strings); route nesting is depth-capped to catch cycles.
@@ -303,7 +317,7 @@ const result = await runWorkflow({ workflow: wf, cwd: tempDir, now: 1000, dispat
 | `loop_until` | `prompt(ctx,i)`, `until(ctx,i)`, `maxIterations?` | array of per-iteration outputs |
 | `adversarial` | `produce`, `rubric[]`, `judges?`, `minPass?` | `{ candidate, passed, passCount, judges }` |
 | `tournament` | `candidates`, `judges`, `produce` | `{ candidates, winner, judges }` |
-| `classify_route` | `classifier`, `routes: Record<cat, Step[]>`, `fallback?` | `{ category, matched, route, routeStatus }` |
+| `classify_route` | `classifier`, `routes: Record<cat, Step[]>`, `fallback?` | `{ category, matched, route, routeStatus, path }` |
 | `sub_workflow` | `workflow: WorkflowDefinition`, `input?`, `inheritBudget?` | `{ steps, status, workflowName, error }` |
 | `loop_until_dry` | `agent(item, i)`, `keyOf?`, `merge?`, `maxRounds?`, `dryThreshold?` | array of discovered items |
 

package/README.zh-CN.md

@@ -20,6 +20,12 @@
 
 ---
 
+**开箱即用**：本包的扩展工厂会组合
+[`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents)
+（实时代理 UI——编辑器上方 widget、FleetView、`/agents`——以及 `subagent`
+工具），且版本钉定在自身依赖副本上，工作流运行的可观测性开箱即得。
+单独安装 pi-subagents 是可选的，二者可共存（组合幂等）。
+
 ## 安装
 
 这是一个 pi 扩展包（workspace / 本地），尚未发布到 npm。在 pi workspace 中：
@@ -28,7 +34,7 @@
 npm install --ignore-scripts   # 水合（本包是 workspace 依赖）
 ```
 
-这会解析 npm registry 上的 [`@fyeeme/pi-subagent-core`](https://www.npmjs.com/package/@fyeeme/pi-subagent-core)（`^0.5.0`，无需保持同级仓库目录结构）。
+这会解析 npm registry 上的 [`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents)（无需保持同级仓库目录结构）。
 
 随后从包根模块导入公共 API（TypeScript barrel，包直接以 `.ts` 源码分发）：
 
@@ -36,7 +42,7 @@ npm install --ignore-scripts   # 水合（本包是 workspace 依赖）
 import { defineWorkflow, runWorkflow } from "@fyeeme/pi-dynamic-workflows/src/index.ts";
 ```
 
-> 包的 `pi.extensions` 入口注册 `run_workflow` 工具，并接入 pi-subagent-core 的共享子代理 UI（编辑器上方实时 agent widget、下方 FleetView、`/agents` 转录查看器——每个工作流 agent 以其 step id 出现在其中）。引擎本身也可经上述导入直接使用。
+> 包的 `pi.extensions` 入口注册 `run_workflow` 工具，并接入 pi-subagents 的共享子代理 UI（编辑器上方实时 agent widget、下方 FleetView、`/agents` 转录查看器——每个工作流 agent 以其 step id 出现在其中；需先安装 @fyeeme/pi-subagents，见上方提示）。引擎本身也可经上述导入直接使用。
 
 ---
 
@@ -179,7 +185,7 @@ defineWorkflow({
 		},
 	],
 });
-// results: { category, matched, route: StepResult[], routeStatus }
+// results: { category, matched, route: StepResult[], routeStatus, path }
 ```
 
 评判/分类的 JSON 采用宽松解析（LLM 常把 `"true"`/`"0"` 当字符串返回）；路由嵌套有深度上限以防循环。

package/index.ts

@@ -6,7 +6,7 @@
  * only adapts the agent's JSON args into the code-form WorkflowDefinition and
  * runs it with the default dispatch (real `pi --mode json` subprocesses).
  *
- * Live progress UI is delegated to the shared `@fyeeme/pi-subagent-core`
+ * Live progress UI is delegated to the shared `@fyeeme/pi-subagents`
  * extension (registered via the `pi.extensions` manifest alongside this
  * entry): every spawned workflow agent notifies the process-global monitor
  * through spawnAgent, rendering in the shared above-editor agent widget, the
@@ -15,17 +15,22 @@
  * `/wf-inspect` command were removed in favor of that shared surface.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { truncateHead } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
+import piSubagents from "@fyeeme/pi-subagents";
 import { defineWorkflow, runWorkflow } from "./src/index.ts";
+import { createClassifyHook } from "./src/classifier-hook.ts";
 import type { Budget, StepContext, StepDefinition, WorkflowDefinition } from "./src/types.ts";
 import { WorkflowError } from "./src/errors.ts";
+import { discoverWorkflowLibrary, loadLibraryWorkflow } from "./src/library.ts";
 
 // ---------------------------------------------------------------------------
 // Parameter schema (the JSON-serializable workflow subset)
 // ---------------------------------------------------------------------------
 
 const BudgetExhaustPolicy = Type.Optional(
-	Type.Union([Type.Literal("throw"), Type.Literal("null")], {
+	StringEnum(["throw", "null"] as const, {
 		description: "Budget-exhaustion policy for this step: \"throw\" (default) aborts the run; \"null\" degrades this step to a null result so siblings/downstream continue (the run result records degraded steps).",
 	}),
 );
@@ -76,7 +81,7 @@ const StepSchema = Type.Union([
 	Type.Object({
 		id: Type.String(),
 		type: Type.Literal("classify_route"),
-		prompt: Type.String({ description: "Classifier prompt; agent should reply {category: \"...\"}" }),
+		prompt: Type.String({ description: "Classification prompt; routing runs on a classifier model when the host has one (pi 0.99), otherwise an agent replies with JSON {category: \"...\"}" }),
 		routes: Type.Record(
 			Type.String(),
 			Type.Array(Type.Object({ id: Type.String(), prompt: Type.String(), model: Type.Optional(Type.String()) })),
@@ -103,7 +108,30 @@ const WorkflowSchema = Type.Object({
 });
 
 const RunWorkflowParams = Type.Object({
-	workflow: WorkflowSchema,
+	source: Type.Optional(
+		StringEnum(["inline", "library"] as const, {
+			description:
+				'Where the workflow comes from. "inline" (default): the `workflow` parameter (JSON subset). "library": a named workflow from the discovered library (bundled workflows/ + project .pi/workflows/lib/, project overrides bundled) — full step set incl. loop_until, loaded through the determinism guard.',
+			default: "inline",
+		}),
+	),
+	name: Type.Optional(
+		Type.String({ description: 'Library workflow name (required for source: "library").' }),
+	),
+	workflow: Type.Optional(WorkflowSchema),
+	budget: Type.Optional(
+		Type.Object(
+			{
+				maxAgents: Type.Optional(Type.Number()),
+				maxTokens: Type.Optional(Type.Number()),
+				maxDurationMs: Type.Optional(Type.Number()),
+			},
+			{
+				description:
+					"Per-call budget override (library mode only — inline workflows declare budget inside `workflow.budget`). Fields merge over the workflow definition's own budget; use it to tighten a library workflow for a large input without editing the definition. Omitted fields keep the definition's values.",
+			},
+		),
+	),
 	input: Type.Optional(Type.String({ description: "Initial ctx.input (also {{input}} in prompts)" })),
 	cwd: Type.Optional(Type.String({ description: "Working dir + journal base. Default: session cwd" })),
 	now: Type.Optional(Type.Number({ description: "Deterministic inception ms (resume seed). Default: Date.now()" })),
@@ -287,6 +315,13 @@ function dropInvalidModel(id: string, model: string | undefined, validIds: Set<s
 }
 
 export default function (pi: ExtensionAPI): void {
+	// Compose the subagent stack (live agent UI — widget / FleetView /agents —
+	// and the `subagent` tool) from the pinned dependency copy. The tool
+	// registers exactly once per process (guard in pi-subagents' index.ts):
+	// coexists with a standalone pi-subagents install and with other consumers
+	// (pi-review) composing it.
+	piSubagents(pi);
+
 	pi.registerTool({
 		name: "run_workflow",
 		label: "Run workflow",
@@ -301,44 +336,87 @@ export default function (pi: ExtensionAPI): void {
 		parameters: RunWorkflowParams,
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			// Scoped-models: when the session restricts models (--models /
-			// enabledModels), validate step models against that scope; otherwise
-			// fall back to the full registry. Invalid ids (e.g. "sonnet") are
-			// dropped so the subprocess uses the default session model.
-			const scoped = ctx.scopedModels;
-			const validIds = scoped && scoped.length > 0
-				? new Set(scoped.map((s) => s.model.id))
-				: new Set(ctx.modelRegistry.getAll().map((m) => m.id));
-			const dropped: string[] = [];
-			const sanitizedSteps = params.workflow.steps.map((s) => {
-				const model = "model" in s ? dropInvalidModel(s.id, s.model, validIds, dropped) : undefined;
-				if (s.type === "classify_route") {
-					// Route/fallback sub-step models must be sanitized too — the schema
-					// promises "Invalid ids are dropped", which routeStepToCode otherwise
-					// passes straight through to the subprocess.
-					const routes = Object.fromEntries(
-						Object.entries(s.routes).map(([cat, rs]) => [
-							cat,
-							rs.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) })),
-						]),
-					) as typeof s.routes;
-					const fallback = s.fallback?.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) }));
-					return { ...s, model, routes, fallback };
+			// Library mode: resolve the named workflow from the discovered
+			// library (ast-guard + jiti via the existing loader), then run it
+			// through the same runner as inline mode. Unknown name → list the
+			// available workflows instead of spawning anything.
+			let workflowDef: WorkflowDefinition | undefined;
+			if (params.source === "library") {
+				if (!params.name)
+					throw new Error('run_workflow: source "library" requires a workflow `name`.');
+				try {
+					const entry = await loadLibraryWorkflow(params.name, params.cwd ?? ctx.cwd);
+					if (!entry) {
+						const lib = await discoverWorkflowLibrary(params.cwd ?? ctx.cwd);
+						const available = [...lib.values()]
+							.map((e) => `- ${e.name}${e.description ? ` — ${e.description}` : ""} (${e.filePath})`)
+							.join("\n");
+						throw new Error(`run_workflow: no library workflow named "${params.name}". Available:\n${available || "(none)"}`);
+					}
+					workflowDef = entry.workflow;
+				} catch (e) {
+					if (e instanceof Error && e.message.startsWith("run_workflow:")) throw e;
+					const msg = e instanceof Error ? e.message : String(e);
+					throw new Error(`run_workflow failed: ${msg}`);
 				}
-				return { ...s, model };
-			});
-			if (dropped.length > 0) {
-				ctx.ui.notify(`Invalid model(s) dropped, using default: ${dropped.join(", ")}`, "warning");
+			} else {
+				if (!params.workflow)
+					throw new Error('run_workflow: provide either a `workflow` (inline) or `name` with source "library".');
 			}
-			const sanitizedWorkflow = { ...params.workflow, steps: sanitizedSteps };
-			try {
-				const workflow = buildWorkflow(sanitizedWorkflow);
+
+				try {
+					let workflow: WorkflowDefinition;
+					if (params.source === "library") {
+						// Library workflows are authored TS (models already validated at
+						// authoring time; the determinism guard ran at load). A per-call
+						// `budget` merges over the definition's own budget.
+						workflow =
+							workflowDef && params.budget
+								? { ...workflowDef, budget: { ...workflowDef.budget, ...params.budget } }
+								: workflowDef!;
+					} else {
+					// Scoped-models: when the session restricts models (--models /
+					// enabledModels), validate step models against that scope; otherwise
+					// fall back to the full registry. Invalid ids (e.g. "sonnet") are
+					// dropped so the subprocess uses the default session model.
+					const scoped = ctx.scopedModels;
+					const validIds =
+						scoped && scoped.length > 0
+							? new Set(scoped.map((s) => s.model.id))
+							: new Set(ctx.modelRegistry.getAll().map((m) => m.id));
+					const dropped: string[] = [];
+					const sanitizedSteps = params.workflow!.steps.map((s) => {
+						const model = "model" in s ? dropInvalidModel(s.id, s.model, validIds, dropped) : undefined;
+						if (s.type === "classify_route") {
+							// Route/fallback sub-step models must be sanitized too — the schema
+							// promises "Invalid ids are dropped", which routeStepToCode otherwise
+							// passes straight through to the subprocess.
+							const routes = Object.fromEntries(
+								Object.entries(s.routes).map(([cat, rs]) => [
+									cat,
+									rs.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) })),
+								]),
+							) as typeof s.routes;
+							const fallback = s.fallback?.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) }));
+							return { ...s, model, routes, fallback };
+						}
+						return { ...s, model };
+					});
+					if (dropped.length > 0) {
+						ctx.ui.notify(`Invalid model(s) dropped, using default: ${dropped.join(", ")}`, "warning");
+					}
+					const sanitizedWorkflow = { ...params.workflow!, steps: sanitizedSteps };
+					workflow = buildWorkflow(sanitizedWorkflow);
+				}
 				const result = await runWorkflow({
 					workflow,
 					input: params.input,
 					cwd: params.cwd ?? ctx.cwd,
 					now: params.now ?? Date.now(),
 					signal,
+					// pi 0.99 classifier routing: classify_route prefers ModelRuntime.classify()
+					// when a classifier model is available; otherwise the agent path runs.
+					classify: createClassifyHook(ctx.modelRegistry),
 				});
 
 				const lines = [
@@ -347,14 +425,34 @@ export default function (pi: ExtensionAPI): void {
 					`stats: ${result.stats.agents} agent(s), ${result.stats.tokens} tokens, $${result.stats.cost.toFixed(4)}`,
 				];
 				if (result.error) lines.push(`error: ${result.error}`);
+				if (result.journalFile) lines.push(`full run details: ${result.journalFile}`);
+
+				// Failed/aborted runs are tool errors: throw so pi sets isError and
+				// reports the summary to the model (returning a value never sets the
+				// error flag). Completed runs with degraded steps stay a normal result.
+				const text = truncateHead(lines.join("\n"), { maxLines: 2000, maxBytes: 50_000 }).content;
+				if (result.status !== "completed") {
+					throw new Error(text);
+				}
+				const u = result.stats.usage;
 				return {
-					content: [{ type: "text" as const, text: lines.join("\n") }],
+					content: [{ type: "text" as const, text }],
 					details: result,
-					isError: result.status !== "completed",
+					// Surface nested-agent usage so pi's footer //session totals include it.
+					usage: u
+						? {
+								input: u.input,
+								output: u.output,
+								cacheRead: u.cacheRead,
+								cacheWrite: u.cacheWrite,
+								totalTokens: result.stats.tokens,
+								cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: result.stats.cost },
+							}
+						: undefined,
 				};
 			} catch (e) {
 				const msg = e instanceof Error ? e.message : String(e);
-				return { content: [{ type: "text" as const, text: `run_workflow failed: ${msg}` }], details: { error: msg }, isError: true };
+				throw new Error(`run_workflow failed: ${msg}`);
 			}
 		},
 	});

package/package.json

@@ -1,59 +1,68 @@
 {
-  "name": "@fyeeme/pi-dynamic-workflows",
-  "version": "1.1.0",
-  "description": "Deterministic TypeScript workflow orchestration for pi. Fuses the pi-dynamic-workflows design (declarative graph, 10 step primitives, heuristic planner, outcome collectors) with Claude Code's workflow engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort map, dynamic budget, runaway caps).",
-  "type": "module",
-  "license": "MIT",
-  "author": "fyeeme",
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "dynamic-workflow",
-    "workflow",
-    "orchestration",
-    "fan-out",
-    "pipeline",
-    "multi-agent"
-  ],
-  "files": [
-    "*.ts",
-    "src/**/*.ts",
-    "sessions/**/*.ts",
-    "README.md",
-    "README.zh-CN.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts",
-      "./node_modules/@fyeeme/pi-subagent-core/sub-agent.ts"
-    ]
-  },
-  "scripts": {
-    "test": "vitest --run",
-    "typecheck": "tsc"
-  },
-  "dependencies": {
-    "@fyeeme/pi-subagent-core": "^0.5.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.1",
-    "@earendil-works/pi-coding-agent": ">=0.84.1",
-    "@earendil-works/pi-tui": ">=0.84.1",
-    "jiti": ">=2.0.0",
-    "typebox": ">=1.0.0",
-    "typescript": ">=5.0.0"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.1",
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@earendil-works/pi-tui": "0.84.1",
-    "@types/node": "22.19.19",
-    "jiti": "2.7.0",
-    "typebox": "1.1.38",
-    "typescript": "5.9.3"
-  }
+	"name": "@fyeeme/pi-dynamic-workflows",
+	"version": "2.0.2",
+	"description": "Deterministic TypeScript workflow orchestration for pi. Fuses the pi-dynamic-workflows design (declarative graph, 10 step primitives, heuristic planner, outcome collectors) with Claude Code's workflow engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort map, dynamic budget, runaway caps).",
+	"type": "module",
+	"license": "MIT",
+	"author": "fyeeme",
+	"engines": {
+		"node": ">=18"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"dynamic-workflow",
+		"workflow",
+		"orchestration",
+		"fan-out",
+		"pipeline",
+		"multi-agent"
+	],
+	"files": [
+		"*.ts",
+		"src/**/*.ts",
+		"sessions/**/*.ts",
+		"workflows/**/*.ts",
+		"skills/**/*.md",
+		"prompts/**/*.md",
+		"README.md",
+		"README.zh-CN.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"skills": [
+			"skills/workflow-author"
+		],
+		"prompts": [
+			"prompts"
+		]
+	},
+	"scripts": {
+		"test": "vitest --run",
+		"typecheck": "tsc"
+	},
+	"dependencies": {
+		"@fyeeme/pi-subagents": "2.1.1"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": ">=0.99.0",
+		"@earendil-works/pi-coding-agent": ">=0.99.0",
+		"@earendil-works/pi-tui": ">=0.99.0",
+		"jiti": ">=2.0.0",
+		"typebox": ">=1.0.0",
+		"typescript": ">=5.0.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "0.99.2",
+		"@earendil-works/pi-coding-agent": "0.99.2",
+		"@earendil-works/pi-agent-core": "0.99.2",
+		"@earendil-works/pi-tui": "0.99.2",
+		"@types/node": "22.19.19",
+		"jiti": "2.7.0",
+		"typebox": "1.1.38",
+		"typescript": "5.9.3"
+	}
 }

package/prompts/implement-and-review.md

@@ -0,0 +1,29 @@
+---
+description: Implement → review → fix loop via successive subagent calls
+argument-hint: <what to implement>
+---
+Execute this three-stage loop with the `subagent` tool — one call per stage.
+You are the coordinator: pass each stage's complete output text into the next
+stage's `task` yourself (chain mode no longer exists).
+
+1. **Implement** — call `subagent` with agent `worker`, task: $@ plus any repo
+   context it needs. Ask for the final implementation summary in the result.
+
+2. **Review** — call `subagent` with agent `reviewer`. Its task must begin:
+   "Review the following implementation." followed by the worker's COMPLETE
+   result verbatim, plus the files/areas touched.
+
+3. **Fix** — if and only if the reviewer reported issues, one more `worker`
+   call: "Apply this feedback to your earlier implementation." followed by the
+   reviewer's findings verbatim.
+
+Rules:
+
+- Forward results between stages verbatim — never paraphrase or summarize;
+  each subagent has zero memory of its predecessor.
+- Run stages strictly sequentially; a later stage always needs the earlier
+  stage's full output as input.
+- Skip stages 2–3 only for trivial changes (< ~20 lines, no behavior change);
+  state explicitly that you did so and why.
+- Finish by reporting: what was implemented, the review verdict, and anything
+  still open.

package/prompts/wf-review.md

@@ -0,0 +1,30 @@
+---
+description: Heavy review pipeline via deterministic workflow (budget + resume + adversarial verify)
+---
+Run the heavy review pipeline now. Target: $@
+
+First resolve the diff yourself (run `git diff` against the appropriate
+range — upstream merge-base if configured, else HEAD; pass the diff text as
+the workflow `input`).
+
+Then call `run_workflow` with `source: "library"`:
+
+- For a plain local diff → name `review-local-diff` (5 finders at
+  parallelism 4, adversarial verify judges 3 / minPass 2, budget 12 agents /
+  2M tokens).
+- For changed packages under an extensions submodule → name
+  `review-extension` (one reviewer per changed package at parallelism 3).
+
+Budget guidance: pass a per-call `budget` override on the run_workflow call —
+halve `maxAgents` when the diff exceeds ~150 files; without an override the
+workflow's own declared budget applies.
+
+Resume behavior: on journal keys already present from a prior partial run
+the engine skips completed steps — do not re-dispatch them yourself.
+
+When the run completes, report the merged, verified findings via
+`review_report` (if available) or as a markdown list ranked most-severe
+first.
+
+For tuning the pipeline itself (steps, rubric, determinism constraints),
+load the workflow-author skill.

package/sessions/spawn.ts

@@ -3,7 +3,7 @@
  *
  * Thin barrel over src/agent/dispatch.ts: the spawn registry + per-agent
  * abort primitives. The core spawn implementation lives in
- * `@fyeeme/pi-subagent-core`; skip/retry (workflows-specific) stay in
+ * `@fyeeme/pi-subagents`; skip/retry (workflows-specific) stay in
  * dispatch.ts.
  */
 export {

package/skills/workflow-author/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: workflow-author
+description: "Author and tune deterministic workflow definitions for run_workflow: step-type selection, rubric writing, the single-file determinism constraint, budget/parallelism as declared data, and resume semantics."
+---
+
+# Authoring workflow-library definitions
+
+A library workflow is a single `.ts` file under `.pi/workflows/lib/`
+(project) or the package's bundled `workflows/` (reference examples:
+`review-local-diff`, `review-extension`). It exports a workflow and becomes
+runnable by name (`run_workflow` with `source: "library"`) on the next call —
+dropping the file in IS the registration; no code change, no restart.
+
+## The hard constraint: single-file determinism
+
+The loader runs the ast determinism guard on the entry source and REJECTS
+`Date.now()`, `Math.random()`, and `new Date()` **before** executing. This is
+not a style rule — cache-key resume is only sound when the same workflow
+source produces the same cache keys. The guard scans **only the entry file**:
+a helper imported from another file could smuggle in non-determinism and
+silently break resume. Therefore: **library workflows must stay
+single-file.** Inline everything; if you need `now`, the engine passes it
+(the `now` run parameter / `ctx` plumbing) — never read the clock yourself.
+
+## Choosing step types
+
+| Need | Step | Notes |
+|---|---|---|
+| One LLM call | `agent` | prompt may be a function of `ctx.input` / `ctx.step(id)` |
+| N parallel calls over a list | `fan_out` | `over` may be dynamic (`ctx => …`); declare `parallelism`; `merge` folds results |
+| Produce + judge | `adversarial` | rubric criteria become judge prompts; `judges`/`minPass` (majority default) |
+| Best-of-N | `tournament` | candidates × judges |
+| Route by classification | `classify_route` | classifier replies `{category}`; routes + fallback |
+| Iterate to convergence | `loop_until` | `until` condition + `maxIterations` (TS-only — library files only, not inline JSON) |
+| Zero-token narrative | `log` | journal annotation only |
+
+## Writing rubrics (adversarial / tournament)
+
+A rubric entry is a judge prompt, not a checkbox. Write each criterion as a
+falsifiable, self-contained sentence: `"finding is concretely actionable
+(file:line present)"` — not `"quality"`. 2–4 criteria; a judge that cannot
+verify a criterion from the material in front of it will guess, and guessing
+flattens the verdict distribution.
+
+## Budget and parallelism are data
+
+`budget: { maxAgents, maxTokens, maxDurationMs }` at the workflow level and
+`parallelism` on fan-out steps are declared fields the engine enforces
+(fan-out pre-checks the batch fits; a step exceeding budget follows its
+`onBudgetExhaust` policy — throw, or degrade to null). Tune them by editing
+the file; orchestration prompts may also pass tighter values per call.
+
+## Resume semantics
+
+Every dispatched call is cache-keyed (workflow source + prompts + inputs).
+Re-running with unchanged definition and inputs skips completed steps from
+the journal — do not "help" by re-dispatching; change an input only when you
+want a step actually re-run. Editing the workflow source changes the keys:
+that is the intended way to invalidate stale cache.
+
+## Checklist before shipping a library workflow
+
+1. Single file, and imports type-only: `import type { WorkflowDefinition } from ...` (erased at load — nothing outside the file executes, so the entry-only guard scan covers everything). NEVER value-import the engine by relative path: from `.pi/workflows/lib/` it does not resolve (bricking the whole library), and any value import puts un-scanned code on the load path. Plain `export const workflow = { name, steps }` with no import at all works too (the loader validates shape, not `defineWorkflow`).
+2. No `Date.now` / `Math.random` / `new Date` anywhere in the source.
+3. `name` is unique and descriptive (it is the invocation key); `description`
+   one line — it appears in the unknown-name listing.
+4. Budget and parallelism declared, sized to the worst expected input.
+5. Verified locally: `run_workflow` with `source: "library"`, then re-run to
+   see journal hits skip completed steps.

package/src/agent/dispatch.ts

@@ -3,7 +3,7 @@
  *
  * The core spawn primitive (`spawnAgent`, `mapWithConcurrencyLimit`,
  * `createSpawnRegistry`, `abortAgent`, `getPiInvocation` + the registry/
- * options/result types) lives in the shared `@fyeeme/pi-subagent-core`
+ * options/result types) lives in the shared `@fyeeme/pi-subagents`
  * package — extracted from the duplicate copies that used to live here and
  * in pi-review. This module keeps the workflows-specific layer on top:
  * `skipAgent`/`retryAgent` (with `AbortReason` semantics) and the lifecycle
@@ -19,7 +19,7 @@
  */
 import type { AgentLifecycleListeners } from "../lifecycle.ts";
 import { notifyRetry, notifySkip } from "../lifecycle.ts";
-import type { AgentSpawnRegistry } from "@fyeeme/pi-subagent-core";
+import type { AgentSpawnRegistry } from "@fyeeme/pi-subagents";
 
 // Re-export the core dispatch surface so existing importers of this module
 // (`../agent/dispatch.ts`) keep working unchanged.
@@ -29,7 +29,7 @@ export {
 	getPiInvocation,
 	mapWithConcurrencyLimit,
 	spawnAgent,
-} from "@fyeeme/pi-subagent-core";
+} from "@fyeeme/pi-subagents";
 export type {
 	AgentAbortMap,
 	AgentCallId,
@@ -37,7 +37,7 @@ export type {
 	AgentSpawnRegistry,
 	AgentSpawnResult,
 	AgentUsage,
-} from "@fyeeme/pi-subagent-core";
+} from "@fyeeme/pi-subagents";
 
 export type AbortReason = "user-skip" | "user-retry";
 

package/src/classifier-hook.ts

@@ -0,0 +1,56 @@
+/**
+ * classify_route classifier hook — pi 0.99 `ModelRuntime.classify()` path.
+ *
+ * Model discovery (design D3): a step-declared `model` is honored only when it
+ * resolves to a classifier-type model with working credentials; otherwise the
+ * first available classifier on the host. None → `undefined` (the runner falls
+ * back to the agent path). The choice question's criteria are the route names;
+ * the answer is returned verbatim so undeclared categories resolve through
+ * fallback sub-steps exactly like the agent path (Routing equivalence).
+ */
+import type { ClassifierApi, ClassifierContext, ClassifierModel, ClassifierResult } from "@earendil-works/pi-ai";
+import type { ClassifyHook } from "./types.ts";
+
+/** The registry surface the hook needs — satisfied by the extension context's
+ *  ModelRegistry (pi 0.99+); tests mock this narrow slice. */
+export interface ClassifierRegistrySlice {
+	getAvailableOfType(type: "classifier"): Promise<readonly ClassifierModel<ClassifierApi>[]>;
+	classify(model: ClassifierModel<ClassifierApi>, context: ClassifierContext): Promise<ClassifierResult>;
+}
+
+export function createClassifyHook(registry: ClassifierRegistrySlice): ClassifyHook {
+	return async (prompt, routeNames, model) => {
+		const available = await registry.getAvailableOfType("classifier");
+		if (available.length === 0) return undefined;
+		const chosen = (model ? available.find((m) => m.id === model) : undefined) ?? available[0]!;
+
+		const result = await registry.classify(chosen, {
+			state: { prompt, routes: [...routeNames] },
+			questions: {
+				route: {
+					type: "choice",
+					instructions: prompt,
+					criteria: Object.fromEntries(routeNames.map((name) => [name, name])),
+				},
+			},
+		});
+		if (result.stopReason !== "stop") return undefined;
+		const answer = result.answers.route;
+		if (answer?.type !== "choice") return undefined;
+
+		const u = result.usage;
+		return {
+			category: answer.choice,
+			usage: u
+				? {
+						input: u.input ?? 0,
+						output: u.output ?? 0,
+						cacheRead: u.cacheRead ?? 0,
+						cacheWrite: u.cacheWrite ?? 0,
+						totalTokens: u.totalTokens ?? (u.input ?? 0) + (u.output ?? 0),
+						cost: u.cost?.total ?? 0,
+					}
+				: undefined,
+		};
+	};
+}

package/src/format.ts

@@ -6,7 +6,7 @@
  * monitor `displayName` for the shared sub-agent UI). The former ANSI color
  * helpers + fmtTokens were progress-widget/`/wf-inspect` rendering aids and
  * were removed together with those surfaces (live progress is now rendered by
- * the shared @fyeeme/pi-subagent-core extension).
+ * the shared @fyeeme/pi-subagents extension).
  */
 
 /** Extract the step id from a callId of the form `${stepId}#${n}` (e.g.

package/src/library.ts

@@ -0,0 +1,143 @@
+/**
+ * src/library.ts — named workflow library: the persistence layer for
+ * workflows (PR3 of the sandwich refactor).
+ *
+ * Workflows are single-file `.ts` definitions (full step set including the
+ * TS-only steps like loop_until) discovered from:
+ *
+ *   1. project — nearest `.pi/workflows/lib/` walking up from cwd
+ *   2. bundled — this package's own `workflows/` directory (seed workflows)
+ *
+ * The project entry overrides a bundled entry of the same name. Discovery and
+ * loading go through the existing loader (jiti + the ast determinism guard),
+ * so a library workflow is rejected before execution when its source
+ * smuggles in non-deterministic APIs — the precondition cache-key resume
+ * relies on.
+ *
+ * The library directory is deliberately distinct from the journal output
+ * tree (`.pi/workflows/runs/<runId>/`): definitions and run state never
+ * collide. Adding a workflow = dropping a file; no code change.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadWorkflowModule } from "./loader.ts";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import type { WorkflowDefinition } from "./types.ts";
+
+/** This file lives at <pkg>/src/ → the bundled library is <pkg>/workflows. */
+const PKG_ROOT = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+const BUNDLED_LIB_DIR = path.join(PKG_ROOT, "workflows");
+
+/** Project-level library directory, relative to the project root. */
+const PROJECT_LIB_REL = path.join(CONFIG_DIR_NAME, "workflows", "lib");
+
+/** One library entry, after loading the module. */
+export interface LibraryEntry {
+	readonly name: string;
+	readonly description?: string;
+	readonly filePath: string;
+	readonly workflow: WorkflowDefinition;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Nearest project library dir walking up from cwd (like agent discovery). */
+export function findProjectLibDir(cwd: string): string | null {
+	let dir = path.resolve(cwd);
+	for (;;) {
+		const candidate = path.join(dir, PROJECT_LIB_REL);
+		if (isDirectory(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** Library directories in priority order (later wins on name collision). */
+function libDirs(cwd: string): string[] {
+	const dirs = [BUNDLED_LIB_DIR];
+	const project = findProjectLibDir(cwd);
+	if (project) dirs.push(project);
+	return dirs;
+}
+
+function isValidWorkflow(value: unknown): value is WorkflowDefinition {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		typeof (value as WorkflowDefinition).name === "string" &&
+		Array.isArray((value as WorkflowDefinition).steps)
+	);
+}
+
+/** Load one workflow file: ast-guard + jiti import + shape validation. */
+async function loadEntry(filePath: string): Promise<LibraryEntry | null> {
+	try {
+		const mod = (await loadWorkflowModule({ filePath })) as {
+			workflow?: unknown;
+			default?: unknown;
+		};
+		const wf = mod.workflow ?? mod.default;
+		if (!isValidWorkflow(wf)) return null;
+		return {
+			name: wf.name,
+			description: wf.description,
+			filePath,
+			workflow: wf,
+		};
+	} catch (err) {
+		// Fail-fast, deliberately: a library file that fails the determinism
+		// guard or errors at import must NOT silently disappear from the
+		// available list (a poisoned entry re-appearing would break cache-key
+		// resume). The error names the offending file; remove or fix the file
+		// to restore discovery. Shape-invalid files (below) are the exception
+		// — they are skipped silently as non-workflows.
+		throw new Error(`library workflow ${path.basename(filePath)} failed to load: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
+/**
+ * Discover the library: load every `.ts` workflow in the library dirs and
+ * index by workflow name (later dirs override earlier same-name entries).
+ * A file whose module import or the determinism guard check FAILS aborts the
+ * whole discovery with an error naming the file (fail-fast — see loadEntry);
+ * a file that imports cleanly but is not a valid workflow shape is skipped
+ * silently.
+ */
+export async function discoverWorkflowLibrary(cwd: string): Promise<Map<string, LibraryEntry>> {
+	const byName = new Map<string, LibraryEntry>();
+	for (const dir of libDirs(cwd)) {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue; // unreadable/missing dir — skip
+		}
+		for (const entry of entries) {
+			if (!entry.name.endsWith(".ts") || entry.name.startsWith(".")) continue;
+			if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+			const loaded = await loadEntry(path.join(dir, entry.name));
+			if (loaded) byName.set(loaded.name, loaded);
+		}
+	}
+	return byName;
+}
+
+/** Resolve one workflow by name, or null when not in the library. */
+export async function loadLibraryWorkflow(
+	name: string,
+	cwd: string,
+): Promise<LibraryEntry | null> {
+	// Fast path: only load the files that could define the name. Files export
+	// the workflow's name, so discovery is required either way — but skipping
+	// the project/bundled distinction keeps override semantics identical.
+	const lib = await discoverWorkflowLibrary(cwd);
+	return lib.get(name) ?? null;
+}

package/src/runner/index.ts

@@ -14,11 +14,12 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
 import { BudgetPool } from "../budget/index.ts";
 import { Journal, type RunManifest } from "../cache/index.ts";
 import type { AgentLifecycleListeners } from "../lifecycle.ts";
 import { generateRunId } from "../state/index.ts";
-import type { Budget, RunResult, WorkflowDefinition } from "../types.ts";
+import type { Budget, ClassifyHook, RunResult, WorkflowDefinition } from "../types.ts";
 import {
 	createSpawnRegistry,
 	spawnAgent,
@@ -72,6 +73,11 @@ export interface RunWorkflowOptions {
 	/** A6: policy gate invoked before the first dispatch. Return { allow: false,
 	 *  reason } to deny the run with a policy-gate error. */
 	readonly policyGate?: (workflow: WorkflowDefinition) => { readonly allow: boolean; readonly reason?: string } | Promise<{ readonly allow: boolean; readonly reason?: string }>;
+	/** pi 0.99 classifier hook for classify_route steps: when provided and a
+	 *  classifier model is available, route categories come from
+	 *  ModelRuntime.classify() instead of a spawned classification agent;
+	 *  unavailability and failures fall back to the agent path. */
+	readonly classify?: ClassifyHook;
 }
 
 export async function runWorkflow(opts: RunWorkflowOptions): Promise<RunResult> {
@@ -81,7 +87,7 @@ export async function runWorkflow(opts: RunWorkflowOptions): Promise<RunResult>
 	const budget = opts.budget ?? workflow.budget ?? {};
 	const journalDir =
 		opts.journalDir ??
-		path.join(cwd, ".pi", "workflows", sanitizeWorkflowName(workflow.name));
+		path.join(cwd, CONFIG_DIR_NAME, "workflows", sanitizeWorkflowName(workflow.name));
 
 	await fs.promises.mkdir(journalDir, { recursive: true });
 	const journal = new Journal({ dir: journalDir });
@@ -135,6 +141,7 @@ export async function runWorkflow(opts: RunWorkflowOptions): Promise<RunResult>
 		maxPromptBytes: opts.maxPromptBytes ?? DEFAULT_MAX_PROMPT_BYTES,
 		degradedStepIds: new Set(),
 		allowChildRecursion: opts.allowChildRecursion ?? false,
+		classify: opts.classify,
 		dispatched: 0,
 	};
 

package/src/runner/stage-executor.ts

@@ -35,6 +35,7 @@ import type {
 	AgentCallSpec,
 	AgentOpts,
 	AgentStep,
+	ClassifyHook,
 	ClassifyRouteStep,
 	CodeStep,
 	LoopUntilDryStep,
@@ -81,6 +82,9 @@ export interface StepExecContext {
 	budgetPolicy: "throw" | "null";
 	/** A6: max resolved-prompt byte size; oversize throws a size-limit error. */
 	maxPromptBytes: number;
+	/** pi 0.99 classifier hook for classify_route (undefined → agent path only).
+	 *  See ClassifyHook / spec workflow-classifier-routing. */
+	readonly classify?: ClassifyHook;
 	/** A3: step ids that degraded to null under the "null" policy this run. */
 	degradedStepIds: Set<string>;
 	/** Recursion opt-in propagated to every spawned workflow sub-agent: when
@@ -555,28 +559,63 @@ async function execTournament(step: TournamentStep, ctx: StepContext, exec: Step
 async function execClassifyRoute(step: ClassifyRouteStep, ctx: StepContext, exec: StepExecContext): Promise<StepResult> {
 	const start = Date.now();
 	const classifyPrompt = await resolvePrompt(step.classifier, ctx);
-	const classify = await dispatchAgentCall(`${step.id}#classify`, classifyPrompt, step.classifier, exec);
-	if (!classify.ok) {
-		return stepResult(
-			step.id,
-			"classify_route",
-			classify.aborted ? "skipped" : "failed",
-			undefined,
-			withDuration(classify.stats, start),
-			undefined,
-			classify.aborted ? undefined : "dispatch-error",
-		);
+
+	// pi 0.99 classifier path first (spec: workflow-classifier-routing): when a
+	// classifier hook is available and answers, the category comes from its
+	// ranked choice and no classification subprocess is spawned. Unavailable or
+	// failing hook → the original agent path, unchanged (fallback contract).
+	let classifyPath: "classifier" | "agent" = "agent";
+	let category = "";
+	let classifyStats: StepStats = zeroStats;
+	if (exec.classify) {
+		try {
+			const hookResult = await exec.classify(classifyPrompt, Object.keys(step.routes), step.classifier.model);
+			if (hookResult) {
+				classifyPath = "classifier";
+				category = parseCategoryStr(hookResult.category);
+				const u = hookResult.usage;
+				classifyStats = {
+					tokens: u ? u.totalTokens : 0,
+					cost: u ? u.cost : 0,
+					durationMs: 0,
+					agents: 0,
+					failures: 0,
+					usage: u
+						? { input: u.input, output: u.output, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite }
+						: undefined,
+				};
+			}
+		} catch {
+			// classifier call failed → agent fallback (spec: Fallback to the agent path)
+		}
 	}
 
-	// A3: a degraded classifier (budget exhausted under the "null" policy)
-	// returns value null — the step degrades to a null result per the README
-	// contract; do not fabricate a route run from an empty category.
-	if (classify.value === null) {
-		return stepResult(step.id, "classify_route", "done", null, withDuration(classify.stats, start));
+	if (classifyPath === "agent") {
+		const classify = await dispatchAgentCall(`${step.id}#classify`, classifyPrompt, step.classifier, exec);
+		if (!classify.ok) {
+			return stepResult(
+				step.id,
+				"classify_route",
+				classify.aborted ? "skipped" : "failed",
+				undefined,
+				withDuration(classify.stats, start),
+				undefined,
+				classify.aborted ? undefined : "dispatch-error",
+			);
+		}
+
+		// A3: a degraded classifier (budget exhausted under the "null" policy)
+		// returns value null — the step degrades to a null result per the README
+		// contract; do not fabricate a route run from an empty category.
+		if (classify.value === null) {
+			return stepResult(step.id, "classify_route", "done", null, withDuration(classify.stats, start));
+		}
+
+		const parsed = parseFirstJson(classify.value ?? "") as { category?: unknown } | undefined;
+		category = parseCategoryStr(parsed?.category);
+		classifyStats = classify.stats;
 	}
 
-	const parsed = parseFirstJson(classify.value ?? "") as { category?: unknown } | undefined;
-	const category = parseCategoryStr(parsed?.category);
 	const routeSteps = step.routes[category] ?? step.fallback ?? [];
 
 	exec.depth++;
@@ -592,8 +631,8 @@ async function execClassifyRoute(step: ClassifyRouteStep, ctx: StepContext, exec
 		step.id,
 		"classify_route",
 		status,
-		{ category, matched: category in step.routes, route: sub.steps, routeStatus: sub.status },
-		withDuration(addStats(classify.stats, aggregateStats(sub.steps.map((s) => s.stats), 0)), start),
+		{ category, matched: category in step.routes, route: sub.steps, routeStatus: sub.status, path: classifyPath },
+		withDuration(addStats(classifyStats, aggregateStats(sub.steps.map((s) => s.stats), 0)), start),
 		undefined,
 		sub.errorCategory,
 	);
@@ -986,7 +1025,7 @@ function dispatchOpts(
 		signal,
 		allowChildRecursion,
 		// UI display name for the shared sub-agent widget/FleetView (purely
-		// observational metadata consumed by the pi-subagent-core monitor): the
+		// observational metadata consumed by the pi-subagents monitor): the
 		// step id ("fan", "adv"), so workflow rows are distinguishable from other
 		// agents. Cache hits never spawn, so they never appear — zero dispatch.
 		displayName: stepIdOf(callId),
@@ -1018,6 +1057,12 @@ function usageStats(res: AgentSpawnResult, durationMs: number, ok: boolean): Ste
 		durationMs,
 		agents: 1,
 		failures: ok ? 0 : 1,
+		usage: {
+			input: res.usage.input,
+			output: res.usage.output,
+			cacheRead: res.usage.cacheRead,
+			cacheWrite: res.usage.cacheWrite,
+		},
 	};
 }
 
@@ -1028,6 +1073,20 @@ function addStats(a: StepStats, b: StepStats): StepStats {
 		durationMs: a.durationMs + b.durationMs,
 		agents: a.agents + b.agents,
 		failures: a.failures + b.failures,
+		usage: mergeUsage(a.usage, b.usage),
+	};
+}
+
+function mergeUsage(
+	a: StepStats["usage"],
+	b: StepStats["usage"],
+): StepStats["usage"] {
+	if (!a && !b) return undefined;
+	return {
+		input: (a?.input ?? 0) + (b?.input ?? 0),
+		output: (a?.output ?? 0) + (b?.output ?? 0),
+		cacheRead: (a?.cacheRead ?? 0) + (b?.cacheRead ?? 0),
+		cacheWrite: (a?.cacheWrite ?? 0) + (b?.cacheWrite ?? 0),
 	};
 }
 
@@ -1038,14 +1097,16 @@ export function aggregateStats(stats: readonly StepStats[], durationMs: number):
 	let agents = 0;
 	let failures = 0;
 	let dur = 0;
+	let usage: StepStats["usage"];
 	for (const s of stats) {
 		tokens += s.tokens;
 		cost += s.cost;
 		agents += s.agents;
 		failures += s.failures;
 		dur += s.durationMs;
+		usage = mergeUsage(usage, s.usage);
 	}
-	return { tokens, cost, durationMs: durationMs > 0 ? durationMs : dur, agents, failures };
+	return { tokens, cost, durationMs: durationMs > 0 ? durationMs : dur, agents, failures, usage };
 }
 
 function withDuration(stats: StepStats, start: number): StepStats {

package/src/types.ts

@@ -49,12 +49,51 @@ export interface Budget {
 // Step statistics + result
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// classify_route classifier hook (pi 0.99 ModelRuntime.classify)
+// ---------------------------------------------------------------------------
+
+/** Result of a successful classifier-path classification for classify_route.
+ *  `category` is the classifier's chosen route name (may be undeclared — the
+ *  runner resolves it through fallback sub-steps exactly like the agent path). */
+export interface ClassifyHookResult {
+	readonly category: string;
+	/** Classifier token usage for truthful step stats; omit when unknown. */
+	readonly usage?: {
+		readonly input: number;
+		readonly output: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+		readonly totalTokens: number;
+		readonly cost: number;
+	};
+}
+
+/** Optional classifier hook injected by the extension entry (spec:
+ *  workflow-classifier-routing). Returns undefined when no classifier model is
+ *  available; a throw also falls back to the agent path. Route sub-steps still
+ *  run as agent dispatches either way. */
+export type ClassifyHook = (
+	prompt: string,
+	routeNames: readonly string[],
+	model?: string,
+) => Promise<ClassifyHookResult | undefined>;
+
 export interface StepStats {
 	readonly tokens: number;
 	readonly cost: number;
 	readonly durationMs: number;
 	readonly agents: number;
 	readonly failures: number;
+	/** Nested-LLM usage split, populated for agent-dispatch steps and surfaced
+	 *  as `usage` on the run_workflow tool result (pi usage accounting). Absent
+	 *  for zero-dispatch steps (code/log) and journals written before this field. */
+	readonly usage?: {
+		readonly input: number;
+		readonly output: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+	};
 }
 
 export interface StepResult<T = unknown> {

package/workflows/review-extension.ts

@@ -0,0 +1,51 @@
+/**
+ * Seed library workflow: review-extension — the extensions-submodule review
+ * fan-out distilled from this repository's review-local-extensions-fanout
+ * pipeline: scope the changed packages first, then one reviewer per changed
+ * extension directory (parallelism 3), then merge.
+ *
+ * Input: newline-separated list of changed paths under packages/extensions
+ * (or a single path). Prompts use prompt functions (ctx.input /
+ * ctx.step(id)) — the TS API does not substitute {{...}} tokens.
+ * Runtime-single-file: `import type` is erased at load (see
+ * review-local-diff.ts).
+ */
+import type { WorkflowDefinition } from "../src/index.ts";
+
+export const workflow: WorkflowDefinition = {
+	name: "review-extension",
+	description: "Review each changed extension package: one reviewer per package (parallelism 3), merged findings",
+	budget: { maxAgents: 9, maxTokens: 2_000_000 },
+	steps: [
+		{
+			id: "scope",
+			type: "agent",
+			prompt: (ctx) =>
+				"The input lists changed paths under packages/extensions. Reduce it to the set of " +
+				"distinct top-level extension directories (e.g. \"pi-review\", \"pi-subagents\"). " +
+				"Return ONLY the directory names, one per line, no commentary.\n\n" +
+				String(ctx.input),
+		},
+		{
+			id: "reviewers",
+			type: "fan_out",
+			over: (ctx) =>
+				String(ctx.step("scope").results)
+					.split("\n")
+					.map((l) => l.trim())
+					.filter(Boolean),
+			parallelism: 3,
+			agent: (pkg, _index, ctx) => ({
+				prompt:
+					`Review the uncommitted changes in packages/extensions/${pkg} (run ` +
+					`\`git -C packages/extensions/${pkg} diff\` yourself; read the touched files for ` +
+					`context). Report findings as \`file:line\` — one-line summary — the concrete cost. ` +
+					`Cover correctness, reuse, simplification, efficiency, altitude. Report only.\n\n` +
+					`Changed paths:\n${ctx.input}`,
+			}),
+			merge: (results) => results.join("\n---\n"),
+		},
+	],
+};
+
+export default workflow;

package/workflows/review-local-diff.ts

@@ -0,0 +1,64 @@
+/**
+ * Seed library workflow: review-local-diff — the local-diff review pipeline
+ * actually run in this repository (distilled from the .pi/workflows journals
+ * of review-local-changes / review-local-extensions-fanout runs).
+ *
+ * Input: the unified diff to review (run input). Fan out one finder per
+ * angle (parallelism 4), adversarially verify a merged candidate list, and
+ * return the verified findings. Budget and parallelism are declared here as
+ * data — the engine enforces them.
+ *
+ * Prompts reference run context via prompt FUNCTIONS (ctx.input /
+ * ctx.step(id)) — the {{...}} template tokens are the inline-JSON tool
+ * surface only; the TS API never substitutes them in plain strings.
+ *
+ * Runtime-single-file: `import type` is erased at load, so nothing outside
+ * this file executes and the ast determinism guard's entry-only scan covers
+ * everything that runs (a VALUE import from another file would not be
+ * scanned — keep imports type-only).
+ */
+import type { WorkflowDefinition } from "../src/index.ts";
+
+const ANGLES = ["correctness", "reuse", "simplification", "efficiency", "altitude"] as const;
+
+export const workflow: WorkflowDefinition = {
+	name: "review-local-diff",
+	description: "Fan out diff-scoped finders, adversarially verify the merged candidates, return verified findings",
+	budget: { maxAgents: 12, maxTokens: 2_000_000 },
+	steps: [
+		{
+			id: "finders",
+			type: "fan_out",
+			over: () => [...ANGLES],
+			parallelism: 4,
+			agent: (angle, _index, ctx) => ({
+				prompt:
+					`You are a code-review finder for the "${angle}" angle. Review the diff below. ` +
+					`Report each finding as \`file:line\` — one-line summary — the concrete cost ` +
+					`(for correctness: the input/state that triggers it → wrong output). Report only; ` +
+					`an empty list is a valid answer.\n\nDiff:\n${ctx.input}`,
+			}),
+			merge: (results) => results.join("\n---\n"),
+		},
+		{
+			id: "verify",
+			type: "adversarial",
+			produce: {
+				prompt: (ctx) =>
+					"Dedup and merge these code-review findings into a numbered candidate list " +
+					"(same defect + same location + same reason → keep one; different reasons for " +
+					"the same line are NOT duplicates — keep both). Return only the numbered list.\n\n" +
+					String(ctx.step("finders").results),
+			},
+			rubric: [
+				"finding is concretely actionable (file:line present)",
+				"the failure scenario or cost is stated and realistic",
+				"not a duplicate of another kept finding",
+			],
+			judges: 3,
+			minPass: 2,
+		},
+	],
+};
+
+export default workflow;