specpi-delegation

Bounded in-house subagents for Pi: child sessions read a frozen source snapshot and report back under fixed call, token and time ceilings

Packages

Package details

extension

Install specpi-delegation from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:specpi-delegation
Package
specpi-delegation
Version
0.2.0
Published
Sep 16, 2026
Downloads
2,223/mo · 210/wk
Author
tannermidd
License
MIT
Types
extension
Size
173.3 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

specpi-delegation

Bounded in-house subagents for Pi. The agent hands a question to a real Pi child session that can read a frozen copy of selected sources and nothing else, then reports back under fixed call, token and time ceilings.

This is the first-party replacement for third-party subagent packages in SpecPi's default base. It trades breadth for a boundary you can state in one sentence: a child can read what you selected, when you selected it, and can do nothing else.

Install

pi package add npm:specpi-delegation@0.2.0

Pi supplies every runtime import. The package has no production dependencies.

Use

Delegation ships off. Its tool schema is about 4.4 KB, and Pi sends every active tool's schema on every request of a session, so it is not offered until you ask for it:

/delegate on            # this session
/delegate startup on    # and every new session, saved

While it is on, the agent has a delegate tool with two job modes:

  • review — check finished artifacts against assigned requirements in fresh context, with no memory of how the work was argued for.
  • scout — answer one distinct evidence question over selected sources.

run returns immediately and collect waits, so the parent can keep working while children run. A child's result is advisory evidence, not a verification: it never grants permission and never proves a task is complete.

Command

Command Effect
/delegate on / off Turn delegation on or off for this session
/delegate startup [on|off] Whether new sessions start with it on; ships off, saved across restarts
/delegate status Current posture, model, guard state and session counters
/delegate limits The ceilings currently in force
/delegate budget <1–64> Save a session budget multiplier (default 8); reset restores it
/delegate timeout <1–60> Save a per-job timeout in minutes (default 10); reset restores it
/delegate cancel <id> Cancel a running job or batch

Saved budget and timeout live in <pi-agent-dir>/specpi/delegation/settings.json.

What a child can do

Exactly three tools, against a snapshot taken when the batch starts:

  • list_sources — page through the selected sources
  • read_source — read numbered lines from one selected source
  • search_sources — search within the selection

No shell, no edits, no network, no nested delegation, and no access to any tool the parent registered. A path outside the selection is refused.

Ceilings

Local settings may lower these and never raise them:

Limit Value
Concurrent jobs 2
Jobs per batch 2
Request packet 256 KiB
Result per job 16 KiB
Snapshot 200 files / 8 MiB
Response page 16 KiB
Job timeout 10 minutes (configurable 1–60)
Session budget 8× (configurable 1–64)

Boundaries worth knowing

Child sessions are a capability restriction, not an OS sandbox — they run as the same user in the same process tree. A delegated result is model-generated text and carries no prompt-injection defense; treat it as untrusted input. Changing model, provider, thinking level or working directory invalidates an active grant rather than carrying it forward silently.

SECURITY.md states the full boundary.

License

MIT