English | 简体中文

Pi Smart Subagents

Run isolated child agents in Pi, 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, 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:

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

{
  "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 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.

pi

Ask the parent agent to use subagent with a request such as:

{
  "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 includes parallel work, synthesis, resume/fork, structured output, budgets and the worktree diff/apply/discard loop. The TUI guide 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 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 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 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 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 documents ownership and invariants. Release maintenance covers selective source updates and the separate, explicitly authorized npm publication process.

---

License

MIT. Copyright (c) 2026 Luke Parke. Fork maintained by cr1ms0n (awoaCrim). Preserve the original copyright and license when redistributing this work.

Thanks to Linux.do.