my-pi/pi-permission-system/docs/guides/upstream-issue-template.md

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

## 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 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.