@gotgenes/pi-permission-system 18.0.2 → 18.1.1

package/docs/guides/permission-frontmatter-for-subagent-extensions.md

@@ -0,0 +1,201 @@
+# Permission Frontmatter for Subagent Extensions
+
+A convention guide for pi-subagent extension authors who want to offer users richer per-agent permission control.
+
+## Motivation
+
+Pi subagent extensions already let users restrict **which tools** an agent can see via frontmatter keys like `tools:`, `disallowed_tools:`, or `deny-tools:`.
+These binary allow/deny mechanisms are simple and effective for tool visibility.
+
+The `pi-permission-system` extension adds a second layer: **policy evaluation** with three states — `allow`, `ask`, and `deny` — across multiple permission surfaces (tools, bash commands, MCP operations, skills, external directories, and special operations).
+
+By documenting the `permission:` frontmatter key in your extension, you give users a single agent file that expresses both visibility restrictions (your extension) and runtime policy (the permission system) without any code coupling between the two extensions.
+
+## The Two-Layer Model
+
+```text
+┌──────────────────────────────────────────────────────┐
+│  Layer 1 – Visibility  (your extension)               │
+│  Controls which tools are registered / active         │
+│  before the agent session starts.                     │
+├──────────────────────────────────────────────────────┤
+│  Layer 2 – Policy  (pi-permission-system)             │
+│  Controls allow / ask / deny decisions on every       │
+│  tool call, bash command, MCP operation, etc.         │
+└──────────────────────────────────────────────────────┘
+```
+
+The two layers compose additively:
+
+1. A tool hidden by your extension is never seen by the permission system — policy for it is irrelevant.
+2. A tool denied by the permission system is removed from the active set before the agent starts — your extension's allowlist cannot restore it.
+3. Both denylist mechanisms are additive.
+   A tool blocked by either layer stays blocked.
+
+## The `permission:` Frontmatter Format
+
+The `permission:` key uses a flat policy map.
+Each top-level key is either a tool name (for per-tool policy) or a named surface (`bash`, `mcp`, `skill`, `external_directory`, `special`).
+The special key `"*"` is the universal fallback.
+
+### Minimal example
+
+```yaml
+---
+permission:
+  "*": ask
+  read: allow
+  write: deny
+---
+```
+
+This means: allow all read operations without prompting, deny all write operations, and ask the user for everything else.
+
+### Full example with bash patterns
+
+```yaml
+---
+permission:
+  "*": ask
+  read: allow
+  bash:
+    "*": ask
+    "git status": allow
+    "git diff *": allow
+    "npm test": allow
+  mcp:
+    "*": deny
+  skill:
+    "*": ask
+  external_directory:
+    "*": deny
+    "~/projects/*": allow
+---
+```
+
+### Composing with your extension's keys
+
+Users can freely combine `permission:` with your extension's tool restriction key:
+
+```yaml
+---
+# nicobailon/pi-subagents: restrict visible tools
+tools: bash,read_file,write_file
+
+# pi-permission-system: policy within the visible set
+permission:
+  "*": ask
+  read_file: allow
+  bash:
+    "*": ask
+    "git *": allow
+---
+```
+
+Both keys are read independently by their respective extensions.
+There is no key collision — `permission:` is exclusively consumed by `pi-permission-system`.
+
+## Permission Surfaces
+
+| Surface              | Key                  | Value format                 | Description                                |
+| -------------------- | -------------------- | ---------------------------- | ------------------------------------------ |
+| Tools                | `<tool_name>`        | `"allow" \| "ask" \| "deny"` | Per-tool invocation policy                 |
+| Bash                 | `bash`               | `{ pattern: decision }`      | Pattern-matched bash commands (glob-style) |
+| MCP                  | `mcp`                | `{ pattern: decision }`      | MCP tool-level policy                      |
+| Skills               | `skill`              | `{ pattern: decision }`      | Skill invocation policy                    |
+| External directories | `external_directory` | `{ pattern: decision }`      | Path-based access outside the project      |
+| Special              | `special`            | `{ pattern: decision }`      | Special operations (e.g. `subagent_spawn`) |
+| Universal fallback   | `"*"`                | `"allow" \| "ask" \| "deny"` | Applies when no specific rule matches      |
+
+Pattern maps use last-match-wins ordering: put broad catch-alls first and specific overrides after.
+
+## What Adoption Looks Like
+
+Adopting this convention does **not** require your extension to:
+
+- Import or depend on `pi-permission-system`
+- Evaluate the `permission:` key at runtime
+- Change your existing tool restriction mechanism
+
+Adoption means:
+
+1. **Document** the `permission:` key as an optional frontmatter field in your extension's README or agent authoring guide.
+2. **Explain** that it is consumed by `pi-permission-system` when both extensions are installed.
+3. **Show** a combined example with your extension's key alongside `permission:`.
+
+The permission system handles all evaluation, prompt dialogs, and policy enforcement independently.
+
+## Runtime Integration (Optional)
+
+If your extension runs subagents in-process (e.g. via `createAgentSession()`), you can optionally query the permission system's policy at runtime via the event bus API — no package import needed.
+
+### Querying policy
+
+```typescript
+const requestId = crypto.randomUUID();
+
+pi.events.on(
+  `permissions:rpc:check:reply:${requestId}`,
+  (raw) => {
+    const reply = raw as { success: boolean; data?: { result: string } };
+    if (reply.success) {
+      console.log(reply.data?.result); // "allow" | "deny" | "ask"
+    }
+  },
+);
+
+pi.events.emit("permissions:rpc:check", {
+  requestId,
+  surface: "bash",
+  value: "git push",
+  agentName: "Worker",
+});
+```
+
+### Forwarding permission prompts
+
+When a child agent encounters an `ask` permission and has no UI, the prompt can be forwarded to the parent session:
+
+```typescript
+const requestId = crypto.randomUUID();
+
+pi.events.on(
+  `permissions:rpc:prompt:reply:${requestId}`,
+  (raw) => {
+    const reply = raw as { success: boolean; data?: { approved: boolean } };
+    if (reply.success && reply.data?.approved) {
+      // proceed
+    } else {
+      // deny
+    }
+  },
+);
+
+pi.events.emit("permissions:rpc:prompt", {
+  requestId,
+  surface: "bash",
+  value: "rm -rf /tmp/build",
+  message: "Allow rm -rf /tmp/build?",
+  agentName: "Worker",
+});
+```
+
+If `pi-permission-system` is not installed, no reply arrives.
+Implement a timeout and treat no-reply as `deny` for graceful degradation.
+
+For full API documentation, see [Cross-extension API](../cross-extension-api.md).
+
+## Benefits for Your Users
+
+1. **Richer semantics** — `ask` is more useful than binary allow/deny; users can permit a tool but require approval for each invocation.
+2. **Unified config** — one `permission:` block per agent instead of separate restriction keys in multiple extensions.
+3. **Surface coverage** — policy covers bash patterns, MCP tools, skills, external directories, and special operations, not just tool names.
+4. **Forwarding** — permission prompts from headless child agents surface in the parent session's UI.
+5. **Programmatic access** — the event bus API lets your extension query policy at runtime without importing the package.
+
+## Further Reading
+
+- [Subagent Integration](../subagent-integration.md) — full coexistence documentation and interaction rules
+- [Cross-extension API](../cross-extension-api.md) — service accessor, event bus reference (decision broadcasts, RPC check, RPC prompt)
+- [Configuration](../configuration.md) — full policy reference including merge precedence
+- [Schema](../../schemas/permissions.schema.json) — canonical JSON Schema for the flat permission format

package/docs/guides/upstream-issue-template.md

@@ -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
+- **Event bus API**: other extensions can query policy at runtime without importing the package
+
+### 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 [Event Bus RPC](https://github.com/gotgenes/pi-permission-system/blob/main/docs/cross-extension-api.md#policy-query-rpc-deprecated) as an optional runtime integration path for querying or forwarding permission prompts 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.

package/docs/migration/legacy-to-flat.md

@@ -0,0 +1,365 @@
+# Migration guide: legacy format → flat permission format
+
+This guide covers migration from the pre-#66 config format to the flat `permission` format introduced in #66.
+
+## Summary of changes
+
+The old format had six top-level policy keys (`defaultPolicy`, `tools`, `bash`, `mcp`, `skills`, `special`).
+The new format has a single `permission` key whose top-level entries map surface names to actions.
+
+Runtime knobs (`debugLog`, `permissionReviewLog`, `yoloMode`) are **unchanged** and stay at the top level.
+
+## Checklist
+
+Go through each section below.
+For each key present in your config, apply the translation and remove the old key.
+
+- [ ] `defaultPolicy`
+- [ ] `tools`
+- [ ] `bash`
+- [ ] `mcp`
+- [ ] `skills`
+- [ ] `special`
+- [ ] Per-agent frontmatter
+
+## Translation reference
+
+### `defaultPolicy`
+
+`defaultPolicy` set per-surface fallback actions.
+In the flat format the universal fallback is `permission["*"]`; per-surface catch-alls are entries in the `permission` object.
+
+```jsonc
+// Before
+{
+  "defaultPolicy": {
+    "tools": "ask",
+    "bash": "ask",
+    "mcp": "ask",
+    "skills": "ask",
+    "special": "ask"
+  }
+}
+
+// After — all surfaces default to "ask" via the universal fallback
+{
+  "permission": {
+    "*": "ask"
+  }
+}
+```
+
+If surfaces had **different** defaults, express each one explicitly:
+
+```jsonc
+// Before
+{
+  "defaultPolicy": {
+    "tools": "allow",
+    "bash": "ask",
+    "mcp": "ask",
+    "skills": "ask",
+    "special": "deny"
+  }
+}
+
+// After
+{
+  "permission": {
+    "*": "allow",
+    "bash": "ask",
+    "mcp": "ask",
+    "skill": "ask",
+    "external_directory": "deny"
+  }
+}
+```
+
+### `tools`
+
+Each entry in `tools` maps a tool name to a permission.
+In the flat format, tool names are surface keys directly inside `permission`.
+
+```jsonc
+// Before
+{
+  "tools": {
+    "read": "allow",
+    "write": "deny",
+    "edit": "ask"
+  }
+}
+
+// After
+{
+  "permission": {
+    "read": "allow",
+    "write": "deny",
+    "edit": "ask"
+  }
+}
+```
+
+**Special case — `tools.bash` and `tools.mcp`:** These were catch-all overrides for their respective surfaces.
+In the flat format, use a string shorthand or an explicit `"*"` pattern:
+
+```jsonc
+// Before
+{
+  "tools": { "bash": "allow", "mcp": "deny" }
+}
+
+// After — string shorthand (equivalent to { "*": "allow" })
+{
+  "permission": {
+    "bash": "allow",
+    "mcp": "deny"
+  }
+}
+```
+
+### `bash`
+
+Bash patterns translate directly; the surface name stays `bash`.
+If you also had a `tools.bash` or `defaultPolicy.bash` value different from `defaultPolicy.tools`, add an explicit `"*"` catch-all pattern at the **start** of the object (so specific patterns placed after it override it via last-match-wins).
+
+```jsonc
+// Before
+{
+  "defaultPolicy": { "tools": "allow", "bash": "ask" },
+  "bash": {
+    "git status": "allow",
+    "git diff": "allow",
+    "git *": "ask",
+    "rm -rf *": "deny"
+  }
+}
+
+// After
+{
+  "permission": {
+    "*": "allow",
+    "bash": {
+      "*": "ask",
+      "git status": "allow",
+      "git diff": "allow",
+      "git *": "ask",
+      "rm -rf *": "deny"
+    }
+  }
+}
+```
+
+> **Note:** Pattern ordering matters within an object.
+> `normalizeFlatConfig` preserves insertion order, and `evaluate` uses last-match-wins.
+> Put broad catch-alls **first** and specific overrides **after** them.
+
+### `mcp`
+
+MCP patterns translate directly; the surface name stays `mcp`.
+
+```jsonc
+// Before
+{
+  "mcp": {
+    "mcp_status": "allow",
+    "mcp_list": "allow",
+    "exa:*": "allow",
+    "dangerous-server": "deny"
+  }
+}
+
+// After
+{
+  "permission": {
+    "mcp": {
+      "mcp_status": "allow",
+      "mcp_list": "allow",
+      "exa:*": "allow",
+      "dangerous-server": "deny"
+    }
+  }
+}
+```
+
+### `skills`
+
+The surface name changes from `skills` (plural) to `skill` (singular).
+
+```jsonc
+// Before
+{
+  "skills": {
+    "*": "ask",
+    "librarian": "allow",
+    "dangerous-*": "deny"
+  }
+}
+
+// After — note: "skills" → "skill"
+{
+  "permission": {
+    "skill": {
+      "*": "ask",
+      "librarian": "allow",
+      "dangerous-*": "deny"
+    }
+  }
+}
+```
+
+### `special`
+
+`special.external_directory` becomes a top-level surface key in `permission`.
+Other deprecated keys (`doom_loop`, `tool_call_limit`) are simply dropped.
+
+```jsonc
+// Before
+{
+  "special": {
+    "external_directory": "ask",
+    "doom_loop": "deny",
+    "tool_call_limit": "deny"
+  }
+}
+
+// After — doom_loop and tool_call_limit are removed entirely
+{
+  "permission": {
+    "external_directory": "ask"
+  }
+}
+```
+
+> **Note:** In the old format, `special.external_directory: "deny"` produced a rule with `matchedPattern: "external_directory"`.
+> In the flat format, the string shorthand produces `pattern: "*"`, so `matchedPattern` is now `"*"` when the explicit rule matches.
+
+## Full before/after example
+
+```jsonc
+// Before (legacy format)
+{
+  "$schema": "...",
+  "debugLog": false,
+  "permissionReviewLog": true,
+  "yoloMode": false,
+  "defaultPolicy": {
+    "tools": "ask",
+    "bash": "ask",
+    "mcp": "ask",
+    "skills": "ask",
+    "special": "ask"
+  },
+  "tools": {
+    "read": "allow",
+    "write": "deny"
+  },
+  "bash": {
+    "git status": "allow",
+    "git *": "ask"
+  },
+  "mcp": {
+    "mcp_status": "allow"
+  },
+  "skills": {
+    "*": "ask"
+  },
+  "special": {
+    "external_directory": "ask"
+  }
+}
+```
+
+```jsonc
+// After (flat format)
+{
+  "$schema": "...",
+  "debugLog": false,
+  "permissionReviewLog": true,
+  "yoloMode": false,
+  "permission": {
+    "*": "ask",
+    "read": "allow",
+    "write": "deny",
+    "bash": {
+      "git status": "allow",
+      "git *": "ask"
+    },
+    "mcp": {
+      "mcp_status": "allow"
+    },
+    "skill": { "*": "ask" },
+    "external_directory": "ask"
+  }
+}
+```
+
+## Per-agent frontmatter
+
+Frontmatter in agent `.md` files uses the same flat shape under the `permission` key.
+
+```yaml
+# Before (legacy nested shape)
+---
+permission:
+  defaultPolicy:
+    tools: allow
+  bash:
+    "git *": allow
+  tools:
+    mcp: deny
+  mcp:
+    exa_web_search_exa: allow
+  special:
+    external_directory: allow
+---
+```
+
+```yaml
+# After (flat shape)
+---
+permission:
+  "*": allow
+  bash:
+    "git *": allow
+  mcp:
+    "*": deny
+    exa_web_search_exa: allow
+  external_directory: allow
+---
+```
+
+Key differences from the old frontmatter:
+
+1. The `"*"` key (quoted in YAML) replaces `defaultPolicy.tools`.
+2. `tools.bash` / `tools.mcp` catch-alls become `bash: <state>` or `mcp: { "*": <state>, ... }`.
+3. `special.external_directory` becomes `external_directory` at the top level of `permission`.
+4. Any surface key now works in frontmatter — extension tool names and `mcp` are no longer silently ignored.
+
+## Behavioral differences
+
+### Agent scope catch-alls override parent scope patterns
+
+In the old format, `tools.bash: allow` (override layer) was lower priority than config-layer patterns from any scope, including global.
+In the flat format, `bash: allow` in an agent scope is a config-layer catch-all with **higher** priority than global-scope patterns (last-match-wins, agent rules come later).
+
+If you relied on global `rm -rf *: deny` surviving an agent's `tools.bash: allow`, you must now explicitly deny the pattern within the agent's own `bash` object:
+
+```yaml
+# Old agent frontmatter — global "rm -rf *": "deny" survived
+permission:
+  tools:
+    bash: allow
+
+# New agent frontmatter — must repeat the deny if you want it preserved
+permission:
+  bash:
+    "*": allow
+    "rm -rf *": deny
+```
+
+### `matchedPattern` for `external_directory`
+
+In the old format, an explicit `special.external_directory: "deny"` rule had `matchedPattern: "external_directory"`.
+In the flat format, `external_directory: "deny"` (string shorthand) has `matchedPattern: "*"`.
+Code that inspected `matchedPattern` to detect explicit external-directory config must be updated.