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.

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.

Doom-loop protection

A configured PermissionManager now delivers the doom-loop protection its docstring advertises (PR #5338). Whether built from approval={"permissions": {...}} or an explicit PermissionManager(...), its DoomLoopDetector runs at the live tool-execution gate.

The detector is consulted exactly once per approved tool call, with the final (post-approval, possibly rewritten) arguments — rejected attempts and arg rewrites don’t double-count against the threshold.

On a genuine loop, the gate blocks the call with a denial dict:

{
    "error": "Tool 'bash' blocked: repeated tool call",
    "permission_denied": True,
    "loop_blocked": True,
}

To override with a doom_loop: allow permission, see Approval → Doom-loop safety gate.

Per-tool limit is windowed. A single tool is flagged once it reaches max_tool_calls // 2 calls inside window_seconds — not over the agent’s lifetime. A healthy slow tool (e.g. a once-per-minute status poll) is never permanently denied, so long-running agents no longer need reset_tool() to recover. Lifetime totals are still reported by get_stats() (PR #5959, fixes #5957).

Thread-safe. The detector holds an internal RLock around record, check, record_and_check, get_stats, reset, and reset_tool, so it is safe to share across concurrent tool-execution gates.

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.

Built-in Secret-File Read Gate

Reading a .env or private-key file and forwarding its contents to the model provider is a silent secret-leak path. The core permission manager closes it by defaulting reads of well-known credential-file names to ask — even when a broad "read:*": "allow" rule is in effect. Safe example/template files stay allowed, and explicit user rules always override.

Gated basenames

Case-insensitive fnmatch against the file’s basename (path prefix ignored — config/.env and .env both gate).

Not gated (safe siblings)

Documentation templates without real secrets fall through to normal rules — a broad read:* allow reads them without prompting:

Override precedence

What counts as “secret-specific”?

A rule is a secret-specific opt-in when its glob does not match ordinary files. A glob that also matches ordinary files (like read:*) is treated as broad and does not silently authorise secrets:

Quick-start examples

1. Default — reading .env prompts

   Reading .env prompts for approval — no configuration required.

   from praisonaiagents import Agent
   
   agent = Agent(name="Coder", instructions="Help me refactor")
   agent.start("Read .env and tell me the DB host")
   # > Approve read:.env ? [y/N]:

2. Opt in — secret-specific allow

   Add a secret-specific allow rule — a broad read:* alone won’t do.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="CI Runner",
       instructions="Ship the release",
       approval={
           "permissions": {
               "read:*": "allow",      # ordinary files auto-read
               "read:*.env": "allow",  # explicit opt-in for .env
           },
       },
   )

3. Harden — secret-specific deny

   Add a secret-specific deny rule to reject even with user approval.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Sandboxed",
       instructions="Never touch credentials",
       approval={"permissions": {"read:*.env": "deny"}},
   )

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:

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

Permission Modes

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

Configuration Options

PermissionRule

PermissionManager

approve() — reusable scope kwargs

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

PersistentApproval

PermissionManager.approve()

Record an approval decision. Returns a PersistentApproval.

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.

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

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:

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)

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 *"

Approval scope lifecycle

PersistentApproval.scope controls how long an approval lives.

sequenceDiagram
    participant Agent
    participant Mgr as PermissionManager
    participant Store as approvals.json

    Note over Agent,Mgr: scope="once"
    Agent->>Mgr: check("bash:git status")
    Mgr-->>Agent: allow (consume approval)
    Agent->>Mgr: check("bash:git status")
    Mgr-->>Agent: ask (approval was consumed)

    Note over Agent,Mgr: scope="session" / "always"
    Agent->>Mgr: check("bash:git status")
    Mgr-->>Agent: allow (keep approval)
    Agent->>Mgr: check("bash:git status")
    Mgr-->>Agent: allow (still cached)

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef mgr fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef store fill:#6366F1,stroke:#7C90A0,color:#fff
    class Agent agent
    class Mgr mgr
    class Store store

Approval-scope cleanup

Every Agent gets a globally-unique approval scope id at construction. Skill allowed-tools pre-approvals and “this session” human decisions are keyed by that id in a process-global registry, so PraisonAI knows exactly which grants belong to which agent.

Closing an agent reclaims those grants:

• Calling agent.close() / await agent.aclose() evicts only that agent’s entries — its skill auto-approvals, its “this session” decisions, and its per-context approval-cache keys. Every other agent’s grants stay intact.
• If you never call close(), __del__ releases the same scope when the agent is garbage-collected, so a server that creates one short-lived Agent per request/session no longer leaks approval entries. close() is still recommended for deterministic teardown, since finalizer timing is not guaranteed.

from praisonaiagents import Agent

# One short-lived agent per request in a long-running server
def handle_request(prompt: str) -> str:
    agent = Agent(name="Worker", instructions="Handle one request.")
    try:
        return agent.start(prompt)
    finally:
        agent.close()  # drops only this agent's approval grants

Crash-safe rule persistence

Persisted rules and approvals survive a crash byte-for-byte (PR #5357).

Saving a rule set writes to a temp file in the same directory, fsync-es it, then swaps it in with os.replace — an atomic operation. Serialisation happens before the target file is touched, so a crash, OOM kill, or a non-serialisable rule value leaves the previous good file intact.

A corrupt PermissionAllowlist file is moved aside and loaded as empty (fail-closed) — see Corrupt-allowlist quarantine.

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

CLI Reference

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

# 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

Related