Permissions

1 min read·Updated 30 Jul 2026

Every tool call passes the permission gate, whether it came from the app, the CLI, a scheduled job or the API. If a tool is running, it has already been allowed.

Grant levels

Level	Behaviour
Always allow	Granted once, never prompts again
Ask every time	Prompts on every call, regardless of prior answers
Never allow	Fails immediately, no prompt shown

Scope is the important part

A capability without a scope is a blank cheque. Scope every filesystem and network grant to the narrowest path or host that works.

SHELL

arble permissions grant filesystem.write --scope "~/Projects/api-gateway"
arble permissions grant network.http --scope "api.github.com"
arble permissions revoke network.http --scope "api.github.com"

Inheritance

Grants are scoped per tool, per workflow or per session, and inherit down a call chain. A workflow granted network.http does not make a called tool re-prompt — but a tighter scope on that tool is still enforced on top. Inheritance never loosens a scope.

Unattended runs

In the foreground a call needing approval pauses and prompts. In a background or CI run there is nobody to ask, so it fails closed. Declare what the job needs up front and pass --no-prompt so it fails fast rather than hanging.

Audit

SHELL

$ arble permissions audit --since 24h
TIME      AGENT        TOOL                DECISION  SCOPE
14:02:11  agt_5wTn9Kd  filesystem.read     auto      ~/Projects/api-gateway
14:02:19  agt_5wTn9Kd  github.create_pr    approved  acme/api-gateway
14:03:40  agt_5wTn9Kd  postgres.query      denied    production

When a run stops early, read the audit log before the trace. A denied capability explains it more often than anything else.