---
status: open
tags:
  - wayfinder/map
---

# Pi subagent result delivery

## Destination

Track implementation of the approved specification for improving Pi subagent result delivery so background subagents can finish while the parent session continues another workflow, including a HITL grill, without losing results or requiring an inelegant blocking wait.

## Notes

This is a focused follow-on to [[002-pi-subagents-map|Pi subagents decision]].
Keep the fix Pi-native and centered on the existing subagent extension's tool/API and Pi-native UI surfaces.
Optimize equally for general subagent usability and Wayfinder worker coordination.
The minimum acceptable improvement covers non-blocking result retrieval, visible completion or failure awareness, a less primitive subagent UI, visible summaries of what each child is working on, and workflow-safe reconciliation for Wayfinder AFK workers while HITL work continues.
Do not redesign Wayfinder maps, tickets, claims, or Frontier semantics.
Do not add Herdr or other external host integrations in this effort.
Do not solve remote or OS sandboxing here.
Treat ordinary-message background injection into the active parent conversation as outside the default path unless a HITL design decision explicitly opts into a controlled form.

## Frontier

- [[101-pi-subagent-selectable-monitor-implementation|Pi subagent selectable monitor]]

## Decisions so far

Pi exposes enough extension, custom tool, RPC, session, and UI primitives to implement non-blocking subagent status, result retrieval, notifications, and widgets, but the subagent extension must own supervision, persistence of terminal results, retention, and any push-style coordination.
The Pi-native UI path should use layered state rather than active-message injection: footer status for compact awareness, a subagent widget for a non-disruptive inbox-like view, custom entries for durable milestones or unread trails, and explicit commands or overlays for inspection.
The deployed subagent extension already has non-blocking spawn, polling-friendly status and result tools, blocking wait, process-local terminal result storage, a small widget, notifications, and durable milestone entries, but it has no unread model, durable result body store, acknowledgment state, richer inbox, or visible per-child work summary.
Other agent harnesses consistently make delegated/background work a visible work object with identity, label or title, lifecycle state, logs or result retrieval, completion/failure visibility, and explicit stop/dismiss or steering actions, while leaving workflow-specific reconciliation outside the generic background-work layer.
The generic subagent layer should provide current-session reliable completion state, terminal result retrieval, completion awareness, and work labels without prescribing workflow-specific reconciliation behavior.
Completion should be visible during HITL without derailing it, compact UI should show aggregate counts by status, expanded UI should show per-child rows with label, state, elapsed time, and activity or result marker, and selecting a child should attach a read-only Pi-like view without a text prompt.
Wayfinder should treat the generic subagent layer as a reliable current-session completion, result, and label source, while Wayfinder itself owns active-map reconciliation: completions during HITL are visible but deferred, then reconciled through normal artifact and Frontier mechanics after HITL completion or explicit pause.
Pi can support a read-only attached child view as a custom Pi-native overlay or temporary editor-area replacement fed by child RPC or session events, but the implementation should not assume an embeddable promptless `InteractiveMode` exists.
The behavior design is approved as the basis for the written specification.
The approved behavior design is captured as a specification in [[094-pi-subagent-result-delivery-spec-task|Pi subagent result delivery specification]].
Subagent work items now have explicit and prompt-derived labels reused across accepted, status, list, result, runner naming, notifications, and widget surfaces.
Terminal subagent work now remains visible and retrievable in the current session until explicitly cleared through `subagent_clear`, `/subagent-clear`, or the supervisor clear API.
The subagent widget now has the approved monitor shape: compact mode aggregates status counts, and expanded mode shows one row per visible child with state, elapsed time, label, and activity/result marker.
Structured current-session child activity is now captured from RPC events and retained for future read-only inspection, while status, list, and widget surfaces expose concise activity summaries without transcript bodies.
The read-only attached child view is implemented as `/subagent-attach <id>`, opening a promptless Pi-native overlay with transcript-style activity rendering, detach, and scroll controls.
The first attached-view implementation missed the intended direct selection interaction from the expanded monitor, so selectable monitor activation is now the remaining implementation slice.

## Not yet specified

None.

## Out of scope

Herdr and other external host integrations are outside this effort because this route is scoped to a Pi-native result-delivery improvement.
Replacing Wayfinder mechanics is outside this effort because Wayfinder is the stress-test workflow, not the target system being redesigned.
Remote, container, VM, micro-VM, or OS-level sandboxing is outside this effort because the problem is local result delivery and awareness, not trust-boundary isolation.
Full autonomous background conversation injection is outside the default path because it can disrupt active HITL workflows.
