pi-delegate

One Pi tool: delegate.

Give Pi a clean side thread. delegate starts a fresh child agent, gives it a task, then brings back only the useful result. No child transcript. No scratchpad spill. No context mud.

Small by design: no workflow engine, background job manager, dashboard, or artifact system. One tool. One job. Keep the main context clean.

Install

pi install npm:pi-delegate

What it adds

pi-delegate adds the delegate tool.

The tool runs a fresh in-memory child Pi agent in the current project, waits for the task to finish, and returns:

• the child’s concise final report
• model/effort metadata
• duration
• child tool/error counts
• child turn/token/cost usage when the provider reports usage
• output truncation metadata when the final report is large
• native tool errors with concise failure metadata when delegation fails

The main agent never sees the child’s intermediate exploration.

Tool API

delegate

Parameters:

• task: the task for the child agent
• effort: optional fast | thorough — default fast

The child uses the active parent model by default. effort only selects the requested thinking level:

| effort | thinking | | --- | --- | | fast | low | | thorough | high |

Choose fast for ordinary delegated work, including scouting, research, review, and deterministic debugging. Use thorough only when the user explicitly requests that effort tier, a fast result demonstrates reasoning-limited uncertainty, or an error would be costly and difficult to detect, correct, or rerun. Task category, scope, ambiguity, and requests for “thorough” work do not qualify by themselves. Escalation is a separate parent-owned delegate call.

Model availability, authentication, and thinking-level compatibility follow the parent Pi session and Pi's normal model handling. Speed and cost are relative to the same inherited model; this package makes no cross-provider performance guarantees.

Migration from 0.4

Version 0.5 removes balanced and smart without aliases. Reclassify existing calls: use fast for old balanced calls by default, and retain high reasoning as thorough only where the stricter criteria above apply.

Behavior

• fresh in-memory child session
• parent cwd
• project context files loaded through Pi's normal resource discovery
• extensions and package resources discovered from the child session's cwd/agent directory are loaded; ad-hoc extension paths listed in PI_CHILD_EXTENSION_PATHS are also loaded in the child
• recursive delegation tools are disabled inside the child
• parallel execution, so multiple delegate calls in one agent turn can run concurrently
• 15-minute internal timeout
• running calls render as neutral progress, not failure; the tool header stays compact, while the result area shows the assigned task in a boxed card
• collapsed task cards show the first four non-empty task lines with a hidden-line hint; expanded tool output shows the full assigned task
• completed calls include a bounded child-report preview when collapsed and the full child report when expanded; if the parent-facing tool content was truncated, expanded TUI reads the saved full-output file when available
• parent-facing delegation policy is tool-owned through the active delegate tool description, snippet, guidelines, and parameter descriptions; the package does not append a separate parent system prompt
• child final reports are prompted as handoff-ready summaries with task, result, evidence, files, verification, and only-important handoff notes
• failures throw native Pi tool errors with a concise reason plus model/duration/tool-count metadata
• final child output is truncated at Pi's standard 2000-line/50KB tool-output limits, with the full report saved to a temp file when truncation occurs
• normal Pi tools are available to the child, including write-capable tools; parent agents should keep implementation/final validation in the parent by default and delegate write-capable child tasks only when explicit or exceptional; callers are responsible for avoiding conflicting concurrent delegated writes

Package shape

The npm package is both a Pi package and a small TypeScript module. Pi loads ./extensions/delegate.ts from the package manifest, while ./index.ts re-exports the extension and helper types for tests or advanced consumers.

When to use it

Use delegate for work that benefits from isolation:

• scan a code area without filling the main context
• research a library/API and report the answer
• get an explicitly requested independent/fresh review
• investigate noisy failures and report evidence

Do not use it as a workflow engine or a default implementation worker. The parent agent owns implementation, final validation, and the final answer unless the user explicitly asks for child implementation or the task has a clear exceptional isolation benefit. Explicit independent/fresh review requests should use delegation because isolation is the product. If you need chains, background jobs, worktrees, or agent management, use a purpose-built workflow package.

Development

bun install
bun test
bun run typecheck
bun run check
bun pm pack --dry-run
PI_OFFLINE=1 bunx --bun pi --no-extensions -e . --list-models >/tmp/pi-delegate-pi-load.out

Live delegate evals

live-eval.test.ts runs Pi in JSON mode against disposable fixture repos and compares delegate-enabled runs with a delegate-disabled control. It is opt-in locally because it uses live model calls:

PI_DELEGATE_LIVE=1 \
PI_DELEGATE_EVAL_JUDGE_MODEL=openai/gpt-5.5:low \
PI_DELEGATE_EVAL_TIMEOUT_MS=1800000 \
PI_DELEGATE_EVAL_MAX_TOKENS=1500000 \
PI_DELEGATE_EVAL_MAX_COST_USD=30 \
PI_DELEGATE_EVAL_ARTIFACT_DIR=artifacts/live-eval \
bun run test:live

PI_DELEGATE_EVAL_MODEL and PI_DELEGATE_EVAL_JUDGE_MODEL default to openai/gpt-5.5:low. Use PI_DELEGATE_EVAL_TASKS=id1,id2 to run a subset while tuning the policy. PI_DELEGATE_EVAL_REPETITIONS defaults to 1; scheduled CI runs the full matrix three times. PI_DELEGATE_EVAL_BASELINE_FAST_QUALITY sets the pre-change quality baseline; CI seeds it at 4.5 from the archived pre-change runs and permits at most a 0.25-point regression.

The suite keeps delegation-decision fixtures separate from a 12-case, fast-heavy tier-selection matrix. Tier cases require delegation and score omitted effort as effective fast while recording omission count separately. It records sanitized JSONL traces plus summary.json, including decision, selection, quality, latency, token, and cost data. Selection gates require at least 90% accuracy, at most 10% thorough false positives, and at least 80% thorough recall. Crashes, budget overruns, read-only writes, and required/forbidden delegation misses also hard-fail.