my-pi/pi-permission-system/docs/plans/archive/0098-shared-permission-frontmatter-convention.md

issue, issue_title

issue	issue_title
98	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)

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