[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.
---
### 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": "",
"timeoutMs": 15000,
"models": [
{
"model": "",
"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.
---
### 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.
---
### 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.
---
### 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.
---
### 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/).