@diousk/pi-subagents-fast 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Added
+- **Custom agents accept `service_tier: fast`.** OpenAI Responses and Codex requests forward the configured tier, and `priority` remains accepted.
+
+### Changed
+- **The minimum supported Pi version is 0.99.1.** Development dependencies and blocking CI target that minimum. Scripted model fixtures use transcript replay and physical model lookup.
+
+### Fixed
+- **Mention clones preserve conversation history on Pi 0.99.1.** History is seeded through the session manager, and the live prompt is supplied through the resource loader. Historical system messages do not grant the clone the parent's tools.
+- **Subagent tool scope covers nested execution.** A bound `tool_call` guard blocks out-of-scope deferred/codemode calls, while tool narrowing preserves exposure. Synthetic extension paths match their logical names.
+- **Output transcripts preserve system messages.** System/tool-state changes receive a `system` entry type, and a leading system message no longer causes the initial user prompt to be duplicated.
+
 ## [0.20.0] - 2026-09-09
 
 > **Breaking — the npm package is now `@diousk/pi-subagents-fast`.** Existing installs of `@tintinweb/pi-subagents` are not automatically migrated; install this fork with `pi install npm:@diousk/pi-subagents-fast`.

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,7 +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.84.0 or newer**: the [`SubagentWorkflow`](#subagentworkflow) tool builds on `constrainedSampling` (pi 0.82.0) and pi-tui's `stripTerminalSequences` (0.84.0). The `peerDependencies` range declares it, 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.
+
+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
 
@@ -337,8 +340,8 @@ All fields are optional — sensible defaults for everything.
 | `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
 | `isolation` | — | Set to `worktree` to run in an isolated git worktree, or `off` to refuse one even when the caller passes `isolation: "worktree"` (frontmatter is authoritative). `none`, `no`, and `false` are accepted spellings of `off` |
 | `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp are interchangeable) and falls back to the same model under another provider if the named one doesn't have it |
-| `service_tier` | — | OpenAI Responses/Codex processing tier: `auto`, `default`, `flex`, `priority`, or `scale`. Applied only to `openai-responses` and `openai-codex-responses`; omitted preserves the provider default, and other APIs ignore it without displaying it as active |
-| `thinking` | inherit | off, minimal, low, medium, high, xhigh, max — actual availability depends on your pi version and model; pi clamps unsupported levels down |
+| `service_tier` | — | OpenAI Responses/Codex processing tier: `auto`, `default`, `flex`, `fast`, `priority`, or `scale`. Applied only to `openai-responses` and `openai-codex-responses`; omitted preserves the provider default, and other APIs ignore it without displaying it as active |
+| `thinking` | inherit | off, minimal, low, medium, high, xhigh, max — actual availability depends on your pi version and model; pi maps or clamps unsupported levels |
 | `max_turns` | unlimited | Max agentic turns before graceful shutdown. `0` or omit for unlimited |
 | `persist_session` | `subagents.json` `rememberAgents` (default `true`) | Persist this subagent as a normal pi session instead of keeping the session in memory only; overrides the `rememberAgents` project default in both directions. It records its spawning session as parent, so it nests under it in `/resume`. The subagent's `.output` transcript is still written either way unless `output_transcript: false` |
 | `output_transcript` | `true` (or `subagents.json` `outputTranscript`) | Write this subagent's `.output` transcript; when set, overrides the `subagents.json` `outputTranscript` default. Set `false` to write no transcript file or path. Governs only the transcript — independent of `persist_session`, `isolation: worktree`, and `memory:` |
@@ -350,7 +353,19 @@ All fields are optional — sensible defaults for everything.
 | `isolated` | `false` | Hermetic specialist mode: forces `extensions: false` + `skills: false` + drops `ext:` selectors. Only built-in tools. Distinct from `isolation: worktree` (filesystem) |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
-For an OpenAI Responses or Codex agent, set `service_tier: priority` to request priority processing. The UI shows the requested tier only when the effective model uses one of those APIs; other providers keep their normal request behavior and do not display a tier as active.
+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).
+
+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
+thinking: medium
+service_tier: fast
+```
+
+Sol requires the Responses API for tool use. Selecting its Pi catalog entry chooses the corresponding Responses transport; no custom provider override is needed. See the [Sol model reference](https://developers.openai.com/api/docs/models/gpt-6.1-sol).
 
 Frontmatter is authoritative. If an agent file sets `model`, `thinking`, `service_tier`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent. For fields exposed by the `Agent` tool, its parameters only fill values the agent config leaves unspecified; `service_tier` is frontmatter-only.
 
@@ -408,6 +423,8 @@ A few rules the examples don't make obvious:
 - `extensions:` is the sole loading authority. `ext:foo` in `tools:` narrows what surfaces; it can't load `foo` on its own. Mismatches fire `extension-error:…` warnings.
 - Any `ext:` entry flips extension tools to an explicit allowlist — unnamed extensions still load (handlers fire) but expose no tools. So `tools: "*, ext:mcp/search"` exposes only `search` from `mcp`, nothing from any other extension.
 - Extension names match case-insensitively (`[Mcp]` = `[mcp]`); tool names in `ext:foo/bar` stay case-sensitive.
+- Synthetic extension identities match their logical names: `builtin:mcp` as `mcp`, `builtin:codemode` as `codemode`, and `<inline:foo>` as `foo`. This matches loaded extensions; it does not load Pi CLI built-in factories into SDK child sessions.
+- Scope checks also apply to nested `ctx.executeTool()` calls, including deferred and codemode tools. Deferred tools keep their exposure and are not automatically promoted into model declarations; extension-activated tools remain active only within the agent's scope.
 - Extensions that register tools **lazily** work too. MCP-backed extensions typically can't enumerate their tools until their servers connect, so they register from `session_start` or `before_agent_start` rather than at load. Subagent scoping is re-derived as tools appear, so these surface normally — including under `ext:` selectors, which keep narrowing correctly no matter when a tool shows up.
 - Extensions bound into a subagent see **both ends** of that session's lifecycle: `session_start` when the agent starts, `session_shutdown` (reason `quit`) when its session is disposed — on quit, and when its record is evicted ~10 minutes after it finishes. Release per-session resources there; anything left armed outlives the session it belongs to. Handlers are given three seconds on quit, after which teardown proceeds regardless.
 - An installed **package** extension matches by its package short name (`@scope/pi-subagents` → `[pi-subagents]`), in addition to its path-derived name (a package whose entry is `src/index.ts` also answers to `[src]`). Prefer the package name — the path-derived one is incidental.
@@ -615,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, 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 the model.
+
+**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" },
+      { "model": "openai-codex/gpt-6.1-sol", "description": "Complex debugging, architecture and concurrency" }
+    ]
+  }
+}
+```
+
+`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. 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. Jev changes only the model; Pi still determines the effective 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` and confidence; shadow records `suggestedModel` and leaves `model` 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`.
@@ -627,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 |
 
@@ -647,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 }[] } | 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.
@@ -667,7 +753,7 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, max foreg
 
 **Report usage to session** (`reportUsage`, default `false`): whether subagent spend is added to *this* session's own totals. Subagents run in their own pi sessions, so by default pi's footer, statusline and `/cost` count only what the main model spent — a session that delegated most of its work reads as nearly free. Turn it on and each `Agent` / `get_subagent_result` / `steer_subagent` result carries the spend accumulated since the last one, which pi folds into `getSessionStats()`; `/cost` attributes it to the **Tools/summaries** bucket. Toggle via `/agents → Settings → Report usage to session`; applied live.
 
-Three things worth knowing about the numbers. Every token component is reported, `cacheRead` included — the cached prefix genuinely is re-read and re-billed on every call, and pi counts it the same way for the session's own messages, so withholding it would make a subagent's rows count differently from every other row in one total. (The extension's *own* token displays still leave it out, which is a different question: there it inflates a reading of how much work was done.) Cost is pi's own per-message figure, priced from the model's listed rates; a model pi has no rates for contributes zero rather than an estimate. And the context-window percentage is untouched: pi derives it from assistant messages alone, so a delegating session's context doesn't appear to fill up faster. Agents that finish in the background have no tool result of their own to ride on, so their spend is carried by the next one you make — the footer catches up on the following call, not the moment they finish.
+Three things worth knowing about the numbers. Every token component is reported, `cacheRead` included — the cached prefix genuinely is re-read and re-billed on every call, and pi counts it the same way for the session's own messages, so withholding it would make a subagent's rows count differently from every other row in one total. (The extension's *own* token displays still leave it out, which is a different question: there it inflates a reading of how much work was done.) Cost is pi's own per-message figure, priced from the model's listed rates; a model pi has no rates for contributes zero rather than an estimate. Reported subagent token counts do not inflate the parent's context-window percentage. On Pi 0.99.1 the tool-result text itself occupies context and is included in Pi's projection estimate. Agents that finish in the background have no tool result of their own to ride on, so their spend is carried by the next one you make — the footer catches up on the following call, not the moment they finish.
 
 **Show cost** (`showCost`, default `false`): whether the subagent surfaces print an estimated cost beside their token counts — the widget (running *and* finished lines), [FleetView](#fleetview), the conversation viewer, foreground results, `get_subagent_result`, and completion notifications:
 
@@ -696,6 +782,8 @@ Both places report what the run *actually* used, read back from the child sessio
   ↳ anthropic/claude-haiku-4-5 · thinking: low (asked max) · background
 ```
 
+For a virtual model, the displayed identity is the session's selected virtual model, rather than the physical model chosen for each response.
+
 Toggle via `/agents → Settings → Show model`; applied live.
 
 **Viewer markdown** (`viewerMarkdown`, default `"assistant"`): how much of the [conversation viewer](#ui)'s transcript is rendered as Markdown rather than shown verbatim.
@@ -747,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
 
@@ -773,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`, 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.
@@ -989,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   # Minimal Jev model/description 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
@@ -1024,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,61 @@ 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, 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;
+                }
+            }
+            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 +581,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 +1372,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";
 /**
@@ -85,12 +85,13 @@ export declare function parseExtSelectors(entries: string[]): {
  * snapshotted. `registerTool` writes into the very `extension.tools` maps this reads,
  * so `inScope()` sees late arrivals on the next call.
  *
- * Two enforcement points, because neither covers the whole picture:
+ * The active set and call-time checks cover different parts of scope:
  *
  *   - `turn_end` re-narrows the ACTIVE set. pi emits `turn_end` immediately before
  *     `prepareNextTurn` re-snapshots `agent.state.tools`, and session listeners run
  *     synchronously, so the narrow lands in time for turns 2..N.
- *   - `beforeToolCall` blocks out-of-scope calls. Turn 1 cannot be narrowed at all:
+ *   - The loader's bound `tool_call` handler blocks direct and nested calls.
+ *     Turn 1 cannot be narrowed at all:
  *     `before_agent_start` fires INSIDE `prompt()` and may widen the tool set, but
  *     `createContextSnapshot()` freezes that turn's tools immediately after — there
  *     is no hook in between. A call-time check is the only correct guard there.
@@ -117,7 +118,7 @@ export declare function installExtensionToolScope(session: AgentSession, ctx: {
      * seeded from `toolNames`.
      */
     readmitToolNames: Set<string>;
-}): void;
+}): (toolName: string) => boolean;
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 export declare function normalizeMaxTurns(n: number | undefined): number | undefined;
 /** Get the default max turns value. undefined = unlimited. */
@@ -156,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

@@ -68,6 +68,10 @@ export function installServiceTierPayload(session, serviceTier) {
  * single-file extensions to the basename minus `.ts`/`.js`.
  */
 export function extensionCanonicalName(extPath) {
+    if (extPath.startsWith("builtin:"))
+        return extPath.slice("builtin:".length).toLowerCase();
+    if (extPath.startsWith("<inline:") && extPath.endsWith(">"))
+        return extPath.slice(8, -1).toLowerCase();
     const base = basename(extPath);
     const name = base === "index.ts" || base === "index.js"
         ? basename(dirname(extPath))
@@ -132,6 +136,8 @@ function extensionPackageName(extPath) {
  */
 export function extensionCanonicalNames(extPath) {
     const canonical = extensionCanonicalName(extPath);
+    if (extPath.startsWith("builtin:") || extPath.startsWith("<inline:"))
+        return [canonical];
     const pkg = extensionPackageName(extPath);
     return pkg && pkg !== canonical ? [canonical, pkg] : [canonical];
 }
@@ -219,12 +225,13 @@ export function parseExtSelectors(entries) {
  * snapshotted. `registerTool` writes into the very `extension.tools` maps this reads,
  * so `inScope()` sees late arrivals on the next call.
  *
- * Two enforcement points, because neither covers the whole picture:
+ * The active set and call-time checks cover different parts of scope:
  *
  *   - `turn_end` re-narrows the ACTIVE set. pi emits `turn_end` immediately before
  *     `prepareNextTurn` re-snapshots `agent.state.tools`, and session listeners run
  *     synchronously, so the narrow lands in time for turns 2..N.
- *   - `beforeToolCall` blocks out-of-scope calls. Turn 1 cannot be narrowed at all:
+ *   - The loader's bound `tool_call` handler blocks direct and nested calls.
+ *     Turn 1 cannot be narrowed at all:
  *     `before_agent_start` fires INSIDE `prompt()` and may widen the tool set, but
  *     `createContextSnapshot()` freezes that turn's tools immediately after — there
  *     is no hook in between. A call-time check is the only correct guard there.
@@ -263,7 +270,7 @@ export function installExtensionToolScope(session, ctx) {
         for (const name of EXCLUDED_TOOL_NAMES)
             keep.delete(name);
         // Injected tools are legitimately active for this agent — re-admit them so
-        // the renarrow keeps them in the active set and beforeToolCall doesn't
+        // the renarrow keeps them in the active set and the call-time guard doesn't
         // block them. Already vetted against `disallowed_tools` by the caller,
         // which is the only place that knows which kind may be taken back.
         for (const name of readmitToolNames)
@@ -272,8 +279,10 @@ export function installExtensionToolScope(session, ctx) {
     };
     const renarrow = () => {
         const allowed = inScope();
-        const next = session.getAllTools().map((t) => t.name).filter((n) => allowed.has(n));
         const current = session.getActiveToolNames();
+        // Keep deferred/codemode tools callable without promoting them into model
+        // declarations. Explicit activation by an extension is preserved in scope.
+        const next = session.getAllTools().filter((tool) => allowed.has(tool.name) && (tool.exposure === "direct" || tool.exposure === "model-only" || current.includes(tool.name))).map((tool) => tool.name);
         // setActiveToolsByName unconditionally rebuilds the system prompt, so skip
         // the no-op that steady-state turns would otherwise pay for every turn.
         if (next.length !== current.length || next.some((n, i) => n !== current[i])) {
@@ -287,16 +296,7 @@ export function installExtensionToolScope(session, ctx) {
         if (event.type === "turn_end")
             renarrow();
     });
-    const priorBeforeToolCall = session.agent.beforeToolCall;
-    session.agent.beforeToolCall = async (context, signal) => {
-        if (!inScope().has(context.toolCall.name)) {
-            return {
-                block: true,
-                reason: `Tool "${context.toolCall.name}" is not available to this subagent.`,
-            };
-        }
-        return priorBeforeToolCall?.(context, signal);
-    };
+    return (toolName) => inScope().has(toolName);
 }
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns;
@@ -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) {
@@ -557,6 +557,7 @@ export async function runAgent(ctx, type, prompt, options) {
     // must compare against this, not the surviving set (absence from survivors is
     // an exclude *succeeding*).
     let discoveredNames;
+    let toolInScope;
     const extensionsOverride = noExtensions || (loadAll && !hasExcludes)
         ? undefined
         : (base) => {
@@ -564,6 +565,8 @@ export async function runAgent(ctx, type, prompt, options) {
             return {
                 ...base,
                 extensions: base.extensions.filter((e) => {
+                    if (e.path === "<inline:subagent-tool-scope>")
+                        return true;
                     const canons = extensionCanonicalNames(e.path);
                     if (canons.some((n) => excludeNames.has(n)))
                         return false; // exclude wins
@@ -576,6 +579,19 @@ export async function runAgent(ctx, type, prompt, options) {
         agentDir,
         noExtensions,
         additionalExtensionPaths,
+        // Pi's nested ctx.executeTool calls dispatch tool_call directly, and prompt
+        // setup can replace agent.beforeToolCall. Enforce scope in that dispatch too.
+        extensionFactories: noExtensions ? [] : [{
+                name: "subagent-tool-scope",
+                hidden: true,
+                factory: (pi) => {
+                    pi.on("tool_call", (event) => {
+                        if (toolInScope && !toolInScope(event.toolName)) {
+                            return { block: true, reason: `Tool "${event.toolName}" is not available to this subagent.` };
+                        }
+                    });
+                },
+            }],
         extensionsOverride,
         noSkills,
         noPromptTemplates: true,
@@ -786,21 +802,14 @@ export async function runAgent(ctx, type, prompt, options) {
                 parentSession: ctx.sessionManager?.getSessionFile?.(),
             })
             : SessionManager.inMemory(effectiveCwd);
-    // Pi 0.80.8 replaced createAgentSession's modelRegistry option with
-    // modelRuntime, but ExtensionContext still exposes only the registry facade.
-    // Pass both so the full supported Pi range retains the parent's providers.
+    // ExtensionContext exposes the registry facade; its runtime owns provider auth.
     const parentModelRuntime = ctx.modelRegistry.runtime;
     const sessionOpts = {
         cwd: effectiveCwd,
         agentDir,
         sessionManager,
         settingsManager,
-        modelRegistry: ctx.modelRegistry,
-        // `as never` is what keeps this assignable across the supported Pi range:
-        // pre-0.80.8 the field exists only via the `modelRuntime?: unknown` shim
-        // above, while newer Pi types it as `ModelRuntime` — a shape an opaque
-        // `unknown` read off the private facade field can never satisfy.
-        ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime }),
+        modelRuntime: parentModelRuntime,
         model,
         tools: sessionTools,
         customTools: [...nestedTools, ...structuredTools],
@@ -835,7 +844,7 @@ export async function runAgent(ctx, type, prompt, options) {
     // handled below by re-deriving scope from the loader's live extension maps —
     // `registerTool` writes into those same maps, so late arrivals are judged too.
     if (!noExtensions) {
-        installExtensionToolScope(session, {
+        toolInScope = installExtensionToolScope(session, {
             loader,
             toolNames,
             disallowedSet,