# Modes

Modes define the different behaviors a Harness can run. Each mode layers its own instructions and tool overrides on top of a shared backing agent, so the same agent can act as a planner in one mode and an executor in another. The Harness keeps exactly one mode active at a time, carries the thread and state across switches, and handles the transition between them.

Every Harness needs at least one mode — the `modes` array is required, and the Harness throws at construction if it's empty. A single-purpose Harness still defines one mode; multiple modes are how you give a session more than one behavior to switch between.

A mode supplies three things that change how the agent behaves:

- **Instructions**: layered on top of the backing agent's own instructions while the mode is active.
- **Tools**: either replacing or adding to the backing agent's tools (see [Mode tool overrides](#mode-tool-overrides)).
- **Model**: an optional `defaultModelId` to bootstrap model selection when the session enters the mode.

Because every mode shares the same backing agent, thread, and state, switching modes changes how the agent behaves without losing conversation context.

## Quickstart

Import the `Harness` class and create a new instance with your agent and modes:

```typescript
import { Harness } from '@mastra/core/harness'
import { myAgent } from './agents'

const harness = new Harness({
  id: 'multi-mode',
  agent: myAgent,
  modes: [
    {
      id: 'plan',
      name: 'Plan',
      metadata: { default: true },
      instructions: 'Reason about the task before making changes.',
    },
    { id: 'build', name: 'Build', instructions: 'Implement the approved plan.' },
  ],
})

await harness.init()
```

## Defining modes

Each mode requires an `id`. When a top-level `agent` is provided, modes layer instructions and tool overrides on the shared agent. Each mode can also specify a `defaultModelId` to bootstrap model selection:

```typescript
import { Harness } from '@mastra/core/harness'

const harness = new Harness({
  id: 'multi-mode',
  agent: myAgent,
  modes: [
    {
      id: 'plan',
      name: 'Plan',
      metadata: { default: true },
      defaultModelId: 'anthropic/claude-sonnet-4-6',
      instructions: 'Reason about the task before making changes.',
    },
    {
      id: 'build',
      name: 'Build',
      defaultModelId: 'anthropic/claude-sonnet-4-6',
      instructions: 'Implement the approved plan.',
    },
  ],
})
```

### Mode tool overrides

Modes support two strategies for tool configuration. Use `tools` to replace the backing agent's tools entirely, or `additionalTools` to layer extra tools on top:

```typescript
// Replace — agent sees only these tools in plan mode
const planMode = { id: 'plan', tools: { planTool } }

// Augment — agent keeps its own tools plus these
const buildMode = { id: 'build', additionalTools: { deployTool } }
```

You can't set both `tools` and `additionalTools` on the same mode.

### Mode transitions

A mode can declare a `transitionsTo` target. When the `submit_plan` built-in tool runs in that mode, the Harness transitions to the target mode on approval:

```typescript
const planMode = {
  id: 'plan',
  name: 'Plan',
  transitionsTo: 'build',
  instructions: 'Reason about the task and submit a plan.',
}
```

On plan approval, the Harness automatically switches to `build` mode. On rejection, the agent remains in `plan` mode to revise.

## Switching modes

Call `switchMode()` to change the active mode. The Harness aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events:

```typescript
await harness.switchMode({ modeId: 'build' })
```

## Querying modes

The Harness exposes the full mode catalog, while the Session tracks which mode is active. Use `harness.listModes()` to read every configured mode, `harness.session.mode.get()` for the active mode ID, and `harness.session.mode.resolve()` for the active mode's full definition:

```typescript
// List all configured modes
const modes = harness.listModes()

// Get the current mode ID
const modeId = harness.session.mode.get()

// Get the full mode object
const mode = harness.session.mode.resolve()
```

## Related

- [Harness overview](https://mastra.ai/docs/harness/overview)
- [Threads and state](https://mastra.ai/docs/harness/threads-and-state)
- [API reference](https://mastra.ai/reference/harness/harness-class)