@diousk/pi-subagents-fast 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-10-02
+
+### Changed
+- **BREAKING: Jev model profiles require `thinkingLevel`.** Add `minimal`, `low`, `medium`, `high`, `xhigh` or `max` to every `jev.models` entry. Successful routing applies the model and thinking level together; shadow and fallback preserve the original pair. The routing menu requires a level, and invalid or missing levels disable the Jev block with a diagnostic.
+
+## [0.22.0] - 2026-10-02
+
+> **Breaking: requires Pi 1.0.0 or newer.** Update Pi before using this version.
+
+### Added
+- **Optional Jev routing with four modes.** `routingMode` defaults to `auto`: custom agents, then a Markdown guideline, then Jev. Choose `shadow` to record suggestions without changing models, `jev` for Jev-first selection with default-priority fallback, or `off` to disable routing guidance and classification. Configure the mode, guideline, model descriptions and optional TypeSafe credentials in `subagents.json` or `/agents → Model routing`; usage is recorded separately, including shadow calls. Jev choices honor Pi's model scope and, when enabled, the extension's `scopeModels` policy.
+
+### Changed
+- **Service-tier compatibility is documented for GPT-6.1 Sol and GPT-6 Luna.** Native transport regression tests cover `fast` and `priority` on initial and resumed turns. Pi 1.0.0's Codex cost estimate still understates responses marked `fast`; this release documents that upstream limitation without recalculating costs.
+
 ## [0.21.0] - 2026-09-30
 
 > **Breaking: requires Pi 0.99.1 or newer.** Update Pi before installing this version. Legacy transcript and session API compatibility paths have been removed.

package/README.md

@@ -28,6 +28,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Graceful turn limits** — agents get a "wrap up" warning before hard abort, producing clean partial results instead of cut-off output
 - **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work. A type that doesn't resolve to exactly one *enabled* agent — unknown, disabled, or ambiguous between two agents differing only by case — falls back to general-purpose with a note, or is refused outright under [`fallbackSubagent: none`](#persistent-settings)
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
+- **Model routing** — custom agents first, then a user-supplied Markdown guideline, then optional Jev model selection. Configure it through `/agents → Model routing` or two ordinary JSON fields; see [Model routing](#model-routing)
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
 - **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
 - **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
@@ -76,9 +77,9 @@ npm pack --dry-run
 
 The `prepublishOnly` script runs lint, typecheck, tests, and the build before npm uploads the package. After publishing, install it with `pi install npm:@diousk/pi-subagents-fast`.
 
-Requires **Pi 0.99.1 or newer** and **Node.js 22.19.0 or newer**. Update Pi before installing this extension. The `peerDependencies` range declares the minimum, so npm flags an older Pi at install time.
+Requires **Pi 1.0.0 or newer** and **Node.js 22.19.0 or newer**. Update Pi before installing this extension. The `peerDependencies` range declares the minimum, so npm flags an older Pi at install time.
 
-The development and CI baseline is **Pi 0.99.1**. Use that version or newer for `openai/gpt-6.1-sol` (API key) or `openai-codex/gpt-6.1-sol` (your Pi Codex login). Child sessions reuse the parent's configured providers and authentication; model limits and pricing come from Pi's provider catalog. See the [Pi 0.99.1 release](https://pi.dev/changelog/releases/0.99.1).
+Development and CI use **Pi 1.0.0**. Jev uses Pi's native classifier API. Child sessions reuse the parent's configured providers and authentication; model availability, limits and pricing come from Pi's catalog.
 
 ### Other hosts
 
@@ -354,7 +355,9 @@ All fields are optional — sensible defaults for everything.
 
 For an OpenAI Responses or Codex agent, set `service_tier: fast` to request fast processing; `priority` remains a supported alias. Availability depends on the provider and account. The UI shows the requested tier only when the effective model uses one of those APIs. See [OpenAI fast mode](https://developers.openai.com/api/docs/guides/fast-mode).
 
-GPT-6.1 Sol supports `low`, `medium`, `high`, `xhigh`, and `max` reasoning. In Pi 0.99.1, `minimal` maps to provider effort `low`; `off` is clamped to that same alias because Sol cannot disable reasoning. The UI reports Pi's logical thinking level. Prefer explicit supported levels in agent files:
+The extension forwards both tiers for `gpt-6.1-sol` and `gpt-6-luna` through Pi's OpenAI Responses and Codex transports. Pi 1.0.0's Codex adapter currently estimates a response marked `fast` at the standard rate; forwarding the tier works, but its displayed cost can be understated. This extension reports Pi's cost estimate without recalculating it. OpenAI documents Fast mode as unavailable for these models with EU data residency.
+
+GPT-6.1 Sol supports `low`, `medium`, `high`, `xhigh`, and `max` reasoning. In Pi 1.0.0, `minimal` maps to provider effort `low`; `off` is clamped to that same alias because Sol cannot disable reasoning. The UI reports Pi's logical thinking level. Prefer explicit supported levels in agent files:
 
 ```yaml
 model: openai-codex/gpt-6.1-sol
@@ -629,6 +632,72 @@ When background agents complete, they notify the main agent. The **join mode** c
 **Configuration:**
 - Configure join mode in `/agents` → Settings → Join mode
 
+## Model routing
+
+Open `/agents → Model routing` to choose a mode and configure a guideline path, models with descriptions and required thinking levels, or a masked TypeSafe API key. The menu shows the active mode and source and saves project settings. For machine-wide defaults, edit `~/.pi/agent/subagents.json`; project overrides go in `.pi/subagents.json`. `PI_CODING_AGENT_DIR` changes the global directory along with Pi's other configuration.
+
+Set one top-level field to control routing; omitting it means `auto`:
+
+```json
+{ "routingMode": "auto" }
+```
+
+| `routingMode` | Behavior |
+|---|---|
+| `auto` (default) | Use the priority table below |
+| `shadow` | Ask Jev and record its suggestion, but keep the model chosen from agent definitions, the guideline or the existing model. Jev requests can incur charges |
+| `jev` | Jev chooses first for every fresh task, even with custom agents, a guideline, explicit model parameters or agent-file model pins. Invalid configuration, unavailable credentials, low confidence or errors keep the default-priority choice |
+| `off` | No custom-agent routing selection guidance, guideline injection or Jev requests. Agents remain callable and existing model/thinking settings still apply |
+
+Mode changes apply to subsequent fresh launches. The main agent's routing guidance and tool description refresh before its next turn, so switching to `off` removes previously injected routing instructions.
+
+The default priority is:
+
+| Priority | Configuration | Who chooses |
+|---|---|---|
+| 1 | At least one enabled custom agent | The main agent chooses an agent from its description. Guideline and Jev are inactive, even if it chooses a built-in agent |
+| 2 | `customGuideline` points to a Markdown file | The main agent reads the guideline and passes its model/thinking choice explicitly |
+| 3 | `jev` is configured | Jev chooses a model from your descriptions for a fresh delegated task |
+| 4 | None of the above | The existing model is used |
+
+**Custom agents:** keep using `~/.pi/agent/agents/<name>.md`, `.pi/agents/<name>.md` or `.agents/agents/<name>.md`. No routing setting is needed. Built-in and disabled agents do not activate priority 1. Agent-file model/thinking pins supply the default choice over `Agent` parameters; a confident Jev choice in `jev` mode can replace both model and thinking level.
+
+**Custom guideline:** write your routing rules in `~/.pi/agent/agents/custom-route.md`, then configure:
+
+```json
+{
+  "customGuideline": "~/.pi/agent/agents/custom-route.md"
+}
+```
+
+For example, the Markdown can say “Use anthropic/claude-haiku-4-5 for simple edits; use openai-codex/gpt-6.1-sol for debugging concurrency.” The guideline reaches the main agent in full, compact and custom description modes, and is refreshed before each turn, except in `off` mode. Relative paths are resolved from the settings file's directory: `agents/custom-route.md` in `.pi/subagents.json` means `.pi/agents/custom-route.md`. `custom-route.md` and the configured guideline file are excluded from agent discovery. Merely placing a guideline file in the directory does not enable it. A configured missing, empty or oversized guideline produces a diagnostic and keeps the existing model under `auto`; it does not prevent Jev requests under `jev` or `shadow`.
+
+**Jev:** provide descriptions and exact model IDs available through your Pi login:
+
+```json
+{
+  "jev": {
+    "TYPESAFE_API_KEY": "your-typesafe-key",
+    "models": [
+      { "model": "anthropic/claude-haiku-4-5", "description": "Simple edits, lookup and concise summaries", "thinkingLevel": "low" },
+      { "model": "openai-codex/gpt-6.1-sol", "description": "Complex debugging, architecture and concurrency", "thinkingLevel": "high" }
+    ]
+  }
+}
+```
+
+`TYPESAFE_API_KEY` is optional when Pi already has TypeSafe credentials or the environment variable is set. A literal key must be a nonempty token without whitespace or control characters and applies only to that classifier request; it is saved in the settings file, masked in the menu and omitted from settings events, prompts and routing records. Without a literal key, Pi's native credential availability check runs before classification. Rejected credentials fall back without retrying. The extension does not change environment variables or register a routing provider. `models` accepts 1–254 unique entries with descriptions of 1–4000 characters. Every entry requires `thinkingLevel`: `minimal`, `low`, `medium`, `high`, `xhigh` or `max`. Existing profiles must add this field; a missing or invalid value disables the whole Jev block and uses the default-priority fallback. Jev entries use exact `provider/model-id` spelling; fuzzy names remain available for explicit `Agent` parameters.
+
+Under `auto`, supplying **either** `model` or `thinking` explicitly skips Jev. An agent-file pin also skips it. In workflows, either `model` or `effort` skips it, and workflow options retain their precedence over agent-file defaults. Inherited models remain eligible for Jev. Under `jev`, these choices supply the fallback model, but do not skip classification. Under `shadow`, they remain the actual choice while Jev records a comparison. A selected Jev profile applies both its model and `thinkingLevel`. Pi clamps the requested thinking level to what that model supports. Shadow and fallback preserve the original model and thinking level.
+
+Automatic choices are limited to authenticated models and the current nonempty Pi model scope, regardless of the `scopeModels` setting. When `scopeModels` is enabled, Jev candidates also respect `enabledModels`. Unavailable candidates are excluded and the selected model is checked again after classification, including any changed scope. Jev failure, confidence below 0.6 or a two-second timeout keeps the default-priority model already selected by the main agent, explicit caller or agent definition, otherwise the existing model. This fallback does not make a second Jev request. Cancellation stops startup without launching a fallback. Queued agents read the current mode and classify after dequeue; nested calls share a separate classifier concurrency limit of four and do not take another agent slot.
+
+Jev applies to fresh tool, nested, workflow, scheduled, RPC and direct-mention spawns. Schedules read current configuration when they fire. Direct calls, schedules and RPC do not create an extra main-agent turn to interpret a custom guideline: with priorities 1 or 2 under `auto`, or when Jev falls back under `jev`, they use an explicit choice, agent definition or the existing model. Resumes and internal agent-file generation do not call Jev in any mode.
+
+Project `routingMode` and `customGuideline` replace the global values; omission inherits them, and `customGuideline: false` disables the guideline. A project `jev` block replaces the **whole** global block, including credentials; omitted fields inside that block do not inherit. `"jev": false` disables global Jev. An invalid mode or malformed settings file disables routing. An invalid explicit Jev block disables that block instead of restoring global paid routing. Other settings changes preserve these inheritance rules.
+
+Classifier usage is recorded separately as `routingUsage`, including in `shadow`; it does not consume coding context or workflow output budgets. Its reported cost is added once to the agent and ancestor cost totals, and `reportUsage` can return its token usage to the parent. `routing` records the mode, source, reason, applied `model`, requested `thinkingLevel` and confidence; shadow records `suggestedModel` and `suggestedThinkingLevel` and leaves both applied fields unset. `fallbackSource` identifies the default source when a suggestion is observed or Jev falls back. Shadow results show “Jev shadow”. Zero catalog prices are marked `unpriced`; the Agent result shows “Jev price unavailable” instead of treating that as proof the classifier is free.
+
 ## Model Scope
 
 **Opt-in:** off by default. Enable via `/agents → Settings → Scope models`.
@@ -641,6 +710,7 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 |---|---|
 | Caller-supplied via `Agent({ model: "..." })` | Hard error returned to the orchestrator, listing allowed models |
 | Caller-supplied via cross-extension RPC (`subagents:rpc:spawn`, e.g. pi-tasks `TaskExecute`) | Hard error returned to the calling extension, listing allowed models |
+| Jev-selected | Excluded from candidates; a scope change during classification keeps the default-priority model |
 | Pinned in agent frontmatter | Warning toast + the pinned model runs (frontmatter is authoritative) |
 | Parent-inherited (neither set) | Warning toast + parent's model runs |
 
@@ -661,6 +731,8 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, max foreg
 
 **Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `10`, max foreground concurrency `0` = unlimited, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, defaults enabled).
 
+Routing settings: `routingMode` (`auto | shadow | jev | off`, default `auto`), `customGuideline` (`string | false`, default unset) and `jev` (`{ TYPESAFE_API_KEY?: string, models: { model, description, thinkingLevel }[] } | false`, default unset). See [Model routing](#model-routing) for examples and the whole-block override rule.
+
 **Nested depth** (`maxSubagentDepth`, default `2`): the hard ceiling on [nested delegation](#nested-subagents), counted from the main session (main = 0, its subagents = 1). `0` or `1` disables nesting project-wide regardless of any agent's `allowed_subagents`. Read when a subagent session is built, so a change applies to agents started after it.
 
 **Fallback agent** (`fallbackSubagent`, default `general-purpose`): the agent used when a caller-supplied `subagent_type` doesn't resolve to exactly one enabled agent — unknown, disabled, or ambiguous because two agents differ only by case. Name any enabled agent to route those calls there instead, or set `none` for **strict**, fail-closed dispatch: the call is refused with an error listing the available types, and nothing spawns. Strict mode matters most for background and scheduled calls, which would otherwise start executing a substituted agent before the caller learns anything. Also settable from `/agents → Settings → Fallback agent`. The boolean `false` is accepted as a spelling of `none`, because it would otherwise be dropped as the wrong type and silently leave the permissive default in place. Every other value is read as an agent name, so a mistaken `off` fails loudly at dispatch rather than meaning one thing in the settings file and another in the resolver. A fallback agent that is itself unknown or disabled is a misconfiguration and is reported rather than quietly replaced. Note the default is unchanged and stays permissive by design: with `disableDefaultAgents` and no `general-purpose` of your own, an unresolvable type still resolves to a built-in config carrying *all* tools — set `none` (or name one of your own agents) to close that.
@@ -763,7 +835,7 @@ EOF
 
 Every project now starts with concurrency 16 and grace 10, without ever touching the menu. Individual projects can still override via `/agents` → Settings.
 
-**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/agents` toast to a warning with `(session only; failed to persist)`.
+**Failure behavior:** missing file is silent; malformed JSON logs a warning without its contents and suppresses inherited routing; invalid/out-of-range ordinary fields are dropped per-field, while invalid explicit routing fields disable that route. Write failures downgrade the `/agents` toast to a warning with `(session only; failed to persist)`.
 
 ## Events
 
@@ -789,6 +861,8 @@ The four agent-lifecycle events — `subagents:started`, `:completed`, `:failed`
 
 `usage` answers the other question — what was billed — and so does include `cacheRead`, because the prefix really is re-read and re-charged on every call. It is a pi `Usage`, the same shape pi puts on `ToolResultEvent` and `AssistantMessage`, so `usage.cost.total` is where a listener already expects the money and anything pi adds to `Usage` arrives without a change here. Neither field derives from the other; `tokens` is a view model, `usage` is the data.
 
+Completed/failed payloads and persisted `subagents:record` entries also carry `routing` (`source`, `code`, `reason`, optional `model`, `thinkingLevel`, `suggestedModel`, `suggestedThinkingLevel`, supplied `description`, `confidence`, `unpriced`, `guidelinePath`, `guidelineHash`) and optional `routingUsage` (classifier-only Pi `Usage`). The guideline hash is SHA-256 of the original file contents. Coding `tokens` excludes classifier tokens; total cost includes the reported classifier cost once. Settings events omit `jev.TYPESAFE_API_KEY`.
+
 ## Cross-Extension RPC
 
 Other pi extensions can spawn and stop subagents programmatically via the `pi.events` event bus, without importing this package directly.
@@ -1005,6 +1079,8 @@ src/
   # Invocation surface
   invocation-config.ts # Shared tool-parameter schemas (isolation, join, thinking, ...)
   model-resolver.ts   # Model resolution: exact provider/modelId with fuzzy fallback
+  model-routing.ts    # Source priority and bounded native Jev classification before startup
+  routing-config.ts   # Jev model/description/thinking-level and credential config validation
   enabled-models.ts   # Read pi's enabledModels settings (project over global)
   model-scope.ts      # scopeModels allowlist policy, shared by top-level and nested tools
   mention.ts          # `@handle message` grammar: suggestion triggers and send parsing
@@ -1040,6 +1116,7 @@ src/
     viewer-keys.ts        # Viewer scroll keys resolved through user keybindings
     agent-mention.ts      # `@` roster (running, resumable, and startable agents) + popup rows
     schedule-menu.ts      # /agents → Scheduled jobs submenu
+    model-routing-menu.ts # Guideline/model descriptions and masked API-key editor
     select-item.ts        # Collision-safe ctx.ui.select wrapper (numbered rows)
     workflow-card.ts      # Inline workflow card (tool result and session entry)
     workflow-dialog.ts    # /agents → Workflows two-pane inspector

package/dist/agent-manager.d.ts

@@ -16,7 +16,8 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type ToolActivity } from "./agent-runner.js";
-import type { AgentInvocation, AgentRecord, AgentTombstone, IsolationMode, MentionResolution, SubagentType, ThinkingLevel } from "./types.js";
+import { type RoutingInput } from "./model-routing.js";
+import type { AgentConfig, AgentInvocation, AgentRecord, AgentTombstone, IsolationMode, MentionResolution, SubagentType, ThinkingLevel } from "./types.js";
 import { type LifetimeUsage } from "./usage.js";
 import type { CompiledSchema } from "./workflow/json-schema.js";
 export type OnAgentComplete = (record: AgentRecord) => void;
@@ -47,6 +48,10 @@ export type CompactionInfo = {
  */
 export declare function isTopLevelAgent(record: Pick<AgentRecord, "parentAgentId" | "workflowId">): boolean;
 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
@@ -219,6 +224,7 @@ interface ResumeOptions {
     onStarted?: () => void;
 }
 export declare class AgentManager {
+    private router;
     private agents;
     private cleanupInterval;
     private onComplete?;

package/dist/agent-manager.js

@@ -16,9 +16,11 @@
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { isAbsolute } from "node:path";
-import { resumeAgent, runAgent } from "./agent-runner.js";
+import { resolveDefaultModel, resumeAgent, runAgent } from "./agent-runner.js";
+import { getAgentConfig } from "./agent-types.js";
 import { assignHandle, handleBase } from "./mention.js";
 import { describeModel } from "./model-resolver.js";
+import { loadRoutingPolicy, ModelRouter } from "./model-routing.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, } from "./worktree.js";
 /**
@@ -157,6 +159,7 @@ async function shutdownChildSession(session) {
     catch { /* ignore */ }
 }
 export class AgentManager {
+    router = new ModelRouter();
     agents = new Map();
     cleanupInterval;
     onComplete;
@@ -323,7 +326,7 @@ export class AgentManager {
         if (record.handle !== undefined && record.alias === undefined && options.name !== undefined) {
             record.alias = assignHandle(handleBase(options.name), this.takenHandles());
         }
-        const args = { pi, ctx, type, prompt, options };
+        const args = { pi, ctx, type, prompt, options: { ...options, agentConfig: options.agentConfig ?? getAgentConfig(type) } };
         const pool = this.poolFor(record);
         if (pool !== undefined && !options.bypassQueue && !this.poolHasRoom(pool)) {
             // Queue it — started when a running agent in the same pool completes.
@@ -461,6 +464,7 @@ export class AgentManager {
             else if (pool === "foreground")
                 this.runningForeground--;
         };
+        const wasQueued = record.startGate !== undefined;
         record.status = "running";
         record.startedAt = Date.now();
         record.startGate = undefined;
@@ -468,6 +472,63 @@ export class AgentManager {
             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 = 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.
@@ -522,6 +583,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,
@@ -1312,6 +1374,7 @@ export class AgentManager {
      */
     async dispose(pi) {
         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/dist/agent-runner.d.ts

@@ -5,7 +5,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type AgentSession, DefaultResourceLoader, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type NestedAgentManager } from "./nested-tools.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";
 /**
@@ -157,6 +157,8 @@ export interface ToolActivity {
     toolName: string;
 }
 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`). */

package/dist/agent-runner.js

@@ -450,8 +450,8 @@ function resolveConfiguredSessionDir(sessionDir, cwd) {
     return resolve(cwd, sessionDir);
 }
 export async function runAgent(ctx, type, prompt, options) {
-    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;
     // Filesystem work happens in effectiveCwd; config discovery in configCwd.
@@ -479,7 +479,7 @@ export async function runAgent(ctx, type, prompt, options) {
             extras.skillBlocks = loaded;
         }
     }
-    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.
     if (agentConfig?.memory) {

package/dist/custom-agents.js

@@ -2,9 +2,10 @@
  * custom-agents.ts — Load user-defined agents from project (.pi/agents/, plus the shared .agents/agents/ workspace) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
  */
 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";
 /**
  * The one thing a declared `name:` may not contain, matching Claude Code
  * exactly: it reserves `:` for plugin-scoped identifiers (`my-plugin:reviewer`)
@@ -42,15 +43,16 @@ export function loadCustomAgents(cwd, strict = false) {
     const workspaceProjectDir = join(cwd, ".agents", "agents");
     const projectDir = join(cwd, ".pi", "agents");
     const agents = new Map();
-    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();
     return agents;
 }
 /** Load agent configs from a directory into the map. */
-function loadFromDir(dir, agents, source, strict) {
+function loadFromDir(dir, agents, source, strict, excluded) {
     if (!existsSync(dir))
         return;
     let files;
@@ -61,6 +63,8 @@ function loadFromDir(dir, agents, source, strict) {
         return;
     }
     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);
         const parsed = readAgentFile(path, strict);

package/dist/index.js

@@ -28,16 +28,18 @@ import { isolationParam, resolveAgentInvocationConfig, resolveJoinMode } from ".
 import { describeMention, handleBase, isReservedHandle, parseMention, resolveHandleToType, stripAgentPrefix } from "./mention.js";
 import { runMentionClone } from "./mention-clone.js";
 import { describeModel, 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, saveAndEmitChanged } from "./settings.js";
+import { applyAndEmitLoaded, loadSettings, projectRoutingSettings, saveAndEmitChanged } from "./settings.js";
 import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
 import { createMentionProvider, mentionRoster } from "./ui/agent-mention.js";
 import { AgentWidget, buildInvocationTags, describeActivity, fgPreservingNestedStyles, formatCost, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
 import { FleetList } 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";
@@ -344,6 +346,7 @@ export default function (pi) {
     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
     // session on the next unrelated spawn, so every later reload keeps warning.
@@ -502,6 +505,8 @@ export default function (pi) {
             durationMs,
             tokens,
             usage,
+            routing: record.routing,
+            routingUsage: record.routingUsage,
         };
     }
     // Background completion: route through group join or send individual nudge
@@ -526,6 +531,7 @@ export default function (pi) {
             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
         if (record.resultConsumed) {
@@ -636,6 +642,8 @@ export default function (pi) {
     };
     const spawnTopLevel = (piRef, ctxRef, type, prompt, options) => {
         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.
@@ -1258,6 +1266,16 @@ export default function (pi) {
         fleet.setUICtx(ctx.ui);
         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();
@@ -1454,10 +1472,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.",
@@ -1618,7 +1637,8 @@ Terse command-style prompts produce shallow, generic work.
             // Ensure we have UI context for widget rendering
             widget.setUICtx(ctx.ui);
             // 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;
             // Single decision point for dispatch (#183): unknown, disabled and
             // case-ambiguous types are refused here, BEFORE anything spawns, so a
@@ -1765,6 +1785,11 @@ 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,
@@ -1800,7 +1825,7 @@ Terse command-style prompts produce shallow, generic work.
                         subagent_type: requestedType,
                         prompt: params.prompt,
                         model: params.model,
-                        thinking: thinking,
+                        thinking: params.thinking,
                         max_turns: effectiveMaxTurns,
                         isolated: isolated,
                         isolation: isolation,
@@ -1888,6 +1913,8 @@ Terse command-style prompts produce shallow, generic work.
                     description: params.description,
                     name: params.name,
                     model,
+                    agentConfig: customConfig,
+                    routing: { policy: routingPolicy, modelExplicit: !!resolvedConfig.modelInput, thinkingExplicit: thinking !== undefined, entrypoint: "agent" },
                     maxTurns: effectiveMaxTurns,
                     isolated,
                     inheritContext,
@@ -2028,6 +2055,8 @@ Terse command-style prompts produce shallow, generic work.
                     description: params.description,
                     name: params.name,
                     model,
+                    agentConfig: customConfig,
+                    routing: { policy: routingPolicy, modelExplicit: !!resolvedConfig.modelInput, thinkingExplicit: thinking !== undefined, entrypoint: "agent" },
                     maxTurns: effectiveMaxTurns,
                     isolated,
                     inheritContext,
@@ -2687,6 +2716,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" +
                 "Each subagent has its own context window, custom system prompt, and specific tools.\n\n" +
@@ -2721,6 +2751,15 @@ Terse command-style prompts produce shallow, generic work.
             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);
+        }
     }
     async function showAllAgentsList(ctx) {
         const allNames = getAllTypes();
@@ -3065,6 +3104,7 @@ Guidelines for choosing settings:
 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
@@ -3173,6 +3213,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(),