pi-herdsman 0.3.2 → 0.5.0

package/README.md

@@ -99,7 +99,7 @@ For the complete walkthrough, see [Getting started](docs/getting-started.md).
   questions return when they need attention.
 - **One assignment per agent.** Each managed agent generation handles one
   bounded assignment, delivers its terminal result, and is cleaned up. Continue
-  completed context by delegating to the exact returned Pi session.
+  completed context with the explicit `continue` action and exact returned Pi session.
 - **Nested multi-agent orchestration.** Delegation-enabled agents can own and manage
   permitted agents themselves. Identity, ownership, steering, clarification,
   results, and cleanup share the same lifecycle across the hierarchy.
@@ -126,9 +126,9 @@ The model-facing tools are `agent`, `chief`, `staff`, and `ask_owner`.
 `staff` lets the chief supervise leads, and `ask_owner` lets an agent ask its
 exact owner. Leads use `chief.message` and `chief.ask`; the active chief uses
 `staff.message` and `staff.reply` with exact lead session IDs. Agent labels are
-not continuation handles: exact Pi session IDs are the continuation identity.
-Exact herdr identifiers are validation evidence behind live agent and lead
-identity.
+not continuation handles: exact Pi session IDs are the continuation selector.
+A continued session reuses its saved logical label. Exact herdr identifiers are
+validation evidence behind live agent and lead identity.
 
 Bundled definitions are portable defaults, not required workflow stages. Global
 definitions can override them or add new roles with your preferred models,
@@ -136,9 +136,8 @@ tools, extensions, skills, and instructions.
 
 ## Requirements
 
-- [herdr](https://github.com/herdrdev/herdr) `>=0.8.0`
+- [herdr](https://github.com/herdrdev/herdr) `>=0.9.0`
 - Pi `>=0.84.2 <0.86.0` (the version range tested for this release)
-- herdr Pi integration version `2` or newer
 - Node `>=22.19.0`
 
 Install or refresh the herdr Pi integration:
@@ -151,6 +150,19 @@ herdr integration status
 The package manifest loads the bundled extension and exposes the optional
 `agents` skill.
 
+## Compatible extensions
+
+Pi Herdsman interoperates with optional Pi extensions without depending on
+them:
+
+- [pi-web-access](https://github.com/nicobailon/pi-web-access) — the bundled
+  `researcher` recognizes its standard web-research tools.
+- [pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system)
+  — shared agent frontmatter, active-agent identity, and subagent lineage
+  conventions support per-agent permission policy.
+
+Neither extension is required or installed by Pi Herdsman.
+
 ## Documentation
 
 Choose the path that matches what you are doing:

package/SKILL.md

@@ -28,17 +28,17 @@ The session-start instructions include the current agent-definition roster.
 Use list for live agent state, ownership, or a refreshed definition roster
 after configuration changes.
 
-Use delegate to give one bounded assignment to an agent while retaining
-ownership:
-
-- definition creates a new agent from an agent definition;
-- session continues one exact historical Pi context in a new agent generation.
+Use delegate to start one bounded assignment from an agent definition.
+Use continue to start one bounded assignment from an exact historical Pi session.
 
 Each managed agent exists for one assignment only. After its terminal result is
 delivered, Pi Herdsman cleans up that agent automatically. To continue completed
 work with its existing context, use the exact session returned with the result.
-Agent identity is only for controlling the current assignment; it is not a
-continuation identity.
+Agent labels control the currently live generation; they are not continuation
+selectors.
+Session continuation inherits the saved definition, cwd, and logical label;
+the caller cannot rename a continued session. The inherited label controls only
+the currently live generation.
 
 For a live agent, use only operations currently listed in available_actions.
 State describes what is happening; available_actions describes current control
@@ -64,8 +64,7 @@ file inspection, large logs or command output, and dataset analysis. Keep small,
 tightly coupled work local.
 If several tightly coupled phases are already known, put them in one bounded
 assignment when practical. If genuinely new follow-up work emerges after
-completion and previous context is valuable, continue the returned session with
-`delegate.session`.
+completion and previous context is valuable, continue the exact returned session.
 Never continue work that depends on an active agent. Continue useful
 independent work when available; otherwise end the turn normally. Agent
 completion or attention resumes the owning controller automatically. Do not
@@ -75,7 +74,7 @@ If list reports result_error, do not start a new delegation over unresolved
 work. Resolve mailbox persistence first, then close the exact agent before
 starting another assignment; follow the stored recovery nextAction.
 
-Before delegate, steer, or reply, make the message self-contained.
+Before delegate, continue, steer, or reply, make the message self-contained.
 
 Do not attach or mention agent instruction files such as AGENTS.md, CLAUDE.md,
 GEMINI.md, or equivalents merely because they exist. Rely on normal project or
@@ -110,8 +109,10 @@ later dependent assignments when approved scope or decisions change because
 embedded text is snapshotted at submission time while referenced files are not
 copied.
 
-For dependent work, prefer passing an existing resultPath or coordination
-artifact through files instead of copying large results into a task. ask_owner
+Agent completions may return a resultRef such as result:<request-id>. Pass that
+exact resultRef through files for dependent work; do not reconstruct or guess
+the underlying filesystem path. Prefer passing it or a coordination artifact
+through files instead of copying large results into a task. ask_owner
 may also include files when the owner needs supporting evidence. files does not
 add runtime capability.
 
@@ -166,8 +167,8 @@ message evidence. Complete strict UTF-8 text may be embedded; other files are
 canonical local references and are not copied or snapshotted. Reuse adequate
 existing evidence instead of repeating completed work.
 Do not overlap writers in a worktree or file-ownership boundary. For dependent
-work, use and preserve files and resultPath handoffs rather than copying large
-results into assignments.
+work, copy resultRef values exactly through files rather than reconstructing
+physical result paths or copying large results into assignments.
 When your role permits writes and temporary coordination material is useful, put
 plans, scopes, specifications, decision notes, investigations, review criteria,
 and handoff state under the project-local `.pi-herdsman/` directory. Reuse and
@@ -239,8 +240,9 @@ escalation.
 
 ## Handoffs
 
-Prefer `files: [resultPath]` for a dependent agent instead of copying a large
-completion into a new task.
+Prefer `files: [result:<request-id>]` for a dependent agent instead of copying
+a large completion into a new task. Copy the exact resultRef returned by the
+completion; do not reconstruct its physical path.
 
 A concise handoff should include: