> ## 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

> Use the investigate-only ceiling for critical systems and high-risk new use cases

Read-only mode constrains an agent to **inspection commands only** - it can describe state, read logs, query APIs, but it cannot change anything. Useful when you want a recommendation, not a remediation.

## Two ways to enable it

| Scope | How | Effect |
| - | - | - |
| **One ticket** | Add `@2501:investigate` to the ticket body or a comment | Just this ticket runs read-only |
| **A whole specialty** | Set the [specialty](/0.17/configure/specialties) to investigate-only | Agents using this specialty are read-only unless the winning ticket tag is `@2501:remediate` |

Use the specialty ceiling for **large fleets of investigative agents** - for example, 1000 Oracle DB agents that should default to read-only. You can explicitly authorize remediation for one job with `@2501:remediate`, or change the specialty setting for all its agents.

## How it works

The agent **knows** it's in read-only mode 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](/0.17/understand/engine-agents#secondary-engine--the-copilot) - steps in: it reviews every command before execution. If the command would alter the system in read-only mode, the secondary engine blocks it.

Two independent layers of read-only protection:

1. The main engine is **told** it's in read-only mode (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 in read-only mode. 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.

## Partial resolution

When an untagged ticket needs remediation but a specialty ceiling forced read-only, the job ends as **partial** rather than failed. The ticket gets a public comment explaining what the agent found and why it didn't act, so a human can pick up cleanly.

See the [escalation policy](/0.17/core-concepts/gateways#escalation-groups) for how partials route in your ITSM.

## Patterns

### Plan-then-apply

Tag the ticket `@2501:investigate` and ask for a plan. After reviewing the findings, add `@2501:remediate` with instructions to apply the fix. The same job retains its plan, previous reasoning and task history as context. The tag overrides an investigate-only specialty for this job; other operational rules and access restrictions still apply.

### Critical fleet, safe by default

Set all critical-system specialties to investigate-only. Operators can read every diagnostic the agent produces. When you want a specific repair, add `@2501:remediate` to that ticket or change the specialty setting.

### Audit-mode rollout

When introducing a new specialty or operational rule for the first time, **always start in investigate-only**. Watch the agent's plans for a week. Lift the ceiling only after the plans look right consistently.


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