Permissions and Access Control

CrabCode's tool permission model: 5 modes + working-directory allowlist + allow/deny/ask rules.

What it is

Every time CrabCode wants to read a file, write a file, run a command, or hit the network, it goes through a tool permission check. The result depends on two things:

1. The current permission mode (one of 5)
2. The permissions block in settings.json (allow / deny / ask rules)

"Permissions" here means a per-tool local interceptor, not enterprise SSO/RBAC identity. Account login and billing live in the Acosmi gateway — see getting-started.

When you see this doc

• An invalid value in settings.json for permissions.defaultMode
• A misconfigured additionalDirectories
• The "Learn more" link from the in-TUI /permissions command
• A tool call denied with a link back here

Five permission modes

How to switch:

crabcode --permission-mode plan        # at startup

crabcode --permission-mode plan        # at startup

Or in settings.json:

{ "permissions": { "defaultMode": "acceptEdits" } }

{ "permissions": { "defaultMode": "acceptEdits" } }

Or press Shift+Tab in the TUI to cycle (default → acceptEdits → plan → bypassPermissions → back to default).

Tool × mode behavior matrix

The table below shows the default behavior of common tools under the five modes (still subject to allow / deny / ask rules).

Notes:

• "auto" = passes without prompt; "ask" = confirmation dialog; "deny" = silently blocked
• Subagent (Task) toolsets are subsets of the caller's; the mode is inherited
• plan mode only allows read-only tools (Read / Glob / Grep / LS / WebSearch per config); any write or side-effect tool is denied

Working-directory allowlist

By default CrabCode can only read/write inside the cwd at startup and its descendants. To extend:

crabcode --add-dir ~/code/sibling-repo

crabcode --add-dir ~/code/sibling-repo

Or in settings.json:

{ "permissions": { "additionalDirectories": ["~/code/sibling-repo"] } }

{ "permissions": { "additionalDirectories": ["~/code/sibling-repo"] } }

You'll be asked to confirm trust for each new directory at startup.

Rules: allow / deny / ask

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",          // any npm test subcommand passes
      "Read(/etc/hosts)"           // allow reading this specific file
    ],
    "deny": [
      "Bash(rm -rf:*)",            // forever blocked
      "WebFetch"                   // entire tool blocked
    ],
    "ask": [
      "Bash(git push:*)"           // prompt even under acceptEdits
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",          // any npm test subcommand passes
      "Read(/etc/hosts)"           // allow reading this specific file
    ],
    "deny": [
      "Bash(rm -rf:*)",            // forever blocked
      "WebFetch"                   // entire tool blocked
    ],
    "ask": [
      "Bash(git push:*)"           // prompt even under acceptEdits
    ]
  }
}

Rule syntax

• Shaped as <ToolName> or &lt;ToolName&gt;(<pattern>)
• :* matches a subcommand prefix (Bash(git push:*) covers git push origin main, git push --force, etc.)
• For piped or chained commands (|, &&, ;), CrabCode checks each segment; any deny hit fails the whole call
• Path-based tools (Read / Edit / Write / NotebookEdit) accept absolute paths or globs inside parentheses (e.g. Read(~/secrets/**))
• WebFetch(domain:*) enables per-domain allow / deny lists

Conflict precedence

deny > ask > allow. That is:

• A call matching both deny and allow → denied
• A call matching both ask and allow → prompts
• After multi-layer settings merge, rules are unioned and deduped; a deny in any layer wins

TUI commands

Enterprise / team hardening

Managed (policy) settings.json can push the following fields, which override personal settings.json and cannot be undone by users:

Limits and caveats

• bypassPermissions is dangerous: CrabCode requires explicit acknowledgement before entering it. Once enabled, you can still cycle back to default via Shift+Tab or --permission-mode, but any operations already executed cannot be undone
• --dangerously-skip-permissions CLI flag is equivalent to bypassPermissions — only use it in sandboxed or network-isolated environments
• Managed settings always win: team members cannot bypass an enterprise policy
• Rules identify the tool, not literal command text: Bash(rm -rf:*) blocks the underlying rm -rf invocation; aliasing (alias rm="rm -rf") does not evade — the call is still recognized as rm
• plan mode denies more than writes: it also denies side-effect tools (Bash / WebFetch / NotebookEdit, etc.) — it's the safe lane for design discussions

Related

• security
• settings
• sandboxing
• hooks