@diousk/pi-subagents-fast 0.21.0 → 0.23.0

package/dist/ui/model-routing-menu.js

@@ -0,0 +1,116 @@
+import { Input, Text } from "@earendil-works/pi-tui";
+import { loadRoutingPolicy } from "../model-routing.js";
+import { parseJevConfig, ROUTING_THINKING_LEVELS } from "../routing-config.js";
+import { loadSettings, projectRoutingSettings } from "../settings.js";
+/** Input handles paste/editing, but its unmasked renderer is never called. */
+export async function maskedApiKey(ctx) {
+    return ctx.ui.custom((_tui, _theme, _kb, done) => {
+        const input = new Input();
+        input.onSubmit = value => done(value.trim());
+        input.onEscape = () => done(undefined);
+        return {
+            render: (width) => new Text(`Typesafe API key: ${"*".repeat(input.getValue().length)}\nEnter to save; Esc to cancel`, 0, 0).render(width),
+            invalidate: () => { },
+            handleInput: (data) => input.handleInput(data),
+        };
+    });
+}
+/** Simple mode, guideline, models and credentials; saves project overrides. */
+export async function showRoutingMenu(ctx) {
+    const settings = loadSettings(ctx.cwd);
+    const local = projectRoutingSettings(ctx.cwd);
+    const policy = loadRoutingPolicy(ctx.cwd);
+    const labels = { agents: "Custom agents", guideline: "Custom guideline", jev: "Jev", baseline: "Existing model" };
+    const inactive = policy.source === "agents" ? "Guideline and Jev are inactive while custom agents exist."
+        : policy.source === "guideline" ? "Jev is inactive while a custom guideline is configured." : "";
+    const note = policy.mode === "off" ? "No routing guidance or Jev requests."
+        : policy.mode === "shadow" ? `Observe Jev; actual choice: ${labels[policy.source]}. Jev calls may incur charges.`
+            : policy.mode === "jev" ? `Jev first; fallback: ${labels[policy.fallbackSource ?? "baseline"]}.${policy.jev ? "" : " Configure Jev models and credentials to use Jev."}`
+                : policy.diagnostic ?? inactive;
+    const choice = await ctx.ui.select(`Model routing: ${policy.mode} — ${note || labels[policy.source]}`, [
+        "Routing mode", "Custom guideline path", "Jev models and descriptions", "Typesafe API key", "Use Pi/environment credentials", "Disable custom guideline", "Disable Jev", "Back",
+    ]);
+    if (!choice || choice === "Back")
+        return;
+    if (choice === "Routing mode") {
+        const modes = [
+            { mode: "auto", label: "auto — default priority: agents, guideline, Jev, existing model" },
+            { mode: "shadow", label: "shadow — record Jev suggestions; keep the default model (may incur charges)" },
+            { mode: "jev", label: "jev — Jev first; default-priority fallback on uncertainty or failure" },
+            { mode: "off", label: "off — no routing guidance or Jev requests" },
+        ];
+        const selected = await ctx.ui.select(`Routing mode (current: ${policy.mode})`, modes.map(entry => entry.label));
+        const mode = modes.find(entry => entry.label === selected)?.mode;
+        return mode ? { routingMode: mode } : undefined;
+    }
+    if (choice === "Disable custom guideline")
+        return { customGuideline: false };
+    if (choice === "Disable Jev")
+        return { jev: false };
+    if (choice === "Custom guideline path") {
+        const path = await ctx.ui.input("Routing guideline Markdown path", typeof settings.customGuideline === "string" ? settings.customGuideline : "~/.pi/agent/agents/custom-route.md");
+        return path?.trim() ? { customGuideline: path.trim() } : undefined;
+    }
+    const models = settings.jev ? settings.jev.models.map(entry => ({ ...entry })) : [];
+    // Creating a project block must not silently copy a global credential.
+    const localKey = local.jev ? local.jev.TYPESAFE_API_KEY : undefined;
+    if (choice === "Use Pi/environment credentials")
+        return models.length ? { jev: { models } } : undefined;
+    if (choice === "Typesafe API key") {
+        if (!models.length) {
+            ctx.ui.notify("Configure Jev models first.", "info");
+            return;
+        }
+        const key = await maskedApiKey(ctx);
+        if (!key)
+            return;
+        try {
+            return { jev: parseJevConfig({ models, TYPESAFE_API_KEY: key }) };
+        }
+        catch (err) {
+            ctx.ui.notify(err instanceof Error ? err.message : "Invalid Jev settings", "warning");
+            return;
+        }
+    }
+    for (;;) {
+        const options = [...models.map((entry, index) => `${index + 1}. ${entry.model} (${entry.thinkingLevel})`), "Add model", "Save", "Cancel"];
+        const action = await ctx.ui.select("Jev models — describe which tasks each model should handle", options);
+        if (!action || action === "Cancel")
+            return;
+        if (action === "Save") {
+            try {
+                return { jev: parseJevConfig({ models, ...(localKey ? { TYPESAFE_API_KEY: localKey } : {}) }) };
+            }
+            catch (err) {
+                ctx.ui.notify(err instanceof Error ? err.message : "Invalid Jev models", "warning");
+                continue;
+            }
+        }
+        const index = options.indexOf(action);
+        const current = action === "Add model" ? undefined : models[index];
+        if (current) {
+            const edit = await ctx.ui.select(current.model, ["Edit", "Remove", "Back"]);
+            if (edit === "Remove") {
+                models.splice(index, 1);
+                continue;
+            }
+            if (edit !== "Edit")
+                continue;
+        }
+        const model = await ctx.ui.input("Exact provider/model-id", current?.model);
+        if (!model)
+            continue;
+        const description = await ctx.ui.editor("Tasks this model is suitable for", current?.description ?? "");
+        if (!description?.trim())
+            continue;
+        const selectedLevel = await ctx.ui.select(`Thinking level (required${current ? `; current: ${current.thinkingLevel}` : ""})`, [...ROUTING_THINKING_LEVELS]);
+        const thinkingLevel = ROUTING_THINKING_LEVELS.find(level => level === selectedLevel);
+        if (!thinkingLevel)
+            continue;
+        const entry = { model: model.trim(), description: description.trim(), thinkingLevel };
+        if (current)
+            models[index] = entry;
+        else
+            models.push(entry);
+    }
+}

package/dist/workflow/host.js

@@ -260,6 +260,8 @@ export function createWorkflowHost(deps) {
             try {
                 const { record } = await manager.spawnAndWait(pi, ctx, dispatch.type, request.prompt, {
                     description: request.label,
+                    agentConfig: config,
+                    routing: { modelExplicit: modelInput !== undefined, thinkingExplicit: request.effort !== undefined || config?.thinking !== undefined, entrypoint: "workflow" },
                     // The stamp is what keeps this child out of the session's
                     // `maxConcurrent` pool — see `occupiesPoolSlot`. The run already
                     // bounds how many of its agents run at once, and counting them

package/docs/rpc.md

@@ -34,6 +34,7 @@ For the channel list, the reply envelope, the per-channel snippets and the event
 
 | Field | Why it is taken away |
 |---|---|
+| `routing`, `agentConfig` | Private routing provenance and selected agent definition; callers cannot turn an explicit model into an inherited default or inject a Jev policy |
 | `parentAgentId` | Ownership. A forged parent hides your agent under someone else's nested tools |
 | `workflowId` | A forged value would hide an RPC-spawned agent inside someone else's workflow — and take it out of the concurrency pool with it |
 | `depth`, `maxSubagentDepth` | The nesting cap is inherited, not declared |
@@ -52,6 +53,12 @@ Four things that are not obvious from the tables:
 - **`structuredOutput` is documented "set only by the workflow host"** (`src/agent-manager.ts:231-234`) and is also not stripped.
 - **`signal` and the `on*` callbacks are function values.** They work only because the bus is in-process. A caller that genuinely serializes its payload cannot use them, and they arrive as `undefined` rather than failing.
 
+### Model routing
+
+RPC and the manager registry follow the [same routingMode setting](../README.md#model-routing) as the tools. Under `auto` (default), enabled custom agents and a configured guideline take priority; with Jev active, a fresh spawn omitting both `model` and `thinkingLevel` is classified before worktree/session creation. Providing either field skips classification only under `auto`. A selected Jev profile applies its model and required `thinkingLevel` together; Pi clamps the level to model support. Shadow and fallback preserve both original values. Under `jev`, Jev chooses first, including over explicit or agent-file models; missing credentials, invalid configuration, uncertainty or errors keep the default-priority choice. Under `shadow`, the same check records a suggestion but preserves that choice. Under `off`, routing guidance and Jev are disabled. `null` means omitted. No mode creates an extra main-agent turn to interpret descriptions or Markdown. `awaitStartup` includes classification and its two-second deadline, while cancellation stops startup.
+
+Completion events expose the credential-free `routing` decision and optional classifier-only `routingUsage`. `routing.mode` identifies the mode, `model` and `thinkingLevel` an applied Jev profile, `suggestedModel` and `suggestedThinkingLevel` an observed shadow profile, and `fallbackSource` the preserved default source. Classifier tokens are separate from coding token totals; reported classifier cost, including shadow requests, is included in total cost once. `routing.unpriced` means the catalog does not provide a price. Settings events omit literal TypeSafe keys.
+
 ### Names that look right and are not
 
 One of these already shipped as a bug in this project's own README example, so it is worth reading the table even if you are sure.

package/docs/workflows.md

@@ -308,6 +308,10 @@ A run's concurrency limit is its own, independent of the session's `maxConcurren
 
 ### Settings and the CLI flag
 
+Workflow children follow [Model routing](../README.md#model-routing). With `routingMode: "auto"` (default), custom agents come first, then a main-agent Markdown guideline, then optional Jev, then the existing model. The main agent receives the guideline before writing the script and can express its choice through `agent(prompt, { model, effort })`. Either explicit option skips Jev under `auto`; workflow options retain their precedence over agent-file defaults. A selected Jev profile applies its model and required `thinkingLevel` together; Pi clamps the level to model support. Shadow and fallback preserve both original values. Under `jev`, Jev chooses first and those defaults remain the fallback on uncertainty, missing credentials or errors. Under `shadow`, Jev records a suggestion without changing the model; under `off`, routing guidance and Jev are disabled. An inherited parent model is eligible for Jev. Resuming a child does not classify again in any mode.
+
+Jev classification happens once at child startup through Pi's native API, with a separate concurrency limit of four. Uncertainty, errors or a two-second timeout keep the existing model; stopping the workflow cancels classification without launching another child. Classifier tokens do not affect `budget.spent()` or coding context. Reported classifier cost rolls into child/ancestor cost totals once; classifier usage and the routing decision remain separately available on the agent record. Catalog-zero classifier prices mean unavailable pricing.
+
 `workflowsEnabled` is **on**; leaving it unset means *auto*, which is on unless another extension already offers a `Workflow` or `SubagentWorkflow` tool, in which case this one stands down for the session. Setting it explicitly pins it. See [Persistent settings](../README.md#persistent-settings).
 
 `pi --subagents-workflow-file=<path>` runs a workflow at startup, including headless under `pi -p`. Use the `=` form — the bare `--flag value` spelling swallows the next argument. See [CLI flags](../README.md#cli-flags).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diousk/pi-subagents-fast",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "A pi extension that brings Claude Code-like sub-agents and workflow orchestration to pi — parallel execution, live widget, fleet view, custom agent types, mid-run steering, dynamic workflows, Claude Code compatibility, look and feel.",
   "author": "tintinweb",
   "license": "MIT",
@@ -24,9 +24,9 @@
     "autonomous"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.99.1",
-    "@earendil-works/pi-coding-agent": ">=0.99.1",
-    "@earendil-works/pi-tui": ">=0.99.1"
+    "@earendil-works/pi-ai": ">=1.0.0",
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
@@ -50,9 +50,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-ai": "0.99.1",
-    "@earendil-works/pi-coding-agent": "0.99.1",
-    "@earendil-works/pi-tui": "0.99.1",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "@types/node": "^25.5.0",
     "@vitest/coverage-istanbul": "^4.1.10",
     "typescript": "^6.0.0",

package/src/agent-manager.ts

@@ -19,10 +19,12 @@ import { statSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import { resolveDefaultModel, resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import { getAgentConfig } from "./agent-types.js";
 import { assignHandle, handleBase } from "./mention.js";
 import { describeModel } from "./model-resolver.js";
-import type { AgentInvocation, AgentRecord, AgentTombstone, IsolationMode, MentionResolution, SubagentType, ThinkingLevel } from "./types.js";
+import { loadRoutingPolicy, ModelRouter, type RoutingInput } from "./model-routing.js";
+import type { AgentConfig, AgentInvocation, AgentRecord, AgentTombstone, IsolationMode, MentionResolution, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage, type LifetimeUsage } from "./usage.js";
 import type { CompiledSchema } from "./workflow/json-schema.js";
 import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, } from "./worktree.js";
@@ -167,6 +169,10 @@ interface SpawnArgs {
 }
 
 interface SpawnOptions {
+  /** Internal only; stripped at the programmatic/RPC boundary. */
+  routing?: RoutingInput;
+  /** Branch-local definition selected by a trusted invocation resolver. */
+  agentConfig?: AgentConfig;
   description: string;
   /**
    * Optional memorable name for this instance, becoming a second handle
@@ -361,6 +367,7 @@ async function shutdownChildSession(session: AgentSession | undefined): Promise<
 }
 
 export class AgentManager {
+  private router = new ModelRouter();
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private onComplete?: OnAgentComplete;
@@ -550,7 +557,7 @@ export class AgentManager {
       record.alias = assignHandle(handleBase(options.name), this.takenHandles());
     }
 
-    const args: SpawnArgs = { pi, ctx, type, prompt, options };
+    const args: SpawnArgs = { pi, ctx, type, prompt, options: { ...options, agentConfig: options.agentConfig ?? getAgentConfig(type) } };
 
     const pool = this.poolFor(record);
     if (pool !== undefined && !options.bypassQueue && !this.poolHasRoom(pool)) {
@@ -696,12 +703,67 @@ export class AgentManager {
       if (pool === "background") this.runningBackground--;
       else if (pool === "foreground") this.runningForeground--;
     };
+    const wasQueued = record.startGate !== undefined;
     record.status = "running";
     record.startedAt = Date.now();
     record.startGate = undefined;
     if (pool === "background") this.runningBackground++;
     else if (pool === "foreground") this.runningForeground++;
 
+    const config = options.agentConfig;
+    const provenance = options.routing;
+    const explicit = provenance
+      ? provenance.modelExplicit || provenance.thinkingExplicit
+      : options.model != null || options.thinkingLevel != null;
+    const currentPolicy = wasQueued || !provenance?.policy ? loadRoutingPolicy(options.configCwd ?? ctx.cwd) : undefined;
+    const policy = currentPolicy ?? provenance!.policy!;
+    record.routing = { mode: policy.mode, source: policy.source, fallbackSource: policy.fallbackSource,
+      code: policy.mode === "off" ? "off" : policy.diagnostic ? "guideline_unavailable" : "baseline",
+      reason: policy.mode === "off" ? "Model routing and routing guidance are off" : policy.diagnostic ?? "Using the existing model", guidelinePath: policy.guidelinePath, guidelineHash: policy.guidelineHash };
+    if (policy.diagnostic) console.warn(`[pi-subagents] ${policy.diagnostic}`);
+    const route = policy.mode === "jev" || policy.mode === "shadow" ||
+      (policy.mode === "auto" && !explicit && !config?.model && !config?.thinking && policy.source === "jev");
+    if (!options.resumeSessionFile && provenance?.entrypoint !== "internal" && route) {
+      const stop = () => this.abort(id);
+      options.signal?.addEventListener("abort", stop, { once: true });
+      if (options.signal?.aborted) stop();
+      try {
+        const routed = await this.router.choose(ctx, policy, prompt, options.description ?? type,
+          options.model ?? resolveDefaultModel(ctx.model, ctx.modelRegistry, config?.model),
+          record.abortController!.signal, usage => {
+            record.routingUsage = usage;
+            // Classifier tokens stay separate from coding/context/output budgets.
+            const delta = { input: usage.input, output: usage.output, cacheWrite: usage.cacheWrite, cacheRead: usage.cacheRead, cost: usage.cost.total };
+            this.onUsage?.(record, delta);
+            for (let current: AgentRecord | undefined = record; current; ) {
+              current.lifetimeUsage.cost = (current.lifetimeUsage.cost ?? 0) + usage.cost.total;
+              current = current.parentAgentId ? this.agents.get(current.parentAgentId) : undefined;
+            }
+          });
+        record.routing = { ...routed.decision, guidelinePath: policy.guidelinePath, guidelineHash: policy.guidelineHash };
+        if (routed.model && policy.mode === "shadow") {
+          record.routing = { ...record.routing, code: "shadow", model: undefined, thinkingLevel: undefined, suggestedModel: routed.decision.model,
+            fallbackSource: policy.source, reason: "Jev suggested a model; shadow mode kept the default-priority model" };
+        } else if (routed.model) {
+          options.model = routed.model;
+          options.thinkingLevel = routed.thinkingLevel;
+          record.invocation = { ...record.invocation, thinking: routed.thinkingLevel, requestedThinking: undefined };
+        }
+      } catch {
+        record.routing.code = "classifier_error";
+        record.routing.reason = "Jev could not choose a model; using the existing model";
+      } finally {
+        options.signal?.removeEventListener("abort", stop);
+      }
+      if (record.status !== "running" || record.abortController!.signal.aborted) {
+        this.settleRun(record, true, pool);
+        return;
+      }
+    } else if (policy.mode === "auto" && (explicit || config?.model || config?.thinking)) {
+      record.routing.code = "explicit";
+      record.routing.reason = "Explicit model or thinking; automatic routing skipped";
+    }
+
     // Worktree isolation: try to create a temporary git worktree. Strict —
     // fail loud if not possible (no silent fallback to main tree). Done BEFORE
     // the run is kicked off so a failure doesn't leave a half-running agent.
@@ -761,6 +823,7 @@ export class AgentManager {
     const promise = runAgent(ctx, type, prompt, {
       pi,
       agentId: id,
+      agentConfig: options.agentConfig,
       model: options.model,
       maxTurns: options.maxTurns,
       isolated: options.isolated,
@@ -1556,6 +1619,7 @@ export class AgentManager {
    */
   async dispose(pi?: ExtensionAPI): Promise<void> {
     clearInterval(this.cleanupInterval);
+    this.abortAll();
     // Clear queue — via dequeue, so anyone blocked in spawnAndWait is woken
     // rather than left awaiting a gate nothing will ever resolve.
     this.dequeue(() => true);

package/src/agent-runner.ts

@@ -28,7 +28,7 @@ import { createNestedSubagentTools, getMaxSubagentDepth, type NestedAgentManager
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
 import { createStructuredCapture, createStructuredOutputTool, structuredRetryPrompt } from "./structured-output.js";
-import type { ServiceTier, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentConfig, ServiceTier, SubagentType, ThinkingLevel } from "./types.js";
 import type { LifetimeUsage } from "./usage.js";
 import type { CompiledSchema } from "./workflow/json-schema.js";
 
@@ -436,6 +436,8 @@ export interface ToolActivity {
 }
 
 export interface RunOptions {
+  /** Snapshot of the selected definition for this branch. */
+  agentConfig?: AgentConfig;
   /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
   pi: ExtensionAPI;
   /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
@@ -654,8 +656,8 @@ export async function runAgent(
   prompt: string,
   options: RunOptions,
 ): Promise<RunResult> {
-  const config = getConfig(type);
-  const agentConfig = getAgentConfig(type);
+  const agentConfig = options.agentConfig ?? getAgentConfig(type);
+  const config = agentConfig ?? getConfig(type);
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
@@ -688,7 +690,7 @@ export async function runAgent(
     }
   }
 
-  let toolNames = getToolNamesForType(type);
+  let toolNames = options.agentConfig ? options.agentConfig.builtinToolNames ?? [...BUILTIN_TOOL_NAMES] : getToolNamesForType(type);
 
   // Persistent memory: detect write capability and branch accordingly.
   // Account for disallowedTools — a tool in the base set but on the denylist is not truly available.

package/src/custom-agents.ts

@@ -3,9 +3,10 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { loadRoutingSettings } from "./settings.js";
 import type { AgentConfig, IsolationMode, MemoryScope, ServiceTier, ThinkingLevel } from "./types.js";
 
 /**
@@ -47,9 +48,10 @@ export function loadCustomAgents(cwd: string, strict = false): Map<string, Agent
   const projectDir = join(cwd, ".pi", "agents");
 
   const agents = new Map<string, AgentConfig>();
-  loadFromDir(globalDir, agents, "global", strict);            // lowest priority
-  loadFromDir(workspaceProjectDir, agents, "project", strict); // shared workspace
-  loadFromDir(projectDir, agents, "project", strict);          // highest priority (overwrites)
+  const excluded = loadRoutingSettings(cwd).guidelineFile;
+  loadFromDir(globalDir, agents, "global", strict, excluded);
+  loadFromDir(workspaceProjectDir, agents, "project", strict, excluded);
+  loadFromDir(projectDir, agents, "project", strict, excluded);
 
   warnedLastLoad = warnedThisLoad;
   warnedThisLoad = new Set();
@@ -57,7 +59,7 @@ export function loadCustomAgents(cwd: string, strict = false): Map<string, Agent
 }
 
 /** Load agent configs from a directory into the map. */
-function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "project" | "global", strict: boolean): void {
+function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "project" | "global", strict: boolean, excluded?: string): void {
   if (!existsSync(dir)) return;
 
   let files: string[];
@@ -68,6 +70,7 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
   }
 
   for (const file of files) {
+    if (file.toLowerCase() === "custom-route.md" || resolve(dir, file) === excluded) continue;
     const filenameType = basename(file, ".md");
 
     const path = join(dir, file);

package/src/index.ts

@@ -29,12 +29,13 @@ import { isolationParam, resolveAgentInvocationConfig, resolveJoinMode } from ".
 import { describeMention, handleBase, isReservedHandle, parseMention, resolveHandleToType, stripAgentPrefix } from "./mention.js";
 import { runMentionClone } from "./mention-clone.js";
 import { describeModel, type ModelRegistry, resolveModel } from "./model-resolver.js";
+import { loadRoutingPolicy, routingGuidance } from "./model-routing.js";
 import { checkModelScope, isScopeModelsEnabled, setScopeModelsEnabled } from "./model-scope.js";
 import { getMaxSubagentDepth, setMaxSubagentDepth } from "./nested-tools.js";
 import { createOutputFilePath, ensureOutputFile, getOutputTranscriptDefault, sessionTaskDir, setOutputTranscriptDefault, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
-import { applyAndEmitLoaded, loadSettings, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
+import { applyAndEmitLoaded, loadSettings, projectRoutingSettings, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
 import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
 import { type AgentConfig, type AgentInvocation, type AgentMentionMode, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType, type ViewerMarkdownMode, type WidgetMode } from "./types.js";
 import { createMentionProvider, mentionRoster, type TypeInfo } from "./ui/agent-mention.js";
@@ -57,6 +58,7 @@ import {
   type UICtx,
 } from "./ui/agent-widget.js";
 import { FleetList, type FleetUICtx, type FleetWorkflow } from "./ui/fleet-list.js";
+import { showRoutingMenu } from "./ui/model-routing-menu.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { selectItem } from "./ui/select-item.js";
 import { renderWorkflowCard, renderWorkflowEntryCard } from "./ui/workflow-card.js";
@@ -396,6 +398,7 @@ export default function (pi: ExtensionAPI) {
   const reloadCustomAgents = (strict = false) => {
     const userAgents = loadCustomAgents(process.cwd(), strict);
     registerAgents(userAgents);
+    return userAgents;
   };
 
   // Initial load — the only strict one. A bad edit mid-session must not kill the
@@ -561,6 +564,8 @@ export default function (pi: ExtensionAPI) {
       durationMs,
       tokens,
       usage,
+      routing: record.routing,
+      routingUsage: record.routingUsage,
     };
   }
 
@@ -586,6 +591,7 @@ export default function (pi: ExtensionAPI) {
       id: record.id, type: record.type, description: record.description,
       status: record.status, result: record.result, error: record.error,
       startedAt: record.startedAt, completedAt: record.completedAt,
+      routing: record.routing, routingUsage: record.routingUsage,
     });
 
     // Skip notification if result was already consumed via get_subagent_result
@@ -697,6 +703,8 @@ export default function (pi: ExtensionAPI) {
 
   const spawnTopLevel = (piRef: any, ctxRef: any, type: string, prompt: string, options: any) => {
     const safeOptions = { ...(options ?? {}) };
+    delete safeOptions.routing;
+    delete safeOptions.agentConfig;
     delete safeOptions.parentAgentId;
     // Internal too: a forged value would hide an RPC-spawned agent inside
     // someone else's workflow, and take it out of the concurrency pool with it.
@@ -1364,6 +1372,16 @@ export default function (pi: ExtensionAPI) {
     widget.onTurnStart();
   });
 
+  pi.on("before_agent_start", (event, ctx) => {
+    const guidance = routingGuidance(loadRoutingPolicy(ctx.cwd));
+    const description = agentToolDescription + (guidance ? "\n\n" + guidance : "");
+    if (agentTool.description !== description) {
+      agentTool.description = description;
+      pi.registerTool(agentTool);
+    }
+    if (guidance) return { systemPrompt: event.systemPrompt + "\n\n" + guidance };
+  });
+
   /** Build the full type list text dynamically from available agents only. */
   const buildTypeListText = () => {
     const available = getAvailableTypes();
@@ -1578,10 +1596,11 @@ Terse command-style prompts produce shallow, generic work.
   // Held rather than registered inline: the mention clone reuses this exact
   // definition, so the agent it starts is an ordinary top-level spawn instead
   // of a second implementation that has to be kept in step with this one.
+  const initialRoutingGuidance = routingGuidance(loadRoutingPolicy(process.cwd()));
   const agentTool = defineTool({
     name: SUBAGENT_TOOL_NAMES.AGENT,
     label: "Agent",
-    description: agentToolDescription,
+    description: agentToolDescription + (initialRoutingGuidance ? "\n\n" + initialRoutingGuidance : ""),
     promptSnippet: "Launch autonomous sub-agents for complex multi-step tasks",
     promptGuidelines: [
       "Use Agent with specialized agents when the task matches an agent type's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself.",
@@ -1769,7 +1788,8 @@ Terse command-style prompts produce shallow, generic work.
       widget.setUICtx(ctx.ui as UICtx);
 
       // Reload custom agents so new project/global .md files are picked up without restart
-      reloadCustomAgents();
+      const userAgents = reloadCustomAgents();
+      const routingPolicy = loadRoutingPolicy(ctx.cwd, userAgents);
 
       const rawType = params.subagent_type as SubagentType;
       // Single decision point for dispatch (#183): unknown, disabled and
@@ -1916,6 +1936,10 @@ Terse command-style prompts produce shallow, generic work.
         const { modelName: recModelName, tags } = buildInvocationTags(rec.invocation);
         const recModeLabel = getPromptModeLabel(type);
         const recTags = recModeLabel ? [recModeLabel, ...tags] : tags;
+        if (rec.routing?.source === "jev" && (rec.routingUsage || rec.routing.unpriced !== undefined)) {
+          recTags.push(rec.routing.mode === "shadow" ? "Jev shadow" : "Jev");
+          if (rec.routing.unpriced) recTags.push("Jev price unavailable");
+        }
         return {
           displayName: getDisplayName(type),
           description: rec.description,
@@ -1952,7 +1976,7 @@ Terse command-style prompts produce shallow, generic work.
             subagent_type: requestedType,
             prompt: params.prompt as string,
             model: params.model as string | undefined,
-            thinking: thinking,
+            thinking: params.thinking as typeof thinking,
             max_turns: effectiveMaxTurns,
             isolated: isolated,
             isolation: isolation,
@@ -2057,6 +2081,8 @@ Terse command-style prompts produce shallow, generic work.
           description: params.description,
           name: params.name as string | undefined,
           model,
+          agentConfig: customConfig,
+          routing: { policy: routingPolicy, modelExplicit: !!resolvedConfig.modelInput, thinkingExplicit: thinking !== undefined, entrypoint: "agent" },
           maxTurns: effectiveMaxTurns,
           isolated,
           inheritContext,
@@ -2211,6 +2237,8 @@ Terse command-style prompts produce shallow, generic work.
           description: params.description,
           name: params.name as string | undefined,
           model,
+          agentConfig: customConfig,
+          routing: { policy: routingPolicy, modelExplicit: !!resolvedConfig.modelInput, thinkingExplicit: thinking !== undefined, entrypoint: "agent" },
           maxTurns: effectiveMaxTurns,
           isolated,
           inheritContext,
@@ -2933,6 +2961,7 @@ Terse command-style prompts produce shallow, generic work.
     // Actions
     options.push("Create new agent");
     options.push("Settings");
+    options.push("Model routing");
 
     const noAgentsMsg = allNames.length === 0 && agents.length === 0
       ? "No agents found. Create specialized subagents that can be delegated to.\n\n" +
@@ -2964,6 +2993,14 @@ Terse command-style prompts produce shallow, generic work.
     } else if (choice === "Settings") {
       await showSettings(ctx);
       await showAgentsMenu(ctx);
+    } else if (choice === "Model routing") {
+      const patch = await showRoutingMenu(ctx);
+      if (patch) {
+        const toast = saveAndEmitChanged({ ...snapshotSettings(), ...patch }, "Model routing settings updated", (event, payload) => pi.events.emit(event, payload), ctx.cwd);
+        ctx.ui.notify(toast.message, toast.level);
+        reloadCustomAgents();
+      }
+      await showAgentsMenu(ctx);
     }
   }
 
@@ -3331,6 +3368,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
 
     const { record } = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
       description: `Generate ${name} agent`,
+      routing: { modelExplicit: false, thinkingExplicit: false, entrypoint: "internal" },
       maxTurns: 5,
       // Exempt from maxConcurrentForeground. This runs from a modal wizard, not
       // a tool call: it passes no signal, and Esc in `ctx.ui` never reaches the
@@ -3440,6 +3478,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
    */
   function snapshotSettings() {
     return {
+      ...projectRoutingSettings(process.cwd()),
       maxConcurrent: manager.getMaxConcurrent(),
       // 0 = unlimited, and the default — see SubagentsSettings.
       maxConcurrentForeground: manager.getMaxConcurrentForeground(),