Request Types

Request types for client-to-agent communication

Request types define the structure of requests sent from client to agent. All requests expect a corresponding response.

Initialization Requests

InitializeRequest

Sent by the client to establish connection and negotiate capabilities.

export type InitializeRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Capabilities supported by the client.
   */
  clientCapabilities?: ClientCapabilities;
  /**
   * Information about the Client name and version sent to the Agent.
   */
  clientInfo?: Implementation | null;
  /**
   * The latest protocol version supported by the client.
   */
  protocolVersion: ProtocolVersion;
};

See also: InitializeResponse

AuthenticateRequest

Specifies which authentication method to use.

export type AuthenticateRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the authentication method to use.
   * Must be one of the methods advertised in the initialize response.
   */
  methodId: string;
};

Session Management Requests

NewSessionRequest

Creates a new agent session.

export type NewSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The working directory for this session. Must be an absolute path.
   */
  cwd: string;
  /**
   * List of MCP (Model Context Protocol) servers the agent should connect to.
   */
  mcpServers: Array<McpServer>;
};

See also: NewSessionResponse

LoadSessionRequest

Loads an existing session. Only available if the agent supports the loadSession capability.

export type LoadSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The working directory for this session.
   */
  cwd: string;
  /**
   * List of MCP servers to connect to for this session.
   */
  mcpServers: Array<McpServer>;
  /**
   * The ID of the session to load.
   */
  sessionId: SessionId;
};

ListSessionsRequest

UNSTABLE - Lists existing sessions with optional filtering and pagination.

export type ListSessionsRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Opaque cursor token from a previous response's nextCursor field for cursor-based pagination
   */
  cursor?: string | null;
  /**
   * Filter sessions by working directory. Must be an absolute path.
   */
  cwd?: string | null;
};

ForkSessionRequest

UNSTABLE - Creates a new session based on the context of an existing one.

export type ForkSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The working directory for this session.
   */
  cwd: string;
  /**
   * List of MCP servers to connect to for this session.
   */
  mcpServers?: Array<McpServer>;
  /**
   * The ID of the session to fork.
   */
  sessionId: SessionId;
};

ResumeSessionRequest

UNSTABLE - Resumes a stopped session.

export type ResumeSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the session to resume.
   */
  sessionId: SessionId;
};

StopSessionRequest

UNSTABLE - Stops a running session.

export type StopSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the session to stop.
   */
  sessionId: SessionId;
};

Prompt Requests

PromptRequest

Sends a prompt to the agent for processing.

export type PromptRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Optional command to execute (e.g., 'create_plan', 'research_codebase').
   */
  command?: string | null;
  /**
   * Optional input parameter for the command if required.
   */
  commandInput?: string | null;
  /**
   * The prompt content blocks to send to the agent.
   */
  prompt: Array<Content>;
  /**
   * The ID of the session to send the prompt to.
   */
  sessionId: SessionId;
};

See also: PromptResponse, SessionUpdate

Configuration Requests

SetSessionModeRequest

Changes the session’s operating mode.

export type SetSessionModeRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the mode to switch to.
   */
  modeId: SessionModeId;
  /**
   * The ID of the session.
   */
  sessionId: SessionId;
};

SetSessionConfigOptionRequest

Updates a session configuration option.

export type SetSessionConfigOptionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the configuration option to set.
   */
  configId: SessionConfigId;
  /**
   * The ID of the session.
   */
  sessionId: SessionId;
  /**
   * The new value for the configuration option.
   */
  value: SessionConfigValueId;
};

SetSessionModelRequest

UNSTABLE - Changes the model used by the session.

export type SetSessionModelRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the model to use.
   */
  modelId: ModelId;
  /**
   * The ID of the session.
   */
  sessionId: SessionId;
};

File System Requests

These requests are sent from agent to client.

ReadTextFileRequest

Requests the client to read a text file.

export type ReadTextFileRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Absolute path to the file to read.
   */
  path: string;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};

WriteTextFileRequest

Requests the client to write a text file.

export type WriteTextFileRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The text content to write to the file.
   */
  content: string;
  /**
   * Absolute path to the file to write.
   */
  path: string;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};

RequestPermissionRequest

Requests the user to choose from a set of permission options.

export type RequestPermissionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Optional additional context about why permission is needed.
   */
  context?: string | null;
  /**
   * The permission options to present to the user.
   */
  options: Array<PermissionOption>;
  /**
   * Human-readable prompt to display to the user.
   */
  prompt: string;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};

Terminal Requests

These requests are sent from agent to client for terminal operations.

CreateTerminalRequest

Creates a new terminal and executes a command.

export type CreateTerminalRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Array of command arguments.
   */
  args?: Array<string>;
  /**
   * The command to execute.
   */
  command: string;
  /**
   * Working directory for the command (absolute path).
   */
  cwd?: string | null;
  /**
   * Environment variables for the command.
   */
  env?: Array<EnvVariable>;
  /**
   * Maximum number of output bytes to retain.
   */
  outputByteLimit?: number | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};

TerminalOutputRequest

Requests the current output from a terminal.

export type TerminalOutputRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal.
   */
  terminalId: string;
};

ReleaseTerminalRequest

Releases a terminal when no longer needed.

export type ReleaseTerminalRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal to release.
   */
  terminalId: string;
};

WaitForTerminalExitRequest

Waits for a terminal to exit.

export type WaitForTerminalExitRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal to wait for.
   */
  terminalId: string;
};

KillTerminalRequest

Kills a terminal without releasing it.

export type KillTerminalRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal to kill.
   */
  terminalId: string;
};