pi-herdsman 0.44.0 → 0.45.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)
@@ -209,14 +209,14 @@ live in [Staff tools](../reference/staff.md).
209
209
 
210
210
  Coordination crosses one authority edge at a time:
211
211
 
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 |
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 / `notify_owner`, `await_owner`, `reply_agent` | owner <-> directly owned Agent |
220
220
 
221
221
  ### Coordination does not imply dependency
222
222
 
@@ -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
@@ -326,8 +327,8 @@ Verify:
326
327
  Launch a delegating managed agent with an explicit ordinary execution-tool
327
328
  allowlist and ask it to delegate one bounded scout task. Verify that it retains
328
329
  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
330
+ `await_owner`, then verify that the spawned scout is a leaf with its normal tools
331
+ and `await_owner` but no delegation tools. Also verify that role-required tools
331
332
  are not removed by `excludeTools`.
332
333
 
333
334
  For a definition with `tools` omitted, verify that launch does not add a
@@ -363,7 +364,7 @@ Verify the agent obeys that instruction through the expanded private prompt.
363
364
  Afterward remove the temporary definition and referenced file, confirm discovery
364
365
  no longer lists the temporary definition, and verify no repository file changed.
365
366
 
366
- ## `ask_owner` round trip
367
+ ## `await_owner` round trip
367
368
 
368
369
  Owner ask/reply remains manual, unautomated coverage.
369
370
 
@@ -371,7 +372,7 @@ Give an agent a task whose correct continuation requires an owner choice.
371
372
 
372
373
  Verify:
373
374
 
374
- 1. agent calls `ask_owner` alone;
375
+ 1. agent calls `await_owner` alone;
375
376
  2. owner receives one question;
376
377
  3. agent becomes `blocked`;
377
378
  4. owner replies with exact `reply_agent`;
@@ -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)
@@ -320,7 +320,7 @@ append-only and rejects `replace`. A custom replacement prompt does not
320
320
  automatically preserve Pi's normal system-prompt rules or tool guidelines.
321
321
 
322
322
  Managed agents additionally receive shared herdr agent guidance at launch,
323
- including the `ask_owner` contract. This shared guidance is infrastructure and
323
+ including the `notify_owner` and `await_owner` contracts. This shared guidance is infrastructure and
324
324
  is not copied into every bundled role body. Managed project Leads instead use
325
325
  the effective `managed-lead` body plus the ordinary Lead runtime charter and
326
326
  dynamic project coordination context.
@@ -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.
@@ -51,7 +51,7 @@ ordinary Pi tool selection.
51
51
 
52
52
  Code Mode does not add `bash`, `edit`, or `write` to a role's tool policy.
53
53
  Ordinary Lead profiles with explicit tools also enforce that policy during
54
- nested tool execution. `ask_owner` remains model-only and cannot be called from
54
+ nested tool execution. `await_owner` remains model-only and cannot be called from
55
55
  Code Mode scripts. `delegate_agent` and `continue_agent` are direct tools when
56
56
  active for the role; they return after acceptance, while completion arrives
57
57
  through the normal result-delivery mechanism. Other extensions may have
@@ -267,7 +267,7 @@ the fallback.
267
267
  | `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `false` | spawning controller for fresh `delegate`; saved session for `continue` | Explicit value wins; `false` launches as `off`. |
268
268
  | `systemPromptMode` | `append` or `replace` | `append` | Controls whether the effective body is appended to or replaces Pi's base system prompt. `replace` is an explicit escape hatch for ordinary custom definitions; `managed-lead` rejects it. |
269
269
  | `bodyMode` | `append` or `replace` | `replace` for non-empty matching overlay body | Valid only when overlaying an existing lower-precedence definition; consumed during body composition. |
270
- | `noTools` | boolean | Pi normal tool policy | `true` emits `--no-tools`; managed `ask_owner` remains infrastructure. |
270
+ | `noTools` | boolean | Pi normal tool policy | `true` emits `--no-tools`; managed `await_owner` and `notify_owner` remain infrastructure. |
271
271
  | `noBuiltinTools` | boolean | Pi normal built-in tool policy | `true` emits `--no-builtin-tools`. |
272
272
  | `tools` | array of non-empty strings | no explicit allowlist | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array. |
273
273
  | `excludeTools` | array of non-empty strings | no explicit exclusions | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array. |
@@ -378,7 +378,7 @@ ordinary tools permit it unless one of those opt-outs applies. An omitted or
378
378
  empty `agents` list always makes the agent a leaf, as does reaching the
379
379
  configured `maxAgentDepth` (see [Configuration](configuration.md)); the depth
380
380
  limit applies even to a definition that lists `agents`. Every managed agent
381
- receives `ask_owner`.
381
+ receives `await_owner` and `notify_owner`.
382
382
 
383
383
  The tool name `agent` is configuration-policy evidence only; it is not
384
384
  registered or callable. In `tools`, it opts into delegation when `noTools: true`
@@ -387,7 +387,7 @@ leaf, `agent` is removed from its `tools` list.
387
387
 
388
388
  `tools` and `excludeTools` configure ordinary execution tools, not this
389
389
  mandatory role infrastructure. They cannot remove required coordination tools
390
- or `ask_owner`. When `tools` is omitted, Pi Herdsman emits no `--tools` option
390
+ or `await_owner` and `notify_owner`. When `tools` is omitted, Pi Herdsman emits no `--tools` option
391
391
  and Pi's configured/default selection remains in effect. An explicit `tools`
392
392
  allowlist is augmented with the managed agent's mandatory role tools; the
393
393
  configuration-only `agent` name is excluded from that allowlist.
@@ -511,8 +511,8 @@ Additional local review instructions.
511
511
  ```
512
512
 
513
513
  Because `agents` is non-empty, and none of the delegation opt-outs apply, this
514
- managed agent receives all nine coordination tools and `ask_owner`, in
515
- addition to the explicitly selected ordinary tools.
514
+ managed agent receives all nine coordination tools and `await_owner` and
515
+ `notify_owner`, in addition to the explicitly selected ordinary tools.
516
516
 
517
517
  To disable a bundled role without copying its definition, use a minimal global
518
518
  override:
@@ -20,7 +20,7 @@ Use only tools currently listed there; do not infer control eligibility
20
20
  from `state` alone. `steer_agent` means active work accepts cooperative steering,
21
21
  `interrupt_agent` means a currently working Pi operation may be preempted,
22
22
  superseding earlier undelivered steering with replacement direction,
23
- `reply_agent` means a correlated pending `ask_owner` is valid, and
23
+ `reply_agent` means a correlated pending `await_owner` is valid, and
24
24
  `stop_agent` means exact direct ownership and the current applicable stop
25
25
  preflight permit teardown. For a
26
26
  Lead-owned parent, that preflight includes its owned descendant cascade.
@@ -46,7 +46,7 @@ non-direct descendants remain fail-closed with no actions.
46
46
 
47
47
  ## `blocked` and owner questions
48
48
 
49
- An agent waiting on a valid `ask_owner` reply projects as `blocked` after its ask
49
+ An agent waiting on a valid `await_owner` reply projects as `blocked` after its ask
50
50
  turn settles. Answer through the exact direct owner using `reply_agent` with the exact `agent` identity.
51
51
 
52
52
  A delegating parent can also project as `blocked` while it waits for direct
@@ -56,7 +56,7 @@ work may advertise `steer_agent` while remaining `blocked`; only the managed
56
56
  receiver's acknowledgement confirms acceptance. It does not advertise
57
57
  `interrupt_agent` unless a Pi operation is working. Recovery attention for
58
58
  `blocked` is reserved for a live Herdr runtime that reports `blocked` while an
59
- active request exists and no `ask_owner` question is pending.
59
+ active request exists and no `await_owner` question is pending.
60
60
 
61
61
  ## `settling`
62
62
 
@@ -90,7 +90,7 @@ model metadata, missing activity, a guessed session, or an old agent identity.
90
90
 
91
91
  When physical identity is ambiguous for an otherwise valid direct-owned record,
92
92
  Herdsman may emit one generic `unknown` attention event for that unresolved
93
- episode. It does not add mutation actions, prove loss, or broaden `ask_owner`.
93
+ episode. It does not add mutation actions, prove loss, or broaden `await_owner`.
94
94
  When exact physical evidence changes, re-evaluate the record from fresh state.
95
95
 
96
96
  `lost` is different: a coherent Herdr inventory proves the expected pane,
@@ -16,6 +16,7 @@ inspect_agent
16
16
  read_agent_transcript
17
17
  read_evidence
18
18
  attach_handoff
19
+ notify_owner
19
20
  ```
20
21
 
21
22
  Each tool accepts only its operation's fields. Schemas require necessary fields
@@ -256,7 +257,7 @@ covers the complete owned descendant cascade at every depth because closing the
256
257
  parent closes that cascade child-first. Invocation always reacquires current evidence and revalidates
257
258
  identity, ownership, mailbox state, durable results, and lifecycle before
258
259
  mutation. Active work may list `steer_agent`; a valid correlated pending
259
- `ask_owner` may list `reply_agent`. A currently working agent may list
260
+ `await_owner` may list `reply_agent`. A currently working agent may list
260
261
  `interrupt_agent`; a delegating agent blocked while waiting on children may
261
262
  still list `steer_agent` but not `interrupt_agent`.
262
263
  `available_tools` never lists `delegate_agent` or `continue_agent`: these are
@@ -304,6 +305,15 @@ attention event is an advisory snapshot of current authority; every later
304
305
  `steer_agent`, `interrupt_agent`, `reply_agent`, or `stop_agent` call revalidates identity, ownership,
305
306
  mailbox state, and lifecycle.
306
307
 
308
+ When several attention conditions are due in one scan, Herdsman submits their
309
+ original, independently identifiable messages together, with one triggering
310
+ message to wake the idle owner. Collection is limited by the existing
311
+ recipient fan-in message and byte budgets; overflow remains eligible for a
312
+ later scan. This scan-local budget is separate from the subsequent startup
313
+ fan-in budget. A scan attempts at most one first-time stale live diagnostic,
314
+ so additional initial stale inspections wait for another scan. Submission is
315
+ best-effort and is not an acknowledgment that the owner consumed a message.
316
+
307
317
  Persistent actionable attention may repeat while the same condition remains
308
318
  unresolved. Reminder timing is process-local and advisory, not a mailbox API;
309
319
  restarting may cause an unresolved condition to be reminded again. The normal
@@ -322,14 +332,14 @@ Generic attention reasons are:
322
332
 
323
333
  - `result_error`: a terminal result could not be durably persisted; follow the
324
334
  stored recovery details and `nextAction`;
325
- - `blocked`: the live Herdr runtime is blocked without a pending `ask_owner`
335
+ - `blocked`: the live Herdr runtime is blocked without a pending `await_owner`
326
336
  question;
327
337
  - `handoff`: an old durable request remains unacknowledged; do not duplicate or
328
338
  resubmit it because non-acknowledgement does not prove non-delivery;
329
339
  - `unknown`: physical identity is ambiguous and remains fail-closed, with no
330
340
  mutation actions and at most one attention event per episode.
331
341
 
332
- Stale and lost assignments, and delivered `ask_owner` questions, retain their
342
+ Stale and lost assignments, and delivered `await_owner` questions, retain their
333
343
  dedicated message types. Stale attention is advisory and does not by itself
334
344
  justify intervention. `settling` alone does not generate generic attention.
335
345
  The public `blocked` projection can also mean that a delegating parent is
@@ -339,7 +349,7 @@ from a live Herdr runtime reporting `blocked`.
339
349
  Initial attention eligibility is: stale after ten minutes without qualifying
340
350
  progress; lost, `result_error`, live runtime `blocked`, and physical `unknown`
341
351
  immediately; an old retained handoff after ten minutes; and a delivered
342
- `ask_owner` reminder approximately five minutes after health reconciliation
352
+ `await_owner` reminder approximately five minutes after health reconciliation
343
353
  first observes that the original ask was successfully delivered. The reminder
344
354
  path never duplicates first ask delivery. Unknown is the exception to repeated
345
355
  attention: it is one notification per unresolved physical-identity episode.
@@ -543,6 +553,13 @@ child editor.
543
553
  Cancellation uses Pi's native abort mechanism. Non-cooperative third-party
544
554
  tools may not stop immediately; `stop_agent` remains the destructive fallback.
545
555
 
556
+ ## `notify_owner`
557
+
558
+ Use `notify_owner` to send material information to your exact direct owner
559
+ while continuing the active assignment. It is nonblocking, accepts optional
560
+ evidence files, and does not create a reply obligation. See the
561
+ [`notify_owner` API](notify-owner.md) for acceptance and delivery semantics.
562
+
546
563
  ## `reply_agent`
547
564
 
548
565
  ```json
@@ -553,10 +570,10 @@ tools may not stop immediately; `stop_agent` remains the destructive fallback.
553
570
  ```
554
571
 
555
572
  Call `reply_agent` only when `available_tools` lists it for a valid correlated
556
- pending `ask_owner` question. The reply continues the same assignment and
573
+ pending `await_owner` question. The reply continues the same assignment and
557
574
  contains its request, ask, assignment, and session correlation evidence.
558
575
 
559
- See [`ask_owner` API](ask-owner.md).
576
+ See [`await_owner` API](await-owner.md).
560
577
 
561
578
  ## `stop_agent`
562
579
 
@@ -1,15 +1,15 @@
1
- # `ask_owner` API
1
+ # `await_owner` API
2
2
 
3
3
  [Documentation index](../README.md)
4
4
 
5
- `ask_owner` is mandatory managed agent infrastructure for one direct-owner
5
+ `await_owner` is mandatory managed agent infrastructure for one direct-owner
6
6
  decision required to continue the current assignment.
7
7
 
8
8
  It is not a generic messaging channel.
9
9
 
10
10
  ## Availability
11
11
 
12
- Every valid managed agent receives the `ask_owner` tool at launch.
12
+ Every valid managed agent receives the `await_owner` tool at launch.
13
13
 
14
14
  Normal definition `tools`, `excludeTools`, and `noTools` policy cannot remove
15
15
  this infrastructure capability.
@@ -37,7 +37,7 @@ working directory. This does not weaken the sole-final-tool-call rule.
37
37
 
38
38
  ## Turn rule
39
39
 
40
- `ask_owner` must be:
40
+ `await_owner` must be:
41
41
 
42
42
  - the agent's only tool call in the turn;
43
43
  - the final tool call of the turn.
@@ -59,8 +59,8 @@ An agent can ask only while it has a valid active assignment and:
59
59
 
60
60
  For a delegation-enabled agent, direct-agent state adds one gate:
61
61
 
62
- - no unresolved direct-agent work leaves normal `ask_owner` eligibility unchanged;
63
- - if unresolved direct agents exist, every unresolved child must have a valid pending `ask_owner`;
62
+ - no unresolved direct-agent work leaves normal `await_owner` eligibility unchanged;
63
+ - if unresolved direct agents exist, every unresolved child must have a valid pending `await_owner`;
64
64
  - ordinary active children, pending results, result errors, or unverifiable child asks block escalation.
65
65
 
66
66
  ## Durable effect
@@ -88,7 +88,7 @@ delivery path.
88
88
  The system does not automatically forward an agent question through an ownership
89
89
  chain.
90
90
 
91
- If a delegating agent needs a lead decision, it independently calls `ask_owner`
91
+ If a delegating agent needs a lead decision, it independently calls `await_owner`
92
92
  on its own direct ownership edge.
93
93
 
94
94
  ## Reply
@@ -120,7 +120,7 @@ the same assignment with the owner answer.
120
120
 
121
121
  ## One outstanding question
122
122
 
123
- Only one `ask_owner` question may be outstanding per assignment at a time.
123
+ Only one `await_owner` question may be outstanding per assignment at a time.
124
124
 
125
125
  There is no ask timeout.
126
126
 
@@ -0,0 +1,51 @@
1
+ # `notify_owner` API
2
+
3
+ [Documentation index](../README.md)
4
+
5
+ `notify_owner` sends material information to a managed Agent's exact direct
6
+ owner without blocking the assignment or requiring a reply.
7
+
8
+ ## Availability and request
9
+
10
+ Every valid managed Agent receives the tool, including leaf Agents and
11
+ Agents with active child work. It is available through direct Pi tool dispatch.
12
+
13
+ ```json
14
+ {
15
+ "message": "The upstream API changed; I am adapting the implementation.",
16
+ "files": ["findings.md"]
17
+ }
18
+ ```
19
+
20
+ `message` must contain non-whitespace text. Optional `files` use the same
21
+ strict UTF-8 and result-binding rules as managed-Agent handoffs. File content
22
+ is resolved and snapshotted before the notification is accepted.
23
+
24
+ ## Acceptance and delivery
25
+
26
+ Acceptance requires a valid active assignment that is not settling. Herdsman
27
+ atomically stores the notification in the Agent mailbox before reporting
28
+ success. At most eight undelivered notifications may be outstanding for one
29
+ Agent; a rejected call does not remove previously accepted records.
30
+
31
+ The notification goes only to the exact direct owner. Pi's persisted owner
32
+ session history confirms receipt. A successful message submission is not
33
+ confirmation; unresolved records remain durable and are reconciled after
34
+ restart. Because Pi message submission is asynchronous, recovery may replay a
35
+ notification if interruption occurred before its receipt became visible.
36
+ Delivery is therefore recoverable and may be at-least-once, not exactly-once.
37
+
38
+ Notifications do not set `pendingAskId`, block completion, or create a reply
39
+ obligation. The owner may use `steer_agent` when that operation is eligible.
40
+ Ordinary Agent cleanup waits until accepted notifications have confirmed
41
+ receipts. Explicit `stop_agent` retains its intentional abandonment behavior.
42
+
43
+ ## Choosing the owner tool
44
+
45
+ Use `notify_owner` when your direct owner needs material information but you
46
+ can continue working. Use `await_owner` only when your assignment cannot
47
+ proceed without the owner's answer. After an accepted `await_owner` call, end
48
+ your turn; Herdsman retains the blocked assignment until the owner replies.
49
+
50
+ See [`await_owner`](await-owner.md) for the blocking, correlated request
51
+ contract and [Agent tools](agent.md) for `steer_agent`.