Command-Aware Permissions

Permission checks for shell tool calls now follow the command’s actual structure, so a deny rule fires even when the blocked command is hidden inside a compound, pipe, subshell, or substitution.

from praisonaiagents import Agent
from praisonaiagents.approval.protocols import ApprovalConfig

agent = Agent(
    name="Safe Worker",
    instructions="Run shell commands safely",
    approval=ApprovalConfig(permissions={
        "bash:rm *": "deny",
        "write:/etc/*": "deny",
        "*": "allow",
    }),
)

# All of these are now blocked, even though previously only the first was:
#   cd /tmp && rm -rf x
#   ls; rm -rf x
#   echo $(rm -rf x)
#   cat foo > /etc/hosts
agent.start("Tidy up /tmp")

The user approves shell tools; compound commands are parsed so hidden deny rules still block unsafe operations.

Quick Start

Block destructive commands — even in compound form

A single deny rule on bash:rm * now catches rm wherever it appears:

from praisonaiagents import Agent
from praisonaiagents.approval.protocols import ApprovalConfig

agent = Agent(
    name="Safe Worker",
    instructions="Run shell commands safely",
    approval=ApprovalConfig(permissions={
        "bash:rm *": "deny",
        "*": "allow",
    }),
)

agent.start("Clean up old files")

Commands like cd /tmp && rm -rf x, ls; rm -rf x, and echo $(rm -rf x) are all blocked — not just rm -rf x directly.

Protect files from redirect overwrites

Truncating redirections (>, >>) emit a write: sub-target. A write: deny rule catches them:

from praisonaiagents import Agent
from praisonaiagents.approval.protocols import ApprovalConfig

agent = Agent(
    name="Safe Worker",
    instructions="Run shell commands safely",
    approval=ApprovalConfig(permissions={
        "write:/etc/*": "deny",
        "*": "allow",
    }),
)

agent.start("Update system config")

cat foo > /etc/hosts and echo x >> /etc/hosts are blocked even though the command starts with cat / echo.

How It Works

Step	Action
1	Tool call arrives as `bash:<cmd>` target
2	`command_parser.parse_command` decomposes into `ShellOp` list
3	Each op evaluated as its own sub-target (`bash:<exe> <args>` and `write:<path>`)
4	Original compound target also evaluated (legacy flat-rule compatibility)
5	Aggregate: deny wins → ask → allow

What Gets Decomposed

Operator / Construct	Example	Result
`&&` (AND)	`cd /tmp && rm x`	`[cd, rm]`
`\|\|` (OR)	`ls \|\| rm x`	`[ls, rm]`
`;` (sequence)	`ls; rm x`	`[ls, rm]`
`\|` (pipe)	`cat foo \| rm x`	`[cat, rm]`
`&` (background)	`rm x &`	`[rm]`
Subshell `(...)`	`(cd /tmp && rm x)`	`[cd, rm]`
`$(...)` substitution	`echo $(rm -rf x)`	`[echo, rm]`
Backtick substitution	echo `rm -rf x`	`[echo, rm]`
Truncating redirect `>`	`cat foo > /etc/hosts`	`[cat] + write:/etc/hosts`
Append redirect `>>`	`echo x >> /etc/hosts`	`[echo] + write:/etc/hosts`
`>	`/`&>`/`&>>`	`cmd &> /tmp/log`	`[cmd] + write:/tmp/log`
fd-prefixed `2>` / `1>>`	`ls 2> err.txt`	`[ls] + write:err.txt`
Env-var assignment prefix	`FOO=bar rm x`	`[rm]`
Path-like arg outside workspace	`cat /etc/passwd`	`[cat] + external_dir:/etc/*`
Redirect target outside workspace	`echo x > ~/.bashrc`	`[echo] + external_dir:<home>/*`
Executable referenced by path outside workspace	`/tmp/tool.sh`	`[/tmp/tool.sh] + external_dir:/tmp/*`

The external_dir: rows above only apply when PermissionManager is created with workspace_root=.... See Workspace Boundary.

Single-quote suppression: echo '$(rm -rf x)' is a literal string — no rm is extracted. fd-to-fd redirects like 2>&1 are never treated as write targets. Input redirects (<, <<, <<<) — the filename is never mistaken for the executable.

Shell expansion escalates to ASK

Shell commands containing an expansion that cannot be statically resolved are escalated to ASK instead of being silently allowed by a broad rule. Before the tokenizer runs, the manager checks for $IFS, ${VAR}, and bare $VAR. If any is present, an explicit deny still wins; otherwise the request is escalated to ASK with the reason “Command contains shell expansion that cannot be statically verified; requires approval”. Command substitution ($(...) and backticks) is excluded — it is already decomposed per-op, so its inner commands keep matching deny rules.

Pattern	Example	Resolution
`$IFS` word-splitting	`rm${IFS}-rf${IFS}/`	`ASK` (deny still wins)
`${VAR}` expansion	`rm -rf ${TARGET_DIR}`	`ASK` (deny still wins)
Bare `$VAR`	`rm -rf $HOME`	`ASK` (deny still wins)
`$(...)` substitution	`echo $(rm -rf x)`	Decomposed per-op (existing behavior)
Backtick substitution	echo `rm -rf x`	Decomposed per-op (existing behavior)

from praisonaiagents import Agent
from praisonaiagents.approval.protocols import ApprovalConfig

agent = Agent(
    name="Safe Worker",
    instructions="Run shell commands safely",
    approval=ApprovalConfig(permissions={
        "bash:rm *": "deny",
        "bash:*": "allow",
    }),
)

# All of these now trigger ASK (or hit the explicit deny), not silent allow:
#   rm${IFS}-rf${IFS}/tmp/data      → ASK
#   rm -rf ${TARGET}                → ASK
#   rm -rf $HOME/downloads          → ASK
#   rm -rf /tmp/foo                 → DENY (matches bash:rm *)
agent.start("Clean up temp files")

Before this change, a broad bash:* allow could shadow a specific bash:rm * deny for anything containing ${IFS} or $HOME — a real permission bypass.

Evasions Now Blocked

A deny: bash:rm * rule now blocks all of these:

Command	Previous	Now
`bash:rm -rf /tmp`	denied	denied (unchanged)
`bash:cd /tmp && rm -rf x`	ALLOWED	denied
`bash:ls; rm -rf x`	ALLOWED	denied
`bash:cat foo \| rm x`	ALLOWED	denied
`bash:echo $(rm -rf x)`	ALLOWED	denied
`bash:echo \`rm -rf x“	ALLOWED	denied
`bash:(cd /tmp && rm -rf x)`	ALLOWED	denied
`bash:echo '$(rm -rf x)'` (single-quoted)	denied	allowed (correctly — literal)

Aggregation Precedence

When a compound command produces multiple sub-operations, their results are aggregated as: deny wins → then ask → then allow.

from praisonaiagents.permissions import PermissionManager, PermissionRule, PermissionAction

manager = PermissionManager()

manager.add_rule(PermissionRule(pattern="bash:*", action=PermissionAction.ALLOW))
manager.add_rule(PermissionRule(pattern="bash:cat *", action=PermissionAction.ASK))

result = manager.check("bash:ls && cat foo")
print(result.action)  # ASK — because cat triggered ask, and ask beats allow

Sub-op results	Aggregate
Any deny	deny
No deny, any ask	ask
All allow	allow

Workspace Boundary

When PermissionManager is created with workspace_root=..., an extra external_dir:<parent>/* sub-target is added for any path that escapes the root — whether it appears as a command argument, a redirect write-target, or an executable path. The same deny→ask→allow aggregation applies: external_dir:* → deny hard-blocks; external_dir:/data/* → allow pre-authorises; the default is ask. See Workspace Boundary for full details.

Fallback Behaviour

For simple single commands (bash:ls -la) with no compound operators, the engine defers to the existing flat matcher — exact backward compatibility. On any parse failure, the whole command is treated as a single op using today’s behaviour, so no existing rule is silently weakened.

Common Patterns

Block all destructive shell ops:

approval=ApprovalConfig(permissions={
    "bash:rm *": "deny",
    "bash:mv *": "deny",
    "bash:dd *": "deny",
    "*": "allow",
})

Protect a config directory from redirects:

approval=ApprovalConfig(permissions={
    "write:/etc/*": "deny",
    "*": "allow",
})

CI runner — deny by default, allow git only:

praisonai run "Deploy check" \
  --permission-default deny \
  --allow 'bash:git *'

Best Practices

Patterns match the executable name, not the full path

bash:rm * catches rm -rf /tmp but not bash:/usr/bin/rm -rf /tmp. Use a regex rule with is_regex: true for absolute-path coverage.

Single-quoted substitutions are literals

echo '$(rm -rf x)' is correctly not treated as an rm call — the parser respects single-quote suppression. Double-quoted substitutions are still extracted.

Protect filesystem locations with write: patterns, not bash: patterns

Truncating redirects produce a write:<path> sub-target. Use write:/etc/* to block overwrites — bash:cat * alone won’t catch cat foo > /etc/hosts.

Zero overhead when permissions are off

The command parser is lazy-imported: no parsing cost when permissions are not in use or the target is a non-shell tool.

Command-aware permissions decompose a compound command; Reusable Approval Scopes generalise a single command’s approval to a whole family.

Declarative Permissions

Pre-declare allow/deny rules in YAML, CLI, or Python

Permissions Module

Programmatic PermissionManager API

Permissions CLI

CLI rule management reference

Approval

Interactive approval backends

Workspace Boundary

Gate shell/file access outside a project root with external_dir:*

Reusable Approval Scopes

Generalise one approval to cover a whole command family

Command-aware permissions parse inside the command; the workspace boundary gates where on disk it can act.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Command-Aware Permissions

Quick Start

How It Works

What Gets Decomposed

Shell expansion escalates to ASK

Evasions Now Blocked

Aggregation Precedence

Workspace Boundary

Fallback Behaviour

Common Patterns

Best Practices

Declarative Permissions

Permissions Module

Permissions CLI

Approval

Workspace Boundary

Reusable Approval Scopes

​Quick Start

​How It Works

​What Gets Decomposed

​Shell expansion escalates to ASK

​Evasions Now Blocked

​Aggregation Precedence

​Workspace Boundary

​Fallback Behaviour

​Common Patterns

​Best Practices

​Related

Declarative Permissions

Permissions Module

Permissions CLI

Approval

Workspace Boundary

Reusable Approval Scopes

Quick Start

How It Works

What Gets Decomposed

Shell expansion escalates to ASK

Evasions Now Blocked

Aggregation Precedence

Workspace Boundary

Fallback Behaviour

Common Patterns

Best Practices

Related