[English](README.md) | [简体中文](README.zh-CN.md)

# Pi Smart Subagents

Run isolated child agents and managed shell commands in [Pi](https://pi.dev/). Jev chooses subagent models; ordinary command tasks use your existing `bash` tool without model selection.

An independent community fork of Luke Parke's `@parke.dev/pi-subagent` from [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent). It retains named agents, parallel and background tasks, worktree isolation and usage accounting, and adds Jev model routing with child capability checks.

<a id="quick-start"></a>
## Installation

Requires Node.js 22.19.0 or newer and Pi. Do not enable this fork and `@parke.dev/pi-subagent` together: both register the same tools.

```bash
pi install npm:@cr1ms0n/pi-subagent
```

Before your first **subagent** task, configure your TypeSafe API key and candidate models in `~/.pi/subagent.json`. See the [configuration example](docs/REFERENCE.md#jev-routing); keep credentials private and merge changes into any existing configuration.

The separate `task` tool needs Pi 1.2.0+ with a callable `bash`, not Jev configuration. Both extension entries ship in the package and can also be loaded independently.

## Command tasks

Use `task` for a non-interactive build, command or script in the current directory:

```json
{ "command": "npm run build" }
```

It waits up to 30 seconds by default, then returns the same task ID while that one command continues in the background. Set `"background": true` to return a receipt immediately, or use `timeout_ms` to change this call's wait. Native `bash.timeout` keeps its existing hard-stop meaning.

Keep the full task ID for `list`, `status`, `output`, `wait` and `cancel`. Logs remain under the configured session directory; output reads use repeatable UTF-8 byte cursors. Background completion notifies the owning session unless notifications are disabled. Exit, reload and branch/session replacement request cancellation; tasks are not persistent daemons. See [command task examples and limits](docs/REFERENCE.md#managed-shell-tasks).

<a id="delegation"></a>
## Subagent usage

Ask Pi, for example:

> Use a read-only subagent to review this project's directory structure and summarize the main modules.

Jev selects the model, not individual tools. Local policy controls the permitted tool set, and startup checks which capabilities are available in the child. An explicitly requested tool must be available. See the [tool policy and routing reference](docs/REFERENCE.md#jev-routing) for details.

The default **compact** mode keeps ordinary delegation, parallel/background tasks, budgets and worktree management. For advanced request controls such as resume, synthesis and structured output, merge this field into `~/.pi/subagent.json`, then reload or restart Pi after active tasks finish:

```json
{ "toolMode": "full" }
```

See [tool modes](docs/REFERENCE.md#tool-modes) for the field split and upgrade behavior.

Subagent `timeout_ms` is a reminder, not a stop limit. At the threshold, a foreground call returns the run ID and the same work continues in the background. Use `status`, `wait`, `steer` or `cancel` to decide what happens next. Existing time settings now have this advisory meaning; turn/cost budgets and independent fault checks remain. See [budgets and retries](docs/REFERENCE.md#budgets-and-retries).

Every child launched by this package automatically receives a package-owned mandatory rule: it must not run tests or test commands, and it must not create or modify test code. Delegated children implement changes and review statically and report untested work; executable testing belongs only to the TOP-LEVEL main agent, never to a delegated child, so an intermediate delegating child owns no tests either. Logs and backups remain allowed within the existing task scope and tool permissions. This is a prompt-level instruction, not a sandbox, and it applies to new launches after the updated package is loaded, not to already-running children or independently launched/custom-backend processes. See [delegated testing](docs/REFERENCE.md#delegated-testing-boundary).

- Open `/subagents` to inspect and manage subagent runs.
- Open `/subagent-cost` to view usage.
- See the [usage reference](docs/REFERENCE.md#quick-usage) for named agents, parallel tasks, background work, worktrees and structured results, or the [TUI guide](docs/UX.md) for keyboard controls.

Model execution and Jev selection may incur separate charges. Planning also invokes Jev; `max_cost` does not cap TypeSafe selector charges. See [cost accounting](docs/COST-ACCOUNTING.md).

Routing sends task text and candidate-model information to the selector. Set `jevRouting.baseUrl` only to a trusted endpoint, since it changes the recipient of routing data and the routing credential. See the [security guide](docs/SECURITY.md).

<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/).