feat: vendor permission system source

2026-08-28 08:35:57 +00:00 · 2026-08-19 14:35:19 +08:00
parent 198584daf8
commit 410c50a3e5
809 changed files with 157793 additions and 139 deletions
@@ -0,0 +1,113 @@
+# Upstream Issue Template
+
+Template text for proposing the `permission:` frontmatter convention to subagent extension repositories.
+Customize the placeholders (`{{...}}`) for each target repo.
+
+---
+
+## Issue Title
+
+> Proposal: document `permission:` frontmatter for per-agent permission policy
+
+## Issue Body
+
+````markdown
+## Context
+
+Users of both `{{your-extension}}` and [`pi-permission-system`](https://github.com/gotgenes/pi-permission-system) currently configure tool restrictions in two places:
+
+1. **Tool visibility** via `{{your-key}}` in agent frontmatter (consumed by your extension)
+2. **Permission policy** via `permission:` in the same frontmatter (consumed by pi-permission-system)
+
+These two layers compose correctly today — there is no conflict — but users may not realize they can combine them in the same agent file.
+
+## Proposal
+
+Document the `permission:` key as an optional companion to `{{your-key}}` in your agent authoring docs.
+This is purely a documentation change — no code dependency on pi-permission-system is needed.
+
+### What `permission:` provides
+
+- **Three-state policy**: `allow`, `ask` (prompt the user), or `deny` — richer than binary allow/deny
+- **Multiple surfaces**: tools, bash commands (glob patterns), MCP operations, skills, external directories
+- **Prompt forwarding**: `ask` decisions in headless child agents surface in the parent session's UI
+- **Service accessor API**: other extensions can query policy at runtime via a `Symbol.for()`-backed accessor, with only a dynamic `import()` and no required peer dependency
+
+### Example
+
+```yaml
+---
+# {{your-extension}}: restrict visible tools
+{{your-key}}: {{example-value}}
+
+# pi-permission-system (optional): policy within the visible set
+permission:
+  "*": ask
+  read_file: allow
+  bash:
+    "*": ask
+    "git *": allow
+---
+```
+
+### Two-layer model
+
+```text
+Layer 1 – Visibility ({{your-extension}})
+  → Controls which tools are registered before the session starts
+
+Layer 2 – Policy (pi-permission-system)
+  → Controls allow/ask/deny decisions on every tool call, bash command, etc.
+```
+
+A tool hidden by Layer 1 is never evaluated by Layer 2.
+A tool denied by Layer 2 cannot be restored by Layer 1.
+Both mechanisms are additive — a tool blocked by either stays blocked.
+
+### What adoption requires from you
+
+1. Add a section to your README noting that `permission:` is an optional key consumed by pi-permission-system
+2. Show a combined example with `{{your-key}}` + `permission:`
+3. Link to the [convention guide](https://github.com/gotgenes/pi-permission-system/blob/main/docs/guides/permission-frontmatter-for-subagent-extensions.md) for full details
+
+No code changes, no new dependency, no schema enforcement.
+
+## References
+
+- [Convention guide](https://github.com/gotgenes/pi-permission-system/blob/main/docs/guides/permission-frontmatter-for-subagent-extensions.md)
+- [Subagent integration docs](https://github.com/gotgenes/pi-permission-system/blob/main/docs/subagent-integration.md)
+- [Cross-extension API docs](https://github.com/gotgenes/pi-permission-system/blob/main/docs/cross-extension-api.md)
+````
+
+---
+
+## Per-Repository Customization
+
+### nicobailon/pi-subagents
+
+| Placeholder          | Value                       |
+| -------------------- | --------------------------- |
+| `{{your-extension}}` | `pi-subagents`              |
+| `{{your-key}}`       | `tools`                     |
+| `{{example-value}}`  | `bash,read_file,write_file` |
+
+### tintinweb/pi-subagents
+
+| Placeholder          | Value              |
+| -------------------- | ------------------ |
+| `{{your-extension}}` | `pi-subagents`     |
+| `{{your-key}}`       | `disallowed_tools` |
+| `{{example-value}}`  | `write_file,bash`  |
+
+Additional note for tintinweb: since this extension runs subagents in-process via `createAgentSession()`, mention the [service accessor](https://github.com/gotgenes/pi-permission-system/blob/main/docs/cross-extension-api.md#service-accessor) as an optional runtime integration path for querying policy without spawning a subprocess.
+
+### HazAT/pi-interactive-subagents
+
+| Placeholder          | Value                      |
+| -------------------- | -------------------------- |
+| `{{your-extension}}` | `pi-interactive-subagents` |
+| `{{your-key}}`       | `deny-tools`               |
+| `{{example-value}}`  | `write_file,bash`          |
+
+Additional note for HazAT: this extension already uses `PI_DENY_TOOLS` env var for subprocess tool denial.
+The `permission:` frontmatter provides the same effect via `tool_name: deny` but adds `ask` as an intermediate option and covers surfaces beyond tools.