pi-herdsman 0.3.1 → 0.4.0

package/docs/development/smoke-testing.md

@@ -15,16 +15,19 @@ Verify:
 ```sh
 node --version
 pi --version
-herdr --version
+herdr status --json
 herdr integration status
 ```
 
+The `herdr status --json` output is the Herdr 0.9 CLI protocol compatibility
+preflight. It must report a Herdr client version of `>=0.9.0`,
+`server.running` as `true`, and `server.compatible` as `true`.
+
 The supported repository contract requires:
 
 - Node `>=22.19.0`
 - Pi `>=0.84.2 <0.86.0`
-- herdr `>=0.8.0`
-- herdr Pi integration version `2` or newer
+- herdr `>=0.9.0`
 
 Run focused tests and other intermediate checks before this smoke suite. Do
 not format during smoke testing; complete smoke testing and review before the
@@ -189,9 +192,9 @@ Verify the native Definitions selector shows:
 Structured `agent list` should still retain exact deterministic metadata.
 
 Select a disposable bundled, project, or global definition and change its
-model, thinking, and enabled state. Confirm that project discovery requires a
-trusted project's `piHerdsman.projectAgents: true` setting and that these edits
-write global overrides only, not project files.
+model, thinking, and enabled state. Confirm that project discovery requires Pi
+project trust and that these edits write global overrides only, not project
+files.
 
 Verify unrelated frontmatter and body remain unchanged, `Use default` removes
 only the selected field, fresh definition delegations and session continuations
@@ -249,7 +252,7 @@ substitutes for these checks.
 | Discover leads across multiple workspaces                                                                                            | NOT RUN |
 | Exclude managed agents and the active Chief from leads                                                                               | NOT RUN |
 | Agent exclusion uses the production validated snapshot and stale/ambiguous generations fail closed                                   | NOT RUN |
-| Herdr `agent_status ?? status` lifecycle normalization is reflected                                                                  | NOT RUN |
+| Herdr `agent_status` lifecycle normalization is reflected                                                                            | NOT RUN |
 | Nested agent aggregation attaches only to the proven lead                                                                            | NOT RUN |
 | A blocked agent does not mark its lead `needs you`                                                                                   | NOT RUN |
 | Duplicate live agents, coordination records, or agent evidence fail closed                                                           | NOT RUN |

package/docs/getting-started.md

@@ -10,9 +10,8 @@ path.
 
 You need:
 
-- [herdr](https://github.com/herdrdev/herdr) `>=0.8.0`;
+- [herdr](https://github.com/herdrdev/herdr) `>=0.9.0`;
 - Pi `>=0.84.2 <0.86.0` (the version range tested for this release);
-- herdr Pi integration version `2` or newer;
 - Node `>=22.19.0`.
 
 Install or refresh the herdr Pi integration:
@@ -83,10 +82,10 @@ Stop all…
 
 `Running` is the complete authoritative live-agent inventory and focuses the
 selected pane directly. `Definitions` manages the effective bundled, project,
-and global agent definitions. Project definitions participate only when the
-trusted project setting `piHerdsman.projectAgents` is `true`; effective precedence
-is bundled < project < global. `Layout` controls whether newly started agents
-use tabs or splits. `Stop all…` is destructive emergency control.
+and global agent definitions. Trusted projects contribute definitions from
+`.pi/agents/`; effective precedence is bundled < project < global. `Layout`
+controls whether newly started agents use tabs or splits. `Stop all…` is
+destructive emergency control.
 
 See [`/agents` commands](reference/commands.md) for exact behavior.
 

package/docs/guides/agent-definitions.md

@@ -29,26 +29,23 @@ Project definitions are optional and live in the current project:
 <cwd>/.pi/agents/
 ```
 
-For example:
+Pi Herdsman discovers project definitions when Pi considers the project
+trusted. Precedence is:
 
 ```text
-.pi/
-├── settings.json
-└── agents/
-    └── reviewer.md
+bundled < project < global
 ```
 
-with project settings:
+Global definitions remain final user policy. For example:
 
-```json
-{ "piHerdsman": { "projectAgents": true } }
+```text
+.pi/
+└── agents/
+    └── reviewer.md
 ```
 
-They are discovered only when the trusted project settings contain
-`piHerdsman.projectAgents: true`. Precedence is `bundled < project < global`;
-global definitions remain final user policy. Project definitions apply only to
-their project cwd, and the Definitions UI writes global overrides, never
-project files.
+Project definitions apply only to their project cwd, and the Definitions UI
+writes global overrides, never project files.
 
 When Pi uses a custom agent directory, the global definitions live under that
 agent directory's `agents/` subdirectory.
@@ -56,6 +53,35 @@ agent directory's `agents/` subdirectory.
 A project or global definition whose `name` matches a lower-precedence
 definition overlays it. An unmatched definition is standalone.
 
+### Permission-aware extensions
+
+Agent definitions may include a `permission:` mapping for compatible
+permission-aware Pi extensions.
+
+[`pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system)
+can consume the same global or trusted project-local agent definition as Pi
+Herdsman:
+
+```yaml
+---
+name: reviewer
+tools: ["read", "ls", "find", "grep"]
+permission:
+  "*": deny
+  read: allow
+  ls: allow
+  find: allow
+  grep: allow
+---
+```
+
+Pi Herdsman accepts and preserves `permission:` but does not evaluate its
+contents or make authorization decisions from it. Managed agents also publish
+the conventional active-agent identity and subagent lineage metadata used by
+compatible extensions. Permission policy is effective only when the
+compatible permission extension is loaded in that Pi session. The permission
+extension is optional; Pi Herdsman does not install or depend on it.
+
 ## Enable or disable a definition
 
 Definitions are enabled by default. Set `enabled: false` in a matching project

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

@@ -57,8 +57,8 @@ Global definitions by default:
 A matching project or global name overlays the lower-precedence definition.
 
 An unmatched project or global definition is standalone. Project definitions
-are loaded from `<cwd>/.pi/agents/` only when trusted project settings set
-`piHerdsman.projectAgents` to `true`. Precedence is `bundled < project < global`.
+are loaded from `<cwd>/.pi/agents/` when Pi considers the project trusted.
+Precedence is `bundled < project < global`.
 
 All effective definitions are sorted and validated together, including every
 `agents` reference.
@@ -84,6 +84,7 @@ available actions; disabling a definition does not mutate that assignment.
 | `noBuiltinTools`        | boolean                                                               | Pi normal built-in tool policy                                    | `true` emits `--no-builtin-tools`.                                                                     |
 | `tools`                 | array of non-empty strings                                            | no explicit allowlist                                             | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array.          |
 | `excludeTools`          | array of non-empty strings                                            | no explicit exclusions                                            | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array.          |
+| `permission`            | mapping                                                               | absent                                                            | Opaque interoperability policy for permission-aware extensions; Pi Herdsman does not evaluate it.      |
 | `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`                | array of non-empty strings                                            | no explicit skill arguments                                       | Each value is passed unchanged as a Pi skill path/resource.                                            |
@@ -93,6 +94,10 @@ available actions; disabling a definition does not mutate that assignment.
 | `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.                                                              |
 
+`permission` is reserved for compatible permission extensions. Pi Herdsman
+accepts and preserves the mapping but does not validate its internal policy
+schema or make authorization decisions from it.
+
 Arrays supplied by an override replace the complete inherited array, including
 an explicit `[]`.
 
@@ -230,10 +235,13 @@ Pi base system prompt
 selected project/global context-file additions
     ↓
 shared herdr agent guidance
+    ↓
+<active_agent name="<definition>"/>
 ```
 
 The final effective body and shared guidance are delivered through private
-temporary prompt snapshots.
+temporary prompt snapshots. The active-agent tag is appended directly as
+interoperability metadata for compatible Pi extensions.
 
 ## Complete override example
 

package/docs/reference/commands.md

@@ -27,10 +27,10 @@ token. The enforced limits are bytes, not tokens.
 ## `/agents definitions`
 
 Opens the native Definitions menu for the effective bundled, project, and
-global roster. Project definitions are included only when the trusted project
-setting `piHerdsman.projectAgents` is `true`. Project participation is marked
-`[project]`; a global override adds `*` (so `[project] *` means both layers
-contribute). Edits write global overrides only.
+global roster. Project definitions are included when Pi considers the project
+trusted. Project participation is marked `[project]`; a global override adds
+`*` (so `[project] *` means both layers contribute). Edits write global
+overrides only.
 
 The details view can show:
 

package/docs/reference/configuration.md

@@ -106,16 +106,7 @@ delegation policy in `piHerdsman`.
 
 Those belong in Markdown agent definitions.
 
-Trusted project-local definitions can be enabled with this project-only
-discovery gate in `<cwd>/.pi/settings.json`:
-
-```json
-{ "piHerdsman": { "projectAgents": true } }
-```
-
-The default is disabled, and a global `projectAgents` value has no effect.
-This setting enables discovery only; agent models, tools, bodies, extensions,
-and delegation remain in Markdown definitions.
+Trusted project-local definitions are discovered from `<cwd>/.pi/agents/`.
 
 See:
 
@@ -131,9 +122,6 @@ herdr integration install pi
 herdr integration status
 ```
 
-Pi Herdsman requires integration version `2` or newer for supported native session
-identity/restore behavior.
-
 ## See also
 
 - [`/agents` commands](commands.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Asynchronous Pi agent orchestration with nested delegation, parallel execution, and supervision in herdr.",
   "license": "Apache-2.0",
@@ -38,20 +38,21 @@
     "skills": [
       "."
     ],
-    "image": "https://raw.githubusercontent.com/boadij/pi-herdsman/main/docs/assets/banner.webp"
+    "image": "https://raw.githubusercontent.com/boadij/pi-herdsman/main/docs/assets/thumbnail.webp"
   },
   "scripts": {
     "test": "node --experimental-test-module-mocks --test --test-timeout=10000",
     "check": "node scripts/check.mjs",
     "build": "node scripts/build.mjs",
     "package:audit": "node scripts/package-audit.mjs",
-    "release:check": "npm run check && npm run build && npm run package:audit && npm publish --dry-run --ignore-scripts",
+    "validate": "npm run check && npm run build && npm run package:audit",
+    "release:check": "npm run validate && npm publish --dry-run --ignore-scripts",
     "prepack": "npm run build"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": ">=0.84.2 <0.86.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.2 <0.86.0",
+    "@earendil-works/pi-tui": ">=0.84.2 <0.86.0",
     "typebox": "*"
   },
   "devDependencies": {