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

Configuration

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

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

Pattern Matching

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

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

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

Signal Engine Integration

The permission firewall uses the 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:

{
  "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:

{
  "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)

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

CI Automation (Minimal Gates)

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

Paranoid (Everything Asks)

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

Related