---
status: resolved
claimed-by: "019fbff0-e725-79bd-861c-f1928d963392"
claimed-at: "2026-08-01T22:00:33-04:00"
resolved-at: "2026-08-01T22:00:33-04:00"
parent: "[[089-pi-subagent-result-delivery-design-approval-grill|Pi subagent result delivery design approval]]"
blocked-by:
  - "[[089-pi-subagent-result-delivery-design-approval-grill|Pi subagent result delivery design approval]]"
tags:
  - ticket/task/afk
---

# Pi subagent result delivery specification

## Question

Write the approved non-blocking subagent result-delivery and UI behavior as a specification, without implementation slicing.

## Result

The approved behavior design is captured below as a specification.
This artifact intentionally does not divide the work into implementation slices.

# Specification: Pi subagent result delivery

## Purpose

Improve Pi subagents so background work remains visible and retrievable while the parent session continues another workflow.
The motivating case is Wayfinder dispatching AFK research workers while the parent continues a HITL grill.
The human should not need to poll, block on `subagent_wait`, or remember that workers might have finished.

## Scope

This specification covers current-session subagent result delivery, completion awareness, work labels, and improved Pi-native subagent UI.
It also covers the boundary between the generic subagent layer and workflow-specific skills such as Wayfinder.
It does not cover cross-restart durability, Herdr integration, remote sandboxing, or redesigning Wayfinder mechanics.

## Generic subagent responsibilities

The generic subagent layer must expose reliable current-session completion state.
It must expose reliable current-session terminal result retrieval.
It must expose completion awareness without requiring blocking waits.
It must expose useful work labels for running and terminal children.
It must not prescribe workflow-specific reconciliation rules.

A completed result remains visible and retrievable for the parent session until it is explicitly cleared.
Terminal result persistence across parent session restart, Pi restart, or extension reload is not required.

## Work labels

Each child should have a human-readable label that explains what it is working on.
The spawn caller may provide an explicit label.
Structured callers may provide or imply a label from their own context, such as a Wayfinder ticket title.
Ad hoc children should fall back to a generated or truncated prompt summary.

## Completion awareness

Completion during HITL work should be visible but non-disruptive.
The UI should announce completion once and keep persistent compact state visible afterward.
Completion notices should identify what finished and whether it completed, failed, timed out, or was cancelled.
Several completions may be batched into one notice.

The generic layer should not inject ordinary messages into the active parent conversation by default.
Result bodies should remain retrievable out of band until a workflow or explicit user action chooses to inspect them.

## Compact UI

The compact UI should show aggregate counts by status rather than one row per child.
The compact view is for ambient awareness while the parent workflow remains primary.
It should be enough to tell that work is running, queued, completed, failed, timed out, cancelled, or otherwise awaiting attention.

## Expanded UI

The expanded UI should show one row per subagent.
Each row should include the child label, lifecycle state, elapsed time, and last activity or result marker.
Rows should truncate cleanly when space is limited.
The expanded view is for quickly understanding what children exist and which ones need attention.

## Attached child view

Selecting a child for inspection should open a read-only attached child view.
The view should look like a normal Pi session view, but without the text prompt.
The view should be an overlay or temporary replacement rather than a split pane.
The view only needs detach and normal scroll up and down controls.
It must not provide a text-input channel to the child.

Pi can support this shape through a custom Pi-native viewer component fed by child RPC or session events.
The design must not assume an embeddable promptless `InteractiveMode` exists.

## Wayfinder boundary

Wayfinder treats the generic subagent layer as a reliable current-session source for child completion, result, and label state.
Wayfinder owns active-map reconciliation.
When AFK workers complete during a HITL ticket, Wayfinder may surface completion awareness but should not read result bodies or reconcile artifacts unless the human explicitly pauses for reconciliation.
After HITL completion or explicit pause, Wayfinder reconciles active-map workers through its normal artifact and Frontier mechanics.

## Acceptance criteria

A parent session can continue a HITL workflow while background subagents run.
The human can see that subagents completed or failed without invoking a blocking wait.
The parent can retrieve terminal results later in the same session.
The compact UI shows aggregate status counts.
The expanded UI shows useful per-child work rows.
A selected child can be inspected through a read-only Pi-like attached view without a prompt.
The generic subagent layer remains workflow-neutral.