@cr1ms0n/pi-subagent 0.9.0 → 0.10.0

package/README.md

@@ -1,672 +1,130 @@
-# @cr1ms0n/pi-subagent
-
-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 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, 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
-
-Pi packages install from **npm**, **git**, or a **local path**:
-
-```bash
-# npm (scoped; surfaces on the pi.dev gallery via the pi-package keyword)
-# Note: unscoped "pi-subagent" is rejected by npm as too similar to "pi-sub-agent".
-pi install npm:@cr1ms0n/pi-subagent@0.8.1
-
-# latest npm
-pi install npm:@cr1ms0n/pi-subagent
-
-# npm is the supported package install path from the monorepo.
-# For local development, install this workspace directly:
-pi install /absolute/path/to/pi-extensions/packages/pi-subagent
-
-# local checkout
-pi install /absolute/path/to/pi-subagent
-```
-
-Then start Pi normally. The package registers:
-
-- tool: `subagent`
-- command: `/subagents` (run inspector overlay)
-- command: `/subagent-cost` (parent / subagent / combined usage on demand)
-
-This fork is published manually after pack-content and offline checks — see
-[docs/RELEASING.md](./docs/RELEASING.md).
-
-## Quick usage
-
-```ts
-// 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. Jev still picks the model.
-{ task: "Review this diff for security issues", agent: "reviewer" }
-
-// Parallel read-only explorers (default profile for tasks[]: explore).
-{
-  tasks: [
-    { task: "Map auth middleware flow", description: "Auth flow map" },
-    { task: "List all env vars used in server/", description: "Env var inventory" }
-  ]
-}
-
-// Parallel research with automatic fan-in: one read-only child folds all
-// outputs into a single brief, delivered first.
-{
-  tasks: [
-    { 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: 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
-{ action: "cancel", id: "abc123" }
-
-// Collecting a background run also has its own tool, for reflexive mid-flow
-// use. Identical semantics to action:"wait" (same handler underneath).
-// A timeout returns a still-running notice WITHOUT cancelling or consuming
-// the run, so it stays collectable.
-subagent_wait { id: "abc123" }
-subagent_wait { id: "abc123", timeout_ms: 30000 }
-
-// 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",
-  output_schema: {
-    type: "object",
-    required: ["findings", "risk"],
-    properties: {
-      findings: { type: "array", items: { type: "string" } },
-      risk: { type: "string", enum: ["low", "medium", "high"] }
-    }
-  }
-}
-
-// 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", 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", max_turns: 15, grace_turns: 2 }
-
-// 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.
-{ action: "steer", id: "abc123", message: "Skip the tests directory; focus on src/" }
-// Parallel runs: pass index to pick one live task.
-{ action: "steer", id: "abc123", index: 1, message: "Wrap up now" }
-
-// 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", profile: "general", isolation: "worktree" },
-    { task: "Implement feature B", profile: "general", isolation: "worktree" }
-  ]
-}
-
-// Close the worktree loop after the run finishes:
-{ action: "diff", id: "abc123", index: 0 }     // inspect the patch
-{ action: "apply", id: "abc123", index: 0 }    // land as uncommitted changes in your checkout
-{ action: "discard", id: "abc123", index: 1 }  // drop worktree + branch
-```
-
-The `/subagents` overlay mirrors the worktree loop interactively: `s` steer,
-`a` apply, `x` discard on the selected run.
-
-## Side questions (`/btw`)
-
-```
-/btw does this repo have a rate limiter?
-/btw                      # prompts for the question
-```
-
-`/btw` runs a one-off read-only subagent for _you_, not for the model. It uses
-the same policy, budget, semaphore and process-lock machinery as any run, but
-delivers its answer as a custom session entry, which does not participate in
-LLM context. The main agent keeps working and never sees the question or the
-answer — useful for checking something mid-task without derailing the
-conversation or polluting the context window.
-
-## Backends
-
-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
-// Refused on new work. Use the Pi-backed path so Jev can route it.
-{ task: "Summarize this module", backend: "codex", profile: "explore" }
-```
-
-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`               |
-| ------------------------------- | -------------- | ------------------------------------- | ---------------------- |
-| `max_cost`                      | yes            | **refused** (reports tokens, no cost) | yes (`total_cost_usd`) |
-| read-only profile               | tool allowlist | `--sandbox read-only` (OS-level)      | `--allowedTools`       |
-| steering / graceful wrap-up     | yes            | **no** (no stdin channel)             | **no** (one-shot)      |
-| `resume`                        | yes            | yes                                   | yes                    |
-| `context:'fork'`, `fork_resume` | yes            | **refused**                           | yes                    |
-| `thinking`                      | yes            | no                                    | no                     |
-| `output_schema`                 | yes            | yes                                   | yes                    |
-
-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.
-
-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) | locally permitted read-only tools + Pi context tools     | no project-file writes                      |
-| `review`                     | same as explore                                         | no project-file writes                      |
-| `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 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`.
-
-## Configuration
-
-Defaults can be overridden in `~/.pi/subagent.json` and per-field via env vars
-(env wins over file):
-
-| Setting                 | Env var                               | Default                               |
-| ----------------------- | ------------------------------------- | ------------------------------------- |
-| `maxTasksPerRun`        | `PI_SUBAGENT_MAX_TASKS`               | 8                                     |
-| `maxActiveProcesses`    | `PI_SUBAGENT_MAX_ACTIVE`              | 4                                     |
-| `maxQueuedTasks`        | `PI_SUBAGENT_MAX_QUEUED`              | 32                                    |
-| `maxGlobalActive`       | `PI_SUBAGENT_MAX_GLOBAL_ACTIVE`       | 16                                    |
-| `defaultTimeoutMs`      | `PI_SUBAGENT_TIMEOUT_MS`              | 900000                                |
-| `maxDepth`              | `PI_SUBAGENT_MAX_DEPTH`               | 2                                     |
-| `killGraceMs`           | `PI_SUBAGENT_KILL_GRACE_MS`           | 3000                                  |
-| `sessionDir`            | `PI_SUBAGENT_SESSION_DIR`             | `~/.pi/subagent-sessions`             |
-| `worktreeDir`           | `PI_SUBAGENT_WORKTREE_DIR`            | `~/.pi/subagent-worktrees`            |
-| `lockDir`               | `PI_SUBAGENT_LOCK_DIR`                | `~/.pi/subagent-locks`                |
-| `worktreeRetentionDays` | `PI_SUBAGENT_WORKTREE_RETENTION_DAYS` | unused (lifecycle GC)                 |
-| `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                                 |
-| `maxRetries`            | `PI_SUBAGENT_MAX_RETRIES`             | 1                                     |
-| `widget`                | `PI_SUBAGENT_WIDGET`                  | `background` (`off` disables)         |
-| `notifications`         | `PI_SUBAGENT_NOTIFICATIONS`           | `batched` (`off` disables)            |
-| (bin)                   | `PI_SUBAGENT_BIN`                     | auto (`process.execPath` + CLI entry) |
-
-### Jev routing
-
-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
-{
-  "jevRouting": {
-    "selectorModel": "jev-latest",
-    "apiKeyEnv": "TYPESAFE_API_KEY",
-    "timeoutMs": 15000,
-    "models": [
-      {
-        "model": "<provider/model-id>",
-        "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. 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
-
-Define reusable subagent personas as markdown files, discovered from the same
-conventional roots skills use (higher root wins name conflicts):
-
-| Priority | Location                                                                | Scope                       |
-| -------- | ----------------------------------------------------------------------- | --------------------------- |
-| 1        | `.pi/agents/<name>.md`                                                  | project (authoritative)     |
-| 2        | `.agents/agents/<name>.md`                                              | shared cross-tool workspace |
-| 3        | `$PI_CODING_AGENT_DIR/agents/<name>.md` (default `~/.pi/agent/agents/`) | global                      |
-
-The markdown body becomes the child's appended system prompt; frontmatter
-supplies defaults using the same snake_case names as the tool parameters:
-
-```md
----
-description: Security-focused code reviewer
-# Legacy model/fallback fields are ignored; Jev routing owns model/tool choice.
-thinking: high
-profile: review
-max_turns: 20
-spawns: false # or "*", "scout", "[reviewer, scout]"
----
-
-You are a security auditor. Review code for injection flaws, auth issues,
-and sensitive data exposure. Report findings with file:line evidence and
-severity ratings.
-
-@include shared/review-checklist.md
-```
-
-Agent files may also pin a structured contract with
-`output_schema: {"type": "object", …}` (single-line inline JSON) or
-`output_schema: @contract.json` (path relative to the agent file).
-
-`spawns:` controls which agents a child of this persona may spawn:
-`false` disables further nesting (no tool registered in that child),
-`"*"` (or omit) is unrestricted, and a comma/bracket list is an allowlist
-(agentless tasks are rejected under an allowlist). The policy is passed to
-the child via `PI_SUBAGENT_SPAWNS` and enforced on each subsequent spawn.
-
-Body lines that consist solely of `@include relative/path.md` expand that
-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" }`. 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.
-
-### Per-profile task defaults
-
-`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 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` 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`
-  when the child concluded in time. `graceTurns: 0` restores immediate stops.
-- A **stall watchdog** flags children with no protocol activity for
-  `stallAfterMs` (a liveness probe distinguishes quiet-but-thinking from dead),
-  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 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
-  parallel fanout (context duplication × N is a cost bug, not a feature).
-- **Structured output** (`output_schema`): the contract is appended to the
-  child's system prompt; the final message must end with a fenced
-  `json:result` block. Validation runs parent-side against a dependency-free
-  JSON-Schema subset (type/properties/required/items/enum/const — unknown
-  keywords are ignored, never rejected). Invalid output triggers **one
-  steer-based repair round**; still-invalid results end `partial` with
-  `structuredError` set and the raw text delivered — paid work is never
-  discarded. Validated parallel results feed the `synthesis` child as clean
-  JSON instead of prose.
-- **Arg repair**: double-encoded task text (literal `\n` / `\"` escapes from
-  LLM re-encoding) is conservatively de-mangled once at validation time.
-  Identifier fields and paths are never touched.
-  Protocol streams truncated after useful assistant output also end as `partial`.
-- Aborting a `wait` returns immediately without cancelling the background run.
-- Child processes are launched via the same Node runtime + CLI entry as the
-  parent when possible (`PI_SUBAGENT_BIN` overrides). Bare `pi` on PATH is only
-  a logged last resort.
-- Direct resume is exclusive **across processes** via durable locks under
-  `lockDir`. Lost runs block resume until startup orphan reconciliation kills
-  (or confirms dead) the recorded child process group.
-- `maxGlobalActive` bounds concurrent children across every Pi parent process
-  on the machine (in addition to the per-session semaphore).
-- Nested children at the depth ceiling do not re-register the subagent tool;
-  only top-level parents run maintenance/orphan reclaim/worktree GC.
-- Preserved worktrees live under `worktreeDir` (durable, not `/tmp`) and are
-  garbage-collected on startup by **lifecycle**, not wall-clock retention: once
-  a run is over (not live, past a 1h concurrency race guard), the worktree's
-  unique work is archived as one applyable patch under
-  `<repo-container>/_patches/` and the directory is reclaimed immediately.
-  Branches holding commits that exist on no other ref are never deleted.
-  `diff`/`apply`/`discard` transparently fall back to the archived patch when
-  the directory is already gone. Live runs are never swept: the current
-  session's live worktrees plus any worktree recorded on a running run record
-  (concurrent Pi processes) are shielded machine-wide.
-- Startup GC sweeps **every** repo container under `worktreeDir`, not just the
-  current checkout's, so repos you stop visiting are still reclaimed. A
-  container whose base repo no longer exists is kept and reported, never
-  deleted — its worktrees' object stores lived inside the deleted repo, so
-  unique work cannot be distinguished from a pristine checkout, let alone
-  archived. Empty containers (no worktrees, no archived patches) are removed.
-- Child session transcripts are likewise distilled on lifecycle: when a run is
-  over and nothing on the parent branch references its session, the transcript
-  is reduced to a small `.digest.json` (task, final output, model, usage,
-  turn/tool/error counts) and the raw `.jsonl` is deleted. Resume needs the
-  transcript, so anything referenced or busy machine-wide is kept.
-- `keep_background: true` on a task keeps processes the child intentionally
-  backgrounded (e.g. dev servers) alive after a clean exit.
-- `include_wip: true` (with `isolation: "worktree"`) seeds the worktree with the
-  parent checkout's uncommitted changes so the child sees your dirty baseline.
-  `diff`/`apply` subtract that baseline when clean, else report the combined
-  delta with an explicit `[includes parent WIP]` warning.
-
-## Using the runner as a library
-
-Import the stable public SDK from the package root or the explicit `/sdk`
-subpath — do not reach into `src/*` internals (those paths are not part of the
-supported contract):
-
-```ts
-import {
-  runTasks,
-  runSubagent,
-  ChildRunner,
-  WorktreeManager,
-  Semaphore,
-  ProcessLockManager,
-  addUsage,
-  normalizeUsage,
-  emptyUsage,
-  type TaskSpec,
-  type TaskResult,
-  type RunState,
-  type UsageStats,
-} 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 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 task: TaskSpec = {
-  task: "Audit src/ for unsafe parsing",
-  profile: "explore",
-  model: "<provider/model-id resolved by your embedding code>",
-  timeoutMs: 10 * 60_000,
-};
-```
-
-Prefer `runTasks()` for multi-task / worktree orchestration (same path the
-extension and pi-workflows use). `runSubagent()` runs a single child process
-directly without the extension host, but durable coordination is **opt-in**.
-Pass both `locks` (a `ProcessLockManager`) and a stable `runId` if you want
-global concurrency slots and orphan reclaim to see the child. Without those
-options no durable run record is written, so a parent restart cannot reclassify
-the process and nested children vanish from reconcile. There is intentionally
-no implicit default lock manager — embedding code that needs durability must
-construct and share one.
-
-The Pi extension entry is unchanged: package `pi.extensions` still points at
-`./extensions/subagent.ts`.
-
-## Design invariants
-
-1. A run belongs to one parent session and cannot update another session.
-2. Per-session + machine-wide process caps and nesting depth limits prevent process storms.
-3. Cancellation prevents queued tasks from spawning.
-4. Direct resume of a child session is exclusive **across processes** via durable locks.
-5. Tool responses are capped to ~50KB/2000 lines; full output lives in
-   artifacts and `~/.pi/subagent-sessions`.
-6. Status is compact; wait is the one-shot deliverable.
-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;
-   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 (@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, 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)
-  semaphore.ts     # per-session concurrency limit
-  registry.ts      # session-scoped run state + durable resume locks
-  persistence.ts   # parent-session event folding
-  usage.ts         # root/subagent/combined usage ledger
-  output.ts        # exact global output caps
-  notifications.ts # batched background-run completion notifications
-  format.ts / ui.ts# renderers, ambient widget, /subagents overlay
-```
-
-## 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 pack --dry-run --json
-```
-
-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
-
-`status`, `/subagent-cost`, and the `/subagents` overlay header show separate
-**root**, **subagent**, and **combined** totals based on provider-reported
-usage. On Pi builds after v0.80.10, delivered runs also report their total
-usage natively on the tool result
-([pi#6671](https://github.com/earendil-works/pi/pull/6671)), so Pi's own
-footer, `/session`, and RPC totals include subagent spend — exactly once per
-run; older Pi hosts ignore the field. Nested usage reported by a child's tool
-results (e.g. grandchild subagents) folds into the run's totals and budgets.
-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,
-live transcripts — lives in [docs/ROADMAP.md](./docs/ROADMAP.md) (rationale
-and design sketches) and [docs/PLAN.md](./docs/PLAN.md) (execution contract:
-work breakdown, acceptance criteria, test plans, and release gates per phase).
-
-## Security
-
-See [docs/SECURITY.md](./docs/SECURITY.md). Pi packages run with full system
-access—review source before installing third-party packages.
-
-## Status
-
-v0.1 focuses on the correct lifecycle engine:
-
-- process + session ownership
-- budgets, caps, profiles
-- persistence + inspector
-- worktree isolation helpers
-
-Named agent catalogs and automatic chain workflows are intentionally deferred
-until the core is battle-tested.
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+# Pi Smart Subagents
+
+Run isolated child agents in [Pi](https://pi.dev/), with Jev selecting an execution model and individual tools for each task.
+
+Published on npm as `@cr1ms0n/pi-subagent`. This is an independent community fork of Luke Parke's `@parke.dev/pi-subagent` 0.8.0 from [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent), not an official upstream release. The original MIT license and copyright are preserved.
+
+The upstream extension provides the child-process engine, named agents, background tasks, worktrees and usage accounting. This fork adds mandatory Jev model/tool selection and verifies the child's selected capabilities before sending it the task.
+
+---
+
+<a id="quick-start"></a>
+### Install and quick start
+
+Use Node.js 22.19.0 or newer and an installed Pi CLI with a working model provider. Pi 0.86.0 is the verified host baseline for enforcing built-in, extension and late-registered tool allowlists. A host that cannot verify the selected capabilities is refused rather than granted more tools.
+
+**1. Install the published package.**
+
+Install the exact `0.10.0` release. The earlier `0.9.0` release uses the older `apiKeyEnv` configuration contract and does not accept `apiKey`:
+
+```bash
+pi install npm:@cr1ms0n/pi-subagent@0.10.0
+```
+
+Pi loads the package directly. Do not enable another copy of this extension or `@parke.dev/pi-subagent` together with it: they register the same tools. The package provides `subagent`, `subagent_wait`, `/subagents`, `/subagent-cost` and `/btw`.
+
+**2. Store your TypeSafe credential in private configuration.**
+
+Set `jevRouting.apiKey` in your user-level `~/.pi/subagent.json`, as shown below. If you are upgrading from `0.9.0`, move the existing value from `jevRouting.apiKeyEnv` to `jevRouting.apiKey` and remove the old field before starting new dispatches. Do not paste the key into chat or repository files. The file stores the key in plaintext: restrict file access and protect backups. See [credential setup](docs/REFERENCE.md#credential-setup) for migration and security details. Provider authentication for the child models is configured separately in Pi.
+
+**3. Configure your candidate models.**
+
+Add this block to `~/.pi/subagent.json`, preserving unrelated settings. Replace the example model ID with an exact `provider/model-id` available in your Pi installation and write your own model characteristics. Remove any legacy `modelPolicy` block; it is not migrated automatically.
+
+```json
+{
+  "jevRouting": {
+    "selectorModel": "jev-latest",
+    "apiKey": "<your-typesafe-api-key>",
+    "timeoutMs": 15000,
+    "models": [
+      {
+        "model": "<provider/model-id>",
+        "description": "Describe this model's strengths and the tasks you want it to handle."
+      }
+    ]
+  }
+}
+```
+
+Replace the `apiKey` placeholder with your TypeSafe key and remove any old `apiKeyEnv` field. There is no environment fallback or automatic migration. Candidate descriptions may be written in Chinese. See the [configuration reference](docs/REFERENCE.md#configuration) for optional thinking defaults, profile defaults and limits.
+
+Jev selection can incur TypeSafe charges. It receives the delegated task text, model IDs/descriptions, candidate tool names/descriptions and required constraints. It does not automatically upload repository files or conversation history; text you include in the task can still disclose sensitive information. `action: "plan"` also calls Jev, and a later execution selects again.
+
+**4. Start Pi and delegate a read-only task.**
+
+Start Pi, or reload/restart it after switching extension code. Once `0.10.0` is loaded, each new dispatch re-reads the configuration; changing `apiKey` does not require a shell environment update.
+
+```bash
+pi
+```
+
+Ask the parent agent to use `subagent` with a request such as:
+
+```json
+{
+  "task": "Read README.md and summarize what this package does.",
+  "description": "Summarize the README",
+  "profile": "explore",
+  "tools": ["read"],
+  "max_turns": 4,
+  "timeout_ms": 120000,
+  "max_retries": 0
+}
+```
+
+Omit `model` and `fallback_models`. Jev chooses from your configured model list and permitted tools; a routing failure stops the new dispatch without a fallback. Existing-run management remains available without a routing credential.
+
+---
+
+<a id="delegation"></a>
+### Delegation
+
+- **Model and tool routing:** this fork asks Jev to match each task to your model descriptions and select tools individually. Local permission checks and child startup verification enforce the result.
+- **Named agents and parallel work:** the upstream engine supports reusable personas and concurrent child processes. This fork routes each new child through Jev; agent files do not pin its model or tool selection.
+- **Background tasks:** the upstream engine supports status, interruptible waiting, cancellation and steering. The fork's display includes the selected model, with tool details in expanded results.
+- **Isolated edits:** the upstream worktree flow lets you inspect, apply or discard changes without sharing one writable checkout between parallel agents.
+- **Structured results and budgets:** the upstream engine validates structured output parent-side and preserves partial work. This fork keeps retries on the selected model/tool set and accounts for selector tokens separately.
+
+For a background task, set `async: true`, then collect it using `subagent_wait` or `action: "wait"`. Aborting or timing out a wait does not cancel the child. Use `action: "cancel"` to stop it. Open `/subagents` to inspect runs and `/subagent-cost` to see usage.
+
+The [reference](docs/REFERENCE.md#quick-usage) includes parallel work, synthesis, resume/fork, structured output, budgets and the worktree diff/apply/discard loop. The [TUI guide](docs/UX.md) describes the inspector and keyboard controls.
+
+---
+
+<a id="permissions-and-costs"></a>
+### Permissions and costs
+
+| Profile | Tool selection | Project-file writes |
+| --- | --- | --- |
+| `explore` | Jev-selected locally permitted read-only tools plus available Pi context controls | No |
+| `review` | Same read-only policy | No |
+| `general` | Jev-selected locally permitted tools plus available Pi context controls | Possible with selected write-capable tools |
+
+Single tasks default to `general`; parallel tasks default to `explore`. An explicit `tools` list is a ceiling. Available Pi context-management controls are added locally even with `tools: []`. An empty tool selection never means all tools.
+
+Profiles are tool-selection policy, not an OS sandbox. Children inherit the parent environment and can read files accessible to the same user, including the private config. Worktrees isolate the checkout only. Review the [security model](docs/SECURITY.md) before delegating untrusted work.
+
+The ledger separates root, subagent, routing and combined usage. TypeSafe reports routing tokens, not currency, so selector cost is **unreported**, not free. `max_cost` limits provider-reported child execution cost; it does not cap TypeSafe fees. See [cost accounting](docs/COST-ACCOUNTING.md) for delivery, retry and branch semantics.
+
+New extension-managed dispatch supports the Pi backend only. Native Codex/Claude requests are rejected. The [low-level SDK](docs/REFERENCE.md#using-the-runner-as-a-library) is a separate explicit-spec API: it does not automatically call Jev, and embedding code owns its model/tool choices.
+
+---
+
+<a id="development"></a>
+### Development
+
+The source is a standalone TypeScript package with peer dependencies, no build step and no bundled test runner or typecheck script. Follow [development and verification](docs/DEVELOPMENT.md) for the checks this checkout supports. A syntax transform is not a semantic typecheck, and `npm pack --dry-run --ignore-scripts --json` verifies package contents without publishing.
+
+The [architecture contract](docs/ARCHITECTURE.md) documents ownership and invariants. [Release maintenance](docs/RELEASING.md) covers selective source updates and the separate, explicitly authorized npm publication process.
+
+---
+
+<a id="license"></a>
+### License
+
+[MIT](LICENSE). Copyright (c) 2026 Luke Parke. Fork maintained by cr1ms0n (awoaCrim). Preserve the original copyright and license when redistributing this work.
+
+Thanks to [Linux.do](https://linux.do/).