Permissions

Overview

Armament uses a workspace sandbox model to control what files agents can access. Every channel has a workspace root (set via /setroot or the default .armaws/ directory), and agents are restricted to that root by default. Accessing files outside the workspace requires explicit user approval.

The system has three components:

scopePath() — resolves and checks every file path against allowed workspaces
PermissionStore — manages pending requests, remembered paths, and god mode
Approval widget — TUI dialog for approve/deny decisions

How It Works

When an agent tries to access a file path:

agent: read_file("src/app.ts")
          ↓
    scopePath("src/app.ts", workspace)
          ↓
    Is it a bare relative path (no /, ~, ..)? → auto-allowed
    Is it inside the workspace?              → auto-allowed
    Is it a remembered path?                 → auto-allowed
    Is god mode active?                      → auto-allowed
    Otherwise                                → show permission dialog

Path Types

Path Type	Example	Permission Check
Bare relative	`src/app.ts`	None — auto-allowed (can’t escape workspace)
Dot relative	`./src/app.ts`	None — auto-allowed
Parent relative	`../README.md`	Checked against workspace
Absolute	`/etc/hosts`	Checked against workspace
Home-expanded	`~/.bashrc`	Checked against workspace

Built-in Allowlist

These system paths are always allowed without prompting:

/dev/null, /dev/zero, /dev/random, /dev/urandom
/dev/stdin, /dev/stdout, /dev/stderr

Non-Existent Files

If the resolved path does not exist on disk, the request is automatically denied — no dialog shown. This prevents pointless prompts for typos or paths that don’t exist.

Permission Dialog

When an agent requests access outside the workspace, a dialog appears:

read file wants to access:
/home/rob/some-file.txt
  ● Deny
  ○ Allow once
  ○ Allow and remember folder

Option	Behavior
Deny	Reject this request. The agent sees `PERMISSION_DENIED:tool:path:` — the structured prefix prevents retries. The path is NOT remembered — next request for the same path will prompt again.
Allow once	Approve this request. The exact path is allowed for the rest of the session only.
Allow and remember folder	Approve and remember the parent directory for the rest of the session. All files and subdirectories under that directory are auto-allowed without prompting.

Subfolder Handling

When you allow a folder, all subdirectories and files under it are automatically included — allowing /home/rob/scripts also allows /home/rob/scripts/deploy.sh and /home/rob/scripts/utils/.

God Mode

God mode bypasses ALL permission checks. This is useful for workflow development, demos, or trusted environments.

Per-Channel

/godmode              # Toggle god mode for current channel
/godmode on           # Enable for current channel
/godmode off          # Disable for current channel

Global (CLI)

arma --godmode        # Enable god mode for ALL channels this session

God mode is in-memory only — it resets on restart. When active, all agents see:

╡ God mode ON for #armament — all permission requests auto-approved.

Workspace Configuration

Setting the Workspace

The workspace defaults to the channel’s .armaws/ directory. Use /setroot to point it at a project:

/setroot /home/rob/my-project

After /setroot, the agent can access any file under /home/rob/my-project/ without prompting. Subfolders are automatically included.

Default Workspace

On first join or restart, the workspace is set to:

The project root from .armaroot (if /setroot was used)
Otherwise, the channel’s .armaws/ directory
Plus /tmp and /dev (for temporary file operations)

Audit Trail

All permission requests and decisions are tracked:

Allow once → exact path allowed for session
Allow and remember folder → parent directory allowed for session
Deny → agent sees PERMISSION_DENIED:tool:path:, path not remembered

Channel Identity

Every agent knows its channel name via a persistent sticky note:

You are in channel: #armament

This is injected on every message and survives restarts. It helps the agent understand its workspace context and avoid confusion when working across channels.

Bash Tool Permissions

The bash tool also enforces workspace permissions. Any absolute path appearing in a shell command is checked against the workspace in the same way as file tools. Commands are additionally blocked for destructive patterns (rm -rf /, dd, mkfs, fork bombs).

List Files Tool Permissions

The list_files tool now enforces the same permission checks as other file tools. Listing directories outside the workspace triggers the permission dialog.