pi-herdsman 0.44.0 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/README.md CHANGED
@@ -43,7 +43,8 @@ Start with [Coordination API](coordination-api.md), then use the focused
43
43
  references for exact contracts:
44
44
 
45
45
  - [Agent tools](reference/agent.md)
46
- - [`ask_owner`](reference/ask-owner.md)
46
+ - [`notify_owner`](reference/notify-owner.md)
47
+ - [`await_owner`](reference/await-owner.md)
47
48
  - [Staff tools](reference/staff.md)
48
49
  - [Supervisor tools](reference/supervisor.md)
49
50
  - [Peer tools](reference/peer.md)
@@ -5,6 +5,26 @@
5
5
  Pi Herdsman separates supervision, execution ownership, and physical placement.
6
6
  Those relationships intentionally do not collapse into one global Agent tree.
7
7
 
8
+ ## Emergent workflows, explicit boundaries
9
+
10
+ Pi Herdsman provides coordination tools, not a prescribed execution graph.
11
+ A Lead decides how to decompose its objective into bounded tasks and which
12
+ permitted Agents to delegate them to. A delegation-enabled Agent can repeat
13
+ that process within its own allowlist and the configured depth limit. At
14
+ project scale, a Manager decides which independent, branch-scoped objectives
15
+ to assign to managed Leads; each Lead directs its own Agent tree. The models
16
+ may choose parallel execution for independent work or sequence dependent work,
17
+ reassessing after handoffs instead of following a fixed pipeline.
18
+
19
+ The execution strategy is adaptive; authority is not. Exact-session Agent
20
+ ownership, delegation permissions, current project assignments, verified
21
+ worktree scope, and supervision boundaries remain enforced by Herdsman.
22
+ Agents cannot grant themselves broader authority by choosing a different
23
+ handoff. Users can still specify a workflow or customize Agent definitions,
24
+ but no predetermined handoff order is required. See [Delegation](delegation.md)
25
+ and [Project orchestration](../guides/project-orchestration.md) for the
26
+ respective execution contracts.
27
+
8
28
  ## Roles
9
29
 
10
30
  ```mermaid
@@ -209,14 +229,14 @@ live in [Staff tools](../reference/staff.md).
209
229
 
210
230
  Coordination crosses one authority edge at a time:
211
231
 
212
- | Direction | Interface | Boundary |
213
- | --------- | ------------------------------------------- | --------------------------------------------------- |
214
- | Up | `message_supervisor` / automatic results | Assigned Lead -> Manager |
215
- | Down | `message_staff` / project operations | Manager -> assigned Lead |
216
- | Up | `message_supervisor` | Ordinary Lead -> Manager or Chief; Manager -> Chief |
217
- | Down | `message_staff` | Manager -> ordinary Lead (cooperative steering) |
218
- | Sideways | `message_peer` | Lead <-> Lead or Manager <-> Manager |
219
- | Ownership | Agent controls / `reply_agent`; `ask_owner` | owner <-> directly owned Agent |
232
+ | Direction | Interface | Boundary |
233
+ | --------- | ------------------------------------------------------------- | --------------------------------------------------- |
234
+ | Up | `message_supervisor` / automatic results | Assigned Lead -> Manager |
235
+ | Down | `message_staff` / project operations | Manager -> assigned Lead |
236
+ | Up | `message_supervisor` | Ordinary Lead -> Manager or Chief; Manager -> Chief |
237
+ | Down | `message_staff` | Manager -> ordinary Lead (cooperative steering) |
238
+ | Sideways | `message_peer` | Lead <-> Lead or Manager <-> Manager |
239
+ | Ownership | Agent controls / `notify_owner`, `await_owner`, `reply_agent` | owner <-> directly owned Agent |
220
240
 
221
241
  ### Coordination does not imply dependency
222
242
 
@@ -25,7 +25,7 @@ final decision authority for its assignment.
25
25
 
26
26
  A managed Agent may delegate to the definitions in its effective
27
27
  `agents` allowlist only when delegation is enabled by its tool policy. Every
28
- managed agent receives `ask_owner`; qualifying delegating agents also receive
28
+ managed agent receives `await_owner` and `notify_owner`; qualifying delegating agents also receive
29
29
  Agent ownership tools. See the [agent-definition schema](../reference/agent-definition-schema.md#managed-agent-coordination-tools)
30
30
  for the exact eligibility, exclusion, and mandatory-tool rules.
31
31
 
@@ -58,7 +58,7 @@ allows chains of four agents. Delegation at every level still requires the
58
58
  launching agent's definition to list `agents`, and each level may delegate only
59
59
  to definitions in its own allowlist. When a delegated agent's result is
60
60
  delivered and cleaned up, any agents it still owns are closed with it, as they
61
- are for a root controller. Questions from `ask_owner`, results, stop, and
61
+ are for a root controller. Questions from `await_owner`, results, stop, and
62
62
  continuation always go through the direct owner, so each level behaves the
63
63
  same whatever its depth. Lowering `maxAgentDepth` never removes running
64
64
  agents: they stay manageable, but agents at the new limit can no longer start
@@ -150,10 +150,11 @@ merely to keep the controller active. For the full turn-navigation model, see
150
150
 
151
151
  ## Clarification across ownership edges
152
152
 
153
- An agent may ask its exact direct owner through `ask_owner`.
153
+ An agent may notify its exact direct owner without blocking through
154
+ `notify_owner`, or request an answer required to proceed through `await_owner`.
154
155
 
155
156
  A delegating agent with no unresolved direct-agent work follows normal
156
- `ask_owner` eligibility. If unresolved direct agents exist, every unresolved
157
+ `await_owner` eligibility. If unresolved direct agents exist, every unresolved
157
158
  child must itself be validly blocked on an owner question. Ordinary active work
158
159
  or an undelivered result still blocks escalation. Questions are not
159
160
  automatically forwarded through an ownership chain.
@@ -166,6 +167,7 @@ closed, the delegating agent is preserved rather than destructively guessing.
166
167
 
167
168
  ## See also
168
169
 
169
- - [`ask_owner` API](../reference/ask-owner.md)
170
+ - [`await_owner` API](../reference/await-owner.md)
171
+ - [`notify_owner` API](../reference/notify-owner.md)
170
172
  - [Lifecycle](lifecycle.md)
171
173
  - [Handoffs and files](../guides/handoffs.md)
@@ -33,6 +33,11 @@ evidence remains `unknown`.
33
33
  The authoritative final result is correlated to the accepted assignment request
34
34
  ID.
35
35
 
36
+ An Agent may send nonblocking material information to its exact owner with
37
+ `notify_owner`; this does not alter assignment completion eligibility. An
38
+ accepted notification remains in the mailbox until the owner's persisted
39
+ session history confirms receipt, and cleanup waits for that confirmation.
40
+
36
41
  An aborted Pi execution is not successful assignment completion, even when the
37
42
  conversation contains assistant text. The assignment remains active when an
38
43
  accepted interrupt replacement continues the work; otherwise its terminal
@@ -44,7 +49,7 @@ An agent that requires an owner decision stays on the same assignment:
44
49
 
45
50
  ```text
46
51
  working
47
- ↓ ask_owner
52
+ ↓ await_owner
48
53
  blocked
49
54
  ↓ owner reply
50
55
  working
@@ -15,17 +15,17 @@ supporting native programmatic invocation are `list_agents`, `steer_agent`,
15
15
  `read_staff_transcript`, `message_staff`, `delegate_work`, `resume_work`,
16
16
  `stop_lead`, `remove_worktree`, `integrate_branch`, `message_supervisor`,
17
17
  `list_peers`, `message_peer`, `attach_handoff`, `delegate_agent`, and
18
- `continue_agent`. Delegation tools return after assignment acceptance, not
18
+ `continue_agent`, and `notify_owner`. Delegation tools return after assignment acceptance, not
19
19
  completion; eventual results arrive through Herdsman's normal result-delivery
20
- mechanism. `ask_owner` also remains `model-only` because it must be a direct,
20
+ mechanism. `await_owner` also remains `model-only` because it must be a direct,
21
21
  exclusive tool call in its turn. See
22
- [`ask_owner`](reference/ask-owner.md) for its contract.
22
+ [`await_owner`](reference/await-owner.md) for its contract.
23
23
 
24
24
  Tool access still depends on the active role, ownership, extension loading, and
25
25
  runtime authorization. This documents Pi's native contract; behavior through
26
26
  third-party code-mode integrations and their approval or foreground settings
27
27
  depends on that integration and is not guaranteed here. In environments where
28
- `ask_owner` and Fabric are both registered, Fabric may configure it as a
28
+ `await_owner` and Fabric are both registered, Fabric may configure it as a
29
29
  foreground tool, for example:
30
30
 
31
31
  ```json
@@ -33,7 +33,7 @@ foreground tool, for example:
33
33
  "foreground": {
34
34
  "tools": [
35
35
  {
36
- "name": "ask_owner",
36
+ "name": "await_owner",
37
37
  "owner": "pi-herdsman",
38
38
  "reason": "turn-steering"
39
39
  }
@@ -65,7 +65,8 @@ read_agent_transcript
65
65
  ```
66
66
 
67
67
  Managed Agents contact their exact direct owner through
68
- [`ask_owner`](reference/ask-owner.md).
68
+ [`notify_owner`](reference/notify-owner.md) for nonblocking information or
69
+ [`await_owner`](reference/await-owner.md) when progress depends on an answer.
69
70
 
70
71
  The lifecycle and execution-ownership rules are documented in
71
72
  [Lifecycle](concepts/lifecycle.md) and [Delegation](concepts/delegation.md).
@@ -39,7 +39,8 @@ disagrees.
39
39
  | Operator recovery | [Recovery](../guides/recovery.md) |
40
40
  | Container deployment | [Container deployment](../guides/container-deployment.md) |
41
41
  | Agent ownership contract | [Agent tools](../reference/agent.md) |
42
- | `ask_owner` contract | [`ask_owner`](../reference/ask-owner.md) |
42
+ | `notify_owner` contract | [`notify_owner`](../reference/notify-owner.md) |
43
+ | `await_owner` contract | [`await_owner`](../reference/await-owner.md) |
43
44
  | Staff and project-work contract | [Staff tools](../reference/staff.md) |
44
45
  | Supervisor and ask contract | [Supervisor tools](../reference/supervisor.md) |
45
46
  | Peer contract | [Peer tools](../reference/peer.md) |
@@ -151,7 +152,7 @@ When implementation and prose disagree:
151
152
  3. stale prose is deleted rather than preserved as another contract
152
153
 
153
154
  Particularly verify runtime implementation for Agent ownership operations,
154
- `ask_owner`, staff and project operations, supervisor and ask operations, peer
155
+ `await_owner`, `notify_owner`, staff and project operations, supervisor and ask operations, peer
155
156
  operations, `/agents`, `/manager`, `/chief`, states,
156
157
  definition composition, project work, recovery, and presentation behavior.
157
158
 
@@ -124,6 +124,17 @@ Do not ask the model to infer, remember, reconstruct, or supply information the
124
124
 
125
125
  Instructions should describe semantics the system cannot make sufficiently obvious or enforce directly.
126
126
 
127
+ ## Prefer programmatically composable tools
128
+
129
+ Expose Herdsman tools through Pi's native `direct` interface when their
130
+ semantics permit, so models can call them individually or compose them through
131
+ native Code Mode. Reserve `model-only` exposure for tools whose required turn
132
+ isolation, lifecycle, or safety constraints cannot be preserved in nested
133
+ execution. Do not weaken these constraints solely for Code Mode compatibility.
134
+
135
+ This preference applies to Pi's native execution contract; third-party
136
+ integrations may impose additional restrictions.
137
+
127
138
  ## Keep shared instructions roster-agnostic
128
139
 
129
140
  Shared runtime instructions, tool descriptions, and reusable workflows must not
@@ -125,6 +125,13 @@ consumption. Prefer eliminating work over adding caches or infrastructure,
125
125
  and justify optimization complexity with evidence. Never trade correctness,
126
126
  reliability, security, or recovery for speed.
127
127
 
128
+ When independently eligible messages, results, or notifications target the
129
+ same model session, prefer recipient-side fan-in at existing Pi execution
130
+ boundaries over separate model turns. Do not delay time-sensitive delivery just
131
+ to form a batch. Preserve each communication's identity, authority checks,
132
+ ordering requirements, receipts, and recovery; reuse native delivery rather
133
+ than introduce batching infrastructure without demonstrated need.
134
+
128
135
  ## Decision test
129
136
 
130
137
  For any proposed feature, ask:
@@ -81,15 +81,16 @@ provider accepts only expected transcript states and requires actual correlated
81
81
  tool results before producing completion responses. It cannot produce
82
82
  successful tool results or directly mutate Herdsman or Herdr state. The
83
83
  simulated-only scenarios use real Pi, Herdsman, and Herdr; they do not replace
84
- live-model acceptance. `agent-crash-recovery` fully stops and restarts its
85
- generated named Herdr server, reopens the exact owner Pi session, and verifies
86
- that the restored pending-child parent remains `blocked`. If that live parent
87
- advertises `steer_agent`, the scripted owner tries it once and the scenario
88
- requires the receiverless request to be rejected; listing the tool alone does
89
- not prove receiver readiness. It then persists a successful close tool result
90
- and continues the exact saved target session as a new generation. Model
91
- decisions are scripted; the process/server lifecycle and controller tools are
92
- real. The scenario never uses the default Herdr server.
84
+ live-model acceptance. `agent-crash-recovery` restarts its isolated Herdr server
85
+ and reopens the exact owner session with its pending-child parent safely
86
+ blocked or unknown. It resolves the original target through an exact persisted aborted
87
+ result or one authorized stop receipt, then waits read-only for the persisted
88
+ acknowledgment/absence of active work and physical quiescence before one exact
89
+ session continuation. It verifies one correlated completed result and fails
90
+ closed on incomplete state or process evidence. An advertised receiverless
91
+ parent steer is attempted once and must be rejected. The process/server
92
+ lifecycle and controller tools are real; the scenario never uses the default
93
+ Herdr server.
93
94
  Simulated runs do not require model credentials or inference, but retain runtime
94
95
  compatibility checks, build, isolation, Herdr setup, and cleanup. They are
95
96
  integration checks, not replacements for real-model acceptance.
@@ -101,7 +102,7 @@ real Pi, Herdsman, and Herdr, that each of levels 1 through 3 holds the
101
102
  delegation tool while the level-4 Agent at the limit does not, that each
102
103
  Agent's completed result reaches its direct owner, and that the leaf's marker
103
104
  bubbles up through every level to the root's final message. The level-4 Agent
104
- also escalates one `ask_owner` to its level-3 owner, which answers with
105
+ also escalates one `await_owner` to its level-3 owner, which answers with
105
106
  `reply_agent`, and the scenario asserts both calls. It asserts
106
107
  completion and result delivery. It also samples the root's rendered status
107
108
  tree and requires every level to be shown there at some sample before the chain
@@ -230,6 +231,26 @@ Herdsman, copy normal Pi settings or extensions, or run as part of
230
231
  `npm run validate`. Run selected scenarios according to the change being
231
232
  verified; `npm run smoke` defaults to `core`.
232
233
 
234
+ ## Peer federation acceptance
235
+
236
+ Required peer-federation CI runs the shared core acceptance independently for
237
+ real containerized Managers (`manager-core`) and ordinary Leads (`lead-core`).
238
+ Each verifies one successful request, the exact correlated reply persisted
239
+ once, and A's assistant completion after that reply without another prompt.
240
+ The comprehensive ordinary-Lead acceptance remains manually available as the
241
+ `delivery` phase; it covers managed-Lead exclusion and delivery/recovery checks
242
+ not included in the focused CI gate.
243
+
244
+ Run the focused phases with
245
+ `PEER_SMOKE_PHASE=manager-core node scripts/peer-federation-smoke.mjs` and
246
+ `PEER_SMOKE_PHASE=lead-core node scripts/peer-federation-smoke.mjs`.
247
+ The comprehensive Manager recovery scenario remains the default and is
248
+ manually runnable with
249
+ `node scripts/peer-federation-smoke.mjs`. Run comprehensive ordinary-Lead
250
+ delivery with
251
+ `PEER_SMOKE_PHASE=delivery node scripts/peer-federation-smoke.mjs`.
252
+ A failed federation invocation is not retried automatically.
253
+
233
254
  ## Runtime preflight
234
255
 
235
256
  Before allocating the Herdr environment, the harness validates installed Node,
@@ -326,8 +347,8 @@ Verify:
326
347
  Launch a delegating managed agent with an explicit ordinary execution-tool
327
348
  allowlist and ask it to delegate one bounded scout task. Verify that it retains
328
349
  those ordinary tools and can call all nine coordination tools plus
329
- `ask_owner`, then verify that the spawned scout is a leaf with its normal tools
330
- and `ask_owner` but no delegation tools. Also verify that role-required tools
350
+ `await_owner`, then verify that the spawned scout is a leaf with its normal tools
351
+ and `await_owner` but no delegation tools. Also verify that role-required tools
331
352
  are not removed by `excludeTools`.
332
353
 
333
354
  For a definition with `tools` omitted, verify that launch does not add a
@@ -363,7 +384,7 @@ Verify the agent obeys that instruction through the expanded private prompt.
363
384
  Afterward remove the temporary definition and referenced file, confirm discovery
364
385
  no longer lists the temporary definition, and verify no repository file changed.
365
386
 
366
- ## `ask_owner` round trip
387
+ ## `await_owner` round trip
367
388
 
368
389
  Owner ask/reply remains manual, unautomated coverage.
369
390
 
@@ -371,7 +392,7 @@ Give an agent a task whose correct continuation requires an owner choice.
371
392
 
372
393
  Verify:
373
394
 
374
- 1. agent calls `ask_owner` alone;
395
+ 1. agent calls `await_owner` alone;
375
396
  2. owner receives one question;
376
397
  3. agent becomes `blocked`;
377
398
  4. owner replies with exact `reply_agent`;
@@ -140,31 +140,34 @@ worktree. If `node_modules` is absent, run `npm ci` from that checkout.
140
140
  ### Optional setup for newly created worktrees
141
141
 
142
142
  The repository includes a `post-checkout` hook that runs `npm ci` synchronously
143
- when Git creates a new linked worktree. It is not enabled automatically. To
144
- enable it, run these steps from the trusted **primary checkout** (not a linked
145
- worktree).
143
+ when Git creates a new linked worktree. It is not enabled automatically.
146
144
 
147
- First inspect the configured hook directory and its origin:
145
+ For a fresh trusted clone, run this from the **primary checkout** (not a linked
146
+ worktree):
148
147
 
149
148
  ```sh
150
- git config --show-origin --get core.hooksPath
149
+ npm run setup
151
150
  ```
152
151
 
153
- Inspect its existing executable hooks as well; if `core.hooksPath` is unset,
154
- inspect the repository's default hooks directory using
155
- `git rev-parse --git-path hooks`.
156
-
157
- If an existing hook configuration or hook manager would be displaced, retain
158
- that configuration or integrate the script manually; this repository does not
159
- install a dispatcher. `core.hooksPath` selects the whole hooks directory, so
160
- changing it can disable other hooks. If no existing configuration would be
161
- displaced, enable the repository hook locally:
152
+ This configures the hook and installs dependencies. If dependencies are already
153
+ installed, `npm run setup:hooks` enables only the hook. Setup is idempotent.
154
+ When a repository folder is copied with its `.git` directory, setup repairs a
155
+ repository-local `core.hooksPath` pointing to an old `.githooks` directory
156
+ if that directory is missing or its hook files match the current checkout.
157
+ Unrelated hook managers, global settings, and executable default hooks are
158
+ not overridden. Inspect the current hook configuration and its origin with:
162
159
 
163
160
  ```sh
164
- git config --local core.hooksPath "$(pwd -P)/.githooks"
161
+ git config --show-origin --get core.hooksPath
165
162
  ```
166
163
 
167
- This local, optional setting affects only this repository. Its absolute path
164
+ If an existing hook configuration or hook manager would be displaced, retain
165
+ it or integrate `.githooks/post-checkout` manually; the repository does not
166
+ install a dispatcher. `core.hooksPath` selects the whole hooks directory, so
167
+ changing it can disable other hooks.
168
+
169
+ When newly configured, this local, optional setting affects only this
170
+ repository. Its absolute path
168
171
  deliberately points all linked worktrees to the same trusted script; ordinary
169
172
  worktrees share the repository's common Git configuration. Enabling it is an
170
173
  explicit developer trust decision: creating a new linked worktree in this
@@ -51,7 +51,7 @@ Pi to use the bundled `scout` Agent for a read-only reconnaissance task:
51
51
 
52
52
  ```text
53
53
  Use scout to identify this repository's main entry points.
54
- Explain how the application starts. Don't change any files.
54
+ Explain how the application starts.
55
55
  ```
56
56
 
57
57
  Delegation starts after Herdsman accepts the task. The Agent works
@@ -290,7 +290,7 @@ the active controller contract remains authoritative for delegation behavior.
290
290
 
291
291
  A non-empty `agents` list is required but does not alone enable delegation;
292
292
  the effective tool policy also governs eligibility. Every managed agent retains
293
- mandatory `ask_owner`, and an Agent at the configured maximum nesting depth
293
+ mandatory `await_owner` and `notify_owner`, and an Agent at the configured maximum nesting depth
294
294
  is a leaf. See
295
295
  [Delegation](../concepts/delegation.md) for the ownership model and the
296
296
  [agent-definition schema](../reference/agent-definition-schema.md#managed-agent-coordination-tools)
@@ -150,7 +150,40 @@ Tailscale provides networking only. SSH remains normal OpenSSH.
150
150
 
151
151
  ## Update
152
152
 
153
- To update Herdsman inside the container, finish active coordination first, then run:
153
+ To update the Pi runtime inside the container, finish active coordination
154
+ first, then run:
155
+
156
+ ```sh
157
+ pi update
158
+ ```
159
+
160
+ Pi downloads the complete official release into an immutable directory under
161
+ `~/.local/share/pi-herdsman/pi/releases/` and atomically selects it. New Pi
162
+ processes use that release; already-running processes continue using their
163
+ original files. The selection survives container restart and recreation and
164
+ takes precedence over the Pi bundled in a newer image. Pulling an image does
165
+ not replace this persistent selection, so review it separately for Pi security
166
+ updates. Forced reinstallations create additional retained release directories;
167
+ the container does not prune them.
168
+
169
+ Pi's `pi update --all` follows upstream behavior: installed packages are
170
+ updated before the Pi runtime, so the operation is not transactional. For
171
+ operationally significant updates, stop coordination and run the Pi update and
172
+ package updates as separate operations.
173
+
174
+ To recover to the image-bundled Pi after stopping work, remove only the
175
+ selection symlink:
176
+
177
+ ```sh
178
+ rm ~/.local/share/pi-herdsman/pi/current
179
+ pi --version
180
+ ```
181
+
182
+ Do not delete the release directories or the persistent home. The bundled
183
+ runtime remains available at `/opt/pi`.
184
+
185
+ To update Herdsman or other installed Pi packages, finish active coordination
186
+ first, then run:
154
187
 
155
188
  ```sh
156
189
  pi update npm:pi-herdsman
@@ -87,9 +87,11 @@ agents: [scout, reviewer]
87
87
  ```
88
88
 
89
89
  An omitted `agents` field leaves Leads unrestricted; `agents: []` disables
90
- fresh delegation. Overlay arrays replace lower-layer arrays, including with
91
- `[]`. Existing owned Agents remain manageable. The policy covers direct
92
- children only and is independent of ordinary tool selection.
90
+ fresh delegation. Existing owned Agents remain manageable. The policy covers
91
+ direct children only and is independent of ordinary tool selection. For
92
+ concrete inherited lists, `agents: [+scout, -reviewer]` modifies the list.
93
+ Leads with an unrestricted implicit default must first use a plain
94
+ `agents: [scout, reviewer]` allowlist before applying modifiers.
93
95
 
94
96
  Ordinary Leads persist their execution mode separately from role/authority
95
97
  state and retain their ordinary tool baseline while a restrictive profile is
@@ -238,7 +240,9 @@ For a matching higher-precedence definition:
238
240
 
239
241
  - omitted fields inherit;
240
242
  - strings and booleans replace;
241
- - arrays replace wholesale, including `[]`;
243
+ - arrays with plain entries replace wholesale, including `[]`;
244
+ - `+name` and `-name` entries modify inherited arrays; in a mixed list,
245
+ plain entries establish the replacement base before ordered modifiers;
242
246
  - the complete effective definition is validated after composition.
243
247
 
244
248
  `enabled` is a boolean that defaults to `true`. Use it in a minimal override to
@@ -320,7 +324,7 @@ append-only and rejects `replace`. A custom replacement prompt does not
320
324
  automatically preserve Pi's normal system-prompt rules or tool guidelines.
321
325
 
322
326
  Managed agents additionally receive shared herdr agent guidance at launch,
323
- including the `ask_owner` contract. This shared guidance is infrastructure and
327
+ including the `notify_owner` and `await_owner` contracts. This shared guidance is infrastructure and
324
328
  is not copied into every bundled role body. Managed project Leads instead use
325
329
  the effective `managed-lead` body plus the ordinary Lead runtime charter and
326
330
  dynamic project coordination context.
@@ -407,8 +411,23 @@ The same diagnostic's no-network negative probe can be run with
407
411
  deterministic forbidden `exec_command` call into an empty tool context and
408
412
  asserts Pi returns `Tool exec_command not found` without execution.
409
413
 
410
- Remember that arrays replace the bundled array rather than append to it.
411
- Explicitly include every value you want in the effective array.
414
+ Plain arrays replace the inherited array. Use modifiers to add or remove
415
+ individual values without copying the inherited list. For example, a project
416
+ overlay can adjust an Agent's skills and a private repository overlay can
417
+ remove one inherited extension:
418
+
419
+ ```yaml
420
+ # .pi/agents/reviewer.md
421
+ skills: ["+/absolute/path/to/review/SKILL.md"]
422
+
423
+ # <git-common-dir>/pi-herdsman/agents/reviewer.md
424
+ extensions: ["-./extensions/legacy.ts"]
425
+ ```
426
+
427
+ For tools, a modifier-only list such as `tools: [+codemode, -write]` is
428
+ relative to Pi's ordinary tool selection, not a closed allowlist. Use a plain
429
+ list when a closed allowlist is intended. Tool modifiers accept exact names;
430
+ put wildcard patterns in `excludeTools`.
412
431
 
413
432
  Skill and extension paths are passed to Pi unchanged; unlike body `@file`
414
433
  references, herdr does not resolve them relative to the definition file.
@@ -471,38 +490,6 @@ execution fields from their spawning controller; `continue` restores saved
471
490
  session settings. They do not mutate an already-running agent or the lead Pi
472
491
  session.
473
492
 
474
- ## Optional Pi Codex Conversion context sharing
475
-
476
- The Herdsman adapter for Pi Codex Conversion (PCC) is optional and supports
477
- Remote storage only. PCC's `shareSubagentContext` setting remains authoritative.
478
- Load the adapter in both the delegating controller and each participating fresh
479
- managed child; it is shipped at
480
- `dist/integrations/pi-codex-context-sharing.js` but is not loaded by default.
481
- For a normal npm Pi installation, reference it explicitly, for example:
482
-
483
- ```text
484
- ~/.pi/agent/npm/node_modules/pi-herdsman/dist/integrations/pi-codex-context-sharing.js
485
- ```
486
-
487
- When a managed Agent definition uses `noExtensions: true`, list both PCC and the
488
- Herdsman adapter in that definition's `extensions`:
489
-
490
- ```yaml
491
- ---
492
- name: shared-worker
493
- noExtensions: true
494
- extensions:
495
- - "~/.pi/agent/npm/node_modules/@howaboua/pi-codex-conversion/dist/index.js"
496
- - "~/.pi/agent/npm/node_modules/pi-herdsman/dist/integrations/pi-codex-context-sharing.js"
497
- ---
498
- ```
499
-
500
- An explicit `tools` allowlist must independently permit the tools needed by the
501
- current PCC execution mode. The adapter does not modify tools or PCC execution
502
- mode; consult PCC for mode-specific requirements. PCC restores the saved
503
- context identity on continuation, so no adapter rebind is needed. Local and
504
- Tree storage are not supported because they require ongoing context routing.
505
-
506
493
  ## See also
507
494
 
508
495
  - [Agent-definition schema](../reference/agent-definition-schema.md)
@@ -118,7 +118,7 @@ Ordinary files supplied to `message_staff`, `message_supervisor`, or
118
118
  configured per-file and complete-message budgets; unsupported, changed, or
119
119
  non-fitting files reject the handoff instead of becoming path-only references.
120
120
  Other `files` operations retain their existing preparation behavior. In
121
- particular, `ask_owner` requires supported UTF-8 text attachments to fit fully
121
+ particular, `await_owner` requires supported UTF-8 text attachments to fit fully
122
122
  within its per-file and complete-message budgets; rejection does not fall back
123
123
  to a path-only reference. Ordinary
124
124
  coordination attachments are per-message evidence unless retained through an
@@ -144,13 +144,13 @@ Pi Herdsman has two text-file mechanisms with different purposes:
144
144
  - `files` supplies evidence to the coordination operations that accept it:
145
145
  `delegate_agent`, `continue_agent`, `steer_agent`, `interrupt_agent`,
146
146
  `reply_agent`, `delegate_work`, `message_staff`,
147
- `message_supervisor`, `message_peer`, and `ask_owner`.
147
+ `message_supervisor`, `message_peer`, `notify_owner`, and `await_owner`.
148
148
  - whole-line body `@file` references put definition-owned text into the agent
149
149
  system prompt when a new agent generation is built.
150
150
 
151
151
  For coordination operations that allow reference fallback, strict UTF-8 text is
152
152
  embedded when it fits; ordinary non-text and non-fitting files are canonical
153
- local references and are not copied or snapshotted. `ask_owner` is stricter:
153
+ local references and are not copied or snapshotted. `await_owner` is stricter:
154
154
  its explicit files must be embedded supported UTF-8 text, or the request is
155
155
  rejected. The required-assignment exception preserves supported text snapshots
156
156
  and can reference those snapshots when they do not fit inline; see
@@ -234,8 +234,8 @@ markup frames evidence for the model and is not a security boundary.
234
234
 
235
235
  `files` is supported by `delegate_agent`, `continue_agent`, `steer_agent`,
236
236
  `interrupt_agent`, `reply_agent`, `delegate_work`, `message_staff`,
237
- `message_supervisor`, `message_peer`, and `ask_owner`. For controller actions,
238
- relative paths resolve from the calling controller's cwd; for `ask_owner`, they
237
+ `message_supervisor`, `message_peer`, `notify_owner`, and `await_owner`. For controller actions,
238
+ relative paths resolve from the calling controller's cwd; for `await_owner`, they
239
239
  resolve from the managed agent's cwd. Accepted ordinary filesystem paths retain
240
240
  canonical absolute-path names; semantic and canonical result refs retain the
241
241
  exact supplied reference as the model-facing name.
@@ -40,11 +40,16 @@ Do not intervene solely because a stale threshold was reached.
40
40
 
41
41
  The generic attention reasons are `result_error`, live runtime `blocked`, old
42
42
  unacknowledged `handoff`, and physical `unknown`. Stale, lost, and delivered
43
- `ask_owner` conditions retain their dedicated message types. A retained
43
+ `await_owner` conditions retain their dedicated message types. A retained
44
44
  unacknowledged request must not be duplicated or resubmitted: timeout or lack
45
45
  of acknowledgement does not prove non-delivery. `settling` alone does not
46
46
  generate generic attention.
47
47
 
48
+ An Agent may remain `settling` after its result is delivered while accepted
49
+ `notify_owner` records await receipt in the owner's persisted session history.
50
+ Do not treat a successful Pi message submission as confirmation or close the
51
+ Agent; normal cleanup retries after the receipt is recorded.
52
+
48
53
  ## Agent is `blocked`
49
54
 
50
55
  A blocked agent still has an active assignment.
@@ -53,7 +58,7 @@ If the agent is waiting for an owner answer, use `reply_agent` with its exact ag
53
58
 
54
59
  Otherwise inspect the reported external/runtime condition and resolve it using
55
60
  only the currently listed actions. A live Herdr runtime reported as `blocked`
56
- may generate health attention when no `ask_owner` question exists. This is
61
+ may generate health attention when no `await_owner` question exists. This is
57
62
  different from a delegating parent whose public projection is `blocked` while
58
63
  it waits for direct child work; parent waiting is not, by itself, evidence of
59
64
  an externally blocked runtime. Do not delegate a new task to a blocked agent.
@@ -134,7 +139,7 @@ Do not guess from pane IDs, process appearance, elapsed time, or stale metadata.
134
139
 
135
140
  Physical `unknown` remains fail-closed: it has no mutation actions and receives
136
141
  at most one generic attention event for an unresolved episode. Do not infer
137
- loss, guess a pane or process, or use `ask_owner` as a generic escalation path.
142
+ loss, guess a pane or process, or use `await_owner` as a generic escalation path.
138
143
  Refresh with `list_agents` and resolve the identity/lifecycle condition when new exact
139
144
  evidence is available. If a cleanup or recovery error is present, inspect its
140
145
  exact details.