Repository navigation
v0.22.0
🐑 Pi Herdsman v0.22.0
More control over how the herd works. Less complexity to get started.
v0.22.0 introduces configurable Lead execution profiles, makes /herdsman the main entry point, and establishes a clearer boundary between Manager-controlled project work and ordinary Lead sessions.
It also simplifies the coordination-tool vocabulary, improves context-retirement handling, and adopts Pi 1.1.0.
Important
Breaking change: Model-facing coordination tools now use verb-first names. Existing agent instructions, integrations, and workflows referencing the previous tool names need updating.
Lead execution is now configurable
Ordinary Leads can now operate in two explicit execution modes:
Flexible
A normal Pi session with Herdsman coordination capabilities. The default profile preserves Pi's ordinary tools and supports both direct work and delegation.
Orchestrate
An orchestration-focused Lead that delegates bounded work to Agents while retaining coordination, direction, integration, and decisions.
The bundled Orchestrate profile starts with read-oriented tools, but both profiles can be customized.
Each mode has its own standalone definition:
Ordinary Lead
├─ Flexible → flexible-lead
└─ Orchestrate → orchestrator-lead
Manager-assigned Lead
└─ Managed → managed-lead
These profiles do not inherit from or compose with one another.
Switch ordinary execution modes through:
/lead
/lead flexible
/lead orchestrate
The /herdsman menu also provides an Execution selector.
A new defaultLeadExecution setting controls the initial mode for future ordinary Lead sessions. The default is flexible.
Execution preferences persist across session continuation, and navigation through Pi's conversation tree restores the appropriate execution state.
Note
Lead execution profiles control instructions and ordinary tool availability, not ownership or supervision authority. Manager-assigned Leads continue using their separate managed-lead definition.
Contributor: @boadij · PR: #304 · Issue: #294
/herdsman becomes the main entry point
Herdsman has grown beyond background Agents. The human-facing interface now reflects that broader scope.
Run:
/herdsman
to access:
- Execution
- Agents
- Project manager
- Session stats
- Definitions
- Settings
- Advanced controls
The interface progressively exposes more powerful workflows without requiring users to understand the entire orchestration hierarchy first.
Existing /agents commands remain fully supported as aliases, including their arguments and expert shortcuts.
Tip
You can start with normal Pi usage, add background Agents when useful, and move into dedicated Lead or Manager workflows without changing tools or adopting a prescribed development process.
This also establishes progressive capability disclosure as an explicit product-design principle: simple workflows should remain simple even as more advanced orchestration becomes available.
Contributor: @boadij · PRs: #300, #299
Manager authority is now tied to exact project assignments
Manager supervision is now explicitly limited to Leads named by current durable project assignments.
Sharing a workspace or worktree scope no longer implies Manager authority.
Manager
└─ assigned Lead → Manager authority
Unassigned ordinary Lead → no implicit Manager authority
Unassigned Leads remain eligible for Chief supervision.
This makes the project-control boundary clearer and avoids treating physical proximity as ownership.
Automatic handoffs from managed Leads
Every completed direct turn from an assigned Lead can now return a nonterminal report to Manager.
When a managed Agent herd run owns the work, herd settlement remains the single automatic handoff boundary.
This closes the gap where a Lead could perform multi-turn direct work without reliably returning its result to Manager.
Routine coordination through message_supervisor remains asynchronous and nonblocking.
Explicit /takeover
Users can now release a Lead from Manager control without destroying its working environment.
After confirmation, /takeover:
- removes the current project assignment and pending project messages
- preserves the Pi session and conversation
- preserves the branch, worktree, and running process
- preserves the Lead's owned Agents
- transitions the Lead to ordinary Orchestrate execution
This is an authority transition, not project completion.
Important
A managed Lead remains managed until its assignment is explicitly released. Merely continuing the same Pi session manually does not revoke Manager authority.
Contributor: @boadij · PR: #284 · Issues: #277, #278
Breaking: coordination tools now use verb-first names
The model-facing API now follows a consistent:
<verb>_<target>
naming convention.
Agent tools
agent_list → list_agents
agent_delegate → delegate_agent
agent_continue → continue_agent
agent_steer → steer_agent
agent_interrupt → interrupt_agent
agent_reply → reply_agent
agent_close → close_agent
agent_inspect → inspect_agent
agent_transcript → read_agent_transcript
Peer and supervisor tools
peer_list → list_peers
peer_message → message_peer
supervisor_message → message_supervisor
Staff and project tools
staff_list → list_staff
staff_inspect → inspect_staff
staff_transcript → read_staff_transcript
staff_message → message_staff
staff_delegate → delegate_project
staff_resume → resume_project
staff_stop → stop_lead
The existing ask_owner tool keeps its name.
Human-readable tool presentation, documentation, bundled instructions, and runtime registration have been updated accordingly.
Manager/Lead messaging also remains intentionally distinct from managed-Agent questions: supervisor coordination is nonblocking, while ask_owner remains the direct-owner question mechanism.
Contributor: @boadij · PR: #297 · Issue: #289
Pi 1.1.0 and cancellation-safe settlement
The tested runtime baseline is now:
Pi 1.1.0
Herdr 0.9.3
Pi 1.1.0 provides explicit cancellation information through agent_settled.aborted.
Herdsman now respects that signal when classifying managed-Agent results.
A cancelled run can no longer be reported as successfully completed merely because its last assistant message looked successful.
Cancelled Lead turns likewise produce factual, nonterminal reporting instead of implying verified completion.
This preserves existing assignment ownership, child-work reconciliation, and durable result delivery.
The update also keeps Agent-definition tool policies closed by rejecting Pi's new +name and -name modifiers in explicit tool allowlists.
Contributor: @boadij · PR: #305 · Issue: #301
Context retirement reaches the next provider request
Context retirement now delivers its guidance more reliably when an active managed Agent reaches the automatic compaction threshold.
Pi can defer durable messages until a safe turn boundary. Previously, this meant retirement could be recorded before the next provider request actually received the instruction.
Herdsman now uses a one-request bridge to make the guidance available immediately while retaining the durable message in Pi history.
Preventive threshold compaction remains cancelled, and overflow recovery retains its existing behavior.
Retired Agents also cannot start new Agent delegations or continuations, although they may still coordinate already-running children.
Note
This fixes timely instruction delivery, not guaranteed model compliance. Adversarial testing still demonstrated additional ordinary tool calls after guidance was delivered. Further work on reliable post-retirement convergence remains necessary.
Contributor: @boadij · PR: #310 · Issue: #303
Clearer project reports and evidence boundaries
Manager handoffs now distinguish between information present in a project report and evidence actually available on the current Pi conversation branch.
Automatic project reports preserve their text without silently attaching or inventing result bindings.
A semantic Agent result reference is forwardable only when the relevant direct completion or imported result binding exists on the current branch.
Merely mentioning a reference does not make its underlying artifact available.
Explicit files handoffs remain the supported mechanism for transferring evidence between coordination boundaries.
Contributor: @boadij · PR: #315 · Issue: #313
Execution mode is visible in the status widget
The Lead status widget now shows its verified effective execution mode:
● lead · flexible
● lead · orchestrate
● lead · managed
This helps distinguish ordinary interactive work, orchestration-focused Leads, and Manager-assigned project work without opening a menu.
Unknown or unverified execution state is omitted rather than guessed. Narrow terminals preserve the Lead identity before optional metadata.
Contributor: @boadij · PR: #318 · Issue: #317
Additional polish
Agent Definition details now support individual click-to-expand behavior, consistent with other expandable Herdsman transcript entries.
Editing Agent-definition settings preserves the original frontmatter key order instead of moving edited properties to the bottom. Bundled definitions have also received consistent frontmatter formatting.
Test coverage now recognizes bundled-definition paths across standard macOS, Linux, and Windows home directories.
Contributor: @boadij · PRs: #296, #308, #314
Release
Full changelog: v0.21.3...v0.22.0
