mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 08:35:57 +00:00
114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
# 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.
|