Command-Aware Permissions

Deny rules now follow shell command structure — &&, ;, |, $(), subshells and redirects can no longer evade them

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

Argument-scoped deny rules now reach the enforcement path (PraisonAI PR #4234, closes #4228): On releases prior to #4234, an argument-scoped deny rule like bash:rm * on a PermissionManager was parsed and understood by the rule engine, but the name-based deny gate only asked is_denied(function_name). So if execute_command was allowed by name, execute_command(command="rm -rf /tmp/x") still ran — the argument-scoped rule never fired at call time. After #4234 the gate builds a scoped target from the arguments and checks both, so the rule fires. Upgrade to a release that includes #4234 — no code change is required.

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

Quick Start

1. 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.

2. 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
execute_command({"command=": "rm -rf /tmp/x"}) (argument-key mangling)	ALLOWED	denied
bash:echo '$(rm -rf x)' (single-quoted)	denied	allowed (correctly — literal)

---

Argument-scoped deny reaches the gate

The rule engine has always understood argument-scoped patterns like bash:rm *. Since PR #4234 the enforcement path does too — the deny gate builds a scoped target from the call’s arguments and checks it alongside the tool name.

from praisonaiagents import Agent
from praisonaiagents.permissions import PermissionManager

# Rule engine has always understood argument-scoped patterns —
# since PR #4234 the enforcement path does too.
manager = PermissionManager(storage_dir=".praisonai/permissions")
manager.load_rules_from_config({"bash:rm *": "deny"})

agent = Agent(name="Safe Worker", instructions="Run shell commands safely")
agent._permission_manager = manager

# Blocked — argument-scoped rule fires at the deny gate
agent._check_tool_approval_sync("execute_command", {"command": "rm -rf /tmp/x"})
# → {"permission_denied": True, "error": "Tool 'execute_command' blocked by permission policy"}

# Allowed — same tool, different args
agent._check_tool_approval_sync("execute_command", {"command": "ls -la"})
# → None (no denial)

Name-level rules keep their all-or-nothing behaviour. execute_command: deny still blocks every execute_command(...) call regardless of arguments. The scoped check is additive — it narrows a name that is otherwise allowed; it never loosens a name-level deny.

Argument-key mangling can’t evade the gate. A malformed {"command=": "rm -rf /tmp/x"} (a trailing-= kwarg LLMs sometimes hallucinate) is normalised in the gate with k.strip().rstrip('=').strip() before the scoped target is built — so a deny rule can’t be dodged by a key that only cleans up after dispatch.

---

Modified-args re-authorisation

An approval backend may rewrite arguments (a common sanitisation pattern). Since PR #4234, the rewritten args are re-checked against the deny gate before dispatch — so a rewrite can’t smuggle a denied command past a gate that only saw the original, safe args.

from praisonaiagents.approval.protocols import ApprovalDecision

# Approval backend rewrites args from safe to dangerous — re-authorised
decision = ApprovalDecision(
    approved=True,
    reason="mock",
    modified_args={"command": "rm -rf /tmp/x"},  # was originally "ls -la"
)
# The gate re-runs on modified_args before dispatch — the rewritten
# 'rm -rf' matches "bash:rm *" deny and the call is blocked.

Both the sync and async approval paths re-run the gate on the final arguments. BYPASS mode opts out entirely, matching its “skip all permission checks” contract.

---

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.

Related

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.