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

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

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.

Windows / PowerShell dialect

PowerShell and cmd wrappers are unwrapped so the inner cmdlet — not the opaque powershell -Command "…" — is what your rules see.

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

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

# All of these are blocked by the single Remove-Item deny above:
#   powershell -Command "Remove-Item C:\tmp\x"
#   pwsh -c "Remove-Item .\out.txt"
#   powershell -NoProfile -Command "Remove-Item .\x"
#   powershell -Command "& { Remove-Item .\x }"
#   powershell -EncodedCommand <base64-of-'Remove-Item .\x'>
agent.start("Clean up temp files")

What Windows dialects understand

Wrapper / construct	Example	Result
`powershell -Command "…"`	`powershell -Command "Remove-Item C:\tmp\x"`	`[Remove-Item]` (dialect = `powershell`)
`pwsh -c "…"` (short flag)	`pwsh -c "New-Item .\out.txt"`	`[New-Item]`
`cmd /c "…"`	`cmd /c "del C:\tmp\x"`	`[del]` (dialect = `cmd`)
Option-prefixed PS	`powershell -NoProfile -Command "Remove-Item C:\outside\x"`	`[Remove-Item]` (switches before `-Command` are skipped)
Option-prefixed cmd	`cmd /d /c "del C:\outside\x"`	`[del]`
PowerShell pipeline	`powershell -Command "Get-Content a.txt \| Set-Content b.txt"`	`[Get-Content, Set-Content]`
Call-operator scriptblock	`powershell -Command "& { Remove-Item .\x }"`	`[Remove-Item]` — `{` is not left as the executable
Bare call operator	`powershell -Command "& Remove-Item .\x"`	`[Remove-Item]`
`-EncodedCommand` (base64 UTF-16LE)	`powershell -EncodedCommand UgBlAG0Abw…`	decoded, then parsed inline
`-e` / `-ec` abbreviations	`pwsh -e UgBlAG0Abw…`	decoded, then parsed inline
Undecodable `-EncodedCommand`	`powershell -EncodedCommand not!valid!base64`	fail-closed — stays a single opaque `powershell` op
`powershell script.ps1` (no `-Command`)	`powershell script.ps1`	opaque single op — filename is not misparsed as a command flag
Drive-letter path arg	`powershell -Command "Remove-Item C:\tmp\x"`	`C:\tmp\x` is a `path_arg` (POSIX would not see it)
Relative Windows path arg	`powershell -Command "Set-Content .\out.txt hi"`	`.\out.txt` is a `path_arg`
UNC / backslash tokens	`\\host\share\x`, `.\x`, `..\x`	recognised as Windows path shapes

Recognised mutation vocabulary

Match is case-insensitive; a directory prefix on the executable is ignored. PowerShell (cmdlets + aliases): Remove-Item, New-Item, Move-Item, Copy-Item, Rename-Item, Set-Content, Add-Content, Clear-Content, Out-File, and aliases ri, rd, del, erase, ni, mi, move, cpi, copy, cp, rni, ren, sc, ac, rm, mv. cmd built-ins: del, erase, rd, rmdir, md, mkdir, move, copy, xcopy, ren, rename.

Get-Content, Get-ChildItem, and dir are not mutations — they follow the same read-vs-write distinction as POSIX.

Workspace boundary on Windows

The workspace boundary fires on Windows paths the same way it fires on POSIX paths.

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

agent = Agent(
    name="Windows Worker",
    instructions="Only write inside the workspace",
    approval=ApprovalConfig(permissions={"bash:*": "allow"}),
)

# Inside workspace → allowed
#   powershell -Command "Set-Content .\note.txt hi"
#
# Outside workspace → prompts (external_dir:* boundary fires)
#   powershell -Command "Remove-Item C:\Users\Public\secret.txt"
#   powershell -NoProfile -Command "Remove-Item C:\outside\x"
#   powershell -EncodedCommand <base64-of-'Remove-Item C:\outside\x'>
agent.start("Save today's notes")

The boundary check fires the same way it does for POSIX rm — Windows users no longer get a weaker default.
Option-prefixed forms (-NoProfile -Command …, cmd /d /c …) do not defeat the unwrap.
-EncodedCommand payloads are decoded (base64 UTF-16LE) before gating, so a base64 blob cannot slip an external write past the gate.

Anchor: Workspace Boundary.

Fail-closed behaviour

Undecodable -EncodedCommand → the wrapper stays opaque (executable is preserved as powershell), so a command-specific deny or allow on powershell * still applies; a broad wildcard does not silently authorise the payload.
powershell script.ps1 (no command flag) → stays opaque, filename is not treated as a command operand.
Any parse failure → whole-command fallback (existing POSIX behaviour, extended to Windows) — no rule is silently weakened.

Which rule should I write?

A rule name matches the executable name: POSIX pattern names catch POSIX executables; Windows cmdlet names catch cmdlets. The path-based workspace boundary is dialect-agnostic, so that half of the safety story needs no per-OS duplication.

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)

Windows dialects — with a matching cmdlet deny like bash:Remove-Item * (or bash:del * / bash:New-Item *):

Command	Previous	Now
`bash:powershell -Command "Remove-Item x"`	ALLOWED	denied
`bash:cmd /c "del x"`	ALLOWED	denied
`bash:pwsh -c "New-Item x"`	ALLOWED	denied
`bash:powershell -EncodedCommand …` (decodes to `Remove-Item x`)	ALLOWED	denied
`bash:powershell -Command "& { Remove-Item x }"`	ALLOWED	denied

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.

On Windows, prefer cmdlet names in your rules

bash:Remove-Item * catches powershell -Command "Remove-Item …", pwsh -c "Remove-Item …", & { Remove-Item … } scriptblocks, and -EncodedCommand payloads that decode to Remove-Item. bash:rm * still catches POSIX rm; write both if your workflow targets both OSes.

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.

​Quick Start

​How It Works

​What Gets Decomposed

​Windows / PowerShell dialect

​What Windows dialects understand

​Recognised mutation vocabulary

​Workspace boundary on Windows

​Fail-closed behaviour

​Which rule should I write?

​Shell expansion escalates to ASK

​Evasions Now Blocked

​Argument-scoped deny reaches the gate

​Modified-args re-authorisation

​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

Windows / PowerShell dialect

What Windows dialects understand

Recognised mutation vocabulary

Workspace boundary on Windows

Fail-closed behaviour

Which rule should I write?

Shell expansion escalates to ASK

Evasions Now Blocked

Argument-scoped deny reaches the gate

Modified-args re-authorisation

Aggregation Precedence

Workspace Boundary

Fallback Behaviour

Common Patterns

Best Practices

Related