@cr1ms0n/pi-subagent 0.8.9 → 0.10.0

package/README.md

@@ -1,569 +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 requires a user-owned `modelPolicy` in `~/.pi/subagent.json` before new subagent tasks can run, and displays actual models in the TUI.
-
-Production-grade isolated subagents for [Pi](https://github.com/badlogic/pi-mono).
-
-Delegate research, parallel exploration, and clean-context review to child Pi
-processes. Named agent personas, cancellable background runs with completion
-notifications and a live widget, mid-run steering, graceful budget wrap-ups,
-automatic retry with model fallback, a stall watchdog, session resume and
-context forking, worktree isolation with a diff/apply/discard loop, capability
-profiles, a root/subagent/combined cost ledger, and a TUI inspector.
-
-## 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; `model` must exactly match ~/.pi/subagent.json modelPolicy.
-{ task: "Find all call sites of parseConfig and summarize patterns.", description: "Map parseConfig usage", model: "<provider/model-id>" }
-
-// Named agent — persona prompt from .pi/agents/reviewer.md; model still comes from modelPolicy.
-{ task: "Review this diff for security issues", agent: "reviewer", model: "<provider/model-id>" }
-
-// Parallel read-only explorers (default profile: explore); each task needs its mapped model.
-{
-  tasks: [
-    { task: "Map auth middleware flow", description: "Auth flow map", model: "<provider/model-id>" },
-    { task: "List all env vars used in server/", description: "Env var inventory", model: "<provider/model-id>" }
-  ]
-}
-
-// 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", model: "<exact model from current modelPolicy route>" },
-    { task: "Audit frontend error handling", description: "Frontend audit", model: "<exact model from current modelPolicy route>" }
-  ],
-  synthesis: "Merge both audits into one prioritized findings list"
-}
-
-// Background run — model is still required; the live widget shows the actual model
-// and changes when a configured fallback is selected.
-{ task: "Audit dependency licenses", model: "<provider/model-id>", async: true }
-// 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 + preflights (git repo, fork
-// session, output paths), returns the resolved per-task plan (model, tools,
-// budgets, isolation) without spawning anything.
-{ action: "plan", tasks: [{ task: "Implement feature A", model: "<exact model from current modelPolicy route>", isolation: "worktree" }] }
-
-// Structured output: the child must end with a fenced json:result block
-// matching the schema. Invalid output gets one automatic repair round;
-// delivery is the clean JSON and details carry the parsed object.
-{
-  task: "Audit the auth module",
-  model: "<exact model from current modelPolicy route>",
-  output_schema: {
-    type: "object",
-    required: ["findings", "risk"],
-    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", model: "<exact model from current modelPolicy route>", context: "fork", profile: "general" }
-
-// Budgets with graceful wrap-up: at the limit the child is steered to produce
-// a final answer and given grace turns before any hard stop.
-{ task: "Audit deps", model: "<exact model from current modelPolicy route>", max_turns: 15, grace_turns: 2 }
-
-// Automatic retry uses the configured fallback order. If fallback_models is
-// supplied, it must exactly match modelPolicy; otherwise omit it.
-{ task: "Research X", model: "<provider/model-id>", max_retries: 1 }
-
-// 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
-{ task: "Continue from your findings and propose a fix plan", model: "<exact model from current modelPolicy route>", resume: "<session-id>" }
-
-// Isolated writers
-{
-  tasks: [
-    { task: "Implement feature A", model: "<exact model from current modelPolicy route>", profile: "general", isolation: "worktree" },
-    { task: "Implement feature B", model: "<exact model from current modelPolicy route>", profile: "general", isolation: "worktree" }
-  ]
-}
-
-// 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
-
-Children can run on a different agent CLI. Everything else — worktrees, process
-locks, depth limits, budgets, orphan reclaim — is backend-agnostic and applies
-unchanged.
-
-```ts
-{ task: "Summarize this module", model: "<exact model from current modelPolicy route>", backend: "codex", profile: "explore" }
-{ task: "Review this diff",      model: "<exact model from current modelPolicy route>", backend: "claude", max_cost: 0.50 }
-```
-
-Requires the corresponding CLI on PATH (`codex`, `claude`). Capabilities differ,
-and **unsupported combinations are refused with an explanation rather than
-silently ignored** — a dropped `max_cost` or unenforced read-only profile would
-be a safety regression, not a minor degradation.
-
-|                                 | `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.
-
-Set a persona's backend in agent frontmatter with `backend: codex`.
-
-## Profiles
-
-| Profile                      | Tools                                                   | Writes                                      |
-| ---------------------------- | ------------------------------------------------------- | ------------------------------------------- |
-| `explore` (parallel default) | read/grep/find/ls + safe extras + 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        |
-
-For the Pi backend, the context-management tools `new_context`,
-`get_context_remaining`, `history`, and `notes` are retained in child tool
-allowlists when the parent exposes them. They are control-plane tools: they may
-update continuity notes or the remote context window, but cannot modify the
-child checkout or run a shell command. This exception also applies when a task
-supplies a narrower tool list, so Pi's `contextManagement` remains usable for
-configured gateway models.
-
-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                                  |
-| `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) |
-
-### Model policy
-
-New spawns are routed only by the user-owned `modelPolicy` in `~/.pi/subagent.json`.
-Agent frontmatter, `taskDefaults`, parent-session model inheritance, and ad-hoc
-fallback lists are ignored for model selection. The minimal template is:
-
-```json
-{
-  "modelPolicy": {
-    "default": {
-      "model": "<provider/model-id>",
-      "fallbackModels": [],
-      "thinking": "medium"
-    },
-    "agents": {
-      "<agent-name>": {
-        "model": "<provider/model-id>",
-        "fallbackModels": [],
-        "thinking": "high"
-      }
-    }
-  }
-}
-```
-
-`thinking` is optional and is an opaque Pi thinking-level string. Common values
-include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`, but the
-package does not remap or restrict model-specific values. Pi receives the value
-unchanged and decides whether the active model supports it. It is a route default,
-not a strict policy value. Resolution order is: explicit task `thinking` > agent
-frontmatter `thinking` > profile `taskDefaults.<profile>.thinking` > the selected
-`modelPolicy` route's `thinking` > the parent session's thinking level. Omitting it
-preserves the existing behavior.
-
-Every new `task`/`tasks[]` item must pass the exact mapped `model`. Omit
-`fallback_models` to use the configured list; when supplied it must match the
-configured order exactly. Management actions remain available when this file is
-missing, but new spawns and synthesis are rejected until it is valid. The
-extension re-reads the policy on each dispatch and injects the current mapping
-into the parent prompt. No provider catalog or credentials are read.
-
-This guarantee applies to the Extension tool dispatch and its internal synthesis
-handoff. The stable SDK exports (`runTasks` and `runSubagent`) are trusted
-low-level library APIs and intentionally do not load the Extension's
-`modelPolicy`; library callers must parse and validate their own policy before
-passing `TaskSpec` values. Do not treat direct SDK calls as policy enforcement.
-
-### 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; use modelPolicy instead.
-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", model: "<provider/model-id>" }`.
-The agent file supplies persona/capability defaults only; its legacy
-`model`/`fallback_models` fields are ignored. An explicit `system_prompt`
-appends after the persona body.
-Profiles still enforce capability: an agent declaring `profile: review` with
-write tools fails closed. The agent catalog is advertised in the tool's
-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 routing belongs only to
-`modelPolicy`. A profile `thinking` value overrides the selected route default.
-Invalid fields are dropped field-by-field.
-
-Notes on behavior:
-
-- `timeout_ms` covers queue time plus runtime, but timed-out tasks report
-  `state: "timeout"` with `timeoutPhase: "queued"|"starting"|"running"` so
-  agents can retry capacity issues without confusing them for task failures.
-- 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, escalating
-  through `fallback_models` when provided. Usage accumulates across attempts;
-  results record `attempts` and `attemptedModels`. Task-quality failures
-  (nonzero exit with complete protocol, cancellations, budget stops, running
-  timeouts) never retry.
-- `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 "@parke.dev/pi-subagent/sdk";
-```
-
-The package root is an alias for the same SDK:
-`import { runTasks } from "@cr1ms0n/pi-subagent"`.
-
-The Extension dispatch path requires `model` to be the exact value from the
-current `modelPolicy` route. This placeholder is illustrative only and does not
-write or select a real configuration:
-
-```ts
-const routeModel = "<exact model from current modelPolicy route>";
-const task: TaskSpec = {
-  task: "Audit src/ for unsafe parsing",
-  profile: "explore",
-  model: routeModel,
-  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.
-10. Protocol completion prefers `agent_settled` (falls back to non-retrying `agent_end`).
-
-## Layout
-
-```
-src/
-  index.ts         # stable public SDK entry (@parke.dev/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
-  agents.ts        # named agent files (.pi/agents/, .agents/agents/, global)
-  launch.ts        # resolve child pi via execPath / PI_SUBAGENT_BIN
-  process-lock.ts  # durable session locks, global slots, orphan records
-  worktree.ts      # git worktree isolation + diff/apply/discard
-  orchestrator.ts  # multi-task execution, transient retry + model fallback
-  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
-
-```bash
-npm install
-npm run typecheck
-npm test
-npm run pack:check
-```
-
-Tests use a deterministic `fake-pi` child. No live model calls are required.
-
-## 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).
-
-## 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/).