@0xkobold/pi-whitelist
A Three-State Permission System for AI Agent Tool Invocation
Install & Use
Copy this prompt and send it to your AI assistant (Claude / Cursor / TRAE / Codex / WorkBuddy etc.) to auto-install:
Help me install this AI Skill: @0xkobold/pi-whitelist. It is used for: A Three-State Permission System for AI Agent Tool Invocation Full Skill content: https://321skill.com/skills/0xkobold-pi-whitelist/raw/index.md Read that page and install it.
The prompt includes a link to the full Skill content. You can also view the full content.
This Skill addresses the lack of fine-grained permission control when AI agents invoke tools. In practical development, agents may be authorized to perform dangerous operations such as Bash commands, file editing, and network requests. Overly permissive rules can easily lead to data leaks or system damage, while an outright ban severely limits the agent's functionality. pi-whitelist provides an allow/deny/ask three-state judgment, enabling developers to precisely control each invocation based on the tool and its content, striking a balance between security and efficiency.
Usage is straightforward: simply import the PermissionManager and initialize it. By passing the tool name and invocation content to the check method, you receive an allow/deny/ask decision. You can then add persistent rules via addRule, which supports glob pattern matching (e.g., 'Bash(git *)' allows all git commands). Rules support two storage backends, MemorySettingsStore and FileSettingsStore, facilitating persistence across sessions. Utility functions like parseRuleString and serializeRuleString are also provided for parsing and serializing rule formats.
It is well-suited for teams or individuals needing to manage AI agent tool invocation permissions, especially those already using AI coding assistants like Claude, Trae, or Cursor, who wish to protect user privacy, block dangerous operations, and prevent API abuse. Agent developers, backend engineers, and DevOps engineers can use it to define a security policy, allowing the AI to work autonomously within safe boundaries.
It is recommended to configure this tool uniformly during Agent initialization and use it in conjunction with project-wide security rules. Note that it primarily handles single-invocation decisions and is suitable for single-machine or lightweight deployment scenarios. For large-scale distributed permission management, consider integrating it with an external policy engine. Rule matching follows the order of addition, with priority given to earlier rules, so it's advisable to place specific rules before broader ones.
Key Features
Unlike simple allow/deny black-and-white lists, pi-whitelist supports a three-state (ask) option for temporary user confirmation. It features built-in glob pattern matching and multiple persistent storage backends. In contrast, similar tools like agent-tool-policy typically offer only simple allow/deny lists or rely on external policy services.
Limitations
Currently supports only TypeScript/JavaScript environments, requiring Node.js 16+ or a modern browser. The built-in storage backends only support memory and file storage, making it unsuitable for high-concurrency distributed scenarios.
FAQ
How do I add a rule that always allows an action?
Use `manager.addRule({ toolName: 'Bash', ruleContent: 'git *' }, 'allow', 'projectSettings')`. The second parameter, 'allow', indicates permanent permission.
Which tools are supported?
Any tool name is supported, such as Bash, FileEdit, Read, Write, etc., and works with glob pattern matching for the tool invocation content.
Installation guide for AI assistants
If your AI coding assistant (Claude Code, Cursor, TRAE etc.) can see this page, send it this message to auto-install:
Visit https://321skill.com/skills/0xkobold-pi-whitelist/raw/index.md to read the original Skill definition (Markdown format) for @0xkobold/pi-whitelist, and install it according to the instructions.
Raw Markdown URL for AI: /skills/0xkobold-pi-whitelist/raw/index.md