# @thurstonsand/pi-permissions

`pi-permissions` adds a permissions gate for Pi tool calls. You can write small TypeScript modules that inspect a pending tool call and either let it pass, ask the approver, or block it before it runs.

## Install

```bash
pi install npm:@thurstonsand/pi-permissions
```

Restart Pi after installing.

The package includes a user-only skill that helps you author and test permissions:

```text
/skill:create-permission Ask before the agent pushes Git commits
```

For local development from a clone:

```bash
pi -e ./extensions/index.ts
```

## Where you can write permissions

| Scope   | Location                                           | Loads when                                    |
| ------- | -------------------------------------------------- | --------------------------------------------- |
| User    | `~/.pi/agent/permissions/*.ts`                     | Every session                                 |
| Project | `.pi/permissions/*.ts`                             | You trusted the project                       |
| Package | `pi.permissions` or `permissions/` in a Pi package | The package is installed and not filtered out |

Permission modules are TypeScript modules, using the same basic trust model as Pi extensions. Project permissions only load once you trust the project, through Pi's trust prompt or by saving "Trust" with `/trust`. When Pi trusts a project on its own because its `.pi` holds nothing Pi gates, such as only `.pi/permissions`, those permissions stay unloaded and a notice points to `/trust`.

Hooks run in this order:

1. project-level permissions
2. user-level permissions
3. package-level permissions

and stops on the first hook that requests or blocks.

## Writing a permission module

A permission module default-exports a function. Register checks with `api.onToolUse()`. This module is also available as [`examples/git-commit.ts`](examples/git-commit.ts):

```ts
import {
  gitValueFlags,
  matchCommand,
  matchTool,
  request,
  type PermissionsAPI,
} from "@thurstonsand/pi-permissions";

const gitCommit = matchCommand({
  program: "git",
  subcommands: ["commit"],
  valueFlags: gitValueFlags,
  onMatch: () => request({ guidance: "Review the commit message before approving." }),
});

export default function permissions(api: PermissionsAPI) {
  api.onToolUse({
    name: "git commit",
    description: "Ask before the agent creates a commit.",
    handler(input) {
      return matchTool(input.tool, { bash: gitCommit });
    },
  });
}
```

![Git commit approval prompt](images/example-git-commit.png)

Each hook has:

- `name`: short label shown in prompts and logs
- `description`: explanation shown to the approver if a request is made
- `handler`: code that returns a decision, or returns nothing to keep evaluating other hooks

Handlers receive a `PermissionInput`:

```ts
input.cwd; // current Pi working directory
input.permissionRoot; // directory containing the permission module
input.tool; // normalized tool input
```

For built-in tools, `input.tool` includes typed convenience fields:

```ts
bash.command;
read.projectPath;
edit.absolutePath;
write.path;
```

For custom tools, use `isCustomToolInput()` or the `custom` branch of `matchTool()` to narrow by exact tool name.

Any tool may carry `tool.annotations`, the unverified hints its author declares (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). Pi's built-in MCP support names tools `mcp__<server>__<tool>` and passes along the hints each server declares.

Hooks also see calls that tools make on the model's behalf, such as the tool calls inside a `codemode` script. Approval notes and edits on those calls are relayed to the agent on the calling tool's result.

Decisions are one of:

```ts
return request(); // default request behavior
return request({
  guidance: "Check the target environment.",
  highlight: /production|prod-db/i,
  approveLabel: "Approve",
  editLabel: "Edit",
  rejectLabel: "Reject",
});
return block("Do not edit generated files directly.");
```

`guidance` adds request-specific text to the prompt. `highlight` emphasizes offending fragments of the tool detail with a string, RegExp, array of either, precomputed spans, or a callback that returns spans. If no highlight is provided, it uses the matched command by default. `approveLabel`, `editLabel`, and `rejectLabel` change the button labels for that request.

A highlight callback receives the rendered tool detail and returns half-open `{ start, end }` offsets. Use `highlightSpans(detail, pattern)` inside a callback when you need pattern matching plus a little extra filtering.

Useful exports:

| Export                          | Use                                                 |
| ------------------------------- | --------------------------------------------------- |
| `PermissionsAPI`                | Type for the module factory argument                |
| `request()`                     | Ask the approver before the tool runs               |
| `block()`                       | Block the tool with an agent-facing reason          |
| `matchTool()`                   | Branch on built-in and custom tool inputs           |
| `highlightSpans()`              | Resolve highlight strings, RegExps, and spans       |
| `parseShellCommand()`           | Parse bash into span-carrying simple commands       |
| `matchCommand()`                | Match bash by program, subcommand, or predicate     |
| `gitValueFlags`                 | Git value-taking flags for subcommand resolution    |
| `isBashToolInput()`             | Narrow a normalized tool input to Pi's `bash` tool  |
| `isReadToolInput()`             | Narrow to Pi's `read` tool                          |
| `isEditToolInput()`             | Narrow to Pi's `edit` tool                          |
| `isWriteToolInput()`            | Narrow to Pi's `write` tool                         |
| `isGrepToolInput()`             | Narrow to Pi's `grep` tool                          |
| `isFindToolInput()`             | Narrow to Pi's `find` tool                          |
| `isLsToolInput()`               | Narrow to Pi's `ls` tool                            |
| `isCustomToolInput(tool, name)` | Narrow to an extension/custom Pi tool by exact name |

## Examples

Every example below is also available as a runnable module in [`examples/`](examples/). Copy one into your user- or project-level permissions directory and adapt it to your workflow.

### [Ask before recursive forced removal](examples/destructive-removal.ts)

```ts
import {
  matchCommand,
  matchTool,
  request,
  type SimpleCommand,
  type PermissionsAPI,
} from "@thurstonsand/pi-permissions";

function isDestructiveRemoval(cmd: SimpleCommand): boolean {
  return cmd.programName === "rm"
    ? cmd.hasFlag("-r", "-R", "--recursive") && cmd.hasFlag("-f", "--force")
    : cmd.hasFlag("-delete");
}

const destructiveRemoval = matchCommand({
  program: ["rm", "find"],
  where: isDestructiveRemoval,
  onMatch: ({ commands }) => request({ highlight: commands.map((cmd) => cmd.span) }),
});

export default function permissions(api: PermissionsAPI) {
  api.onToolUse({
    name: "destructive removal",
    description: "Ask before recursive forced removal or find deletion.",
    handler(input) {
      return matchTool(input.tool, { bash: destructiveRemoval });
    },
  });
}
```

![Destructive removal approval prompt](images/example-destructive-removal.png)

`where` narrows matches by an arbitrary predicate the same way `subcommands` narrows by name; `onMatch` only fires when at least one command passes all filters.

### [Block reading `.env`](examples/block-env-read.ts)

```ts
import { block, matchTool, type PermissionsAPI } from "@thurstonsand/pi-permissions";

export default function permissions(api: PermissionsAPI) {
  api.onToolUse({
    name: "read env file",
    description: "Do not expose local secrets to the LLM.",
    handler(input) {
      return matchTool(input.tool, {
        read(tool) {
          if (tool.projectPath === ".env") {
            return block("Reading .env could expose local secrets to the LLM.");
          }
        },
      });
    },
  });
}
```

![Blocked .env read](images/example-block-env-read.png)

### [Ask before MCP tools that change something](examples/mcp-writes.ts)

```ts
import { type PermissionsAPI, request } from "@thurstonsand/pi-permissions";

export default function permissions(api: PermissionsAPI) {
  api.onToolUse({
    name: "MCP writes",
    description: "Ask before an MCP tool that is not read-only.",
    handler(input) {
      const { toolName, annotations } = input.tool;
      if (!toolName.startsWith("mcp__") || annotations?.readOnlyHint) return undefined;
      return request();
    },
  });
}
```

MCP servers that omit `readOnlyHint` are treated as able to change things, matching the MCP default.

### [Ask before a specific MCP tool](examples/github-release.ts)

Pi names MCP tools `mcp__<server>__<tool>`, after the server key in `mcp.json`, with any character other than letters, digits, and `_` replaced by `_`. If a server named `github` exposes `create_release`, you can match it like any other Pi tool. This works for direct tools and for calls made from `codemode` alike.

```ts
import { matchTool, request, type PermissionsAPI } from "@thurstonsand/pi-permissions";

export default function permissions(api: PermissionsAPI) {
  api.onToolUse({
    name: "GitHub release",
    description: "Ask before creating a GitHub release over MCP.",
    handler(input) {
      return matchTool(input.tool, {
        custom: {
          mcp__github__create_release() {
            return request({
              guidance: "Check the tag, target repository, and release notes.",
              approveLabel: "Create release",
              rejectLabel: "Cancel release",
            });
          },
        },
      });
    },
  });
}
```

![GitHub release approval prompt](images/example-github-release.png)

## Package-bundled permissions

A Pi package can ship permissions alongside the pi-native extensions, skills, prompts, or themes.

```json
{
  "name": "my-pi-package",
  "pi": {
    "extensions": ["./extensions/index.ts"],
    "permissions": ["./permissions/index.ts"]
  }
}
```

If `pi.permissions` is omitted, `pi-permissions` also checks for a top-level `permissions/` directory.

And you can choose exactly which permissions to use in your pi settings where you declare that package:

```json
{
  "packages": [
    {
      "source": "npm:my-pi-package",
      "permissions": ["permissions/*.ts", "!permissions/legacy.ts"]
    }
  ]
}
```

An empty `permissions` array disables permissions from that package.

## Responding to permission requests

When a hook returns `request()`, Pi pauses before running the tool.

Approving runs the tool. If the approver adds a note, that note is passed back into the session as context.

Rejecting blocks the tool. A rejection with a note tells the agent how to proceed; a rejection without a note aborts the current turn. Hitting `esc` also aborts the turn.

`ctrl+s` approves and disables the deciding permission check for the rest of the session branch, exactly as if you had approved and then run `/permissions disable <name>`. Any note drafted on the approve choice still travels with the approval.

For `bash` tool calls, **Edit** opens the command and an optional note in a multiline editor.

![Editing a bash command before approval](images/edit-command.png)

## Managing permissions

Use `/permissions` to review loaded hooks and choose which permission checks are enabled in the current session branch.

![Permissions summary](images/permissions-summary.png)

Inside the permissions modal:

- `j`/`k` or arrow keys navigate
- `space` toggles the selected permission
- `g` toggles all currently loaded permissions
- `enter` saves and closes
- `esc` closes without saving

Commands:

```text
/permissions
/permissions enable
/permissions disable
/permissions enable Git mutations
/permissions disable Git mutations
```

`/permissions enable` and `/permissions disable` apply to all permissions.

You can also toggle all currently loaded permissions via `Alt+P`, customizable in `~/.pi/agent/settings.json`:

```json
{
  "permissions": {
    "toggleShortcut": "alt+p"
  }
}
```

Run `/reload` after changing settings.

## Development

This repo uses mise for local commands.

```bash
mise run check
mise run test
```

Run Pi against the local extension entrypoint:

```bash
pi -e ./extensions/index.ts
```