---
status: resolved
claimed-by: 019fbffd-0114-7f56-bce9-2c4e67bb7d52
claimed-at: 2026-08-01T21:01:01-04:00
parent: "[[083-pi-subagent-result-delivery-map|Pi subagent result delivery]]"
blocked-by: []
tags:
  - ticket/task/afk
---

# Pi subagent result delivery current extension inventory

## Question

Inventory the current dotfiles-managed Pi subagent extension's result, status, wait, lifecycle, storage, and UI behavior so the design decisions are grounded in the deployed implementation rather than memory.

## Canonical result

The deployed extension is `modules/agents/pi/extensions/subagents`, copied by `modules/agents/pi/pi.nix` into the Home Manager managed `~/.pi/agent/extensions` tree.
It exposes tools and slash commands for spawn, batch spawn, list, status, result, wait, cancel, clear, diagnostics, and UI toggling.

`subagent_spawn` and `subagent_batch` are non-blocking.
They create in-memory child records, return accepted ids immediately, and start children through a bounded supervisor queue.
The default concurrency is three children.
The default context is independent.
The default tool profile is `read-only`, with built-in profiles for no tools, read-only, read-only plus safe bash, and full tools.
Named agents and config are read from `~/.pi/agent/agents`, trusted project `.pi/agents`, `~/.pi/agent/subagents.json`, and trusted project `.pi/subagents.json`.

The lifecycle states are `queued`, `starting`, `running`, `settling`, `completed`, `failed`, `cancelled`, `timed_out`, and `orphaned`.
The supervisor currently drives queued, starting, running, settling, completed, failed, cancelled, and timed_out.
`orphaned` exists in the type model but is not assigned by the current supervisor path.
Startup timeout defaults to 30 seconds.
Runtime timeout defaults to disabled.
Cancellation and shutdown mark active children cancelled.
Timeout marks children timed_out and attempts to cancel the process.

A child is a separate Pi RPC process launched with `--mode rpc`, `--no-extensions`, and an explicit `--extension` pointing back to the subagents extension.
Forked children receive the parent session file through `--fork`.
Independent children do not.
The child environment strips parent `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`.
Completion is detected from the child RPC `agent_settled` event, after which the runner asks the child for `get_last_assistant_text` and stores that text as the result.

`subagent_status` returns the current lifecycle record for one id.
The record includes id, label, agent, ad-hoc flag, context, state, cwd, model, thinking, tools, timestamps, elapsed time, last event, stop reason, result availability, child session, and error.
`subagent_list` returns all active records plus terminal records that have not been explicitly cleared.
Terminal records remain visible and addressable by id while the supervisor lives, until `subagent_clear` or `/subagent-clear` removes them from the visible current-session work set.

`subagent_result` is polling-friendly.
Before completion it returns a result object with `running: true`, `resultAvailable: false`, and no result text.
After successful completion it returns `running: false`, `resultAvailable: true`, and the final assistant text.
Failed terminal states return `running: false`, the terminal state, and the error when one exists.
The result object is not marked read, acknowledged, consumed, or hidden by retrieval.

`subagent_wait` is blocking by design.
It accepts ids, optional timeout, and mode `all` or `any`.
It returns ids, mode, ready flag, result objects for all requested ids, pending statuses, timedOut flag, and elapsed time.
A timeout returns pending data but does not cancel children.
An abort rejects the wait and also does not cancel children.
Unknown ids and empty id sets are errors.

Storage is process-local.
The supervisor and all child records live in module-level memory for the extension process.
Terminal results are retained in the in-memory child map until explicit clear.
On `session_shutdown`, the supervisor cancels active children and is cleared.
There is no durable result store, unread queue, acknowledgment state, or cross-session recovery.
The only durable transcript-adjacent output is `pi.appendEntry("subagent_milestone", { event, status })` for accepted, completed, failed, cancelled, and timed_out milestones.

The UI behavior is a small Pi widget plus notifications.
When UI is available and enabled, the widget is registered as `subagents`.
Collapsed mode shows one summary line with running, queued, and terminal counts.
Expanded mode adds one line per listed status with id, label, context, state, elapsed seconds, model, tool profile, last event, and whether a result is available.
The `subagent-ui` command toggles expanded mode.
Spawn and UI commands notify the user.
List, status, result, wait, batch, diagnostics, cancel, and clear commands display JSON through notifications.
Milestones update the transcript via `appendEntry`, but they do not inject an ordinary assistant message into the active conversation.
There is no visible unread result model or reconciliation workflow beyond polling status, polling result, waiting, clearing terminal work, or using the widget.

## Source files inventoried

- `modules/agents/pi/pi.nix`
- `modules/agents/pi/extensions/subagents/index.ts`
- `modules/agents/pi/extensions/subagents/supervisor.ts`
- `modules/agents/pi/extensions/subagents/runner.ts`
- `modules/agents/pi/extensions/subagents/types.ts`
- `modules/agents/pi/extensions/subagents/status.ts`
- `modules/agents/pi/extensions/subagents/ui.ts`
- `modules/agents/pi/extensions/subagents/config.ts`
- `modules/agents/pi/extensions/subagents/agents.ts`
- `modules/agents/pi/extensions/subagents/supervisor.test.ts`
