pi-whitelist

Tri-state tool permission system (allow/deny/ask) for AI agent tool invocations

A standalone, runtime-agnostic npm module for controlling AI agent tool invocations.

Why?

Every AI agent that executes tools needs permission gating. Without it, agents can run destructive commands without oversight. pi-whitelist gives you a simple, battle-tested model:

#	Action	Behavior
1	Allow once	Let it run this time, don't persist
2	Allow always	Save a rule, auto-approve future matches
3	Deny	Block the invocation

Every check returns one of three decisions: allow, deny, or ask. No booleans, no ambiguity.

Install

npm install @0xkobold/pi-whitelist

Quick Start

import { PermissionManager } from '@0xkobold/pi-whitelist'

const manager = new PermissionManager()

// Read-only tools are auto-allowed
manager.check({ toolName: 'Read' })
// → { behavior: 'allow', decisionReason: { type: 'other', reason: 'read-only-tool' } }

// Destructive tools require approval
manager.check({ toolName: 'Bash', ruleContent: 'docker build .' })
// → { behavior: 'ask', message: 'Bash: docker build .', suggestions: [...] }

// Add an "allow always" rule
manager.addRule({ toolName: 'Bash', ruleContent: 'git *' }, 'allow', 'session')
manager.check({ toolName: 'Bash', ruleContent: 'git status' })
// → { behavior: 'allow', decisionReason: { type: 'rule', rule: ... } }

// Add a deny rule — deny always wins over allow for the same pattern
manager.addRule({ toolName: 'Bash', ruleContent: 'rm -rf *' }, 'deny', 'session')
manager.check({ toolName: 'Bash', ruleContent: 'rm -rf /tmp' })
// → { behavior: 'deny', message: 'Permission denied for Bash: rm -rf /tmp', ... }

Three-State UI Integration

const decision = manager.check({ toolName: 'Bash', ruleContent: 'docker build -t myapp .' })

if (decision.behavior === 'ask') {
  // Show the prompt:
  // ┌──────────────────────────────────────────────┐
  // │  Bash: docker build -t myapp .                │
  // │                                                │
  // │  1. Allow          (allow this once)           │
  // │  2. Allow always   (add rule to settings)      │
  // │  3. Deny           (block this invocation)     │
  // └──────────────────────────────────────────────┘
  const userChoice = await showPermissionPrompt(decision)

  if (userChoice === 1) {
    // Allow once — no persistence
    return { behavior: 'allow', decisionReason: { type: 'other', reason: 'user-allow-once' } }
  }
  if (userChoice === 2) {
    // Allow always — persist the rule
    manager.addRule(
      { toolName: 'Bash', ruleContent: 'docker *' },
      'allow',
      'projectSettings', // persists to .pi/settings.json
    )
  }
  if (userChoice === 3) {
    // Deny
    return { behavior: 'deny', message: decision.message, ... }
  }
}

Rule Format

Rules use the format ToolName or ToolName(content) with glob patterns:

Rule	Matches
Bash	Any Bash invocation
Bash(git *)	Any command starting with git
Bash(npm test)	Exactly npm test
FileEdit(/src/**)	Any file edit under /src/
Read	The Read tool (no content filter)
Bash(python -c "print\(1\)")	Commands with escaped parentheses

Permission Modes

Mode	Behavior
default	Prompt for destructive tools, auto-allow read-only tools
bypassPermissions	Allow everything — dangerous, for CI/testing only
plan	Ask for everything, even read-only tools
acceptEdits	Auto-allow file edits, ask for everything else
dontAsk	Allow everything not explicitly denied

const ci = new PermissionManager({ mode: 'bypassPermissions' })
ci.check({ toolName: 'Bash', ruleContent: 'rm -rf /' })
// → { behavior: 'allow', decisionReason: { type: 'mode', mode: 'bypassPermissions' } }

Rule Sources & Priority

Rules come from multiple sources, merged by priority (lowest → highest):

Source	File	Priority
userSettings	~/.pi/settings.json	0 (lowest)
projectSettings	.pi/settings.json	1
localSettings	.pi/settings.local.json	2
flagSettings	CLI flags	3
policySettings	Enterprise/org policy	4
cliArg	--allowedTools	5
command	/command in session	6
session	In-memory only	7 (highest)

Deny always wins over allow when both match the same tool+content.

Settings File

.pi/settings.json:

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(git *)",
      "Bash(npm test)",
      "FileEdit(/src/**)",
      "Read"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ],
    "ask": [
      "Bash(docker *)"
    ],
    "additionalDirectories": []
  }
}

API Reference

PermissionManager

The main class. Holds rules, resolves checks, persists changes.

const manager = new PermissionManager({
  store?: SettingsStore,              // Storage backend (default: MemorySettingsStore)
  mode?: PermissionMode,              // 'default' | 'bypassPermissions' | 'plan' | 'acceptEdits' | 'dontAsk'
  additionalWorkingDirectories?: Map<string, WorkingDirectorySource>,
  isBypassPermissionsModeAvailable?: boolean,
  shouldAvoidPermissionPrompts?: boolean,
})

Method	Description
check(input)	Evaluate a tool invocation against all rules
addRule(rule, behavior, source)	Add a rule and persist it
removeRule(rule, behavior, source)	Remove a matching rule
setMode(mode)	Switch permission mode
applyUpdates(updates)	Batch-apply permission updates
isBashAllowed(command)	Convenience: check if Bash command is allowed
isFileEditAllowed(path)	Convenience: check if file path edit is allowed
getRulesForTool(toolName)	Get all rules for a specific tool
getRulesFromSource(source)	Get all rules from a specific source
getContext()	Get the full permission context snapshot
invalidateCache()	Clear the rule evaluation cache

checkPermission(input)

Standalone one-shot check with default settings:

import { checkPermission } from '@0xkobold/pi-whitelist'

const decision = checkPermission({ toolName: 'Read' })
// → { behavior: 'allow', ... }

Matchers

Matcher	For	Behavior
GlobMatcher	Default fallback	Uses picomatch for glob matching
CommandMatcher	Bash, PowerShell	Splits on &&, ||, ;, | and checks prefix
FileMatcher	FileEdit, FileWrite	Normalizes paths to POSIX, uses picomatch

Storage

Store	Use
MemorySettingsStore	Testing, ephemeral sessions
FileSettingsStore	Persistent settings in .pi/settings.json

import { MemorySettingsStore, FileSettingsStore, mergeSettings } from '@0xkobold/pi-whitelist'

const mem = new MemorySettingsStore({ permissions: { allow: ['Bash(git *)'], deny: [], ask: [], additionalDirectories: [] } })
const file = new FileSettingsStore('.pi/settings.json')
await file.load()

Read-Only Tools

These tools auto-allow in default mode without prompting:

Read, FileRead, Glob, Grep, WebFetch, WebSearch, TaskGet, TaskList, TaskOutput, ListMcpResources, ReadMcpResource, ToolSearch, LSP, AskUser

Error Classes

Error	Code	When
PermissionError	Various	Base error class
RuleParseError	RULE_PARSE_ERROR	Malformed rule string
StorageError	STORAGE_ERROR	File read/write failure
MatcherError	MATCHER_ERROR	Glob/command matching failure

Subpath Exports

import { parseRuleString, serializeRuleString } from '@0xkobold/pi-whitelist/rules'
import { GlobMatcher, CommandMatcher, FileMatcher } from '@0xkobold/pi-whitelist/matchers'
import { MemorySettingsStore, FileSettingsStore, mergeSettings } from '@0xkobold/pi-whitelist/storage'
import type { PermissionDecision, PermissionRule, PermissionMode } from '@0xkobold/pi-whitelist/types'

Test

npm test        # Run all tests
npm run build   # Compile TypeScript

97 tests across 9 suites covering parser, matchers, storage, merge, errors, readonly, constants, manager, and check.

License

MIT