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

# Permissions & Access Control

> How Bugzy controls what the agent can do — task scoping, tool-level restrictions, and integration access levels.

Bugzy uses a two-layer permission model to control what the agent can do. The first layer defines the scope of each task. The second layer restricts which tools each subagent can use, even when broader access is technically available.

## Layer 1: Task scope

Every action Bugzy takes happens within a defined task — `run-tests`, `generate-test-cases`, `verify-changes`, etc. Each task declares which subagents it needs and what they're allowed to do.

* **Scheduled and webhook-triggered tasks** execute autonomously within their defined scope. A `run-tests` task can execute tests, triage failures, and file bugs — but it cannot, for example, delete issues or modify repository settings.
* **Conversational triggers** (Slack and Teams messages) go through the inbox agent, which interprets the request and routes it to the appropriate task. The inbox agent can ask your team for confirmation before acting.

The agent cannot perform actions outside its task's declared scope. It does not have general-purpose access to your systems.

## Layer 2: Tool-level access control

Within each task, subagents are restricted to specific tools based on their role. This is enforced at two boundaries:

* **Per-subagent restriction** — each subagent can only use the tools defined for its role. A documentation-researcher cannot use issue-creation commands, even if the underlying integration token has write access.
* **Session-wide boundary** — the maximum set of tools available in any execution is the union of all configured subagent tools. Tools not in this set are blocked entirely.

### Access levels by role

| Role                     | Access level             | What it can do                                                                          |
| ------------------------ | ------------------------ | --------------------------------------------------------------------------------------- |
| Documentation Researcher | **Read-only**            | Search and retrieve tickets, pages, and wiki content — cannot create or modify anything |
| Issue Tracker            | **Full access**          | Create issues, add comments, transition ticket status, update fields                    |
| Team Communicator        | **Write**                | Post messages and test results to Slack, Teams, or email                                |
| Source Control           | **Read + limited write** | Read PRs and commit history, post PR comments                                           |
| Browser Automation       | **Scoped**               | Navigate pages and interact with UI via Playwright — no filesystem or API access        |
| Test Engineer            | **Full shell**           | Run test commands, debug failures, fix code — needs unrestricted shell access           |
| Test Case Manager        | **File write**           | Create and update test case files, optionally sync with external TMS                    |

### Example: Jira access

When you connect Jira, Bugzy receives an OAuth token with both read and write scopes. But the token's capabilities are not the same as the agent's capabilities:

* The **documentation-researcher** subagent can only use `jira-cli issue search` and `jira-cli issue get`. It reads tickets for product context but cannot create or modify anything.
* The **issue-tracker** subagent gets full `jira-cli` access — it can create issues, add comments, and transition tickets.

If your project only has the documentation-researcher configured (no issue-tracker), Bugzy cannot create Jira issues — even though the token technically allows it.

This same pattern applies to all integrations: Notion, Linear, Azure DevOps, Asana, Slack, and others.

## OAuth tokens and credentials

Integration tokens are managed securely:

* **Nango** handles OAuth flows and automatic token refresh — no manual token management required
* **Encrypted at rest** — tokens are stored encrypted via Google Cloud KMS
* **Decrypted only at runtime** — credentials are available only inside ephemeral Cloud Run containers during task execution
* **Per-project isolation** — each project maintains its own set of connections; tokens are not shared across projects

For full details on encryption, data handling, and compliance, see [Security](/docs/security).