---
title: Permissions
url: https://arcana.otnelhq.com/docs/permissions
---

New in v0.4.0 

Permission system overhaul — configurable benign auto-allow, signal-engine classifier, and permission firewall.

# Permissions

Arcana's permission system controls what tools the agent can use and when it needs approval. Every tool call passes through a **permission firewall** that evaluates rules, risk classification, and governance policy before allowing execution.

## How It Works

1. **Tool request** — The agent wants to execute a tool (bash, file edit, network, etc.)
2. **Risk classification** — The signal engine classifies the tool call's risk level
3. **Rule matching** — Permission rules are evaluated (last match wins)
4. **Benign auto-allow** — Low-risk actions can be auto-allowed based on policy
5. **Gate or execute** — If approval is needed, a gate opens; otherwise, the tool runs

## Permission Values

| Value | Behavior |
| --- | --- |
| `"allow"` | Execute without asking |
| `"ask"` | Show approval gate before executing |
| `"deny"` | Block execution entirely |

## Configuration

Permissions are configured in `arcana.json`. Rules are evaluated top-to-bottom; **last match wins**:

```json
{
  "permission": {
    "edit": "deny",
    "bash": {
      "git *": "allow",
      "rm *": "deny",
      "*": "ask"
    },
    "network": "ask"
  }
}
```

### Pattern Matching

Patterns use glob-style matching on the tool's arguments:

| Pattern | Matches |
| --- | --- |
| `git *` | Any git command |
| `rm *` | Any rm command |
| `npm install *` | npm install with any args |
| `*` | Everything (catch-all) |

## Benign Auto-Allow

In v0.4.0, low-risk actions can be automatically allowed without a gate:

### What Counts as Benign

- **Read-only tools** — File reads, memory searches, model listings
- **Non-destructive bash** — `git status`, `ls`, `cat`
- **Information queries** — `arcana doctor`, `arcana models`

### Configuring Benign Policy

```json
{
  "governance": {
    "benign_auto_allow": true,
    "benign_log": true
  }
}
```

             Safety 

Benign auto-allow fails closed when the coarse risk level demands human review. Low-risk classification is conservative — when in doubt, the gate opens.

## Signal Engine Integration

The permission firewall uses the [signal engine](/docs/signal-engine) to classify tool calls:

- **Intent classification** — What is the agent trying to do?
- **Risk scoring** — How dangerous is this action?
- **Mutation detection** — Is this modifying files, installing packages, or changing config?
- **Dependency manifest detection** — Is this editing `package.json` or similar?

## Permission Events

Permission decisions are published as events for governance visibility:

```json
{
  "type": "permission.allowed",
  "data": {
    "tool": "bash",
    "pattern": "git status",
    "decision": "allow",
    "reason": "benign_auto_allow",
    "risk_level": "low"
  }
}
```

These events appear in the Desktop governance bridge and can be forwarded to the enterprise console.

## Per-Agent Permissions

Different agents can have different permission profiles:

```json
{
  "agent": {
    "reviewer": {
      "description": "Read-only code reviewer",
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "network": "ask"
      }
    },
    "builder": {
      "description": "Full-access builder",
      "permission": {
        "edit": "allow",
        "bash": {
          "rm *": "deny",
          "*": "allow"
        }
      }
    }
  }
}
```

## Examples

### Safe Workspace (Read-Only)

```json
{
  "permission": {
    "edit": "deny",
    "write": "deny",
    "bash": "deny",
    "network": "ask"
  }
}
```

### CI Automation (Minimal Gates)

```json
{
  "permission": {
    "edit": "allow",
    "bash": {
      "rm *": "deny",
      "*": "allow"
    },
    "network": "allow"
  },
  "governance": {
    "benign_auto_allow": true
  }
}
```

### Paranoid (Everything Asks)

```json
{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "network": "ask",
    "write": "ask"
  },
  "governance": {
    "benign_auto_allow": false
  }
}
```

## Related

- [File Edit Guard](/docs/file-edit-guard) — Line-level analysis of file mutations
- [Trust & Security](/docs/trust-boundaries) — Security model and trust boundaries
- [Autonomy Modes](/docs/autonomy-modes) — Control how much autonomy agents have