---
status: resolved
tags:
  - wayfinder/map
---

# Pi subagents decision

## Destination

Produce an implementation-ready specification for a new neutral Pi subagent extension.
The specification must preserve Pi configuration ownership of subagent types, support frequent context-clean child spawning, and leave Herdr as an optional later adapter rather than the core design target.

## Notes

The original adopt, adapt, or build decision is resolved: build a new neutral Pi extension.
The expanded destination is an implementation-ready specification, not the implementation itself.
Treat no bundled subagent types as a hard architectural boundary: mechanism belongs in the extension, while named agents, prompts, and policy belong in Pi configuration.
Prioritize Pi-native behavior first: runtime model, context modes, status UI, lifecycle supervision, trust boundaries, and dotfiles deployment seam.

## Frontier

None.

## Blocked

None.

## Decisions so far

Herdr compatibility cannot rely on arbitrary background Pi child processes.
Current evidence says independent Herdr agents-section entries are pane-oriented, while parent-pane metadata can project child status but cannot create true per-child visibility.
The best off-the-shelf Pi subagent candidate found is `mjakl/pi-subagent`, but it appears to need adaptation for Herdr visibility and for the no-opinionated-agent-types boundary.
Firstmate is not a suitable direct adoption target because it is an opinionated agent distro, but its Herdr backend is a strong design reference for robust pane identity and recovery.
Local dotfiles already manage Pi and Herdr declaratively, but they manage no Pi extensions or subagent definitions yet, and Herdr's optional Pi integration is not installed because its target path is Nix-managed.
For development, throwaway Pi extensions can be created where Pi normally expects them, but finished deployment should still go through the flake-managed module.
Herdr's Pi integration reports lifecycle for interactive Pi processes in Herdr panes, but it does not make background or JSON-mode Pi child processes appear as independent Herdr agents.
Herdr has plugins and pane-reporting APIs, but independent agent reporting appears pane-bound, so a host-neutral Pi subagent core likely needs a Herdr adapter or Herdr pane strategy for clean agents-section visibility.
`pi-fork` contributes the key context-engineering pattern: fork the active branch into an isolated child transcript, keep noisy work out of parent context, and return a compact evidence-bearing report.
The subagent core must support both active-branch forked children and completely independent children, because adversarial review, red-green refactor checks, code review, and document sanity checks can be harmed by shared context.
Reusable Firstmate patterns are exact host endpoint identity, durable lifecycle events separate from current truth, unknown-preserving recovery, incarnation tokens, and host adapters that keep presentation separate from semantic subagent identity.
Build a new neutral Pi extension, focus on Pi-native subagent behavior first, show headless subagent status inside Pi, and leave Herdr support as an optional adapter rather than a core dependency.
Use a hybrid child-runtime boundary with subprocess RPC as the first implementation and an in-process SDK runner as a later optimization, while representing independent, forked, and persistent children through session inputs rather than separate runtime semantics.
Version one supports only `independent` and `fork` context modes, with `independent` as the global default.
`independent` receives the task prompt, selected agent definition, and normal trusted project context, but no parent transcript or generated parent summary by default.
`fork` receives the full active-branch transcript snapshot as-is plus a small delegated-role wrapper, and child Pi handles normal compaction if needed.
Parent conversation context is opt-in through `fork`, but `fork` itself needs no special confirmation beyond the risky-capability confirmation rules.
The parent receives the final textual result plus compact metadata by default, not selected evidence snippets or child transcript content.
Named agent definitions should use Markdown files with YAML frontmatter and a Markdown body prompt, with `name` and `description` required.
User-level definitions should live under `~/.pi/agent/agents/`, project-level definitions under `.pi/agents/`, and project definitions should load only after project trust.
Project definitions should override user definitions, while duplicate names inside one precedence tier should be configuration errors.
Extension-wide defaults live in dedicated JSON files: global `~/.pi/agent/subagents.json` and trusted project `.pi/subagents.json`, with project config overriding global config after trust.
`subagents.json` owns extension defaults, optional UI settings, concurrency, timeouts, guardrails, and named tool profiles, but not inline named agents.
Version one agent frontmatter supports optional `context`, `model`, `thinking`, `tools`, `allowedContexts`, and `hidden`.
Tool profiles are named profiles that compile to Pi active tools and optional tool-call gates, with reserved built-ins `none`, `read-only`, `read-only-with-safe-bash`, and `full-tools`.
The spawn surface is non-blocking, accepts a single `prompt` field, optionally references a named `agent`, supports ad hoc runtime subagents when no agent is named, and exposes post-spawn list, status, result, and cancel controls.
Exact tool names are deferred to the implementation specification.
The extension must not claim sandbox isolation.
Children run in the local user's trust boundary unless routed through a real container, VM, micro-VM, remote sandbox, or equivalent OS boundary.
Child spawns should default to a conservative environment, explicit tool/resource inheritance, sanitized environment variables, and user confirmation or headless preauthorization for risky capabilities.
Lifecycle should be owned by a central parent-extension supervisor, with subprocess RPC children driven by events, abort signals, process lifecycle, and bounded timers rather than sleep-loop polling.
Use `agent_settled` as semantic completion, followed by process close for subprocess cleanup.
The status architecture should separate status data from presentation.
The default subagent extension should own the data model, status endpoints, durable child records, and neutral events, while its Pi-native UI should be optional and replaceable by another extension.
The bundled optional UI should use three progressive Pi-native layers: a collapsed live summary by default, an expanded live inspector on demand, and durable transcript milestone entries for historical record.
Durable deployment should place the neutral extension under `modules/agents/pi/extensions/subagents/`, optionally add `modules/agents/pi/agents/` for managed user definitions, and avoid `pi install` or package installation without explicit consent.
The Nix seam keeps the extension Nix-unaware and marks detailed dotfiles module option design out of scope for the extension specification.
The spec should require only stable runtime paths such as `~/.pi/agent/subagents.json` and `~/.pi/agent/agents/*.md`, while this repository's Pi module may later decide whether to link plain files, render JSON from Nix attrs, or expose typed options.

## Result

The implementation-ready specification is complete in [[027-pi-subagents-implementation-spec-task]].
The minimal subagent extension tracer bullet is complete in [[046-pi-subagents-minimal-tracer-bullet-task]].
The subagent lifecycle controls slice is complete in [[047-pi-subagents-lifecycle-controls-task]].
The config, named agents, and tool profiles slice is complete in [[048-pi-subagents-config-agents-tool-profiles-task]].
The batch spawning, fork context, and status UI slices are complete in [[049-pi-subagents-batch-concurrency-task]], [[050-pi-subagents-fork-context-task]], and [[051-pi-subagents-status-ui-task]].
The deployed extension verification is complete in [[052-pi-subagents-final-deployment-verification-task]].

## Out of scope

Herdr-specific adapter implementation is outside the initial Pi-extension focus and can be revisited after the Pi-native subagent behavior is deployed.