5.7 KiB
status, claimed-by, claimed-at, parent, blocked-by, tags
| status | claimed-by | claimed-at | parent | blocked-by | tags | |
|---|---|---|---|---|---|---|
| resolved | 019fbffd-0114-7f56-bce9-2c4e67bb7d52 | 2026-08-01T21:01:01-04:00 | 083-pi-subagent-result-delivery-map |
|
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.nixmodules/agents/pi/extensions/subagents/index.tsmodules/agents/pi/extensions/subagents/supervisor.tsmodules/agents/pi/extensions/subagents/runner.tsmodules/agents/pi/extensions/subagents/types.tsmodules/agents/pi/extensions/subagents/status.tsmodules/agents/pi/extensions/subagents/ui.tsmodules/agents/pi/extensions/subagents/config.tsmodules/agents/pi/extensions/subagents/agents.tsmodules/agents/pi/extensions/subagents/supervisor.test.ts