pi-workflow-engine 1.0.0 → 1.1.0

package/.pi/extensions/pi-workflow-engine/index.ts

@@ -40,6 +40,9 @@ import { registerWorkflowRunCommand, WorkflowRunController } from "./src/workflo
 import { completeCurrentArgument, splitArgumentPrefix } from "./src/command-completions.ts";
 import { assertSupportedPiVersion } from "./src/pi-compat.ts";
 import { formatWorkflowInspection, workflowInspectionSnapshot } from "./src/ui/workflow-format.ts";
+import { workflowUsageForPi, type WorkflowUsageSnapshot } from "./src/usage.ts";
+import { unknownErrorMessage } from "./src/unknown-error.ts";
+import { createHostToolBridge } from "./src/host-tools.ts";
 
 /** Extension root (this file lives in <repo>/.pi/extensions/pi-workflow-engine/index.ts). */
 const EXTENSION_DIR = fileURLToPath(new URL(".", import.meta.url));
@@ -195,15 +198,7 @@ export function buildTemporaryWorkflowAuthorPrompt(brief: string): string {
 User brief:
 ${brief.trim()}
 
-Use the workflow tool with a script argument, not a saved workflow name.
-The script must start with export const meta = { ... } and default-export an async workflow function.
-Use the injected Type object for schemas. Do not import anything or use dynamic import().
-Set profile to "small", "medium", or "big" on each agent() call; use explicit model/thinkingLevel only for an intentional override.
-Always pass a plain string as the first api.agent() argument; build prompts with template strings before calling agent().
-If using \`isolation: "worktree"\`, remember api.agent() returns \`{ result, patch, changed }\`; read \`.result\` for the agent answer and \`.patch\` for the diff.
-When the run is budgeted, guard expensive loops with \`while (api.budget.total && api.budget.remaining() > N) { ... }\`; api.agent() throws once the budget is spent.
-Subagents receive no skills by default. When the brief asks for a skill or a stage clearly benefits from one, pass \`skills: ["skill-name"]\` on that agent call only.
-${ADAPTIVE_WORKFLOW_GUIDANCE}
+Use the workflow tool with a script argument, not a saved workflow name, and follow its guidelines for inline scripts.
 Do not edit files unless the user explicitly requested edits.`;
 }
 
@@ -219,9 +214,17 @@ export type WorkflowToolRequest =
   | { readonly kind: "inline"; readonly script: string }
   | { readonly kind: "error"; readonly error: "invalid_workflow_invocation"; readonly message: string };
 
-export interface WorkflowToolErrorResult {
+export interface WorkflowToolErrorResult<TDetails = WorkflowToolErrorDetails> {
   readonly content: Array<{ readonly type: "text"; readonly text: string }>;
-  readonly details: { readonly error: "invalid_workflow_invocation" } | { readonly error: "inline_compile_error"; readonly message: string };
+  readonly details: TDetails;
+  /** The model sees a failed call while the renderer still reads `details`. */
+  readonly isError: true;
+}
+
+type WorkflowToolErrorDetails = { readonly error: "invalid_workflow_invocation" } | { readonly error: "inline_compile_error"; readonly message: string };
+
+function workflowToolError<TDetails>(text: string, details: TDetails): WorkflowToolErrorResult<TDetails> {
+  return { content: [{ type: "text", text }], details, isError: true };
 }
 
 const INVALID_WORKFLOW_INVOCATION_MESSAGE = "Provide exactly one workflow name or inline workflow script.";
@@ -236,11 +239,11 @@ export function normalizeWorkflowToolRequest(params: WorkflowToolRequestParams):
 }
 
 export function invalidWorkflowInvocationResult(): WorkflowToolErrorResult {
-  return { content: [{ type: "text", text: INVALID_WORKFLOW_INVOCATION_MESSAGE }], details: { error: "invalid_workflow_invocation" } };
+  return workflowToolError(INVALID_WORKFLOW_INVOCATION_MESSAGE, { error: "invalid_workflow_invocation" });
 }
 
 export function inlineCompileErrorResult(message: string): WorkflowToolErrorResult {
-  return { content: [{ type: "text", text: `Inline workflow did not compile: ${message}` }], details: { error: "inline_compile_error", message } };
+  return workflowToolError(`Inline workflow did not compile: ${message}`, { error: "inline_compile_error", message });
 }
 
 export type WorkflowPickerSelection =
@@ -485,6 +488,10 @@ function registerWorkflowTool(
     description:
       "ONLY call workflow when the user opted into multi-agent orchestration via the literal token `dynamax`, sticky `/workflow:dynamax on`, an explicit request to run or author a workflow, or a command/skill instruction. Runs either a registered named workflow or an inline one-off workflow script (fan-out → verify → synthesize), synchronously by default or explicitly in the background.",
     promptSnippet: "Run an existing named workflow or an inline one-off workflow script",
+    // Like codemode itself, an orchestrating tool stays a top-level model action: from a codemode script a
+    // run would lose its tool row, hit the script's output cap, and parallel runs would each get their own
+    // concurrency cap. It also stays declared under `codemode.mode: "only"`, which hides direct tools.
+    exposure: "model-only",
     promptGuidelines: [
       "Use workflow only when the user opted into workflow orchestration via `dynamax`, `/workflow:dynamax on`, an explicit request to run/author a workflow, or a command/skill instruction.",
       "Use workflow with `name` for existing registered workflows such as code-review, diagnose, refactor-scout, or perf-review.",
@@ -492,9 +499,13 @@ function registerWorkflowTool(
       "Inline workflow scripts must use the injected `Type` object for schemas and must not contain imports or dynamic import().",
       "Inline scripts may compose registered workflows in-process via `api.workflow(\"<name>\", args)` (e.g. `await api.workflow(\"code-review\", \"HEAD~3\")`); it returns the sub-workflow's result and nests one level only.",
       "Subagents receive no skills by default. In inline workflows, pass `skills: [\"skill-name\"]` per `agent()` call when the user asks for a skill or a stage should use one; grant only the needed skills.",
+      "Set `profile: \"small\"`, `\"medium\"`, or `\"big\"` on every `api.agent()` call so the user's central model routes apply; use `model`/`thinkingLevel` only for an intentional override.",
       "Always pass a plain string as the first `api.agent()` argument; build prompts with template strings before calling agent().",
       "When using `isolation: \"worktree\"`, `api.agent()` returns `{ result, patch, changed }`; use `.result` for the answer and `.patch` for the isolated diff.",
       "If an inline subagent needs grep/find/code-search helpers, use `tools: [\"read\", \"bash\", \"grep\", \"find\", \"ls\"]` plus `toolHints: [\"search\"]` so installed tools such as ast-grep, mgrep, ffgrep, or fffind are discovered dynamically.",
+      "Add \"codemode\" to an inline agent's `tools` when it should batch or filter many tool calls in one script; its scripts can call only that agent's other allowed tools.",
+      "`api.classify({ state, questions }, { label })` answers typed choice/score/bool questions with a classifier model and no chat session; use it for cheap gates such as dedup or triage, and handle its rejection when no classifier is configured.",
+      "Host MCP tools reach subagents only in synchronous workflow tool runs: name them in `tools` (e.g. `mcp__server__tool`), or use `toolHints: [\"external-search\"]` to pick up MCP web research tools.",
       "`api.budget` exposes `{ total, spent(), remaining() }` (output tokens). When the run is budgeted, scale fleets from `budget.total` and guard loops with `while (budget.total && budget.remaining() > N) { await api.agent(...) }`; `api.agent()` throws once the ceiling is reached.",
       ADAPTIVE_WORKFLOW_GUIDANCE,
       "Set background: true only when the user explicitly wants the workflow to continue after this tool call; the tool returns a durable run ID and completion is delivered later.",
@@ -565,16 +576,10 @@ function registerWorkflowTool(
       if (request.kind === "error") return invalidWorkflowInvocationResult();
       const resumeFromRunId = params.resumeFromRunId?.trim();
       if (params.resumeFromRunId !== undefined && resumeFromRunId === "") {
-        return {
-          content: [{ type: "text", text: "resumeFromRunId must be non-empty." }],
-          details: { error: "invalid_resume_from_run_id" },
-        };
+        return workflowToolError("resumeFromRunId must be non-empty.", { error: "invalid_resume_from_run_id" });
       }
       if (params.resumeEditedWorkflow && !resumeFromRunId) {
-        return {
-          content: [{ type: "text", text: "resumeEditedWorkflow requires resumeFromRunId." }],
-          details: { error: "invalid_edited_workflow_resume" },
-        };
+        return workflowToolError("resumeEditedWorkflow requires resumeFromRunId.", { error: "invalid_edited_workflow_resume" });
       }
       if (params.background) {
         const unavailable = backgroundUnavailableResult(ctx.mode);
@@ -606,10 +611,7 @@ function registerWorkflowTool(
         const named = workflows.get(request.name);
         if (!named) {
           const available = [...workflows.keys()].join(", ") || "(none)";
-          return {
-            content: [{ type: "text", text: `Unknown workflow "${request.name}". Available: ${available}` }],
-            details: { error: "unknown_workflow", available },
-          };
+          return workflowToolError(`Unknown workflow "${request.name}". Available: ${available}`, { error: "unknown_workflow", available });
         }
         mod = named;
         resultName = request.name;
@@ -647,11 +649,30 @@ function registerWorkflowTool(
       }
       // Marks the tool row as running (rendered `● running <name>`) until the envelope replaces it.
       onUpdate?.({ content: [{ type: "text", text: `Running workflow ${resultName}.` }], details: { state: "running", name: resultName } });
-      const envelope = await executeResolvedWorkflow(pi, ctx, resultName, mod, resultArgs, runOptions, perfRecorder);
+      // Only this synchronous path may bridge host MCP tools: executeTool ends with the tool call.
+      const hostTools = createHostToolBridge(() => pi.getAllTools(), ctx);
+      // Keep the latest usage: a failed run still reports what its agents spent instead of dropping it with the error.
+      let spent: WorkflowUsageSnapshot | undefined;
+      const onUsageSnapshot = (snapshot: WorkflowUsageSnapshot) => {
+        spent = snapshot;
+        return runOptions.onUsageSnapshot?.(snapshot);
+      };
+      let envelope: WorkflowResultEnvelope;
+      try {
+        envelope = await executeResolvedWorkflow(pi, ctx, resultName, mod, resultArgs, { ...runOptions, hostTools, onUsageSnapshot }, perfRecorder);
+      } catch (error) {
+        const message = unknownErrorMessage(error);
+        return {
+          ...workflowToolError(`Workflow ${resultName} failed: ${message}`, { error: "workflow_failed", name: resultName, message }),
+          usage: workflowUsageForPi(spent),
+        };
+      }
       reviewSessions.remember(ctx, envelope, runOptions);
       return {
         content: [{ type: "text", text: formatWorkflowResultForContext(envelope) }],
         details: envelope,
+        // pi counts tool-result usage toward the session cost; subagent spend was invisible there before.
+        usage: workflowUsageForPi(envelope.usage),
       };
     },
   });

package/.pi/extensions/pi-workflow-engine/src/advisory-evidence.ts

@@ -49,16 +49,19 @@ export function dedupeCandidates<T extends IdentifiedAdvisoryCandidate>(candidat
     const key = candidateDedupKey(candidate);
     const previous = seen.get(key);
     if (!previous) seen.set(key, { ...candidate });
-    else {
-      previous.sourceCandidateIds = [...new Set([...previous.sourceCandidateIds, ...candidate.sourceCandidateIds])];
-      previous.locations = uniqueLocations([...previous.locations, ...candidate.locations]);
-      previous.impact = [...new Set([previous.impact, candidate.impact])].join("\n");
-      previous.discoveryEvidence = [...new Set([...(previous.discoveryEvidence ?? []), ...(candidate.discoveryEvidence ?? [])])];
-    }
+    else mergeCandidateInto(previous, candidate);
   }
   return [...seen.values()];
 }
 
+/** Fold a duplicate into the kept candidate, keeping every source id, location, impact, and piece of evidence. */
+export function mergeCandidateInto<T extends IdentifiedAdvisoryCandidate>(kept: T, duplicate: T): void {
+  kept.sourceCandidateIds = [...new Set([...kept.sourceCandidateIds, ...duplicate.sourceCandidateIds])];
+  kept.locations = uniqueLocations([...kept.locations, ...duplicate.locations]);
+  kept.impact = [...new Set([kept.impact, duplicate.impact])].join("\n");
+  kept.discoveryEvidence = [...new Set([...(kept.discoveryEvidence ?? []), ...(duplicate.discoveryEvidence ?? [])])];
+}
+
 export function uniqueLocations(locations: AdvisoryCandidate["locations"]): AdvisoryCandidate["locations"] {
   return [...new Map(locations.map((location) => [JSON.stringify(location), location])).values()];
 }

package/.pi/extensions/pi-workflow-engine/src/agent-runner-types.ts

@@ -1,4 +1,4 @@
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, ClassifierApi, ClassifierModel, Model } from "@earendil-works/pi-ai";
 import type {
   AgentSession,
   CreateAgentSessionOptions,
@@ -8,6 +8,7 @@ import type { WorkflowBudget } from "./budget.ts";
 import type { Semaphore } from "./concurrency.ts";
 import type { WorkflowAgentLimiter } from "./agent-limits.ts";
 import type { AgentRetryScheduler } from "./agent-retry.ts";
+import type { HostToolBridge } from "./host-tools.ts";
 import type { ResolvedWorkflowModelProfiles } from "./model-profiles.ts";
 import type { WorkflowJournal } from "./journal.ts";
 import type { PerfSink } from "./perf.ts";
@@ -63,6 +64,10 @@ interface RunContextBase {
   budget: WorkflowBudget;
   journal: WorkflowJournal;
   worktrees: WorktreeRegistry;
+  /** Host MCP tools subagents may call; set only for a synchronous `workflow` tool run. */
+  hostTools?: HostToolBridge;
+  /** Classifier routes resolved this run, so repeated `api.classify()` calls skip the credential lookup. */
+  classifierRoutes?: Map<string, Promise<ClassifierModel<ClassifierApi>>>;
 }
 
 /** Shared per-run context threaded into every agent() call. */
@@ -74,7 +79,7 @@ export type RunContext = RunContextBase & (
     }
   | {
       /** Injected test sessions bypass Pi's resource loader and therefore do not resolve skills. */
-      modelRegistry: Pick<ModelRegistry, "find">;
+      modelRegistry: Pick<ModelRegistry, "find" | "classify" | "getAvailableOfType" | "getModelOfType">;
       createSession: CreateAgentSession;
     }
 );

package/.pi/extensions/pi-workflow-engine/src/agent-session.ts

@@ -2,9 +2,11 @@ import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import {
   createAgentSessionFromServices,
   createAgentSessionServices,
+  createCodemodeExtension,
   defineTool,
   SessionManager,
   type CreateAgentSessionOptions,
+  type CreateAgentSessionServicesOptions,
   type ModelRegistry,
   type Skill,
   type ToolDefinition,
@@ -23,11 +25,15 @@ import {
 } from "./structured-output.ts";
 import { providerErrorFromMessages } from "./agent-retry.ts";
 import { synchronizeWorkflowModelRuntime } from "./agent-session-providers.ts";
+import { hostToolProxy, isMcpToolName, WorkflowHostToolUnavailableError, type HostToolBridge } from "./host-tools.ts";
 import { matchesAgentToolHint, WorkflowToolHintUnavailableError } from "./tool-capabilities.ts";
+import { parseAgentModelRef } from "./model-ref.ts";
 import { truncateText } from "./text.ts";
 import { WORKFLOW_TOOL_NAME, type AgentToolHint } from "./types.ts";
 
 export const FINAL_TOOL = "final_answer";
+/** pi's codemode tool; SDK sessions only have it when their resource loader registers the extension. */
+export const CODEMODE_TOOL = "codemode";
 
 const SCHEMA_REPROMPT =
   `You ended your turn without calling the ${FINAL_TOOL} tool, so no result was recorded. ` +
@@ -76,6 +82,8 @@ export async function openAgentSession(input: {
           description:
             "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
           parameters: opts.schema,
+          // The agent's own terminal action: a codemode script must not answer on its behalf.
+          exposure: "model-only",
           async execute(_toolCallId, params) {
             captured = true;
             structuredResult = params;
@@ -84,6 +92,7 @@ export async function openAgentSession(input: {
         }),
       ]
     : [];
+  customTools.push(...requestedHostTools(opts, rc.hostTools));
   let session: AgentRunnerSession | undefined;
   try {
     throwIfAborted(rc.signal);
@@ -105,7 +114,7 @@ export async function openAgentSession(input: {
     if (!opts.tools?.includes(WORKFLOW_TOOL_NAME)) withholdWorkflowTool(session);
     if (opts.requireToolHints) {
       const missing = toolSelection.toolHints.filter((hint) => !matchedToolHints.has(hint));
-      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing);
+      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing, { hostToolsReachable: rc.hostTools !== undefined });
     }
     throwIfAborted(rc.signal);
     return {
@@ -200,24 +209,6 @@ export async function promptAgentSession(input: {
   }
 }
 
-function parseAgentModelRef(modelRef: string): { readonly provider: string; readonly id: string } {
-  const normalized = modelRef.trim();
-  if (normalized.length === 0) {
-    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
-  }
-  if (normalized !== modelRef) {
-    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
-  }
-
-  const slash = modelRef.indexOf("/");
-  if (slash === -1) return { provider: "anthropic", id: modelRef };
-  const provider = modelRef.slice(0, slash);
-  const id = modelRef.slice(slash + 1);
-  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
-    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
-  }
-  return { provider, id };
-}
 
 interface AgentSessionResources {
   readonly selectedSkills: readonly Skill[];
@@ -262,7 +253,7 @@ async function prepareAgentSessionResources(input: {
   const preparedSkills = prepareAgentSkillResources(skillOptions);
   const services = await createAgentSessionServices({
     cwd,
-    resourceLoaderOptions: preparedSkills.resourceLoaderOptions,
+    resourceLoaderOptions: { ...preparedSkills.resourceLoaderOptions, ...codemodeExtension(opts) },
   });
   await synchronizeWorkflowModelRuntime({
     host: rc.modelRegistry,
@@ -289,6 +280,36 @@ async function prepareAgentSessionResources(input: {
   };
 }
 
+/**
+ * SDK sessions load none of pi's built-in extensions, so codemode is registered only for agents whose
+ * allowlist names it. Scripts can call just the agent's other allowed tools. Mode "on" keeps those
+ * tools declared whatever the user's `codemode.mode`, so the author's allowlist stays what the model sees.
+ */
+function codemodeExtension(opts: AgentExecutionOptions): Pick<SessionResourceLoaderOptions, "extensionFactories"> {
+  if (!opts.tools?.includes(CODEMODE_TOOL)) return {};
+  return { extensionFactories: [{ name: CODEMODE_TOOL, factory: createCodemodeExtension({ mode: "on" }), replaceable: true }] };
+}
+
+type SessionResourceLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
+
+/**
+ * Proxies for the host MCP tools this agent asked for: those named in its allowlist, and open-world
+ * research tools when it hints `external-search`. Local `search` hints never bridge, because host tools
+ * run in the host session's working directory, not the agent's (an isolated worktree, for example).
+ * A named tool the run cannot reach fails the agent, like `requireToolHints`, rather than letting it
+ * work without a tool its prompt may rely on.
+ */
+function requestedHostTools(opts: AgentExecutionOptions, bridge: HostToolBridge | undefined): ToolDefinition[] {
+  const named = new Set((opts.tools ?? []).filter(isMcpToolName));
+  const externalSearch = opts.toolHints?.includes("external-search") ?? false;
+  if (named.size === 0 && !externalSearch) return [];
+  const available = bridge?.tools() ?? [];
+  const selected = available.filter((tool) => named.has(tool.name) || (externalSearch && matchesAgentToolHint(tool, "external-search")));
+  const missing = [...named].filter((name) => !selected.some((tool) => tool.name === name));
+  if (missing.length > 0) throw new WorkflowHostToolUnavailableError(missing, bridge !== undefined);
+  return bridge ? selected.map((tool) => hostToolProxy(tool, bridge)) : [];
+}
+
 function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerSession): () => void {
   if (!signal) return () => {};
   const onAbort = () => {

package/.pi/extensions/pi-workflow-engine/src/background-workflow-tool.ts

@@ -7,6 +7,7 @@ import { unknownErrorMessage } from "./unknown-error.ts";
 export interface BackgroundWorkflowToolResult {
   readonly content: Array<{ readonly type: "text"; readonly text: string }>;
   readonly details: Readonly<Record<string, unknown>>;
+  readonly isError?: true;
 }
 
 export interface BackgroundWorkflowToolStartInput {
@@ -25,6 +26,7 @@ export function backgroundUnavailableResult(mode: ExtensionContext["mode"]): Bac
       text: `Background workflows are unavailable in ${mode} mode because pi exits after the prompt. Run synchronously or use TUI/RPC mode.`,
     }],
     details: { error: "background_unavailable", mode },
+    isError: true,
   };
 }
 
@@ -63,6 +65,7 @@ export async function startBackgroundWorkflowTool(
     return {
       content: [{ type: "text", text: `Background workflow did not start: ${message}` }],
       details: { error: "background_start_failed", message, runId },
+      isError: true,
     };
   }
   return {

package/.pi/extensions/pi-workflow-engine/src/classify.ts

@@ -0,0 +1,107 @@
+import type { ClassifierAnswer, ClassifierApi, ClassifierContext, ClassifierModel } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { RunContext } from "./agent-runner-types.ts";
+import { parseAgentModelRef } from "./model-ref.ts";
+import { assertWorkflowBudgetAvailable } from "./budget.ts";
+import { throwIfAborted } from "./cancellation.ts";
+import type { ClassifyOptions } from "./types.ts";
+
+type ClassifierRegistry = Pick<ModelRegistry, "classify" | "getAvailableOfType" | "getModelOfType">;
+
+/** No classifier model is configured, or the requested one is unknown. Recoverable inside `parallel`. */
+export class WorkflowClassifierUnavailableError extends Error {
+  readonly code = "WORKFLOW_CLASSIFIER_UNAVAILABLE";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowClassifierUnavailableError";
+  }
+}
+
+/** The classifier answered with an error or no answer. Recoverable inside `parallel`. */
+export class WorkflowClassifierError extends Error {
+  readonly code = "WORKFLOW_CLASSIFIER_FAILED";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowClassifierError";
+  }
+}
+
+/**
+ * `api.classify()`: answer typed questions about JSON state with a classifier model through the host's
+ * credentials, without a chat session. It shares the run's concurrency cap, budget, and per-agent timeout,
+ * records usage like an agent, and is not journaled, so a resumed run asks again.
+ */
+export async function runClassifier(
+  rc: RunContext,
+  context: ClassifierContext,
+  opts: ClassifyOptions = {},
+): Promise<Record<string, ClassifierAnswer>> {
+  const registry = rc.modelRegistry;
+  return await rc.semaphore.run(async () => {
+    assertWorkflowBudgetAvailable(rc.budget);
+    const model = await cachedClassifierModel(rc, registry, opts.model);
+    const label = opts.label ?? `classify:${model.provider}/${model.id}`;
+    // A stalled classifier must not hold a concurrency slot past the limit agents get.
+    const timeout = AbortSignal.timeout(rc.agentTimeoutMs);
+    const result = await registry.classify(model, context, { signal: rc.signal ? AbortSignal.any([rc.signal, timeout]) : timeout });
+    // One classifier response is one model response: recording it like one keeps per-model usage and the budget
+    // whole. Record before the abort check, since the provider charged for a call that returned as the run stopped.
+    rc.usage.recordAgentSession({
+      label,
+      phase: opts.phase,
+      messages: [{ role: "assistant", provider: result.provider, model: result.model, usage: result.usage }],
+    });
+    throwIfAborted(rc.signal);
+    if (result.stopReason !== "stop" && timeout.aborted) {
+      throw new WorkflowClassifierError(`${label}: classifier timed out after ${rc.agentTimeoutMs}ms`);
+    }
+    if (result.stopReason !== "stop") {
+      throw new WorkflowClassifierError(`${label}: classifier ${result.stopReason}${result.errorMessage ? `: ${result.errorMessage}` : ""}`);
+    }
+    return result.answers;
+  }, { signal: rc.signal });
+}
+
+/** One credential lookup per route and run; a route that failed to resolve keeps failing for the run. */
+function cachedClassifierModel(
+  rc: RunContext,
+  registry: ClassifierRegistry,
+  ref: string | readonly string[] | undefined,
+): Promise<ClassifierModel<ClassifierApi>> {
+  const key = JSON.stringify(ref ?? null);
+  const cached = rc.classifierRoutes?.get(key);
+  if (cached) return cached;
+  const resolved = resolveClassifierModel(registry, ref);
+  rc.classifierRoutes?.set(key, resolved);
+  return resolved;
+}
+
+async function resolveClassifierModel(
+  registry: ClassifierRegistry,
+  ref: string | readonly string[] | undefined,
+): Promise<ClassifierModel<ClassifierApi>> {
+  if (ref !== undefined && typeof ref !== "string") {
+    const available = await registry.getAvailableOfType("classifier");
+    const preferred = ref.map((candidate) => parseAgentModelRef(candidate))
+      .map(({ provider, id }) => available.find((model) => model.provider === provider && model.id === id))
+      .find((model) => model !== undefined);
+    if (!preferred) throw new WorkflowClassifierUnavailableError(`None of the classifier models ${ref.join(", ")} has working credentials.`);
+    return preferred;
+  }
+  if (ref === undefined) {
+    const [available] = await registry.getAvailableOfType("classifier");
+    if (!available) {
+      throw new WorkflowClassifierUnavailableError(
+        "No classifier model has working credentials. Configure one (for example TypeSafe Jev via OpenRouter) or pass { model: \"provider/id\" }.",
+      );
+    }
+    return available;
+  }
+  // Same ref rules as agent({ model }): malformed refs throw, bare ids mean Anthropic.
+  const { provider, id } = parseAgentModelRef(ref);
+  const model = registry.getModelOfType("classifier", provider, id);
+  if (!model) throw new WorkflowClassifierUnavailableError(`Classifier model "${ref}" not found (resolved as ${provider}/${id}).`);
+  return model;
+}

package/.pi/extensions/pi-workflow-engine/src/dynamax.ts

@@ -68,20 +68,13 @@ Adaptive multi-pass workflows are optional. Use a simple single-pass fan-out whe
 - synthesize the first-pass and follow-up results together.
 Do not generate a second pass when the first pass is sufficient, and do not invent iteration, quorum, graph, reduction, or retry primitives for this pattern.`;
 
-export const DYNAMAX_REMINDER = `
-## dynamax workflow opt-in
+/** System prompt section pi wraps as `<dynamax>`; adding or dropping it appends a section patch instead of rewriting the prompt. */
+export const DYNAMAX_SECTION = "dynamax";
 
-The user has opted into dynamax multi-agent orchestration. The workflow tool is permitted for this task. You may either run an existing named workflow or author a new inline workflow script when that best serves the user's request.
-
-Inline workflow rules:
-- Use the injected Type object for schemas, for example Type.Object({ ok: Type.Boolean() }); do not import typebox.
-- Do not use import statements or dynamic import() in inline workflow scripts.
-- Set profile to "small", "medium", or "big" on each agent() call so routing remains explicit; use model/thinkingLevel only for an intentional override.
-- Subagents receive no skills by default. Add \`skills: ["skill-name"]\` per agent only when that stage should load that skill; grant the smallest useful set.
-- Provide exactly one of workflow.name or workflow.script.
-
-${ADAPTIVE_WORKFLOW_GUIDANCE}
-`;
+/** Only the opt-in itself: the authoring rules already reach the model as the workflow tool's guidelines. */
+export const DYNAMAX_REMINDER =
+  "The user opted into dynamax multi-agent orchestration for this request, so the workflow tool is permitted. " +
+  "Run a registered workflow by name, or author an inline workflow script when none fits, following the workflow tool's guidelines.";
 
 export function createDynamaxState(): DynamaxState {
   return { sticky: false, oneShotPending: false, turnActive: false };
@@ -140,11 +133,16 @@ export function dynamaxStatusText(state: DynamaxState, theme: Theme): string {
   return mode ? `${label}${dot(theme)}${theme.fg("muted", mode)}` : label;
 }
 
-export function appendDynamaxSystemReminder(systemPrompt: string, state: DynamaxState): string {
-  if (!state.sticky && !state.oneShotPending) return systemPrompt;
+/**
+ * Add the opt-in section for this run and consume a pending one-shot. pi rebuilds `sections` for every
+ * run, so an inactive run simply leaves it out and pi records the removal as a patch.
+ */
+export function applyDynamaxPromptSection(sections: Record<string, string>, state: DynamaxState): boolean {
+  if (!state.sticky && !state.oneShotPending) return false;
   state.oneShotPending = false;
   state.turnActive = true;
-  return `${systemPrompt}\n\n${DYNAMAX_REMINDER.trim()}`;
+  sections[DYNAMAX_SECTION] = DYNAMAX_REMINDER;
+  return true;
 }
 
 export function registerDynamax(pi: ExtensionAPI, shortcuts: DynamaxShortcuts, options: DynamaxRegistrationOptions): DynamaxHandle {
@@ -238,10 +236,12 @@ export function registerDynamax(pi: ExtensionAPI, shortcuts: DynamaxShortcuts, o
 
   pi.on("before_agent_start", (event, ctx) => {
     const runtime = getDynamaxRuntime(runtimes, ctx);
-    const systemPrompt = appendDynamaxSystemReminder(event.systemPrompt, runtime.state);
-    if (systemPrompt === event.systemPrompt) return undefined;
+    const options = event.systemPromptOptions;
+    if (!applyDynamaxPromptSection(options.sections, runtime.state)) return undefined;
     updateDynamaxSurfaces(ctx, runtime);
-    return { systemPrompt };
+    // An earlier extension forced the whole prompt, and pi renders no sections then; append to its text instead.
+    if (options.forceSystemPrompt === undefined) return undefined;
+    return { systemPrompt: `${options.forceSystemPrompt}\n\n<${DYNAMAX_SECTION}>\n${DYNAMAX_REMINDER}\n</${DYNAMAX_SECTION}>` };
   });
 
   pi.on("agent_end", (_event, ctx) => {

package/.pi/extensions/pi-workflow-engine/src/engine.ts

@@ -7,6 +7,7 @@ import { resolveWorkflowModelProfiles, type ResolvedWorkflowModelProfiles } from
 import { abortReason, isWorkflowPauseError, linkAbortSignal, throwIfAborted } from "./cancellation.ts";
 import { createBudget } from "./budget.ts";
 import { runAgent, type AgentExecutionOptions, type RunContext } from "./agent-runner.ts";
+import { runClassifier } from "./classify.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, formatPerfSummary, type PerfSink } from "./perf.ts";
 import { createWorkflowUsageRecorder, type WorkflowUsageSink } from "./usage.ts";
@@ -177,6 +178,8 @@ export async function runResolvedWorkflow(
       budget,
       journal,
       worktrees,
+      hostTools: resolvedOptions.hostTools,
+      classifierRoutes: new Map(),
     };
 
     // perf.total_ms wraps the whole tree: sub-workflows run inside this span via api.workflow().
@@ -401,6 +404,7 @@ export async function runWorkflowWithContext(
 
   const api: WorkflowApi = {
     agent,
+    classify: (context, classifyOpts) => runClassifier(rc, context, { ...classifyOpts, phase: scope.agentOptions({ phase: classifyOpts?.phase }).phase }),
     workflow,
     parallel: bindParallel({
       signal: rc.signal,

package/.pi/extensions/pi-workflow-engine/src/host-tools.ts

@@ -0,0 +1,76 @@
+import type { AgentToolCallOutcome } from "@earendil-works/pi-agent-core";
+import { defineTool, type ExtensionToolContext, type ToolDefinition, type ToolInfo } from "@earendil-works/pi-coding-agent";
+
+/** pi names MCP tools `mcp__<server>__<tool>`; its MCP extension also registers these resource tools. */
+const MCP_TOOL_PREFIX = "mcp__";
+const MCP_RESOURCE_TOOLS = new Set(["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"]);
+
+/** Mirrors pi's own `isMcpToolName`, which the package does not export. */
+export function isMcpToolName(name: string): boolean {
+  return name.startsWith(MCP_TOOL_PREFIX) || MCP_RESOURCE_TOOLS.has(name);
+}
+
+/** An agent named MCP tools it cannot reach. Raised before prompting so it never runs without them. */
+export class WorkflowHostToolUnavailableError extends Error {
+  readonly code = "WORKFLOW_HOST_TOOL_UNAVAILABLE";
+  readonly tools: readonly string[];
+
+  constructor(tools: readonly string[], bridged: boolean) {
+    super(
+      bridged
+        ? `Host MCP tools not available: ${tools.join(", ")}`
+        : `MCP tools reach subagents only in runs started by the workflow tool; unavailable: ${tools.join(", ")}`,
+    );
+    this.name = "WorkflowHostToolUnavailableError";
+    this.tools = [...tools];
+  }
+}
+
+/**
+ * Host-only tools a subagent can reach through the host session. Subagents are SDK sessions, which
+ * load none of pi's built-in extensions, so they connect no MCP servers of their own; proxies call the
+ * host's tools over its existing connections and through its `tool_call` permission handlers. They act
+ * in the host's context, so a local MCP tool sees the main checkout even for an isolated worktree agent.
+ */
+export interface HostToolBridge {
+  /** Callable host MCP tools, read as each agent starts so servers that connected mid-run are included. */
+  tools(): readonly ToolInfo[];
+  execute(name: string, args: unknown, signal: AbortSignal | undefined): Promise<AgentToolCallOutcome>;
+}
+
+/**
+ * `executeTool` exists only while the host's tool call runs, so only a synchronous `workflow` tool run
+ * gets a bridge; `/workflow` commands and background runs that outlive the call do not.
+ */
+export function createHostToolBridge(
+  registeredTools: () => readonly ToolInfo[],
+  ctx: Pick<ExtensionToolContext, "tools" | "executeTool">,
+): HostToolBridge {
+  return {
+    tools() {
+      const callable = new Set(ctx.tools.map((tool) => tool.name));
+      return registeredTools().filter((tool) => isMcpToolName(tool.name) && callable.has(tool.name));
+    },
+    execute: (name, args, signal) => ctx.executeTool(name, args, { signal }),
+  };
+}
+
+/**
+ * A subagent tool that runs the host tool. It reports no usage: pi already adds nested calls' usage to
+ * the host's `workflow` tool result.
+ */
+export function hostToolProxy(tool: ToolInfo, bridge: HostToolBridge): ToolDefinition {
+  return defineTool({
+    name: tool.name,
+    label: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+    promptGuidelines: tool.promptGuidelines,
+    namespace: tool.namespace,
+    annotations: tool.annotations,
+    async execute(_toolCallId, params, signal) {
+      const outcome = await bridge.execute(tool.name, params, signal);
+      return { content: outcome.result.content, details: undefined, ...(outcome.isError ? { isError: true } : {}) };
+    },
+  });
+}

package/.pi/extensions/pi-workflow-engine/src/model-ref.ts

@@ -0,0 +1,19 @@
+/** Parse a model ref: a bare id is Anthropic shorthand, otherwise "provider/id". Malformed refs throw. */
+export function parseAgentModelRef(modelRef: string): { readonly provider: string; readonly id: string } {
+  const normalized = modelRef.trim();
+  if (normalized.length === 0) {
+    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
+  }
+  if (normalized !== modelRef) {
+    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
+  }
+
+  const slash = modelRef.indexOf("/");
+  if (slash === -1) return { provider: "anthropic", id: modelRef };
+  const provider = modelRef.slice(0, slash);
+  const id = modelRef.slice(slash + 1);
+  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
+    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
+  }
+  return { provider, id };
+}

package/.pi/extensions/pi-workflow-engine/src/pi-compat.ts

@@ -1,6 +1,6 @@
-const MINIMUM_PI_VERSION = "0.80.10";
+const MINIMUM_PI_VERSION = "1.0.0";
 
-const MINIMUM_PI_CORE = [0, 80, 10] as const;
+const MINIMUM_PI_CORE = [1, 0, 0] as const;
 
 /** Fail during extension registration instead of failing later in a workflow. */
 export function assertSupportedPiVersion(version: string): void {

package/.pi/extensions/pi-workflow-engine/src/research-evidence.ts

@@ -155,8 +155,10 @@ const UNAVAILABLE_RESEARCH = {
     nextStep: "Run `/workflow research <question>` and include any source, date, or geography constraints in the arguments.",
   },
   "missing-capability": {
-    message: "Research could not start because pi exposed no installed external web-search or URL-extraction tool.",
-    nextStep: "Install or enable a pi tool that can search the web or extract HTTP(S) pages, then rerun the workflow.",
+    message: "Research could not start because its agents could reach no external web-search or URL-extraction tool.",
+    nextStep:
+      "Install or enable a pi tool that can search the web or extract HTTP(S) pages, then rerun the workflow. " +
+      "An MCP web search server counts only when the host agent runs research through the workflow tool, for example after `dynamax`.",
   },
   "lanes-failed": {
     message: "Research could not gather direct-page evidence because one or more research lanes failed.",

package/.pi/extensions/pi-workflow-engine/src/tool-capabilities.ts

@@ -1,4 +1,5 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import { isMcpToolName } from "./host-tools.ts";
 import type { AgentToolHint } from "./types.ts";
 
 /** Raised before prompting when required semantic tool capabilities are unavailable. */
@@ -6,8 +7,12 @@ export class WorkflowToolHintUnavailableError extends Error {
   readonly code = "WORKFLOW_TOOL_HINT_UNAVAILABLE";
   readonly hints: readonly AgentToolHint[];
 
-  constructor(hints: readonly AgentToolHint[]) {
-    super(`Required workflow tool capability unavailable: ${hints.join(", ")}`);
+  constructor(hints: readonly AgentToolHint[], options: { readonly hostToolsReachable?: boolean } = {}) {
+    // Host MCP tools only count in runs that can reach them; say so rather than imply none are installed.
+    const mcpNote = hints.includes("external-search") && options.hostToolsReachable === false
+      ? " (MCP tools reach subagents only in runs started by the workflow tool)"
+      : "";
+    super(`Required workflow tool capability unavailable: ${hints.join(", ")}${mcpNote}`);
     this.name = "WorkflowToolHintUnavailableError";
     this.hints = [...hints];
   }
@@ -18,7 +23,9 @@ export function matchesAgentToolHint(tool: ToolInfo, hint: AgentToolHint): boole
 }
 
 function isExternalSearchLikeTool(tool: ToolInfo): boolean {
-  if (isMutationLikeToolName(tool.name) || tool.sourceInfo.source === "builtin") return false;
+  if (isMutationLikeToolName(tool.name) || isPiLocalTool(tool)) return false;
+  // MCP servers declare these hints: a tool that changes its environment or stays in a closed domain is not web research.
+  if (tool.annotations?.readOnlyHint === false || tool.annotations?.openWorldHint === false) return false;
   const name = tool.name.toLowerCase();
   const description = [tool.description, ...(tool.promptGuidelines ?? [])].join(" ").toLowerCase();
   const text = `${name} ${description}`;
@@ -40,6 +47,11 @@ function isSearchLikeTool(tool: ToolInfo): boolean {
   return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(tool.description.toLowerCase());
 }
 
+/** pi's own tools, such as read and bash. MCP tools also come from a built-in extension but reach outside it. */
+function isPiLocalTool(tool: ToolInfo): boolean {
+  return tool.sourceInfo.source === "builtin" && !isMcpToolName(tool.name);
+}
+
 function isMutationLikeToolName(name: string): boolean {
   return /(?:edit|write|replace|patch|apply|delete|remove|move|rename|create|commit|push)/.test(name.toLowerCase());
 }

package/.pi/extensions/pi-workflow-engine/src/types.ts

@@ -1,4 +1,5 @@
 import type { Static, TSchema } from "typebox";
+import type { ClassifierAnswer, ClassifierContext } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { WorkflowBudget } from "./budget.ts";
 import type { Pipeline, WorkflowParallel } from "./concurrency.ts";
@@ -10,6 +11,7 @@ import type { WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "./progres
 import type { WorkflowUsageSnapshot } from "./usage.ts";
 import type { WorktreeBaseline } from "./worktree.ts";
 import type { WorkflowModelProfileName } from "./model-profiles.ts";
+import type { HostToolBridge } from "./host-tools.ts";
 import type { WorkflowRunState } from "./workflow-run-record.ts";
 
 export type { WorkflowLaneItemStatus } from "./progress-types.ts";
@@ -79,6 +81,8 @@ export interface WorkflowRunOptions {
   signal?: AbortSignal;
   /** Internal recorder override for command/tool invocation timing. */
   perfRecorder?: PerfSink;
+  /** Internal bridge to the host session's MCP tools, available while a `workflow` tool call runs. */
+  hostTools?: HostToolBridge;
   /** Resolve a sub-workflow reference to a module, enabling `api.workflow()`. When omitted, `api.workflow()` throws. */
   resolveWorkflow?: (ref: WorkflowRef) => Promise<LoadedWorkflow>;
   /** Called with the final performance snapshot when perf is enabled. */
@@ -185,6 +189,19 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   schema?: S;
 }
 
+/** Options for `api.classify()`. */
+export interface ClassifyOptions {
+  /**
+   * Classifier model as "provider/id", or refs in preference order of which the first with working
+   * credentials is used. Default: the first classifier model with working credentials.
+   */
+  model?: string | readonly string[];
+  /** Label for usage reporting. Default: `classify:<provider>/<id>`. */
+  label?: string;
+  /** Phase to attribute usage to. Default: the current phase. */
+  phase?: string;
+}
+
 /**
  * The primitives injected into every workflow run. A workflow is any module that
  * exports `meta` plus a default `async (api: WorkflowApi) => result`.
@@ -201,6 +218,13 @@ export interface WorkflowApi {
   agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S>>;
   /** Run a subagent and return its final assistant text. */
   agent(prompt: string, opts?: AgentOptions): Promise<string>;
+  /**
+   * Answer typed `choice`/`score`/`bool` questions about JSON `state` with a classifier model, without
+   * starting a chat session: a cheap gate for triage, deduplication, or routing between stages. Answers
+   * are keyed by question id. Rejects with a recoverable error when no classifier is configured or the
+   * call fails; results are not journaled, so a resumed run classifies again.
+   */
+  classify(context: ClassifierContext, opts?: ClassifyOptions): Promise<Record<string, ClassifierAnswer>>;
   /**
    * Run another registered workflow inline as a sub-step and return its result. The child shares
    * this run's concurrency cap, abort signal, and perf sink. Nests one level only: calling

package/.pi/extensions/pi-workflow-engine/src/usage.ts

@@ -1,3 +1,4 @@
+import type { Usage } from "@earendil-works/pi-ai";
 import { isFiniteNumber, isRecord } from "./guards.ts";
 import { formatCount } from "./text.ts";
 
@@ -81,9 +82,14 @@ export class WorkflowUsageRecorder implements WorkflowUsageSink {
       const parsed = parseAssistantUsageMessage(message);
       return parsed ? [parsed] : [];
     });
-    if (assistantMessages.length === 0) return;
+    // Tools that call models themselves, such as codemode running a classifier, report it on their result.
+    const toolUsage = input.messages.flatMap((message) => {
+      const parsed = parseToolResultUsage(message);
+      return parsed ? [parsed] : [];
+    });
+    if (assistantMessages.length === 0 && toolUsage.length === 0) return;
 
-    const usage = sumTotals(assistantMessages.map((message) => message.usage));
+    const usage = sumTotals([...assistantMessages.map((message) => message.usage), ...toolUsage]);
     const latestMetadata = assistantMessages.findLast((message) => message.provider !== undefined || message.model !== undefined);
     this.agents.push({
       label: input.label,
@@ -127,6 +133,13 @@ export function hasWorkflowUsage(snapshot: unknown): snapshot is WorkflowUsageSn
   return snapshot.totals.totalTokens > 0 || snapshot.totals.cost.total > 0;
 }
 
+/** The run's subagent totals as pi's `Usage`, so a tool result adds them to the session's cost. */
+export function workflowUsageForPi(snapshot: unknown): Usage | undefined {
+  if (!hasWorkflowUsage(snapshot)) return undefined;
+  const { input, output, cacheRead, cacheWrite, totalTokens, cost } = snapshot.totals;
+  return { input, output, cacheRead, cacheWrite, totalTokens, cost: { ...cost } };
+}
+
 export function formatWorkflowUsageLine(snapshot: unknown): string | undefined {
   if (!hasWorkflowUsage(snapshot)) return undefined;
   const parts = formatWorkflowUsageComponents(snapshot.totals);
@@ -217,6 +230,11 @@ function parseAssistantUsageMessage(message: unknown): AssistantUsageMessage | u
   };
 }
 
+function parseToolResultUsage(message: unknown): WorkflowUsageTotals | undefined {
+  if (!isRecord(message) || message.role !== "toolResult") return undefined;
+  return parseUsageTotals(message.usage);
+}
+
 function parseUsageTotals(value: unknown): WorkflowUsageTotals | undefined {
   if (!isRecord(value)) return undefined;
   const input = finiteNumber(value.input);

package/.pi/extensions/pi-workflow-engine/src/workflow-advisory-utils.ts

@@ -1,5 +1,8 @@
 import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, formatAdvisoryLocation, type AdvisoryCandidate, type AdvisoryFinding, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
-import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
+import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, mergeCandidateInto, repoPathCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
+import { isFatalWorkflowError } from "./cancellation.ts";
+import { WorkflowClassifierUnavailableError } from "./classify.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 import type { AgentOptions, WorkflowApi, WorkflowProgressEvent, WorkflowRunStats } from "./types.ts";
 
 
@@ -49,7 +52,7 @@ export function publishVerifiedKeptProgress(
 }
 
 export interface LensVerificationPipelineOptions {
-  api: Pick<WorkflowApi, "agent" | "parallel" | "phase" | "progress" | "log">;
+  api: Pick<WorkflowApi, "agent" | "classify" | "parallel" | "phase" | "progress" | "log">;
   lenses: readonly AdvisoryLens[];
   perLens: number;
   finderPhase?: "Find" | "Hypothesize";
@@ -90,7 +93,7 @@ export async function runLensVerificationPipeline(
     }
     return candidates;
   } })), coverage);
-  const candidates = dedupeCandidates(found.flat());
+  const candidates = await mergeEquivalentCandidates(api, dedupeCandidates(found.flat()));
   const dropped = rawCandidates - candidates.length;
   if (dropped > 0) {
     api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
@@ -112,6 +115,106 @@ export async function runLensVerificationPipeline(
   return { verified, rawCandidates, dropped, coverage };
 }
 
+/** TypeSafe Jev routes in preference order. Jev is the classifier the duplicate merge was measured with. */
+export const DUPLICATE_CANDIDATE_CLASSIFIERS = [
+  "typesafe/jev-latest",
+  "openrouter/~typesafe/jev-latest",
+  "openrouter/typesafe/jev-1.13",
+  "cloudflare-workers-ai/typesafe/jev",
+  "vercel-ai-gateway/typesafe-ai/jev",
+  "opencode/jev-1.13",
+  "opencode/jev-1.13-free",
+] as const;
+
+/** Probability above which two candidates count as one defect. */
+const SAME_DEFECT_PROBABILITY = 0.8;
+
+/**
+ * Merge same-file candidates that a classifier judges to be one defect, so each defect gets one verifier.
+ * Lenses often report the same bug in different words; on GPT-6.1 Sol code reviews this cut verifier
+ * agents and cost by about 40% without losing a finding. Runs without a reachable Jev classifier skip it.
+ */
+export async function mergeEquivalentCandidates<T extends IdentifiedAdvisoryCandidate>(
+  api: Pick<WorkflowApi, "classify" | "parallel" | "log">,
+  candidates: readonly T[],
+): Promise<T[]> {
+  const files = candidates.map(candidateFile);
+  const pairs: Array<readonly [number, number]> = [];
+  for (let first = 0; first < candidates.length; first++) {
+    for (let second = first + 1; second < candidates.length; second++) {
+      if (files[first] === files[second]) pairs.push([first, second]);
+    }
+  }
+  if (pairs.length === 0) return [...candidates];
+  const sameDefect = async ([first, second]: readonly [number, number]): Promise<number> => {
+    const answers = await api.classify({
+      state: { first: candidateForClassifier(candidates[first]!), second: candidateForClassifier(candidates[second]!) },
+      questions: {
+        same: {
+          type: "bool",
+          instructions: "Two code-review candidates were raised against the same file. Do they describe the same underlying defect (same root cause and same fix), even if worded differently?",
+          criteria: { true: "Same underlying defect", false: "Different defects" },
+        },
+      },
+    }, { model: DUPLICATE_CANDIDATE_CLASSIFIERS, label: "dedup" });
+    return answers.same?.type === "bool" ? answers.same.probability : 0;
+  };
+  // The first call probes the classifier: if it fails for any reason (no Jev route, bad credentials, a rate
+  // limit), skip the merge rather than send every other pair into the same failure.
+  let firstProbability: number;
+  try {
+    firstProbability = await sameDefect(pairs[0]!);
+  } catch (error) {
+    if (isFatalWorkflowError(error, undefined)) throw error;
+    if (!(error instanceof WorkflowClassifierUnavailableError)) api.log(`Skipped merging duplicate candidates: ${unknownErrorMessage(error)}`);
+    return [...candidates];
+  }
+  if (pairs.length > 1) api.log(`Comparing ${pairs.length} same-file candidate pairs for duplicates`);
+  const rest = await api.parallel(pairs.slice(1).map((pair) => () => sameDefect(pair)));
+  const probability = new Map<string, number>();
+  pairs.forEach(([first, second], index) => probability.set(`${first}:${second}`, index === 0 ? firstProbability : rest[index - 1] ?? 0));
+
+  // Complete linkage: a candidate joins a group only when it matches every member, so one vague candidate
+  // that resembles two different defects cannot chain them together.
+  const groups: number[][] = [];
+  candidates.forEach((_, index) => {
+    const group = groups.find((members) =>
+      members.every((member) => (probability.get(`${member}:${index}`) ?? 0) >= SAME_DEFECT_PROBABILITY));
+    if (group) group.push(index);
+    else groups.push([index]);
+  });
+  const merged = groups.map(([keep, ...folded]) => {
+    const kept = { ...candidates[keep!]! };
+    for (const index of folded) {
+      const duplicate = candidates[index]!;
+      mergeCandidateInto(kept, duplicate);
+      // The kept summary leads; keep folded wording visible to the verifier in case the classifier was wrong.
+      if (duplicate.summary !== kept.summary) {
+        kept.discoveryEvidence = [...new Set([...(kept.discoveryEvidence ?? []), `Also reported as: ${duplicate.summary}`])];
+      }
+    }
+    return kept;
+  });
+  const folded = candidates.length - merged.length;
+  if (folded > 0) api.log(`Merged ${folded} candidate(s) describing the same defect before verification`);
+  return merged;
+}
+
+/** Pair by the changed line when there is one, with the repository-relative path exact dedup uses. */
+function candidateFile(candidate: IdentifiedAdvisoryCandidate): string {
+  return repoPathCandidates((candidate.reviewAnchor ?? primaryLocation(candidate)).file)[1];
+}
+
+function candidateForClassifier(candidate: IdentifiedAdvisoryCandidate) {
+  return {
+    category: candidate.category,
+    summary: candidate.summary,
+    impact: candidate.impact,
+    location: formatLocation(candidate),
+    evidence: (candidate.discoveryEvidence ?? []).slice(0, 4),
+  };
+}
+
 /** Stats for a lens review that stopped before discovery. */
 export const EMPTY_LENS_REVIEW_STATS: Readonly<WorkflowRunStats> = Object.freeze({ files: 0, candidates: 0, verified: 0, kept: 0, dropped: 0, refuted: 0 });
 

package/README.md

@@ -15,7 +15,7 @@ one-off workflow for the task.
 
 ## Quick start
 
-Requires **pi 0.80.10 or newer**.
+Requires **pi 1.0.0 or newer**.
 
 ```bash
 pi install npm:pi-workflow-engine

package/USAGE.md

@@ -2,7 +2,7 @@
 
 `pi-workflow-engine` adds zero-dependency Dynamax workflows to pi: opt into live, parallel subagents for the tasks that need a custom investigation instead of one long prompt. Most users only need these surfaces:
 
-This release requires **pi 0.80.10 or newer**. pi remains host-provided rather
+This release requires **pi 1.0.0 or newer**. pi remains host-provided rather
 than bundled by this package, and the extension rejects older runtimes at load
 time with an update message.
 
@@ -109,7 +109,9 @@ command instead of selecting another model.
 as external web search, browsing, or HTTP(S) page extraction. Local grep/find
 tools do not satisfy this check. The workflow does not bundle a scraper or a
 paid API; install or enable the web capability you prefer, then restart or
-reload pi so subagent sessions can see it.
+reload pi so subagent sessions can see it. An MCP web search server also
+qualifies when the host agent runs `research` through the `workflow` tool,
+because only those runs can reach the host's MCP tools.
 
 The workflow bounds decomposition to four lanes and verification to twelve
 claims, while the engine's concurrency, total-agent, timeout, cancellation, and
@@ -146,7 +148,7 @@ Sticky mode and inspector shortcut:
 
 The workflow inspector and code-review results viewer are also registered as first-class shortcuts shown by `/hotkeys`. The defaults are `ctrl+shift+m` for the inspector and `ctrl+shift+r` for the latest review results. `ctrl+o` is intentionally not used because pi already uses it for tool-output expansion and tree filtering.
 
-When only the literal `dynamax` token is used, the opt-in is one-shot: the next agent run receives the workflow permission reminder, stays visibly active for that run, then clears after the run ends. When `/workflow:dynamax on` is used, the opt-in is sticky for the current pi session until `/workflow:dynamax off`. The footer status states the mode compactly: `◆ dynamax` while sticky, `◆ dynamax · next prompt` while a one-shot waits for its prompt, and `◆ dynamax · this turn` while that run is active; off mode clears it. A running workflow names itself in its own status next to it.
+When only the literal `dynamax` token is used, the opt-in is one-shot: the next agent run receives a `<dynamax>` system prompt section that permits the workflow tool (pi appends it as a section patch, so the cached prompt head is kept), stays visibly active for that run, then clears after the run ends. When `/workflow:dynamax on` is used, the opt-in is sticky for the current pi session until `/workflow:dynamax off`. The footer status states the mode compactly: `◆ dynamax` while sticky, `◆ dynamax · next prompt` while a one-shot waits for its prompt, and `◆ dynamax · this turn` while that run is active; off mode clears it. A running workflow names itself in its own status next to it.
 
 ### Prompt editor cue
 
@@ -160,7 +162,7 @@ The default effect is `shine`. Set `PI_DYNAMAX_EFFECT=static` for a motionless
 cue or `PI_DYNAMAX_EFFECT=off` to disable it. A non-empty `NO_COLOR` also
 disables the default cue; an explicit `PI_DYNAMAX_EFFECT` value takes precedence.
 
-The implementation follows pi 0.80.10's [official `CustomEditor`
+The implementation follows pi's [official `CustomEditor`
 pattern](https://pi.dev/docs/latest/extensions#custom-editor): it decorates only
 the editor's rendered lines, retaining the wrapped editor's input, cursor,
 deletion, paste, multiline, undo, completion, IME, and app-keybinding behavior.
@@ -423,6 +425,11 @@ overrides its profile.
 
 `tools` is a strict allowlist. If you set `tools: ["read", "bash"]`, extension tools such as `ast-grep`, `mgrep`, `fffind`, or `ffgrep` are hidden from that subagent. Add `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools while keeping the concrete base allowlist portable. Use `toolHints: ["external-search"]` for installed web search, browsing, and URL-extraction tools; `requireToolHints: true` fails before prompting unless each requested capability matched. The built-in advisory workflows use `tools: ["read", "bash", "grep", "find", "ls"]` plus `toolHints: ["search"]`.
 
+Subagents are SDK sessions, so pi's built-in codemode and MCP extensions do not load in them. Two opt-ins cover that:
+
+- **Codemode.** Add `"codemode"` to an agent's `tools` to let it batch or filter many tool calls in one script, for example `tools: ["read", "grep", "codemode"]`. Scripts can call only that agent's other allowed tools, and never `final_answer`. Classifier calls a script makes count toward the run's usage and budget.
+- **Host MCP tools.** In runs started by the `workflow` tool, subagents reach the host's MCP tools over its existing connections and through its permission handlers. Name a tool in `tools` (for example `"mcp__linear__create_issue"`), or use `toolHints: ["external-search"]` to pick up MCP web research tools; servers that declare a tool not read-only or closed-world are excluded from that hint. Bridged tools act in the host session, so the local `search` hint never bridges them, and an isolated worktree agent that names a local MCP tool sees the main checkout through it, not its worktree. `/workflow` commands and background runs outlive the host tool call that makes this possible: an agent there that names an MCP tool fails before prompting rather than running without it.
+
 Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; if `tools` is also restricted, the engine automatically keeps `read` available so the subagent can load the selected `SKILL.md`. When `skills` is omitted, clear prompt text such as `/skill:name`, `include skill name`, or `use the name skill` is also treated as an opt-in. Pass `skills: []` to suppress that inference.
 
 Set `model` only when a subagent should use a specific model. Bare ids keep the Anthropic shorthand; `provider/id` targets built-in, custom, or local providers. Explicit models override a requested profile; calls with neither inherit the host/session default. Malformed or unknown explicit refs fail fast.
@@ -461,6 +468,25 @@ export default async function run({ workflow }: WorkflowApi) {
 
 Nesting is one level only: calling `workflow()` from inside a sub-workflow rejects. Resolution throws on an unknown name. Inside `parallel()` or `pipeline()`, recoverable branch errors become `null` results, so filter nulls before synthesis; a genuine run abort still rejects.
 
+### Classify between stages
+
+`classify(context, opts?)` answers typed `choice`, `score`, or `bool` questions about JSON `state` with one of pi's classifier models (for example TypeSafe Jev or Cloudflare Clef), using the host's credentials and no chat session. It suits cheap gates between stages, such as deduplicating findings or deciding which items need a follow-up agent.
+
+```ts
+const answers = await api.classify(
+  {
+    state: { finding },
+    questions: {
+      followUp: { type: "bool", instructions: "Does this finding need verification?", criteria: { true: "Plausible but unproven", false: "Clearly settled" } },
+    },
+  },
+  { label: `triage:${finding.id}` },
+);
+if (answers.followUp?.type === "bool" && answers.followUp.probability > 0.5) { /* verify it */ }
+```
+
+Without `opts.model` ("provider/id"), the first classifier with working credentials is used. Calls share the run's concurrency cap, count toward usage and the budget, and are not journaled, so a resumed run classifies again. When no classifier is configured the call rejects with a recoverable error, so guard it or let `parallel()` turn it into `null`.
+
 ### Where workflows live
 
 Guaranteed built-ins are statically registered:
@@ -575,6 +601,25 @@ fails, the result retains verified records and reports incomplete coverage.
 Synthesis selects or merges IDs; the workflow reconstructs evidence-bearing
 fields from those records.
 
+### Duplicate candidates
+
+Lenses often report the same defect in different words. When a TypeSafe Jev
+classifier is reachable (TypeSafe directly, OpenRouter, Cloudflare Workers AI,
+Vercel AI Gateway, or OpenCode Zen), the four advisory workflows ask it whether
+each pair of candidates in the same file describes one defect. Before
+verification, a candidate joins a group only when the classifier is at least 80%
+sure it matches every member, so each defect gets one verifier. Merged
+candidates keep all of their source IDs, locations, impacts, and evidence, and
+the verifier sees the other wordings as "Also reported as" evidence. If the
+first comparison fails (no Jev credentials, a bad key, a rate limit), the merge
+is skipped.
+
+Measured on GPT-6.1 Sol code reviews with planted bugs, the merge cut verifier
+agents and cost by about 40% (e.g. 29 → 18 agents, $0.60 → $0.37 list price on
+a small diff; 22 → 14 agents, $1.74 → $0.89 on a 160 KB diff). In every
+instrumented run, each planted bug that a finder proposed reached the final
+report, with or without merging.
+
 ### Selective adversarial challenges
 
 Add `--challenge` to an advisory workflow to challenge up to three uncertain or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [