Creates a new ACP client connected to the given transport.

• #transport — the transport to use for communication.
• client_name — human-readable name of the client application.
• client_version — version string of the client.
• capabilities — client capabilities to advertise. Default: minimal.

Agent capabilities received during initialization.

Agent info received during initialization.

Authentication methods the agent supports.

Authenticates with the agent using the specified method ID.

This should be called after #initialize_connection if the agent reported authMethods in its initialize response.

Raises InvalidStateError if not in the Initialized state. Raises JsonRpcError on authentication failure.

Client capabilities to advertise during initialization.

Client capabilities to advertise during initialization.

Client info to send during initialization.

Client info to send during initialization.

Closes the client, stopping the dispatcher and closing the transport.

Returns true if the client has been closed.

Performs the ACP initialize handshake with the agent.

Sends the client's protocol version, capabilities, and info. Receives the agent's protocol version, capabilities, auth methods, and info. Validates protocol version compatibility.

Raises VersionMismatchError if the agent's protocol version is incompatible. Raises JsonRpcError if the agent returns an error.

The protocol version negotiated with the agent.

Callback invoked for agent-initiated method calls that the client must respond to (e.g., session/request_permission). The handler receives the method name and raw params, and must return the result as JSON::Any. If not set, agent requests receive an error.

Callback invoked for agent-initiated method calls that the client must respond to (e.g., session/request_permission). The handler receives the method name and raw params, and must return the result as JSON::Any. If not set, agent requests receive an error.

Handler for terminal/create — create a new terminal and execute a command. Set this when advertising the terminal capability.

Handler for terminal/create — create a new terminal and execute a command. Set this when advertising the terminal capability.

Callback invoked when the transport connection is lost.

Callback invoked when the transport connection is lost.

Handler for terminal/kill — kill terminal command without releasing. Set this when advertising the terminal capability.

Handler for terminal/kill — kill terminal command without releasing. Set this when advertising the terminal capability.

Callback invoked for any notification that is NOT session/update. Useful for handling custom or future notification types.

Callback invoked for any notification that is NOT session/update. Useful for handling custom or future notification types.

Handler for fs/read_text_file — read file contents from the editor. Set this when advertising fs.readTextFile capability.

Handler for fs/read_text_file — read file contents from the editor. Set this when advertising fs.readTextFile capability.

Handler for terminal/release — release a terminal. Set this when advertising the terminal capability.

Handler for terminal/release — release a terminal. Set this when advertising the terminal capability.

Handler for terminal/output — get terminal output and exit status. Set this when advertising the terminal capability.

Handler for terminal/output — get terminal output and exit status. Set this when advertising the terminal capability.

Callback invoked for every session/update notification. Set this to handle streaming agent responses, tool calls, etc.

Callback invoked for every session/update notification. Set this to handle streaming agent responses, tool calls, etc.

Handler for terminal/wait_for_exit — wait for terminal command to exit. Set this when advertising the terminal capability.

Handler for terminal/wait_for_exit — wait for terminal command to exit. Set this when advertising the terminal capability.

Handler for fs/write_text_file — write file contents. Set this when advertising fs.writeTextFile capability.

Handler for fs/write_text_file — write file contents. Set this when advertising fs.writeTextFile capability.

Default timeout for requests (in seconds). Nil means no timeout.

Default timeout for requests (in seconds). Nil means no timeout.

Responds to an agent-initiated request.

• id — the request ID from the agent's request.
• result — the result to send back.

Responds to an agent-initiated request with an error.

• id — the request ID from the agent's request.
• code — the JSON-RPC error code.
• error_message — human-readable error description.

Sends a JSON-RPC notification (no response expected).

• method — the notification method name.
• params — the notification parameters.

Sends a JSON-RPC request and waits for the response.

• method — the RPC method name.
• params — the request parameters (JSON::Serializable).
• timeout — optional timeout in seconds (nil = use default).

Returns the result field from the response as JSON::Any. Raises JsonRpcError if the response contains an error. Raises RequestTimeoutError if the request times out. Raises ConnectionClosedError if the transport is closed.

Returns true if a session is currently active.

Sends a session/cancel notification to abort the current operation in the active session.

• #session_id — optional session ID override.

This is a fire-and-forget notification (no response expected).

Config options available for the current session.

The active session ID, if any.

Loads (resumes) a previous session by ID.

• #session_id — the session ID to load.
• cwd — optional working directory override.

Raises InvalidStateError if not initialized. Raises JsonRpcError if the agent can't load the session.

Mode state for the current session.

Creates a new session with the agent.

• cwd — the absolute path to the working directory.
• mcp_servers — optional list of MCP servers to connect to.

Returns the session creation result with the session ID, modes, and config options. Stores the session ID for subsequent calls.

Raises InvalidStateError if not initialized.

Sends a prompt to the agent in the active session.

• prompt — an array of content blocks forming the prompt.
• #session_id — optional session ID override (uses active session if nil).

This is a blocking call that waits for the agent to finish processing the prompt. While waiting, session/update notifications will be dispatched to the #on_update callback.

Returns the prompt result with the stop reason.

Raises NoActiveSessionError if no session is active.

Convenience: sends a simple text prompt.

• text — the text content to send as a prompt.
• #session_id — optional session ID override.

Changes a configuration option for the active session.

• config_id — the ID of the configuration option to change.
• value — the new value to set.
• #session_id — optional session ID override.

Returns the full set of configuration options and their current values. See: https://agentclientprotocol.com/protocol/session-config-options#from-the-client

Changes the mode for the active session.

• mode_id — the mode ID to switch to.
• #session_id — optional session ID override.

The current client state.

The transport used for communication with the agent.