@cr1ms0n/pi-subagent 0.8.9 → 0.10.0

package/docs/SECURITY.md

@@ -6,11 +6,11 @@ and can use tools according to their capability profile.
 
 ## What subagents can do
 
-| Profile | Default tools | Writes? |
-|---------|---------------|---------|
-| `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 |
+| Profile | Finalized tools | Writes? |
+|---------|-----------------|---------|
+| `explore` | Jev-chosen subset of locally permitted read-only candidates, plus available Pi context tools | No project-file writes |
+| `review` | Same as explore | No project-file writes |
+| `general` | Jev-chosen subset of the full available locally permitted catalog, plus available Pi context tools | Yes if write-capable tools are selected |
 
 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
@@ -41,22 +50,47 @@ Parallel mode defaults to `explore` to avoid concurrent shared writes.
    (RPC mode). Extension UI dialogs raised inside a child are auto-cancelled so
    they can never hang a run — which also means a child can never obtain
    interactive consent. Prefer restricted tools for async/background runs.
-11. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
-    into a running child's conversation with user-level authority. Anything that
-    can call the subagent tool can steer any live run in the same session.
-7. **Process cleanup.** On POSIX, children run in their own process group so tree
+7. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
+   into a running child's conversation with user-level authority. Anything that
+   can call the subagent tool can steer any live run in the same session.
+8. **Process cleanup.** On POSIX, children run in their own process group so tree
    kills work for ordinary descendants. Parent (re)start reaps orphans recorded
    under `~/.pi/subagent-locks/runs/` so resume cannot race a still-alive writer.
    Grandchildren that call `setsid()` can still escape a simple process-group kill.
-8. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
+9. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
    concurrent parents cannot append to the same child session.
-9. **Profiles are tool-selection policy, not a sandbox.** Children inherit
+10. **Profiles are tool-selection policy, not a sandbox.** Children inherit
    `$HOME`, SSH/cloud credentials, network access, and the parent filesystem.
    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.
+11. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
+    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.
+
+Version `0.10.0` reads the TypeSafe credential from `jevRouting.apiKey` in the private user-level `~/.pi/subagent.json`. This is plaintext storage: restrict file access and protect editor backups and synchronized copies. Same-user processes, including children with filesystem access, may read it. Profiles and worktrees do not protect this file from those processes.
+
+The transport sends the key only as an `Authorization` header to the fixed official HTTPS endpoint, with redirects disabled. It does not automatically copy the key into prompts, selector JSON bodies, argv, child manifests, logs, receipts or results. Never serialize or log the complete routing configuration. Rotate any credential pasted into a transcript or shared in conversation.
+
+Published npm `0.9.0` uses the older environment-based mechanism. In `0.10.0`, `apiKeyEnv` is rejected with manual migration guidance and no environment fallback. Unrelated `PI_SUBAGENT_*` runtime settings remain supported.
+
+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 +106,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

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.10.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",
@@ -10,6 +10,13 @@
     "cr1ms0n (fork maintainer)"
   ],
   "homepage": "https://www.npmjs.com/package/@cr1ms0n/pi-subagent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awoaCrim/pi-smart-subagents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/awoaCrim/pi-smart-subagents/issues"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -31,6 +38,7 @@
     "skills",
     "docs",
     "README.md",
+    "README.zh-CN.md",
     "CHANGELOG.md",
     "LICENSE"
   ],