Permissions Module

Pattern-based permission rules, persistent approvals, and doom loop detection

Pattern-based rules let you allow, deny, or ask about tool calls — with persistent approvals and doom loop detection.

For the CLI, see praisonai permissions and Interactive Tool Approval.

To also block reads, writes, and shell commands outside a project root, see Workspace Boundary.

from praisonaiagents import Agent

agent = Agent(
    name="Safe Coder",
    instructions="Run shell commands safely",
    approval={
        "permissions": {
            "read:*": "allow",
            "bash:rm *": "deny",
            "*": "ask",
        },
    },
)
agent.start("List files in the project root")

The user prompts the agent; permission rules allow, deny, or ask before each tool executes.

How It Works

Two seams enforce a deny rule: the schema-hide seam at build time and the call-time gate — both for native and MCP tools.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent
   
   agent = Agent(
       name="CI Worker",
       instructions="Run safely without prompts",
       approval={
           "permissions": {
               "read:*": "allow",
               "bash:rm *": "deny",
           },
       },
   )
   agent.start("Check the deployment status")
   
2. With Configuration

   Use PermissionManager directly for programmatic rule management:

   from praisonaiagents.permissions import (
       PermissionManager,
       PermissionRule,
       PermissionAction,
   )
   
   manager = PermissionManager()
   manager.add_rule(PermissionRule(
       pattern="bash:rm *",
       action=PermissionAction.DENY,
       description="Block destructive commands",
   ))
   manager.add_rule(PermissionRule(
       pattern="read:*",
       action=PermissionAction.ALLOW,
   ))
   
   result = manager.check("bash:rm -rf /tmp")
   print(result.is_denied)  # True
   

   For YAML and CLI surfaces, see Declarative Permissions.

---

Auto-wiring from approval config

Passing approval={"permissions": {...}} to Agent(...) now attaches a PermissionManager automatically, so pattern-based rules both hide denied tools from the model and block them at call time.

from praisonaiagents import Agent

agent = Agent(
    name="CI Worker",
    instructions="Ship safely",
    approval={
        "permissions": {
            "read:*": "allow",
            "bash:rm *": "deny",   # hidden from the model + blocked at call time
            "*": "ask",
        },
    },
)
agent.start("Check the deployment status")

The agent accepts three shapes for permissions:

Shape	Behaviour
dict (flat "pattern": "action")	Loaded via PermissionManager(agent_name=...).load_rules_from_config(dict)
list / tuple of PermissionRule	Each rule added via add_rule
PermissionManager instance	Reused as-is — no throwaway manager, no ~/.praisonai/permissions/ disk I/O

Pass a pre-built manager to reuse it directly:

from praisonaiagents import Agent
from praisonaiagents.permissions import PermissionManager

mgr = PermissionManager(storage_dir="/tmp/policy")
mgr.load_rules_from_config({"bash:rm *": "deny", "read:*": "allow"})

agent = Agent(
    name="Deployer",
    instructions="Deploy safely",
    approval={"permissions": mgr},   # reused as-is
)

Wiring failures are non-fatal — logged at DEBUG. The preset frozenset tier and the call-time gate stay in effect.

---

MCP tools are gated uniformly

The same deny gate applies to MCP tools: both native functions and MCP tools flow through _execute_tool_impl, so deny hides and blocks them identically. MCP tools using a tool:<name> prefix are matched by rules against either the bare name or the prefixed form.

from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

agent = Agent(
    name="Ops",
    instructions="Run ops tasks",
    tools=MCP("http://localhost:8000/sse"),
    approval={
        "permissions": {
            "tool:delete_*": "deny",   # matches MCP-namespaced tool names
        },
    },
)
# delete_* MCP tools never appear in the schema and are blocked at call time
# with {"permission_denied": True}.

---

Permission Actions

Action	Description
ALLOW	Automatically allow the operation
DENY	Automatically deny the operation
ASK	Require user approval

Since praisonai-agents v1.6.91, tools matched as deny are also removed from the LLM-advertised set (function schema and system prompt) — not just blocked at execution. See Approval › How tools are pruned from the LLM.

---

Permission Modes

Global modes for subagent delegation — see Permission Modes for full details.

Mode	Value	Description
DEFAULT	default	Standard permission checking
PLAN	plan	Read-only exploration
ACCEPT_EDITS	accept_edits	Auto-accept file edits
DONT_ASK	dont_ask	Auto-deny all prompts
BYPASS	bypass_permissions	Skip all checks

---

Configuration Options

PermissionRule

Option	Type	Default	Description
pattern	str	—	Glob or regex pattern to match
action	PermissionAction	ASK	allow, deny, or ask
description	str	""	Human-readable description
is_regex	bool	False	Use regex instead of glob
priority	int	0	Higher priority rules checked first
agent_name	str	None	Apply to a specific agent only
enabled	bool	True	Whether the rule is active

PermissionManager

Option	Type	Default	Description
storage_dir	str	~/.praisonai/permissions	Directory for persistent approvals
agent_name	str	None	Filter rules to one agent
approval_callback	Callable	None	Custom callback for user approval
workspace_root	str	None	Optional project/workspace root. When set, shell and file targets that resolve outside this root emit a distinct external_dir:<parent>/* sub-target defaulting to ask. When None, no boundary check runs (backward compatible). See Workspace Boundary.

approve() — reusable scope kwargs

Available on PermissionManager.approve(target, approved, scope, agent_name, reusable_scope, pattern):

Option	Type	Default	Description
reusable_scope	bool	False	When True and scope is "session" or "always", store the derived prefix glob instead of the literal command. Ignored when pattern= is given.
pattern	str | None	None	Explicit pattern to record. Overrides both target and reusable_scope — lets a CLI/UI show the suggestion and let the user tweak it before saving.

PersistentApproval

Option	Type	Default	Description
pattern	str	—	Glob pattern this approval covers (fnmatch semantics)
approved	bool	—	Whether the action was approved
scope	str	"once"	once, session, or always
derived	bool	False	True when pattern was auto-generated by reusable-scope derivation. Gates a small bare-prefix match extension so bash:git status * also matches the bare bash:git status. User-authored globs stay pure fnmatch.

---

PermissionManager.approve()

Record an approval decision. Returns a PersistentApproval.

Arg	Type	Default	Description
target	str	—	The exact action being approved, e.g. "bash:git status -s"
approved	bool	—	True to allow, False to deny
scope	str	"once"	once (this call only), session (this process), always (persisted)
agent_name	str | None	None	Restrict this approval to one agent
reusable_scope	bool	False	Opt in to store a generalised prefix glob instead of the literal target (see Reusable command-prefix approvals). Ignored when scope="once".
pattern	str | None	None	Explicit pattern to store. Overrides both target and reusable_scope — useful when CLI/UI displays a suggested scope for the user to edit before saving.

---

PermissionManager.is_denied()

Cheap, callback-free helper used at schema-build time to hide tools the model can’t call.

def is_denied(self, tool_name: str, agent_name: Optional[str] = None) -> bool:
    """Return True if tool_name resolves to a hard deny.

    Only DENY hides the tool; ask/allow/no-match keep it visible so approval
    can still happen at execution time (defence in depth).

    Checks both bare and tool:<name> forms. Never consults the interactive
    approval callback — safe to call while assembling the schema.
    """

Returns True only when a matching rule resolves to a hard DENY. allow, ask, and the no-matching-rule default of ask all return False — those tools stay visible so approval can still run at call time. It checks both the bare name and the tool:<name> form, so a rule against either convention takes effect (important for MCP-namespaced names). Deny-wins is global: the first target form that resolves to DENY returns True.

Arg	Type	Default	Description
tool_name	str	—	Tool name to check — bare ("write_file") or namespaced ("tool:write_file")
agent_name	str | None	None	Restrict the check to one agent’s rules

from praisonaiagents.permissions import PermissionManager

mgr = PermissionManager()
mgr.load_rules_from_config({"write_file": "deny", "read_file": "allow"})

mgr.is_denied("write_file")       # True   -> hidden from the schema
mgr.is_denied("read_file")        # False  -> allow, stays advertised
mgr.is_denied("edit_file")        # False  -> no matching rule = ask, not deny
mgr.is_denied("tool:write_file")  # True   -> namespaced form

PermissionManager.is_denied(...) is a manager method — an exposure-time helper. PermissionResult.is_denied (documented above at the check() result) is a result attribute describing a single check() outcome. The method never calls the interactive approval callback; the attribute reflects an already-resolved decision.

---

Reusable command-prefix approvals

Approving git status once should not force a new prompt for git status -s. Opt in with reusable_scope=True on a session/always approval and PraisonAI derives a generalised glob from a small command-arity table:

Command approved	Stored pattern	Also allows
bash:git status -s	bash:git status *	bash:git status, bash:git status .
bash:npm run build	bash:npm run *	bash:npm run test, bash:npm run lint
bash:docker compose up -d	bash:docker compose *	bash:docker compose down, bash:docker compose logs
bash:ls -la	bash:ls *	bash:ls, bash:ls src/

from praisonaiagents.permissions import PermissionManager

manager = PermissionManager()

# Preview what would be stored (safe to call — never records anything)
suggested = manager.suggest_scope_pattern("bash:git status -s")
# → "bash:git status *"

# Record the approval with the reusable prefix
manager.approve(
    "bash:git status -s",
    approved=True,
    scope="always",
    reusable_scope=True,
)

manager.check("bash:git status").is_allowed   # True
manager.check("bash:git status .").is_allowed  # True
manager.check("bash:git commit").needs_approval  # True — different subcommand still asks

What is NOT generalised (conservative by design)

Input	Result	Why
bash:git (bare, no subcommand)	bash:git (literal)	A globbed prefix would auto-approve every git subcommand
bash:cd /tmp && rm x	literal	A &&/|/;/$()/> operator would swallow the second command into the reusable scope
bash:rm * (already a glob)	bash:rm * (unchanged)	The user has already declared the pattern they want
read:/etc/hosts	read:/etc/hosts (unchanged)	Only bash:/shell: targets are generalised
Unknown command (cowsay hello)	bash:cowsay *	Matches only trailing args, never the whole command space

The derived flag

A reusable-scope approval is stored with derived=True (persisted in approvals.json). That flag gates a small extra rule in PersistentApproval.matches: for a derived pattern that ends in " *" and starts with bash:/shell:, the bare prefix also matches. So bash:git status * (derived) matches both bash:git status -s and the plain bash:git status.

Your own hand-authored bash:rm * keeps exact fnmatch semantics: bash:rm does not match it, matching the behaviour you had before this feature.

Custom arity table

The default table covers common tools (git, gh, npm, pnpm, pip, cargo, go, docker, docker compose, kubectl, helm, python, pytest, ruff, apt, brew, systemctl, and more). Longest multi-word key wins (so docker compose beats docker). To override for one call, use the low-level helpers:

from praisonaiagents.permissions import derive_pattern, command_prefix

command_prefix(["mytool", "run", "job"], {"mytool": 2})
# → "mytool run"

derive_pattern("bash:mytool run job", {"mytool": 2})
# → "bash:mytool run *"

---

How It Works

Compound shell commands (&&, ||, |, subshells) are decomposed and evaluated independently — deny beats ask beats allow. See Command-Aware Permissions.

When workspace_root is set, any path that escapes the root emits an external_dir:<parent>/* sub-target — a first-class permission target alongside bash:, write:, and read:. Set it once to stop broad approvals from granting whole-machine access. See Workspace Boundary.

manager = PermissionManager()
manager.add_rule(PermissionRule(pattern="bash:rm *", action=PermissionAction.DENY))

manager.check("bash:cd /tmp && rm -rf x").is_denied  # True — rm in compound command

---

Best Practices

Deny destructive commands first

Add high-priority deny rules for bash:rm *, bash:sudo *, and similar patterns before broader allow rules.

Use session scope for repeated tools

Approve with scope="session" so a tool call doesn’t re-prompt every time in one run. For shell commands whose flags/args change (git status -s vs git status .), add reusable_scope=True so the approval covers the whole subcommand instead of just the literal string. See Reusable Approval Scopes.

Set per-agent rules for teams

Use agent_name on rules when a coder agent may write but a reviewer agent must stay read-only.

Watch for doom loops

DoomLoopDetector flags repeated identical tool calls — reset or change strategy when is_loop is true.

---

CLI Reference

The praisonai permissions subcommands let you manage permission rules from the terminal.

These subcommands were unreachable in earlier versions due to a lazy-loader bug. They are fully functional in the current release.

# List all active permission rules
praisonai permissions list

# Allow a pattern (e.g. allow all read operations)
praisonai permissions allow "read:*"

# Deny a pattern (e.g. deny all rm commands)
praisonai permissions deny "bash:rm *"

# Prompt user for approval matching a pattern
praisonai permissions ask "bash:*"

# Remove a rule
praisonai permissions remove "bash:rm *"

# Reset all rules to defaults
praisonai permissions reset

# Export rules to a file
praisonai permissions export rules.json

# Import rules from a file
praisonai permissions import-rules rules.json

Subcommand	Description
list	List all current permission rules
allow <pattern>	Add an allow rule for a tool call pattern
deny <pattern>	Add a deny rule for a tool call pattern
ask <pattern>	Add a rule to prompt the user for approval
remove <pattern>	Remove a rule matching the pattern
reset	Reset all rules to factory defaults
export <file>	Export all rules to a JSON file
import-rules <file>	Import rules from a JSON file

---

Related

Declarative Permissions

YAML, CLI, and Python permission policies

Command-Aware Permissions

How compound shell commands are evaluated

Workspace Boundary

Gate shell and file access outside your project root

Reusable Approval Scopes

Approve once, cover arg variants with prefix globs