@cr1ms0n/pi-subagent 0.8.9 → 0.9.0

package/docs/ARCHITECTURE.md

@@ -12,9 +12,10 @@
   after a second window so retry can take over. Group kills verify process start-time
   identity (Linux `/proc`, macOS/BSD `ps lstart`) before signalling a possibly-recycled
   PID; transcript joins happen only on message boundaries, not per-chunk ticks.
-- Retry with model fallback lives in `orchestrator.ts` (`isTransientFailure`): queue
-  timeouts, stalls, spawn errors, and provider errors re-run the same spec on the next
-  fallback model with accumulated usage; task-quality failures never retry.
+- Retry lives in `orchestrator.ts` (`isTransientFailure`): queue timeouts, stalls, spawn
+  errors, and provider errors re-run the same already-selected spec (model and tool set)
+  with accumulated usage; there is no fallback-model escalation, and task-quality failures
+  never retry.
 - `context: "fork"` spawns the child with `--fork <parent session file>` so it starts
   from a real branched copy of the parent conversation. Fail-fast when the parent
   session is not persisted; single-task only.
@@ -26,10 +27,20 @@
   identity records for orphan reconcile.
 - `launch.ts`: resolve the child `pi` invocation via `PI_SUBAGENT_BIN` or
   `process.execPath` + CLI entry (bare PATH name only as last-resort fallback).
-- `persistence.ts`: versioned active-branch event folding and bounded child transcript metadata.
+- `persistence.ts`: versioned active-branch event folding, the bounded routing-event decoder
+  (`subagent-routing-v1`), and bounded child transcript metadata.
 - `maintenance.ts`: filesystem GC (session files) and abort-race helpers; kept out of persistence.
-- `usage.ts`: provider-reported root/subagent/combined accounting.
+- `usage.ts`: provider-reported root/subagent/combined accounting, plus a separate
+  once-per-request routing-token category whose currency is reported as unreported.
 - `policy.ts` / `schema.ts`: discriminated request validation and safe capability profiles. `schema.ts` retains the canonical TypeBox validators and derives provider-safe tool-schema projections; `extension.ts` registers those projections while validating calls with the originals. Pi context-management control-plane tools remain available to child allowlists without granting project-file write access.
+- `routing-types.ts` / `routing-policy.ts` / `jev-router.ts` / `dispatch-routing.ts`:
+  the mandatory Jev route. `routing-types.ts` owns the selector DTOs, decision/receipt
+  shapes and local resource limits; `routing-policy.ts` owns the strict `jevRouting`
+  parser, the candidate intersection with locally available models, and the injected
+  model-facing guidance; `jev-router.ts` owns the injectable TypeSafe transport,
+  response validation, deadlines and per-request receipts; `dispatch-routing.ts`
+  resolves every worker before any launch and refuses a partially selected fanout. The
+  router has no engine imports and makes no parent UI calls.
 - `config.ts`: defaults ← `~/.pi/subagent.json` ← `PI_SUBAGENT_*` env overrides.
 - `structured.ts`: structured-output contract (dependency-free JSON-Schema subset
   validation, fenced json:result extraction, contract/repair prompts) and
@@ -65,7 +76,9 @@ Invariants:
 9. On startup, orphan process groups recorded under `lockDir` are reaped (SIGTERM then SIGKILL)
    before any matching child session is eligible for resume. `$state: "lost"` is a labeling
    that keeps `resumeBlocked` until reconciliation proves death.
-10. Billed usage is folded once per root message and once per full child run UUID.
+10. Billed execution usage is folded once per root message and once per full child run UUID.
+    Selector usage is a separate category folded once per selector request ID, with currency
+    reported as unreported rather than inferred.
 11. Checkpoint persistence events are lightweight (state, usage, process identity, pointers).
     Full transcripts and final output are persisted exactly once, in the terminal event.
 12. High-frequency registry "changed" events coalesce (trailing window); state transitions,
@@ -96,10 +109,10 @@ Invariants:
     turns before SIGTERM; a child that concludes within grace ends `partial` with
     `wrappedUp: true`. `graceTurns: 0` restores immediate stops.
 21. Transient failures (queued timeout, stall, spawn error, provider error, protocol
-    truncation) retry up to `maxRetries` extra attempts, escalating through
-    `fallback_models`; usage accumulates across attempts and `attemptedModels` is
-    recorded. Task-quality failures (nonzero exit with complete protocol, cancellation,
-    budget stop, running timeout) never retry.
+    truncation) retry up to `maxRetries` extra attempts on the already selected model and
+    tool set; there is no fallback-model escalation and no reselection. Usage accumulates
+    across attempts. Task-quality failures (nonzero exit with complete protocol,
+    cancellation, budget stop, running timeout) never retry.
 22. The stall watchdog treats protocol silence as suspect, not fatal: after
     `stallAfterMs` the task is flagged and probed via `get_state` (a live child's
     answer clears the flag); only continued silence for `stallKillAfterMs` more kills
@@ -120,6 +133,36 @@ Invariants:
     `activeAtOrBelowDepth(depth) < maxGlobalActive - reservedFor(depth)`, holding slots
     back for deeper tiers so a full-width spawn tree cannot deadlock on its own children.
     Slot records without a `depth` field count as depth 0.
-28. `action: "plan"` is a truth oracle: it runs the exact validation and preflights of a
-    real spawn and returns the resolved plan without spawning — never a softer check, and
-    never a registry entry.
+28. `action: "plan"` is a truth oracle: it runs the exact validation, Jev selection and
+    local preflights of a real spawn and returns the resolved plan and its selector usage
+    without spawning. It creates no registry entry, and its fee-bearing selection is not
+    cached for a later dispatch.
+29. Every new extension-managed launch (`task`/`tasks[]`, `action:"plan"`, `/btw`,
+    resume, fork, nested dispatch and the optional synthesis child) crosses one selector
+    interface before any child starts. The dedicated candidate list intersected with
+    locally available models is the only source of execution models; the full locally
+    permitted tool catalog is the only candidate source. Legacy `model`/`fallback_models`
+    fields are rejected on new work, and an empty selected tool set never becomes
+    inheritance or "all tools".
+30. The finalized tool subset is passed to the child as Pi's `--tools` allowlist
+    (`--no-tools` when empty). Pi 0.86.0 is the verified baseline for built-in, extension
+    and late-registered tool enforcement; a host that cannot honor the allowlist is
+    refused rather than silently weakened, and no older release is advertised as
+    equivalent.
+    Startup verification is the enforcement companion: the Pi adapter supplies a
+    package-local preflight extension plus a bounded non-secret expectation, verifies that
+    the nonce-specific bootstrap command exists from the expected package source, then
+    requires the child to acknowledge the exact selected model and finalized tool names
+    (including nested-tool source) before the real task prompt is sent. Missing or
+    mismatched acknowledgement is a capability/startup diagnostic, never compensated by
+    broadening tools or choosing another model.
+31. An absolute task deadline is created before preflight/selection, and routing, setup,
+    queue and retries all count against it. Pending selector work is tracked per session
+    runtime, aborted on cancellation, shutdown or session switch, and every post-await
+    transition re-checks captured runtime/session ownership so a late response cannot
+    launch into a replaced session.
+32. Before any paid selection, plan and dispatch share a side-effect-free direct-resume
+    availability check (in-memory owner, `resumeBlocked`, durable lock ownership and
+    staleness) that acquires, renews or reaps nothing. Dispatch still takes the
+    authoritative lock atomically at the existing launch point, and forked resumes skip
+    the exclusive direct-resume check.

package/docs/COST-ACCOUNTING.md

@@ -1,66 +1,116 @@
-# Cost accounting
-
-`pi-subagent` reports three independent ledgers:
-
-- **root** — provider-reported usage from assistant messages on the active parent-session branch.
-- **subagents** — provider-reported cumulative usage from child-run checkpoints and terminal events on that same branch.
-- **combined** — root + subagents.
-
-These totals appear in `subagent { action: "status" }`, per-run status, the `/subagent-cost` command, and the `/subagents` overlay header. The footer stays terse (running/ready counts only) because Pi's native footer already shows session cost — including subagent spend, on Pi builds with native tool-result usage accounting (see below).
-
-## Source of truth
-
-The extension does not estimate prices. It uses Pi's normalized provider response:
-
-```ts
-message.usage.cost.total
-```
-
-It also retains provider-reported input/output/cache category costs, token counts, reasoning tokens, context size, and completed turn count when supplied.
-
-## Native Pi usage accounting
-
-Pi builds after v0.80.10 persist an optional `usage` field on tool-result messages ([pi#6671](https://github.com/earendil-works/pi/pull/6671)) and fold it into the native footer total, `/session` statistics (as `Tools/summaries`), and RPC `get_state` totals.
-
-The extension participates in both directions:
-
-- **Upward** — the tool result that *delivers* a run (foreground completion, or the first `wait`) carries the run's total provider usage as native `usage`. Attachment is gated on the same delivered-flag transition as output delivery, so it happens exactly once per run UUID. Status, replayed waits, steer, diff/apply/discard, and plan responses never attach usage. Older Pi hosts copy only `content`/`details` from tool results and silently ignore the field — safe on every version this package supports.
-- **Downward** — a child's event stream may contain tool-result messages that themselves carry nested usage (for example, a grandchild subagent on a new-Pi child). The parent folds that into the run's cumulative usage, so `max_cost` budgets and both ledgers see true subtree spend. Pre-#6671 children simply never emit the field.
-
-Known undercounts in the **native** total (the extension ledger still counts these from persisted entries):
-
-- A background run dismissed in the overlay (or via status) without a delivering `wait` never produces a tool result, so its spend reaches only the extension ledger.
-- A failed or lost run raises an error instead of returning a tool result; any pre-failure usage likewise reaches only the extension ledger.
-
-Because the native footer counts parent assistant messages plus delivered tool-result usage, and the extension's **combined** counts the same runs by UUID, the two agree whenever every terminal run was delivered.
-
-## Deduplication rules
-
-1. Root assistant messages are counted once by session-entry ID.
-2. Each subagent run is counted once by full run UUID; the newest live/checkpoint/terminal cumulative value replaces older values.
-3. Delivery, dismissal, status, and checkpoint events never add cost.
-4. If an old run is evicted from in-memory UI history, its latest persisted usage still contributes to the session ledger.
-5. Active and immediately completed runs supplement or replace stale persisted checkpoints until newer session entries become visible; the full run UUID prevents double counting afterward.
-6. Resumed and forked invocations are distinct billed runs. Their new provider usage is counted once, even though they reuse prior context.
-7. Retry attempts (transient-failure retries and model fallbacks) accumulate into their
-   run's single usage record — every attempt's billed usage counts once, under one run
-   UUID, with `attemptedModels` recording the escalation path.
-8. The optional parallel `synthesis` child bills into the same run as an extra result.
-9. Native `usage` on the delivering tool result mirrors rule 2's run totals and is attached at most once per run (delivered-flag gated), so Pi-side totals cannot double count a run either.
-
-## Branch semantics
-
-Only `sessionManager.getBranch()` is used. Costs from abandoned sibling branches are excluded. When a parent session is forked, its inherited active-branch terminal entries remain part of that fork's historical total; new runs are added to the fork independently.
-
-## Failure and cancellation
-
-Any usage reported before a failure, timeout, budget stop, cancellation, or parent crash is retained in a cumulative checkpoint/terminal record. A run with no provider response contributes zero rather than an estimate.
-
-## Provider limitations
-
-Accounting is only as precise as the provider data normalized by Pi:
-
-- Some providers may report zero or incomplete costs.
-- `reasoning` is a subset of output tokens and is not added to output again.
-- `contextTokens` is the latest turn's context size, not an additive billed-token field.
-- The extension deliberately does not infer missing prices from a local model table.
+# Cost accounting
+
+`pi-subagent` reports four independent ledgers:
+
+- **root** — provider-reported usage from assistant messages on the active parent-session branch.
+- **subagents** — provider-reported cumulative usage from child-run checkpoints and terminal events on that same branch.
+- **routing**: usage reported by the Jev/TypeSafe selector, one record per selector HTTP request.
+- **combined**: root + subagents + routing.
+
+These totals appear in `subagent { action: "status" }`, per-run status, the
+`/subagent-cost` command, and the `/subagents` overlay header. The footer stays
+terse (running/ready counts only) because Pi's native footer already shows
+session cost, including subagent spend, on Pi builds with native tool-result
+usage accounting (see below).
+
+## Source of truth
+
+The extension does not estimate prices. It uses Pi's normalized provider response:
+
+```ts
+message.usage.cost.total
+```
+
+It also retains provider-reported input/output/cache category costs, token counts, reasoning tokens, context size, and completed turn count when supplied.
+
+## Routing (selector) accounting
+
+Jev selection is billed separately from child execution:
+
+- TypeSafe reports input and output **tokens**, not billed currency. The routing
+  ledger therefore reports tokens and marks its currency as **unreported**. Do not
+  read the numeric `0` currency placeholder in the native usage schema as the
+  selector being free: it is the API-required number for an unreported value.
+- Numeric dollar totals for root/subagent/combined exclude unreported routing
+  spend. The status line says so explicitly rather than silently omitting it.
+- `max_cost` remains the provider-reported execution ceiling for the child and
+  its subtree. It cannot cap TypeSafe charges, so a run can stay under `max_cost`
+  while still incurring selector fees.
+- No selector price is inferred from a public price page or a local model table.
+
+A routing record exists per selector HTTP request, not per logical selection: a
+model question plus one or more packed tool-question requests each produce their
+own record, and all of them count once by full request ID. Plan selections and
+pre-spawn failures are included, because no child run exists to carry them.
+
+Successful route metadata (decision ID, selector model and reported version(s),
+selected execution model/tools, locally added control-plane tools, confidence,
+success outcome, latency and receipt IDs) travels with the run and both registry
+projections. Per-request failure outcomes and safe error codes stay in selector receipts. It carries no descriptions, raw request bodies, headers,
+credentials or invented rationale.
+
+Receipts pending append visibility remain in a bounded session-local overlay until the
+active branch exposes the matching record. Persistence retries reuse the receipt ID,
+not the paid selector request. If persistence cannot be confirmed, new child launch is
+blocked and a branch change is cancelled; a forced shutdown reports that durable usage
+may be incomplete. This cannot repair an unavailable storage adapter after process exit.
+
+## Native Pi usage accounting
+
+Pi builds after v0.80.10 persist an optional `usage` field on tool-result messages ([pi#6671](https://github.com/earendil-works/pi/pull/6671)) and fold it into the native footer total, `/session` statistics (as `Tools/summaries`), and RPC `get_state` totals.
+
+The extension participates in both directions:
+
+- **Upward**: the tool result that *delivers* a run (foreground completion, or the first `wait`) carries the run's total provider usage as native `usage`. Attachment is gated on the same delivered-flag transition as output delivery, so it happens exactly once per run UUID. Status, replayed waits, steer, diff/apply/discard, and plan responses never attach run execution usage; plan may report its own selector usage through its result instead (rule 10). Older Pi hosts copy only `content`/`details` from tool results and silently ignore the field; that is safe on every version this package supports.
+- **Downward**: a child's event stream may contain tool-result messages that themselves carry nested usage (for example, a grandchild subagent on a new-Pi child). The parent folds that into the run's cumulative usage, so `max_cost` budgets and the execution/routing ledgers see true subtree spend. Pre-#6671 children simply never emit the field.
+
+Known undercounts in the **native** total (the extension ledger still counts these from persisted entries):
+
+- A background run dismissed in the overlay (or via status) without a delivering `wait` never produces a tool result, so its spend reaches only the extension ledger.
+- A failed or lost run raises an error instead of returning a tool result; any pre-failure usage likewise reaches only the extension ledger. The same native limitation applies to selector usage on a thrown error: the extension ledger retains it, but a thrown tool call cannot attach a native usage object. This is documented rather than converted into a success.
+
+Because the native footer counts parent assistant messages plus delivered tool-result usage, and the extension's **combined** counts the same runs by UUID, the reported token totals agree when every run and selector receipt was successfully delivered as native usage. Thrown errors and undelivered plan/dispatch failures can leave selector usage only in the extension ledger; currency totals never include unreported selector fees.
+
+## Deduplication rules
+
+1. Root assistant messages are counted once by session-entry ID.
+2. Each subagent run is counted once by full run UUID; the newest live/checkpoint/terminal cumulative value replaces older values.
+3. Delivery, dismissal, status, and checkpoint events never add cost.
+4. If an old run is evicted from in-memory UI history, its latest persisted usage still contributes to the session ledger.
+5. Active and immediately completed runs supplement or replace stale persisted checkpoints until newer session entries become visible; the full run UUID prevents double counting afterward.
+6. Resumed and forked invocations are distinct billed runs. Their new provider usage is counted once, even though they reuse prior context.
+7. Retry attempts (transient-failure retries on the already selected model and tool set)
+   accumulate into their run's single usage record: every attempt's billed usage counts once
+   under one run UUID. There is no fallback-model escalation, so `attemptedModels` repeats the
+   selected model rather than recording a route change.
+8. The optional parallel `synthesis` child bills into the same run as an extra result.
+9. Selector requests are counted once by full selector request ID, including plan
+   requests and pre-spawn rejected decisions. Route references inside task results
+   never add selector usage again, and each receipt is folded once across
+   replay/status/repeated wait.
+10. Native `usage` on the delivering tool result mirrors rule 2's run totals and is attached at most once per run (delivered-flag gated), so Pi-side totals cannot double count a run either. Worker pre-spawn routing tokens attach once at async start; the first delivery/wait attaches child execution usage plus any deferred-synthesis routing tokens not yet delivered; foreground completion attaches all invocation routing tokens plus execution tokens. Plan attaches only its own routing usage. Missing usage on an interrupted or invalid response stays **unknown**, never an invented zero. A partial or malformed token report retains individually validated counts while marking completeness unknown; for example, valid input with invalid output is not a complete report.
+
+Native routing attachment commits atomically: foreground/wait use the run's single
+`delivered` event for linked receipts; plan and async-start use one `native-delivery`
+request-ID batch on the routing event stream. A throwing append does not consume a
+prefix or set the in-memory run delivered flag. Transient persistence failures retry
+without another selector call. A batch holds at most 1024 receipt IDs; larger plan or
+background requests must be split. Background requests check this bound before any
+child/run registration. Already incurred selector usage stays in the ledger.
+
+## Branch semantics
+
+Only `sessionManager.getBranch()` is used. Costs from abandoned sibling branches are excluded. When a parent session is forked, its inherited active-branch terminal entries remain part of that fork's historical total; new runs are added to the fork independently.
+
+## Failure and cancellation
+
+Any usage reported before a failure, timeout, budget stop, cancellation, or parent crash is retained in a cumulative checkpoint/terminal record. A run with no provider response contributes zero rather than an estimate.
+
+## Provider limitations
+
+Accounting is only as precise as the provider data normalized by Pi:
+
+- Some providers may report zero or incomplete costs.
+- `reasoning` is a subset of output tokens and is not added to output again.
+- `contextTokens` is the latest turn's context size, not an additive billed-token field.
+- The extension deliberately does not infer missing prices from a local model table, and TypeSafe's token-only reports are never converted into a dollar estimate.

package/docs/RELEASING.md

@@ -1,32 +1,32 @@
-# Releasing @cr1ms0n/pi-subagent
-
-This is an independent community fork of `@parke.dev/pi-subagent` by Luke Parke. Preserve the MIT license and copyright, and do not publish this fork under the upstream scope. The upstream monorepo's tag automation does not publish this package.
-
-## Prepare
-
-1. Update `package.json` and `CHANGELOG.md`; use an unpublished version.
-2. Run strict type checking against the installed Pi version and offline fake-runner/extension tests. Do not run real provider calls without permission.
-3. Run `npm pack --dry-run --json` and review the file list. Do not include authentication, user settings, machine-specific paths, local backups, session transcripts or generated test bundles.
-4. Run `npm pack --ignore-scripts`, install the resulting tarball into an isolated prefix with `--ignore-scripts --legacy-peer-deps`, then repeat the offline checks against the packed source.
-
-## Publish
-
-Use an existing npm login or a securely supplied environment-based credential. Never put tokens in command text, source files, or a committed `.npmrc`. Enable TLS verification.
-
-```bash
-npm whoami --strict-ssl=true --registry=https://registry.npmjs.org/
-npm publish ./cr1ms0n-pi-subagent-<version>.tgz --access public --ignore-scripts --strict-ssl=true --registry=https://registry.npmjs.org/
-npm view @cr1ms0n/pi-subagent@<version> name version dist.integrity --strict-ssl=true --registry=https://registry.npmjs.org/
-```
-
-A successful public release makes every file in the tarball public. Verify the package metadata and registry integrity before replacing an existing installation.
-
-## Install and replace
-
-```bash
-pi install npm:@cr1ms0n/pi-subagent@<version>
-```
-
-Do not enable this package and `@parke.dev/pi-subagent` at the same time: both register the same tool names. Back up the old package selection, activate only the new package after verification, and keep the old source for rollback. Reload or restart Pi after changing packages. Configure `~/.pi/subagent.json` modelPolicy before spawning tasks.
-
-This fork uses the same config and persisted state paths as upstream. Switching packages is not a data migration. Upgrading must not overwrite user model choices or credentials.
+# Releasing @cr1ms0n/pi-subagent
+
+This is an independent community fork of `@parke.dev/pi-subagent` by Luke Parke. Preserve the MIT license and copyright, and do not publish this fork under the upstream scope. The upstream monorepo's tag automation does not publish this package.
+
+## Prepare
+
+1. Update `package.json` and `CHANGELOG.md`; use an unpublished version.
+2. Run strict type checking against the installed Pi version and offline fake-runner/extension tests. Do not run real provider calls without permission.
+3. Run `npm pack --dry-run --json` and review the file list. Do not include authentication, user settings, machine-specific paths, local backups, session transcripts or generated test bundles.
+4. Run `npm pack --ignore-scripts`, install the resulting tarball into an isolated prefix with `--ignore-scripts --legacy-peer-deps`, then repeat the offline checks against the packed source.
+
+## Publish
+
+Use an existing npm login or a securely supplied environment-based credential. Never put tokens in command text, source files, or a committed `.npmrc`. Enable TLS verification.
+
+```bash
+npm whoami --strict-ssl=true --registry=https://registry.npmjs.org/
+npm publish ./cr1ms0n-pi-subagent-<version>.tgz --access public --ignore-scripts --strict-ssl=true --registry=https://registry.npmjs.org/
+npm view @cr1ms0n/pi-subagent@<version> name version dist.integrity --strict-ssl=true --registry=https://registry.npmjs.org/
+```
+
+A successful public release makes every file in the tarball public. Verify the package metadata and registry integrity before replacing an existing installation.
+
+## Install and replace
+
+```bash
+pi install npm:@cr1ms0n/pi-subagent@<version>
+```
+
+Do not enable this package and `@parke.dev/pi-subagent` at the same time: both register the same tool names. Back up the old package selection, activate only the new package after verification, and keep the old source for rollback. Reload or restart Pi after changing packages. Configure `~/.pi/subagent.json` `jevRouting` (candidate models plus the credential environment variable) before spawning tasks.
+
+This fork uses the same config and persisted state paths as upstream. Switching packages is not a data migration. Upgrading must not overwrite user model choices or credentials.

package/docs/SECURITY.md

@@ -10,7 +10,7 @@ and can use tools according to their capability profile.
 |---------|---------------|---------|
 | `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and Pi context tools) | No project-file writes |
 | `review` | same as explore | No project-file writes |
-| `general` | inherited active tools (+ Pi context tools) | Yes if `bash`/`edit`/`write` are active |
+| `general` | Jev-chosen subset of the full available locally permitted catalog (+ Pi context tools) | Yes if the selected tools include `bash`/`edit`/`write` |
 
 Parallel mode defaults to `explore` to avoid concurrent shared writes.
 
@@ -20,7 +20,16 @@ Parallel mode defaults to `explore` to avoid concurrent shared writes.
    an explore/review profile. Pi context-management tools (`new_context`,
    `get_context_remaining`, `history`, `notes`) are an explicit control-plane
    exception: they may update continuity notes/window state but cannot access
-   the project write tools.
+   the project write tools. The finalized tools reach the child as Pi's `--tools`
+   allowlist (`--no-tools` when empty), and the selector's answer is re-validated
+   locally: unknown, unavailable or unsafe choices cannot launch broader
+   capability, and an empty selection never becomes "all tools". Pi 0.86.0 is the
+   verified baseline for built-in, extension and late-registered tool enforcement;
+   a host that cannot honor the allowlist is refused rather than silently weakened.
+   Before the real task prompt, a package-local startup check verifies the routing
+   bootstrap command source and has the child acknowledge the exact selected model
+   and tool names; a mismatch aborts as a capability diagnostic and is never fixed
+   by widening tools, switching models or approving project trust.
 2. **Parallel writers** require `isolation: "worktree"`, distinct `cwd` values,
    or an explicit `allow_shared_writes: true` opt-in.
 3. **Depth is capped** (`maxDepth`, default 2). Nested children at the ceiling do
@@ -55,8 +64,34 @@ Parallel mode defaults to `explore` to avoid concurrent shared writes.
    Git worktrees only isolate the checkout. For untrusted tasks, use an outer
    container/cgroup/network policy.
 10. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
-    turn; orphans may spend money the ledger never sees. Combine with provider
-    account budgets for hard spend limits.
+    turn; orphans may spend money the ledger never sees. It caps provider-reported
+    execution cost only: TypeSafe reports routing tokens, not currency, so selector
+    cost is unreported and outside `max_cost`. Combine with provider account
+    budgets for hard spend limits.
+
+## Routing disclosure and credentials
+
+Jev routing sends a minimal projection to TypeSafe: the current delegated task
+text, the configured candidate model IDs and your per-model descriptions,
+eligible candidate tool names and descriptions, and necessary constraints
+(profile, requested thinking, whether structured output is needed). It does not
+upload repository files, conversation history, full system prompts, persona text
+or tool parameter schemas, and does not read them in the background. Resume, fork
+and synthesis select from the new task instruction rather than the assembled
+transcript. Task text and model descriptions are user content and can themselves
+contain secrets; there is no guaranteed redaction.
+
+The TypeSafe credential is read from the environment variable named by
+`jevRouting.apiKeyEnv` (default `TYPESAFE_API_KEY`) and sent only as an
+`Authorization` header to the fixed official HTTPS endpoint, with redirects
+disabled. It is never stored in the config file, prompts, argv, logs or results.
+Rotate any credential that has been pasted into a transcript or shared in
+conversation.
+
+New extension-managed dispatch is Pi-only. A `backend: "codex"` or
+`backend: "claude"` new task is rejected before any selector or provider work,
+including a backend inherited from agent frontmatter, rather than silently
+switched to Pi. Existing native-backend runs stay manageable.
 
 ## Trust and project cwd
 
@@ -72,7 +107,9 @@ duplicate output paths across parallel workers.
 ## Named agent files
 
 Agent files (`.pi/agents/`, `.agents/agents/`, global agent dir) inject their
-body into the child's system prompt and set its model/tools/budgets. A
+body into the child's system prompt and set persona, thinking and budget
+defaults. Model and tool selection come from Jev routing; a legacy
+`model`/`fallback_models` in frontmatter is ignored. A
 project-level agent file shapes subagent behavior the same way project
 extensions and skills do — review them like code when working in untrusted
 repositories. Mitigations: capability profiles still fail closed (an agent