pi-delegation-policy
A Pi extension for configurable delegation intensity and exact subagent role model references.
Package details
Install pi-delegation-policy from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-delegation-policy- Package
pi-delegation-policy- Version
0.31.0- Published
- Nov 19, 2026
- Downloads
- 3,051/mo · 732/wk
- Author
- yivas
- License
- MIT
- Types
- extension
- Size
- 742.3 KB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"subagents": {
"agents": [
"./agents"
]
},
"extensions": [
"./src/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
Documentation · Version 0.31.0
Requires Pi 0.87.1 or later (>=0.87.1). Version 0.14.1 supports Pi 0.84.3 or later.
What it does
It adds one policy block to the request, one ephemeral notice after an effective configuration change, and an optional Advisor reminder. It never changes Pi's main model, thinking level, or tool permissions, and no hook launches a child.
It is not a subagent runner. It does not start, route, supervise, or collect delegated work. Only explicit tools reach the authorized host executor: context_shunt_delegate, and consult_advisor when Advisor launch is tool.
While delegation is active or an Advisor is enabled, a launch check runs before any child starts. By default it corrects three unambiguous cases, writes the exact values into the call, and refuses what it cannot settle. See launch check.
The block also asks for a brief on every child: the bounded outcome and its owner, the context already decided, the scope, the permissions and the exclusions, how it is verified, what it returns, and when it should stop and ask.
Install
pi install npm:pi-delegation-policy@0.31.0
# restart Pi, or run /reload
- Open
/delegate, or pressAlt+G. - Give each role an explicit decision: an exact authenticated
provider/model, or Disable for this session. At least one ordinary role stays enabled. - Choose an intensity and Apply changes, then confirm
/delegate status.
Global defaults live in ~/.pi/agent/delegation-policy.json, and any branch can override them. Installing or upgrading changes no configuration: a session with no saved intensity starts at off.
Intensities
| Intensity | What the guidance asks |
|---|---|
off |
No execution-delegation guidance. An independently enabled Advisor still injects its own section. With both off, no policy block is injected. |
normal |
Delegate substantial, separable work only when the expected benefit clearly outweighs briefing, supervision, review, and integration. Borderline work stays with you. |
aggressive |
Delegate suitable substantial, independently checkable work by default when the objective and the acceptance criteria are clear. |
orchestrator |
Delegate all transferable execution before it begins when an enabled capable role and an authorized launcher exist, regardless of size. Direct work then needs a briefly stated exception. |
The configuration reference states the full orchestrator rule and its exceptions.
Roles and thinking
While delegation is active, every ordinary role needs an explicit decision: an exact provider/model, or disabled. A disabled role is a decision, not a missing model. An absent, unavailable, out-of-scope, or unauthenticated reference, zero enabled ordinary roles, or an unsupported thinking level on an ordinary role produces D:ERR and removes execution-delegation guidance, while a valid enabled Advisor keeps its own section. There is no fallback of any kind.
The policy weighs task fit and then picks the least costly enabled role that can meet the acceptance criteria. When none can, the work stays with the main agent. Preference (efficient, standard, intensive) only breaks ties between Small and Medium, and does nothing when either is disabled.
Visual Design, Vision and Writing are optional, hold up to three models each, and stay outside the cheapest-role comparison. A configured role adds a rule per family and a line per entry, and the block states which models the host reports as able to read images.
Thinking is unset by default, or a fixed level, or an inclusive range. Advisor thinking is not a setting, and the level chosen for one run is never stored. The configuration reference covers entries, sidecars, and validation.
Advisor
Advisor is optional and has no model until you configure one. Its mode defaults to with-delegation, on keeps consultation with delegation off, and off silences it while keeping the saved models. Each of the three slots takes an exact model, and every valid entry gets the same question.
rolelaunch: the main agent launches every valid advisor in one background subagent call.toollaunch:consult_advisor({ question, brief?, evidence? })launches one child per advisor in parallel and needs a stablepi-subagentsSemVer>=0.76.1.
Every consultation runs in fresh context and carries only the question and a self-contained brief, never your conversation, unless pi-subagents itself defaults a launch to fork, which the extension cannot read. A slot can also be given the read tool for role launches, off by default, which opens a file the brief names, though the host's own permission rules decide what read may reach (SECURITY.md). Consulting another model costs latency and money. A:PART means some entries are usable and A:ERR means none is.
Advisor reference covers modes, threads, provider extensions, and the reading flag.
ContextShunt
ContextShunt is a separate opt-in layer, off by default. observe records what enforcement would block without changing a call or its result. enforce blocks recognized declared excess and compacts a known textual result it has already preserved, so context_shunt_recover returns one bounded range. Errors, valid JSON text, images, binaries, mixed blocks, and unknown tool contracts stay untouched, nothing is launched from a hook, and delegation off suspends the layer. The limits reference states the caps and the answer contract.
Commands
/delegate Open the editor
/delegate off|normal|aggressive|orchestrator Set the branch intensity
/delegate status Show effective session state
/delegate reset Turn both axes off for the branch
/delegate advisor off|on|with-delegation Set the Advisor mode
/delegate advisor launch role|tool Select the launch surface
/delegate advisor 1|2|3 model PROVIDER/MODEL Configure an entry
/delegate advisor 1|2|3 model inherit Return every entry to inheritance
/delegate advisor 1|2|3 model remove Remove an entry
/delegate advisor threads status|recover|reset Inspect, recover or reset threads
/delegate vision [2|3] PROVIDER/MODEL Add a Vision entry
/delegate visual-design 2|3 PROVIDER/MODEL Add a Visual Design entry
/delegate writing [2|3] PROVIDER/MODEL Add a Writing entry
/delegate context off|observe|enforce|status Set or inspect ContextShunt
/delegate context allow TOKEN LINES BYTES Approve the next blocked read once
Panel changes stay in a draft until Apply changes. The commands above write when they run. Status tokens carry their source, for example advisor-mode=with-delegation (global) and A:OFF. D:OFF, D:NORM, D:AGG, and D:ORCH describe delegation, while launches= counts launches by role, so a configured role that never ran stays visible at zero. Commands and status covers the panel keys and the status fields.
Where state lives
State lives under ~/.pi/agent. The extension stores no credentials and no prompts.
delegation-policy.json (schema 7) holds the intensity, the preference, the three ordinary roles, uiDesign, the thinking policies, and the ContextShunt configuration. Companions sit beside it: the Advisor pair, optional entries, provider admissions, and the private threads journal. Content-free events go to delegation-policy.events.jsonl.
Loading never rewrites a file. Persistence lists the schemas each version reads and the downgrade steps.
Development and license
npm ci
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run pack:check
Tests use local mocks, with no paid model calls and no network. CONTRIBUTING.md covers working in this repository and SECURITY.md how to report a problem.
ContextShunt adapts the large-read routing pattern of Spotify Engineering's Portal and shunt and its shunt plugin, independently for Pi, with no affiliation or endorsement.
MIT. See LICENSE.