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

# Herdr Pi integration research

## Question

What does Herdr's Pi integration extension actually report or enable, and how does that change the requirements for Pi-spawned subagents to appear with useful lifecycle state in Herdr?

## Resolution

## Findings

Herdr's Pi integration is a Pi lifecycle reporter, not a launcher or subagent manager.
A safe fake install generated `/tmp/herdr-pi.12G0B5/.pi/agent/extensions/herdr-agent-state.ts` without touching the real home.
The generated extension enables itself only when `HERDR_ENV === "1"`, `HERDR_SOCKET_PATH`, and `HERDR_PANE_ID` are present.
Citation: generated `herdr-agent-state.ts` inspected under `/tmp/herdr-pi.12G0B5`.

The extension reports to Herdr through pane-bound API calls.
It uses `pane.report_agent_session` for Pi session identity, `pane.report_agent` for lifecycle state, and `pane.release_agent` on real quit.
It reports `working` on Pi `agent_start`, `idle` on `agent_settled` when Pi is idle, and `blocked` through a custom `herdr:blocked` event.
Citation: generated `herdr-agent-state.ts` and `herdr api schema --json` definitions for pane reporting methods.

The integration runs only for Pi contexts with UI.
On `session_start`, the generated extension returns early unless `ctx.hasUI === true`.
Pi docs state `ctx.hasUI` is false in print and JSON modes.
Citation: generated `herdr-agent-state.ts` and Pi `docs/extensions.md` mode behavior.

Pi's official subagent example launches children with `--mode json -p --no-session` and no Herdr pane assignment.
Those children would not pass the integration's UI guard, and any inherited Herdr pane env vars would identify the parent pane rather than an independent child pane.
Citation: Pi `examples/extensions/subagent/index.ts`.

## Implications

The Herdr Pi integration makes interactive Pi processes inside Herdr panes authoritative lifecycle reporters.
It does not make background or JSON-mode Pi subprocesses appear as independent Herdr agents.

Useful Herdr visibility for Pi subagents therefore requires either running each visible child in a Herdr-addressable pane with the Pi integration loaded, or building a separate mechanism that maps child lifecycle into a Herdr pane or parent-pane metadata representation.

If blocked or waiting state matters, the subagent workflow must emit or translate a blocked-state signal.
The default Pi lifecycle only provides working and idle through the generated integration.
