> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Permissions

> Control what agents can and cannot do

## Why Permissions Matter

Agents with unrestricted access can:

* Execute dangerous commands
* Modify critical files
* Access sensitive data
* Make irreversible changes

Permissions create **guardrails** that let agents work autonomously while keeping humans in control.

## Permission Models

### Allowlist (Recommended)

Only explicitly permitted actions are allowed:

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(git status:*)",
      "Bash(npm test:*)"
    ]
  }
}
```

### Denylist

Everything allowed except explicitly denied:

```json theme={null}
{
  "permissions": {
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Write(.env)"
    ]
  }
}
```

### Hybrid

Combine both for fine-grained control:

```json theme={null}
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)"
    ],
    "deny": [
      "Bash(git push --force:*)",
      "Bash(npm publish:*)"
    ]
  }
}
```

## Configuration by Tool

<Tabs>
  <Tab title="Claude Code">
    **File**: `.claude/settings.json`

    ```json theme={null}
    {
      "permissions": {
        "allow": [
          "Read(**)",
          "Edit(**)",
          "Write(**)",
          "Glob(**)",
          "Grep(**)",
          "Bash(git:*)",
          "Bash(npm:*)",
          "Bash(node:*)"
        ],
        "deny": [
          "Bash(rm -rf:*)",
          "Bash(sudo:*)"
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    **Settings** → **Features** → **Codebase Indexing**

    ```json theme={null}
    {
      "allowedCommands": ["git", "npm", "node"],
      "blockedCommands": ["rm -rf", "sudo"],
      "allowFileEdits": true,
      "requireConfirmation": ["delete", "rename"]
    }
    ```
  </Tab>

  <Tab title="OpenCode">
    **File**: `.opencode/permissions.json`

    ```json theme={null}
    {
      "tools": {
        "shell": {
          "allowed": ["git", "npm", "node"],
          "blocked": ["rm", "sudo", "chmod"]
        },
        "files": {
          "read": "**/*",
          "write": "src/**/*",
          "delete": false
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Permission Categories

### File Operations

| Permission | Risk Level | Recommendation       |
| ---------- | ---------- | -------------------- |
| Read       | Low        | Allow broadly        |
| Write      | Medium     | Scope to project     |
| Delete     | High       | Require confirmation |
| Execute    | High       | Allowlist only       |

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "deny": [
      "Write(.env*)",
      "Write(*.pem)",
      "Write(credentials*)"
    ]
  }
}
```

### Shell Commands

| Command               | Risk Level | Notes              |
| --------------------- | ---------- | ------------------ |
| `git status/diff/log` | Low        | Read-only          |
| `git add/commit`      | Medium     | Changes repo state |
| `git push`            | High       | Affects remote     |
| `git push --force`    | Critical   | Destructive        |
| `rm -rf`              | Critical   | Never allow        |
| `sudo`                | Critical   | Never allow        |

```json theme={null}
{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(npm install:*)",
      "Bash(npm test:*)",
      "Bash(npm run:*)"
    ],
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}
```

### Network Access

```json theme={null}
{
  "permissions": {
    "allow": [
      "WebFetch(domain:github.com)",
      "WebFetch(domain:docs.anthropic.com)",
      "WebFetch(domain:localhost)"
    ],
    "deny": [
      "WebFetch(domain:*internal*)"
    ]
  }
}
```

### MCP Tools

```json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__supabase__list_tables",
      "mcp__supabase__execute_sql",
      "mcp__chrome-devtools__take_screenshot"
    ],
    "deny": [
      "mcp__supabase__delete_*",
      "mcp__*__deploy_*"
    ]
  }
}
```

## Permission Patterns

### Read-Only Agent

Safe for exploration and analysis:

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(git log:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)"
    ]
  }
}
```

### Development Agent

Standard development workflow:

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)",
      "Edit(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Write(.env*)",
      "Bash(git push --force:*)",
      "Bash(npm publish:*)"
    ]
  }
}
```

### CI/CD Agent

Deployment with safeguards:

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Bash(git:*)",
      "Bash(npm run build:*)",
      "Bash(npm test:*)",
      "Bash(docker build:*)",
      "Bash(gcloud run deploy:*)"
    ],
    "deny": [
      "Write(**)",
      "Edit(**)",
      "Bash(git push --force:*)"
    ]
  }
}
```

## Confirmation Prompts

Require human approval for sensitive actions:

```json theme={null}
{
  "permissions": {
    "requireConfirmation": [
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Write(*.config.*)",
      "mcp__*__deploy_*"
    ]
  }
}
```

## Audit Logging

Track all permission-related events:

```json theme={null}
{
  "permissions": {
    "audit": {
      "enabled": true,
      "logFile": ".agents/audit.log",
      "logLevel": "all",
      "alertOn": ["denied", "elevated"]
    }
  }
}
```

**Audit log example:**

```
2024-01-15T10:30:00Z [ALLOWED] Read(src/api/auth.ts) agent=code-reviewer
2024-01-15T10:30:05Z [DENIED] Bash(rm -rf node_modules) agent=code-reviewer
2024-01-15T10:30:10Z [CONFIRMED] Bash(git push origin main) agent=deployer user=jorge
```

## Best Practices

<Check>
  * Start with minimal permissions, expand as needed
  * Use allowlists over denylists
  * Scope file access to project directories
  * Never allow `sudo` or `rm -rf`
  * Require confirmation for destructive actions
  * Enable audit logging in production
  * Review permissions when adding new agents
</Check>

<Warning>
  **Security risks:**

  * Overly permissive defaults
  * Forgotten legacy permissions
  * Permissions copied between environments
  * Missing audit trails
  * No separation between dev/prod permissions
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="Security" icon="lock" href="/guides/security">
    Comprehensive security practices
  </Card>

  <Card title="Hooks" icon="webhook" href="/guides/hooks">
    Add permission checks via hooks
  </Card>
</CardGroup>