Skip to main content
Author(s): anna239

​
Elevator pitch

What are you proposing to change?
Add a typed terminal authentication method so a Client can run the configured Agent program interactively for login, then reconnect to the Agent after the login flow succeeds.

​
Status quo

How do things work today and what problems does this cause? Why would we change things?
Agents use several authentication flows. Some can handle login over ACP, while others require users to interact with the Agent’s terminal UI. The baseline agent authentication method does not tell a Client that it must launch an interactive program, so users may need to leave the Client and complete setup manually.

​
What we propose to do about it

What are you proposing to improve the situation?
Add a terminal authentication method. A supporting Client launches the same configured Agent program in an interactive terminal, adding arguments and environment variables supplied by the Agent. After the terminal flow succeeds, the Client reconnects and reinitializes the ACP Agent. Terminal authentication is an out-of-band process. The Client does not pass a terminal method to v1 authenticate or v2 auth/login.

​
Shiny future

How will things play out once this feature exists?
Users can complete an Agent’s interactive login flow without leaving their Client. Agents describe how to enter that flow without knowing the Client-specific path or command used to launch them.

​
Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

​
Terminal authentication method

The terminal discriminator identifies a terminal authentication method. The descriptor includes:
  • args (optional, default []): additional arguments for the configured Agent program.
  • env (optional, default empty): additional environment variables for the terminal process. Descriptor values override same-named variables in the base launch configuration. In v2, every env entry MUST have a unique name.
The identifier and env wire shapes differ between protocol versions.
The descriptor cannot specify a command. The Client constructs the terminal invocation from the same configured Agent program and base launch configuration used for the ACP connection, then appends args and applies env. This keeps the descriptor independent of Client-specific installation paths and prevents the Agent from selecting an unrelated program.

​
Client capability

Clients opt in because terminal authentication requires Client-side process and terminal support.
A Client advertises this capability only when it can reproduce the configured Agent invocation in an interactive terminal. In particular, a Client connected to an Agent over a remote transport must omit the capability unless it can launch that same Agent program in the Agent’s execution environment. An Agent may advertise a terminal authentication method only when the Client advertised the corresponding capability.

​
Login flow

  1. The Client initializes the ACP connection and receives a terminal authentication method.
  2. When the user selects it, the Client launches a separate interactive process using the configured Agent program and base launch configuration, plus the descriptor’s args and env.
  3. The Client presents the terminal to the user and waits for the process to exit. Exit status zero signals success; a non-zero status, termination without an exit status, or cancellation signals failure.
  4. On success, the Client reconnects and reinitializes the ACP Agent, then retries the operation that required authentication.
Agents SHOULD provide arguments that enter a login-only flow and exit after the flow completes. ACP does not define an output pattern or other in-band success signal. Clients may recognize implementation-specific signals as an extension, but Agents cannot require that behavior for interoperability. The Client MUST NOT pass the terminal method to v1 authenticate or v2 auth/login: the interactive terminal process is not the ACP connection. In v2, advertising any authentication method requires the Agent to implement both auth/login and auth/logout, preserving the baseline authentication surface rule. The standard agent type uses auth/login; terminal does not, so Clients never pass a terminal method ID to that endpoint.

​
Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

​
What alternative approaches did you consider?

The proposal originally included an env_var method that asked the Client to collect credentials and restart the Agent with new environment variables. That model assumes the Client owns the Agent process and does not generalize to remote transports. Agents using this former experimental method should replace it with agent or terminal authentication. Authentication setup could also be included in an Agent’s registry declaration, making it static rather than negotiated. See the Registry RFD. Structured credential collection could instead use an elicitation flow. That keeps user input inside the Agent’s protocol-driven authentication logic rather than giving the Client special knowledge of environment variables.

​
Revision history

The original authentication RFD also discussed elicitation. That material was removed and moved to a separate proposal.
  • 2026-07-27: Removed the remaining unstable env_var types and made the Rust SDK decode legacy descriptors as agent in both protocol versions.
  • 2026-07-24: Moved terminal authentication to Preview, defined it as an out-of-band launch and reconnect flow, removed env_var from v2, and retained the unstable v1 variant for compatibility.
  • 2026-03-09: Removed auth_methods from the Error type.
  • 2026-03-03: Changed env_var from a single varName to a structured vars array of AuthEnvVar objects and simplified the field name from varName to name.
  • 2026-02-27: Updated the proposal to reflect the implementation.
  • 2026-01-14: Incorporated Core Maintainer feedback.