ai-artifacts/projects/dotfiles/092-subagent-ui-other-harness-patterns-research.md

status, claimed-by, claimed-at, resolved-at, parent, blocked-by, tags

status	claimed-by	claimed-at	resolved-at	parent	blocked-by	tags
resolved	019fc017-704e-7100-a949-2701c6e6a12f	2026-08-01T21:29:56-04:00	2026-08-01T21:33:10-04:00	084-pi-subagent-result-delivery-product-semantics-grill		ticket/research

Subagent UI other harness patterns research

Question

What do other agent harnesses and adjacent developer-agent tools make visible for background or parallel agents, tasks, jobs, or delegated work, and what design patterns should inform Pi's improved subagent UI without prescribing workflow-specific result handling?

Answer

Primary sources point to a consistent product pattern: background or delegated agent work needs a durable visible object with an identity, label or title, lifecycle state, detailed transcript or log, and explicit retrieval or steering actions. Claude Code is the closest peer for Pi because it documents background subagents, a task list, a fork panel, completion notifications, named-agent status in typeahead, permission prompts that name the child, failure preservation, resumable transcripts, and final summaries returned to the main conversation. GitHub Copilot cloud agent is the strongest adjacent cloud pattern because it centralizes long-running work in an agents panel and session list, opens a session log and overview with progress, token usage, and session length, lets users steer or stop a session, keeps archived history, and answers later questions from session logs. Devin's public API shows the same model in API form: sessions have ids, titles, tags, status enums, timestamps, messages, pull-request links, structured output, list filtering by tags, detailed retrieval, tag updates, and termination. OpenHands SDK shows a composable library pattern: concurrent background conversations, conversation forks with titles and tags, execution status, pause and resume, and non-intrusive ask_agent() progress questions. For Pi, these sources support an inbox-like subagent surface plus compact ambient status and one-shot notifications, rather than default uncontrolled conversation injection. The generic layer should expose the durable work object and retrieval/acknowledgment mechanics, while workflow-specific code decides what it means to reconcile the result.

Findings

Claude Code foreground, background, and task-list patterns

Claude Code documents subagents as specialized assistants that run in their own context window with custom prompts, tool access, and permissions, and that return only a summary to the main conversation for context management. It distinguishes subagents from independent parallel sessions and points users to background agents when they need to monitor many independent sessions from one place. It also treats descriptions as routing labels because Claude uses each subagent description to decide when to delegate. Citation: Anthropic Claude Code subagents.

Claude Code lets users invoke subagents by natural language, by @ mention, or as a session-wide agent. Its @ typeahead includes named background subagents that are currently running and shows their status next to the name. This is direct evidence for exposing child identity and lifecycle state at selection or reference points, not only in a separate status command. Citation: Anthropic Claude Code subagents.

Claude Code explicitly separates foreground and background subagents. Foreground subagents block the main conversation until completion. Background subagents run concurrently while the user continues working. When a background subagent needs tool permission, the prompt appears in the main session and names the subagent that is asking. As of the documented version, background subagent results reach Claude as a completion notification in a later turn, and Claude waits for that notification before reporting the result. Citation: Anthropic Claude Code subagents.

Claude Code keeps completed background subagents visible in /tasks, marked done and sorted below running work, until session cleanup. Its detail view stays open when a subagent finishes. Failures and stopped subagents leave the list, while API-error failures are reported as failures rather than as findings, and the failure message can include last output so partial work is not lost. This supports a Pi rule that terminal status and terminal output should remain retrievable until explicitly cleared or retained by policy. Citation: Anthropic Claude Code subagents.

Claude Code documents parallel-research usage where multiple subagents explore independent areas and Claude synthesizes their findings when results return. It warns that many detailed results consume main-conversation context, which supports Pi keeping result bodies retrievable out of band and only injecting or summarizing by deliberate action. Citation: Anthropic Claude Code subagents.

Claude Code also documents nested delegation. A subagent can spawn subagents below it up to a configured depth, and nested subagents are recommended when a delegated task itself splits into parallel subtasks so intermediate output never reaches the main conversation and only the top-level summary returns. This supports preserving hierarchy or parent-child relationships when Pi eventually displays multi-level delegated work, even if the first implementation stays flat. Citation: Anthropic Claude Code subagents.

Claude Code forked subagents appear in a panel below the prompt input with one row for the main session and one row for each fork. The panel supports navigation, opening a fork transcript and sending follow-up messages, dismissing a finished fork, stopping a running fork, and returning focus to the prompt. When a fork finishes, its result arrives as a message in the main conversation. This is a strong UI pattern for Pi's richer subagent widget: rows, statuses, open transcript/details, stop, dismiss or acknowledge, and explicit result handling. Citation: Anthropic Claude Code subagents.

Claude Code persists subagent transcripts independently from the main conversation. Main-conversation compaction does not affect subagent transcripts, session persistence lets users resume subagents after restarting the same session, and automatic cleanup removes transcripts after a retention period. This supports Pi separating compact visible state from potentially large child transcripts or results, and making retention an explicit product concept. Citation: Anthropic Claude Code subagents.

Claude Code common-workflow and scheduled-task patterns

Claude Code's common workflows recommend delegating research to subagents when codebase exploration would flood the parent context. The subagent reads files in its own context window and reports a summary. Citation: Anthropic Claude Code common workflows.

Claude Code's common workflows also describe parallel sessions via git worktrees and state that background agents are the way to monitor parallel sessions from one screen instead of separate terminals. This reinforces the distinction between many visible work objects and one active conversation. Citation: Anthropic Claude Code common workflows.

For scheduled autonomous tasks, the same documentation tells users to be explicit about what success looks like and what to do with results because the task runs autonomously and cannot ask clarifying questions. Its example asks Claude to review pull requests with a label, leave inline comments, and post a summary in a channel. This supports Pi keeping the generic subagent layer workflow-neutral while letting the caller's prompt or skill define success and result destination. Citation: Anthropic Claude Code common workflows.

GitHub Copilot cloud agent session-management patterns

GitHub Copilot cloud agent works independently in the background to complete tasks. GitHub documents that it can research a repository, create implementation plans, fix bugs, update docs, address technical debt, and optionally open a pull request. It runs in its own ephemeral development environment powered by GitHub Actions. Citation: GitHub Docs, Overview of Copilot cloud agent.

GitHub exposes delegated work through an agents panel and other entry points on GitHub.com. The user can have Copilot research, plan, make code changes on a branch, iterate before creating a pull request, or request that a pull request be created right away. Third-party integrations are explicitly more constrained, because they only support creating a pull request directly rather than deep research, planning, and iterative pre-PR work. Citation: GitHub Docs, Overview of Copilot cloud agent.

GitHub's session-management documentation says the agents panel can monitor and manage agent sessions across repositories. Sessions started by the user or prompted by another user appear in a sessions list. Clicking a session opens a session log and overview where the user can monitor progress, token usage, and session length. Citation: GitHub Docs, Managing agent sessions.

GitHub's session logs show Copilot's internal reasoning and tools used to understand the repository, make changes, and validate work. Commits authored by Copilot include a link to session logs, providing traceability for later code review or audit. Citation: GitHub Docs, Managing agent sessions.

GitHub lets users steer a running session by opening the session and typing a follow-up prompt below the session log. It lets users stop a session, which ends the GitHub Actions run and preserves already-pushed commits. It lets users archive stopped sessions to remove them from the session list, and cloud-agent sessions can be archived but not deleted. Citation: GitHub Docs, Managing agent sessions.

GitHub distinguishes visibility and retrieval semantics for cloud and local sessions. Cloud-agent sessions are visible by default to repository collaborators in the repository Agents tab, while local sessions are private by default and can be shared view-only. Recipients can view prompts, responses, and file changes but cannot steer or modify the shared local session. Citation: GitHub Docs, Managing agent sessions.

GitHub lets users query past sessions in natural language across synced sessions. When a session is complete or a Copilot-created pull request is being viewed, the user can ask what changed, what was validated, and why, and Copilot answers from session logs. This supports a Pi design where the completed result remains a retrievable record rather than only a transient notification. Citation: GitHub Docs, Managing agent sessions.

Devin session API patterns

Devin's API models delegated work as sessions. Creating a session requires a prompt and can include a custom title, tags, snapshot id, playbook id, secrets, ACU limit, idempotency, visibility, and a structured-output schema. If a custom title is omitted, the API can generate one automatically. This supports Pi accepting caller-provided labels while falling back to inferred or generated labels. Citation: Devin API, Create a new session.

Devin's list-sessions endpoint returns session summaries and supports filtering by tags and user email. Session summaries include session id, title, status, status enum, timestamps, tags, pull-request info, structured output, snapshot id, playbook id, and requesting user email. The documented status enum includes working, blocked, expired, finished, suspend and resume request states, and resumed. Citation: Devin API, List sessions.

Devin's retrieve-session endpoint returns detailed session information including status, output metadata, messages, structured output, pull-request info, tags, title, created time, and updated time. This supports a Pi separation between list summary data and full result or transcript retrieval. Citation: Devin API, Retrieve details about an existing session.

Devin's API also exposes tag updates and session termination. Tag updates are capped at 50 tags. Termination ends an active session and cannot be resumed. These endpoints support explicit user-managed organization and lifecycle actions on background work objects. Citations: Devin API, Update session tags and Devin API, Terminate a session.

OpenHands SDK concurrent conversation and fork patterns

OpenHands SDK documents running multiple agent conversations in parallel with asyncio.gather() and running a conversation in a background thread with a callback that receives results in the main run loop. This is a library-level pattern rather than a finished UI pattern, but it reinforces that background execution should have callback or event delivery rather than requiring a blocking wait. Citation: OpenHands SDK, Conversation with Async.

OpenHands SDK documents Conversation.fork() as a deep copy of a conversation's events, agent configuration, and workspace metadata into a new conversation id. The fork starts in idle status, retains the full event memory of the source, can have a title, tags, metadata, a different agent, and fresh or preserved metrics. Its examples include CI debugging, A/B testing, and tool changes. This supports Pi treating side explorations as separately identifiable records that can be compared or resumed without contaminating the source context. Citation: OpenHands SDK, Fork a Conversation.

OpenHands SDK documents ask_agent() as a non-intrusive way to ask context-aware questions during or after a conversation without interrupting the main execution flow. Its use cases include progress monitoring. This supports a Pi detail view or retrieval command that can answer status/progress questions without forcing the background worker's entire result into the active parent exchange. Citation: OpenHands SDK, Ask Agent Questions.

OpenHands SDK documents pause and resume by starting a conversation in a background thread, calling conversation.pause(), observing execution status after pause, sending another message while paused, and calling run() again to resume. This supports exposing pause or stop state as lifecycle state rather than hiding it in logs. Citation: OpenHands SDK, Pause and Resume.

Design patterns for Pi

Pi should model each background subagent as a durable current-session work item with id, label, status, timestamps, prompt summary, terminal summary, and retrieval handle. This pattern is backed by Claude Code's /tasks, fork panel, and transcript ids, GitHub's sessions list and log pages, and Devin's session summary and detail APIs.

Pi should keep compact ambient awareness separate from result bodies. A footer or widget can show counts and short rows for running, done, failed, cancelled, or unread work, while an explicit detail command or expanded widget retrieves full result text. This pattern follows Claude Code's done task rows and detail view, GitHub's agents panel plus session-log drilldown, and Devin's summary-list versus detail-retrieve split.

Pi should make completion visible once and then persistent until acknowledged or cleared. Claude Code documents completion notifications and completed tasks that remain listed. GitHub documents stopped-session archiving rather than deletion from history. Devin exposes finished sessions and timestamps through list and detail APIs.

Pi should show failure as a first-class terminal state and preserve partial output when available. Claude Code documents background API-error failures that mark the subagent failed and include last output. GitHub stops sessions while preserving already-pushed commits. Devin exposes blocked, expired, and finished status enums rather than a single done bit.

Pi should support caller-provided labels and generated fallback labels. Claude Code names forks from the first words of the task and uses named subagents in typeahead. Devin accepts a custom title and otherwise can generate a title. GitHub session lists provide human-openable session entries.

Pi should expose actions separately from workflow reconciliation. Generic actions should include inspect, retrieve result, mark read or acknowledge, dismiss or clear, cancel or stop running work, and maybe open transcript. Workflow-specific actions such as updating a Wayfinder ticket, synthesizing research, or commenting on a PR should remain outside the generic subagent layer. Claude Code and GitHub both expose generic session actions, while their examples let the task prompt decide whether to create PRs, post summaries, or synthesize findings.

Pi should avoid default uncontrolled injection into the active parent conversation. Claude Code does return background subagent results as a later main-conversation message, but it also warns that many detailed results consume main-conversation context. GitHub and Devin primarily use explicit session/log retrieval surfaces. For Pi's HITL grill case, the safer synthesis is notice plus inbox plus explicit retrieval, with any parent-session injection reserved for a controlled opt-in behavior.

Limitations and evidence gaps

Cursor documentation was investigated, but the accessible HTML repeatedly rendered the generic docs shell rather than stable primary page bodies for Cloud Agent pages in this environment. Cursor was therefore not used for settled claims beyond noting the evidence gap.

OpenAI Codex documentation was investigated, but the accessible pages in this environment did not yield stable primary Markdown or easily extractable page bodies for cloud tasks. Codex was therefore not used for settled claims.

The research did not inspect live proprietary UIs such as Devin or GitHub Copilot by logging into accounts. Findings are limited to public first-party documentation and first-party API schemas.

Claude Code behavior is moving quickly and its docs include version-specific notes. The patterns are useful for product design, but exact version behavior should not be copied into Pi without checking the target version at implementation time.

Citations

• Anthropic Claude Code subagents, including background subagents, /tasks, completion notifications, permission prompts, parallel research, nested subagents, fork panel, transcripts, and retention: https://docs.anthropic.com/en/docs/claude-code/sub-agents.
• Anthropic Claude Code common workflows, including delegated research, parallel sessions, background-agent monitoring, and scheduled-task result handling: https://docs.anthropic.com/en/docs/claude-code/common-workflows.
• GitHub Docs, Overview of Copilot cloud agent, including background autonomous work, agents panel entry points, branches, pull requests, ephemeral environments, and integrations: https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent.
• GitHub Docs, Managing agent sessions, including agents panel, session list, session log and overview, progress, token usage, session length, steering, stopping, archiving, sharing, querying, and completed-session questions: https://docs.github.com/en/copilot/how-tos/copilot-on-github/use-copilot-agents/manage-and-track-agents.
• Devin API, Create a new session, including prompt, title, tags, structured output schema, idempotency, snapshots, playbooks, and generated title fallback: https://docs.devin.ai/api-reference/v1/sessions/create-a-new-devin-session.md.
• Devin API, List sessions, including summaries, tag and user filtering, status enum, timestamps, titles, tags, pull request info, and structured output: https://docs.devin.ai/api-reference/v1/sessions/list-sessions.md.
• Devin API, Retrieve details about an existing session, including status, messages, metadata, structured output, title, tags, timestamps, and pull request info: https://docs.devin.ai/api-reference/v1/sessions/retrieve-details-about-an-existing-session.md.
• Devin API, Update session tags: https://docs.devin.ai/api-reference/v1/sessions/update-session-tags.md.
• Devin API, Terminate a session: https://docs.devin.ai/api-reference/v1/sessions/terminate-a-session.md.
• OpenHands SDK, Conversation with Async, including concurrent agent tasks and background-thread result callbacks: https://docs.openhands.dev/sdk/guides/convo-async.md.
• OpenHands SDK, Fork a Conversation, including copied state, idle status, titles, tags, metadata, alternate agents, and fork REST endpoint: https://docs.openhands.dev/sdk/guides/convo-fork.md.
• OpenHands SDK, Ask Agent Questions, including non-intrusive progress questions during and after execution: https://docs.openhands.dev/sdk/guides/convo-ask-agent.md.
• OpenHands SDK, Pause and Resume, including execution status, background thread execution, pause, and resume: https://docs.openhands.dev/sdk/guides/convo-pause-and-resume.md.