@cr1ms0n/pi-subagent 0.8.9 → 0.9.0

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## Unreleased
+## Unreleased
+
+## 0.9.0 — 2026-09-21
+
+### Jev model and tool routing
+
+- Replace fixed `modelPolicy` routes for extension-managed work with required Jev selection from user-described, locally available model candidates and individual permitted tools. New work is Pi-only; management and explicit low-level SDK specs remain available.
+- Route normal/parallel/background dispatch, paid plan, `/btw`, resume/fork and deferred synthesis through the shared selector. Reject legacy explicit model/fallback fields; accept valid low-confidence decisions without substituting an emergency model.
+- Verify the child model and exact selected tool set before sending task text. Carry cancellation/deadlines through routing, preflight, startup and same-model retries.
+- Persist bounded per-request selector receipts separately from execution usage, with deduplicated native delivery and unreported selector currency. Preserve resume-lock safety, fanout usage and retained worktree pointers across failures.
+- Document manual configuration migration, minimum disclosure and rollback. No automatic settings rewrite, installation or live provider evaluation is included.
 
 ## 0.8.9 — 2026-09-16
 

package/README.md

@@ -2,16 +2,17 @@
 
 This is an independent community fork of **@parke.dev/pi-subagent 0.8.0**, originally by Luke Parke. It is not an official upstream release. The original MIT license and copyright are preserved. Upstream source: [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent).
 
-This fork requires a user-owned `modelPolicy` in `~/.pi/subagent.json` before new subagent tasks can run, and displays actual models in the TUI.
+This fork replaces the upstream fixed model route with mandatory Jev routing. New subagent dispatches require a `jevRouting` block in `~/.pi/subagent.json` (a dedicated candidate-model list plus the name of the environment variable holding your TypeSafe credential), and the TUI shows the selected execution model and tools.
 
 Production-grade isolated subagents for [Pi](https://github.com/badlogic/pi-mono).
 
 Delegate research, parallel exploration, and clean-context review to child Pi
-processes. Named agent personas, cancellable background runs with completion
-notifications and a live widget, mid-run steering, graceful budget wrap-ups,
-automatic retry with model fallback, a stall watchdog, session resume and
-context forking, worktree isolation with a diff/apply/discard loop, capability
-profiles, a root/subagent/combined cost ledger, and a TUI inspector.
+processes. Named agent personas, Jev-selected execution models and individual
+tools, cancellable background runs with completion notifications and a live
+widget, mid-run steering, graceful budget wrap-ups, bounded same-model retry, a
+stall watchdog, session resume and context forking, worktree isolation with a
+diff/apply/discard loop, capability profiles, a root/subagent/combined cost
+ledger, and a TUI inspector.
 
 ## Install
 
@@ -45,17 +46,18 @@ This fork is published manually after pack-content and offline checks — see
 ## Quick usage
 
 ```ts
-// Single foreground task; `model` must exactly match ~/.pi/subagent.json modelPolicy.
-{ task: "Find all call sites of parseConfig and summarize patterns.", description: "Map parseConfig usage", model: "<provider/model-id>" }
+// Single foreground task (default profile: general). Omit model and
+// fallback_models: Jev selects the execution model from your configured list.
+{ task: "Find all call sites of parseConfig and summarize patterns.", description: "Map parseConfig usage" }
 
-// Named agent — persona prompt from .pi/agents/reviewer.md; model still comes from modelPolicy.
-{ task: "Review this diff for security issues", agent: "reviewer", model: "<provider/model-id>" }
+// Named agent: persona prompt from .pi/agents/reviewer.md. Jev still picks the model.
+{ task: "Review this diff for security issues", agent: "reviewer" }
 
-// Parallel read-only explorers (default profile: explore); each task needs its mapped model.
+// Parallel read-only explorers (default profile for tasks[]: explore).
 {
   tasks: [
-    { task: "Map auth middleware flow", description: "Auth flow map", model: "<provider/model-id>" },
-    { task: "List all env vars used in server/", description: "Env var inventory", model: "<provider/model-id>" }
+    { task: "Map auth middleware flow", description: "Auth flow map" },
+    { task: "List all env vars used in server/", description: "Env var inventory" }
   ]
 }
 
@@ -63,15 +65,14 @@ This fork is published manually after pack-content and offline checks — see
 // outputs into a single brief, delivered first.
 {
   tasks: [
-    { task: "Audit backend error handling", description: "Backend audit", model: "<exact model from current modelPolicy route>" },
-    { task: "Audit frontend error handling", description: "Frontend audit", model: "<exact model from current modelPolicy route>" }
+    { task: "Audit backend error handling", description: "Backend audit" },
+    { task: "Audit frontend error handling", description: "Frontend audit" }
   ],
   synthesis: "Merge both audits into one prioritized findings list"
 }
 
-// Background run — model is still required; the live widget shows the actual model
-// and changes when a configured fallback is selected.
-{ task: "Audit dependency licenses", model: "<provider/model-id>", async: true }
+// Background run: the widget shows the selected model; expanded results include tools.
+{ task: "Audit dependency licenses", async: true }
 // later
 { action: "status", id: "abc123" }
 { action: "wait", id: "abc123" }      // interruptible; does not cancel
@@ -84,17 +85,17 @@ This fork is published manually after pack-content and offline checks — see
 subagent_wait { id: "abc123" }
 subagent_wait { id: "abc123", timeout_ms: 30000 }
 
-// Dry-run a spawn request: full validation + preflights (git repo, fork
-// session, output paths), returns the resolved per-task plan (model, tools,
-// budgets, isolation) without spawning anything.
-{ action: "plan", tasks: [{ task: "Implement feature A", model: "<exact model from current modelPolicy route>", isolation: "worktree" }] }
+// Dry-run a spawn request: full validation, Jev selection and local preflights
+// (git repo, fork session, output paths). Returns the resolved per-task plan
+// (model, tools, budgets, isolation) and its selector usage without spawning.
+// Selector fees apply, and a later dispatch selects again.
+{ action: "plan", tasks: [{ task: "Implement feature A", profile: "general", isolation: "worktree" }] }
 
 // Structured output: the child must end with a fenced json:result block
 // matching the schema. Invalid output gets one automatic repair round;
 // delivery is the clean JSON and details carry the parsed object.
 {
   task: "Audit the auth module",
-  model: "<exact model from current modelPolicy route>",
   output_schema: {
     type: "object",
     required: ["findings", "risk"],
@@ -107,15 +108,15 @@ subagent_wait { id: "abc123", timeout_ms: 30000 }
 
 // Fork the parent conversation into the child (needs a persisted session).
 // The child starts from a branched copy of everything discussed so far.
-{ task: "Implement the plan we agreed on", model: "<exact model from current modelPolicy route>", context: "fork", profile: "general" }
+{ task: "Implement the plan we agreed on", context: "fork", profile: "general" }
 
 // Budgets with graceful wrap-up: at the limit the child is steered to produce
 // a final answer and given grace turns before any hard stop.
-{ task: "Audit deps", model: "<exact model from current modelPolicy route>", max_turns: 15, grace_turns: 2 }
+{ task: "Audit deps", max_turns: 15, grace_turns: 2 }
 
-// Automatic retry uses the configured fallback order. If fallback_models is
-// supplied, it must exactly match modelPolicy; otherwise omit it.
-{ task: "Research X", model: "<provider/model-id>", max_retries: 1 }
+// Transient child failures retry the already selected model and tool set, up to
+// max_retries. There are no emergency or fallback models.
+{ task: "Research X", max_retries: 1 }
 
 // Steer a running child mid-run instead of cancel + retry. The message is
 // delivered after the current assistant turn, before the next LLM call.
@@ -123,14 +124,14 @@ subagent_wait { id: "abc123", timeout_ms: 30000 }
 // Parallel runs: pass index to pick one live task.
 { action: "steer", id: "abc123", index: 1, message: "Wrap up now" }
 
-// Resume a child session
-{ task: "Continue from your findings and propose a fix plan", model: "<exact model from current modelPolicy route>", resume: "<session-id>" }
+// Resume a child session. The new invocation selects again.
+{ task: "Continue from your findings and propose a fix plan", resume: "<session-id>" }
 
 // Isolated writers
 {
   tasks: [
-    { task: "Implement feature A", model: "<exact model from current modelPolicy route>", profile: "general", isolation: "worktree" },
-    { task: "Implement feature B", model: "<exact model from current modelPolicy route>", profile: "general", isolation: "worktree" }
+    { task: "Implement feature A", profile: "general", isolation: "worktree" },
+    { task: "Implement feature B", profile: "general", isolation: "worktree" }
   ]
 }
 
@@ -159,19 +160,27 @@ conversation or polluting the context window.
 
 ## Backends
 
-Children can run on a different agent CLI. Everything else — worktrees, process
-locks, depth limits, budgets, orphan reclaim — is backend-agnostic and applies
-unchanged.
+Jev routing manages Pi-backed new dispatch only. A `backend: "codex"` or
+`backend: "claude"` new task is refused before any selector or provider work,
+including a backend inherited from agent frontmatter; the extension never
+silently switches it to Pi. Existing Codex/Claude runs stay manageable:
+`status`, `wait`, `cancel`, `steer`, `diff`, `apply` and `discard` all still
+work. Provider diversity is not lost, because another provider's execution
+model stays eligible through Pi once it is in your configured candidate list.
 
 ```ts
-{ task: "Summarize this module", model: "<exact model from current modelPolicy route>", backend: "codex", profile: "explore" }
-{ task: "Review this diff",      model: "<exact model from current modelPolicy route>", backend: "claude", max_cost: 0.50 }
+// Refused on new work. Use the Pi-backed path so Jev can route it.
+{ task: "Summarize this module", backend: "codex", profile: "explore" }
 ```
 
-Requires the corresponding CLI on PATH (`codex`, `claude`). Capabilities differ,
-and **unsupported combinations are refused with an explanation rather than
-silently ignored** — a dropped `max_cost` or unenforced read-only profile would
-be a safety regression, not a minor degradation.
+The low-level SDK is a different contract: `runTasks`/`runSubagent` execute the
+explicit `TaskSpec` you hand them, so embedding code can still select a backend
+directly. Everything else (worktrees, process locks, depth limits, budgets,
+orphan reclaim) is backend-agnostic and applies unchanged.
+
+Capabilities differ, and **unsupported combinations are refused with an
+explanation rather than silently ignored**: a dropped `max_cost` or unenforced
+read-only profile would be a safety regression, not a minor degradation.
 
 |                                 | `pi` (default) | `codex`                               | `claude`               |
 | ------------------------------- | -------------- | ------------------------------------- | ---------------------- |
@@ -187,23 +196,43 @@ A budget breach on a backend without steering hard-stops instead of asking the
 child to wrap up. Codex's read-only sandbox is enforced by the OS, which is
 stronger than a tool allowlist.
 
-Set a persona's backend in agent frontmatter with `backend: codex`.
+Agent frontmatter `backend:` remains a default. New extension-managed work rejects
+any effective backend other than Pi, including a native backend inherited from an agent.
+Direct SDK specs retain the backend capabilities listed above.
 
 ## Profiles
 
 | Profile                      | Tools                                                   | Writes                                      |
 | ---------------------------- | ------------------------------------------------------- | ------------------------------------------- |
-| `explore` (parallel default) | read/grep/find/ls + safe extras + Pi context tools      | no project-file writes                      |
+| `explore` (parallel default) | locally permitted read-only tools + Pi context tools     | no project-file writes                      |
 | `review`                     | same as explore                                         | no project-file writes                      |
-| `general`                    | inherited active tools + Pi context tools               | yes if tools include bash/edit/write        |
+| `general`                    | Jev chooses from the full available locally permitted catalog + Pi context tools | yes for selected write-capable tools; unknown custom tools count as writable |
+
+Jev chooses individual tool names, not a capability bundle. Candidates come
+from the full available locally permitted catalog, not from the agent file's
+`tools` defaults and not from the parent's currently active tools. An explicit
+task `tools` list is a ceiling, and explore/review keep their read-only rule
+regardless of what the selector returns. An empty selection never means "all
+tools".
 
 For the Pi backend, the context-management tools `new_context`,
-`get_context_remaining`, `history`, and `notes` are retained in child tool
-allowlists when the parent exposes them. They are control-plane tools: they may
-update continuity notes or the remote context window, but cannot modify the
-child checkout or run a shell command. This exception also applies when a task
-supplies a narrower tool list, so Pi's `contextManagement` remains usable for
-configured gateway models.
+`get_context_remaining`, `history`, and `notes` are added locally when the
+parent exposes them, so they are never a selector question. They are
+control-plane tools: they may update continuity notes or the remote context
+window, but cannot modify the child checkout or run a shell command. This
+exception also applies when a task supplies a narrower tool list, so Pi's
+`contextManagement` remains usable for configured gateway models. Locally added
+controls are reported in the route metadata.
+
+The finalized tool set is passed to the child as Pi's `--tools` allowlist
+(`--no-tools` for a true empty set). Pi 0.86.0 is the verified baseline for
+built-in, extension and late-registered tool enforcement; a host that cannot
+honor that allowlist is refused rather than silently weakened, and the extension
+does not claim identical behavior on untested older releases. Before the real
+task prompt is sent, the child is also asked to confirm the selected model and
+the finalized tool names through a verified private startup command; if the host
+cannot verify that command or the child cannot confirm both, the launch aborts
+with a startup diagnostic instead of running with a broader tool set.
 
 Parallel write-capable tasks sharing one checkout are rejected unless each uses
 `isolation: "worktree"`, distinct `cwd`, or explicit `allow_shared_writes: true`.
@@ -229,6 +258,7 @@ Defaults can be overridden in `~/.pi/subagent.json` and per-field via env vars
 | `sessionRetentionDays`  | `PI_SUBAGENT_SESSION_RETENTION_DAYS`  | unused (lifecycle GC)                 |
 | `lockRetentionDays`     | `PI_SUBAGENT_LOCK_RETENTION_DAYS`     | 7                                     |
 | `taskDefaults`          | —                                     | none                                  |
+| `jevRouting`            | -                                     | required for new dispatch (see below) |
 | `graceTurns`            | `PI_SUBAGENT_GRACE_TURNS`             | 2                                     |
 | `stallAfterMs`          | `PI_SUBAGENT_STALL_AFTER_MS`          | 90000                                 |
 | `stallKillAfterMs`      | `PI_SUBAGENT_STALL_KILL_AFTER_MS`     | 90000                                 |
@@ -237,52 +267,93 @@ Defaults can be overridden in `~/.pi/subagent.json` and per-field via env vars
 | `notifications`         | `PI_SUBAGENT_NOTIFICATIONS`           | `batched` (`off` disables)            |
 | (bin)                   | `PI_SUBAGENT_BIN`                     | auto (`process.execPath` + CLI entry) |
 
-### Model policy
+### Jev routing
 
-New spawns are routed only by the user-owned `modelPolicy` in `~/.pi/subagent.json`.
-Agent frontmatter, `taskDefaults`, parent-session model inheritance, and ad-hoc
-fallback lists are ignored for model selection. The minimal template is:
+New subagent dispatches are selected by Jev, TypeSafe's structured-decision API,
+against a dedicated candidate list you maintain in `~/.pi/subagent.json`. Fixed
+routing is gone: a `modelPolicy` block produces a migration error, and an
+explicit `model` or `fallback_models` on new work is rejected rather than
+bypassing selection. Management actions (`status`, `wait`, `cancel`, `steer`,
+`diff`, `apply`, `discard`) never call the selector and need no credential.
 
 ```json
 {
-  "modelPolicy": {
-    "default": {
-      "model": "<provider/model-id>",
-      "fallbackModels": [],
-      "thinking": "medium"
-    },
-    "agents": {
-      "<agent-name>": {
+  "jevRouting": {
+    "selectorModel": "jev-latest",
+    "apiKeyEnv": "TYPESAFE_API_KEY",
+    "timeoutMs": 15000,
+    "models": [
+      {
         "model": "<provider/model-id>",
-        "fallbackModels": [],
-        "thinking": "high"
+        "description": "<your characteristics notes, Chinese allowed>",
+        "thinking": "<optional opaque Pi thinking default>"
       }
-    }
+    ]
   }
 }
 ```
 
+- `selectorModel` defaults to the stable alias `jev-latest`. Pin an exact
+  version to control which selector version is requested. This does not guarantee
+  deterministic choices; the extension records the version that actually answered.
+- `apiKeyEnv` defaults to `TYPESAFE_API_KEY`. Only the variable *name* lives in
+  the file. Set the credential in your local environment; the extension reads it
+  at request time and never writes it to config, prompts, argv, logs or results.
+- `timeoutMs` defaults to 15000 and must be an integer between 100 and 600000.
+  It bounds one logical task selection, including all its HTTP requests and queue
+  waits. Parallel workers each have a selection allowance, still capped by their
+  absolute task `timeout_ms` deadline. Deferred synthesis has a separate allowance.
+- `models` holds 1 to 255 entries, each with an exact `provider/model-id` and a
+  non-blank description. Those descriptions are what Jev matches against your
+  task, so write them the way you would explain the model to a colleague.
+  `thinking` is optional.
+
+Plan and background-start native usage attachments are limited to 1024 selector
+HTTP receipts per invocation. Larger requests fail with a request-splitting error;
+background work has not started at that point. Previously incurred selector tokens
+remain in the ledger. This bounds an atomic delivery record, not the number of tools
+Jev may consider within each task.
+
+The candidate list is intersected with the models the local Pi registry reports
+as available. A configured model Pi cannot resolve is not eligible, and an empty
+eligible pool fails before any request. Adding a model anywhere else in Pi does
+not authorize it, and legacy `modelPolicy` entries are never imported
+automatically. An unknown `jevRouting` field is an error, not a silent default.
+
+Jev receives only the current delegated task text, your model IDs and
+descriptions, candidate tool names and descriptions, and the permission/output
+requirements it needs to choose. It does not receive repository files,
+conversation history, full system prompts, persona text or tool parameter
+schemas. Task text and descriptions are user content and may contain sensitive
+material, so treat what you delegate as disclosure to TypeSafe.
+
+Every new extension-managed dispatch routes through Jev: `task`/`tasks[]`,
+`action:"plan"`, `/btw`, resume, fork, locally permitted nested dispatch and the
+optional `synthesis` child. `action:"plan"` calls Jev and runs the same local
+preflights, returns the resolved model/tool plan and the selector usage, and
+creates no child or run entry. A later dispatch selects again; there is no cached
+decision to reuse. If optional synthesis selection fails, the worker plan and its
+usage stay valid and synthesis is reported as blocked with its diagnostic.
+
 `thinking` is optional and is an opaque Pi thinking-level string. Common values
 include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`, but the
 package does not remap or restrict model-specific values. Pi receives the value
-unchanged and decides whether the active model supports it. It is a route default,
-not a strict policy value. Resolution order is: explicit task `thinking` > agent
-frontmatter `thinking` > profile `taskDefaults.<profile>.thinking` > the selected
-`modelPolicy` route's `thinking` > the parent session's thinking level. Omitting it
-preserves the existing behavior.
-
-Every new `task`/`tasks[]` item must pass the exact mapped `model`. Omit
-`fallback_models` to use the configured list; when supplied it must match the
-configured order exactly. Management actions remain available when this file is
-missing, but new spawns and synthesis are rejected until it is valid. The
-extension re-reads the policy on each dispatch and injects the current mapping
-into the parent prompt. No provider catalog or credentials are read.
-
-This guarantee applies to the Extension tool dispatch and its internal synthesis
-handoff. The stable SDK exports (`runTasks` and `runSubagent`) are trusted
-low-level library APIs and intentionally do not load the Extension's
-`modelPolicy`; library callers must parse and validate their own policy before
-passing `TaskSpec` values. Do not treat direct SDK calls as policy enforcement.
+unchanged and decides whether the active model supports it. Resolution order is:
+explicit task `thinking` > agent frontmatter `thinking` > profile
+`taskDefaults.<profile>.thinking` > the selected candidate's optional `thinking`
+> the parent session's thinking level. Jev never chooses a thinking level.
+
+The extension re-reads `jevRouting` on each dispatch and injects the current
+routing guidance into the parent prompt, so configuration edits reach the next
+decision without a code change. Missing or invalid `jevRouting`, or a missing
+credential environment variable, rejects new dispatch and plan with a remedy;
+management stays available.
+
+The mandatory routing above is the Extension dispatch contract. The stable SDK
+exports (`runTasks` and `runSubagent`) are trusted low-level library APIs: they
+execute the explicit `TaskSpec` you pass and perform no implicit routing, config
+discovery or network call. Library callers own model and tool choice, and must not
+read these SDK calls as Jev enforcement.
 
 ### Named agent files
 
@@ -301,7 +372,7 @@ supplies defaults using the same snake_case names as the tool parameters:
 ```md
 ---
 description: Security-focused code reviewer
-# Legacy model/fallback fields are ignored; use modelPolicy instead.
+# Legacy model/fallback fields are ignored; Jev routing owns model/tool choice.
 thinking: high
 profile: review
 max_turns: 20
@@ -330,12 +401,13 @@ file one level deep (relative to the agent file, same 64KB/symlink guards
 as `@contract.json`). Missing or rejected includes leave the line verbatim;
 includes do not recurse.
 
-Invoke with `{ task: "…", agent: "reviewer", model: "<provider/model-id>" }`.
-The agent file supplies persona/capability defaults only; its legacy
-`model`/`fallback_models` fields are ignored. An explicit `system_prompt`
-appends after the persona body.
-Profiles still enforce capability: an agent declaring `profile: review` with
-write tools fails closed. The agent catalog is advertised in the tool's
+Invoke with `{ task: "…", agent: "reviewer" }`. The agent file supplies
+persona, capability, thinking and budget defaults only: model and tool selection
+stay with Jev routing, and a legacy `model`/`fallback_models` in frontmatter is
+ignored. An explicit `system_prompt` appends after the persona body.
+Profiles still enforce capability: `profile: review` filters candidates to read-only
+tools. Legacy agent `tools` defaults are ignored; an explicit task `tools` list
+requesting write tools under review fails closed. The agent catalog is advertised in the tool's
 system-prompt guidelines (session start) and in bare `status` output (live),
 and file changes are picked up within seconds — no restart needed.
 
@@ -343,15 +415,17 @@ and file changes are picked up within seconds — no restart needed.
 
 `taskDefaults` in `~/.pi/subagent.json` remains available for non-model
 fields such as thinking, budgets, and retry counts. Its legacy `model` and
-`fallbackModels` fields are ignored; model routing belongs only to
-`modelPolicy`. A profile `thinking` value overrides the selected route default.
-Invalid fields are dropped field-by-field.
+`fallbackModels` fields are ignored; model and tool routing belong only to
+`jevRouting`. A profile `thinking` value overrides the selected candidate's
+optional `thinking` default. Invalid fields are dropped field-by-field.
 
 Notes on behavior:
 
-- `timeout_ms` covers queue time plus runtime, but timed-out tasks report
-  `state: "timeout"` with `timeoutPhase: "queued"|"starting"|"running"` so
-  agents can retry capacity issues without confusing them for task failures.
+- `timeout_ms` is the absolute task deadline: local preflight, Jev selection,
+  setup, queue time and runtime all count against it, and selection cannot reset
+  it. Timed-out tasks report `state: "timeout"` with
+  `timeoutPhase: "queued"|"starting"|"running"` so agents can retry capacity
+  issues without confusing them for task failures.
 - Budget stops (`max_turns`, `max_cost`) trigger a **graceful wrap-up**: the
   child is steered to produce its final answer NOW and allowed `graceTurns`
   more turns before SIGTERM. Results end as `partial` with `wrappedUp: true`
@@ -361,11 +435,11 @@ Notes on behavior:
   then kills after `stallKillAfterMs` more silence — feeding automatic retry
   instead of burning the whole timeout.
 - **Transient failures retry automatically** (queue timeouts, stalls, spawn
-  errors, provider errors) up to `maxRetries` extra attempts, escalating
-  through `fallback_models` when provided. Usage accumulates across attempts;
-  results record `attempts` and `attemptedModels`. Task-quality failures
-  (nonzero exit with complete protocol, cancellations, budget stops, running
-  timeouts) never retry.
+  errors, provider errors) up to `maxRetries` extra attempts on the already
+  selected model and tool set. There are no emergency or fallback models, and a
+  quality or budget failure never reselects. Usage accumulates across attempts;
+  results record `attempts`. Task-quality failures (nonzero exit with complete
+  protocol, cancellations, budget stops, running timeouts) never retry.
 - `context: "fork"` starts a single child from a real branched copy of the
   parent conversation (`--fork` on the parent's session file). It requires a
   persisted parent session, cannot combine with `resume`, and is rejected for
@@ -443,22 +517,23 @@ import {
   type TaskResult,
   type RunState,
   type UsageStats,
-} from "@parke.dev/pi-subagent/sdk";
+} from "@cr1ms0n/pi-subagent/sdk";
 ```
 
 The package root is an alias for the same SDK:
 `import { runTasks } from "@cr1ms0n/pi-subagent"`.
 
-The Extension dispatch path requires `model` to be the exact value from the
-current `modelPolicy` route. This placeholder is illustrative only and does not
-write or select a real configuration:
+The Extension dispatch path routes every new task through Jev, so callers never
+pass a model to it. The low-level SDK is the opposite contract: it is
+explicit-spec and performs no implicit routing, config discovery or network
+call, so embedding code supplies the model (and tool list) it resolved itself.
+This placeholder is illustrative only and configures nothing:
 
 ```ts
-const routeModel = "<exact model from current modelPolicy route>";
 const task: TaskSpec = {
   task: "Audit src/ for unsafe parsing",
   profile: "explore",
-  model: routeModel,
+  model: "<provider/model-id resolved by your embedding code>",
   timeoutMs: 10 * 60_000,
 };
 ```
@@ -488,25 +563,34 @@ The Pi extension entry is unchanged: package `pi.extensions` still points at
 7. On parent session shutdown, live children are aborted and awaited briefly.
 8. On parent (re)start, orphan process groups recorded under `lockDir` are reaped
    before any resume is allowed for the matching child session.
-9. Provider-reported usage is counted once per root message and terminal child run.
+9. Provider-reported usage is counted once per root message and terminal child run;
+   selector usage is a separate category counted once per selector request ID.
 10. Protocol completion prefers `agent_settled` (falls back to non-retrying `agent_end`).
+11. Jev selection precedes every new extension-managed launch, and the selected
+    tool subset is enforced by Pi's CLI allowlist; empty selection never means all tools.
 
 ## Layout
 
 ```
 src/
-  index.ts         # stable public SDK entry (@parke.dev/pi-subagent)
+  index.ts         # stable public SDK entry (@cr1ms0n/pi-subagent)
   extension.ts     # Pi wiring only
   schema.ts        # request schemas (subagent + subagent_wait)
   btw.ts           # /btw side questions (model-hidden entries)
   backend.ts       # backend adapter seam + capability gate
   backends/        # pi | codex | claude adapters (invocation + parser)
   policy.ts        # profiles, normalization, write guards, agent resolution
+  routing-types.ts # selector DTOs, decisions, receipts, local resource limits
+  routing-policy.ts# strict jevRouting parser, candidate list, routing guidance
+  jev-router.ts    # injectable Jev transport, response validation, receipts
+  dispatch-preflight.ts # bounded read-only checks before selector work
+  startup-check.ts / child-preflight.ts # private child model/tool verification
+  dispatch-routing.ts # prepare -> select -> finalize for one or many tasks
   agents.ts        # named agent files (.pi/agents/, .agents/agents/, global)
   launch.ts        # resolve child pi via execPath / PI_SUBAGENT_BIN
   process-lock.ts  # durable session locks, global slots, orphan records
   worktree.ts      # git worktree isolation + diff/apply/discard
-  orchestrator.ts  # multi-task execution, transient retry + model fallback
+  orchestrator.ts  # multi-task execution, worktree prep, bounded same-model retry
   runner.ts        # child process lifecycle, RPC channel, steering,
                    # graceful budget wrap-up, stall watchdog
   protocol.ts      # Pi RPC/JSON event parser (agent_settled-aware)
@@ -521,14 +605,24 @@ src/
 
 ## Develop
 
+This checkout has no `scripts`, no `devDependencies`, no `tsconfig.json` and no
+test runner, so `npm install`, `npm run typecheck`, `npm test` and
+`npm run pack:check` are not defined here. The checks that do run locally are
+offline:
+
 ```bash
-npm install
-npm run typecheck
-npm test
-npm run pack:check
+npm pack --dry-run --json
 ```
 
-Tests use a deterministic `fake-pi` child. No live model calls are required.
+That verifies the publishable file list matches `package.json` `files` and leaks
+no backup, transcript, session data, research output or generated bundle. Source
+changes are parse/type-strip checked by running the global Pi install's bundled
+esbuild over every `src/` and `extensions/` file; that catches malformed
+TypeScript only, not type errors or peer API mismatches. Provider-free fixtures
+and an injected fake selector transport, run with the already installed Pi runtime
+rather than a repository test framework, exercise routing behavior without any
+model call. See [.trellis/spec/backend/quality-guidelines.md](.trellis/spec/backend/quality-guidelines.md)
+for the exact commands and what each check does and does not prove.
 
 ## Cost accounting
 
@@ -544,6 +638,15 @@ The extension footer stays terse (running/ready counts only). Delivery and
 replay do not double count runs. See
 [docs/COST-ACCOUNTING.md](./docs/COST-ACCOUNTING.md).
 
+Jev selection is billed separately from execution. TypeSafe reports tokens, not
+currency, so the ledger shows routing tokens as their own category, counts each
+selector request once by its request ID (including plan and pre-spawn failures),
+and marks routing cost as **unreported** rather than free. Numeric dollar totals
+exclude unreported routing spend, and `max_cost` caps provider-reported execution
+cost only; it does not cap TypeSafe charges. Route metadata (selected model,
+selected tools, locally added controls, selector version, confidence, outcome,
+latency) travels with the run alongside usage.
+
 ## Roadmap
 
 Planned work — agent spawn policies, dry-run validation, engine hardening,