@gotgenes/pi-permission-system 5.2.0 → 5.2.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.1](https://github.com/gotgenes/pi-permission-system/compare/v5.2.0...v5.2.1) (2026-05-05)
+
+
+### Documentation
+
+* document subagent extension coexistence ([#97](https://github.com/gotgenes/pi-permission-system/issues/97)) ([9bf2972](https://github.com/gotgenes/pi-permission-system/commit/9bf29726de98d44d7cfd8963f666be37fe807c9a))
+* plan subagent extension coexistence documentation ([#97](https://github.com/gotgenes/pi-permission-system/issues/97)) ([4cf975f](https://github.com/gotgenes/pi-permission-system/commit/4cf975f505081c5df46b20a2dd2d65e9a9a877f9))
+* **retro:** add retro notes for issue [#96](https://github.com/gotgenes/pi-permission-system/issues/96) ([8757ffc](https://github.com/gotgenes/pi-permission-system/commit/8757ffc3f186d137c65aea7abde9a383335584f8))
+
 ## [5.2.0](https://github.com/gotgenes/pi-permission-system/compare/v5.1.2...v5.2.0) (2026-05-05)
 
 

package/README.md

@@ -519,6 +519,63 @@ When a delegated or routed subagent runs without direct UI access, `ask` permiss
 
 This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
 
+### Coexistence with Subagent Extensions
+
+Several pi-subagent extensions implement their own tool restriction mechanisms.
+These compose correctly with the permission system because the two operate at different layers: **visibility** (subagent extension) and **policy** (permission system).
+
+#### The two-layer model
+
+```text
+┌─────────────────────────────────────────────────────┐
+│  Layer 1 – Visibility  (subagent extension)          │
+│  Controls which tools are registered / active        │
+│  before the agent session starts.                    │
+├─────────────────────────────────────────────────────┤
+│  Layer 2 – Policy  (pi-permission-system)            │
+│  Controls allow / ask / deny decisions on every      │
+│  tool call, bash command, MCP operation, etc.        │
+└─────────────────────────────────────────────────────┘
+```
+
+#### Known subagent extensions and their mechanisms
+
+|Extension|Mechanism|Frontmatter key|
+|----|----------|----------|
+|[nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents)|`--tools` CLI allowlist passed to subprocess|`tools:` (CSV allowlist)|
+|[tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)|`session.setActiveToolsByName()` in-process filter|`disallowed_tools:` (CSV denylist)|
+|[HazAT/pi-interactive-subagents](https://github.com/HazAT/pi-interactive-subagents)|`PI_DENY_TOOLS` env var + `--tools` CLI allowlist|`deny-tools:` (CSV denylist), `spawning:` (bool)|
+
+#### Interaction rules
+
+1. **Hidden tool → permission system never sees it.**
+   If a subagent extension removes a tool from the active set, the permission system receives no registration or call event for that tool.
+   The permission policy for that tool is irrelevant — it is already gone.
+2. **Denied tool → hidden regardless of the subagent extension's allowlist.**
+   If the permission system denies a tool (via `deny` policy or tool filtering), it is removed from the active set before the agent starts.
+   A `tools:` allowlist in a subagent extension cannot restore a tool that the permission system has already hidden.
+3. **The two denylist mechanisms are additive, not conflicting.**
+   A tool blocked by either layer stays blocked.
+   Neither layer can silently re-enable what the other has blocked.
+
+#### `permission:` frontmatter is exclusive to this extension
+
+The `permission:` key in an agent's YAML frontmatter is read exclusively by `pi-permission-system`.
+It has no interaction with the `tools:`, `disallowed_tools:`, or `deny-tools:` keys consumed by subagent extensions.
+You can freely use both in the same agent file:
+
+```yaml
+---
+# Subagent extension: allow only bash and read_file in the subprocess
+tools: bash,read_file
+# pi-permission-system: still enforce ask on bash within those allowed tools
+permission:
+  bash: ask
+---
+```
+
+In this example the subagent extension restricts visibility to `bash` and `read_file`, and the permission system then gates every `bash` call with an `ask` prompt — both rules apply independently.
+
 ### Logging
 
 When the extension prompts, denies, or forwards permission requests, it can append structured JSONL entries under:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [