pi-herdsman 0.1.4 → 0.2.0

package/docs/guides/handoffs.md

@@ -6,8 +6,8 @@ Pi Herdsman has two text-file mechanisms with different purposes:
 
 - `files` supplies evidence to delegate (definition or session), steer, reply,
   or ask_owner.
-- whole-line body `@file` references put definition-owned text into the worker
-  system prompt when a new worker generation is built.
+- whole-line body `@file` references put definition-owned text into the agent
+  system prompt when a new agent generation is built.
 
 Strict UTF-8 text is embedded when it fits; non-text and non-fitting files are
 canonical local references and are not copied or snapshotted.
@@ -15,11 +15,17 @@ canonical local references and are not copied or snapshotted.
 ## Message `files`
 
 For `delegate` with `definition`, `delegate` with `session`, `steer`, and
-`reply`, pass supporting artifacts, including
-applicable instruction or skill files, through `files` instead of mentioning
-only their paths in the task or message; explain each file's relevance in the
-accompanying text, and do not reattach skills already supplied by the selected
-agent definition.
+`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 runtime discovery.
+
+Attach an agent instruction file only when the task requires inspecting,
+modifying, comparing, or transmitting it, the user explicitly requests it, or
+its instructions are required and the target would not otherwise receive them.
+Skills are separate: attach a required `SKILL.md` only when the task needs it
+and the selected definition does not already provide that skill. Ordinary
+relevant source, documentation, configuration, and evidence files remain
+attachable.
 
 Example:
 
@@ -32,10 +38,30 @@ Example:
 }
 ```
 
+The model-facing representation follows Pi's native `@file` convention:
+
+```xml
+<file name="/absolute/canonical/path" bytes="123">
+contents
+</file>
+```
+
+A reference-only file uses a self-closing tag:
+
+```xml
+<file name="/absolute/canonical/path" bytes="123" />
+```
+
+`name` is the canonical absolute path and `bytes` is the observed file size.
+A body means the complete submission-time UTF-8 snapshot was embedded; a
+self-closing tag means only the path and size reference was supplied. File
+content remains raw text. This markup frames evidence for the model and is not
+a security boundary.
+
 `files` is supported by `delegate` with `definition`, `delegate` with `session`,
 `steer`, `reply`, and `ask_owner`. For
 controller actions, relative paths resolve from the calling controller's cwd;
-for `ask_owner`, they resolve from the managed worker's cwd. Every accepted
+for `ask_owner`, they resolve from the managed agent's cwd. Every accepted
 path is displayed using its canonical absolute path.
 
 Supplied paths must resolve to readable regular files. Missing, broken,
@@ -95,6 +121,7 @@ line has one of these shapes:
 @./relative.md
 @../relative.md
 @/absolute/path.md
+@~/home-relative.md
 ```
 
 These remain literal text:
@@ -102,12 +129,15 @@ These remain literal text:
 ```text
 @alice
 Use @./policy.md when needed
+@~user/file.md
+@$HOME/file.md
+@${HOME}/file.md
 ```
 
 Relative body references are resolved from the Markdown definition that
 declared them **before** bundled/global body composition.
 
-Expansion then happens once, in body order, when a new worker generation is
+Expansion then happens once, in body order, when a new agent generation is
 constructed.
 
 Included file contents are not recursively parsed for more `@file` references.
@@ -140,21 +170,21 @@ same canonical file in both
 
 ## Immutable prompt transport
 
-A definition body is expanded into text before worker lifecycle mutation.
+A definition body is expanded into text before agent lifecycle mutation.
 
-The final expanded body and shared herdr worker guidance are written to private
+The final expanded body and shared herdr agent guidance are written to private
 temporary snapshots (`0600` files under private `0700` directories), passed to
 Pi, and removed after the delegation attempt.
 
 Original body source paths are never handed to Pi as system-prompt paths.
 
-Each worker generation builds its system prompt once for its single assignment.
+Each agent generation builds its system prompt once for its single assignment.
 Session continuation builds a new generation with the current effective
 definition configuration while preserving the saved Pi session context.
 
 ## Result handoff
 
-Successful worker completion may expose a private `resultPath`.
+Successful agent completion may expose a private `resultPath`.
 
 For dependent work, pass the exact result path through `files` rather than
 copying a large result manually:
@@ -168,7 +198,7 @@ copying a large result manually:
 }
 ```
 
-Successful worker completions persist their complete output at the canonical
+Successful agent completions persist their complete output at the canonical
 `resultPath`; they do not receive a separate completion overflow path.
 Oversized non-completion registered-tool output may additionally expose
 `full_output_path` when overflow persistence succeeds. Model-visible content
@@ -203,12 +233,12 @@ These files are coordination state, not product state. Do not use `.pi-herdsman/
 for product source, permanent user documentation, application data, build
 output, caches, or generated artifacts.
 
-Read-only workers may consume existing coordination artifacts but do not gain
+Read-only agents may consume existing coordination artifacts but do not gain
 permission to modify them.
 
 When dependent work uses an artifact, pass the same path through `files` on the
 message that creates or updates the dependency: `delegate.files` for a new
-worker, `steer.files` for an active worker, `ask_owner.files` for supporting
+agent, `steer.files` for an active agent, `ask_owner.files` for supporting
 evidence in a question, or `reply.files` for the owner's answer. Update the
 artifact before submission. Small text is embedded at submission time; a
 reference-only artifact remains a live canonical local path.
@@ -219,6 +249,6 @@ actual runtime capability is required.
 
 ## See also
 
-- [`worker` API](../reference/worker.md)
+- [`agent` API](../reference/agent.md)
 - [Agent-definition schema](../reference/agent-definition-schema.md)
 - [Delegation](../concepts/delegation.md)

package/docs/guides/recovery.md

@@ -5,23 +5,23 @@
 Recovery is identity-safe and conservative. Use the public state and returned
 structured error before attempting another mutation.
 
-## Worker is `blocked`
+## Agent is `blocked`
 
-A blocked worker still has an active assignment.
+A blocked agent still has an active assignment.
 
-If the worker is waiting for an owner answer, use `reply` with its exact worker.
+If the agent is waiting for an owner answer, use `reply` with its exact agent.
 
 Otherwise resolve the reported external/attention condition. Do not delegate new
-task to a blocked worker.
+task to a blocked agent.
 
-## Worker is `settling`
+## Agent is `settling`
 
 `settling` means assignment convergence is incomplete. Typical causes include:
 
 - task handoff acknowledgement;
 - result delivery;
 - bounded result-persistence recovery;
-- delegating-worker/worker completion gating;
+- delegating-agent/agent completion gating;
 - launch handoff;
 - one-shot cleanup.
 
@@ -31,13 +31,13 @@ If nothing independent remains, end the turn normally and let result/attention
 delivery returns attention to the owner. Refresh `list` only when there is a reason to take
 another control action.
 
-If `list` reports `result_error`, the worker's result could not be persisted
-after bounded retries. The condition retains the run, request, owner, worker,
+If `list` reports `result_error`, the agent's result could not be persisted
+after bounded retries. The condition retains the run, request, owner, agent,
 and failure category. Do not delegate over it: resolve the mailbox persistence
-problem, then close the exact worker before delegating new work. The condition
+problem, then close the exact agent before delegating new work. The condition
 marks retry as unsafe and exact-owner cleanup as safe.
 
-## Worker is `unknown`
+## Agent is `unknown`
 
 `unknown` means the system cannot prove a safe control state from current exact
 evidence.
@@ -49,7 +49,7 @@ recovery error is present, inspect its exact details.
 
 ## Inactivity advisory
 
-A `working` worker with an exact active assignment can become advisory `stale`
+A `working` agent with an exact active assignment can become advisory `stale`
 after ten minutes without observed Pi turn, message, or tool activity.
 
 Possible list fields:
@@ -58,7 +58,7 @@ Possible list fields:
 - `inactive_ms`
 - `last_activity_at`
 
-This is not proof that the worker is hung, dead, safe to terminate, or safe to
+This is not proof that the agent is hung, dead, safe to terminate, or safe to
 replace.
 
 Do not close solely because of inactivity.
@@ -82,7 +82,7 @@ Do not "fix" this by manually deleting guessed panes or mailboxes.
 
 ## `pane_not_ready`
 
-A pane-readiness failure means the managed worker did not reach the required
+A pane-readiness failure means the managed agent did not reach the required
 safe startup boundary.
 
 The normal response is to inspect the returned stage/diagnostic and the current
@@ -104,13 +104,13 @@ uncertain.
 
 ## Close failure
 
-Normal `worker close` targets one exact directly owned live worker.
+Normal `agent close` targets one exact directly owned live agent.
 
-Closing a delegating worker cascades through its owned workers first. If a
-worker cannot be proved or closed safely, the delegating worker remains rather
+Closing a delegating agent cascades through its owned agents first. If a
+agent cannot be proved or closed safely, the delegating agent remains rather
 than being destructively guessed away.
 
-For lead-only human emergency cleanup, `/workers stop` operates on the proven
+For lead-only human emergency cleanup, `/agents stop` operates on the proven
 owned tree and reports discarded active work or durable pending results. It is
 not the normal model orchestration interface.
 
@@ -124,15 +124,15 @@ delegation uses that saved cwd and does not accept a caller-supplied `cwd`.
 The saved agent-definition name is resolved against the current effective
 definition roster. If it no longer exists, session delegation fails instead of guessing a
 replacement. The definition must also be enabled and authorized for the current
-controller, and its current effective configuration is used for the new worker
+controller, and its current effective configuration is used for the new agent
 generation.
 
 An exact session that is already represented by active or unresolved managed
 work cannot be activated concurrently. The session-start exclusion applies to
 the canonical session path, so an exact UUID and its exact path identify the
 same target. Wait for the existing assignment to finish and clean up, or close
-its exact live worker when abandoning it, then retry. Do not delegate another
-task through a worker label.
+its exact live agent when abandoning it, then retry. Do not delegate another
+task through an agent label.
 
 ## Before retrying
 
@@ -140,17 +140,17 @@ Check:
 
 1. exact error category;
 2. operation;
-3. worker identity;
+3. agent identity;
 4. known pane/session IDs;
 5. startup stage when present;
 6. primary cause;
 7. cleanup cause;
 8. `rollbackOccurred`;
 9. `nextAction`;
-10. current `worker list`.
+10. current `agent list`.
 
 ## See also
 
 - [Errors](../reference/errors.md)
-- [Worker states](../reference/worker-states.md)
-- [Workers and identity](../concepts/workers.md)
+- [Agent states](../reference/agent-states.md)
+- [Agents and identity](../concepts/agents.md)

package/docs/reference/agent-definition-schema.md

@@ -48,12 +48,12 @@ are loaded from `<cwd>/.pi/agents/` only when trusted project settings set
 `piHerdsman.projectAgents` to `true`. Precedence is `bundled < project < global`.
 
 All effective definitions are sorted and validated together, including every
-`workers` reference.
+`agents` reference.
 
 `enabled` controls definition availability. A disabled definition remains in the
 lead roster so it can be enabled again, but owner-visible definition lists omit
 it. Definition and session delegations reject a disabled definition. An already
-active worker may finish and remains controllable according to its current
+active agent may finish and remains controllable according to its current
 available actions; disabling a definition does not mutate that assignment.
 
 ## Fields
@@ -61,7 +61,7 @@ available actions; disabling a definition does not mutate that assignment.
 | Field                   | Accepted value                                                        | Omitted/default behavior                                          | Runtime/composition behavior                                                                           |
 | ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `name`                  | non-empty string                                                      | required                                                          | Effective definition identity.                                                                         |
-| `enabled`               | boolean                                                               | `true`                                                            | `false` makes definition and session delegation unavailable; it does not mutate an active worker.      |
+| `enabled`               | boolean                                                               | `true`                                                            | `false` makes definition and session delegation unavailable; it does not mutate an active agent.       |
 | `description`           | string                                                                | absent                                                            | Display/selection description.                                                                         |
 | `model`                 | non-empty string                                                      | Pi default/current launch behavior                                | Passed as Pi model selection.                                                                          |
 | `thinking`              | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `false` | Pi default/current launch behavior                                | `false` launches as `off`.                                                                             |
@@ -74,19 +74,20 @@ available actions; disabling a definition does not mutate that assignment.
 | `noSkills`              | boolean                                                               | skills disabled unless `inheritSkills: true`                      | Controls Pi native skill discovery; explicit `skills` values are still passed separately.              |
 | `inheritSkills`         | boolean                                                               | does not enable by itself unless `true`                           | `true` changes omitted `noSkills` default so native skills remain available. Explicit `noSkills` wins. |
 | `skills`                | inline array of non-empty strings                                     | no explicit skill arguments                                       | Each value is passed unchanged as a Pi skill path/resource.                                            |
-| `noExtensions`          | boolean                                                               | Pi normal extension policy                                        | `true` emits `--no-extensions`. Required herdr worker infrastructure remains injected by the launcher. |
+| `noExtensions`          | boolean                                                               | Pi normal extension policy                                        | `true` emits `--no-extensions`. Required herdr agent infrastructure remains injected by the launcher.  |
 | `extensions`            | inline array of non-empty strings                                     | no extra extension arguments                                      | Each value is passed unchanged to Pi.                                                                  |
-| `workers`               | inline array of unique non-empty definition names                     | no direct workers                                                 | Names direct definitions this worker may delegate to; every name must exist.                           |
+| `agents`                | inline array of unique non-empty definition names                     | no direct agents                                                  | Names direct definitions this agent may delegate to; every name must exist.                            |
 | `inheritProjectContext` | boolean                                                               | `true` only for definition name `delegate`; otherwise `false`     | Controls project context-file inheritance.                                                             |
 | `inheritGlobalContext`  | boolean                                                               | follows effective `inheritProjectContext`                         | Controls global context-file inheritance.                                                              |
 
 Arrays supplied by an override replace the complete inherited array, including
 an explicit `[]`.
 
-When a delegating worker declares a worker in `workers`, that worker must be enabled.
-A delegating worker referencing a disabled worker can remain discoverable, but is rejected
-during assignment or fresh worker startup with an explicit disabled-worker error
-rather than being silently removed from the delegating worker definition.
+When a delegating agent declares an agent definition in `agents`, that definition must
+be enabled. A delegating agent referencing a disabled agent definition can remain
+discoverable, but is rejected during assignment or fresh agent startup with an explicit
+disabled-agent error rather than being silently removed from the delegating agent
+definition.
 
 Skill and extension paths are passed to Pi unchanged. herdr does not resolve
 them relative to the definition file.
@@ -100,7 +101,7 @@ source-qualified permissions, such as an extension path plus tool name.
 
 An explicit `tools` allowlist takes precedence over the default-selection
 switches `noTools` and `noBuiltinTools`; `excludeTools` still removes matching
-names. Thus a managed worker may receive both `--no-tools` and an explicit
+names. Thus a managed agent may receive both `--no-tools` and an explicit
 `--tools ask_owner`. Pi Herdsman protects that mandatory `ask_owner` capability in
 managed launches and removes it from explicit exclusions. Unmanaged Pi
 launches do not receive this exception.
@@ -122,39 +123,39 @@ Tools with the same name are not independently permissionable by source, and
 the winner for a name collision is not a supported ordering contract.
 
 `noExtensions` disables ordinary extension discovery, but launcher-injected
-Pi Herdsman worker and Herdr-state extensions remain mandatory infrastructure.
+Pi Herdsman agent and Herdr-state extensions remain mandatory infrastructure.
 Explicit `extensions` entries remain separate launch inputs and are passed to
 Pi normally. Launcher-injected infrastructure remains separate from the
 definition's extension and tool policy.
 
-## Tool inference for `workers`
+## Tool inference for `agents`
 
-A non-empty `workers` list declares potential worker definitions; effective
-delegation also requires permitted `worker` capability and a controller depth
+A non-empty `agents` list declares potential agent definitions; effective
+delegation also requires permitted `agent` capability and a controller depth
 that allows delegation.
 
 This capability is projected by controller depth. Lead-launched definitions
-retain their declared worker allowlist and effective `worker` tool. A
-worker-launched worker receives no worker allowlist and no effective `worker`,
+retain their declared agent allowlist and effective `agent` tool. An
+agent-launched agent receives no agent allowlist and no effective `agent`,
 even when its definition is delegation-enabled at the lead. Explicit tool
 allowlists, empty arrays, `noTools`, and exclusions remain fail-closed.
 
 When it has an explicit non-empty `tools` allowlist and does not already contain
-`worker`, Pi Herdsman appends `worker` to the effective allowlist unless denied.
+`agent`, Pi Herdsman appends `agent` to the effective allowlist unless denied.
 
 Rules:
 
-| Configuration                                    | Effective inference                                                       |
-| ------------------------------------------------ | ------------------------------------------------------------------------- |
-| `workers` omitted or `[]`                        | no inferred `worker`                                                      |
-| non-empty `workers`, `tools` omitted             | keep Pi default tool policy; do not materialize a `worker`-only allowlist |
-| non-empty `workers`, explicit non-empty `tools`  | append `worker`                                                           |
-| `excludeTools` contains `worker`                 | explicit denial wins                                                      |
-| `noTools: true`, no explicit `worker` in `tools` | no inferred `worker`                                                      |
-| `noTools: true`, explicit `tools: ["worker"]`    | explicit allow is preserved                                               |
-| explicit allow plus explicit exclusion           | exclusion wins                                                            |
-
-`ask_owner` is separate mandatory managed-worker infrastructure and is not this
+| Configuration                                   | Effective inference                                                       |
+| ----------------------------------------------- | ------------------------------------------------------------------------- |
+| `agents` omitted or `[]`                        | no inferred `agent`                                                       |
+| non-empty `agents`, `tools` omitted             | keep Pi default tool policy; do not materialize an `agent`-only allowlist |
+| non-empty `agents`, explicit non-empty `tools`  | append `agent`                                                            |
+| `excludeTools` contains `agent`                 | explicit denial wins                                                      |
+| `noTools: true`, no explicit `agent` in `tools` | no inferred `agent`                                                       |
+| `noTools: true`, explicit `tools: ["agent"]`    | explicit allow is preserved                                               |
+| explicit allow plus explicit exclusion          | exclusion wins                                                            |
+
+`ask_owner` is separate mandatory managed agent infrastructure and is not this
 inference rule.
 
 ## Body composition
@@ -184,14 +185,16 @@ A body line is a reference only when the complete trimmed line matches:
 @./relative/path
 @../relative/path
 @/absolute/path
+@~/home-relative/path
 ```
 
 Before bundled/global body composition, relative references are resolved from
 the definition file that declared them.
 
-When a new worker generation is constructed:
+When a new agent generation is constructed:
 
-1. references are processed in body order;
+1. references are processed in body order; `~/` is resolved beneath the
+   current user's home directory;
 2. targets are canonicalized with `realpath`;
 3. each canonical file is included once;
 4. a caller `delegate.files` canonical overlap wins and removes the body copy;
@@ -200,20 +203,20 @@ When a new worker generation is constructed:
 6. included text replaces that reference line;
 7. included text is not recursively expanded.
 
-Every new worker generation expands the effective body and its file references
+Every new agent generation expands the effective body and its file references
 once at launch. Session continuation preserves the Pi session history while
 using the current effective definition configuration.
 
 ## Runtime prompt order
 
-For a newly constructed managed worker, the effective launch composition is:
+For a newly constructed managed agent, the effective launch composition is:
 
 ```text
 Pi base system prompt
     ↓ effective body via systemPromptMode
 selected project/global context-file additions
     ↓
-shared herdr worker guidance
+shared herdr agent guidance
 ```
 
 The final effective body and shared guidance are delivered through private
@@ -238,7 +241,7 @@ inheritSkills: true
 skills: ["/absolute/path/to/code-review/SKILL.md"]
 noExtensions: false
 extensions: ["/absolute/path/to/local-extension.ts"]
-workers: ["scout"]
+agents: ["scout"]
 inheritProjectContext: true
 inheritGlobalContext: false
 ---
@@ -248,8 +251,8 @@ Additional local review instructions.
 @./prompts/review-policy.md
 ```
 
-Because `workers` is non-empty and the explicit `tools` list does not deny it,
-the effective tools include `worker`.
+Because `agents` is non-empty and the explicit `tools` list does not deny it,
+the effective tools include `agent`.
 
 To disable a bundled role without copying its definition, use a minimal global
 override:
@@ -261,7 +264,7 @@ enabled: false
 ---
 ```
 
-The `/workers agents` menu exposes the same enable and disable operations.
+The `/agents definitions` menu exposes the same enable and disable operations.
 Removing the `enabled` line inherits the bundled value; when no source declares
 the field, the effective value is `true`.
 

package/docs/reference/{worker-states.md → agent-states.md}

@@ -1,57 +1,57 @@
-# Worker states
+# Agent states
 
 [Documentation index](../README.md)
 
 The public state is a safe-control projection built from live lifecycle and
 durable assignment/convergence evidence. It is not a raw herdr lifecycle string.
 
-| State      | Meaning                                                                                               |
-| ---------- | ----------------------------------------------------------------------------------------------------- |
-| `working`  | An assignment is active.                                                                              |
-| `blocked`  | Active assignment waits for owner attention or another condition.                                     |
-| `settling` | Assignment handoff, completion/result delivery, launch, direct-worker gate, or cleanup is converging. |
-| `unknown`  | Exact safe control state cannot be proved.                                                            |
+| State      | Meaning                                                                                              |
+| ---------- | ---------------------------------------------------------------------------------------------------- |
+| `working`  | An assignment is active.                                                                             |
+| `blocked`  | Active assignment waits for owner attention or another condition.                                    |
+| `settling` | Assignment handoff, completion/result delivery, launch, direct-agent gate, or cleanup is converging. |
+| `unknown`  | Exact safe control state cannot be proved.                                                           |
 
 ## `available_actions` is authoritative
 
-A live worker record in `worker list` includes an `available_actions` snapshot.
+A live agent record in `agent list` includes an `available_actions` snapshot.
 Use only operations currently listed there; do not infer control eligibility
 from `state` alone. `steer` means active work accepts steering, `reply` means a
 correlated pending `ask_owner` is valid, and `close` means exact ownership or
 approved orphan recovery permits teardown. `available_actions` never includes
-`delegate`; a worker generation handles one assignment only. Every operation
+`delegate`; an agent generation handles one assignment only. Every operation
 revalidates identity, ownership, mailbox state, and lifecycle immediately before
 mutation.
 
-A delegating worker may be blocked while direct worker work is pending and still accept
+A delegating agent may be blocked while direct agent work is pending and still accept
 steering when `steer` is listed. Descendant visibility does not imply authority;
 records outside the controller's direct ownership can have an empty action list.
 
 ## `blocked` and owner questions
 
-A worker waiting on a valid `ask_owner` reply projects as `blocked` after its ask
-turn settles. Answer through the exact direct owner using `reply.worker`.
+An agent waiting on a valid `ask_owner` reply projects as `blocked` after its ask
+turn settles. Answer through the exact direct owner using `reply.agent`.
 
 ## `settling`
 
 Examples include an uncompleted task handoff, pending final result delivery,
-direct-worker gating, terminal cleanup, result persistence recovery, and startup
-or integration handoff. Do not assign another task to a settling worker.
+direct-agent gating, terminal cleanup, result persistence recovery, and startup
+or integration handoff. Do not assign another task to a settling agent.
 
 ## `unknown`
 
 Unknown is intentional fail-closed behavior. Unreadable, oversized, malformed,
 or validation-failing mailbox state is reported with a bounded diagnostic and an
 empty `available_actions` list. Do not substitute pane idleness, elapsed time,
-model metadata, missing activity, a guessed session, or an old worker identity.
+model metadata, missing activity, a guessed session, or an old agent identity.
 
 ## Inactivity fields
 
-A qualifying `working` worker may also report `stale`, `inactive_ms`, and
+A qualifying `working` agent may also report `stale`, `inactive_ms`, and
 `last_activity_at`. This advisory does not change the state or prove a hang.
 
 ## See also
 
 - [Lifecycle](../concepts/lifecycle.md)
 - [Recovery](../guides/recovery.md)
-- [`worker` API](worker.md)
+- [`agent` API](agent.md)