mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 16:45:22 +00:00
126 lines
7.3 KiB
Markdown
126 lines
7.3 KiB
Markdown
---
|
|
issue: 98
|
|
issue_title: "Explore a shared permission frontmatter convention for pi-subagent extensions"
|
|
---
|
|
|
|
# Shared Permission Frontmatter Convention Guide
|
|
|
|
## Problem Statement
|
|
|
|
Three major pi-subagent extensions (nicobailon/pi-subagents, tintinweb/pi-subagents, HazAT/pi-interactive-subagents) each define their own tool restriction frontmatter keys (`tools:`, `disallowed_tools:`, `deny-tools:`).
|
|
Users must configure restrictions in two places — once for tool visibility in the subagent extension and again for ask/deny/allow policy in the `permission:` frontmatter.
|
|
Now that all prerequisites (#78, #29, #96, #97) are landed, we can propose the `permission:` frontmatter as a shared convention that provides richer semantics (ask/deny/allow), broader surface coverage (bash, MCP, skills, external directories), and a single configuration point.
|
|
|
|
## Goals
|
|
|
|
- Draft a self-contained guide (`docs/guides/permission-frontmatter-for-subagent-extensions.md`) explaining the convention, benefits, and adoption path for upstream extension authors.
|
|
- Include concrete frontmatter examples showing the flat format alongside existing subagent extension keys.
|
|
- Link to existing docs (`docs/subagent-integration.md`, `docs/event-api.md`) for deeper reference.
|
|
- Prepare template text for upstream issues/discussions to be opened on the three repos once the guide is reviewed.
|
|
|
|
## Non-Goals
|
|
|
|
- Changing any runtime behavior or code in this extension.
|
|
- Requiring upstream extensions to depend on or import our package.
|
|
- Defining a formal specification or versioned protocol — this is a convention proposal, not a contract.
|
|
- Actually opening the upstream issues — that is a manual outreach step after the guide is merged and reviewed.
|
|
|
|
## Background
|
|
|
|
### Existing Documentation
|
|
|
|
- `docs/subagent-integration.md` documents the two-layer model (visibility vs. policy) and coexistence rules.
|
|
- `docs/event-api.md` documents the event bus RPC for in-process permission queries and prompt forwarding.
|
|
- `config/config.example.json` shows the flat permission format.
|
|
- `schemas/permissions.schema.json` defines the schema.
|
|
|
|
### Permission Surfaces Involved
|
|
|
|
All surfaces are relevant to the guide since we're documenting the full capability:
|
|
|
|
- **tools** — per-tool allow/ask/deny
|
|
- **bash** — pattern-matched bash commands
|
|
- **mcp** — MCP tool-level policy
|
|
- **skill** — skill invocation policy
|
|
- **external_directory** — path-based access control
|
|
- **special** — special operations (subagent spawning, etc.)
|
|
|
|
### Prerequisites (all closed)
|
|
|
|
| Issue | Status | Purpose |
|
|
| ----- | ------ | ------------------------------------------------ |
|
|
| #78 | Closed | Correct README flat format examples |
|
|
| #29 | Closed | Event bus API for runtime permission queries |
|
|
| #96 | Closed | Permission forwarding with CLI-spawned subagents |
|
|
| #97 | Closed | Coexistence documentation |
|
|
|
|
## Design Overview
|
|
|
|
The guide is a standalone Markdown document aimed at extension authors (not end users).
|
|
It should answer:
|
|
|
|
1. **What is the `permission:` frontmatter?**
|
|
— A flat policy map in agent `.md` files that pi-permission-system reads.
|
|
2. **Why adopt it?**
|
|
— Richer semantics (ask), broader coverage (bash/mcp/skills/directories), forwarding support.
|
|
3. **How does it compose with existing keys?**
|
|
— The two-layer model: visibility first, then policy.
|
|
Both apply independently.
|
|
4. **What does adoption look like?**
|
|
— Extension authors document `permission:` as an optional key in their agent frontmatter docs.
|
|
They do NOT need to evaluate it — pi-permission-system handles that.
|
|
5. **Runtime integration (optional)** — Extensions running in-process can query policy via the event bus API instead of re-implementing evaluation.
|
|
|
|
### Flat Format (for reference in guide)
|
|
|
|
```typescript
|
|
// Per-agent frontmatter shape
|
|
interface AgentPermissionFrontmatter {
|
|
permission: FlatPermissionPolicy;
|
|
}
|
|
|
|
type FlatPermissionPolicy = {
|
|
"*"?: Decision; // universal fallback
|
|
[toolName: string]: Decision | PatternMap;
|
|
};
|
|
|
|
type Decision = "allow" | "ask" | "deny";
|
|
type PatternMap = { [pattern: string]: Decision };
|
|
```
|
|
|
|
## Module-Level Changes
|
|
|
|
| File | Action | Description |
|
|
| --------------------------------------------------------------- | ------ | ----------------------------------------------------------------- |
|
|
| `docs/guides/permission-frontmatter-for-subagent-extensions.md` | Add | Main guide document for upstream authors |
|
|
| `docs/guides/upstream-issue-template.md` | Add | Template text for issues to open on the three repos |
|
|
| `docs/architecture/target-architecture.md` | Update | Note the guide under "External Integration" or equivalent section |
|
|
| `README.md` | Update | Add a link to the guide in the documentation section |
|
|
|
|
## TDD Order
|
|
|
|
This is a docs-only change — no test cycles are needed.
|
|
|
|
1. **docs: add permission frontmatter convention guide for subagent extensions**
|
|
- Create `docs/guides/permission-frontmatter-for-subagent-extensions.md` with sections: motivation, the two-layer model, flat format reference, composition examples, runtime integration (event bus), adoption checklist.
|
|
2. **docs: add upstream issue template for subagent extension outreach**
|
|
- Create `docs/guides/upstream-issue-template.md` with customizable template text for nicobailon, tintinweb, and HazAT repos.
|
|
3. **docs: link permission frontmatter guide from README and target architecture**
|
|
- Update `README.md` docs section and `docs/architecture/target-architecture.md`.
|
|
|
|
## Risks and Mitigations
|
|
|
|
| Risk | Mitigation |
|
|
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Upstream authors reject the convention as too complex | Guide emphasizes that adoption is purely documentation — no code dependency, no schema enforcement. Extensions can ignore `permission:` entirely. |
|
|
| Flat format changes after guide is published | #78 is closed and the format is stable. Guide links to the schema for canonical reference. |
|
|
| Could this silently weaken a permission? | No. This is a documentation-only change. No runtime behavior is modified. |
|
|
| Users confused by two overlapping keys in frontmatter | Guide explicitly explains the two-layer model and includes examples showing both keys coexisting. |
|
|
|
|
## Open Questions
|
|
|
|
- Should we propose a formal "convention version" number in case the flat format evolves, or is linking to the schema sufficient?
|
|
Defer until upstream feedback arrives.
|
|
- Should the guide live in this repo or in a separate shared repo?
|
|
Start here; move to a shared location only if multiple extensions want to co-maintain it.
|