Workspace Boundary

Gate shell and file access outside your project root with a distinct external_dir approval

Set a workspace root and any tool call touching a path outside it asks for extra approval — a single broad allow no longer lets the agent reach your whole machine.

The PermissionManager boundary described here is complementary to the EditTools fallback root introduced in PR #2981 — see File Editing → Constructor Parameters.

Quick Start

1. Agent — boundary active out of the box

   Construct an Agent with permissions= — workspace_root defaults to os.getcwd(), so the boundary gate is on with no extra wiring:

   from praisonaiagents import Agent
   
   # workspace_root defaults to os.getcwd() — no extra wiring
   agent = Agent(
       name="researcher",
       instructions="Read files inside my project and summarise them.",
       permissions={
           "read:*": "allow",
           "external_dir:*": "deny",  # hard-block everything outside CWD
       },
   )
   
   agent.start("Summarise the READMEs in this repo")

2. Enable workspace boundary directly

   Create a PermissionManager with workspace_root and the boundary gate activates automatically:

   from praisonaiagents.permissions import PermissionManager
   
   manager = PermissionManager(workspace_root="/path/to/project")
   
   result = manager.check("bash:cat /etc/passwd")
   print(result.needs_approval)  # True — /etc/passwd is outside workspace
   print(result.target)          # bash:cat /etc/passwd

   When the manager checks cat /etc/passwd, it returns needs_approval=True — even if a broad bash:cat * → allow rule is set.

3. Pre-authorise an external directory

   Add a rule to allow a specific external directory without prompting:

   from praisonaiagents.permissions import PermissionManager, PermissionRule, PermissionAction
   
   manager = PermissionManager(workspace_root="/proj")
   manager.add_rule(PermissionRule(
       pattern="external_dir:/data/*",
       action=PermissionAction.ALLOW,
       description="Allow shared data volume",
   ))
   
   result = manager.check("bash:cat /data/input.csv")
   print(result.action)  # allow — pre-authorised

How It Works

The boundary check is dialect-agnostic: it fires on Remove-Item C:\outside\x the same way it fires on rm /outside/x. See Command-Aware Permissions → Windows / PowerShell dialect.

What Triggers the Gate

Any path that resolves outside workspace_root triggers an external_dir: approval request.

Aggregation with Existing Rules

The workspace boundary fits into the same deny→ask→allow aggregation as all other permission checks.

Deny always wins — an explicit deny on bash:rm or external_dir: beats the boundary ask, and an explicit deny cannot be overridden by a boundary allow.

Backward Compatibility

When workspace_root is None (the default), no boundary check runs and behaviour is 100% unchanged. Only opting in to workspace_root activates the gate — no existing code breaks.

from praisonaiagents.permissions import PermissionManager

# No workspace_root → old behaviour, no boundary check
manager = PermissionManager()

# With workspace_root → boundary gate active
manager_bounded = PermissionManager(workspace_root="/proj")

Fail-Closed Behaviour

Pre-Authorising External Directories

praisonai permissions allow "external_dir:/data/*" --description "Shared data volume"
praisonai permissions deny "external_dir:*" --description "Block all external paths"

# agents.yaml
permissions:
  "external_dir:/data/*": allow
  "external_dir:*": deny
  "read:*": allow
  "bash:rm *": deny

from praisonaiagents.permissions import PermissionManager, PermissionRule, PermissionAction

manager = PermissionManager(workspace_root="/proj")
manager.add_rule(PermissionRule(
    pattern="external_dir:/data/*",
    action=PermissionAction.ALLOW,
    description="Allow shared data volume",
))
manager.add_rule(PermissionRule(
    pattern="external_dir:*",
    action=PermissionAction.DENY,
    description="Block all other external paths",
))
manager.add_rule(PermissionRule(
    pattern="read:*",
    action=PermissionAction.ALLOW,
))

Best Practices

Related