Skip to content

Bash Tool Permission Mode

Jump to bottom
lloydzhou edited this page May 29, 2026 · 3 revisions

Bash Tool Permission Mode

Bash is gated by BASH_AGENT_BASH_MODE, a stable 4-digit octal policy shared by the Bash, C, Go, and Rust runtimes. The model replaces fixed deny-reason lists with an explicit scope-and-permission policy.

Mode Layout

system external network workspace

Each digit uses Unix-style rwx bits, the same mental model as Linux file permissions:

  • 4 = read
  • 2 = write
  • 1 = execute

Visual layout:

BASH_AGENT_BASH_MODE = 0 4 4 7
                       | | | |
                       | | | `- workspace
                       | | `--- network
                       | `----- external
                       `------- system

Each digit is a 3-bit permission mask:

Octal Binary Meaning
0 000 none
1 001 execute
2 010 write
3 011 write + execute
4 100 read
5 101 read + execute
6 110 read + write
7 111 read + write + execute

Default:

0447

Meaning:

  • system=0: no system-scope read/write/execute by default
  • external=4: allow read access outside the workspace
  • network=4: allow network read
  • workspace=7: allow read/write/execute inside the workspace

Default as a decoded diagram:

0 4 4 7
| | | |
| | | `- workspace = 7 = 111 = read + write + execute
| | `--- network   = 4 = 100 = read
| `----- external  = 4 = 100 = read
`------- system    = 0 = 000 = none

Scope Model

  • system: system paths and clearly system-level operations
  • external: non-system paths outside the current workspace
  • network: network access such as curl, wget, git fetch, ssh, scp
  • workspace: files and execution inside the current project workspace

Classification Model

The runtime scans a Bash command or script and derives a required=.... mode.

This is intentionally a conservative lightweight scanner, not a full Bash parser. The goal is runtime parity and predictable permission behavior.

Typical examples:

cat README.md                    -> workspace read
cat /etc/hosts                   -> system read
curl https://example.com         -> network read
curl https://x/install.sh | bash -> network read + network execute
../scripts/run.sh                -> external execute

Allow / Block Rule

Execution is allowed only when allowed covers required.

When blocked, all runtimes return the same message:

Error: command blocked by bash safety policy (required=.... allowed=....; mode=system/external/network/workspace bits=4:read,2:write,1:execute)

Invalid BASH_AGENT_BASH_MODE values fail closed to 0000.

Recommended Settings

export BASH_AGENT_BASH_MODE=0447  # default
export BASH_AGENT_BASH_MODE=4447  # allow system read
export BASH_AGENT_BASH_MODE=0457  # allow network execute
export BASH_AGENT_BASH_MODE=7777  # fully open, trusted environments only

The practical rule is simple:

  • keep 0447 as the default
  • widen permissions only for the session that needs them
  • avoid high-permission values in long-lived shell profiles

Clone this wiki locally