Reusable Approval Scopes

Approve a command once and cover every trailing-arg variant with an arity-derived prefix glob

Reusable scopes let one persistent approval cover every trailing-arg variant of the same command — approve git status and future git status -s runs never re-prompt.

Quick Start

1. Enable reusable scopes on your Agent

   Add one line to opt in — approval fatigue drops immediately:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Shell Assistant",
       instructions="Run git commands the user asks for",
       tools=["shell"],
       approval={"reusable_scope": True},
   )
   
   agent.start("Show me the status and then the last five commits")

   The first time the agent runs git status -s, the user sees the prompt once. Every subsequent git status <flags> variant is auto-approved for the session.

2. Preview and store scopes programmatically

   For advanced workflows — CLIs, approval UIs, or testing — call the PermissionManager API directly:

   from praisonaiagents.permissions import PermissionManager
   
   mgr = PermissionManager()
   
   suggested = mgr.suggest_scope_pattern("bash:git status -s")
   print(suggested)
   # => "bash:git status *"
   
   mgr.approve(
       target="bash:git status -s",
       approved=True,
       scope="always",
       reusable_scope=True,
   )

   suggest_scope_pattern() lets you surface the derived pattern in your UI before committing it, so users can review what always will cover.

3. Inspect the suggested pattern before saving

   from praisonaiagents.permissions import PermissionManager
   
   manager = PermissionManager()
   
   suggested = manager.suggest_scope_pattern("bash:git status -s")
   print(suggested)  # 'bash:git status *'
   
   approval = manager.approve(
       target="bash:git status -s",
       approved=True,
       scope="always",
       pattern=suggested,
   )

   Pass pattern= to override the derived pattern with any string you prefer.

4. Persistence round-trip

   import tempfile
   from praisonaiagents.permissions import PermissionManager
   
   with tempfile.TemporaryDirectory() as d:
       mgr1 = PermissionManager(storage_dir=d)
       mgr1.approve(
           "bash:git log --oneline",
           approved=True,
           scope="always",
           reusable_scope=True,
       )
   
       # Reload from disk
       mgr2 = PermissionManager(storage_dir=d)
       print(mgr2.check("bash:git log --oneline -5").is_allowed)  # True

How It Works

When reusable_scope=True and scope is "session" or "always", PermissionManager.approve() calls suggest_scope_pattern() internally. That delegates to arity.derive_pattern(), which looks up the command in a small arity table and builds a glob.

The stored PersistentApproval has derived=True, which enables a bare-prefix fallback in matches(): bash:git status * (derived) also matches the bare bash:git status.

The Arity Table

arity.derive_pattern uses this built-in table to decide how many leading tokens to keep as the reusable prefix.

Behaviour table

Escape hatches — these always stay literal:

The bare-single-token rule is the most important: approving bash:git stays literal — it never automatically covers bash:git push --force.

Extend the arity table for your own tools

Pass a custom arity_map to derive_pattern() to add commands not in the built-in table:

from praisonaiagents.permissions import derive_pattern

my_tools = {"mytool": 2, "mytool sub": 3}

pattern = derive_pattern("bash:mytool sub action --flag", arity_map=my_tools)
print(pattern)
# => "bash:mytool sub action *"

What Never Gets Generalised

derive_pattern is conservative. These cases always return the literal target unchanged:

• Non-shell targets — anything that doesn’t start with bash: or shell:.
• Empty commands — bash: with no command string.
• Existing globs — targets already containing * or ?.
• Shell control operators — targets containing &&, ||, |, ;, &, $(, ` `, >, <`, or a newline.
• Bare single-token commands — bash:git, bash:ls — never become bash:git *.

This prevents a compound-command approval from silently expanding its scope to cover a second unrelated command.

How this differs from skill grants

Reusable prefix scopes (bash:git *) live on the PermissionManager and cover any matching tool call within that agent’s scope. Skill allowed-tools auto-approval is separate: it is keyed to the specific agent instance that activated the skill, not to a command prefix.

Two unnamed Agent() instances (both defaulting to name="Agent") never share a skill grant, because each carries a unique per-instance approval-scope id. See Tool Approval → Scope of a skill grant.

Common Patterns

Approve once, cover all trailing-arg variants

from praisonaiagents.permissions import PermissionManager

manager = PermissionManager()

manager.approve("bash:git status -s", True, scope="always", reusable_scope=True)

manager.check("bash:git status").is_allowed          # True
manager.check("bash:git status --short").is_allowed  # True
manager.check("bash:git status").is_allowed          # True (bare form)
manager.check("bash:git push").is_allowed            # False — new prompt

Bare command stays literal

manager.approve("bash:git", True, scope="always", reusable_scope=True)

approval = manager.check("bash:git")
print(approval.pattern)  # 'bash:git'  — NOT 'bash:git *'

Compound commands stay literal

manager.approve("bash:cd /tmp && rm x", True, scope="always", reusable_scope=True)

approval = manager.check("bash:cd /tmp && rm x")
print(approval.pattern)  # 'bash:cd /tmp && rm x'  — literal, not generalised

Session vs Always scope

from praisonaiagents.permissions import PermissionManager

mgr = PermissionManager()

mgr.approve(
    target="bash:npm run build",
    approved=True,
    scope="session",
    reusable_scope=True,
)

mgr.approve(
    target="bash:git status -s",
    approved=True,
    scope="always",
    reusable_scope=True,
)

Use session for exploratory work and always only for commands you trust unconditionally across all future sessions.

Preview before storing

from praisonaiagents.permissions import PermissionManager

mgr = PermissionManager()

targets = [
    "bash:git log --oneline",
    "bash:npm run test",
    "bash:docker ps",
]

for t in targets:
    print(f"{t!r}  →  {mgr.suggest_scope_pattern(t)!r}")

'bash:git log --oneline'  →  'bash:git log *'
'bash:npm run test'       →  'bash:npm run *'
'bash:docker ps'          →  'bash:docker *'

Preview and override before saving

from praisonaiagents.permissions import PermissionManager

manager = PermissionManager()

target = "bash:npm run build"
preview = manager.suggest_scope_pattern(target)
# preview = "bash:npm run *"

# User narrows the scope — override with explicit pattern
manager.approve(
    target=target,
    approved=True,
    scope="session",
    pattern="bash:npm run build",  # explicit override: stays literal
)

Custom arity map for project-specific commands

from praisonaiagents.permissions.arity import derive_pattern

# Teach the engine about your own CLI tool
custom_map = {"mycli": 2}
pattern = derive_pattern("bash:mycli deploy prod", arity_map=custom_map)
print(pattern)  # "bash:mycli deploy *"

Best Practices

from praisonaiagents.permissions import PermissionManager

mgr = PermissionManager()
pattern = mgr.suggest_scope_pattern("bash:rm -rf /tmp/build")
print(f"This will auto-approve: {pattern}")

mgr.approve(target="bash:git status -s", approved=True, scope="session", reusable_scope=True)

from praisonaiagents.permissions import derive_pattern

corp_tools = {
    "deploy": 2,
    "deploy rollback": 2,
}

pattern = derive_pattern("bash:deploy rollback service-a --dry-run", arity_map=corp_tools)
# => "bash:deploy rollback *"

API Reference

PermissionManager.approve()

manager.approve(
    target: str,
    approved: bool,
    scope: str = "once",           # "once" | "session" | "always"
    agent_name: Optional[str] = None,
    reusable_scope: bool = False,  # derive prefix glob when True
    pattern: Optional[str] = None, # override target and derivation
) -> PersistentApproval

PermissionManager.suggest_scope_pattern()

manager.suggest_scope_pattern(target: str) -> str

Exception-safe wrapper around arity.derive_pattern. Returns the derived glob pattern, or the original target unchanged if derivation is not possible.

PersistentApproval.derived

Related