@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

pi install npm:@thurstonsand/pi-permissions

Restart Pi after installing.

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

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

For local development from a clone:

pi -e ./extensions/index.ts

Where you can write permissions

Permission modules are TypeScript modules, using the same basic trust model as Pi extensions. Project permissions only load after Pi trusts the project.

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:

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

const gitCommit = matchCommand({
  program: "git",
  subcommands: ["commit"],
  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 });
    },
  });
}

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:

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:

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:

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:

Examples

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

Ask before recursive forced removal

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 });
    },
  });
}

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

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.");
          }
        },
      });
    },
  });
}

Ask before MCP tools that change something

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

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.

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",
            });
          },
        },
      });
    },
  });
}

Package-bundled permissions

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

{
  "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:

{
  "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.

Managing permissions

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

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:

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

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

Run /reload after changing settings.

Development

This repo uses mise for local commands.

mise run check
mise run test

Run Pi against the local extension entrypoint:

pi -e ./extensions/index.ts