---
status: resolved
parent: "[[003-pi-subagents-herdr-compatibility-research]]"
blocked-by: []
tags:
  - ticket/research
---

# Herdr extension boundary research

## Question

What extension or plugin surfaces does Herdr provide, and would a Herdr-side adapter let Pi subagents stay host-agnostic while still integrating cleanly with Herdr's agents section?

## Resolution

## Findings

Herdr exposes a runtime socket and CLI API for session state and control.
`herdr api snapshot` exposes live agents, panes, tabs, and workspaces.
`herdr agent list/get/read/prompt/send-keys/wait/start` operates on detected agent panes.
`herdr pane report-agent`, `report-agent-session`, `release-agent`, and `report-metadata` allow external reporters to set pane-bound agent state, identity, and display metadata.
Citation: `herdr --help`, `herdr agent --help`, `herdr pane report-agent --help`, and `herdr api schema --json`.

Herdr also has a plugin system available through `herdr plugin`.
The CLI exposes install, uninstall, link, unlink, enable, disable, list, config-dir, action, log, and pane commands.
Plugin manifests use `herdr-plugin.toml` and schema fields include build, startup, actions, events, panes, and link handlers.
Plugin event hooks can subscribe to runtime events such as `pane.agent_detected` and `pane.agent_status_changed`.
Citation: `herdr plugin --help`, `herdr plugin action --help`, `herdr plugin pane --help`, and `herdr api schema --json` plugin definitions.

Herdr plugins and API clients can observe the Herdr agent model, but reporting independent agents is pane-bound.
The reporting APIs require `pane_id`, so Herdr's agents section appears derived from panes that host or report agents rather than from arbitrary logical child-agent records.
Citation: `herdr api schema --json` request definitions for `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent`.

Herdr has built-in agent integrations for host tools including Pi.
Those integrations install host-side hooks or extensions, such as Pi's `~/.pi/agent/extensions/herdr-agent-state.ts`.
Citation: `herdr integration status`.

## Implications

A Herdr-side adapter can help keep Pi subagents host-agnostic only if the Pi-side subagent mechanism emits host-neutral lifecycle events or exposes child state for the adapter to consume.
Herdr cannot cleanly infer invisible Pi child subprocesses as separate agents on its own.

The cleanest boundary is likely a host-neutral Pi subagent core plus optional host adapters.
A Herdr adapter can translate subagent lifecycle into Herdr pane APIs when a Herdr pane exists, while other future hosts can provide different adapters.

A pure Herdr plugin may be useful for observing, presentation, and translating events, but independent entries in Herdr's agents section still need a pane target or a Herdr-supported virtual-agent concept that was not found in the inspected schema.
