pi-permission-explain

pi on its own has no permission gate. It stays minimal and extensible, so asking before a tool runs is something a package adds, and the package this extension hooks into is pi-permission-system. It puts a dialog in front of a tool call and waits for your answer.

The dialog shows technical facts: which tool, which rule matched, the raw command. That is enough when you wrote the rule and can still remember why, and less help at 1 AM on one you forgot about. This extension adds a key that works while the dialog is open: press it and a model explains the pending action, in one sentence, above the editor.

Features

• Press to explain: A hint appears above the editor while a permission dialog is open. Press the key and the explanation replaces the hint; press it again to hide it. The key is only intercepted while a dialog is open, so it keeps its usual meaning everywhere else.
• Covers every permission surface: bash commands, path reads and writes, MCP targets, and skills.
• No model call until you ask: The extension sends nothing until the key is pressed, so a prompt you already knew how to answer costs nothing and reaches no provider.
• Names the model: The line above the explanation says which model wrote it, so a weak model’s answer is not mistaken for a strong one’s.
• Subagent asks: When a subagent’s request is forwarded to your session, the explanation says which subagent asked.
• Configurable key and model: Both sit in a config file next to the extension.

Requirements

pi-permission-system has to be installed, since it fires the events this listens to. Without it there are no ask dialogs, so the extension loads and idles. Install only one permission system at a time.

A fork works if it emits the same permissions:ui_prompt and permissions:decision payloads, and the extension has been checked against @xzzpig/pi-permission-system. Permission packages that run their own mechanism and fire no events, such as pi-verdict, leave it doing nothing.

Install

pi install npm:pi-permission-explain

Usage

While a permission dialog is open, the hint sits above the editor:

Permission required
tool    : bash
command : git push origin main
rule    : git push*

ctrl+e: explain this action

▶ (y) Yes   (n) No   ...

Press the key and the hint becomes the explanation:

explain (AI · openai/gpt-5-mini)
Pushes your local main branch to the origin remote, publishing those commits.

Answering the dialog clears it.

The explanation renders in a widget above the editor, since pi-permission-system does not expose a way to put text inside its own dialog yet. The key works in the interactive TUI only, since it is read from terminal input; in RPC, JSON, and print modes there is no terminal to press a key in, so the hint never appears.

Configuration

Optional. Create <agent-dir>/extensions/permission-explain/config.json, which is usually ~/.pi/agent/extensions/permission-explain/config.json:

{
  "key": "ctrl+e",
  "model": "openai/gpt-5-mini"
}

Reload pi (/reload) after editing. Leave the file out and the defaults apply. A malformed file or an unparseable key is reported and the default is used.

Advisory only

The explanation is written by a model and can be wrong. It is marked (AI), the prompt asks the model to describe the action rather than call it safe, and the extension has no way to allow, deny, or change a decision. Read it as a hint about a command you half-remember, not as a verdict on whether to approve it. If you are not sure after reading the explanation, open the rule and check.