Skip to main content
You can now use Session Config Options. Dedicated session mode methods will be removed in a future version of the protocol. Until then, you can offer both to clients for backwards compatibility.
Agents can provide a set of modes they can operate in. Modes often affect the system prompts used, the availability of tools, and whether they request permission before running.

​
Initial state

During Session Setup the Agent MAY return a list of modes it can operate in and the currently active mode: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456",
    "modes": {
      "currentModeId": "ask",
      "availableModes": [
        {
          "id": "ask",
          "name": "Ask",
          "description": "Request permission before making any changes"
        },
        {
          "id": "architect",
          "name": "Architect",
          "description": "Design and plan software systems without implementation"
        },
        {
          "id": "code",
          "name": "Code",
          "description": "Write and modify code with full tool access"
        }
      ]
    }
  }
}
​
modes
SessionModeState
The current mode state for the session

​
SessionModeState

​
currentModeId
SessionModeId
required
The ID of the mode that is currently active
​
availableModes
SessionMode[]
required
The set of modes that the Agent can operate in

​
SessionMode

​
id
SessionModeId
required
Unique identifier for this mode
​
name
string
required
Human-readable name of the mode
​
description
string
Optional description providing more details about what this mode does

​
Setting the current mode

The current mode can be changed at any point during a session, whether the Agent is idle or generating a response.

​
From the Client

Typically, Clients display the available modes to the user and allow them to change the current one, which they can do by calling the session/set_mode method. 
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/set_mode",
  "params": {
    "sessionId": "sess_abc123def456",
    "modeId": "code"
  }
}
​
sessionId
SessionId
required
The ID of the session to set the mode for
​
modeId
SessionModeId
required
The ID of the mode to switch to. Must be one of the modes listed in availableModes

​
From the Agent

The Agent can also change its own mode and let the Client know by sending the current_mode_update session notification: 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "current_mode_update",
      "modeId": "code"
    }
  }
}

​
Exiting plan modes

A common case where an Agent might switch modes is from within a special “exit mode” tool that can be provided to the language model during plan/architect modes. The language model can call this tool when it determines it’s ready to start implementing a solution. This “switch mode” tool will usually request permission before running, which it can do just like any other tool: 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/request_permission",
  "params": {
    "sessionId": "sess_abc123def456",
    "toolCall": {
      "toolCallId": "call_switch_mode_001",
      "title": "Ready for implementation",
      "kind": "switch_mode",
      "status": "pending",
      "content": [
        {
          "type": "text",
          "text": "## Implementation Plan..."
        }
      ]
    },
    "options": [
      {
        "optionId": "code",
        "name": "Yes, and auto-accept all actions",
        "kind": "allow_always"
      },
      {
        "optionId": "ask",
        "name": "Yes, and manually accept actions",
        "kind": "allow_once"
      },
      {
        "optionId": "reject",
        "name": "No, stay in architect mode",
        "kind": "reject_once"
      }
    ]
  }
}
When an option is chosen, the tool runs, setting the mode and sending the current_mode_update notification mentioned above.

Learn more about permission requests