# pipi
Delegate one task to a native child Pi session, optionally using reusable agents and structured output.

## Use in Pi
Ask Pi to delegate a bounded task through `pipi`.
No preset required; child inherits parent model and active tools unless overridden.
```json
{"prompt":"Inspect auth flow and report risks","tools":["read","grep","find"]}
```
Calls block until completion; concurrent calls run independently.
Cancellation stops child work, including nested pipi calls.
Results include outcome, native final assistant message or submitted JSON, session ID/file, new-work usage and effective config.
Use returned `sessionId` or `sessionFile` as `sessionId` to continue; `fork:true` forks natively instead.
Without a session ID, `fork:true` forks parent history.
Continuation uses current preset and call config.
### Reusable agents
Under Pi agent directory, create `pipi/agents//config.json` with a required `description` and optional call configuration.
Optional `instructions.md` adds plain Markdown instructions as `sections.pipi_agent`.
Folder name is unique agent name; lowercase ASCII recommended.
No startup directory creation or registration needed.
Discovery refreshes before each parent run; directories without config are ignored, invalid presets are excluded with diagnostics, explicit unavailable names fail.
```json
{"description":"Investigate repository behavior without editing","tools":["read","grep","find"]}
```
Call `{"agent":"reviewer","prompt":"Review authentication"}` after saving that config under `pipi/agents/reviewer/config.json`.
Explicit call values replace preset fields; resource path lists add to preset paths.
Call tier overrides preset model; explicit call model wins over tier.
`sections.pipi_agent` replaces preset instructions.
Prefer improving existing presets over adding near-duplicates.
### Structured output
```json
{"prompt":"Count matching files","outputSchema":{"type":"integer"}}
```
Schema enables a child-local submission tool.
Last valid submission during this call wins; transcript submissions from previous calls never count.
One reminder follows natural completion without submission; second completion fails explicitly.
Errors or cancellation remain errors or cancellation even after valid submission.
Omitted schema inherits preset; object replaces; null disables.
Submission requirement survives `forceSystemPrompt`.
### Configuration and resources
Native `images` input accepts image content blocks alongside `prompt`.
Call options: `model` as `provider/model`, `tier`, `thinkingLevel`, `tools`, `extensions`, `skills`, `prompts`, `flags`, `cwd`, `noExtensions`, `noSkills`, `noPromptTemplates`, `noContextFiles`.
Prompt controls: `sections`, `customPrompt`, `appendSystemPrompt`, `forceSystemPrompt`.
Custom prompts have native guidance-loss semantics; default retains normal Pi guidance.
Tools use native plain replacement and +/- modification syntax.
Call-local resource paths are additive.
Resource selectors retain native +path/-path/!pattern semantics for inherited and call-local resources.
Relative call paths resolve from parent workspace; inherited CLI paths keep their original startup location.
Dynamic extensions are ordinary files under `pipi/dynamic//index.ts`; discover their relative entry paths before loading explicitly with `extensions`.
Start with one entry file; grow only when needed.
User recommendations configure tiny/small/medium/large/huge through `pipi.modelTiers` and optional provider-specific `pipi.providerModelTiers`.
Each tier can specify `model` (`provider/model` or null for inherited model), `thinkingLevel`, and selection `instructions`; provider-specific fields override base recommendations.
Recommendations appear in orchestrator context and do not restrict explicit model selection.
```json
{"pipi":{"modelTiers":{"small":{"model":"openai-codex/gpt-6-luna","thinkingLevel":"high","instructions":"Few local decisions; low consequence."}}}}
```
Explicit model wins; omitted model/tier inherits parent on fresh calls, native saved model on continuation.
An unconfigured tier uses inherited model with its default recommended thinking level; unknown explicit models fail without fallback graphs.
### Boundaries
Child resources are rediscovered for child workspace, respecting trust.
Parent file-based resources, including hook-only permission extensions, remain available across workspace changes.
Runtime-only extensions, programmatic flags, runtime auth overrides and provider-context prompt transforms cannot be introspected exactly.
Requested/effective config and diagnostics expose mismatches rather than promising exact cloning.
No per-child environment override.
Child sessions persist using native storage; complete transcripts are accessible through returned locator.
New and forked child sessions are named `PiPi · · `, so `pi --resume` lists them recognisably under their parent.
Result usage counts only new work persisted in that child session, excluding persisted descendant sessions; unpersisted provider work is not observable.
A persisted child session is its own native usage ledger, so the parent tool result carries no native usage and parent session totals exclude delegated work.
Human previews and model-facing text are bounded; structured result retains native final message.
Use separate sessions or native forks for concurrent work instead of competing writers on one continued session.
[Installation](../../README.md#install)
## Reference
### Setting names
| Setting | Environment |
| --- | --- |
| `pipi` | |
| `pipi.timeoutMs` | `PIPI_TIMEOUT_MS` |
#### Setting values
| Setting | Default | Valid values | Purpose |
| --- | --- | --- | --- |
| `pipi.timeoutMs` | `14400000` | Integer 1000–2147483647 | Call deadline: Wall-clock deadline per pipi call; an expired deadline aborts the child and preserves its session for continuation. |
#### Object fields
Paths below describe fields inside their parent settings object, not literal top-level keys.
`[]` denotes an array element; see setup above for examples and defaults.
| Field |
| --- |
| `pipi.modelTiers` |
| `pipi.providerModelTiers` |