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

# Read-Only Agents

> Put critical systems in Plan: agents only read, and each change waits for a person's approval

An agent in **Plan** is a read-only agent: it can describe state, read logs and query APIs, but it cannot change anything. When a change is needed, 2501 posts it as a **plan**, and makes it only after a person approves it. Useful when you want a recommendation first, and a person's decision before any change.

## Three ways to enable it

| Scope | How | Effect |
| - | - | - |
| **One ticket** | Add `@2501:plan` to the ticket body or a comment | Every agent of this ticket's job only reads |
| **A whole specialty** | An Admin overrides the [specialty](https://docs.2501.ai/0.20/configure/specialties.md) with Plan | Agents using this specialty only read |
| **A whole organization** | An Admin sets the [organization](https://docs.2501.ai/0.20/core-concepts/organizations.md#execution-mode) to Plan | Every agent whose specialty has no override only reads |

A ticket can force Auto on all the agents of its job with `@2501:auto`, also through a specialty in Plan, but only when an Admin allows `@2501:auto` for the organization. Keep that setting off to keep every approval that an Admin set.

## How it works

The agent **knows** it only reads and tries to comply. But it can still emit a command that would alter state. That's where the secondary engine - the [LLM-as-judge](https://docs.2501.ai/0.20/understand/engine-agents.md#secondary-engine-the-copilot) - steps in: it reviews every command before execution. If the command would alter the system, the secondary engine blocks it.

Two independent layers of read-only protection:

1. The main engine is **told** that it only reads (prompt-level).
2. The secondary engine **enforces** read-only at every command (runtime check).

### Authentication commands are not blocked

Commands that only affect the agent's own credential context - `oc login`, `aws sso login`, `vault login`, and similar - are **not** blocked on a read-only agent. These commands do not modify the target system; they configure how the agent authenticates to reach it. Blocking them would prevent the agent from acquiring the credentials it needs to inspect anything.

## When a change is needed

A job stops after its first turn that reads through an agent in Plan. When a change is still needed, it posts a plan in the ticket with every change that is left, and waits. The plan says what 2501 found, each change it needs, on which host and through which agent, and the changes it already made. While it waits, the ticket stays In Progress, and 2501 does not escalate it.

Approve the plan with `@2501:approve-plan`, or **Approve plan** on the job page. Then 2501 starts its steps, and tells the agent of each step to make only its own change. Ask for something different with a `@2501` comment, and 2501 posts a new version. When no change is needed, the job only answers and ends as a success. See [Jobs: Plans](https://docs.2501.ai/0.20/core-concepts/jobs.md#plans).

## Patterns

### Approve before every change

Put the ticket in Plan with `@2501:plan`, or its specialty or organization. 2501 investigates, posts a plan, and changes nothing before `@2501:approve-plan`. The approval covers only the steps of the plan. 2501 tells the agent of each step to stop when the step needs another change, and then posts a new version that names that change.

### Critical fleet, safe by default

Override all critical-system specialties with Plan. Operators can read every diagnostic the agent produces, and each change waits for an approval. To let one job act without approval, an Admin allows `@2501:auto`, and a person adds it to that ticket.

### Audit-mode rollout

When introducing a new specialty or operational rule for the first time, **always start in Plan**. Read the plans for a week. Move it to Auto only after the plans look right consistently.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.