@cr1ms0n/pi-subagent 0.8.9 → 0.9.0

package/docs/UX.md

@@ -1,141 +1,158 @@
-# pi-subagent UX
-
-## Overview
-The standalone pi-subagent provides rich TUI support for monitoring, inspecting, and interacting with isolated subagent runs (single and parallel modes): inline streaming blocks, a terse footer, an ambient widget for background runs, batched completion notifications, mid-run steering, a worktree apply loop, and the `/subagents` inspector. UI logic is kept independent from `runner`/`registry` via small structural adapters (`SubagentAdapter`).
-
-## Design principles
-
-1. **Pi's tool shell owns state signaling.** The Box wrapper paints
-   `toolPendingBg` / `toolSuccessBg` / `toolErrorBg`, so inline blocks do not
-   repeat state words or draw their own success/error framing.
-2. **Cost is a per-run attribute, not a competing ledger.** Dollar cost appears
-   inside the run's own result block; the parent/children/combined ledger is
-   available on demand via `/subagent-cost`, in `status` tool output, and in the
-   `/subagents` overlay header. The footer never shows cost.
-3. **Fixed-height, mutate-in-place progress.** Streaming blocks keep a stable
-   shape (stats line + one `⎿ activity` line; parallel adds one line per task)
-   and the same component identity is reused across partial renders.
-4. **Trailing-edge streaming flush.** Structural updates (state transition, new
-   session id, billed turn) emit immediately; live-text bursts coalesce with a
-   deferred flush so the last update of a burst always lands.
-
-## Surfaces
-
-### Inline tool block (foreground runs)
-- `renderCall` is exactly one line: `subagent <task preview>` (or
-  `N parallel tasks — first task…`, `wait a1b2c3d4`, `… · background`).
-- `renderResult` while streaming (fixed shape, spinner animates via wall-clock
-  frame; Pi's working indicator drives repaints):
-  ```
-  ⠹ ↻3 · 12.4k tok · 8s
-    ⎿ reading src/auth/middleware.ts…
-  ```
-- Terminal single run:
-  ```
-  ↻8 · 33.8k tok · $0.012 · 12s
-    ⎿ Found 5 middleware call sites…
-    → /tmp/report.md
-  ```
-- Parallel: one line per task with a themed state glyph
-  (`◌ queued · ⠹ running · ✓ done · ✗ failed · ◐ partial · − cancelled · ◷ timeout`),
-  per-task stats, and a one-line tail (live activity or first output line).
-- Expanded (Ctrl+O / `app.tools.expand`): full task output capped with a dim
-  `… +N lines` trailer pointing at the artifact/child session.
-- Durations freeze at `endedAt`; running durations tick at render time.
-- Reliability annotations render inline: `[attempt 2]` during a retry,
-  `[stalled 2m]` while the stall watchdog is flagging silence, and
-  `◐ wrapped up` on budget-stopped runs that concluded gracefully.
-
-### Footer status
-Terse and actionable only: `⚙ 2 running · 1 ready · /subagents`. Cleared when
-nothing is running or ready. No cost — Pi's footer already shows session cost.
-
-### Ambient widget (background runs only)
-An above-editor widget renders while `async: true` runs are live — foreground
-runs already render inline as the tool result, so they never appear here
-(avoids double-render):
-
-```
-● Subagents
-├─ ⠼ Audit deps · ↻4 · 18k tok · 41s
-│   ⎿ checking license headers…
-└─ ◌ License scan · 12s
-```
-
-Cleared when the last background run settles. Spinner and elapsed animate on
-a 250ms interval that exists only while background runs are live.
-
-### Completion notifications (background runs only)
-When an async run reaches a terminal state, a `steer` message (custom type
-`subagent-completion`) is queued for the parent LLM before its next LLM call,
-so it can react without polling. The human sees a themed compact box (state
-glyph, label, stats, one-line preview, artifact pointers); the LLM sees plain
-text with run ids and a `wait { id }` pointer.
-
-- Successes within a short window batch into one message (no fanout spam);
-  failures bypass batching and flush immediately, carrying held successes.
-- A `wait` that already delivered the run suppresses the redundant
-  notification (delivered-state is re-checked at flush time).
-
-### `/subagents` overlay
-- Header: title + running/ready counters + full usage ledger + rule.
-- List: two lines per run — glyph/id/state/stats, then the task preview.
-  Selection cursor `▶`, animated spinner for live runs.
-- Detail: run stats, summary, then per-task sections (glyph, label,
-  model/profile/thinking, usage, pointers, transcript/final output/errors),
-  scrollable with ↑↓/j/k and PageUp/PageDown.
-- Actions: `c` cancel, `s` steer (prompts for a message, injects it into the
-  running child), `d` dismiss, `r` resume, `o` output pointers, `a` apply a
-  finished run's changed worktree into the main checkout (confirm dialog),
-  `x` discard worktree + branch (confirm dialog), Enter drill-down,
-  Esc/b back, Esc/q close.
-- Live transcript (`t` on a **running** run's detail): tails the child's
-  session file (`sessionDir/<…sessionId…>.jsonl`) on a 500ms poll while the
-  pane is visible — compact role/tool lines, auto-follow unless you scroll
-  up (which pauses follow). No RPC reads; hidden/finished runs never poll.
-  Missing file shows “waiting for child session…”. `s` steering still works
-  from the same pane so observe → steer stays on one surface.
-
-### `/subagent-cost`
-Prints the root/subagents/combined ledger once, on demand.
-
-### Mid-run steering
-Children run in Pi RPC mode, so their stdin stays open as a command channel.
-`action: "steer"` (or `s` in the overlay) queues a message that is delivered
-after the child's current assistant turn, before its next LLM call — course
-correction without cancel + retry. Parallel runs steer one task via `index`.
-
-### Worktree loop
-Finished runs with changed worktrees support `diff` / `apply` / `discard`
-actions (tool) and `a` / `x` keys (overlay). `apply` lands the worktree's
-combined patch (committed + uncommitted + untracked vs base) onto the main
-checkout as **uncommitted working-tree changes** via `git apply --3way`; it
-never commits and never deletes the worktree. `discard` is the explicit
-cleanup step and always confirms first.
-
-### Parallel fan-in
-`synthesis: "<instruction>"` on a parallel run spawns one read-only child
-after all tasks settle that folds their outputs into a single brief, delivered
-first in the result. Synthesis failures degrade silently to raw results.
-
-## States
-- **Queued/Running**: spinner + live stats + activity tail from live text.
-- **Completed/Partial/Failed/Cancelled/Timeout/Lost**: state glyph, frozen
-  duration, usage summary, output pointers; failures show the error message.
-- **Delivered vs Undelivered**: footer/overlay track pending delivery.
-- **Notification**: one per terminal transition to avoid spam.
-
-## Integration Notes
-- Extension wires via `ctx.ui.custom((tui, theme, kb, done) => createSubagentsOverlay(tui, theme, adapter, done), {overlay: true})`.
-- Adapter provides getActiveRuns/getCompletedRuns/cancelRun etc. without tight coupling.
-- Inline renderers reuse `context.lastComponent` (a `LineBlock`) so the row keeps
-  a stable component identity across partial renders.
-- Streamed tool updates separate LLM-facing `content` (compact status string)
-  from render-facing `details` (state, usage, live-text tail, run timing).
-- Tests combine pure UI models with a headless Pi extension harness: format
-  helpers, block layouts (collapsed/streaming/terminal/parallel), navigation,
-  truncation (ANSI-safe via `visibleWidth`), ready state, lifecycle/disposal.
-- Follows Pi TUI guidelines (render(width), handleInput, invalidate,
-  requestRender, dispose). The overlay owns a single animation interval.
-
-See ARCHITECTURE.md for ownership boundaries. All rendering respects terminal width and ANSI safety.
+# pi-subagent UX
+
+## Overview
+The standalone pi-subagent provides rich TUI support for monitoring, inspecting, and interacting with isolated subagent runs (single and parallel modes): inline streaming blocks, a terse footer, an ambient widget for background runs, batched completion notifications, mid-run steering, a worktree apply loop, and the `/subagents` inspector. UI logic is kept independent from `runner`/`registry` via small structural adapters (`SubagentAdapter`).
+
+## Design principles
+
+1. **Pi's tool shell owns state signaling.** The Box wrapper paints
+   `toolPendingBg` / `toolSuccessBg` / `toolErrorBg`, so inline blocks do not
+   repeat state words or draw their own success/error framing.
+2. **Cost is a per-run attribute, not a competing ledger.** Dollar cost appears
+   inside the run's own result block; the parent/children/combined ledger is
+   available on demand via `/subagent-cost`, in `status` tool output, and in the
+   `/subagents` overlay header. The footer never shows cost.
+3. **Fixed-height, mutate-in-place progress.** Streaming blocks keep a stable
+   shape (stats line + one `⎿ activity` line; parallel adds one line per task)
+   and the same component identity is reused across partial renders.
+4. **Trailing-edge streaming flush.** Structural updates (state transition, new
+   session id, billed turn) emit immediately; live-text bursts coalesce with a
+   deferred flush so the last update of a burst always lands.
+
+## Surfaces
+
+### Inline tool block (foreground runs)
+- `renderCall` is exactly one line: `subagent <task preview>` (or
+  `N parallel tasks — first task…`, `wait a1b2c3d4`, `… · background`).
+- `renderResult` while streaming (fixed shape, spinner animates via wall-clock
+  frame; Pi's working indicator drives repaints):
+  ```
+  ⠹ ↻3 · 12.4k tok · 8s
+    ⎿ reading src/auth/middleware.ts…
+  ```
+- Terminal single run:
+  ```
+  ↻8 · 33.8k tok · $0.012 · 12s
+    ⎿ Found 5 middleware call sites…
+    → /tmp/report.md
+  ```
+- Parallel: one line per task with a themed state glyph
+  (`◌ queued · ⠹ running · ✓ done · ✗ failed · ◐ partial · − cancelled · ◷ timeout`),
+  per-task stats, and a one-line tail (live activity or first output line).
+- Expanded (Ctrl+O / `app.tools.expand`): full task output capped with a dim
+  `… +N lines` trailer pointing at the artifact/child session.
+- Expanded detail adds one bounded route line for Jev-routed runs: selected
+  execution model, selected tools (plus locally added control-plane tools),
+  selector version, confidence, outcome and selection latency. Legacy runs
+  simply have no route line.
+- Durations freeze at `endedAt`; running durations tick at render time.
+- Reliability annotations render inline: `[attempt 2]` during a same-model
+  retry, `[stalled 2m]` while the stall watchdog is flagging silence, and
+  `◐ wrapped up` on budget-stopped runs that concluded gracefully.
+
+### Footer status
+Terse and actionable only: `⚙ 2 running · 1 ready · /subagents`. Cleared when
+nothing is running or ready. No cost — Pi's footer already shows session cost.
+
+### Ambient widget (background runs only)
+An above-editor widget renders while `async: true` runs are live — foreground
+runs already render inline as the tool result, so they never appear here
+(avoids double-render):
+
+```
+● Subagents
+├─ ⠼ Audit deps · ↻4 · 18k tok · 41s
+│   ⎿ checking license headers…
+└─ ◌ License scan · 12s
+```
+
+Cleared when the last background run settles. Spinner and elapsed animate on
+a 250ms interval that exists only while background runs are live.
+
+### Completion notifications (background runs only)
+When an async run reaches a terminal state, a `steer` message (custom type
+`subagent-completion`) is queued for the parent LLM before its next LLM call,
+so it can react without polling. The human sees a themed compact box (state
+glyph, label, stats, one-line preview, artifact pointers); the LLM sees plain
+text with run ids and a `wait { id }` pointer.
+
+- Successes within a short window batch into one message (no fanout spam);
+  failures bypass batching and flush immediately, carrying held successes.
+- A `wait` that already delivered the run suppresses the redundant
+  notification (delivered-state is re-checked at flush time).
+
+### `/subagents` overlay
+- Header: title + running/ready counters + full usage ledger + rule.
+- List: two lines per run — glyph/id/state/stats, then the task preview.
+  Selection cursor `▶`, animated spinner for live runs.
+- Detail: run stats, summary, then per-task sections (glyph, label,
+  model/selector route/profile/thinking, usage, pointers, transcript/final
+  output/errors), scrollable with ↑↓/j/k and PageUp/PageDown.
+- Actions: `c` cancel, `s` steer (prompts for a message, injects it into the
+  running child), `d` dismiss, `r` resume, `o` output pointers, `a` apply a
+  finished run's changed worktree into the main checkout (confirm dialog),
+  `x` discard worktree + branch (confirm dialog), Enter drill-down,
+  Esc/b back, Esc/q close.
+- Live transcript (`t` on a **running** run's detail): tails the child's
+  session file (`sessionDir/<…sessionId…>.jsonl`) on a 500ms poll while the
+  pane is visible — compact role/tool lines, auto-follow unless you scroll
+  up (which pauses follow). No RPC reads; hidden/finished runs never poll.
+  Missing file shows “waiting for child session…”. `s` steering still works
+  from the same pane so observe → steer stays on one surface.
+
+### `/subagent-cost`
+Prints the root/subagents/routing/combined ledger once, on demand. Routing
+tokens appear as their own category and their currency as unreported; the known
+dollar totals exclude that unreported selector spend.
+
+### Mid-run steering
+Children run in Pi RPC mode, so their stdin stays open as a command channel.
+`action: "steer"` (or `s` in the overlay) queues a message that is delivered
+after the child's current assistant turn, before its next LLM call — course
+correction without cancel + retry. Parallel runs steer one task via `index`.
+
+### Worktree loop
+Finished runs with changed worktrees support `diff` / `apply` / `discard`
+actions (tool) and `a` / `x` keys (overlay). `apply` lands the worktree's
+combined patch (committed + uncommitted + untracked vs base) onto the main
+checkout as **uncommitted working-tree changes** via `git apply --3way`; it
+never commits and never deletes the worktree. `discard` is the explicit
+cleanup step and always confirms first.
+
+### Parallel fan-in
+`synthesis: "<instruction>"` on a parallel run asks for one read-only child
+after all tasks settle that folds their outputs into a single brief, delivered
+first in the result. It is best effort and deferred: its route is selected only
+when aggregation is actually needed after the workers finish, so it never blocks
+worker launch. A selector or child failure keeps the raw worker outputs, their
+usage and a bounded `Optional synthesis blocked: …` diagnostic instead of
+discarding or re-routing them.
+
+### Plan results (tool output, not TUI)
+`action:"plan"` returns the resolved model/tools and the selector usage it
+incurred, and states that a later dispatch selects again. It starts no child and
+creates no run entry, so plan never adds an overlay row or ambient widget. A
+plan whose optional synthesis selection fails still returns the valid worker plan
+and labels only that synthetic stage blocked with its diagnostic.
+
+## States
+- **Queued/Running**: spinner + live stats + activity tail from live text.
+- **Completed/Partial/Failed/Cancelled/Timeout/Lost**: state glyph, frozen
+  duration, usage summary, output pointers; failures show the error message.
+- **Delivered vs Undelivered**: footer/overlay track pending delivery.
+- **Notification**: one per terminal transition to avoid spam.
+
+## Integration Notes
+- Extension wires via `ctx.ui.custom((tui, theme, kb, done) => createSubagentsOverlay(tui, theme, adapter, done), {overlay: true})`.
+- Adapter provides getActiveRuns/getCompletedRuns/cancelRun etc. without tight coupling.
+- Inline renderers reuse `context.lastComponent` (a `LineBlock`) so the row keeps
+  a stable component identity across partial renders.
+- Streamed tool updates separate LLM-facing `content` (compact status string)
+  from render-facing `details` (state, usage, live-text tail, run timing).
+- Tests combine pure UI models with a headless Pi extension harness: format
+  helpers, block layouts (collapsed/streaming/terminal/parallel), navigation,
+  truncation (ANSI-safe via `visibleWidth`), ready state, lifecycle/disposal.
+- Follows Pi TUI guidelines (render(width), handleInput, invalidate,
+  requestRender, dispose). The overlay owns a single animation interval.
+
+See ARCHITECTURE.md for ownership boundaries. All rendering respects terminal width and ANSI safety.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cr1ms0n/pi-subagent",
-  "version": "0.8.9",
-  "description": "Community fork of Luke Parke's pi-subagent with explicit model policy and model visibility for Pi",
+  "version": "0.9.0",
+  "description": "Community fork of Luke Parke's pi-subagent with Jev model/tool routing and verified Pi child capabilities",
   "type": "module",
   "license": "MIT",
   "author": "Luke Parke",

package/skills/subagent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent
-description: Delegate work to isolated child agents with the subagent tool — model and thinking policy, explore/review/general profiles, parallel fanout with synthesis, worktree isolation and the diff/apply/discard loop, background runs, steering, output_schema, context fork, and backend tradeoffs (pi/codex/claude). Use when delegating exploration or implementation, running tasks in parallel, or when a subagent run needs inspecting, steering, or landing.
+description: Delegate work to isolated child agents with the subagent tool. Jev routes each new dispatch to an execution model and individual tools from the user's configured candidate list; covers explore/review/general profiles, parallel fanout with best-effort synthesis, worktree isolation and the diff/apply/discard loop, background runs, steering, output_schema, context fork, and the Pi-only new-dispatch rule. Use when delegating exploration or implementation, running tasks in parallel, or when a subagent run needs inspecting, steering, or landing.
 ---
 
 # Subagent
@@ -20,24 +20,24 @@ from isolation, parallelism, or a fresh context.
 ## Core calls
 
 ```ts
-// Examples use placeholders only. Replace these with the exact model selected
-// from the current modelPolicy route; they do not configure a real model.
-const routeModel = "<exact model from current modelPolicy route>";
+// Omit model and fallback_models. Jev selects the execution model from the
+// user's configured candidate list and the individual tools from the locally
+// permitted catalog. An explicit model/fallback is rejected on new work.
 
 // Single foreground task (default profile: general)
-{ task: "Find call sites of parseConfig", description: "Map parseConfig", model: routeModel }
+{ task: "Find call sites of parseConfig", description: "Map parseConfig" }
 
 // Parallel read-only explorers (default profile for tasks[]: explore)
 {
   tasks: [
-    { task: "Map auth middleware", description: "Auth flow", model: routeModel },
-    { task: "List env vars in server/", description: "Env inventory", model: routeModel }
+    { task: "Map auth middleware", description: "Auth flow" },
+    { task: "List env vars in server/", description: "Env inventory" }
   ],
   synthesis: "Merge into one prioritized brief"
 }
 
-// Background — notified on completion; wait/status still work
-{ task: "Audit dependency licenses", model: routeModel, async: true }
+// Background: notified on completion; wait/status still work
+{ task: "Audit dependency licenses", async: true }
 { action: "status", id: "abc123" }
 { action: "wait", id: "abc123" }           // interruptible; does not cancel
 { action: "cancel", id: "abc123" }
@@ -45,69 +45,98 @@ const routeModel = "<exact model from current modelPolicy route>";
 // subagent_wait { id: "abc123", timeout_ms?: number }
 
 // Worktree loop
-{ task: "Implement feature A", model: routeModel, profile: "general", isolation: "worktree" }
+{ task: "Implement feature A", profile: "general", isolation: "worktree" }
 { action: "diff", id: "abc123", index: 1 }
 { action: "apply", id: "abc123", index: 1 }
 { action: "discard", id: "abc123", index: 1 }
 
-// Dry-run validation + resolved plan (no spawn)
-// plan is a dry-run, but every task still needs the policy-routed model.
-{ action: "plan", tasks: [{ task: "…", model: routeModel, isolation: "worktree" }] }
+// Dry-run validation + resolved plan (no spawn).
+// plan calls Jev and incurs selector fees, then a later dispatch selects again.
+{ action: "plan", tasks: [{ task: "…", isolation: "worktree" }] }
 ```
 
 ## Profiles
 
 | Profile   | Tools                                                     | Writes                                      |
 | --------- | --------------------------------------------------------- | ------------------------------------------- |
-| `explore` | read/search/ls (+safe) + Pi context tools                | no project-file writes                      |
+| `explore` | 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 if the selected tools include bash/edit/write |
+
+Jev picks individual tool names, not a capability bundle. Candidates come from
+the full available locally permitted catalog, not from agent `tools` defaults and
+not from only the parent's active tools. An explicit `tools` list is a ceiling,
+explore/review stay read-only regardless of the answer, and an empty selection
+never means "all tools".
 
 For Pi children, `new_context`, `get_context_remaining`, `history`, and
-`notes` are control-plane tools. When available in the parent they remain in
-the child allowlist—even if a narrower tool list was requested—so Pi's remote
-`contextManagement` can stay active. They may update context notes/window
-state, but never grant `bash`, `edit`, or `write` access.
+`notes` are added locally when the parent exposes them, so the selector never
+asks about them. They are control-plane tools: they may update context
+notes/window state, but never grant `bash`, `edit`, or `write` access. Route
+metadata reports them as local additions.
+
+The finalized tool subset 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; an unsupported host is
+refused rather than silently weakened.
 
 Parallel write-capable tasks sharing one checkout are rejected unless each uses
 `isolation: "worktree"`, a distinct `cwd`, or `allow_shared_writes: true`.
 
 ## Backends
 
-`backend: "pi" | "codex" | "claude"` (default `pi`). Unsupported combinations are
-**refused**, not silently degraded:
-
-|                          | pi             | codex                  | claude         |
-| ------------------------ | -------------- | ---------------------- | -------------- |
-| `max_cost`               | yes            | refused (tokens only)  | yes            |
-| read-only profile        | tool allowlist | OS sandbox             | tool allowlist |
-| steering / grace wrap-up | yes            | no                     | no             |
-| `context: "fork"`        | yes            | refused                | yes            |
-| `thinking`               | yes            | no                     | no             |
-| `output_schema`          | yes            | yes                    | yes            |
+New dispatch is Pi-only. `backend: "codex"` or `backend: "claude"` on new work
+is **refused** before any selector or provider work, including a backend
+inherited from agent frontmatter, and is never silently switched to Pi. Existing
+Codex/Claude runs remain manageable through `status`/`wait`/`cancel`/`steer`/
+`diff`/`apply`/`discard`.
+
+Another provider's execution model is still eligible through Pi when the user
+lists it in their candidate configuration. Unsupported combinations inside the
+Pi path are **refused**, not silently degraded:
+
+|                          | pi             |
+| ------------------------ | -------------- |
+| `max_cost`               | yes (provider-reported execution only; not selector currency) |
+| read-only profile        | tool allowlist |
+| steering / grace wrap-up | yes            |
+| `context: "fork"`        | yes            |
+| `thinking`               | yes            |
+| `output_schema`          | yes            |
 
 ## Budgets and safety
 
 - Prefer `max_turns`, `max_cost`, and/or `timeout_ms` on long or write-capable runs.
+  `timeout_ms` is absolute: local preflight, Jev selection, setup, queue and
+  runtime all count against it.
 - `output_schema` asks the child for a fenced `json:result` block (one repair round).
-- `context: "fork"` continues from a fork of the parent session (pi/claude).
-- Do not poll `status` in a tight loop — use `wait` / `subagent_wait`, or let the
+- `context: "fork"` continues from a fork of the parent session.
+- Do not poll `status` in a tight loop. Use `wait` / `subagent_wait`, or let the
   completion notification arrive for `async: true` runs.
 - Point the user at `/subagents` for the live inspector and `/subagent-cost` for
-  the root / subagent / combined ledger.
-
-## Model policy
-
-Every new task must pass a `model` that exactly matches the current
-`modelPolicy` mapping in `~/.pi/subagent.json`; agent frontmatter,
-`taskDefaults.model`, and parent-session model inheritance are ignored. An
-agent route replaces the default route, and configured fallback order is
-immutable. Omit `fallback_models` to use the route; if supplied, it must match
-exactly. An optional route `thinking` value is an opaque Pi thinking-level
-string; common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`,
-and `max`, but model-specific values are passed through unchanged. It is a
-default; explicit task, agent, and profile `taskDefaults.thinking` values
-override it. Management actions do not require model. The extension re-reads
-this policy on each dispatch and injects it into
-the parent prompt. If the policy is missing or invalid, management remains
-available but new spawns and synthesis are rejected.
+  the root / subagent / routing / combined ledger. Routing cost is reported as
+  unreported (tokens only, no currency).
+
+## Routing
+
+Omit `model` and `fallback_models` on every new call: both are legacy fields,
+and an explicit value is rejected rather than bypassing selection. Jev chooses
+one execution model from the user's dedicated candidate list plus an individual
+include/exclude decision per eligible tool. The local policy then re-validates
+the answer: unknown or unsafe tools cannot launch, explore/review stay read-only,
+and management actions need no routing config or credential.
+
+There are no emergency or fallback models, and low confidence is accepted rather
+than treated as a threshold. A Jev timeout or API failure stops the affected new
+dispatch with an actionable error; existing runs stay queryable and cancellable.
+Transient child failures retry the already selected model and tool set within the
+original deadline, up to `max_retries`; a quality failure never reselects.
+
+An optional candidate `thinking` value is an opaque Pi thinking-level string;
+common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and
+`max`, but model-specific values are passed through unchanged. It is a default:
+explicit task, agent, and profile `taskDefaults.thinking` values override it.
+The extension re-reads `jevRouting` on each dispatch and injects the current
+routing guidance into the parent prompt. If `jevRouting` is missing or invalid,
+or the credential environment variable is unset, management remains available but
+new spawns, `/btw`, plan, resume, fork and synthesis are rejected.